@namch/agent-assistant 1.0.2 → 1.0.4

package/commands/plan/focus.md

@@ -0,0 +1,190 @@
+---
+description: 🔒 Focused Plan — Research-backed planning with enforced context optimization
+version: "1.0"
+category: planning
+execution-mode: execute
+---
+
+# /plan:focus — Focus Comprehensive Planning
+
+> **MISSION**: Create thorough implementation plan with **enforced context optimization**.
+>
+> This variant automatically clears context before handoff—no user prompt required.
+> Use when you want guaranteed clean plan handoff without context rot risk.
+
+<task>$ARGUMENTS</task>
+
+---
+
+## 🛑 PRE-FLIGHT (DO FIRST — BLOCKS PHASE 1)
+
+**LOAD now** (in order; path `./rules/` or `~/.{TOOL}/skills/agent-assistant/rules/`):
+
+1. ORCHESTRATION-LAWS.md
+2. ADAPTIVE-EXECUTION.md
+3. EXECUTION-PROTOCOL.md
+
+**⛔ Do not run Phase 1 until all are loaded.** Follow **all** rules in those files; they override any conflicting instructions in this file.
+
+---
+
+## 🔀 TIERED EXECUTION
+
+| Tier       | When               | Action                       |
+| ---------- | ------------------ | ---------------------------- |
+| **TIER 1** | runSubagent EXISTS | Invoke sub-agent (MANDATORY) |
+| **TIER 2** | Tool MISSING       | EMBODY agent file (FALLBACK) |
+
+---
+
+## 📁 DELIVERABLE FILES
+
+| Agent      | Output                                                                                                                                                                   |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| researcher | `./reports/researchers/RESEARCH-{task}.md`                                                                                                                               |
+| scouter    | `./reports/scouts/SCOUT-{task}.md`                                                                                                                                       |
+| planner    | **One** `./reports/plans/PLAN-{task}.md` **OR** multiple `./reports/plans/PLAN-{task}-phase1.md`, `PLAN-{task}-phase2.md`, … (see **Complexity & plan splitting** below) |
+
+**Plans are source of truth for implementation.** All files in `./reports/` → English only.
+
+---
+
+## 📐 COMPLEXITY & PLAN SPLITTING (MANDATORY FOR PLANNER)
+
+When the logical plan would have **> 3 phases** or **estimated effort > 3 days**, the planner **MUST** produce **multiple plan files** (one per executable phase or per milestone group), **not** one monolithic file.
+
+| Condition                  | Planner output                                                   |
+| -------------------------- | ---------------------------------------------------------------- |
+| ≤ 3 phases, ≤ 3 days       | **One** `PLAN-{task}.md`                                         |
+| > 3 phases **or** > 3 days | **Multiple** `PLAN-{task}-phase1.md`, `PLAN-{task}-phase2.md`, … |
+
+**Multi-plan rules:**
+
+- Naming: `PLAN-{task}-phase1.md`, `PLAN-{task}-phase2.md`, …
+- Order: Execute in numeric order; phase N starts only after phase N−1 is complete.
+- Each file: scope **only** that phase; Prerequisites state "Phase N−1 complete" (or prior deliverables); clear handoff to next file.
+- Index (optional): planner may add `PLAN-{task}-INDEX.md` listing phases and file names for navigation.
+
+---
+
+## ⛔ INCREMENTAL EXECUTION (MANDATORY)
+
+One phase at a time, each phase independent: Phase 1 → then Phase 2 → … in one reply. No batching (load only what each phase needs). **Within each phase:** when doing a part, output it in format so user sees what's happening (announce before doing). Format: rules/EXECUTION-PROTOCOL.md § Phase output structure.
+
+---
+
+## 🎭 Phase 1: RESEARCH
+
+| Agent  | `researcher`                                  |
+| ------ | --------------------------------------------- |
+| Goal   | Research best practices and patterns          |
+| Output | `./reports/researchers/RESEARCH-{task}.md`    |
+| Exit   | Best practices identified, sources documented |
+
+---
+
+## 🎭 Phase 2: CODEBASE ANALYSIS
+
+| Agent  | `scouter`                                    |
+| ------ | -------------------------------------------- |
+| Goal   | Full architecture mapping                    |
+| Output | `./reports/scouts/SCOUT-{task}.md`           |
+| Exit   | Architecture understood, dependencies mapped |
+
+---
+
+## 🎭 Phase 3: DESIGN (IF UI NEEDED)
+
+| Agent   | `designer`                                        |
+| ------- | ------------------------------------------------- |
+| Trigger | Task involves UI/UX                               |
+| Goal    | Design approach input                             |
+| Exit    | Design approach defined, accessibility considered |
+
+---
+
+## 🎭 Phase 4: PLAN CREATION
+
+| Agent        | `planner`                                                                                                                   |
+| ------------ | --------------------------------------------------------------------------------------------------------------------------- |
+| Prerequisite | **READ** RESEARCH + SCOUT files (and DESIGN if Phase 3 ran)                                                                 |
+| Goal         | Create detailed implementation plan as **one file** or **multiple phase files** (see **Complexity & plan splitting** above) |
+| Output       | One `./reports/plans/PLAN-{task}.md` **or** multiple `./reports/plans/PLAN-{task}-phase1.md`, `PLAN-{task}-phase2.md`, …    |
+
+**Directive to planner:** If the task decomposes into **> 3 phases** or **> 3 days** effort, produce **multiple plan files** (one per phase/milestone), each executable in sequence. Otherwise produce a single `PLAN-{task}.md`.
+
+**CONSTRAINT INHERITANCE:**
+
+```
+Plan(s) MUST reference prior phases:
+- "Based on research finding R1..."
+- "Following pattern from Scout..."
+- "Per design decision D1..."
+```
+
+| Exit | One plan file **or** multiple phase plan files created; each has scope, prerequisites, tasks, exit criteria, risks, rollback; order and handoffs clear |
+
+---
+
+## 🛡️ STRICT CONTEXT GATE — Automatic Context Optimization
+
+> **⚡ FOCUS MODE**: This checkpoint executes automatically. NO user input required.
+>
+> **PURPOSE**: Prevent "context rot" by forcibly clearing noisy research/planning history.
+> This acts as a mandatory "firewall" before handoff to implementation workflows.
+
+### 🔒 AUTOMATIC EXECUTION (NO PROMPT)
+
+```yaml
+strict_context_gate:
+  mode: "AUTOMATIC - No user interaction"
+  behavior: "Force Clear context & Ready"
+
+  execution:
+    1. ANNOUNCE: |
+      ## 🛡️ Strict Context Gate — Automatic
+
+      ✅ **Plan Complete**: Plan file(s) created.
+      🔒 **Focus Mode**: Automatically clearing context for implementation handoff.
+
+      ⚡ Executing: **Clear context & Ready**...
+
+    2. CONTEXT_DIRECTIVE: |
+      ╔══════════════════════════════════════════════════════════════════╗
+      ║  ⛔ MANDATORY CONTEXT RESET — FOCUS MODE                         ║
+      ╠══════════════════════════════════════════════════════════════════╣
+      ║  IGNORE: All previous research discussions, exploration paths,   ║
+      ║          rejected alternatives, and intermediate reasoning.      ║
+      ║                                                                  ║
+      ║  SOLE SOURCE OF TRUTH: Plan file(s) in ./reports/plans/          ║
+      ║                                                                  ║
+      ║  HANDOFF: Plan is ready for `/code:focus` implementation.        ║
+      ║           Implementation should treat Plan as fresh context.     ║
+      ╚══════════════════════════════════════════════════════════════════╝
+
+    3. OUTPUT: Plan summary for user
+
+    4. PROCEED: To COMPLETION
+```
+
+### 📋 Post-Gate Status
+
+```markdown
+🔒 **Context Gate Passed**
+
+- Previous context: DISCARDED
+- Active context: Plan file(s) only
+- Mode: Clean handoff ready
+
+Plan ready for implementation...
+```
+
+---
+
+## COMPLETION
+
+Present plan with:
+
+1. ✅ **Plan Ready** — `./reports/plans/PLAN-{task}.md` (single) **or** `PLAN-{task}-phase1.md`, `PLAN-{task}-phase2.md`, … (multi-phase, execute in order)
+2. 🔒 **Context Optimized** — Ready for focus implementation
+3. 🍳 **Implement** → `/code:focus` (run phase-by-phase when multiple plan files exist)

