complex-feature-dev

name	complex-feature-dev
version	1.1.0
description	Full-cycle 7-phase feature development workflow with persistent file-based planning (task_plan.md, findings.md, progress.md) as macro memory.
user-invocable	true
allowed-tools	["Read","Write","Edit","Bash","Glob","Grep"]
hooks	{"PreToolUse":[{"matcher":"Write|Edit|Bash|Read|Glob|Grep","hooks":[{"type":"command","command":"HOME_DIR=\"$(cd ~ 2>/dev/null && pwd)\"\nSCRIPT_DIR=\"$(ls -dt \"${HOME_DIR}/.claude/plugins/cache/complex-dev-skills/complex-feature-dev\"/*/scripts 2>/dev/null | head -1)\"\nif [ -z \"${SCRIPT_DIR}\" ]; then\n CAND=\"${HOME_DIR}/.claude/plugins/marketplaces/complex-dev-skills/claude/plugins/complex-feature-dev/scripts\"\n if [ -d \"${CAND}\" ]; then\n SCRIPT_DIR=\"${CAND}\"\n fi\nfi\nif [ -z \"${SCRIPT_DIR}\" ]; then\n echo \"[complex-feature-dev] ERROR: cannot locate plugin scripts directory.\" >&2\n echo \"[complex-feature-dev] Expected either:\" >&2\n echo \" - ~/.claude/plugins/cache/complex-dev-skills/complex-feature-dev/<version>/scripts\" >&2\n echo \" - ~/.claude/plugins/marketplaces/complex-dev-skills/claude/plugins/complex-feature-dev/scripts\" >&2\n exit 0\nfi\nIS_WINDOWS=0\nif [ \"${OS-}\" = \"Windows_NT\" ]; then\n IS_WINDOWS=1\nelse\n UNAME_S=\"$(uname -s 2>/dev/null || echo '')\"\n case \"$UNAME_S\" in\n CYGWIN*|MINGW*|MSYS*) IS_WINDOWS=1 ;;\n esac\nfi\n\nROOT=\"$(git rev-parse --show-toplevel 2>/dev/null || pwd)\"\nPLAN_FILE=\"${ROOT}/task_plan.md\"\nFINDINGS_FILE=\"${ROOT}/findings.md\"\nPROGRESS_FILE=\"${ROOT}/progress.md\"\n\nprint_plan_head() {\n local file=\"$1\"\n if command -v head >/dev/null 2>&1; then\n head -30 \"$file\"\n elif command -v sed >/dev/null 2>&1; then\n sed -n '1,30p' \"$file\"\n elif command -v pwsh >/dev/null 2>&1; then\n pwsh -NoProfile -Command \"Get-Content -Path \\\"$file\\\" -TotalCount 30\"\n elif command -v powershell >/dev/null 2>&1; then\n powershell -NoProfile -Command \"Get-Content -Path \\\"$file\\\" -TotalCount 30\"\n else\n cat \"$file\"\n fi\n}\n\ninit_plan_files() {\n # Prefer bash init script first (works on Windows Git Bash/MSYS/WSL too).\n if command -v bash >/dev/null 2>&1; then\n bash \"$SCRIPT_DIR/init-session.sh\" >/dev/null 2>&1 && return 0\n fi\n\n if [ -x \"$SCRIPT_DIR/init-session.sh\" ]; then\n \"$SCRIPT_DIR/init-session.sh\" >/dev/null 2>&1 && return 0\n fi\n\n # If bash isn't available, try PowerShell (Windows).\n if [ \"$IS_WINDOWS\" -eq 1 ]; then\n if command -v powershell >/dev/null 2>&1; then\n powershell -NoProfile -ExecutionPolicy Bypass -File \"$SCRIPT_DIR/init-session.ps1\" >/dev/null 2>&1 && return 0\n fi\n if command -v pwsh >/dev/null 2>&1; then\n pwsh -NoProfile -ExecutionPolicy Bypass -File \"$SCRIPT_DIR/init-session.ps1\" >/dev/null 2>&1 && return 0\n fi\n fi\n\n return 1\n}\n\n\nif [ -f \"$PLAN_FILE\" ] && [ -f \"$FINDINGS_FILE\" ] && [ -f \"$PROGRESS_FILE\" ]; then\n print_plan_head \"$PLAN_FILE\"\nelse\n echo \"[complex-feature-dev] Planning files not found (task_plan.md/findings.md/progress.md). Initializing...\"\n init_plan_files || true\n\n ROOT=\"$(git rev-parse --show-toplevel 2>/dev/null || pwd)\"\n PLAN_FILE=\"${ROOT}/task_plan.md\"\n FINDINGS_FILE=\"${ROOT}/findings.md\"\n PROGRESS_FILE=\"${ROOT}/progress.md\"\n\n if [ -f \"$PLAN_FILE\" ] && [ -f \"$FINDINGS_FILE\" ] && [ -f \"$PROGRESS_FILE\" ]; then\n echo \"[complex-feature-dev] Initialized planning files.\"\n print_plan_head \"$PLAN_FILE\"\n else\n echo \"[complex-feature-dev] Init failed. Run manually:\"\n echo \" bash \\\"$SCRIPT_DIR/init-session.sh\\\"\"\n echo \" pwsh -ExecutionPolicy Bypass -File \\\"$SCRIPT_DIR/init-session.ps1\\\"\"\n fi\nfi\n"}]}],"PostToolUse":[{"matcher":"Write|Edit","hooks":[{"type":"command","command":"echo '[complex-feature-dev] Update planning files with brief macro notes (overall status / current micro-phase / key decisions).'"}]}],"Stop":[{"hooks":[{"type":"command","command":"HOME_DIR=\"$(cd ~ 2>/dev/null && pwd)\"\nSCRIPT_DIR=\"$(ls -dt \"${HOME_DIR}/.claude/plugins/cache/complex-dev-skills/complex-feature-dev\"/*/scripts 2>/dev/null | head -1)\"\nif [ -z \"${SCRIPT_DIR}\" ]; then\n CAND=\"${HOME_DIR}/.claude/plugins/marketplaces/complex-dev-skills/claude/plugins/complex-feature-dev/scripts\"\n if [ -d \"${CAND}\" ]; then\n SCRIPT_DIR=\"${CAND}\"\n fi\nfi\nif [ -z \"${SCRIPT_DIR}\" ]; then\n echo \"[complex-feature-dev] ERROR: cannot locate plugin scripts directory.\" >&2\n echo \"[complex-feature-dev] Expected either:\" >&2\n echo \" - ~/.claude/plugins/cache/complex-dev-skills/complex-feature-dev/<version>/scripts\" >&2\n echo \" - ~/.claude/plugins/marketplaces/complex-dev-skills/claude/plugins/complex-feature-dev/scripts\" >&2\n exit 0\nfi\nIS_WINDOWS=0\nif [ \"${OS-}\" = \"Windows_NT\" ]; then\n IS_WINDOWS=1\nelse\n UNAME_S=\"$(uname -s 2>/dev/null || echo '')\"\n case \"$UNAME_S\" in\n CYGWIN*|MINGW*|MSYS*) IS_WINDOWS=1 ;;\n esac\nfi\n\nif [ \"$IS_WINDOWS\" -eq 1 ]; then\n if command -v pwsh >/dev/null 2>&1; then\n pwsh -NoProfile -ExecutionPolicy Bypass -File \"$SCRIPT_DIR/check-complete.ps1\"\n exit $?\n fi\n if command -v powershell >/dev/null 2>&1; then\n powershell -NoProfile -ExecutionPolicy Bypass -File \"$SCRIPT_DIR/check-complete.ps1\"\n exit $?\n fi\nfi\n\nif command -v bash >/dev/null 2>&1; then\n bash \"$SCRIPT_DIR/check-complete.sh\"\n exit $?\nfi\n\nif [ -x \"$SCRIPT_DIR/check-complete.sh\" ]; then\n \"$SCRIPT_DIR/check-complete.sh\"\n exit $?\nfi\n\necho \"ERROR: Unable to run completion check (no bash/pwsh found)\" >&2\nexit 1\n"}]}]}
metadata	{"short-description":"Full-cycle feature development"}

