codingbuddy-rules 5.2.0 → 5.4.0

package/.ai-rules/adapters/antigravity.md

@@ -593,6 +593,8 @@ When AUTO keyword is detected, Antigravity calls `parse_mode` MCP tool which ret
    - Success: `Critical = 0 AND High = 0`
    - Failure: Max iterations reached (default: 3)
 
+> **Severity and review-cycle canonical sources:** The `Critical`/`High` levels above are the **Code Review Severity** scale defined in [`../rules/severity-classification.md`](../rules/severity-classification.md#code-review-severity). The PR approval loop (CI gate → review → fix → re-review → approve) is specified in [`../rules/pr-review-cycle.md`](../rules/pr-review-cycle.md). Follow those canonical sources rather than re-deriving severity or approval criteria from this adapter.
+
 ### Configuration
 
 Configure in `codingbuddy.config.json`:

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

@@ -529,67 +529,79 @@ 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]
+```
+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
+```
 
-### Recommendations
-- [recommendation]
+**Example 2: SubAgent (outer) without inner Teams**
+
+```
+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
 ```
 
-#### Fallback: Agent Tool
+**Example 3: TaskMaestro (outer) + SubAgent (inner, within worker)**
 
-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
+```
+TaskMaestro session (outer, conductor)
+├── Pane 1: Worker for Issue #101 (auth feature)
+│   ├── Explore subAgent → researches existing auth patterns
+│   ├── Plan subAgent → drafts TDD test plan
+│   ├── [Worker writes code directly in its own worktree]
+│   └── [Worker commits, pushes, creates PR, writes RESULT.json]
+├── Pane 2: Worker for Issue #102 (dashboard UI)
+│   └── Worker uses sub-agents for component research
+│       (no cross-pane interference because each worker owns its worktree)
+└── Pane 3: Review Agent (from review cycle protocol)
+    └── EVAL mode reviewer for completed PRs
+```
 
-#### Red Flags
+This is the **recommended pattern for complex worker tasks** where parallel research or context protection would benefit the worker. The conductor still uses TaskMaestro for the outer dispatch — only the worker's internal orchestration uses sub-agents.
 
-| 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. |
+**Key invariant:** Sub-agents dispatched by a worker operate inside that worker's git worktree. Cross-pane file conflicts are impossible because each pane's worker owns its own isolated worktree.
+
+See [`../rules/parallel-execution.md`](../rules/parallel-execution.md) "Conductor vs Worker Context" section for the authoritative rule.
 
 ### 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 +612,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 +638,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:
@@ -715,6 +792,8 @@ AUTO implement user authentication with JWT
 - **Success**: `Critical = 0 AND High = 0` severity issues
 - **Failure**: Max iterations reached (default: 3, configurable via `auto.maxIterations`)
 