package/commands/plan/hard.md

@@ -123,6 +123,62 @@ Plan(s) MUST reference prior phases:
 
 ---
 
+## 🛡️ VERIFICATION CHECKPOINT — Context Optimization
+
+> **PURPOSE**: Prevent "context rot" by clearing noisy research/planning history before implementation.
+> 
+> Long-running planning sessions fill context with noise that degrades implementation quality.
+> This checkpoint acts as a "firewall" before handing off to implementation workflows.
+
+### ⚡ OPTIONS (Present to User)
+
+```markdown
+## 🛡️ Context Optimization Checkpoint
+
+**Planning Complete** — Plan file(s) created.
+
+**Choose how to proceed:**
+
+| Option | Action | Description |
+|--------|--------|-------------|
+| **1. 🚀 Clear context & Ready** | `RECOMMENDED` | Fresh start for implementation: Reload Plan, ignore planning history |
+| **2. ⏸️ Review First** | `SAFE` | Clear context, show plan summary, wait for approval |
+| **3. ⚠️ Continue (No Clear)** | `RISKY` | Keep full history (may affect `/cook:hard` quality) |
+
+⏳ Awaiting selection...
+```
+
+### 🔄 EXECUTION BEHAVIOR
+
+```yaml
+option_1_clear_ready:
+  behavior: "RECOMMENDED - Prepare clean handoff"
+  steps:
+    1. ACKNOWLEDGE: "🚀 Context optimized. Plan ready for implementation."
+    2. CONTEXT_DIRECTIVE: |
+       ⛔ IGNORE all previous research/planning reasoning chains.
+       ✅ PLAN FILE is SOLE SOURCE OF TRUTH for implementation.
+    3. OUTPUT: "Run `/code:focus` to implement with clean context."
+
+option_2_review_first:
+  behavior: "Clear and show summary"
+  steps:
+    1. ACKNOWLEDGE: "⏸️ Context cleared."
+    2. CONTEXT_DIRECTIVE: |
+       ⛔ IGNORE all previous research/planning reasoning chains.
+       ✅ PLAN FILE is SOLE SOURCE OF TRUTH.
+    3. OUTPUT: Display plan summary for user review
+    4. WAIT: For user approval before proceeding
+
+option_3_continue_no_clear:
+  behavior: "Proceed with caution - context rot risk"
+  steps:
+    1. WARN: "⚠️ Continuing with full history. May affect implementation quality."
+    2. PROCEED: Complete workflow with existing context
+```
+
+---
+
 ## COMPLETION
 
 Present plan with:

