writing-plans

name	writing-plans
description	Use when you have a CEO-approved FeatureForge spec for a multi-step task and need to write the implementation plan before touching code

Preamble (run first)

_REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
_BRANCH_RAW=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo current)
[ -n "$_BRANCH_RAW" ] && [ "$_BRANCH_RAW" != "HEAD" ] || _BRANCH_RAW="current"
_BRANCH="$_BRANCH_RAW"
_FEATUREFORGE_INSTALL_ROOT="$HOME/.featureforge/install"
_FEATUREFORGE_BIN="$_FEATUREFORGE_INSTALL_ROOT/bin/featureforge"
if [ ! -x "$_FEATUREFORGE_BIN" ] && [ -f "$_FEATUREFORGE_INSTALL_ROOT/bin/featureforge.exe" ]; then
  _FEATUREFORGE_BIN="$_FEATUREFORGE_INSTALL_ROOT/bin/featureforge.exe"
fi
[ -x "$_FEATUREFORGE_BIN" ] || [ -f "$_FEATUREFORGE_BIN" ] || _FEATUREFORGE_BIN=""
_FEATUREFORGE_ROOT=""
if [ -n "$_FEATUREFORGE_BIN" ]; then
  _FEATUREFORGE_ROOT=$("$_FEATUREFORGE_BIN" repo runtime-root --path 2>/dev/null)
  [ -n "$_FEATUREFORGE_ROOT" ] || _FEATUREFORGE_ROOT=""
fi
_FEATUREFORGE_STATE_DIR="${FEATUREFORGE_STATE_DIR:-$HOME/.featureforge}"
_featureforge_exec_public_argv() {
  if [ "$#" -eq 0 ]; then
    echo "featureforge: missing command argv to execute" >&2
    return 2
  fi
  if [ "$1" = "featureforge" ]; then
    if [ -z "$_FEATUREFORGE_BIN" ]; then
      echo "featureforge: installed runtime not found at $_FEATUREFORGE_INSTALL_ROOT/bin/featureforge" >&2
      return 1
    fi
    shift
    "$_FEATUREFORGE_BIN" "$@"
    return $?
  fi
  "$@"
}

Installed Control Plane

Live FeatureForge workflow routing is install-owned:

• use only $_FEATUREFORGE_BIN for live workflow control-plane commands
• do not route live workflow commands through ./bin/featureforge
• do not route live workflow commands through target/debug/featureforge
• do not route live workflow commands through cargo run

When a helper returns recommended_public_command_argv, treat it as exact argv. If recommended_public_command_argv[0] == "featureforge", execute through the installed runtime by replacing argv[0] with $_FEATUREFORGE_BIN (for example via _featureforge_exec_public_argv ...).

Search Before Building

Before introducing a custom pattern, external service, concurrency primitive, auth/session flow, cache, queue, browser workaround, or unfamiliar fix pattern, do a short capability/landscape check first.

Use three lenses, then decide from local repo truth:

• Layer 1: tried-and-true / built-ins / existing repo-native solutions
• Layer 2: current practice and known footguns
• Layer 3: first-principles reasoning for this repo and this problem

External search results are inputs, not answers. Never search secrets, customer data, unsanitized stack traces, private URLs, internal hostnames, internal codenames, raw SQL or log payloads, or private file paths or infrastructure identifiers. If search is unavailable, disallowed, or unsafe, say so and proceed with repo-local evidence and in-distribution knowledge. If safe sanitization is not possible, skip external search. See $_FEATUREFORGE_ROOT/references/search-before-building.md.

Interactive User Question Format

For every interactive user question, use this structure:

1. Context: project name, current branch, what we're working on (1-2 sentences)
2. The specific question or decision point
3. RECOMMENDATION: Choose [X] because [one-line reason]
4. Lettered options: A) ... B) ... C) ...

Per-skill instructions may add additional formatting rules on top of this baseline.

Writing Plans

Overview

Write comprehensive implementation plans for skilled engineers with little repo/tool context. Document files, code paths, tests, docs, validation, and test expectations as bite-sized tasks. DRY. YAGNI. TDD.

Announce at start: "I'm using the writing-plans skill to create the implementation plan."