+> **Severity and review-cycle canonical sources:** The `Critical`/`High` levels above are the **Code Review Severity** scale defined in [`../rules/severity-classification.md`](../rules/severity-classification.md#code-review-severity). The approval loop Claude Code runs over a PR (CI gate → review → fix → re-review → approve) is specified in [`../rules/pr-review-cycle.md`](../rules/pr-review-cycle.md). Follow those canonical sources rather than re-deriving severity or approval criteria from this adapter.
+
 ### Configuration
 
 Configure AUTO mode in `codingbuddy.config.json`:
@@ -763,3 +842,149 @@ module.exports = {
 | Iterations | Single pass per mode | Multiple cycles until quality met |
 | Exit | User decides completion | Quality criteria or max iterations |
 | Intervention | Required for each step | Only when requested or on failure |
+
+## EVAL Review Agent Prompt Template
+
+Canonical template for review agents that evaluate PRs in EVAL mode. Use this when a conductor, review pane, or solo workflow needs to generate a structured review prompt.
+
+### When to Use
+
+- **Conductor review**: The conductor generates this prompt for itself or a dedicated review pane
+- **TaskMaestro review pane**: The review agent receives this prompt as its `TASK.md`
+- **Solo workflow**: A developer enters EVAL mode to review their own PR before requesting human review
+
+### Template
+
+The review agent prompt follows this structure:
+
+```
+EVAL: review PR #<PR_NUMBER> for issue #<ISSUE_NUMBER>
+
+Review the PR against the linked issue's acceptance criteria.
+Use review_pr MCP tool, dispatch recommended specialists, and follow pr-review-cycle.md protocol.
+Approve only when Critical = 0 AND High = 0.
+```
+
+### Step-by-Step Execution
+
+When the review agent receives the prompt above, it MUST execute these steps in order:
+
+#### 1. Enter EVAL Mode
+
+```typescript
+const result = await parse_mode({
+  prompt: "EVAL: review PR #<PR_NUMBER> for issue #<ISSUE_NUMBER>"
+});
+```
+
+This returns:
+- `mode: "EVAL"` with code-reviewer as primary agent
+- `parallelAgentsRecommendation` with EVAL-mode specialists
+- `dispatchReady` (if auto-dispatch is enabled)
+
+#### 2. Fetch Structured Review Data
+
+```typescript
+const reviewData = await review_pr({
+  pr_number: <PR_NUMBER>,
+  issue_number: <ISSUE_NUMBER>  // optional, for spec compliance
+});
+```
+
+The `review_pr` tool returns:
+- PR metadata (title, author, base/head branches)
+- Diff summary and changed files list
+- Auto-generated checklists for changed file domains
+- Recommended specialist agents based on file patterns
+
+#### 3. Dispatch Recommended Specialists
+
+Use the specialists from `parse_mode` or `review_pr` response:
+
+```typescript
+// Option A: Auto-dispatch from parse_mode (preferred)
+if (result.dispatchReady?.parallelAgents) {
+  for (const agent of result.dispatchReady.parallelAgents) {
+    Agent({
+      subagent_type: agent.dispatchParams.subagent_type,
+      prompt: agent.dispatchParams.prompt,
+      description: agent.dispatchParams.description,
+      run_in_background: true,
+    });
+  }
+}
+
+// Option B: Manual dispatch from review_pr recommendations
+const dispatch = await dispatch_agents({
+  mode: "EVAL",
+  specialists: reviewData.recommendedSpecialists,
+  taskDescription: `Review PR #${prNumber}`,
+  targetFiles: reviewData.changedFiles,
+});
+```
+
+Typical EVAL-mode specialists: `security-specialist`, `accessibility-specialist`, `performance-specialist`, `code-quality-specialist`.
+
+#### 4. Collect and Classify Findings
+
+Collect all specialist results and classify each finding using the [Code Review Severity](../rules/severity-classification.md#code-review-severity) scale:
+
+| Severity | Meaning | Merge Gate |
+|----------|---------|------------|
+| `critical` | Blocks approval, must fix | BLOCKED |
+| `high` | Should fix before merge | BLOCKED (unless explicitly deferred) |
+| `medium` | Worth addressing, does not gate merge | APPROVED with comments |
+| `low` | Style/polish suggestions | APPROVED |
+
+#### 5. Write the Review
+
+Post the structured review on the PR:
+
+```bash
+gh pr review <PR_NUMBER> --comment --body "<structured review>"
+```
+
+Review body format (per [`pr-review-cycle.md`](../rules/pr-review-cycle.md)):
+
+```markdown
+## Review: [APPROVE | CHANGES_REQUESTED]
+### CI Status: [PASS | FAIL]
+### Issues Found:
+- [critical]: <description> — <file:line>
+- [high]: <description> — <file:line>
+- [medium]: <description> — <file:line>
+### Recommendation: [APPROVE | REQUEST_CHANGES]
+```
+
+#### 6. Approval Gate
+
+Follow the approval criteria from [`pr-review-cycle.md`](../rules/pr-review-cycle.md):
+
+- **Approve** when: CI green, Critical = 0, High = 0 (or explicitly deferred with ticket)
+- **Request changes** when: any Critical or High finding remains unresolved
+
+```bash
+# Approve (when reviewer is not the PR author)
+gh pr review <PR_NUMBER> --approve --body "LGTM - all review comments addressed"
+
+# Request changes
+gh pr review <PR_NUMBER> --request-changes --body "<structured review>"
+```
+
+### Complete Prompt Example
+
+For a conductor generating a review agent task:
+
+```markdown
+EVAL: review PR #42 for issue #40
+
+Review the PR against the linked issue's acceptance criteria.
+Use review_pr MCP tool, dispatch recommended specialists, and follow pr-review-cycle.md protocol.
+Approve only when Critical = 0 AND High = 0.
+```
+
+### Canonical References
+
+- **Severity scale**: [`severity-classification.md`](../rules/severity-classification.md#code-review-severity) — Critical/High/Medium/Low definitions
+- **Review protocol**: [`pr-review-cycle.md`](../rules/pr-review-cycle.md) — CI gate, review steps, approval criteria, commit hygiene
+- **MCP tool**: `review_pr(pr_number, issue_number?, timeout?)` — structured PR review data

package/.ai-rules/adapters/codex.md

@@ -619,6 +619,8 @@ AUTO implement user authentication with JWT
    - Success: `Critical = 0 AND High = 0`
    - Failure: Max iterations reached (default: 3)
 
+> **Severity and review-cycle canonical sources:** The `Critical`/`High` levels above are the **Code Review Severity** scale defined in [`../rules/severity-classification.md`](../rules/severity-classification.md#code-review-severity). The PR approval loop (CI gate → review → fix → re-review → approve) is specified in [`../rules/pr-review-cycle.md`](../rules/pr-review-cycle.md). Follow those canonical sources rather than re-deriving severity or approval criteria from this adapter.
+
 ### Copilot Integration
 
 When using GitHub Copilot Chat with AUTO mode:

package/.ai-rules/adapters/cursor.md

@@ -429,6 +429,8 @@ When AUTO keyword is detected, Cursor calls `parse_mode` MCP tool which returns
    - Success: `Critical = 0 AND High = 0`
    - Failure: Max iterations reached (default: 3)
 
+> **Severity and review-cycle canonical sources:** The `Critical`/`High` levels above are the **Code Review Severity** scale defined in [`../rules/severity-classification.md`](../rules/severity-classification.md#code-review-severity). The PR approval loop (CI gate → review → fix → re-review → approve) is specified in [`../rules/pr-review-cycle.md`](../rules/pr-review-cycle.md). Follow those canonical sources rather than re-deriving severity or approval criteria from this adapter.
+
 ### Configuration
 
 Configure in `codingbuddy.config.json`:

package/.ai-rules/adapters/kiro.md

@@ -552,6 +552,8 @@ When AUTO keyword is detected, Kiro calls `parse_mode` MCP tool which returns AU
    - Success: `Critical = 0 AND High = 0`
    - Failure: Max iterations reached (default: 3)
 
+> **Severity and review-cycle canonical sources:** The `Critical`/`High` levels above are the **Code Review Severity** scale defined in [`../rules/severity-classification.md`](../rules/severity-classification.md#code-review-severity). The PR approval loop (CI gate → review → fix → re-review → approve) is specified in [`../rules/pr-review-cycle.md`](../rules/pr-review-cycle.md). Follow those canonical sources rather than re-deriving severity or approval criteria from this adapter.
+
 ### Configuration
 
 Configure in `codingbuddy.config.json`:

package/.ai-rules/adapters/opencode.md

@@ -145,11 +145,13 @@ Update your configuration file (`.opencode.json` or `crush.json`):
 
 | Codingbuddy Agent | OpenCode Agent | Purpose |
 |------------------|----------------|---------|
-| **plan-mode.json** | `plan-mode` | PLAN mode workflow (delegates to frontend-developer) |
-| **act-mode.json** | `act-mode` | ACT mode workflow (delegates to frontend-developer) |
+| **plan-mode.json** | `plan-mode` | PLAN mode workflow (delegates to solution-architect or technical-planner based on task complexity) |
+| **act-mode.json** | `act-mode` | ACT mode workflow (delegates to software-engineer or domain specialist per ACT resolution rules) |
 | **eval-mode.json** | `eval-mode` | EVAL mode workflow (delegates to code-reviewer) |
 | **auto-mode.json** | N/A (keyword-triggered) | AUTO mode workflow (autonomous PLAN→ACT→EVAL cycle) |
-| **frontend-developer.json** | N/A (delegate) | Primary development implementation |
+| **solution-architect.json** | N/A (delegate) | PLAN mode system-level design and architecture |
+| **technical-planner.json** | N/A (delegate) | PLAN mode implementation-level TDD planning |
+| **frontend-developer.json** | N/A (delegate) | ACT mode implementation for frontend projects |
 | **backend-developer.json** | `backend` | Backend development (Node.js, Python, Go, Java, Rust) |
 | **code-reviewer.json** | N/A (delegate) | Code quality evaluation implementation |
 | **architecture-specialist.json** | `architect` | Architecture and design patterns |
@@ -162,7 +164,7 @@ Update your configuration file (`.opencode.json` or `crush.json`):
 
 - **Mode Agents** (`plan-mode`, `act-mode`, `eval-mode`, `auto-mode`): Workflow orchestrators that delegate to appropriate implementation agents
 - **Specialist Agents** (`architect`, `security`, etc.): Domain-specific expertise for specialized tasks
-- **Delegate Agents** (`frontend-developer`, `code-reviewer`): Implementation agents that Mode Agents delegate to
+- **Delegate Agents**: PLAN mode delegates to `solution-architect` or `technical-planner`; ACT mode delegates to `software-engineer` or a domain specialist (e.g., `frontend-developer`, `backend-developer`); EVAL mode delegates to `code-reviewer`
 
 ### 3. MCP Server Integration
 
@@ -292,15 +294,17 @@ The `parse_mode` tool now returns additional Mode Agent information and dynamic
   "language": "en",
   "languageInstruction": "Always respond in English.",
   "agent": "plan-mode",
-  "delegates_to": "frontend-developer",
+  "delegates_to": "solution-architect",
   "delegate_agent_info": {
-    "name": "Frontend Developer",
-    "description": "React/Next.js expert, TDD and design system experience",
-    "expertise": ["React", "Next.js", "TDD", "TypeScript"]
+    "name": "Solution Architect",
+    "description": "High-level system design and architecture planning specialist",
+    "expertise": ["System Architecture", "Technology Selection", "Integration Patterns", "Scalability Planning"]
   }
 }
 ```
 