package/commands/plan.md

@@ -16,9 +16,10 @@ execution-mode: router
 ## 🛑 PRE-FLIGHT (DO FIRST — BLOCKS EXECUTION)
 
 **LOAD now** (in order; path `./rules/` or `~/.{TOOL}/skills/agent-assistant/rules/`):
-1. ORCHESTRATION-LAWS.md  
-2. ADAPTIVE-EXECUTION.md  
-3. EXECUTION-PROTOCOL.md  
+
+1. ORCHESTRATION-LAWS.md
+2. ADAPTIVE-EXECUTION.md
+3. EXECUTION-PROTOCOL.md
 
 **⛔ Do not run any workflow phase until all are loaded.** Follow **all** rules in those files. Then run this file's ROUTING LOGIC, LOAD the chosen variant (e.g. plan/hard.md), and execute it.
 
@@ -33,6 +34,9 @@ IF task is clear (known approach, codebase-only):
 IF task is complex (research needed, architectural):
   → Route to /plan:hard
 
+IF task is complex AND clean implementation handoff is critical:
+  → Route to /plan:focus
+
 IF unsure:
   → Default to /plan:fast
 ```
@@ -41,10 +45,11 @@ IF unsure:
 
 ## AVAILABLE ROUTES
 
-| Route        | When to Use                     |
-| ------------ | ------------------------------- |
-| `/plan:fast` | Quick planning without research |
-| `/plan:hard` | Full planning with research     |
+| Route         | When to Use                                          |
+| ------------- | ---------------------------------------------------- |
+| `/plan:fast`  | Quick planning without research                      |
+| `/plan:hard`  | Full planning with research                          |
+| `/plan:focus` | Full planning with **enforced context optimization** |
 
 ---
 
@@ -59,6 +64,7 @@ IF unsure:
 
 1. ⚡ **Fast** → `/plan:fast` — Quick plan
 2. ⚡⚡⚡ **Hard** → `/plan:hard` — Full research-backed plan
+3. 🎯 **Focus** → `/plan:focus` — Full plan with **automatic context clearing** (clean implementation handoff)
 
 ⏳ Awaiting selection...
 ```

