implementation

The implementation plan (plan.json) is a required input for this phase. It is not generated during implementation — it is produced during the planning phase (see: skills/implementation_planning/).

Before starting, confirm that {domain}/.forge_workspace/implementation_plan/plan.json exists along with its companion notes/ directory. If these do not exist, the planning phase must be completed first. </prerequisites>

1. session_start
2. state_loop

<session_start> Session Start

You need to have a domain — the user MUST supply this to you. All paths below are relative to {domain}.

1. Read {domain}/CLAUDE.md for project-specific operational notes.
2. Run forgectl status to check for an active session.
3. If no state file exists — initialize:

   forgectl init \
     --from {domain}/.forge_workspace/implementation_plan/plan.json \
     --phase implementing

   All batch sizes, round limits, and guided settings are configured in .forgectl/config (TOML) and locked into the state file at init time.
4. If a state file exists — read the output to understand the current state.
5. Enter the state loop.

See: references/forgectl-workflow.md for init flags and options. </session_start>

<state_loop> State Loop

Forgectl drives a state machine. Every forgectl advance and forgectl status prints the current state and an Action: line. Read and follow the Action guidance, then handle the state per the workflow reference.

After each advance, forgectl prints the new state. Handle it and repeat until DONE.

The states in the implementing phase are: ORIENT → IMPLEMENT → EVALUATE → ORIENT → ... → DONE, with a COMMIT state in between only when enable_commits: false (when enable_commits: true, the batch-terminal commit happens inline at the terminal EVALUATE transition and COMMIT never appears).

For detailed instructions on what to do in each state (ORIENT, IMPLEMENT round 1, IMPLEMENT round 2+, EVALUATE, COMMIT, DONE), including required flags and exact commands, see:

See: references/forgectl-workflow.md </state_loop>

<contextual_information>

Domain

The domain is the root directory for the project being implemented. The user supplies this. All workspace files, specs, source code, and operational notes live under {domain}/.

Forgectl Scaffold

The forgectl scaffold is a Go CLI at forgectl/ that manages the implementation lifecycle — sequencing work through dependency-ordered layers and batches, tracking evaluation rounds, and managing state transitions. The scaffold is the single source of truth for what to implement next. Do NOT choose items yourself. Every output includes an Action: line. Follow it. See: references/forgectl-workflow.md

Implementation Plan

The plan lives at {domain}/.forge_workspace/implementation_plan/plan.json with notes in {domain}/.forge_workspace/implementation_plan/notes/. Read the relevant notes file before implementing an item — it contains specific guidance on approach, data structures, and library usage.

The plan is produced by the planning phase (skills/implementation_planning/). It is a prerequisite for this phase and must exist before initialization.

Implementation Log

Log progress in {domain}/.forge_workspace/implementation/IMPLEMENTATION_LOG.md after each batch is committed. See: references/implementation_log_format.md

CLAUDE.md

{domain}/CLAUDE.md is for operational notes only. Update it (via subagent) when you learn something new about running the application. Keep it brief — progress belongs in the implementation log.

Subagents

See: references/subagent-usage.md

</contextual_information>

<IMPORTANT_INFO>

99999. Forgectl is the driver. Run forgectl status when unsure what to do. Read and follow the Action: line in every output.
100000. Study the item's refs (notes files) before implementing — they contain specific guidance on approach, data structures, and library usage.
100001. Implement functionality completely. Placeholders and stubs waste effort and time redoing the same work.
100002. Single sources of truth, no migrations/adapters. If tests unrelated to your work fail, resolve them as part of the increment.
100003. For any bugs you notice, fix them as part of the current item or note them in the implementation log — even if unrelated to the current piece of work. 9999999999. Keep {domain}/CLAUDE.md operational only — progress notes belong in the implementation log. A bloated CLAUDE.md pollutes every future loop's context. 99999999999. You may add extra logging if required to debug issues. 999999999999. When authoring documentation, capture the why — tests and implementation importance.

</IMPORTANT_INFO>