implementation_planning

You are tasked to generate an Implementation Plan using the forgectl scaffold to manage the workflow. This is a FRESH context window — you have no memory of previous sessions. You are continuing work on a long-running autonomous development task.

You have been provided a workspace within a domain. </role>

The plan is a structured JSON manifest that sequences work items, references specs and notes for detail, and defines acceptance criteria through structured test cases.

The implementation plan should answer: "What is needed to fully implement THESE specs?" </task>

<step_0> Entry Mode — Ask the User

Before starting, ask the user which entry mode they want:

1. generate_planning_queue — Auto-generate the plan queue from completed specs. This is only available as a transition from a completed specifying phase — it cannot be initialized directly. It requires forgectl-state.json with completed specifying data. If no specifying session was run (e.g., specs were committed outside forgectl), use planning instead.
2. planning — Start planning directly with a pre-built plan queue. Use this when you already have a plan-queue.json file (manually constructed or from a previous session), or when specs were created outside of a forgectl specifying session. You build the queue yourself and pass it via --from.

Ask: "Would you like to start with generate_planning_queue (auto-generate from completed specs) or planning (provide your own plan queue)?"

• If generate_planning_queue: proceed to step_0a.
• If planning: proceed to step_0b. </step_0>

<step_0a> Generate Planning Queue — Auto-Generate from Completed Specs

This path uses forgectl's generate_planning_queue phase to auto-generate the plan queue from completed specs. That phase has its own session and skill — run it first, then return here at planning ORIENT.

See the dedicated skill: skills/generate_planning_queue/SKILL.md (background: ../shared/generate-planning-queue.md).

In brief, the phase has 3 states: ORIENT (forgectl groups completed specs by domain and writes <state_dir>/plan-queue.json) → REFINE (review/reorder/edit the queue) → PHASE_SHIFT (validate and transition to planning). Advance through each:

# Advance through each state; at the final PHASE_SHIFT you may override the queue:
forgectl advance
forgectl advance --from <custom-queue.json>   # optional override at PHASE_SHIFT

After the phase shift, planning begins at ORIENT. Proceed to step_1. </step_0a>

<step_0b> Init — Start the Forgectl Planning Session Directly

Prepare a plan queue JSON file listing every implementation plan to produce in this session.

See: ../shared/creating-plan-queue.md and ../shared/plan-queue-format.md

forgectl init --phase planning --from <plan-queue.json>

All batch sizes, round limits, and guided settings are configured in .forgectl/config (TOML).

This creates forgectl-state.json and sets the state to ORIENT.

Run forgectl status to see the full session overview. </step_0b>

<step_1> Loop — Follow the Planning State Machine

For each plan in the queue, follow the forgectl state machine:

1a. ORIENT — Review plan metadata and understand the domain. 1b. STUDY_SPECS — Study every spec listed in the plan's specs field. Read full spec files and review git diffs for recent spec commits. 1c. STUDY_CODE — Explore the codebase using sub-agents (3 agents) within the plan's code_search_roots. Partition agents by concern (e.g. agent 1: infrastructure/config/entry points, agent 2: domain models/state, agent 3: transport/IO/tests). Identify existing implementations, TODOs, placeholders, and patterns. 1d. STUDY_PACKAGES — Study the project's technical stack: package manifests, library docs, CLAUDE.md references. 1e. REVIEW — Checkpoint before drafting. Read the plan format reference BEFORE drafting: references/plan-format.json. If guided, discuss with the user. 1f. DRAFT — Generate the implementation plan as plan.json + notes/ at the target path. Follow the schema in references/plan-format.json exactly. Forgectl validates automatically on advance. See Schema Gotchas below. 1g. EVALUATE — Use forgectl eval to get evaluation context. Spawn an Opus sub-agent to assess the plan against all 11 dimensions. Record the verdict with forgectl advance --verdict PASS|FAIL --eval-report <path>. 1h. REFINE — If evaluation failed or min rounds not met, spawn a sub-agent to update the plan and notes. Advance to re-evaluate. 1i. ACCEPT — Plan finalized. When enable_commits is true in .forgectl/config, advance with forgectl advance --message <commit msg> to auto-commit. When enable_commits is false, just forgectl advance.

