METHODOLOGY: "PRP (Product Requirement Prompt) + ACE (Agentic Context Engineering)"
PHILOSOPHY: "One-pass implementation success through comprehensive context"
TRIGGER: "/plan command OR any planning/architecture request"

PRP_LAYERS:
  layer_1: "What + Why (goal)"
  layer_2: "Curated codebase intelligence (files, patterns)"
  layer_3: "Agent execution playbook (steps, validations, rollback)"

ACE_MECHANISM:
  generator: "Executes reasoning, tool calls"
  reflector: "Extracts insights from execution"
  curator: "Applies incremental updates to context"
  grow_and_refine: "Add insights → Track helpfulness → Prune redundancy"

triggers:
  - Convex (queries, mutations, schema)
  - Clerk (auth, users, sessions)
  - TanStack Router (routes, loaders)
  - shadcn/ui (components)
  - Recharts (charts, visualization)
  - Any npm library/API
  - Vite, Biome, TypeScript config

usage: "resolve-library-id → query-docs"

triggers:
  - Context7 returns insufficient info
  - Deploy/runtime errors without clear solution
  - Best practices / modern patterns (2024+)
  - Undocumented integrations

usage: "tavily-search → tavily-extract if URL promising"

triggers:
  - L4+ complexity tasks
  - After any build/deploy/runtime error
  - Every 5 implementation steps (progress check)
  - Multiple approaches possible (trade-off analysis)
  - Architectural decisions

usage: "Break into steps, analyze root cause, compare options"

priority_order:
  1: "Search codebase for patterns, conventions"
  2: "Query Context7 for official docs"
  3: "Tavily web search for best practices, security"
  4: "Delegate to specialists if domain-specific"

outputs:
  - "Findings Table: | # | Finding | Confidence (1-5) | Source | Impact |"
  - "Knowledge Gaps: what you still don't know"
  - "Assumptions to Validate: explicit assumptions requiring confirmation"
  - "Edge Cases / Failure Modes: at least 5 when complexity ≥ L4"

anti_hallucination:
  - "NEVER speculate about unopened code"
  - "MUST read files before making claims"
  - "Search and verify BEFORE responding"
  - "If fact unknown: research it OR mark as Knowledge Gap"

decomposition:
  method: "Atomic Task Decomposition"
  principle: "Each task completable in isolation with clear validation"

task_template:
  id: "AT-XXX"
  title: "Action verb + specific target"
  phase: "1-5 (foundation → core → integration → polish → validation)"
  priority: "critical | high | medium | low"
  dependencies: "[AT-XXX]"
  parallel_safe: "true/false (mark ⚡ PARALLEL-SAFE when true)"
  files_to_create: "[paths]"
  files_to_modify: "[paths]"
  validation: "Specific command/check"
  rollback: "Exact undo steps"
  acceptance_criteria: "[measurable bullets]"

parallel_safe_when:
  - "No shared file modifications"
  - "No dependency chain"
  - "Independent validation"

behavior: "PROACTIVE"
instruction: |
  Implement changes instead of suggesting.
  Infer intent and proceed using tools.
  Trust existing references, execute directly.

pattern: "Implement → Validate → Commit (or Rollback)"
validation_after_each: true

quality_gates:
  - "bun run lint"
  - "bun run typecheck"
  - "bun run test"
  - "bun run build"

anti_hardcoding: |
  Write general-purpose solutions for ALL valid inputs.
  Never hard-code for specific test cases.
  Report incorrect tests instead of workarounds.

tasks:
  - "Build: zero errors"
  - "Lint: zero warnings"
  - "Tests: all passing"
  - "@code-reviewer if security involved"
  - "@database-specialist if schema changes"

reflection: |
  After each result, reflect on quality and
  determine optimal next steps before proceeding.

success: "All gates pass, no regressions, docs updated, backward compatible"

# File: docs/PLAN-{task-slug}.md

# [Task Title]

## Metadata
complexity: "L[1-10] — [JUSTIFICATION]"
estimated_time: "[DURATION]"
parallel_safe: [true/false]

## Objective
task: "[ACTION VERB] + [TARGET] + [OUTCOME]"
context: "[PROJECT], [STACK], [CONSTRAINTS]"
why_this_matters: "[MOTIVATION]"

