@namch/agent-assistant 1.0.2 → 1.0.4

package/commands/code/focus.md

@@ -0,0 +1,343 @@
+---
+description: 🔒 Focused Development — Full development cycle with enforced context optimization
+version: "1.0"
+category: engineering
+execution-mode: execute
+---
+
+# /code:focus — Focus Development Cycle
+
+> **MISSION**: Execute complete development workflow with **enforced context optimization**.
+>
+> This variant automatically clears context before implementation—no user prompt required.
+> Use when you want guaranteed clean implementation 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.
+
+---
+
+## 📌 PLAN-ALREADY-PROVIDED: SKIP REDUNDANT PHASES
+
+**Before starting Phase 1**, resolve whether the user is **coding from an existing plan**. If yes, **do not** run research, scout, or brainstorm.
+
+### Detection
+
+- User message references a plan: e.g. `@plan`, `@PLAN-...`, path like `./reports/plans/PLAN-{name}.md`, or phrases like "according to plan", "follow the plan", "code from plan", "implement per plan".
+- Or a plan file already exists for this task at `./reports/plans/PLAN-{task}.md` (derive `{task}` from `$ARGUMENTS` or from the referenced file name).
+
+### Resolution
+
+1. **CHECK**: Does a valid plan file exist (user-provided path or `./reports/plans/PLAN-{task}.md`)?
+2. **IF YES**:
+   - **SKIP** Phase 1 (Requirements/Brainstorm), Phase 2 (Scout), Phase 3 (Planning).
+   - **ANNOUNCE**: "✅ Plan provided/found — skipping research, scout, and planning. Proceeding to implementation."
+   - **GO TO**: Strict Context Gate (automatic) → then Phase 4 (Implementation) → Phase 5 (Testing) → Phase 6 (Review).
+3. **IF NO**: Run phases in order: Phase 1 → 2 → 3 → Context Gate → 4 → 5 → 6.
+
+---
+
+## 🔀 TIERED EXECUTION PROTOCOL (MANDATORY)
+
+> **Reference**: `{RULES_PATH}/ADAPTIVE-EXECUTION.md`
+
+```yaml
+tiered_execution:
+  principle: "Sub-agent FIRST (Tier 1). EMBODY ONLY on system failure (Tier 2)."
+
+  tool_discovery: "Check runSubagent availability BEFORE first delegation"
+
+  for_each_phase:
+    TIER_1_MANDATORY: "IF tool exists → MUST use SUB_AGENT_DELEGATION"
+    TIER_2_FALLBACK: "ONLY on system error—NOT complexity/preference/speed"
+
+  anti_lazy_fallback:
+    - ❌ NEVER use Tier 2 when Tier 1 tool is available
+    - ✅ ALWAYS attempt Tier 1 first when tool exists
+    - ✅ ALWAYS log justification for Tier 2 fallback
+```
+
+---
+
+## ⚠️ CRITICAL: PHASE CONTINUITY RULES
+
+```yaml
+phase_continuity:
+  rule: "Each phase MUST reference and follow outputs from prior phases"
+
+  check_for_files:
+    - "./reports/brainstorms/BRAINSTORM-{task}.md"
+    - "./reports/scouts/SCOUT-{task}.md"
+    - "./reports/plans/PLAN-{task}.md"
+
+  enforcement:
+    - Phase 3 (Planning) MUST incorporate Scout findings
+    - Phase 4 (Implementation) MUST follow the Plan file exactly
+    - Phase 5 (Testing) MUST verify all plan checkpoints
+    - If prior phase file missing → Agent MUST create it
+```
+
+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).
+
+---
+
+## 🎭 Phase 1: REQUIREMENTS ANALYSIS
+
+| Attribute   | Value                             |
+| ----------- | --------------------------------- |
+| **Agent**   | `brainstormer`                    |
+| **Goal**    | Clarify requirements if ambiguous |
+| **Trigger** | If requirements unclear           |
+
+### ⚡ TIERED EXECUTION
+
+**TIER 1 (MANDATORY when tool exists):**
+
+> Invoke runSubagent for `brainstormer`. Context: ISOLATED.
+
+**TIER 2 (FALLBACK on system error only):**
+
+> Load `{AGENTS_PATH}/brainstormer.md`
+> EMBODY [brainstormer] — Requires logged system error justification.
+
+**Exit Criteria:**
+
+- [ ] Requirements clear
+- [ ] Scope defined
+- [ ] Acceptance criteria established
+- [ ] **METHODOLOGY CHECK**: Output aligns with `brainstormer` Thinking Protocol
+
+---
+
+## 🎭 Phase 2: CODEBASE ANALYSIS
+
+| Attribute | Value                         |
+| --------- | ----------------------------- |
+| **Agent** | `scouter`                     |
+| **Goal**  | Full codebase context mapping |
+
+### ⚡ TIERED EXECUTION
+
+**TIER 1 (MANDATORY when tool exists):**
+
+> Invoke runSubagent for `scouter`. Context: ISOLATED.
+
+**TIER 2 (FALLBACK on system error only):**
+
+> Load `{AGENTS_PATH}/scouter.md`
+> EMBODY [scouter] — Requires logged system error justification.
+
+**Exit Criteria:**
+
+- [ ] Architecture understood
+- [ ] Patterns documented
+- [ ] Integration points identified
+- [ ] **METHODOLOGY CHECK**: Output aligns with `scouter` Thinking Protocol
+
+---
+
+## 🎭 Phase 3: IMPLEMENTATION PLANNING
+
+| Attribute | Value                      |
+| --------- | -------------------------- |
+| **Agent** | `planner`                  |
+| **Goal**  | Create implementation plan |
+
+### ⚡ TIERED EXECUTION
+
+**TIER 1 (MANDATORY when tool exists):**
+
+> Invoke runSubagent for `planner`. Context: ISOLATED.
+
+**TIER 2 (FALLBACK on system error only):**
+
+> Load `{AGENTS_PATH}/planner.md`
+> EMBODY [planner] — Requires logged system error justification.
+
+**Exit Criteria:**
+
+- [ ] Plan created
+- [ ] Steps defined
+- [ ] Risks identified
+- [ ] **METHODOLOGY CHECK**: Output aligns with `planner` Thinking Protocol
+
+---
+
+## 🛡️ STRICT CONTEXT GATE — Automatic Context Optimization
+
+> **⚡ FOCUS MODE**: This checkpoint executes automatically. NO user input required.
+>
+> **PURPOSE**: Prevent "context rot" by forcibly clearing noisy planning history.
+> This acts as a mandatory "firewall" between Planning and Implementation phases.
+
+### 🔒 AUTOMATIC EXECUTION (NO PROMPT)
+
+```yaml
+strict_context_gate:
+  mode: "AUTOMATIC - No user interaction"
+  behavior: "Force Clear context & Auto-Implement"
+
+  execution:
+    1. ANNOUNCE: |
+      ## 🛡️ Strict Context Gate — Automatic
+
+      ✅ **Plan Complete**: `./reports/plans/PLAN-{task}.md`
+      🔒 **Focus Mode**: Automatically clearing context for implementation.
+
+      ⚡ Executing: **Clear context & Auto-Implement**...
+
+    2. CONTEXT_DIRECTIVE: |
+      ╔══════════════════════════════════════════════════════════════════╗
+      ║  ⛔ MANDATORY CONTEXT RESET — FOCUS MODE                        ║
+      ╠══════════════════════════════════════════════════════════════════╣
+      ║  IGNORE: All previous chat messages, reasoning chains,           ║
+      ║          brainstorming discussions, research explorations,       ║
+      ║          rejected alternatives, and intermediate thinking.       ║
+      ║                                                                  ║
+      ║  SOLE SOURCE OF TRUTH: `./reports/plans/PLAN-{task}.md`          ║
+      ║                                                                  ║
+      ║  PROCEED: Begin Implementation phase with FRESH context mindset. ║
+      ║           Treat this as a NEW conversation starting from Plan.   ║
+      ╚══════════════════════════════════════════════════════════════════╝
+
+    3. LOAD: Read Plan file completely as if seeing it for the first time
+
+    4. PROCEED: Start Phase 4 (Implementation) immediately
+```
+
+### 📋 Post-Gate Status
+
+```markdown
+🔒 **Context Gate Passed**
+
+- Previous context: DISCARDED
+- Active context: Plan file only
+- Mode: Fresh implementation start
+
+Proceeding to Implementation...
+```
+
+---
+
+## 🎭 Phase 4: IMPLEMENTATION
+
+| Attribute | Value                               |
+| --------- | ----------------------------------- |
+| **Agent** | `tech-lead` → routes to specialists |
+| **Goal**  | Execute plan with specialist agents |
+
+### ⚡ TIERED EXECUTION
+
+**TIER 1 (MANDATORY when tool exists):**
+
+> Invoke runSubagent for `tech-lead`. Context: ISOLATED.
+> Tech-lead will spawn specialist subagents as needed.
+
+**TIER 2 (FALLBACK on system error only):**
+
+> Load `{AGENTS_PATH}/tech-lead.md`
+> EMBODY [tech-lead] — Requires logged system error justification.
+> Then recursively EMBODY specialists as needed.
+
+### ⚡ FOCUS ADHERENCE DIRECTIVE
+
+```
+1. READ plan completely BEFORE any implementation
+2. FOR EACH plan step:
+   a. Implement EXACTLY as specified
+   b. Mark complete: `- [ ]` → `- [x]`
+3. IF deviation needed:
+   a. STOP
+   b. REQUEST Re-Planning
+   c. DO NOT proceed with own interpretation
+```
+
+**Exit Criteria:**
+
+- [ ] All plan steps executed
+- [ ] Code complete
+- [ ] Documentation updated
+- [ ] **Each plan step has corresponding implementation**
+- [ ] **No unauthorized deviations**
+- [ ] **METHODOLOGY CHECK**: Output aligns with `tech-lead` Thinking Protocol
+
+---
+
+## 🎭 Phase 5: TESTING
+
+| Attribute | Value                 |
+| --------- | --------------------- |
+| **Agent** | `tester`              |
+| **Goal**  | Comprehensive testing |
+
+### ⚡ TIERED EXECUTION
+
+**TIER 1 (MANDATORY when tool exists):**
+
+> Invoke runSubagent for `tester`. Context: ISOLATED.
+
+**TIER 2 (FALLBACK on system error only):**
+
+> Load `{AGENTS_PATH}/tester.md`
+> EMBODY [tester] — Requires logged system error justification.
+
+**Exit Criteria:**
+
+- [ ] Tests written
+- [ ] All tests pass
+- [ ] Coverage adequate
+- [ ] **METHODOLOGY CHECK**: Output aligns with `tester` Thinking Protocol
+
+---
+
+## 🎭 Phase 6: REVIEW
+
+| Attribute | Value               |
+| --------- | ------------------- |
+| **Agent** | `reviewer`          |
+| **Goal**  | Code quality review |
+
+### ⚡ TIERED EXECUTION
+
+**TIER 1 (MANDATORY when tool exists):**
+
+> Invoke runSubagent for `reviewer`. Context: ISOLATED.
+
+**TIER 2 (FALLBACK on system error only):**
+
+> Load `{AGENTS_PATH}/reviewer.md`
+> EMBODY [reviewer] — Requires logged system error justification.
+
+**Exit Criteria:**
+
+- [ ] Code reviewed
+- [ ] Standards met
+- [ ] No blocking issues
+- [ ] **METHODOLOGY CHECK**: Output aligns with `reviewer` Thinking Protocol
+
+---
+
+## COMPLETION
+
+Present implementation report with:
+
+1. ✅ **Done** — Feature complete (Focus Mode)
+2. 🚀 **Deploy** → `/deploy:preview`
+3. 📝 **Docs** → `/docs:core`

