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

Never skip Phase 3 (Clarifying Questions). If anything is underspecified, ask and wait.
Never start Phase 5 (Implementation) without explicit approval.
Use the planning files as persistent macro memory. Keep them concise and durable.
Read before decide. Before major decisions, re-read task_plan.md.
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.