benjaminshoemaker/feature-plan

Generate the execution plan and scoped agent instructions for the feature $1.

Workflow

Copy this checklist and track progress:

Feature Plan Progress:
- [ ] Directory guard
- [ ] Handle arguments (feature name)
- [ ] Check prerequisites (FEATURE_SPEC.md + FEATURE_TECHNICAL_SPEC.md)
- [ ] Existing file guard (prevent overwrite)
- [ ] Generate EXECUTION_PLAN.md and feature-local AGENTS.md
- [ ] Verify execution skills installed
- [ ] Codex CLI detection and skill install
- [ ] Run spec-verification
- [ ] Run criteria audit
- [ ] Cross-model review (if Codex available)

Directory Guard

1. If .toolkit-marker exists in the current working directory → STOP: "You're in the toolkit repo. Feature skills run from your project directory. Run: cd ~/Projects/your-project && /feature-plan $1"

2. Check .claude/toolkit-version.json exists in the current working directory (confirms /setup was run). If missing → STOP: "Toolkit not installed. Run /setup from the toolkit first."

3. Check AGENTS.md exists in the current working directory (confirms project root). If missing → STOP: "Run this from your project root (where AGENTS.md lives)."

Arguments

• $1 = feature name (e.g., analytics, dark-mode)
• If $1 is empty, ask the user for the feature name
• PROJECT_ROOT = current working directory
• FEATURE_DIR = PROJECT_ROOT/features/$1

Prerequisites

• Check that FEATURE_DIR/FEATURE_SPEC.md exists. If not: "FEATURE_SPEC.md not found at features/$1/. Run /feature-spec $1 first."
• Check that FEATURE_DIR/FEATURE_TECHNICAL_SPEC.md exists. If not: "FEATURE_TECHNICAL_SPEC.md not found at features/$1/. Run /feature-technical-spec $1 first."
• Check that PROJECT_ROOT/AGENTS.md exists. If not: "AGENTS.md not found. Feature development requires an existing AGENTS.md."

Existing File Guard (Prevent Overwrite)

Before generating anything, check whether any output files already exist:

• FEATURE_DIR/EXECUTION_PLAN.md

• FEATURE_DIR/AGENTS.md

• If neither exists: continue normally.

• If one or both exist: STOP and ask the user what to do for the existing file(s):

  1. Backup then overwrite (recommended): for each existing file, read it and write it to {path}.bak.YYYYMMDD-HHMMSS, then write the new document(s) to the original path(s)
  2. Overwrite: replace the existing file(s) with the new document(s)
  3. Abort: do not write anything; suggest they rename/move the existing file(s) first

Process

Read .claude/skills/feature-plan/PROMPT.md and follow its instructions exactly:

1. Read FEATURE_DIR/FEATURE_SPEC.md and FEATURE_DIR/FEATURE_TECHNICAL_SPEC.md as inputs
2. Read existing PROJECT_ROOT/AGENTS.md to understand current conventions
3. Generate EXECUTION_PLAN.md with phases, steps, and tasks for the feature
4. Generate FEATURE_DIR/AGENTS.md with feature-scoped workflow guidance

Output

Write both documents to the feature directory:

• FEATURE_DIR/EXECUTION_PLAN.md
• FEATURE_DIR/AGENTS.md

Create Scoped CLAUDE.md

If FEATURE_DIR/CLAUDE.md does not exist, create it with:

@AGENTS.md

If it already exists, do not overwrite it.

Verify Execution Skills

After writing the documents, verify the execution skills are available so /fresh-start, /phase-start, etc. work from the feature directory.

Check if .claude/skills/fresh-start/SKILL.md exists in PROJECT_ROOT:

• If it exists: good — execution skills are installed
• If it does not exist: STOP and tell the user: "Execution skills are missing. Run /setup from the toolkit to install them."

Codex CLI Detection (Always Runs)

Check if OpenAI Codex CLI is installed:

command -v codex >/dev/null 2>&1

If Codex is NOT detected: skip silently.

If Codex IS detected:

1. Check for new skills by comparing toolkit skills to installed skills:

   # Get installed skills
   INSTALLED_SKILLS=$(ls ~/.codex/skills/ 2>/dev/null | grep -v '^\.')
   