package/commands/code/hard.md

@@ -25,6 +25,26 @@ execution-mode: execute
 
 ---
 
+## 📌 PLAN-ALREADY-PROVIDED: SKIP REDUNDANT PHASES
+
+**Before starting Phase 1**, resolve whether the user is **coding from an existing plan**. If yes, **do not** run research, scout, or brainstorm.
+
+### Detection
+
+- User message references a plan: e.g. `@plan`, `@PLAN-...`, path like `./reports/plans/PLAN-{name}.md`, or phrases like "according to plan", "follow the plan", "code from plan", "implement per plan".
+- Or a plan file already exists for this task at `./reports/plans/PLAN-{task}.md` (derive `{task}` from `$ARGUMENTS` or from the referenced file name).
+
+### Resolution
+
+1. **CHECK**: Does a valid plan file exist (user-provided path or `./reports/plans/PLAN-{task}.md`)?
+2. **IF YES**:
+   - **SKIP** Phase 1 (Requirements/Brainstorm), Phase 2 (Scout), Phase 3 (Planning).
+   - **ANNOUNCE**: "✅ Plan provided/found — skipping research, scout, and planning. Proceeding to implementation."
+   - **GO TO**: Verification Checkpoint (Context Optimization) → then Phase 4 (Implementation) → Phase 5 (Testing) → Phase 6 (Review).
+3. **IF NO**: Run phases in order: Phase 1 → 2 → 3 → Checkpoint → 4 → 5 → 6.
+
+---
+
 ## 🔀 TIERED EXECUTION PROTOCOL (MANDATORY)
 
 > **Reference**: `{RULES_PATH}/ADAPTIVE-EXECUTION.md`
