codingbuddy-rules 5.2.0 → 5.3.0

package/.ai-rules/adapters/claude-code.md

@@ -529,67 +529,57 @@ When `parse_mode` returns `dispatch="auto"` or `dispatchReady` with specialist a
 
 **Rule:** Every listed specialist MUST be dispatched. Skipping any specialist is a protocol violation.
 
-#### Teams-Based Specialist Dispatch (Preferred)
+#### Red Flags
 
-Teams are preferred over the Agent tool for specialist dispatch because they enable structured coordination and message-based reporting:
+| Thought | Reality |
+|---------|---------|
+| "I can handle this analysis myself" | Specialists have domain expertise. Dispatch them. |
+| "It's just a small change" | dispatch="auto" means the system determined specialists are needed. |
+| "I'll save time by skipping" | Skipping causes missed issues that cost more later. |
+| "I'll dispatch later" | Dispatch IMMEDIATELY when dispatch="auto" is returned. |
 
-```
-1. TeamCreate({ team_name: "<task>-specialists" })
-2. Spawn specialists as teammates:
-   Agent({ team_name, name: "security-specialist", subagent_type: "general-purpose", prompt: ... })
-   Agent({ team_name, name: "code-quality-specialist", subagent_type: "general-purpose", prompt: ... })
-3. Create and assign tasks:
-   TaskCreate({ subject: "Security review of auth module" })
-   TaskUpdate({ taskId, owner: "security-specialist" })
-4. Specialists work autonomously, report via SendMessage:
-   SendMessage({ to: "team-lead", message: "## Security Findings\n- ...", summary: "Security review done" })
-5. Team lead collects all findings
-6. Shutdown: SendMessage({ to: "security-specialist", message: { type: "shutdown_request" } })
-```
+### Execution Model: Outer Transport vs Inner Coordination
 
-#### SendMessage-Based Reporting
+CodingBuddy uses a **nested execution model** with two distinct layers:
 
-Specialists report findings through `SendMessage` to the team lead. This enables:
-- Structured collection of all specialist outputs
-- Consolidated summary for the user
-- Clear audit trail of what each specialist found
+| Layer | Role | Tool | Scope |
+|-------|------|------|-------|
+| **Outer transport** | Parallel task execution across isolated environments | **TaskMaestro** (tmux + git worktree) or **SubAgent** (background agents) | One pane/agent per issue or task |
+| **Inner coordination** | Specialist collaboration within a single session | **Teams** (experimental) | Multiple specialists within one pane/session |
 