2. If no installed skills exist (first time), use AskUserQuestion:

   Question: "Codex CLI detected. Install toolkit skills for Codex?"
   Options:
     - "Yes, install" — Install skills via symlink (auto-updates with toolkit)
     - "No, skip" — Don't install Codex skills
   

3. If user selects install, resolve toolkit location from .claude/toolkit-version.json:

   TOOLKIT_PATH=$(jq -r '.toolkit_location' .claude/toolkit-version.json)
   "$TOOLKIT_PATH/scripts/install-codex-skill-pack.sh" --method symlink
   

4. Report installation result.

Lean Mode (--lean)

When --lean is passed:

• Skip all post-generation gates. Do not run /verify-spec, /codex-consult, or /criteria-audit. Report each as LEAN_SKIP in the output.
• All other steps (Q&A, document generation, deferred capture) run normally.

Post-Generation Gates (MANDATORY unless --lean)

These gates MUST execute before you produce the "Next Step" output. The output template requires results from each gate. Reporting SKIPPED without --lean is a skill violation — go back and run the gate.

Gate 1: Spec Verification

After writing EXECUTION_PLAN.md, run the spec-verification workflow:

1. Read .claude/skills/spec-verification/SKILL.md for the verification process
2. Verify context preservation: Check that all key items from FEATURE_TECHNICAL_SPEC.md and FEATURE_SPEC.md appear as tasks or acceptance criteria
3. Run quality checks for untestable criteria, missing dependencies, vague language, regression coverage
4. Present any CRITICAL issues to the user with resolution options
5. Apply fixes based on user choices
6. Re-verify until clean or max iterations reached

IMPORTANT: Do not proceed to Gate 2 until verification passes or user explicitly chooses to proceed with noted issues.

Gate 2: Criteria Audit

Run /criteria-audit FEATURE_DIR to validate verification metadata in EXECUTION_PLAN.md. This passes the feature directory so criteria-audit reads features/$1/EXECUTION_PLAN.md instead of looking in the project root.

• If FAIL: stop and ask the user to resolve missing metadata before proceeding.
• If WARN: report and continue.

Gate 3: Cross-Model Review

After verification passes, run cross-model review if Codex CLI is available:

1. Check if Codex CLI is installed: codex --version
2. If available, run /codex-consult with upstream context
3. Present any findings to the user before proceeding

Consultation invocation:

/codex-consult --upstream features/$1/FEATURE_TECHNICAL_SPEC.md --research "execution planning, task breakdown" features/$1/EXECUTION_PLAN.md

If Codex finds issues:

• Show critical issues and recommendations
• Ask user: "Address findings before proceeding?" (Yes/No)
• If Yes: Apply suggested fixes
• If No: Continue with noted issues

If Codex CLI is not installed or not authenticated: Report UNAVAILABLE (not SKIPPED — the distinction matters).

Error Handling

| Situation | Action | |-----------|--------| | FEATURE_SPEC.md or FEATURE_TECHNICAL_SPEC.md missing | STOP with message directing user to run /feature-spec or /feature-technical-spec first | | EXECUTION_PLAN.md generation produces empty or malformed output | Re-read input specs, retry generation once; if still empty, report error and ask user to check spec completeness | | /criteria-audit returns FAIL | STOP and present failing criteria to user; do not proceed until metadata is fixed | | Codex CLI invocation errors or times out | Log the error, mark cross-model review as SKIPPED, and continue to Next Step | | Backup file write fails (disk full or permissions) | Report the write failure, do NOT overwrite the original file, and suggest user free disk space or fix permissions |

Next Step

Pre-condition: All gates above have completed, or --lean was explicitly passed. If you have not run them, STOP and run them now. Reporting SKIPPED without --lean is a skill violation.

When complete, inform the user:

EXECUTION_PLAN.md and AGENTS.md created and verified at features/$1/

Verification: PASSED | PASSED WITH NOTES | NEEDS REVIEW | LEAN_SKIP
Criteria Audit: PASSED | WARN | LEAN_SKIP
Cross-Model Review: PASSED | PASSED WITH NOTES | UNAVAILABLE | LEAN_SKIP

Next steps:
1. cd features/$1
2. /fresh-start
3. /configure-verification
4. /phase-prep 1
5. /phase-start 1