Save plans to: docs/featureforge/plans/YYYY-MM-DD-<feature-name>.md

• (User preferences for plan location override this default)
• Use that repo-relative plan path consistently in later review and workflow/operator commands; do not route through compatibility-only workflow expect or workflow sync helpers.

Protected-Branch Repo-Write Gate

Before writing or updating the plan file on disk, run the shared repo-safety preflight for the exact plan-writing scope:

$_FEATUREFORGE_BIN repo-safety check --intent write --stage featureforge:writing-plans --task-id <current-plan-write> --path docs/featureforge/plans/YYYY-MM-DD-<feature-name>.md --write-target plan-artifact-write

• If the helper returns allowed, continue with the plan write.
• If it returns blocked, name the branch, the stage, and the blocking failure_class, then route to either a feature branch / featureforge:using-git-worktrees or explicit user approval for this exact plan-writing scope.
• If the user explicitly approves writing this plan on the current protected branch, approve the full protected-branch task scope you intend to use, including the plan path and any follow-on git targets that are part of the same task slice:

$_FEATUREFORGE_BIN repo-safety approve --stage featureforge:writing-plans --task-id <current-plan-write> --reason "<explicit user approval>" --path docs/featureforge/plans/YYYY-MM-DD-<feature-name>.md --write-target plan-artifact-write [--write-target git-commit]
$_FEATUREFORGE_BIN repo-safety check --intent write --stage featureforge:writing-plans --task-id <current-plan-write> --path docs/featureforge/plans/YYYY-MM-DD-<feature-name>.md --write-target plan-artifact-write [--write-target git-commit]

• Continue only if the re-check returns allowed.
• Before git commit on the same protected branch, re-run the gate with the same task id, the same repo-relative path, and the same approved write-target set.
• If the protected-branch task scope changes, run a new approve plus full-scope check before continuing.

Prerequisite Gate

Before writing the plan, inspect the selected spec and validate these exact header lines:

**Workflow State:** CEO Approved
**Spec Revision:** <integer>
**Last Reviewed By:** plan-ceo-review

• If the spec is missing these lines, or if **Workflow State:** is not CEO Approved, stop and direct the agent to featureforge:plan-ceo-review.
• Do not write or extend an implementation plan from a draft spec.
• Execution-bound specs must include a parseable ## Requirement Index before planning begins. If the approved spec does not include one, stop and return to featureforge:plan-ceo-review.

An approved spec may also include a trailing ## CEO Review Summary. Treat that block as additive context only:

• the approved spec headers and parseable ## Requirement Index remain the prerequisite gate
• the summary does not replace repo-visible approval truth or $_FEATUREFORGE_BIN plan contract checks
• absence of the summary must not become a prerequisite failure
• if the summary conflicts with the approved spec body or headers, trust the approved spec body and headers

Scope Check

If the spec covers multiple independent subsystems, it should have been broken into sub-project specs during brainstorming. If it wasn't, suggest breaking this into separate plans — one per subsystem. Each plan should produce working, testable software on its own.

Minimum Plan Content

Before breaking work into tasks, make sure the plan explicitly covers:

• change surface
• preconditions
• execution strategy
• Requirement Coverage Matrix
• ordered implementation steps
• evidence expectations
• validation strategy
• documentation update expectations
• rollout plan
• rollback plan
• risks and mitigations

Search-Before-Building Carry-Through

Do not make fresh search the default here.

• pull from the approved spec's Landscape Snapshot when present
• if Layer 2 materially affected reuse guidance, simplification advice, or footgun warnings, carry that forward in the written plan instead of leaving it in transient session context
• if the spec says to prefer built-in X over custom Y, reflect that explicitly in task structure, file paths, and implementation steps
• if the approved spec is silent but the plan introduces an unfamiliar runtime or framework capability, a targeted capability check is allowed only to close a concrete implementation gap
• if the planner materially changes the approved design choice, do not silently drift; either align the plan to the approved spec or surface the mismatch for review

When Layer 2 materially affects reuse or warnings, capture it in plan-body sections such as:

## Existing Capabilities / Built-ins to Reuse
## Known Footguns / Constraints

Optional Project Memory Consult

