plan

---

name: plan description: Architecture phase (ARCHITECT) - transforms research into rigorous technical architecture through 5 mandatory design artifacts. Interactive and iterative. argument-hint: [task-identifier]

Produces 5 mandatory artifacts: Design Rationale and Evidence, Tree of Thought, Chain of Draft, YAGNI Declaration, Pattern Selection.

You can find active tasks in ./.apex/tasks/ or run with: /apex:plan [identifier] Load task file and begin architecture process.

Contract rules:

• Architecture artifacts MUST NOT contradict task-contract scope or ACs
• If scope/ACs must change, append a <amendment ...> entry inside task-contract and bump its version

Key Findings:

• [Current implementation at file:line]
• [Pattern discovered with trust score]
• [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. Get confirmation before proceeding.

Core Components:

1. [Component A] - [purpose]
2. [Component B] - [purpose]
3. [Component C] - [purpose]

Implementation Phases:

1. [Phase name] - [what it delivers]
2. [Phase name] - [what it delivers]

Does this structure align with your vision? Should I adjust? Get confirmation before developing artifacts.

Only use patterns that exist in:

• ctx.patterns (from research.apex-patterns)
• ctx.impl (from research.codebase-patterns)

Before listing a pattern:

1. Verify it exists in the research section
2. Confirm trust score is from APEX, not invented
3. Document where in research you found it

VIOLATION: Claiming "PAT:NEW:THING" that wasn't in research CONSEQUENCE: apex_reflect will reject, trust scores become meaningless

I'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:

1. [Key outcome 1]
2. [Key outcome 2]

Implementation will NOT:

• [YAGNI item 1]
• [YAGNI item 2]

Should I proceed with the detailed architecture, or adjust any decisions? Get confirmation before finalizing.

Copy<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>

// Record architecture artifacts as evidence for learning apex_task_append_evidence(taskId, "pattern", "Architecture artifacts completed", { design_rationale: "...", tree_of_thought: { winner: "...", solutions: 3 }, yagni: { exclusions: N }, patterns_selected: ["PAT:IDs"] })

// Checkpoint for phase completion apex_task_checkpoint(taskId, "ARCHITECT: Architecture complete, ready for BUILDER", 0.75)

Copy</mcp-calls>
</step>

</workflow>

<self-review-checklist>
- [ ] Design Rationale and Evidence: ALL hidden complexity identified?
- [ ] Tree of Thought: 3 FUNDAMENTALLY different solutions?
- [ ] Chain of Draft: REAL evolution shown?
- [ ] YAGNI: 3+ explicit exclusions?
- [ ] Patterns: Trust scores and usage stats included?
- [ ] Architecture decision: CONCRETE file paths?
- [ ] New files: Test plan included for each?
- [ ] Task contract validated with AC coverage and amendments recorded if any?

**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 trust scores (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
- apex_task_checkpoint called at start and end
- apex_task_update called with db_role: ARCHITECT
- apex_task_append_evidence called to record artifacts
</success-criteria>

<next-phase>
`/apex:implement [identifier]` - Build and validate loop
</next-phase>

</skill>