package/commands/report/fast.md

@@ -0,0 +1,71 @@
+---
+description: ⚡ Fast Report — Quick status updates and summaries
+version: "1.0"
+category: documentation
+execution-mode: execute
+---
+
+# /report:fast — Quick Status Report
+
+> **MISSION**: Generate concise, actionable status reports and summaries.
+>
+> Use for daily standups, progress checks, and high-level overviews.
+> For **update existing files** or **generate from template**, use `/report:hard` or `/report:focus`.
+
+<task>$ARGUMENTS</task>
+
+---
+
+## 🛑 PRE-FLIGHT (DO FIRST — BLOCKS PHASE 1)
+
+**LOAD now** (in order; path `./rules/` or `~/.{TOOL}/skills/agent-assistant/rules/`):
+
+1. ORCHESTRATION-LAWS.md
+2. ADAPTIVE-EXECUTION.md
+3. EXECUTION-PROTOCOL.md
+
+**⛔ Do not run Phase 1 until all are loaded.** Follow **all** rules in those files; they override any conflicting instructions in this file.
+
+---
+
+## 🔀 TIERED EXECUTION
+
+| Tier       | When               | Action                       |
+| ---------- | ------------------ | ---------------------------- |
+| **TIER 1** | runSubagent EXISTS | Invoke sub-agent (MANDATORY) |
+| **TIER 2** | Tool MISSING       | EMBODY agent file (FALLBACK) |
+
+**❌ Anti-Lazy**: Never use TIER 2 when TIER 1 tool available.
+
+---
+
+## ⛔ INCREMENTAL EXECUTION (MANDATORY)
+
+One phase at a time, each phase independent: Phase 1 → then Phase 2 → … in one reply. No batching (load only what each phase needs). **Within each phase:** when doing a part, output it in format so user sees what's happening (announce before doing). Format: rules/EXECUTION-PROTOCOL.md § Phase output structure.
+
+---
+
+## 🎭 Phase 1: INFORMATION GATHERING
+
+| Agent | `reporter`                               |
+| ----- | ---------------------------------------- |
+| Goal  | Scan current state and recent activities |
+| Exit  | Progress summarized, key sources scanned |
+
+---
+
+## 🎭 Phase 2: REPORT GENERATION
+
+| Agent | `reporter`                                                                 |
+| ----- | -------------------------------------------------------------------------- |
+| Goal  | Infer intent; if **create report** → generate concise status report        |
+| Exit  | Report with Summary, Key Changes, Next Steps — or recommend `/report:hard`/`/report:focus` if user intent is update/template |
+
+---
+
+## COMPLETION
+
+Present report:
+
+1. ✅ **Report Ready** — Displayed in chat
+2. 📄 **Save?** → If user wants to save: `./reports/general/REPORT-status-{YYYY-MM-DD}.md`