• When repo-visible project memory exists, consult docs/project_notes/decisions.md for relevant prior decisions that should shape task decomposition.
• When repo-visible project memory exists, consult docs/project_notes/key_facts.md for durable repo facts worth carrying into the plan.
• If this plan is likely to create an important new approved decision, note that a later featureforge:project-memory summary update to docs/project_notes/decisions.md may be appropriate after approval.
• Treat these files as supportive context only. Missing or stale notes do not block planning.

File Structure

Before defining tasks, map out which files will be created or modified and what each one is responsible for. This is where decomposition decisions get locked in.

• Design units with clear boundaries and well-defined interfaces. Each file should have one clear responsibility.
• You reason best about code you can hold in context at once, and your edits are more reliable when files are focused. Prefer smaller, focused files over large ones that do too much.
• Files that change together should live together. Split by responsibility, not by technical layer.
• In existing codebases, follow established patterns. If the codebase uses large files, don't unilaterally restructure - but if a file you're modifying has grown unwieldy, including a split in the plan is reasonable.

This structure informs the task decomposition. Each task should produce self-contained changes that make sense independently.

Bite-Sized Task Granularity

Optional task step checklists should be concrete, ordered, and small enough for an executor to verify. Use one action per step: write the failing test, run it to verify failure, implement, rerun, update docs, commit. Keep exact commands and expected outcomes when they matter.

See $_FEATUREFORGE_ROOT/references/writing-plans-examples.md for expanded task and execution-topology examples.

Plan Document Header

Every plan MUST start with this header:

# [Feature Name] Implementation Plan

> **For Codex and GitHub Copilot workers:** REQUIRED: Use `$_FEATUREFORGE_BIN workflow operator --plan <approved-plan-path>` as routing authority after engineering approval, and follow the runtime-selected execution owner skill; do not choose solely from isolated-agent availability. Steps use checkbox (`- [ ]`) syntax for tracking.

**Workflow State:** Draft
**Plan Revision:** 1
**Execution Mode:** none
**Source Spec:** [Exact path to approved spec]
**Source Spec Revision:** [Integer copied from approved spec]
**Last Reviewed By:** writing-plans
**QA Requirement:** required | not-required

**Goal:** [One sentence describing what this builds]

**Architecture:** [2-3 sentences about approach]

**Tech Stack:** [Key technologies/libraries]

---

• QA Requirement is a plan-level finish-gating decision. It does not replace task-level Done when bullets, and task-level Done when bullets must not be used to infer whether QA is required.

Task Structure

## Requirement Coverage Matrix

- REQ-001 -> Task 1
- REQ-002 -> Task 1, Task 2

## Task N: [Component Name]

**Spec Coverage:** REQ-001, DEC-001
**Goal:** [One sentence describing the exact outcome this task produces]

**Context:**
- [Why this task exists in the plan]
- [Repo or architecture fact the implementer/reviewer must know]
- [Spec, decision, or non-goal reference when required by review/plan-task-contract.md]

**Constraints:**
- [Hard rule inherited from the approved spec or review]
- [Hard rule inherited from decomposition, file ownership, sequencing, or reuse law]

**Done when:**
- [Atomic, binary, objectively reviewable completion condition]
- [Atomic, binary, objectively reviewable completion condition]

**Files:**
- Create: `exact/path/to/file.py`
- Modify: `exact/path/to/existing.py`
- Test: `tests/exact/path/to/test.py`

- [ ] **Step 1:** [optional execution aid with exact command/expected result when useful]