Feature Development (Complex Tasks)

A codebase-agnostic workflow for building new features safely:

• 7 phases (discovery → exploration → questions → architecture → implement → review → summary)
• Persistent planning files for long tasks (macro memory: goal, status, next actions, and durable decisions)

Inputs

Minimum input:

• A 1–2 sentence feature description (what to build + who/why).

Helpful extras (optional):

• Acceptance criteria / examples
• Related files or modules
• Docs / tickets / prototypes (if inaccessible, ask user to paste key parts)

Non-Negotiable Rules

1. Never skip Phase 3 (Clarifying Questions). If anything is underspecified, ask and wait.
2. Never start Phase 5 (Implementation) without explicit approval.
3. Use the planning files as persistent macro memory. Keep them concise and durable.
4. Read before decide. Before major decisions, re-read task_plan.md.
5. Log errors briefly + don’t repeat failures. If an action fails, change the approach.

Quick Start (Planning Files)

This workflow requires these files in the repo root:

• task_plan.md
• findings.md
• progress.md
• CLAUDE.md (agent instructions; created by init if missing)

To initialize them, run:

• /complex-feature-dev:init (recommended)

Or via terminal:

• macOS/Linux (or Windows Git Bash): bash "$(ls -dt ~/.claude/plugins/cache/complex-dev-skills/complex-feature-dev/*/scripts/init-session.sh 2>/dev/null | head -1)"
• Windows PowerShell: pwsh -ExecutionPolicy Bypass -File "~/.claude/plugins/cache/complex-dev-skills/complex-feature-dev/<version>/scripts/init-session.ps1"