## Environment
runtime: "Bun 1.x"
framework: "React 19"
database: "Convex"
auth: "Clerk"
ui: "shadcn/ui"
testing: "Vitest"

## Research Summary
### Findings Table
| # | Finding | Confidence | Source | Impact |

### Knowledge Gaps
- [gaps]

### Assumptions to Validate
- [assumptions]

## Relevant Files
### Must Read
- path: "[PATH]"
  relevance: "[WHY]"

### May Reference
- path: "[PATH]"
  relevance: "[WHY]"

## Existing Patterns
naming: "[DESCRIBE]"
file_structure: "[DESCRIBE]"
error_handling: "[DESCRIBE]"
state_management: "[DESCRIBE]"

## Constraints
non_negotiable: ["[CONSTRAINT_1]", "[CONSTRAINT_2]"]
preferences: ["[PREFERENCE_1]"]

## Chain of Thought
### Research
- Codebase patterns: _____
- Docs consulted: _____
- Security: _____
- Edge cases: _____

### Analyze
- Core requirement: _____
- Technical constraints: _____
- Integration points: _____

### Think
step_by_step: ["First: _____", "Then: _____", "Finally: _____"]
tree_of_thoughts:
  approach_a: {description, pros, cons, score}
  approach_b: {description, pros, cons, score}
  selected: "[CHOSEN]"
  rationale: "[WHY]"

## Atomic Tasks
- id: "AT-001"
  title: "[ACTION] [TARGET]"
  phase: 1
  priority: "critical"
  dependencies: []
  parallel_safe: true
  files_to_create: ["[PATH]"]
  files_to_modify: ["[PATH]"]
  validation: "[COMMAND]"
  rollback: "[UNDO]"
  acceptance_criteria: ["[CRITERION]"]

## Validation Gates
automated:
  - {id: "VT-001", command: "bun run build", expected: "Exit 0"}
  - {id: "VT-002", command: "bun run lint", expected: "No errors"}
  - {id: "VT-003", command: "bun run test", expected: "All pass"}
manual_review:
  - {reviewer: "@code-reviewer", focus: "[ASPECT]", required_if: "[CONDITION]"}

## Output
format: "[DELIVERABLE]"
files_created: [{path, purpose}]
files_modified: [{path, changes}]
success_definition: "[CRITERIA]"
failure_handling: "If [CONDITION], then [ACTION]. Rollback: [STEPS]"

research:
  - [ ] Codebase searched?
  - [ ] Docs consulted (Context7)?
  - [ ] Web research done (Tavily)?
  - [ ] Security/compliance identified?
  - [ ] Edge cases considered (min 5 for L4+)?

context:
  - [ ] Findings Table included?
  - [ ] Knowledge Gaps listed?
  - [ ] Assumptions to Validate listed?
  - [ ] Relevant files specified?
  - [ ] WHY included for instructions?

tasks:
  - [ ] Truly atomic?
  - [ ] Validation command each?
  - [ ] Dependencies mapped?
  - [ ] Rollback defined?
  - [ ] Parallel-safe marked?

behavior:
  - [ ] Mode specified (CONSERVATIVE/PROACTIVE)?
  - [ ] Output format explicit?
  - [ ] Success criteria measurable?
  - [ ] Failure handling defined?

R.P.I.V: RESEARCH → PLAN → IMPLEMENT → VALIDATE

GOLDEN RULES:
✓ RESEARCH FIRST — never implement blind
✓ Be EXPLICIT — agent follows literally
✓ Explain WHY — enables generalization
✓ CONTEXT DENSITY > BREVITY
✓ ATOMIC TASKS — small, validated, rollback-ready
✓ PARALLEL TOOLS — unless dependencies
✓ REFLECT AFTER TOOLS — think before next action

COMPLEXITY → BUDGET:
L1-L2: 1K-4K   | Bug fix, refactor
L3-L5: 8K-16K  | Feature, API
L6-L8: 16K-32K | Architecture
L9-L10: 32K+   | New systems

✅ Plan created: docs/PLAN-{slug}.md

Next steps:
- Review the plan
- Run `/implement` to start implementation
- Or modify plan manually