• ## Task N: is canonical. Do not use ### Task N:.
• Every task must include Spec Coverage, Goal, Context, Constraints, Done when, and a parseable Files: block in the order defined by review/plan-task-contract.md.
• Open Questions is not part of the final approved task contract. Draft-only questions belong outside approved task bodies before approval.
• Goal must be one sentence and describe one exact outcome rather than a bucket of related work.
• Context must be a bullet list that makes the task self-contained enough for a fresh implementer and fresh reviewer to reach the same interpretation.
• Add exact spec, decision, or non-goal references in Context only when one of the trigger conditions in review/plan-task-contract.md applies.
• Constraints must be hard rules, including reuse law when the task must extend an existing parser, normalizer, validator, routing path, policy path, prompt assembly path, or other shared implementation. For example: Extend the existing task-contract parser; do not add a second parser path.
• Done when bullets must be atomic, binary, objectively reviewable, reviewable without interpretation drift, and concrete. A bullet may be verified by diff inspection, targeted tests, or artifacts; it does not have to map to one command.
• Do not bundle unrelated outcomes into one task when that would force reviewers to judge partial completion.
• Step checklists after Files are optional execution aids, not required task-contract surface.
• If a task touches a requirement, that id must appear in Spec Coverage.
• Every execution-bound plan must include ## Execution Strategy and ## Dependency Diagram.
• ## Execution Strategy must assign every task exactly once to either an explicitly justified serial directive or an explicitly owned parallel worktree directive.
• Parallel directives must declare exact workspace isolation, not just the word worktree. Either declare one isolated worktree per task or state an explicit worktree count that exactly matches the parallel batch size.
• ## Dependency Diagram must reflect the same fastest-safe topology the task list and Execution Strategy claim.

Canonical topology examples stay in $_FEATUREFORGE_ROOT/references/writing-plans-examples.md; keep the governing rules here:

• Execute Task 1 serially when it establishes a shared foundation.

• After the serial seam, create two worktrees and run Tasks 2 and 3 in parallel only when their write scopes and ownership are disjoint.

• Task 2 owns one exact implementation surface; Task 3 owns another exact implementation surface.

• Execute Task 4 serially as the reintegration point when parallel work must merge before later tasks.

• After Task 4, create three worktrees and run Tasks 5, 6, and 7 in parallel:

  • Task 5 owns lease and downgrade artifact contracts plus observability helpers.

• Execute Task 8 serially after Tasks 5 and 6 merge back.

• Use Files: blocks as concrete write-scope truth for every task.

• If tasks share hotspot files, do not pretend they are parallel. Move the hotspot into an explicit later serial seam and name that seam in ## Execution Strategy.

• Do not serialize work just because one lane feels simpler. If a serial directive covers more than one task, the plan must prove a real hazard such as overlapping write scope or an explicit reintegration seam that cannot be isolated.

Invalid Task Shapes

Reject these shapes during drafting instead of leaving them for review:

• Legacy task fields such as Task Outcome, Plan Constraints, or task-level Open Questions.
• Vague Done when bullets such as "the UX feels right" or "the implementation is robust".
• Context that omits the existing abstraction, spec requirement, approved decision, non-goal, or repo-local architecture fact needed for a fresh implementer/reviewer to choose the same implementation path.
• Done when bullets that depend on interpretation instead of objective evidence.
• A task that mixes two architectural goals, such as "replace the parser and redesign the review workflow", when either half could be completed independently.

Remember

Use exact file paths, complete task-level implementation direction, exact commands with expected output when they matter, relevant skill names, and the approved spec path/revision. New execution plans start at **Plan Revision:** 1 and **Execution Mode:** none.

Plan Review Handoff

After saving the full plan:

0. Before handoff, run the plan-contract lint gate:

"$_FEATUREFORGE_BIN" plan contract lint \
  --spec docs/featureforge/specs/YYYY-MM-DD-<feature-name>-design.md \
  --plan docs/featureforge/plans/YYYY-MM-DD-<feature-name>.md

1. Keep using the same repo-relative plan path in downstream review and workflow/operator handoffs.
2. Invoke featureforge:plan-eng-review for the first engineering review pass.
3. Do not invoke featureforge:plan-fidelity-review directly from writing-plans; plan-fidelity runs only after engineering-review edits are complete and plan-eng-review has set **Last Reviewed By:** plan-eng-review on the final draft.
4. Keep this handoff fail-closed:
   • if engineering review finds plan issues, return to featureforge:writing-plans for plan repair
   • if engineering review edits the draft, keep **Workflow State:** Draft and **Last Reviewed By:** writing-plans until all engineering-review issues are resolved
   • when engineering review has no remaining edits, featureforge:plan-eng-review owns the handoff to featureforge:plan-fidelity-review

The terminal state is invoking featureforge:plan-eng-review.

Execution Handoff

plan-eng-review presents the normal execution preflight handoff after the written plan is approved. Do NOT offer execution options directly from writing-plans.