+> **Note:** `delegates_to` is resolved dynamically based on prompt intent. System-level design prompts resolve to `solution-architect`; implementation-level planning prompts resolve to `technical-planner`.
+
 **New Fields:**
 - `language`: Language code from codingbuddy.config.json
 - `languageInstruction`: Formatted instruction text for AI assistants (🆕)
@@ -774,6 +778,8 @@ AUTO Build a new user authentication feature
    - Success: `Critical = 0 AND High = 0`
    - Failure: Max iterations reached (default: 3)
 
+> **Severity and review-cycle canonical sources:** The `Critical`/`High` levels above are the **Code Review Severity** scale defined in [`../rules/severity-classification.md`](../rules/severity-classification.md#code-review-severity). The PR approval loop (CI gate → review → fix → re-review → approve) is specified in [`../rules/pr-review-cycle.md`](../rules/pr-review-cycle.md). Follow those canonical sources rather than re-deriving severity or approval criteria from this adapter.
+
 ### OpenCode Agent Integration
 
 AUTO mode describes an autonomous PLAN→ACT→EVAL cycle. However, agent switching behavior differs by platform:

package/.ai-rules/adapters/q.md

@@ -198,6 +198,8 @@ AUTO create a new Lambda function
    - Success: `Critical = 0 AND High = 0`
    - Failure: Max iterations reached (default: 3)
 
+> **Severity and review-cycle canonical sources:** The `Critical`/`High` levels above are the **Code Review Severity** scale defined in [`../rules/severity-classification.md`](../rules/severity-classification.md#code-review-severity). The PR approval loop (CI gate → review → fix → re-review → approve) is specified in [`../rules/pr-review-cycle.md`](../rules/pr-review-cycle.md). Follow those canonical sources rather than re-deriving severity or approval criteria from this adapter.
+
 ### AWS Integration with AUTO Mode
 
 Amazon Q's AWS expertise complements AUTO mode:

package/.ai-rules/adapters/windsurf.md

@@ -299,6 +299,8 @@ Use the `AUTO` keyword at the start of your message:
    - Success: `Critical = 0 AND High = 0`
    - Failure: Max iterations reached (default: 3)
 
+> **Severity and review-cycle canonical sources:** The `Critical`/`High` levels above are the **Code Review Severity** scale defined in [`../rules/severity-classification.md`](../rules/severity-classification.md#code-review-severity). The PR approval loop (CI gate → review → fix → re-review → approve) is specified in [`../rules/pr-review-cycle.md`](../rules/pr-review-cycle.md). Follow those canonical sources rather than re-deriving severity or approval criteria from this adapter.
+
 ### Configuration
 
 Configure in `codingbuddy.config.json`:

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/README.md

@@ -342,7 +342,7 @@ This ensures Mode Agents appear first in agent selection interfaces.
 Mode Agents handle workflow orchestration and delegate to implementation experts:
 
 - **Plan Mode** (`plan-mode.json`): Analysis and planning (delegates to primary developer)
-- **Act Mode** (`act-mode.json`): Implementation execution (delegates to primary developer)
+- **Act Mode** (`act-mode.json`): Implementation execution (delegates to software-engineer or a domain specialist)
 - **Eval Mode** (`eval-mode.json`): Quality evaluation (delegates to code reviewer)
 - **Auto Mode** (`auto-mode.json`): Autonomous PLAN→ACT→EVAL cycle until quality achieved (Critical=0, High=0)
 
@@ -350,9 +350,11 @@ Mode Agents handle workflow orchestration and delegate to implementation experts
 
 These agents are automatically activated via Mode Agent delegation:
 
-- **Primary Developer Agent**: Activated by plan-mode/act-mode
-  - Example: `frontend-developer.json` (React/Next.js projects)
-  - Customize per project: `backend-developer.json`, `mobile-developer.json`, etc.
+- **Planning Agents**: Activated by plan-mode (resolved by intent)
+  - `solution-architect.json`: System-level design (new features, architecture decisions, technology selection)
+  - `technical-planner.json`: Implementation-level planning (bite-sized TDD tasks with exact file paths)
+- **Implementation Agent**: Activated by act-mode (resolved by intent / project config)
+  - Example: `frontend-developer.json` (React/Next.js projects), `backend-developer.json`, `mobile-developer.json`, or the language-agnostic `software-engineer.json`
 - **Code Reviewer** (`code-reviewer.json`): Activated by eval-mode
 
 ### Domain Specialists

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,8 +4,9 @@
   "color": "#82B366",
   "role": {
     "title": "Act Mode Agent",
+    "type": "utility",
     "mode": "ACT",
-    "purpose": "Mode Agent - delegates to Primary Developer Agent",
+    "purpose": "Mode Agent - delegates to the resolved implementation agent (software-engineer by default, domain specialist when selected)",
     "expertise": [
       "TDD cycle execution (Red → Green → Refactor)",
       "Code quality standards compliance",

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",