-**Report format:**
-```markdown
-## [Specialist Name] Findings
+> **Key distinction:** TaskMaestro and SubAgent are alternatives for the *outer* layer. Teams is an *inner* layer that can optionally run inside either outer strategy.
 
-### Critical
-- [finding]
+#### Nested Execution Examples
 
-### High
-- [finding]
+**Example 1: TaskMaestro (outer) + Teams (inner)**
 
-### Medium
-- [finding]
-
-### Recommendations
-- [recommendation]
+```
+TaskMaestro session (outer)
+├── Pane 1: Issue #101 (auth feature)
+│   └── Teams session (inner, optional)
+│       ├── security-specialist → reviews auth impl
+│       └── test-strategy-specialist → validates test coverage
+├── Pane 2: Issue #102 (dashboard UI)
+│   └── Single agent (no inner Teams needed)
+└── Pane 3: Issue #103 (API refactor)
+    └── Teams session (inner, optional)
+        ├── architecture-specialist → validates API design
+        └── performance-specialist → checks query efficiency
 ```
 
-#### Fallback: Agent Tool
-
-If Teams-based dispatch fails, fall back to the Agent tool:
-- Use `run_in_background: true` for each specialist
-- Collect results via `TaskOutput`
-- Document the fallback reason in your response
-
-#### Red Flags
+**Example 2: SubAgent (outer) without inner Teams**
 
-| Thought | Reality |
-|---------|---------|
-| "I can handle this analysis myself" | Specialists have domain expertise. Dispatch them. |
-| "It's just a small change" | dispatch="auto" means the system determined specialists are needed. |
-| "I'll save time by skipping" | Skipping causes missed issues that cost more later. |
-| "I'll dispatch later" | Dispatch IMMEDIATELY when dispatch="auto" is returned. |
+```
+SubAgent dispatch (outer)
+├── Agent 1: security-specialist (run_in_background)
+├── Agent 2: accessibility-specialist (run_in_background)
+└── Agent 3: performance-specialist (run_in_background)
+→ Collect results via TaskOutput
+```
 
 ### Execution Strategy Selection (MANDATORY)
 
-When `parse_mode` returns `availableStrategies`:
+When `parse_mode` returns `availableStrategies`, select the **outer transport** strategy:
 
 1. **Check `availableStrategies`** in the response
 2. **If both strategies available** (`["subagent", "taskmaestro"]`), ask user with AskUserQuestion:
@@ -600,8 +590,8 @@ When `parse_mode` returns `availableStrategies`:
    - Yes → invoke `/taskmaestro` skill to guide installation, then re-check
    - No → proceed with subagent
 4. **Call `dispatch_agents`** with chosen `executionStrategy` parameter:
-   - `dispatch_agents({ mode, specialists, executionStrategy: "subagent" })` — existing Agent tool flow
-   - `dispatch_agents({ mode, specialists, executionStrategy: "taskmaestro" })` — returns tmux assignments
+   - `dispatch_agents({ mode, specialists, executionStrategy: "subagent" })` — Agent tool flow
+   - `dispatch_agents({ mode, specialists, executionStrategy: "taskmaestro" })` — tmux pane assignments
 5. **Execute** based on strategy:
    - **subagent**: Use `dispatchParams` with Agent tool (`run_in_background: true`)
    - **taskmaestro**: Follow `executionHint` — start panes, assign prompts, monitor, collect results
@@ -626,6 +616,71 @@ When `executionStrategy: "taskmaestro"` is chosen, `dispatch_agents` returns:
 
 Execute by following the `executionHint` commands sequentially.
 
+### Teams as Inner Coordination Layer (Experimental)
+
+> **Capability gate:** Teams-based coordination is experimental and depends on Claude Code native Teams support being available at runtime. If Teams APIs (`TeamCreate`, `SendMessage`, etc.) are not available, fall back to the SubAgent dispatch pattern.
+
+Teams provide structured specialist coordination **within** a single session or TaskMaestro pane. Use Teams when a task benefits from multiple specialists collaborating and reporting back to a coordinator, rather than running independently.
+
+#### When to Use Inner Teams
+
+- A single task (or pane) needs input from 2+ specialists who should coordinate
+- Specialist findings need to be collected and consolidated by a team lead
+- The task requires structured message-based reporting between specialists
+
+#### When NOT to Use Inner Teams
+
+- Each specialist can run independently with no cross-specialist dependencies
+- You are dispatching specialists across separate issues/tasks (use outer transport instead)
+- Teams APIs are not available at runtime
+
+#### Teams Workflow (within a session)
+
+```
+1. TeamCreate({ team_name: "<task>-specialists" })
+2. Spawn specialists as teammates:
+   Agent({ team_name, name: "security-specialist", subagent_type: "general-purpose", prompt: ... })
+   Agent({ team_name, name: "code-quality-specialist", subagent_type: "general-purpose", prompt: ... })
+3. Create and assign tasks:
+   TaskCreate({ subject: "Security review of auth module" })
+   TaskUpdate({ taskId, owner: "security-specialist" })
+4. Specialists work autonomously, report via SendMessage:
+   SendMessage({ to: "team-lead", message: "## Security Findings\n- ...", summary: "Security review done" })
+5. Team lead collects all findings
+6. Shutdown: SendMessage({ to: "security-specialist", message: { type: "shutdown_request" } })
+```
+
+#### SendMessage-Based Reporting
+
+Specialists report findings through `SendMessage` to the team lead. This enables:
+- Structured collection of all specialist outputs
+- Consolidated summary for the user
+- Clear audit trail of what each specialist found
+
+**Report format:**
+```markdown
+## [Specialist Name] Findings
+
+### Critical
+- [finding]
+
+### High
+- [finding]
+
+### Medium
+- [finding]
+
+### Recommendations
+- [recommendation]
+```
+
+#### Fallback: SubAgent Dispatch
+
+If Teams APIs are unavailable or Teams-based dispatch fails:
+- Use SubAgent with `run_in_background: true` for each specialist
+- Collect results via `TaskOutput`
+- Document the fallback reason in your response
+
 ## PR All-in-One Skill
 
 Unified commit and PR workflow that:

package/.ai-rules/agent-stacks/api-development.json

@@ -0,0 +1,17 @@
+{
+  "name": "api-development",
+  "description": "API development team for building and maintaining backend services",
+  "category": "backend",
+  "tags": ["api", "backend", "rest", "graphql"],
+  "primary_agent": "backend-developer",
+  "specialist_agents": [
+    "security-specialist",
+    "test-engineer",
+    "performance-specialist",
+    "documentation-specialist"
+  ],
+  "recommended_for": {
+    "file_patterns": ["*.controller.ts", "*.service.ts", "*.resolver.ts", "*.route.ts"],
+    "modes": ["PLAN", "ACT"]
+  }
+}

package/.ai-rules/agent-stacks/data-pipeline.json

@@ -0,0 +1,12 @@
+{
+  "name": "data-pipeline",
+  "description": "Data pipeline team for data engineering, analysis, and monitoring",
+  "category": "data",
+  "tags": ["data", "pipeline", "etl", "analytics"],
+  "primary_agent": "data-engineer",
+  "specialist_agents": ["data-scientist", "performance-specialist", "observability-specialist"],
+  "recommended_for": {
+    "file_patterns": ["*.sql", "*.py", "*migration*", "*pipeline*"],
+    "modes": ["PLAN", "ACT"]
+  }
+}

package/.ai-rules/agent-stacks/frontend-polish.json

@@ -0,0 +1,17 @@
+{
+  "name": "frontend-polish",
+  "description": "Frontend polish team for UI/UX refinement, accessibility, and performance",
+  "category": "frontend",
+  "tags": ["ui", "ux", "accessibility", "frontend", "seo"],
+  "primary_agent": "frontend-developer",
+  "specialist_agents": [
+    "ui-ux-designer",
+    "accessibility-specialist",
+    "performance-specialist",
+    "seo-specialist"
+  ],
+  "recommended_for": {
+    "file_patterns": ["*.tsx", "*.css", "*.scss", "*.module.css"],
+    "modes": ["EVAL", "ACT"]
+  }
+}

package/.ai-rules/agent-stacks/full-stack.json

@@ -0,0 +1,18 @@
+{
+  "name": "full-stack",
+  "description": "Full-stack development team for end-to-end web application development",
+  "category": "development",
+  "tags": ["web", "fullstack", "frontend", "backend"],
+  "primary_agent": "software-engineer",
+  "specialist_agents": [
+    "frontend-developer",
+    "backend-developer",
+    "security-specialist",
+    "test-engineer",
+    "performance-specialist"
+  ],
+  "recommended_for": {
+    "file_patterns": ["*.ts", "*.tsx", "*.js", "*.jsx"],
+    "modes": ["PLAN", "ACT", "AUTO"]
+  }
+}

package/.ai-rules/agent-stacks/ml-infrastructure.json

@@ -0,0 +1,17 @@
+{
+  "name": "ml-infrastructure",
+  "description": "ML infrastructure team for AI/ML model development and deployment",
+  "category": "ml",
+  "tags": ["ml", "ai", "model", "inference", "training"],
+  "primary_agent": "ai-ml-engineer",
+  "specialist_agents": [
+    "data-scientist",
+    "performance-specialist",
+    "observability-specialist",
+    "test-engineer"
+  ],
+  "recommended_for": {
+    "file_patterns": ["*.py", "*model*", "*predict*", "*train*"],
+    "modes": ["PLAN", "ACT", "EVAL"]
+  }
+}

package/.ai-rules/agent-stacks/security-audit.json

@@ -0,0 +1,16 @@
+{
+  "name": "security-audit",
+  "description": "Security audit team for vulnerability assessment and security hardening",
+  "category": "security",
+  "tags": ["security", "audit", "vulnerability", "compliance"],
+  "primary_agent": "security-engineer",
+  "specialist_agents": [
+    "security-specialist",
+    "test-strategy-specialist",
+    "code-quality-specialist"
+  ],
+  "recommended_for": {
+    "file_patterns": ["*auth*", "*token*", "*session*", "*crypto*"],
+    "modes": ["EVAL", "AUTO"]
+  }
+}

package/.ai-rules/agents/accessibility-specialist.json

@@ -4,6 +4,7 @@
   "color": "#27AE60",
   "role": {
     "title": "Accessibility Engineer",
+    "type": "specialist",
     "expertise": [
       "WCAG 2.1 AA compliance planning and verification",
       "ARIA attributes planning and verification",

package/.ai-rules/agents/act-mode.json

@@ -4,6 +4,7 @@
   "color": "#82B366",
   "role": {
     "title": "Act Mode Agent",
+    "type": "utility",
     "mode": "ACT",
     "purpose": "Mode Agent - delegates to Primary Developer Agent",
     "expertise": [

package/.ai-rules/agents/architecture-specialist.json

@@ -4,6 +4,7 @@
   "color": "#2C3E80",
   "role": {
     "title": "Architecture Engineer",
+    "type": "specialist",
     "expertise": [
       "Layer placement planning and verification",
       "Dependency direction design and verification",

package/.ai-rules/agents/auto-mode.json

@@ -4,6 +4,7 @@
   "color": "#B85450",
   "role": {
     "title": "Auto Mode Agent",
+    "type": "utility",
     "mode": "AUTO",
     "purpose": "Mode Agent - autonomously cycles through PLAN → ACT → EVAL, delegates to Primary Developer Agent",
     "expertise": [

package/.ai-rules/agents/code-quality-specialist.json

@@ -4,6 +4,7 @@
   "color": "#8BC34A",
   "role": {
     "title": "Code Quality Engineer",
+    "type": "specialist",
     "expertise": [
       "SOLID principles (Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion)",
       "DRY (Don't Repeat Yourself) principle",

package/.ai-rules/agents/code-reviewer.json

@@ -4,6 +4,7 @@
   "color": "#673AB7",
   "role": {
     "title": "Senior Code Reviewer / Quality Engineer",
+    "type": "specialist",
     "expertise": [
       "Multi-dimensional code quality evaluation",
       "Architecture and design pattern analysis",

package/.ai-rules/agents/documentation-specialist.json

@@ -4,6 +4,7 @@
   "color": "#607D8B",
   "role": {
     "title": "Documentation Engineer",
+    "type": "specialist",
     "expertise": [
       "Documentation planning and quality assessment",
       "Code comments planning and verification",

package/.ai-rules/agents/eval-mode.json

@@ -4,6 +4,7 @@
   "color": "#D4A843",
   "role": {
     "title": "Eval Mode Agent",
+    "type": "utility",
     "mode": "EVAL",
     "purpose": "Mode Agent - delegates to Code Reviewer Agent",
     "expertise": [

package/.ai-rules/agents/event-architecture-specialist.json

@@ -4,6 +4,7 @@
   "color": "#FF5722",
   "role": {
     "title": "Event Architecture Engineer",
+    "type": "specialist",
     "expertise": [
       "Message Queue Selection and Configuration (RabbitMQ, Kafka, SQS, Azure Service Bus)",
       "Event Sourcing and Event Store Design",

package/.ai-rules/agents/i18n-specialist.json

@@ -4,6 +4,7 @@
   "color": "#009688",
   "role": {
     "title": "Internationalization Engineer",
+    "type": "specialist",
     "expertise": [
       "i18n library setup and configuration",
       "Translation key structure design",

package/.ai-rules/agents/integration-specialist.json

@@ -4,6 +4,7 @@
   "color": "#00BCD4",
   "role": {
     "title": "Integration Engineer",
+    "type": "specialist",
     "expertise": [
       "API Integration Patterns (retries, timeouts, circuit breakers)",
       "Webhook Security (HMAC, JWT signature verification)",

package/.ai-rules/agents/observability-specialist.json

@@ -4,6 +4,7 @@
   "color": "#795548",
   "role": {
     "title": "Observability Engineer",
+    "type": "specialist",
     "expertise": [
       "OpenTelemetry instrumentation (traces, metrics, logs)",
       "Distributed tracing (Jaeger, Zipkin, Tempo, Grafana Tempo)",

package/.ai-rules/agents/performance-specialist.json

@@ -4,6 +4,7 @@
   "color": "#E67E22",
   "role": {
     "title": "Performance Engineer",
+    "type": "specialist",
     "expertise": [
       "Bundle size optimization planning and verification",
       "Code splitting strategy planning and verification",

package/.ai-rules/agents/plan-mode.json

@@ -5,6 +5,7 @@
   "systemPrompt": "You are a Plan Mode Agent that follows a structured reasoning process for every planning task.\n\n## Structured Reasoning Process (MANDATORY)\n\nBefore producing any plan, you MUST complete all five steps in order:\n\n### Step 0: Research\nRead relevant source code, configuration files, and documentation BEFORE planning.\n- NEVER plan from memory alone — always verify current state by reading files.\n- Identify existing patterns, conventions, and dependencies in the codebase.\n- Check recent git history for related changes.\n\n### Step 1: Decompose\nBreak the problem into discrete sub-problems.\n- Each sub-problem should be independently understandable.\n- Identify dependencies between sub-problems.\n- Order sub-problems by dependency (independent first, dependent last).\n\n### Step 2: Design\nCreate a concrete solution for each sub-problem.\n- Specify exact file paths, function names, and data structures.\n- Define the TDD approach: which tests to write first, expected failures, minimal implementations.\n- Ensure each solution is minimal — YAGNI applies.\n\n### Step 3: Devil's Advocate\nActively argue against your own plan.\n- What could go wrong? What edge cases are missed?\n- Are there simpler alternatives you overlooked?\n- Does the plan introduce unnecessary complexity or coupling?\n- Would this plan survive a critical code review?\n- Document weaknesses found and how the plan addresses them.\n\n### Step 4: Verify\nAll file paths and references in the plan MUST be verified against the actual codebase.\n- Confirmed paths: mark as-is.\n- Unconfirmed paths (not yet verified or file does not exist yet): mark with ⚠️ UNVERIFIED.\n- New files to be created: mark with 🆕 NEW.\n- NEVER assume a file exists without checking.",
   "role": {
     "title": "Plan Mode Agent",
+    "type": "utility",
     "mode": "PLAN",
     "purpose": "Mode Agent - delegates to Primary Developer Agent",
     "expertise": [

package/.ai-rules/agents/security-specialist.json

@@ -4,6 +4,7 @@
   "color": "#C0392B",
   "role": {
     "title": "Security Engineer",
+    "type": "specialist",
     "expertise": [
       "OAuth 2.0 / OIDC protocols",
       "JWT token management and security",

package/.ai-rules/agents/seo-specialist.json

@@ -4,6 +4,7 @@
   "color": "#16A085",
   "role": {
     "title": "SEO Engineer",
+    "type": "specialist",
     "expertise": [
       "Next.js Metadata API planning and verification",
       "Structured data (JSON-LD) planning and verification",

package/.ai-rules/agents/solution-architect.json

@@ -24,14 +24,14 @@
   "skills": {
     "required": [
       {
-        "name": "superpowers:brainstorming",
+        "name": "brainstorming",
         "purpose": "Explore design options through collaborative dialogue",
         "when": "Starting any new feature or architectural decision"
       }
     ],
     "recommended": [
       {
-        "name": "superpowers:writing-plans",
+        "name": "writing-plans",
         "purpose": "Document validated designs as implementation plans",
         "when": "After design is finalized, before handoff to Technical Planner"
       }
@@ -59,7 +59,7 @@
     ],
     "mandatory_checklist": {
       "🔴 brainstorming_first": {
-        "rule": "MUST invoke superpowers:brainstorming skill before any design work",
+        "rule": "MUST invoke brainstorming skill before any design work",
         "verification_key": "brainstorming_first"
       },
       "🔴 multiple_options": {
@@ -80,7 +80,7 @@
       }
     },
     "verification_guide": {
-      "brainstorming_first": "Check that superpowers:brainstorming skill was invoked at start",
+      "brainstorming_first": "Check that brainstorming skill was invoked at start",
       "multiple_options": "Verify 2-3 approaches were presented with pros/cons",
       "incremental_validation": "Design was presented in 200-300 word sections with user validation",
       "document_design": "Design document exists in docs/plans/ with correct naming",
@@ -92,7 +92,7 @@
       "approach": "Brainstorm-First",
       "applies_to": "New features, architecture decisions, technology selection",
       "steps": [
-        "1. Invoke superpowers:brainstorming skill",
+        "1. Invoke brainstorming skill",
         "2. Understand project context (files, docs, commits)",
         "3. Ask clarifying questions one at a time",
         "4. Propose 2-3 approaches with trade-offs",
@@ -162,7 +162,7 @@
   "reference": {
     "project_rules": ".ai-rules/rules/",
     "existing_agents": ".ai-rules/agents/*.json",
-    "skills_location": "superpowers plugin skills"
+    "skills_location": "codingbuddy skills"
   },
   "visual": {
     "eye": "⬢",

package/.ai-rules/agents/technical-planner.json

@@ -24,24 +24,24 @@
   "skills": {
     "required": [
       {
-        "name": "superpowers:writing-plans",
+        "name": "writing-plans",
         "purpose": "Create comprehensive implementation plans",
         "when": "Always when creating implementation plans"
       }
     ],
     "recommended": [
       {
-        "name": "superpowers:test-driven-development",
+        "name": "test-driven-development",
         "purpose": "Ensure TDD approach in plan tasks",
         "when": "Designing test-first task sequences"
       },
       {
-        "name": "superpowers:subagent-driven-development",
+        "name": "subagent-driven-development",
         "purpose": "Execute plans with fresh subagent per task",
         "when": "User chooses to execute in current session"
       },
       {
-        "name": "superpowers:executing-plans",
+        "name": "executing-plans",
         "purpose": "Execute plans in parallel session",
         "when": "User chooses to execute in separate session"
       }
@@ -69,7 +69,7 @@
     ],
     "mandatory_checklist": {
       "🔴 writing_plans_skill": {
-        "rule": "MUST invoke superpowers:writing-plans skill for plan creation",
+        "rule": "MUST invoke writing-plans skill for plan creation",
         "verification_key": "writing_plans_skill"
       },
       "🔴 bite_sized_tasks": {
@@ -94,7 +94,7 @@
       }
     },
     "verification_guide": {
-      "writing_plans_skill": "Check that superpowers:writing-plans skill was invoked",
+      "writing_plans_skill": "Check that writing-plans skill was invoked",
       "bite_sized_tasks": "Each step should be a single action (2-5 minutes)",
       "exact_file_paths": "All paths use exact/path/to/file.ext format",
       "tdd_structure": "Each task has: failing test → verify fail → implement → verify pass → commit",
@@ -107,7 +107,7 @@
       "approach": "TDD-First Planning",
       "applies_to": "Implementation plans, task breakdowns, coding tasks",
       "steps": [
-        "1. Invoke superpowers:writing-plans skill",
+        "1. Invoke writing-plans skill",
         "2. Read design document or requirements",
         "3. Identify all components and dependencies",
         "4. Break into bite-sized tasks (2-5 minutes each)",
@@ -172,12 +172,12 @@
   "execution_options": {
     "subagent_driven": {
       "description": "Execute in current session with fresh subagent per task",
-      "skill": "superpowers:subagent-driven-development",
+      "skill": "subagent-driven-development",
       "benefits": ["No context switch", "Fast iteration", "Two-stage review"]
     },
     "parallel_session": {
       "description": "Execute in separate session with checkpoints",
-      "skill": "superpowers:executing-plans",
+      "skill": "executing-plans",
       "benefits": ["Parallel work possible", "Clear handoff points"]
     }
   },
@@ -193,8 +193,8 @@
   "reference": {
     "project_rules": ".ai-rules/rules/",
     "existing_agents": ".ai-rules/agents/*.json",
-    "skills_location": "superpowers plugin skills",
-    "plan_examples": "See superpowers:writing-plans skill for examples"
+    "skills_location": "codingbuddy skills",
+    "plan_examples": "See writing-plans skill for examples"
   },
   "visual": {
     "eye": "⎔",

package/.ai-rules/agents/test-strategy-specialist.json

@@ -4,6 +4,7 @@
   "color": "#F1C40F",
   "role": {
     "title": "Test Strategy Engineer",
+    "type": "specialist",
     "expertise": [
       "TDD vs Test-After decision making and verification",
       "Test coverage planning and analysis (90%+ goal)",

package/.ai-rules/agents/ui-ux-designer.json

@@ -4,6 +4,7 @@
   "color": "#E91E63",
   "role": {
     "title": "UI/UX Design Specialist",
+    "type": "specialist",
     "expertise": [
       "Visual Design Principles",
       "User Experience Patterns",

package/.ai-rules/rules/core.md

@@ -609,11 +609,24 @@ To preserve this implementation session for future reference:
 
 ---
 
-### Error Recovery (ACT mode)
+### Branch Discipline
 
-- On recoverable errors (file not found, command failure, path issues), try alternatives immediately
-- Do not wait for user confirmation on recoverable errors — recover immediately
-- Only report to user on unrecoverable errors (auth failure, critical data loss risk)
+- Always verify current branch before committing (`git status` / `git branch`)
+- Never commit directly to master/main — always use feature branches
+- If accidentally on master/main, create a new branch before committing
+
+### Mode Transition Rules
+
+- **PLAN → ACT:** MUST wait for explicit user "ACT" input. Never auto-proceed from PLAN to ACT.
+- **During ACT:** Proceed autonomously. Only stop for errors or blockers.
+- **"Wait for mode transition"** ≠ "wait during execution" — mode transitions require user input, but execution within a mode is continuous.
+
+### Error Recovery
+
+- **Recoverable errors** (label not found, file missing, command failure, path issues): auto-try alternatives immediately, continue without user confirmation
+- **Unrecoverable errors** (auth failure, critical data loss risk): report to user
+- Only report to user when recovery is impossible
+- Never stop for confirmation on recoverable errors
 - Never break the workflow on error — try alternatives and continue
 
 ### Path Safety (monorepo)

package/.ai-rules/rules/parallel-execution.md

@@ -81,6 +81,38 @@ Order waves considering:
 
 ---
 
+## Implementation vs Read-Only Task Dispatch
+
+Implementation tasks (code changes, file modifications, commits) MUST use tmux-based parallel execution (e.g., taskMaestro), NOT background sub-agents.
+
+| Task Type | Dispatch Method | Rationale |
+|-----------|----------------|-----------|
+| **Implementation** (write code, modify files, commit, create PR) | taskMaestro (tmux panes) with git worktree isolation | Full environment, git operations, pre-push checks |
+| **Read-only** (research, analysis, code review, search) | Background sub-agents (Agent tool) | No file mutations, safe to run in parallel without isolation |
+
+**Why:** Background sub-agents lack proper git worktree isolation, cannot run pre-push checks reliably, and risk file conflicts when multiple agents write to the same workspace. taskMaestro provides each worker with an isolated worktree, proper shell environment, and full CI toolchain access.
+
+## Monorepo Path Safety
+
+In monorepo environments, always use absolute paths or `git -C <path>` for git commands to prevent path doubling:
+
+```bash
+# ✅ Correct — absolute path or git -C
+git -C /absolute/path/to/repo status
+git -C "$REPO_ROOT" add src/file.ts
+
+# ❌ Wrong — relative path after cd can double
+cd packages/my-lib
+git add packages/my-lib/src/file.ts  # Path doubled!
+
+# ❌ Wrong — assuming cwd after operations
+git add src/file.ts  # May not be in expected directory
+```
+
+**Why:** Relative paths in monorepo subdirectories frequently cause `git add` to target wrong files or fail silently. After any `cd` or worktree operation, verify cwd or use absolute paths.
+
+---
+
 ## Sub-Agent Parallelization Strategy
 
 When dispatching parallel sub-agents (workers), follow these guidelines:

package/.ai-rules/schemas/agent.schema.json

@@ -43,8 +43,8 @@
         },
         "type": {
           "type": "string",
-          "enum": ["primary", "specialist"],
-          "description": "Agent type: 'primary' uses top-level activation for PLAN/ACT workflow, 'specialist' uses modes for domain-specific guidance. RECOMMENDED: Always specify for new agents to ensure proper workflow integration."
+          "enum": ["primary", "specialist", "utility"],
+          "description": "Agent type: 'primary' uses top-level activation for PLAN/ACT workflow, 'specialist' uses modes for domain-specific guidance, 'utility' is for mode agents (PLAN/ACT/EVAL/AUTO). RECOMMENDED: Always specify for new agents to ensure proper workflow integration."
         },
         "expertise": {
           "type": "array",

package/.ai-rules/skills/ship/SKILL.md

@@ -137,6 +137,41 @@ If `custom.ship.globalChecks` is configured, run each global check command after
 <command>   # executed from project root
 ```
 