@@ -213,6 +233,65 @@ One phase at a time, each phase independent: Phase 1 → then Phase 2 → … in
 
 ---
 
+## 🛡️ VERIFICATION CHECKPOINT — Context Optimization
+
+> **PURPOSE**: Prevent "context rot" by clearing noisy planning history before implementation.
+> 
+> Long-running planning sessions fill context with noise that degrades code generation quality.
+> This checkpoint acts as a "firewall" between Planning and Implementation phases.
+
+### ⚡ OPTIONS (Present to User)
+
+```markdown
+## 🛡️ Context Optimization Checkpoint
+
+**Planning Complete** — Plan file created at: `./reports/plans/PLAN-{task}.md`
+
+**Choose how to proceed with implementation:**
+
+| Option | Action | Description |
+|--------|--------|-------------|
+| **1. 🚀 Clear context & Auto-Implement** | `RECOMMENDED` | Fresh start: Reload Plan file, ignore chat history, begin implementation immediately |
+| **2. ⏸️ Clear context & Manual** | `SAFE` | Clear context, reload Plan, pause for your command before coding |
+| **3. ⚠️ Continue (No Clear)** | `RISKY` | Proceed with full history attached (may cause hallucination) |
+
+⏳ Awaiting selection...
+```
+
+### 🔄 EXECUTION BEHAVIOR
+
+```yaml
+option_1_clear_auto_implement:
+  behavior: "RECOMMENDED - Simulate fresh start"
+  steps:
+    1. ACKNOWLEDGE: "🚀 Executing Clear context & Auto-Implement..."
+    2. CONTEXT_DIRECTIVE: |
+       ⛔ IGNORE all previous chat messages and reasoning chains.
+       ✅ RELOAD: `./reports/plans/PLAN-{task}.md` as SOLE SOURCE OF TRUTH.
+       ✅ PROCEED: Begin Phase 4 (Implementation) immediately.
+    3. LOAD: Read Plan file completely
+    4. EXECUTE: Start Implementation phase with fresh context mindset
+
+option_2_clear_manual:
+  behavior: "Clear and wait for explicit command"
+  steps:
+    1. ACKNOWLEDGE: "⏸️ Context cleared. Plan reloaded."
+    2. CONTEXT_DIRECTIVE: |
+       ⛔ IGNORE all previous chat messages and reasoning chains.
+       ✅ RELOAD: `./reports/plans/PLAN-{task}.md` as SOLE SOURCE OF TRUTH.
+    3. OUTPUT: "Ready for implementation. Type `/continue` or give specific instructions."
+    4. WAIT: For user command before proceeding
+
+option_3_continue_no_clear:
+  behavior: "Proceed with caution - context rot risk"
+  steps:
+    1. WARN: "⚠️ Continuing with full history. Higher hallucination risk."
+    2. PROCEED: Continue to Phase 4 with existing context
+    3. MONITOR: Watch for signs of context confusion
+```
+
+---
+
 ## 🎭 Phase 4: IMPLEMENTATION
 
 | Attribute | Value                               |

