getting-started

1. Understand what forgectl is and the one mental model that makes everything else obvious.
2. Have the binary installed and verified.
3. Know which entry point fits their situation (brand-new product, existing codebase, or "I already have specs/plans").
4. Have .forgectl/config bootstrapped and tuned to a sane starting point.
5. Have an initialized session and know how to drive the state machine to completion.
6. Know which phase skill to invoke for the work in front of them.

Meet the user where they are. If they already have the binary and a session, skip straight to driving the workflow. Do not lecture through steps they have done. </task>

<the_one_mental_model>

Forgectl is a compiler for specs. Specs are the source code; production code is the build artifact.

• A normal compiler takes .go/.c and emits assembly. Forgectl takes Markdown specs and, through AI agents, emits production code.
• The specs are the single source of truth. You change behavior by changing a spec, then "recompiling" — not by editing code directly and hoping the spec catches up.

Forgectl itself writes no specs, no plans, and no code. It is a state machine driver. It tracks where you are, tells you the one thing to do next, evaluates the work with sub-agents, and refuses to let you skip steps. The actual writing is done by an AI agent (you, or the user's agent) following forgectl's instructions.

That gives the two-actor model that everything else follows from:

The golden rule: you never decide what to work on next. Every forgectl status and every forgectl advance prints an Action: line. Read it and do exactly that. When in doubt, run forgectl status. This single habit removes most of the friction newcomers hit.

</the_one_mental_model>

<the_pipeline>

Work flows through sequential phases, each a state machine with its own AI evaluation loop. A phase only ends when its eval loop passes (or hits its round limit). Then a PHASE_SHIFT — a hard stop to refresh context — moves to the next phase.

   (new product)                                        (existing codebase)
   planning docs                                         existing source code
        │                                                        │
        ▼                                                        ▼
   PHASE 1: specifying ──► generate_planning_queue ──► ...   reverse_engineering
   (write specs)            (build plan-queue.json)              (code → specs)
                                   │                                  │
                                   └──────────────┬───────────────────┘
                                                  ▼
                              PHASE: planning  (one plan.json per domain)
                                                  │
                                   plan kind routes the next phase:
                                   kind:"code" ──► implementing
                                   kind:"ui"   ──► ui_implementing
                                                  ▼
                              PHASE: implementing / ui_implementing
                              (production code; ui adds QA + e2e loops)

Each phase has a skill that drives it. Onboarding's job is to get you to the right one:

There is also frontend_specs for authoring the three tiers of frontend specs, and planner for shaping the upstream planning documents that feed specifying.

The full lifecycle with every state is in docs/diagrams/00-full-lifecycle.txt.

</the_pipeline>

<domains_and_specs>

Domains are one of the most important concepts in forgectl. Misunderstanding them is the single most common cause of init failures and broken spec queues.

A domain is a named grouping that maps to a directory in your project. It is the unit forgectl uses to scope specs, batch work, run cross-reference consistency checks, and produce implementation plans. Every spec queue entry, every plan queue entry, and every mid-session add-queue-item call references a domain by name.

What you must know before writing your first queue file

1. Declare domains in .forgectl/config before init. Config is locked at init time — mid-session edits do nothing for the current session.

   [[domains]]
   name = "optimizer"
   path = "optimizer"
   
   [[domains]]
   name = "portal"
   path = "portal"

2. Specs live at <path>/specs/. A spec with "domain": "optimizer" must have its "file" under optimizer/specs/ — any mismatch causes init to reject.
3. Every spec queue entry needs a "domain" field. Every plan queue entry does too. Forgectl uses this to batch, route, and cross-reference correctly.
4. Hard constraints (init rejects on violation):
   • No domain path may be a prefix of another (domains/users and domains/users/employees are rejected).
   • Domain names must be unique within the config.
5. Batches never mix domains. A specifying.batch = 3 setting means up to three specs processed per cycle, always within one domain. After the last batch for a domain, forgectl runs a per-domain CROSS_REFERENCE pass over all specs in that domain before moving to the next one.
6. Domains are optional for small projects. Without a [[domains]] section, forgectl derives groupings from spec file paths. For any multi-subsystem product, declare them explicitly.

Full reference: references/domains-and-specs.md — read this before authoring your first spec-queue.json or plan-queue.json.

</domains_and_specs>

<getting_started>

<step_1> Install and verify the binary

make install-global      # builds and installs to ~/.local/bin/forgectl
forgectl --version       # confirm it works

(Requires Go. make build builds the binary locally without installing.)

Optionally install the Claude Code plugin so the skills and commands are available everywhere:

/plugin marketplace add jackstine/forgectl
/plugin install forgectl@forgectl

</step_1>

<step_2> Bootstrap the config (zero-config is fine to start)

From your project root:

forgectl init      # no flags: creates .forgectl/ and a default .forgectl/config, then exits

This is scaffold-only mode — idempotent and safe to run anytime. It never overwrites an existing config. You do not have to do this separately: a real init --from ... also bootstraps the config first if it is missing. Running it bare just lets you see and edit the config before starting a session.

Open .forgectl/config and skim it. You can run forgectl entirely on defaults; tune later. See references/config-cheatsheet.md for the handful of knobs that actually matter on day one. </step_2>

<step_3> Choose your entry point — see <choosing_your_entry_point> below, then initialize the matching phase. The general form:

forgectl init --phase <phase> --from <input-file>

init reads .forgectl/config, validates your input file, and creates the state file at .forgectl/state/forgectl-state.json in state ORIENT. If validation fails it prints exactly what is wrong and the full valid schema — fix the file and rerun. </step_3>

<step_4> Drive the state machine to DONE — see <driving_the_workflow>. Then hand off to the phase skill (the table above) to do the actual work of that phase. </step_4>

</getting_started>

<choosing_your_entry_point>

A new user's first question is always "where do I start?" It depends entirely on what you already have. You can begin at any phase — forgectl lets you skip earlier phases when their output already exists.

Most newcomers building something new start at specifying and let the pipeline carry them forward. Most newcomers adopting forgectl on an existing product start at reverse_engineering to capture current behavior as specs first, then continue from planning.

The first input file. The hardest part of the very first run is producing the input file for your chosen phase (a spec-queue.json, etc.). Do not hand-author it blind — the phase skill knows how to build it. For specifying, the specs skill's search step generates the spec queue from your planning docs. If you have no planning docs yet, use the planner skill first to shape them.

Notes:

• generate_planning_queue cannot be initialized directly. It only exists as a transition out of a completed specifying phase. If you authored specs outside forgectl, skip it and build a plan-queue.json by hand, then init --phase planning.
• ui_implementing has required config. init --phase ui_implementing validates that ui_implementing.app.launch_command, ui_implementing.app.url, ui_implementing.e2e.test_command, and ui_implementing.e2e.test_dir are all non-empty. Fill those in .forgectl/config first or init will reject with the missing keys named.

</choosing_your_entry_point>

<driving_the_workflow>

Once a session exists, the loop is the same in every phase:

1. forgectl status — shows the current phase, state, progress, and the Action: line. This is your "where am I / what now" command. Run it whenever you are unsure.
2. Do what the Action: line says — write the spec, implement the item, spawn the evaluator, etc. The per-phase skill explains the work for each state.
3. forgectl advance — transition to the next state. Some states need flags; the status output and the CLI map tell you which.

The flags you will actually use:

The evaluation loop is forgectl's quality engine and where the two-actor model shows up. At EVALUATE, you (the engineer) spawn a sub-agent. The sub-agent runs forgectl eval to get the full review context, reads the work, writes a report, and returns a verdict. You then advance --verdict ... --eval-report .... FAIL loops back to refine; PASS accepts once minimum rounds are met. eval.min_rounds / eval.max_rounds in config bound the loop so it never runs forever. (In ui_implementing, sub-agents also forgectl handoff <file> to register QA reports, step lists, and e2e reports back to the scaffold for review.)

Guided mode. With general.user_guided = true (the default), forgectl pauses at human checkpoints (e.g. SELECT, REVIEW, ORIENT) so you can discuss scope before it proceeds. Toggle per-call with --guided / --no-guided on any advance. New users should leave it on — it keeps you in the loop while you learn the rhythm.

The full command reference is docs/diagrams/04-cli-commands.txt. For a concrete end-to-end first run, see references/first-session-walkthrough.md.

</driving_the_workflow>

<what_trips_up_new_users>

The most common sources of "forgectl is hard":

• Trying to decide what to work on. Don't. The scaffold decides; you read the Action: line. If you feel lost, run forgectl status.
• Editing code to change behavior. Change the spec, then recompile. Code is the artifact, not the source of truth.
• "State file already exists." Init refuses to clobber an in-progress session. To start fresh, delete .forgectl/state/forgectl-state.json. To continue, just run forgectl status — you don't re-init.
• Hand-writing the first input file and getting schema errors. Let the phase skill generate it. When validation fails, forgectl prints the offending field and the full valid schema — read both.
• Expecting init to overwrite config. It never touches an existing .forgectl/config. Edit the file directly to change settings.
• Wrong --phase for what you have. Match the phase to the input you actually possess (see the entry-point table). You can start anywhere.
• ui_implementing rejected at init. Its app.* and e2e.* config keys are required and validated non-empty. Fill them first.
• Config edits not taking effect mid-session. Config is read once and locked into the state file at init. Changing .forgectl/config afterward does nothing for the current session — it applies to the next init.
• Forgetting which phase you're even in. forgectl status always tells you the phase, state, and next action.

</what_trips_up_new_users>

<reference_map>

• Domains and specs (read first) — references/domains-and-specs.md — what domains are, how to declare them, spec path rules, queue file requirements, batching and cross-reference behavior
• Config, deeply — references/config-cheatsheet.md, docs/default-config.toml, docs/configurations.md
• First run, concretely — references/first-session-walkthrough.md
• Diagrams — docs/diagrams/: 00-full-lifecycle, 04-cli-commands, 06-state-machine-complete, 07-evaluation-loop, 10-ui-implementing-phase
• Schemas — docs/schemas/: forge-state, plan-json, plan-queue
• Phase skills — planner, specs, generate_planning_queue, implementation_planning, implementation, ui_implementation, reverse_engineering, frontend_specs
• Specs (the contract forgectl implements) — forgectl/specs/: session-init, phase-transitions, config-scaffolding

</reference_map>

<IMPORTANT_INFO> 99999. Forgectl is the driver, not the author. It writes nothing — it tells you what to write next. Run forgectl status whenever you are unsure, and follow the Action: line in every output. 999999. Specs are the source of truth. Change behavior by changing specs and recompiling, never by editing code directly. 9999999. You can start at any phase. Match --phase to the input you already have; let the phase skill generate that input rather than hand-authoring it blind. 99999999. Config is locked into the state file at init. Edit .forgectl/config before init; mid-session edits do nothing for the current session. 999999999. Onboarding orients and routes. Once the user has an initialized session, hand them to the phase skill in the pipeline table to do the real work. </IMPORTANT_INFO> </content> </invoke>