Documentation
¶
Overview ¶
Package schematic implements the pre-worker that analyses bead scope before Smith starts. The schematic is drawn before the smith starts forging.
Schematic can:
- Emit a focused implementation plan appended to Smith's prompt
- Decompose large beads into sub-beads via bd, blocking the parent
- Skip entirely for small/simple beads
- Request human clarification for ambiguous beads and block work until clarified
Index ¶
Constants ¶
const LabelDecomposed = "forge-decomposed"
LabelDecomposed is the label the daemon attaches to a decomposed parent bead when it must stay open (has dependents). Schematic detects this on re-dispatch and returns ActionAlreadyDecomposed so no smith is spawned.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Action ¶
type Action string
Action describes what the Schematic decided to do.
const ( // ActionPlan means the bead is implementable as-is; a focused plan was // produced to guide Smith. ActionPlan Action = "plan" // ActionDecompose means the bead was too large or multi-part and has been // split into sub-beads. The parent bead should be blocked. ActionDecompose Action = "decompose" // ActionSkip means the bead was simple enough that no schematic was needed. ActionSkip Action = "skip" // ActionClarify means the bead requires human clarification and should not // be worked on yet. ActionClarify Action = "clarify" // ActionCrucible means the bead has children that need to be orchestrated // together on a feature branch (crucible mode). ActionCrucible Action = "crucible" // ActionAlreadyDecomposed means the bead was previously decomposed into // children and kept open for dependents. Now that it is re-dispatched there // is no work left — the children were the work. ActionAlreadyDecomposed Action = "already_decomposed" )
type ChildBead ¶ added in v0.3.0
ChildBead is a lightweight summary of a child bead for the crucible check prompt.
type Config ¶
type Config struct {
// Enabled controls whether Schematic runs at all. Defaults to true when
// the global setting is enabled.
Enabled bool
// WordThreshold is the minimum word count in the bead description to
// trigger automatic schematic analysis. Beads below this are skipped
// unless they have the decompose tag. Default: 100.
WordThreshold int
// MaxTurns limits the AI session length. Default: 5. Kept low because
// the schematic should emit its JSON verdict immediately without tool use.
// Note: --max-turns is best-effort and only honored by providers that
// support the flag (e.g. Claude CLI). Gemini and GitHub Copilot CLI
// adapters drop this flag, so enforcement is provider-dependent.
MaxTurns int
// ExtraFlags are additional CLI flags forwarded to the Claude session
// (e.g. model selection, auth tokens). Mirrors pipeline.Params.ExtraFlags.
ExtraFlags []string
// OnSpawn is an optional callback invoked immediately after the AI
// subprocess is started, before waiting for it to finish. It receives the
// process PID and the path to the session log file. Use this to update
// monitoring records (e.g. the worker DB row) so that live-tail and
// progress tracking work during the schematic phase.
OnSpawn func(pid int, logPath string)
}
Config controls Schematic behavior.
func DefaultConfig ¶
func DefaultConfig() Config
DefaultConfig returns sensible defaults for Schematic.
type CrucibleCheckResult ¶ added in v0.3.0
type CrucibleCheckResult struct {
// NeedsCrucible is true when the children should be orchestrated on a
// feature branch rather than dispatched individually.
NeedsCrucible bool
// Reason explains the decision.
Reason string
// Duration is how long the check took.
Duration time.Duration
// CostUSD is the estimated cost of the AI session.
CostUSD float64
// Quota holds rate-limit quota data from the AI session, if available.
Quota *provider.Quota
}
CrucibleCheckResult captures whether a bead with children needs crucible orchestration or can be dispatched as a standalone bead.
func RunCrucibleCheck ¶ added in v0.3.0
func RunCrucibleCheck(ctx context.Context, cfg Config, parent poller.Bead, children []ChildBead, anvilPath string, pv provider.Provider) *CrucibleCheckResult
RunCrucibleCheck determines whether a bead with children needs crucible orchestration (sequential work on a feature branch) or can be dispatched as a standalone bead with children handled individually.
This is a lightweight schematic call that only inspects the relationship between parent and children — it does not produce implementation plans.
type Result ¶
type Result struct {
// Action is what the Schematic decided.
Action Action
// Plan is a focused implementation plan for Smith (only when Action=ActionPlan).
Plan string
// SubBeads is the list of sub-beads created (only when Action=ActionDecompose).
SubBeads []SubBead
// Reason is a human-readable explanation of the decision.
Reason string
// Duration is how long the analysis took.
Duration time.Duration
// CostUSD is the estimated cost of the AI session.
CostUSD float64
// Quota holds rate-limit quota data from the AI session, if available.
Quota *provider.Quota
// Error is set if the schematic failed.
Error error
}
Result captures the outcome of a Schematic analysis.
Source Files