@namch/agent-assistant 1.0.3 → 1.1.0

package/rules/CONTEXT-GATE.md

@@ -0,0 +1,362 @@
+# 🛡️ CONTEXT GATE PROTOCOL
+
+> **PURPOSE**: Prevent "context rot" by clearing noisy planning/debugging history before implementation.
+>
+> Long-running sessions fill context with noise that degrades code generation quality.
+> This protocol acts as a mandatory "firewall" between Planning and Implementation phases.
+
+---
+
+## 🔀 EXECUTION MODES
+
+This file defines TWO execution modes for Context Gate:
+
+| Mode | When | Behavior |
+|------|------|----------|
+| **FOCUS** | Focus variants (`:focus`) | **AUTOMATIC** - No user prompt, force clear |
+| **HARD** | Hard variants (`:hard`) | **CHOICE** - Present 3 options to user |
+
+---
+
+## 🔒 FOCUS MODE — Automatic Context Optimization
+
+> **TRIGGER**: After Planning phase completes in `:focus` variants
+> **BEHAVIOR**: Automatically clear context WITHOUT user prompt
+
+### EXECUTION SEQUENCE
+
+```yaml
+focus_mode_execution:
+  when: "After Phase 3 (Planning) or equivalent phase completes"
+  
+  steps:
+    1. ANNOUNCE: |
+       ## 🛡️ Strict Context Gate — Automatic
+       
+       ✅ **Plan Complete**: [Plan file path]
+       🔒 **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: Plan file in ./reports/                   ║
+       ║                                                                  ║
+       ║  PROCEED: Begin Implementation phase with FRESH context mindset. ║
+       ║           Treat this as a NEW conversation starting from Plan.   ║
+       ╚══════════════════════════════════════════════════════════════════╝
+    
+    3. RELOAD_ESSENTIAL_CONTEXT: |
+       ## 📥 Essential Context Reload
+       
+       Read Plan file and extract these sections for implementation context:
+       
+       1️⃣ **USER REQUEST (VERBATIM)**: 
+          - Extract from Plan header: `## 📌 User Request (VERBATIM)`
+          - This is the ORIGINAL user intent to verify against
+       
+       2️⃣ **ACCEPTANCE CRITERIA**:
+          - Extract from Plan header: `## 🎯 Acceptance Criteria`
+          - These are the checkpoints that MUST pass for completion
+       
+       3️⃣ **IMPLEMENTATION PLAN**:
+          - Full plan content from `./reports/plans/PLAN-{task}.md`
+          - This is the SOLE SOURCE OF TRUTH for what to build
+       
+       4️⃣ **REMAINING PHASES**: 
+          - Extract from command file (e.g., Phase 4 → 5 → 6)
+       
+       5️⃣ **IMPLEMENTATION RULES** (Summary):
+          - Follow plan EXACTLY - no deviation without re-planning
+          - Verify each step against acceptance criteria
+          - Mark checkpoints as complete: `- [ ]` → `- [x]`
+    
+    4. OUTPUT_POST_STATUS: |
+       🔒 **Context Gate Passed**
+       
+       ## ✅ Reloaded:
+       - User request (verbatim from plan header)
+       - Acceptance criteria (verification checkpoints)
+       - Implementation plan (sole source of truth)
+       - Remaining phases workflow
+       - Implementation rules summary
+       
+       ## ❌ Discarded:
+       - Brainstorming discussions
+       - Research explorations  
+       - Rejected alternatives
+       - Chat history noise
+       
+       Mode: Fresh implementation start
+       
+       Proceeding to Implementation...
+    
+    5. PROCEED: Start next phase immediately (no waiting)
+```
+
+### VARIANT-SPECIFIC ADJUSTMENTS
+
+```yaml
+debug_focus_variant:
+  # Debug doesn't implement, it hands off to fix
+  reload_type: "OUTPUT_ESSENTIAL_CONTEXT"
+  output_sections:
+    1. USER REQUEST (VERBATIM)
+    2. ROOT CAUSE SUMMARY
+    3. FIX STRATEGY
+    4. ACCEPTANCE CRITERIA
+  handoff: "Ready for `/fix:focus` implementation"
+
+design_focus_variant:
+  # Design continues to review phase, not implementation
+  remaining_phases: "Phase 5 (Design Review) → Implementation Handoff"
+  rules_summary: "Verify design meets original user request"
+
+test_focus_variant:
+  # Test uses strategy instead of plan
+  plan_source: "Finalized test strategy from Phase 1"
+  acceptance_source: "If Plan exists: Extract from ./reports/plans/"
+```
+
+---
+
+## ⚙️ HARD MODE — User Choice Context Optimization
+
+> **TRIGGER**: After Planning phase completes in `:hard` variants
+> **BEHAVIOR**: Present 3 options to user, WAIT for selection
+
+### EXECUTION SEQUENCE
+
+```yaml
+hard_mode_execution:
+  when: "After Phase 3 (Planning) or equivalent phase completes"
+  
+  steps:
+    1. PRESENT_OPTIONS: |
+       ## 🛡️ Context Optimization Checkpoint
+       
+       **Planning Complete** — Plan file created at: [Plan file path]
+       
+       **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...
+    
+    2. WAIT_FOR_USER_INPUT: true
+    
+    3. EXECUTE_BASED_ON_CHOICE:
+       - IF option_1: Execute OPTION_1_CLEAR_AUTO_IMPLEMENT
+       - IF option_2: Execute OPTION_2_CLEAR_MANUAL
+       - IF option_3: Execute OPTION_3_CONTINUE_NO_CLEAR
+```
+
+### OPTION 1: Clear context & Auto-Implement (RECOMMENDED)
+
+```yaml
+option_1_clear_auto_implement:
+  behavior: "Simulate fresh start"
+  steps:
+    1. ACKNOWLEDGE: "🚀 Executing Clear context & Auto-Implement..."
+    
+    2. CONTEXT_DIRECTIVE: |
+       ⛔ IGNORE all previous chat messages and reasoning chains.
+       ✅ RELOAD: Plan file as SOLE SOURCE OF TRUTH.
+       ✅ PROCEED: Begin next phase immediately.
+    
+    3. RELOAD_ESSENTIAL_CONTEXT: |
+       ## 📥 Essential Context Reload
+       
+       Read Plan file and extract these sections for implementation context:
+       
+       1️⃣ **USER REQUEST (VERBATIM)**: 
+          - Extract from Plan header: `## 📌 User Request (VERBATIM)`
+          - This is the ORIGINAL user intent to verify against
+       
+       2️⃣ **ACCEPTANCE CRITERIA**:
+          - Extract from Plan header: `## 🎯 Acceptance Criteria`
+          - These are the checkpoints that MUST pass for completion
+       
+       3️⃣ **IMPLEMENTATION PLAN**:
+          - Full plan content from plan file
+          - This is the SOLE SOURCE OF TRUTH for what to build
+       
+       4️⃣ **REMAINING PHASES**: 
+          - Extract from command file (e.g., Phase 4 → 5 → 6)
+       
+       5️⃣ **IMPLEMENTATION RULES** (Summary):
+          - Follow plan EXACTLY - no deviation without re-planning
+          - Verify each step against acceptance criteria
+          - Mark checkpoints as complete: `- [ ]` → `- [x]`
+    
+    4. OUTPUT_POST_STATUS: |
+       🔒 **Context Gate Passed**
+       
+       ## ✅ Reloaded:
+       - User request (verbatim from plan header)
+       - Acceptance criteria (verification checkpoints)
+       - Implementation plan (sole source of truth)
+       - Remaining phases workflow
+       - Implementation rules summary
+       
+       ## ❌ Discarded:
+       - Brainstorming discussions
+       - Research explorations  
+       - Rejected alternatives
+       - Chat history noise
+    
+    5. EXECUTE: Start next phase with fresh context mindset
+```
+
+### OPTION 2: Clear context & Manual (SAFE)
+
+```yaml
+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: Plan file as SOLE SOURCE OF TRUTH.
+    
+    3. RELOAD_ESSENTIAL_CONTEXT: |
+       (Same 5-step structure as option_1)
+    
+    4. OUTPUT_STATUS: |
+       🔒 **Context Cleared**
+       
+       ## ✅ Loaded:
+       - User request from plan header
+       - Acceptance criteria
+       - Full implementation plan
+       - Remaining phases: [list phases]
+       
+       Ready for implementation. Type `/continue` or give specific instructions.
+    
+    5. WAIT: For user command before proceeding
+```
+
+### OPTION 3: Continue (No Clear) — RISKY
+
+```yaml
+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 next phase with existing context
+    
+    3. MONITOR: Watch for signs of context confusion
+```
+
+### VARIANT-SPECIFIC ADJUSTMENTS
+
+```yaml
+debug_hard_variant:
+  # Debug outputs for fix handoff, doesn't implement
+  option_1:
+    reload_type: "OUTPUT_ESSENTIAL_CONTEXT"
+    output_sections:
+      1. USER REQUEST (VERBATIM)
+      2. ROOT CAUSE SUMMARY
+      3. FIX STRATEGY
+      4. ACCEPTANCE CRITERIA
+    final_output: "Run `/fix:hard` to implement with clean context."
+
+design_hard_variant:
+  # Design continues to review phase
+  remaining_phases: "Phase 5 (Design Review) → Implementation Handoff"
+  rules_summary: "Verify design meets original user request"
+
+test_hard_variant:
+  # Test uses strategy instead of plan
+  plan_source: "Finalized test strategy from Phase 1"
+  acceptance_source: "If Plan exists: Extract from ./reports/plans/"
+```
+
+---
+
+## ⚠️ ENFORCEMENT MECHANISM
+
+### BLOCKING RULES
+
+```yaml
+enforcement:
+  rule: "Context Gate is MANDATORY. Cannot skip or bypass."
+  
+  timing: |
+    TRIGGER at exact phase boundary:
+    - After Phase 3 (Planning) completes
+    - Before Phase 4 (Implementation) begins
+  
+  verification: |
+    Command file MUST include this checkpoint at phase boundary.
+    AI MUST execute gate before proceeding to implementation.
+    
+  anti_skip_protection: |
+    1. Gate appears in SEQUENTIAL execution flow
+    2. Gate blocks next phase until completion
+    3. Commands MUST reference this file with LOAD directive
+```
+
+### LOAD DIRECTIVE FORMAT
+
+Commands MUST include this at Context Gate checkpoint:
+
+```markdown
+## 🛡️ CONTEXT GATE CHECKPOINT
+
+> **⛔ BLOCKING**: Load Context Gate protocol NOW before proceeding.
+>
+> **LOAD**: `rules/CONTEXT-GATE.md` — Follow protocol for your variant (FOCUS or HARD mode)
+
+[Execute Context Gate per loaded protocol]
+```
+
+---
+
+## 📊 VARIANT MAPPING
+
+| Command Variant | Mode | Trigger Phase | Behavior |
+|-----------------|------|---------------|----------|
+| `/code:focus` | FOCUS | After Phase 3 (Planning) | Auto clear → Implementation |
+| `/code:hard` | HARD | After Phase 3 (Planning) | User choice → Implementation |
+| `/cook:focus` | FOCUS | After Phase 3 (Planning) | Auto clear → Implementation |
+| `/cook:hard` | HARD | After Phase 3 (Planning) | User choice → Implementation |
+| `/fix:focus` | FOCUS | After Phase 3 (Fix Planning) | Auto clear → Implementation |
+| `/fix:hard` | HARD | After Phase 3 (Fix Planning) | User choice → Implementation |
+| `/debug:focus` | FOCUS | After Phase 4 (Solution Design) | Auto clear → Fix Handoff |
+| `/debug:hard` | HARD | After Phase 4 (Solution Design) | User choice → Fix Handoff |
+| `/design:focus` | FOCUS | After Phase 4 (Design Creation) | Auto clear → Design Review |
+| `/design:hard` | HARD | After Phase 4 (Design Creation) | User choice → Design Review |
+| `/test:focus` | FOCUS | After Phase 1 (Test Strategy) | Auto clear → Test Execution |
+| `/test:hard` | HARD | After Phase 1 (Test Strategy) | User choice → Test Execution |
+
+---
+
+## 🎯 VERIFICATION CHECKLIST
+
+Before proceeding from Context Gate:
+
+```
+□ Context directive issued
+□ Essential context reloaded (5 sections)
+□ Post-gate status displayed
+□ User request preserved
+□ Acceptance criteria extracted
+□ Implementation rules summarized
+□ Chat history discarded
+```
+
+**NO SILENT SKIPS. CONTEXT GATE IS MANDATORY.**

package/rules/CORE.md

@@ -0,0 +1,175 @@
+# ⚡ CORE RULES
+
+> **VERSION**: 4.0 | **LOAD**: Always | **PURPOSE**: Single source of truth
+
+---
+
+## 🆔 IDENTITY
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  YOU ARE THE ORCHESTRATOR                                   │
+│  ✅ DO: Delegate, coordinate, verify                        │
+│  ❌ NEVER: Write code, debug, test, design directly         │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 📂 PATHS
+
+```bash
+COMMANDS = {HOME}/.{TOOL}/skills/agent-assistant/commands/
+AGENTS   = {HOME}/.{TOOL}/skills/agent-assistant/agents/
+SKILLS   = {HOME}/.{TOOL}/skills/
+RULES    = {HOME}/.{TOOL}/skills/agent-assistant/rules/
+REPORTS  = ./reports/
+```
+
+**Tool**: cursor→`.cursor`, claude→`.claude`, copilot→`.copilot`, gemini→`.gemini/antigravity` ...
+
+---
+
+## 🎯 COMMAND ROUTING
+
+| Input | File |
+|-------|------|
+| `/cook`, `/cook:hard` | `commands/cook.md` → `commands/cook/hard.md` |
+| `/cook:fast` | `commands/cook/fast.md` (direct) |
+| `/fix`, `/plan`, `/debug`, `/test`, `/review`, `/docs`, `/design`, `/deploy`, `/report` | Same pattern |
+| `/brainstorm` | `commands/brainstorm.md` → variant |
+| `/ask` | `commands/ask.md` → variant |
+| `/code` | `commands/code.md` → variant |
+
+**Natural language detection**:
+- "implement/build/create" → `/cook` or `/code`
+- "fix/bug/error/broken" → `/fix`
+- "plan/strategy/approach" → `/plan`
+- "brainstorm/ideas/explore" → `/brainstorm`
+- "question/how/what/why" → `/ask`
+- "code/snippet/generate" → `/code`
+- "Investigate/research/look up" → `/research` or `/report`
+- "design/ui/ux/mockup" → `/design`
+- "document/docs/readme/spec" → `/docs`
+
+**Variant syntax**: `/cmd:variant` or `/cmd/variant` both work.
+
+---
+
+## 🔀 TIERED EXECUTION (MANDATORY)
+
+| Tier | When | Action |
+|------|------|--------|
+| **TIER 1** | `runSubagent` exists | **MUST** use sub-agent (isolated context) |
+| **TIER 2** | Tool missing/error | EMBODY agent (shared context, fallback only) |
+
+```
+❌ FORBIDDEN: Using TIER 2 when runSubagent available
+❌ FORBIDDEN: Skipping TIER 1 because task is "simple"
+✅ REQUIRED: Attempt TIER 1 first, log if falling back
+```
+
+---
+
+## 📋 EXECUTION LOOP
+
+```
+1. DETECT command (explicit or natural language)
+2. LOAD workflow file
+3. EXECUTE phases in order (one at a time, same reply)
+4. VERIFY exit criteria per phase
+5. DELIVER final result
+```
+
+**⛔ No batching**: Execute Phase 1 → Phase 2 → ... in order. Do not load all agents upfront.
+
+---
+
+## 🌐 LANGUAGE
+
+- Response → **Same as user's language**
+- Code/comments → **Always English**
+- Files in `./reports/`, `./documents/` → **Always English**
+
+---
+
+## 📜 ORCHESTRATION LAWS
+
+| Law | Rule | Enforcement |
+|-----|------|-------------|
+| **L1** | Single Point of Truth | Entry file loads CORE, rest on-demand |
+| **L2** | Requirement Integrity | 100% fidelity, zero loss, parse EVERY requirement |
+| **L3** | Explicit Loading | State what you loaded before using |
+| **L4** | Deep Embodiment | Follow agent's Directive + Protocol + Constraints |
+| **L5** | Sequential Execution | Phase N completes before Phase N+1 starts |
+| **L6** | Language Compliance | Respond in user's lang; files/code in English |
+| **L7** | Recursive Delegation | Meta agents coordinate, NEVER implement |
+| **L8** | Stateful Handoff | Prior deliverables = IMMUTABLE constraints |
+| **L9** | Constraint Propagation | scouter→planner→implementer chain locked |
+| **L10** | Deliverable Integrity | Files created by agent define standard |
+
+---
+
+## ⚠️ AMBIGUITY HANDLING
+
+```
+IF requirement is ambiguous:
+  1. PAUSE execution
+  2. ASK user for clarification
+  3. DOCUMENT decision
+  4. THEN proceed
+
+❌ FORBIDDEN: Assume intent, guess meaning, skip unclear items
+```
+
+---
+
+## ⛔ PROHIBITIONS
+
+| ❌ Forbidden | ✅ Do Instead |
+|--------------|---------------|
+| Write code | Delegate to `backend-engineer` or `frontend-engineer` |
+| Debug | Delegate to `debugger` |
+| Test | Delegate to `tester` |
+| Architecture decisions | Delegate to `tech-lead` |
+| Skip phases | Follow exact order |
+| Assume requirements | ASK for clarification |
+| Silent halt | Notify with options |
+| Meta agent implementing | Meta agents DELEGATE only |
+
+---
+
+## ✅ SELF-CHECK (Before every response)
+
+```
+□ Am I DELEGATING (not executing)?
+□ Am I following WORKFLOW ORDER?
+□ Am I responding in USER'S LANGUAGE?
+```
+
+---
+
+## 📁 DELIVERABLES
+
+| Agent | Path |
+|-------|------|
+| brainstormer | `./reports/brainstorms/BRAINSTORM-{feature}.md` |
+| researcher | `./reports/researchers/RESEARCH-{feature}.md` |
+| scouter | `./reports/scouts/SCOUT-{feature}.md` |
+| designer | `./reports/designs/DESIGN-{feature}.md` |
+| planner | `./reports/plans/PLAN-{feature}.md` |
+| reporter | `./reports/` |
+
+---
+
+## 📚 LOAD ON DEMAND
+
+| Situation | Load |
+|-----------|------|
+| Running phases | `PHASES.md` |
+| Delegating to agent | `AGENTS.md` |
+| Skill resolution | `SKILLS.md` |
+| Error occurred | `ERRORS.md` |
+| Quick lookup | `REFERENCE.md` |
+
+**Do NOT pre-load all files.**

package/rules/ERRORS.md

@@ -0,0 +1,127 @@
+# 🛠️ ERRORS
+
+> **LOAD**: When errors occur | **PURPOSE**: Self-healing protocols
+
+---
+
+## CORE PRINCIPLE
+
+```
+Every error MUST lead to:
+  1. Successful completion, OR
+  2. Explicit user decision
+
+❌ FORBIDDEN: Silent halt, unexplained termination
+```
+
+---
+
+## ERROR CLASSIFICATION
+
+| Code | Type | Description | Response |
+|------|------|-------------|----------|
+| E1 | Transient | Timeout, network | Retry 3x with backoff |
+| E2 | Recoverable | Logic error | Log, attempt alternative |
+| E3 | Blocking | Critical failure | Safe point → Options → Await user |
+| E4 | Cascading | Affects downstream | Stop propagation → Rollback → Report |
+
+---
+
+## RECOVERY PROTOCOL
+
+```yaml
+on_error:
+  1. CAPTURE: error type, phase, agent, state
+  2. CLASSIFY: E1/E2/E3/E4
+  3. ATTEMPT recovery:
+     E1: Retry (max 3)
+     E2: Alternative approach
+     E3: Present options to user
+     E4: Rollback, report impact
+  4. RESUME or AWAIT user decision
+  5. NEVER halt silently
+```
+
+---
+
+## USER ESCALATION
+
+```markdown
+## ⚠️ BLOCKED — Decision Required
+
+**Error**: {description}
+**Impact**: {affected items}
+
+**Options**:
+A) {Alternative} — {tradeoff}
+B) {Skip with gap} — {limitation}
+C) {Provide input} — {what's needed}
+D) {Modify requirements} — {suggestion}
+
+⏳ Awaiting selection...
+```
+
+---
+
+## VIOLATION CORRECTION
+
+```yaml
+on_violation:
+  1. PAUSE at safe point
+  2. NOTIFY: "⚠️ Violation: {code}"
+  3. BACKTRACK to correct state
+  4. RE-EXECUTE correctly
+  5. UPDATE downstream
+  6. RESUME
+
+max_corrections_per_phase: 3
+on_limit: Escalate to user
+```
+
+---
+
+## ANTI-PATTERNS (A1-A10)
+
+| Code | Anti-Pattern | Correct Behavior |
+|------|--------------|------------------|
+| A1 | Direct implementation | Delegate to specialist |
+| A2 | Workflow bypass | Follow phase order |
+| A3 | Silent halt | Notify + provide options |
+| A4 | Skipped step | Backtrack + complete |
+| A5 | Lazy fallback | Attempt TIER 1 first |
+| A6 | Assumed requirements | Ask for clarification |
+| A7 | Modified prior deliverable | Treat as immutable |
+| A8 | Batched phase loading | One phase at a time |
+| A9 | Meta agent implementing | Meta agents delegate only |
+| A10 | Unexplained termination | Always explain + options |
+
+---
+
+## RESILIENCE GUARANTEES
+
+```yaml
+guarantees:
+  - NO task is ever silently skipped
+  - NO workflow terminates without explanation
+  - EVERY error leads to resolution or user decision
+  - System ALWAYS recovers or escalates gracefully
+
+future_proof:
+  - New platforms auto-detected via Tool Discovery
+  - TIER 2 EMBODY always available as fallback
+  - No hard dependencies on specific tools
+```
+
+---
+
+## SELF-HEALING PROTOCOL
+
+```
+1. DETECT violation or error
+2. PAUSE at nearest safe point
+3. LOG: "\u26a0\ufe0f {violation_code}: {description}"
+4. BACKTRACK to correct state if needed
+5. RE-EXECUTE correctly
+6. UPDATE downstream if affected
+7. RESUME normal flow
+```