Project Guidelines

• Follow AGENTS.md / CLAUDE.md / CONTRIBUTING.md / README.md if present.
• Prefer matching existing code patterns over introducing new abstractions.
• Write important conventions you discover into findings.md.

---

Phase 1: Discovery

Goal: Make the request concrete and testable.

• If planning files are missing, run the initializer script via the Bash tool and do not proceed until the files exist.
• Restate the request as acceptance criteria; confirm scope and non-goals.
• Capture constraints (compatibility, performance, time, rollout).
• Write brief confirmed requirements + acceptance criteria to findings.md.

Phase 2: Codebase Exploration

Goal: Identify the correct integration points and existing patterns.

Do 2–3 independent exploration passes:

• Pass A: find similar features and trace end-to-end
• Pass B: map architecture boundaries and extension points
• Pass C: identify testing/build/lint/config/observability conventions

For each pass:

• record key files/patterns (prefer file:line; keep it macro) in findings.md.

Also:

• locate and follow AGENTS.md instructions (if present).

Phase 3: Clarifying Questions (Hard Stop)

Goal: Resolve all ambiguity before architecture and implementation.

Ask questions grouped by:

• behavior definition (inputs/outputs/state)
• edge cases (empty values, duplicates, concurrency, ordering, permissions)
• error handling (timeouts, retries, idempotency, rollback)
• integrations (APIs, data models, config, feature flags)
• backward compatibility & migration
• performance assumptions
• observability
• testing & acceptance plan

Wait for answers (or propose defaults and get explicit confirmation). Record final answers in findings.md.

Phase 4: Architecture Design

Goal: Present 2–3 viable approaches and let the user choose.

Provide at least:

• Minimal changes (reuse, low risk)
• Pragmatic balance (cleaner boundaries)
• Optional clean architecture (more refactor, higher long-term clarity)

For each approach include:

• files to create/modify
• key abstractions + data flow
• trade-offs (risk/time/testability/maintainability)

Write the chosen approach + rationale (brief) to findings.md and task_plan.md.

Phase 5: Implementation (Requires Approval)

Goal: Implement the chosen approach.

• Implement in small verifiable increments.
• Follow existing conventions; avoid unrelated refactors.
• Log key actions/files/tests in progress.md (brief).
• Log errors in task_plan.md (and brief resolution in progress.md).

Phase 6: Quality Review

Goal: Catch high-impact issues before delivery.

Default review scope:

• Prefer reviewing git diff (or specified files).

Focus areas:

• correctness, security/permissions, error handling, observability, conventions, simplicity

Confidence filtering:

• score issues 0–100
• report only issues ≥ 80 confidence, with concrete fixes (file:line)

Phase 7: Summary

Goal: Deliver a clean handoff.

• Summarize what was built, key decisions, and files modified.
• Provide verification steps (commands/endpoints/UI paths).
• Call out risks and suggested next steps.