+### Security check (ALL workspaces)
+
+Security audit must run across ALL workspaces, not just affected ones:
+
+```bash
+# Monorepo — run for ALL workspaces (not just affected):
+<pm> audit
+# Or for npm:
+npm audit --workspaces
+```
+
+**Why:** A vulnerability in an unaffected workspace still ships with the project. Security scanning must be comprehensive.
+
+### CI workflow self-inclusion check
+
+When modifying CI workflow files (e.g., `.github/workflows/*.yml`), verify the workflow's `on.push.paths` or `on.pull_request.paths` filter includes the workflow file itself:
+
+```yaml
+# ✅ Correct — workflow file is included in its own paths filter
+on:
+  push:
+    paths:
+      - 'src/**'
+      - '.github/workflows/ci.yml'  # Self-included
+
+# ❌ Wrong — workflow changes won't trigger the workflow
+on:
+  push:
+    paths:
+      - 'src/**'
+      # Missing: .github/workflows/ci.yml
+```
+
+**Why:** If a workflow file is not in its own paths filter, changes to the workflow itself won't trigger CI, making it impossible to validate workflow changes before merging.
+
 If ANY check fails, stop and report the failure. Do NOT proceed to shipping.
 
 ## Step 6: Check Commit Convention

package/.ai-rules/skills/systematic-debugging/SKILL.md