Use forgectl status at any point to see current state and what action is needed.

See: references/planning-navigation.md

The plan output format is defined in references/plan-format.json. </step_1>

<step_2> Phase Transition

After acceptance, forgectl transitions to either ORIENT (if more plans remain in the queue) or DONE (if all plans are complete). From DONE, advancing triggers PHASE_SHIFT (planning → implementing). The phase shift validates plan.json, adds tracking fields (passes: "pending", rounds: 0) to every item, and writes the updated plan back to disk.

forgectl advance

</step_2>

<contextual_information>

Scope Constraint

• The spec files listed in the plan queue's specs field are your PRIMARY focus.
• Do NOT create implementation items for features not required by the listed specs.

Studying the Codebase

• Cross-reference existing source code — do NOT assume functionality is missing; confirm with code search first.
• Use sub-agents during STUDY_CODE to explore code_search_roots.
• Study src/lib/* for common library components already implemented. Skip if no files exist.
• Search for TODOs, minimal implementations, placeholders, skipped/flaky tests, and inconsistent patterns.

Plan Output Structure

Plans are written to the path specified in the plan queue's file field:

<domain>/.forge_workspace/implementation_plan/
├── plan.json          # The implementation plan manifest
└── notes/             # Reference notes per package
    ├── <package>.md
    └── ...

Format: references/plan-format.json

Schema Gotchas

These are common validation failures. Read references/plan-format.json for the full schema.

1. refs must be objects, not strings. Each entry needs {"id": "...", "path": "..."}. Plain strings like "specs/foo.md" will fail parsing.
2. All paths are relative to the project root (the directory containing .forgectl/). If plan.json is at api/.forge_workspace/implementation_plan/plan.json, then spec paths look like api/specs/foo.md and notes paths look like api/.forge_workspace/implementation_plan/notes/bar.md.
3. No #anchor fragments in refs paths. refs: ["notes/foo.md#section"] will fail — forgectl runs os.Stat() on the raw string. Use refs: ["notes/foo.md"] instead. (specs paths allow #anchors since they are display-only.)
4. specs is a string array, not a single string. Use "specs": ["spec1.md", "spec2.md"]. The field is specs (plural). Display-only, #anchor fragments are OK. There is also refs (plural, string array) for notes file paths validated on disk.
5. context only has domain and module. Extra fields like go_version or binary are silently ignored but add no value.
6. tests must be an array, never null. Use [] for items with no tests. null fails validation.
7. depends_on must be an array, never null. Use [] for items with no dependencies.

Evaluation

The planning evaluator assesses 11 dimensions against the referenced specs:

1. Behavior
2. Error Handling
3. Rejection
4. Interface
5. Configuration
6. Observability
7. Integration Points
8. Invariants
9. Edge Cases
10. Testing Criteria
11. Dependencies & Format

Full evaluator instructions: forgectl/evaluators/plan-eval.md (embedded in the binary, output by forgectl eval automatically)

Eval reports are written to: <domain>/.forge_workspace/implementation_plan/evals/round-N.md

Evaluation Sub-Agent Context

When spawning the evaluation sub-agent, provide clear context about what is NEW work vs ALREADY IMPLEMENTED. Specs often describe full system behavior, but the plan may only cover a subset (e.g. logging migration across existing modules). The evaluator must know the boundary to avoid false negatives on dimensions like Behavior or Testing Criteria for already-implemented functionality.

</contextual_information>

<IMPORTANT_INFO>

999 Plan only. Do NOT implement anything.

999 Do NOT assume that functionality is not implemented — confirm with code search first.

9999 Implementation plan covers ALL specs listed in the plan queue's specs field.

9999 The implementation plan should answer: "What is needed to fully implement THESE specs?"

</IMPORTANT_INFO>