Produces 5 mandatory artifacts: Design Rationale and Evidence, Tree of Thought, Chain of Draft, YAGNI Declaration, Pattern Selection. </overview>
<phase-model> phase_model: frontmatter: [research, plan, implement, rework, complete] rework: enabled db_role: [RESEARCH, ARCHITECT, BUILDER, BUILDER_VALIDATOR, REVIEWER, DOCUMENTER] legacy_db_role: [VALIDATOR] source_of_truth: gating: frontmatter.phase telemetry: db_role </phase-model> <phase-gate requires="research" sets="plan"> <reads-file>./apex/tasks/[ID].md</reads-file> <requires-section>research</requires-section> <appends-section>plan</appends-section> </phase-gate> <principles> - **Be Skeptical**: Question vague requirements, identify issues early, verify with code - **Be Interactive**: Get buy-in at each step, don't create full plan in one shot - **Be Thorough**: Read ALL files FULLY, research patterns with parallel agents - **Be Evidence-Based**: Every decision backed by code, patterns, or research - **No Open Questions**: STOP and clarify before proceeding with unknowns </principles> <initial-response> <if-no-arguments> I'll create a rigorous technical architecture. Please provide the task identifier.You can find active tasks in ./apex/tasks/ or run with:
/apex:plan [identifier]
</if-no-arguments>
<if-arguments>Load task file and begin architecture process.</if-arguments>
</initial-response>
Contract rules:
- Architecture artifacts MUST NOT contradict task-contract scope or ACs
- If scope/ACs must change, append a <amendments><amendment ...> entry inside task-contract and bump its version </instructions>
Key Findings:
- [Current implementation at file:line]
- [Pattern discovered with confidence rating]
- [Complexity identified]
Questions Requiring Human Judgment:
- [Design preference that affects architecture]
- [Business logic clarification]
- [Risk tolerance decision]
Let's address these before I develop architecture options. </template> <wait-for-user>Get confirmation before proceeding.</wait-for-user> </step>
<step id="4" title="Propose architecture structure"> <template> Here's my proposed architecture approach:Core Components:
- [Component A] - [purpose]
- [Component B] - [purpose]
- [Component C] - [purpose]
Implementation Phases:
- [Phase name] - [what it delivers]
- [Phase name] - [what it delivers]
Does this structure align with your vision? Should I adjust? </template> <wait-for-user>Get confirmation before developing artifacts.</wait-for-user> </step>
<step id="5" title="Develop 5 mandatory artifacts"> <critical> YOU CANNOT PROCEED WITHOUT ALL 5 ARTIFACTS. </critical> <artifact id="1" name="Design Rationale and Evidence"> <purpose>Explain rationale and evidence: WHY exists? WHAT problems before? WHO depends? WHERE are landmines?</purpose> <schema> design_rationale: current_state: what_exists: [Component at file:line, purpose] how_it_got_here: [Git archaeology with commit SHA] dependencies: [Verified from code] problem_decomposition: core_problem: [Single sentence] sub_problems: [Specific technical challenges] hidden_complexity: [Non-obvious issues from patterns/history] success_criteria: automated: [Test commands, metrics] manual: [User verification steps] </schema> </artifact> <artifact id="2" name="Tree of Thought Solutions"> <purpose>Generate EXACTLY 3 substantially different architectures.</purpose> <schema> tree_of_thought: solution_A: approach: [Name] description: [2-3 sentences] implementation: [Steps with file:line refs] patterns_used: [PAT:IDs with confidence ratings] pros: [Evidence-backed advantages] cons: [Specific limitations] complexity: [1-10 justified] risk: [LOW|MEDIUM|HIGH with reason] solution_B: [FUNDAMENTALLY different paradigm] solution_C: [ALTERNATIVE architecture] comparative_analysis: winner: [A|B|C] reasoning: [Why, with evidence] runner_up: [A|B|C] why_not_runner_up: [Specific limitation] </schema> </artifact> <artifact id="3" name="Chain of Draft Evolution"> <purpose>Show thinking evolution through 3 drafts.</purpose> <schema> chain_of_draft: draft_1_raw: core_design: [Initial instinct] identified_issues: [Problems recognized] draft_2_refined: core_design: [Improved, pattern-guided] improvements: [What got better] remaining_issues: [Still problematic] draft_3_final: core_design: [Production-ready] why_this_evolved: [Journey from draft 1] patterns_integrated: [How patterns shaped design] </schema> </artifact> <artifact id="4" name="YAGNI Declaration"> <purpose>Focus on production edge cases, exclude everything else.</purpose> <schema> yagni_declaration: explicitly_excluding: - feature: [Name] why_not: [Specific reason] cost_if_included: [Time/complexity] defer_until: [Trigger condition] preventing_scope_creep: - [Temptation]: [Why resisting] future_considerations: - [Enhancement]: [When makes sense] complexity_budget: allocated: [1-10] used: [By chosen solution] reserved: [Buffer] </schema> </artifact> <artifact id="5" name="Pattern Selection Rationale"> <purpose>Justify every pattern choice with evidence.</purpose> <critical> YOU CANNOT FABRICATE PATTERNS.Only use patterns that exist in:
- ctx.patterns (from research.pattern-library)
- ctx.impl (from research.codebase-patterns)
Before listing a pattern:
- Verify it exists in the research section
- Confirm confidence rating is from research, not invented
- Document where in research you found it
VIOLATION: Claiming "PAT:NEW:THING" that wasn't in research CONSEQUENCE: Final reflection becomes unreliable and confidence ratings become meaningless </critical>
<intelligence-sources> Check these sections for valid patterns: - ctx.impl (reusable_snippets, project_conventions) - ctx.patterns (pattern_cache.architecture) - ctx.web (best_practices, official_docs) - ctx.history (similar_tasks) </intelligence-sources> <schema> pattern_selection: applying: - pattern_id: [PAT:CATEGORY:NAME] confidence_rating: [★★★★☆] usage_stats: [X uses, Y% success] why_this_pattern: [Specific fit] where_applying: [file:line] source: [ctx.patterns | ctx.impl | ctx.web] considering_but_not_using: - pattern_id: [PAT:ID] why_not: [Specific reason] missing_patterns: - need: [Gap identified] workaround: [Approach without pattern] </schema> </artifact> </step> <step id="6" title="Architecture checkpoint"> <template> ## Architecture Review CheckpointI've completed the 5 mandatory artifacts. Here's the selected architecture:
Chosen Solution: [Winner from Tree of Thought] Key Patterns: [Top 3 patterns] Excluded Scope: [Top 3 YAGNI items] Complexity: [X/10] Risk Level: [LOW|MEDIUM|HIGH]
Implementation will:
- [Key outcome 1]
- [Key outcome 2]
Implementation will NOT:
- [YAGNI item 1]
- [YAGNI item 2]
Should I proceed with the detailed architecture, or adjust any decisions? </template> <wait-for-user>Get confirmation before finalizing.</wait-for-user> </step>
<step id="7" title="Generate architecture decision record"> <schema> architecture_decision: decision: [Clear statement of chosen approach] files_to_modify: - path: [specific/file.ext] purpose: [Why changing] pattern: [PAT:ID applying] validation: [How to verify] files_to_create: - path: [new/file.ext] purpose: [Why needed] pattern: [PAT:ID template] test_plan: [Test approach] implementation_sequence: 1. [Step with checkpoint] 2. [Step with validation] validation_plan: automated: [Commands to run] manual: [User verification] potential_failures: - risk: [What could go wrong] mitigation: [Prevention strategy] detection: [Early warning] </schema> </step> <step id="8" title="Write plan section to task file"> <output-format> Append to `<plan>` section:<plan>
<metadata>
<timestamp>[ISO]</timestamp>
<chosen-solution>[A|B|C]</chosen-solution>
<complexity>[1-10]</complexity>
<risk>[LOW|MEDIUM|HIGH]</risk>
</metadata>
<contract-validation>
<contract-version>[N]</contract-version>
<status>aligned|amended</status>
<acceptance-criteria-coverage>
<criterion id="AC-1">[How the plan will satisfy this AC]</criterion>
</acceptance-criteria-coverage>
<out-of-scope-confirmation>[Confirm no out-of-scope work is planned]</out-of-scope-confirmation>
<amendments-made>
<amendment version="[N]" reason="[Rationale or 'none']"/>
</amendments-made>
</contract-validation>
<design-rationale>
[Full artifact]
</design-rationale>
<tree-of-thought>
<solution id="A">[Full details]</solution>
<solution id="B">[Full details]</solution>
<solution id="C">[Full details]</solution>
<winner id="[X]" reasoning="[Why]"/>
</tree-of-thought>
<chain-of-draft>
<draft id="1">[Raw design]</draft>
<draft id="2">[Refined]</draft>
<draft id="3">[Final]</draft>
</chain-of-draft>
<yagni>
<excluding>[Features cut with reasons]</excluding>
<scope-creep-prevention>[Temptations resisted]</scope-creep-prevention>
<complexity-budget allocated="X" used="Y" reserved="Z"/>
</yagni>
<patterns>
<applying>[Patterns with locations and justifications]</applying>
<rejected>[Patterns considered but not used]</rejected>
</patterns>
<architecture-decision>
<files-to-modify>[List with purposes and patterns]</files-to-modify>
<files-to-create>[List with test plans]</files-to-create>
<sequence>[Implementation order with checkpoints]</sequence>
<validation>[Automated and manual checks]</validation>
<risks>[Potential failures with mitigations]</risks>
</architecture-decision>
<builder-handoff>
<mission>[Clear directive]</mission>
<core-architecture>[Winner approach summary]</core-architecture>
<pattern-guidance>[PAT:IDs with locations]</pattern-guidance>
<implementation-order>[Numbered steps]</implementation-order>
<validation-gates>[Checks after each step]</validation-gates>
<warnings>[Critical risks and edge cases]</warnings>
</builder-handoff>
<next-steps>
Run `/apex:implement [identifier]` to begin implementation.
</next-steps>
</plan>
If ANY unchecked → STOP and revise </self-review-checklist>
<success-criteria> - All 5 artifacts completed with evidence - User confirmed architecture decisions - Research insights incorporated (ctx.* references used) - Pattern selections justified with confidence ratings (NO fabricated patterns) - 3 DISTINCT architectures in Tree of Thought - YAGNI boundaries explicit - Task contract validated; AC coverage documented; amendments (if any) recorded with version bump - Implementation sequence concrete with validation - Task file updated at ./apex/tasks/[ID].md - Checkpoints recorded at start and end - Task metadata updated for architecture completion - Architecture artifacts recorded in the task log </success-criteria> <next-phase> `/apex:implement [identifier]` - Build and validate loop </next-phase> </skill>