Create Implementation Plan

0. Input

<feature_description> #$ARGUMENTS </feature_description>

If empty, ask: "What would you like to plan? Describe the feature, bug fix, or improvement."

Brainstorm check: Search docs/brainstorms/ for a matching brainstorm. If found, read it fully — it contains architecture decisions, integration impact, and resolved questions that drive this plan. Also read any related existing plans in docs/plans/.

Preset support (optional): If input contains preset:<name> (e.g. preset:nestjs-api), load presets/presets.json and adapt planning emphasis/review focus to that preset. If missing/invalid, fall back to general. Use preset qualityProfile guidance:

• strict: maximize coverage and risk controls.
• balanced: normal rigor.
• fast: smallest safe plan for hotfix scope.

1. Research

Round 1 — Always (execute all research agents):

Execute the following agents by reading and applying their instructions:

1. repo-research-analyst (../../agents/research/repo-research-analyst.md)

   • Purpose: Maps file paths, services, DTOs, entities, rules, existing enums, current migration state for the affected area
   • Input: Feature description, affected modules/areas
   • Output: Concrete file paths, existing patterns, migration state

2. learnings-researcher (../../agents/research/learnings-researcher.md)

   • Purpose: Surfaces relevant solutions from docs/solutions/
   • Input: Feature description, technical domain
   • Output: Applicable patterns, previous solutions, best practices

3. spec-flow-analyzer (../../agents/workflow/spec-flow-analyzer.md)

   • Purpose: Finds missing flows, edge cases, error states; produces Given/When/Then acceptance criteria
   • Input: Feature requirements
   • Output: Acceptance criteria and tasks to add

Execution: Read all three agent files and execute their instructions with the provided context. You can read multiple files in parallel.

Round 2 — Conditional (execute applicable agents):

Execute the following agents when applicable by reading and applying their instructions:

1. migration-impact-planner (../../agents/research/migration-impact-planner.md)

   • Condition: Execute if entity changes detected (new columns, entities, indexes, FK constraints, enum changes)
   • Input: Entity changes, current schema state
   • Output: Migration strategy, risks, atomic chain requirements

2. best-practices-researcher (../../agents/research/best-practices-researcher.md)

   • Condition: Execute if the feature involves security, payments, or new third-party integrations
   • Input: Feature scope, integration requirements
   • Output: Security patterns, integration best practices

3. framework-docs-researcher (../../agents/research/framework-docs-researcher.md)

   • Condition: Execute if the feature requires unfamiliar framework patterns
   • Input: Framework/library requirements
   • Output: Framework-specific patterns and conventions

4. git-history-analyzer (../../agents/research/git-history-analyzer.md)

   • Condition: Execute for legacy/refactor work where historical intent matters
   • Input: Files to analyze, refactor scope
   • Output: Historical context, previous decisions

Execution: Read applicable agent files and execute their instructions. You can read multiple files in parallel.

Round 3 — Review (execute applicable agents):

Execute the following review agents by reading and applying their instructions:

1. architecture-strategist (../../agents/review/architecture-strategist.md) — ALWAYS

   • Purpose: Structural approach, module boundaries, dependency direction
   • Input: Proposed solution, existing architecture
   • Output: Architecture feedback, structural recommendations

2. security-sentinel (../../agents/review/security-sentinel.md)

   • Condition: Only if auth, secrets, permissions, encryption, or file upload involved
   • Input: Security-sensitive components
   • Output: Security risks, mitigation strategies

3. performance-oracle (../../agents/review/performance-oracle.md)

   • Condition: Only if DB-heavy (new queries, pagination, indexes, N+1 risks)
   • Input: Database operations, query patterns
   • Output: Performance risks, optimization recommendations

Execution: Read applicable agent files and execute their instructions. You can read multiple files in parallel.

Consolidate all findings: exact file paths, method names, learnings, conventions, acceptance criteria, architecture feedback.

2. Scope & Concretization

2a. When copying or mirroring existing features:

• Open the existing feature/component. Derive: files and sizes, sections/sub-components, flows to strip vs keep.
• In the plan: enumerate "copy these files, strip A/B/C, keep D" or document copy vs reuse decision.
• Split large copies into multiple tasks.

2b. When the feature has many requirements (5+ items):

• Parse and group requirements by layer (backend/frontend) or capability.
• Add a Scope / Work Breakdown section listing each group with its requirements.
• Assign groups to phases. Cap phase size — no phase should have 10+ unrelated items.

2c. When inline editing is involved:

• List editable fields/sections from the codebase or backend DTOs.
• Document the UX pattern (edit toggle per section, global edit mode, or click-to-edit).
• Reference in implementation tasks.

2d. When a different API serves the same UI:

• Document response shape of the new API and mapping to the shape the UI expects.
• Include a mapping task in implementation.

If none of the above apply, skip this step.

3. Phase Assessment

Use phases when: multi-layer (DB + API + frontend), 4+ files, clear dependency chain. Otherwise use flat tasks (a single numbered list under ## Implementation).

If phased: phases are dependency-ordered. Each phase must have a clear theme and a bounded set of tasks. Apply splitting and grouping rules from Step 2.

4. Write Plan

Write to docs/plans/<TIMESTAMP>-<name>-plan.md (TIMESTAMP = current time in YYYYMMDDHHmmss).

YAML frontmatter:

---