package/commands/code.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 workflow, and execute it.
 
@@ -27,12 +28,18 @@ execution-mode: router
 ## ROUTING LOGIC
 
 ```
+IF user references an existing plan (@plan, @PLAN-..., path to PLAN-*.md, or "according to plan" / "follow the plan"):
+  → Route to /code:hard or /code:focus (workflow will SKIP research, scout, brainstorm and go straight to implementation)
+
 IF task is simple (clear requirements, single file):
   → Route to /code:fast
 
 IF task is complex (multi-file, research needed):
   → Route to /code:hard
 
+IF task is complex AND context optimization is critical:
+  → Route to /code:focus
+
 IF unsure:
   → Default to /code:fast (escalate if needed)
 ```
@@ -41,10 +48,11 @@ IF unsure:
 
 ## AVAILABLE ROUTES
 
-| Route        | When to Use                              |
-| ------------ | ---------------------------------------- |
-| `/code:fast` | Quick implementation, clear requirements |
-| `/code:hard` | Complex features, multi-file changes     |
+| Route         | When to Use                                             |
+| ------------- | ------------------------------------------------------- |
+| `/code:fast`  | Quick implementation, clear requirements                |
+| `/code:hard`  | Complex features, multi-file changes                    |
+| `/code:focus` | Complex features with **enforced context optimization** |
 
 ---
 
@@ -59,6 +67,7 @@ IF unsure:
 
 1. ⚡ **Fast** → `/code:fast` — Quick implementation
 2. ⚡⚡⚡ **Hard** → `/code:hard` — Full development cycle
+3. 🎯 **Focus** → `/code:focus` — Full cycle with **automatic context clearing** (prevents hallucination)
 
 ⏳ Awaiting selection...
 ```