package/commands/report/focus.md

@@ -0,0 +1,156 @@
+---
+description: 🔒 Focused Report — Deep analysis with enforced context optimization
+version: "1.0"
+category: documentation
+execution-mode: execute
+---
+
+# /report:focus — Focused Deep Analysis Report
+
+> **MISSION**: Generate verifiable, objective output with **enforced context optimization** — report, update, or template.
+
+> This variant automatically clears context before analysis—no user prompt required.
+> Use when you want a "clean slate" audit or unbiased analysis. Reporter chooses: **create report**, **update existing files**, or **generate from template** per user intent.
+
+<task>$ARGUMENTS</task>
+
+---
+
+## 🛑 PRE-FLIGHT (DO FIRST — BLOCKS PHASE 1)
+
+**LOAD now** (in order; path `./rules/` or `~/.{TOOL}/skills/agent-assistant/rules/`):
+
+1. ORCHESTRATION-LAWS.md
+2. ADAPTIVE-EXECUTION.md
+3. EXECUTION-PROTOCOL.md
+
+**⛔ Do not run Phase 1 until all are loaded.** Follow **all** rules in those files; they override any conflicting instructions in this file.
+
+---
+
+## 🔀 TIERED EXECUTION
+
+| Tier       | When               | Action                       |
+| ---------- | ------------------ | ---------------------------- |
+| **TIER 1** | runSubagent EXISTS | Invoke sub-agent (MANDATORY) |
+| **TIER 2** | Tool MISSING       | EMBODY agent file (FALLBACK) |
+
+**❌ Anti-Lazy**: Never use TIER 2 when TIER 1 tool available.
+
+---
+
+## 📁 DELIVERABLES (Reporter chooses from user intent)
+
+| User intent | Reporter output |
+| ----------- | ---------------- |
+| **Create report** | `./reports/general/REPORT-FOCUS-{date}.md` or path user asked |
+| **Update existing** | **Edit** related files; do **not** create new report unless also asked |
+| **From template** | File(s) matching user format/template |
+
+| Agent      | When creating report                             |
+| ---------- | ------------------------------------------------- |
+| researcher | (optional) verification checklist                 |
+| scouter    | (optional) evidence output                        |
+| reporter   | Per table above — create / update / from template |
+
+All files in `./reports/` → English only.
+
+---
+
+## ⛔ INCREMENTAL EXECUTION (MANDATORY)
+
+One phase at a time, each phase independent: Phase 1 → then Phase 2 → … in one reply. No batching (load only what each phase needs). **Within each phase:** when doing a part, output it in format so user sees what's happening (announce before doing). Format: rules/EXECUTION-PROTOCOL.md § Phase output structure.
+
+---
+
+## 🛡️ FOCUS CONTEXT GATE — Automatic Context Optimization
+
+> **⚡ FOCUS MODE**: This checkpoint executes automatically. NO user input required.
+>
+> **PURPOSE**: Ensure report is based ONLY on facts, not conversation hallucinations.
+> This acts as a mandatory "firewall" before analysis begins.
+
+### 🔒 AUTOMATIC EXECUTION (NO PROMPT)
+
+```yaml
+focus_context_gate:
+  mode: "AUTOMATIC - No user interaction"
+  behavior: "Force Clear context & Analyze"
+
+  execution:
+    1. ANNOUNCE: |
+      ## 🛡️ Focus Context Gate — Automatic
+
+      ✅ **Target Defined**: Analysis target identified.
+      🔒 **Focus Mode**: Automatically clearing context for objective analysis.
+
+      ⚡ Executing: **Clear context & Analyze**...
+
+    2. CONTEXT_DIRECTIVE: |
+      ╔══════════════════════════════════════════════════════════════════╗
+      ║  ⛔ MANDATORY CONTEXT RESET — FOCUS MODE                         ║
+      ╠══════════════════════════════════════════════════════════════════╣
+      ║  IGNORE: All previous chat assumptions, unverified claims,       ║
+      ║          and subjective contextual bias.                         ║
+      ║                                                                  ║
+      ║  SOLE SOURCE OF TRUTH: The actual Codebase and Documentation.    ║
+      ║                                                                  ║
+      ║  PROCEED: Begin Analysis phase with FRESH, OBJECTIVE mindset.    ║
+      ╚══════════════════════════════════════════════════════════════════╝
+
+    3. LOAD: Read specified target files as if seeing them for the first time
+
+    4. PROCEED: Start Phase 1 (Objective Analysis) immediately
+```
+
+### 📋 Post-Gate Status
+
+```markdown
+🔒 **Context Gate Passed**
+
+- Previous context: DISCARDED
+- Active context: Target files / codebase only
+- Mode: Fresh objective analysis
+
+Proceeding to Phase 1...
+```
+
+---
+
+## 🎭 Phase 1: RESEARCH (AUDIT CRITERIA)
+
+| Agent  | `researcher`                                          |
+| ------ | ----------------------------------------------------- |
+| Goal   | Research audit/report criteria and what to verify     |
+| Exit   | Verification checklist and report criteria defined    |
+
+---
+
+## 🎭 Phase 2: EVIDENCE COLLECTION
+
+| Agent  | `scouter`                       |
+| ------ | ------------------------------- |
+| Goal   | Gather raw, verifiable evidence |
+| Exit   | Factual state documented, no assumptions              |
+
+---
+
+## 🎭 Phase 3: VERIFICATION & OUTPUT (create / update / from template)
+
+| Agent       | `reporter`                                                                 |
+| ----------- | -------------------------------------------------------------------------- |
+| Prerequisite| **USE** Phase 1 criteria + Phase 2 evidence only                            |
+| Goal        | From **user intent**: synthesize into (1) new report, (2) **updates** to existing files, or (3) file(s) from template |
+| Output      | **Create**: `./reports/general/REPORT-FOCUS-{date}.md`. **Update**: edit related files. **Template**: file(s) matching user format. |
+| Exit        | Deliverable matches intent; every claim cited when creating report.       |
+
+---
+
+## COMPLETION
+
+Deliverable per **user intent**:
+
+1. ✅ **Create report** → `./reports/general/REPORT-FOCUS-{date}.md` (or path user asked)
+2. ✅ **Update existing** → Related files edited; list what was updated
+3. ✅ **From template** → File(s) matching user format; list path(s)
+4. 🕵️ **Audit** → `/review:focus` (optional)

