trinity-method-sdk 2.0.9 → 2.2.0

package/dist/templates/.claude/commands/execution/trinity-breakdown.md.template

@@ -0,0 +1,535 @@
+# Trinity Breakdown
+
+**Command:** `/execution:trinity-breakdown`
+**Purpose:** Guided step-by-step implementation where the user makes all edits, instructed by AJ MAESTRO
+**Architecture:** ALY (CTO) → AJ MAESTRO analysis → Step-by-step user guidance → User verification
+**Trinity Version:** 2.1.0
+**Last Updated:** 2026-02-23
+
+**Use throughout your session:** This command guides you through implementations step by step.
+
+---
+
+## Overview
+
+`/trinity-breakdown` is the **guided implementation command** in Trinity Method development. Unlike `/trinity-orchestrate` where CC executes changes directly, this command has CC act as an **implementation instructor** — explaining what to change, where to change it, and why — so **you make the edits yourself**.
+
+**Key Difference from Orchestrate:**
+
+| Aspect | `/trinity-orchestrate` | `/trinity-breakdown` |
+|--------|----------------------|---------------------|
+| Who edits code | CC / KIL agents | **You** (the user) |
+| CC's role | Execute changes | Explain what to change |
+| Output | Commits and reports | Step-by-step instructions |
+| Quality gates | BAS runs automatically | You run quality checks with guidance |
+| Learning | Minimal | **Maximum** — you understand every change |
+
+**When to use Breakdown vs Orchestrate:**
+- **Breakdown:** You want to learn, understand the codebase, or make changes yourself
+- **Orchestrate:** You want CC to handle implementation autonomously
+
+**Development Session Flow:**
+```
+/trinity-start or /trinity-continue
+    |
+/trinity-breakdown (GUIDED LOOP - user makes edits)
+    |
+/trinity-end
+```
+
+---
+
+## Usage Patterns
+
+### 1. Break Down Work Orders (Formal Tasks)
+
+```bash
+/trinity-breakdown @WO-XXX-{task-name}.md
+```
+
+**When to use:**
+- Complex tasks where you want to understand every change
+- Learning a new codebase through guided implementation
+- Tasks requiring careful manual review at each step
+- Work that benefits from human judgment at each edit
+
+**Workflow:**
+1. Create work order: `/trinity-workorder`
+2. Work order saved to: `trinity/work-orders/WO-XXX-{task-name}.md`
+3. Guide: `/trinity-breakdown @WO-042-jwt-refresh.md`
+4. **AJ MAESTRO** analyzes the task and creates step-by-step instructions
+5. **You implement each step** following CC's guidance
+6. **You verify each step** (run tests, lint, build as instructed)
+7. **After completion:** Move work order from `trinity/work-orders/` to `trinity/sessions/`
+
+**Example:**
+```bash
+/trinity-breakdown @WO-042-jwt-refresh-implementation.md
+```
+
+---
+
+### 2. Break Down Investigations (READ-ONLY Analysis)
+
+```bash
+/trinity-breakdown @INV-XXX-{title}.md
+```
+
+**When to use:**
+- Guided investigation where you want to explore the codebase yourself
+- Learning how systems work through structured exploration
+- When you want to understand root causes firsthand
+
+**Workflow:**
+1. Create investigation: `/trinity-create-investigation`
+2. Investigation saved to: `trinity/investigations/INV-XXX-{title}.md`
+3. Guide: `/trinity-breakdown @INV-015-performance-analysis.md`
+4. **AJ MAESTRO** provides exploration steps
+5. **You explore** following CC's guidance (READ-ONLY — no code changes)
+6. **Findings documented** based on your discoveries
+7. **After completion:** Move investigation from `trinity/investigations/` to `trinity/sessions/`
+
+**Example:**
+```bash
+/trinity-breakdown @INV-015-database-performance-analysis.md
+```
+
+---
+
+### 3. Break Down General Tasks (Quick Tasks)
+
+```bash
+/trinity-breakdown "Task description"
+```
+
+**When to use:**
+- Quick changes where you want step-by-step guidance
+- Learning how to implement a specific pattern
+- Simple fixes with instructional walkthrough
+
+**How it works:**
+- AJ MAESTRO assesses task complexity
+- Breaks it into individual steps with instructions
+- Guides you through each step
+- Helps you verify the result
+
+**Example:**
+```bash
+/trinity-breakdown "Fix date validation bug in UserForm component"
+```
+
+---
+
+## AJ MAESTRO's Breakdown Process
+
+When you invoke `/trinity-breakdown`, here's what happens:
+
+### Step 1: Task Analysis
+
+**AJ MAESTRO reads and analyzes:**
+- Work order file (if @WO-XXX provided)
+- Investigation file (if @INV-XXX provided)
+- Task description (if general task)
+
+**Determines:**
+- Task complexity and scope
+- Required expertise areas
+- Optimal step-by-step breakdown
+- Verification checks for each step
+
+---
+
+### Step 2: Agent Persona Selection
+
+**AJ MAESTRO selects the best agent persona(s) for guidance:**
+
+CC adopts the relevant agent's expertise to provide specialized instructions:
+
+- **MON persona** — Requirements guidance
+- **ROR persona** — Design and architecture guidance
+- **KIL persona** — Implementation instructions (TDD guidance)
+- **BAS persona** — Quality gate verification instructions
+- **DRA persona** — Code review guidance
+- **APO persona** — Documentation instructions
+
+**Selection Criteria:**
+- Small tasks (1-2 files): Direct KIL-style implementation guidance
+- Medium tasks (3-5 files): Design overview, then step-by-step implementation
+- Large tasks (6+ files): Full planning overview, then phased step-by-step guidance
+
+---
+
+### Step 3: Walk-Through Execution
+
+**AJ MAESTRO presents each change as a structured instruction:**
+
+For each step, CC provides:
+
+1. **What file to open** — Exact file path
+2. **Where to make the change** — Line numbers or code context
+3. **What to change** — The specific edit (old code → new code)
+4. **Why this change is needed** — Reasoning and context
+5. **How to verify** — What to check after making the change
+
+**Instruction Format:**
+
+```
+STEP X of Y: [Brief description]
+
+FILE: path/to/file.ext
+LOCATION: Line XX (after/before [context])
+
+WHAT TO DO:
+[Clear instruction — add, modify, or remove code]
+
+CODE:
+[Exact code to write or the change to make]
+
+WHY:
+[Brief explanation of why this change is needed]
+
+VERIFY:
+[How to check this step worked — e.g., "Save and run: npm test"]
+```
+
+**Important Rules for Instructions:**
+- One change per step (atomic instructions)
+- Always provide the exact file path
+- Always explain WHY, not just WHAT
+- Include verification after each meaningful change
+- Never skip ahead — wait for user confirmation before next step
+
+---
+
+### Step 4: User Verification
+
+**After each significant phase, CC guides you to verify:**
+
+```
+VERIFICATION CHECKPOINT
+
+Run these commands to verify your changes:
+
+1. Build:  npm run build
+2. Lint:   npm run lint
+3. Test:   npm test
+
+Expected Results:
+- Build: Should compile without errors
+- Lint: No new warnings or errors
+- Test: All tests should pass
+
+If any check fails, let me know and I'll help you fix it.
+```
+
+---
+
+### Step 5: Completion Summary
+
+**After all steps are complete, CC provides:**
+- Summary of all changes made
+- Files modified
+- Tests affected
+- Next steps or follow-up recommendations
+- Work order completion workflow (move to sessions/)
+
+---
+
+## After Task Completion Workflow
+
+### When You've Completed All Steps
+
+**Step 1: Verify All Changes**
+- [ ] All instructed changes have been made
+- [ ] Build passes: `npm run build` (or equivalent)
+- [ ] Lint passes: `npm run lint` (or equivalent)
+- [ ] Tests pass: `npm test` (or equivalent)
+
+**Step 2: Move Completed File to Sessions**
+
+```bash
+# Work Order
+mv trinity/work-orders/WO-XXX-*.md trinity/sessions/
+
+# Investigation
+mv trinity/investigations/INV-XXX-*.md trinity/sessions/
+```
+
+**Step 3: Verify File Locations**
+- [ ] Completed file NOW EXISTS in: `trinity/sessions/`
+- [ ] Completed file NO LONGER EXISTS in: `trinity/work-orders/` or `trinity/investigations/`
+
+**Step 4: Continue or End Session**
+- Continue with next task, or
+- Run `/trinity-end` to archive session
+
+---
+
+## Real-World Examples
+
+### Example 1: Work Order Breakdown
+
+```
+User: /trinity-breakdown @WO-042-jwt-refresh-implementation.md
+
+AJ MAESTRO: Reading work order WO-042...
+
+I'll walk you through implementing JWT token refresh step by step.
+You'll make all the edits — I'll tell you exactly what to change and why.
+
+OVERVIEW:
+- 4 files to create/modify
+- 8 steps total
+- Estimated time: 45-60 minutes
+- You'll need: Your code editor and a terminal
+
+Let's begin.
+
+---
+
+STEP 1 of 8: Create the token refresh service file
+
+FILE: src/services/token-refresh.service.ts
+LOCATION: New file
+
+WHAT TO DO:
+Create a new file with the following content:
+
+CODE:
+import { sign, verify } from 'jsonwebtoken';
+
+export interface TokenPair {
+  accessToken: string;
+  refreshToken: string;
+}
+
+export class TokenRefreshService {
+  async refreshToken(userId: string): Promise<TokenPair> {
+    const accessToken = sign({ userId }, process.env.JWT_SECRET!, {
+      expiresIn: '15m',
+    });
+    const refreshToken = sign({ userId }, process.env.REFRESH_SECRET!, {
+      expiresIn: '7d',
+    });
+    return { accessToken, refreshToken };
+  }
+}
+
+WHY:
+This service encapsulates token generation logic. We separate access tokens
+(short-lived, 15 min) from refresh tokens (long-lived, 7 days) following
+the OAuth 2.0 refresh token pattern. This prevents users from needing to
+re-authenticate frequently while maintaining security.
+
+VERIFY:
+Save the file and run: npm run build
+Expected: Should compile without errors (no tests yet — that's next)
+
+Ready for Step 2? (Say "next" to continue)
+```
+
+---
+
+### Example 2: Investigation Breakdown
+
+```
+User: /trinity-breakdown @INV-015-database-performance-analysis.md
+
+AJ MAESTRO: Reading investigation INV-015...
+
+I'll guide you through investigating the database performance issue.
+You'll explore the codebase yourself — I'll point you where to look.
+
+This is a READ-ONLY investigation. No code changes.
+
+OVERVIEW:
+- 5 exploration steps
+- Estimated time: 30 minutes
+- Goal: Identify root cause of 300% query time increase
+
+Let's begin.
+
+---
+
+STEP 1 of 5: Check the slow query patterns
+
+WHAT TO DO:
+Open this file and look for the getUserOrders function:
+
+FILE: src/services/order.service.ts
+LOCATION: Search for "getUserOrders"
+
+WHAT TO LOOK FOR:
+- Is it loading related data (users, products) inside a loop?
+- Does it use eager loading (include/join) or lazy loading (separate queries)?
+- Count how many database calls happen per invocation
+
+WHY:
+N+1 query patterns are the most common cause of sudden performance
+degradation. If orders are loaded first, then each order's user is
+loaded individually, that's N+1 queries.
+
+REPORT BACK:
+Tell me what you find — specifically:
+1. How many queries does this function make?
+2. Is there a loop that makes individual DB calls?
+3. Are there any JOIN or include statements?
+```
+
+---
+
+### Example 3: Quick Task Breakdown
+
+```
+User: /trinity-breakdown "Fix date validation bug in UserForm component"
+
+AJ MAESTRO: Analyzing task...
+
+I'll walk you through fixing the date validation bug.
+2 steps — should take about 10 minutes.
+
+---
+
+STEP 1 of 2: Add the validation function
+
+FILE: src/components/UserForm.tsx
+LOCATION: Find the validateDate function (around line 45)
+
+WHAT TO DO:
+Replace the current validation:
+
+BEFORE:
+const isValid = date !== '';
+
+AFTER:
+const isValid = (() => {
+  if (!date) return false;
+  const parsed = new Date(date);
+  return parsed instanceof Date && !isNaN(parsed.getTime());
+})();
+
+WHY:
+The current validation only checks if the string is non-empty.
+It doesn't validate the actual date format, so "13/32/2025" passes.
+The new validation parses the date and checks if it's a real date.
+
+VERIFY:
+Save and run: npm test -- --testPathPattern="UserForm"
+Expected: Tests should pass (existing tests still work)
+
+---
+
+STEP 2 of 2: Add test for the edge case
+
+FILE: src/components/UserForm.test.tsx
+LOCATION: After the last test in the "date validation" describe block
+
+WHAT TO DO:
+Add this test:
+
+CODE:
+it('should reject invalid date formats', () => {
+  render(<UserForm />);
+  const dateInput = screen.getByLabelText('Date');
+  fireEvent.change(dateInput, { target: { value: '13/32/2025' } });
+  expect(screen.getByText('Invalid date')).toBeInTheDocument();
+});
+
+WHY:
+This test ensures the bug doesn't regress. It specifically tests the
+invalid date format that was previously accepted.
+
+VERIFY:
+Run: npm test -- --testPathPattern="UserForm"
+Expected: All tests pass, including the new one
+
+---
+
+VERIFICATION CHECKPOINT
+
+All changes complete! Run final checks:
+
+1. npm run build    (should compile)
+2. npm run lint     (no new warnings)
+3. npm test         (all tests pass)
+
+Summary:
+- Fixed: Date validation now rejects invalid formats
+- Added: 1 regression test
+- Files changed: 2 (UserForm.tsx, UserForm.test.tsx)
+
+Task complete!
+```
+
+---
+
+## When NOT to Use /trinity-breakdown
+
+**Don't use for:**
+
+- **Starting a session** → Use `/trinity-start` or `/trinity-continue`
+- **Creating work orders** → Use `/trinity-workorder` to create, then break it down
+- **Creating investigations** → Use `/trinity-create-investigation` to create, then break it down
+- **Ending your session** → Use `/trinity-end` to archive work
+- **When you want AI to do the work** → Use `/trinity-orchestrate` instead
+
+**Use /trinity-breakdown for:**
+
+- Learning how to implement a feature
+- Understanding the codebase through guided changes
+- Making changes yourself with expert guidance
+- Training or onboarding through hands-on implementation
+
+---
+
+## Related Commands
+
+### Session Management
+- `/trinity-start` - Begin new development session
+- `/trinity-continue` - Resume interrupted session
+- `/trinity-end` - End session and archive work
+
+### Task Creation
+- `/trinity-workorder` - Create formal work order for complex tasks
+- `/trinity-create-investigation` - Create investigation for analysis
+
+### Execution Alternatives
+- `/trinity-orchestrate` - AI-executed implementation (CC makes the changes)
+- `/trinity-audit` - Comprehensive Trinity deployment audit
+
+### Planning
+- `/trinity-requirements` - Deep requirements analysis with MON
+- `/trinity-design` - Technical design creation with ROR
+- `/trinity-plan` - Implementation planning with TRA
+- `/trinity-decompose` - Atomic task decomposition with EUS
+
+---
+
+## Summary
+
+**Guided Implementation Command:** `/trinity-breakdown` walks you through changes step by step.
+
+**Key Points:**
+1. **You make all edits** — CC instructs, you implement
+2. **Step-by-step instructions** — File path, line numbers, what to change, why
+3. **Verification at each step** — Run tests, lint, build as guided
+4. **Same usage patterns** — @WO-XXX (work orders), @INV-XXX (investigations), "description" (quick tasks)
+5. **Maximum learning** — Understand every change you make
+
+**When to choose Breakdown:**
+- You want to learn and understand the changes
+- You prefer hands-on implementation with expert guidance
+- You want to review each change before it's applied
+
+**When to choose Orchestrate instead:**
+- You want CC to handle implementation autonomously
+- Speed is more important than learning
+- You trust the AI to make the right changes
+
+**Typical Session Flow:**
+```bash
+/trinity-start                                    # Begin session
+/trinity-breakdown @WO-042-jwt-refresh.md        # Guided implementation
+/trinity-breakdown "Fix validation bug"           # Quick guided fix
+/trinity-end                                      # End session
+```