@@ -22,6 +22,45 @@ NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
 
 If you haven't completed Phase 1, you cannot propose fixes.
 
+## Mandatory 6-Step Debugging Sequence
+
+Before ANY debugging attempt, follow this sequence in order:
+
+1. **Validate/Check command** — If the external tool has a validate/check/lint command, run it FIRST. Always. No exceptions.
+2. **Official documentation** — Verify system behavior by reading official docs. No guessing how a system works.
+3. **Hypothesis formation** — Form a hypothesis with evidence from steps 1-2.
+4. **Fix implementation** — Implement the fix based on your hypothesis.
+5. **Local verification** — Verify the fix locally before shipping.
+6. **Ship** — Only ship after local verification passes.
+
+### Validate First Rule
+
+If an external tool, service, or configuration format has a validate/check/lint command, you MUST run it BEFORE any debugging or fix attempts:
+
+| Tool/Format | Validate Command |
+|-------------|-----------------|
+| GitHub Actions | `actionlint` or validate via `act --list` |
+| Docker | `docker compose config` |
+| Kubernetes | `kubectl apply --dry-run=client` |
+| Terraform | `terraform validate` |
+| JSON | `jq .` or schema-specific validators |
+| YAML | `yamllint` |
+| TypeScript | `tsc --noEmit` |
+| ESLint config | `eslint --print-config` |
+
+**Why:** Validation catches syntax and schema errors instantly. Debugging without validation wastes time on issues the tool itself can detect.
+
+### Verify Mental Model Rule
+
+Before assuming how an external system works, read the official documentation first:
+
+- **Never guess** API behavior, config format, or tool behavior from memory
+- **Always verify** against official docs, especially for version-specific behavior
+- **Check changelogs** when upgrading — behavior may have changed between versions
+- If official docs are unavailable, use `--help`, man pages, or source code as reference
+
+**Why:** Stale mental models from past versions or similar-but-different tools cause debugging to chase phantom issues.
+
 ## When to Use
 
 Use for ANY technical issue:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codingbuddy-rules",
-  "version": "5.2.0",
+  "version": "5.3.0",
   "description": "AI coding rules for consistent practices across AI assistants",
   "main": "index.js",
   "types": "index.d.ts",