package/commands/report/hard.md

@@ -0,0 +1,112 @@
+---
+description: ⚡ Detailed Report — Comprehensive project analysis and documentation
+version: "1.0"
+category: documentation
+execution-mode: execute
+---
+
+# /report:hard — Comprehensive Project Report
+
+> **MISSION**: Generate detailed output for **any topic** — reports, doc updates, or template-based files.
+>
+> Use for: sprint reviews, technical docs, any-topic reports, updating existing files, or generating from user format/template.
+
+<task>$ARGUMENTS</task>
+
+---
+
+## 🛑 PRE-FLIGHT (DO FIRST — BLOCKS PHASE 1)
+
+**LOAD now** (in order; path `./rules/` or `~/.{TOOL}/skills/agent-assistant/rules/`):
+
+1. ORCHESTRATION-LAWS.md
+2. ADAPTIVE-EXECUTION.md
+3. EXECUTION-PROTOCOL.md
+
+**⛔ Do not run Phase 1 until all are loaded.** Follow **all** rules in those files; they override any conflicting instructions in this file.
+
+---
+
+## 🔀 TIERED EXECUTION
+
+| Tier       | When               | Action                       |
+| ---------- | ------------------ | ---------------------------- |
+| **TIER 1** | runSubagent EXISTS | Invoke sub-agent (MANDATORY) |
+| **TIER 2** | Tool MISSING       | EMBODY agent file (FALLBACK) |
+
+**❌ Anti-Lazy**: Never use TIER 2 when TIER 1 tool available.
+
+---
+
+## 📁 DELIVERABLES (Reporter chooses from user intent)
+
+| User intent | Reporter output |
+| ----------- | ---------------- |
+| **Create report** | New file: `./reports/general/REPORT-{type}-{date}.md` (or path user asks) |
+| **Update existing** | **Edit** related files (docs, README, etc.); do **not** create new report unless also asked |
+| **From template** | New file(s) matching user format/template (e.g. after scouting source) |
+
+| Agent      | Output (when creating)                          |
+| ---------- | ------------------------------------------------ |
+| researcher | `./reports/researchers/RESEARCH-{task}.md` (optional) |
+| scouter    | `./reports/scouts/SCOUT-{task}.md` (optional)    |
+| reporter   | Per table above — create report **or** update existing **or** generate from template |
+
+All files in `./reports/` → English only.
+
+---
+
+## ⛔ INCREMENTAL EXECUTION (MANDATORY)
+
+One phase at a time, each phase independent: Phase 1 → then Phase 2 → … in one reply. No batching (load only what each phase needs). **Within each phase:** when doing a part, output it in format so user sees what's happening (announce before doing). Format: rules/EXECUTION-PROTOCOL.md § Phase output structure.
+
+---
+
+## 🎭 Phase 1: RESEARCH
+
+| Agent  | `researcher`                                                |
+| ------ | ---------------------------------------------------------- |
+| Goal   | Research report scope, audience, and best practices for project/technical reports |
+| Output | `./reports/researchers/RESEARCH-{task}.md` (optional)       |
+| Exit   | Report scope and criteria defined, templates identified   |
+
+---
+
+## 🎭 Phase 2: DEEP SCAN
+
+| Agent  | `scouter`                         |
+| ------ | --------------------------------- |
+| Goal   | Full codebase structural analysis |
+| Output | `./reports/scouts/SCOUT-{task}.md` |
+| Exit   | Architecture and recent changes documented                 |
+
+---
+
+## 🎭 Phase 3: DATA SYNTHESIS
+
+| Agent       | `reporter`                                      |
+| ----------- | ------------------------------------------------ |
+| Prerequisite| **READ** RESEARCH + SCOUT outputs if present     |
+| Goal        | Aggregate data from Scouter, Plans, and History; identify discrepancies and milestones |
+| Exit        | Data synthesized, gaps and milestones identified |
+
+---
+
+## 🎭 Phase 4: OUTPUT (create / update / from template)
+
+| Agent | `reporter`                                                                 |
+| ----- | --------------------------------------------------------------------------- |
+| Goal  | From **user intent**: (1) create new report, (2) **update** existing files, or (3) generate from template/format |
+| Output| **Create**: `./reports/general/REPORT-{type}-{date}.md` or path user asked. **Update**: edit related files. **Template**: file(s) matching user format. |
+| Exit  | Deliverable matches intent — report file, updated docs, or template-based file(s). |
+
+---
+
+## COMPLETION
+
+Deliverable per **user intent**:
+
+1. ✅ **Create report** → `./reports/general/REPORT-{type}-{date}.md` (or path user asked)
+2. ✅ **Update existing** → Related files edited; list what was updated
+3. ✅ **From template** → File(s) matching user format; list path(s)
+4. 📢 **Share** → `/internal-comms` (optional)