feature-plan

name	feature-plan
description	Generate EXECUTION_PLAN.md and scoped AGENTS.md files for a feature. Use after /feature-technical-spec to create the task breakdown.
argument-hint	<feature-name>
allowed-tools	Bash, Read, Write, Edit, AskUserQuestion, Glob, Grep

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.

Verification (Automatic)

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 "Next Step" until verification passes or user explicitly chooses to proceed with noted issues.

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.

Cross-Model Review (Automatic)

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 unavailable: Skip silently and proceed to Next Step.

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

When verification is complete, inform the user:

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

Verification: PASSED | PASSED WITH NOTES | NEEDS REVIEW
Cross-Model Review: PASSED | PASSED WITH NOTES | SKIPPED

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