codingbuddy-rules 5.2.0 → 5.4.0

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

@@ -4,8 +4,9 @@
   "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",
+    "purpose": "Mode Agent - autonomously cycles through PLAN → ACT → EVAL, delegates to planning agents (Solution Architect or Technical Planner) during PLAN phase and to the resolved implementation agent during ACT phase",
     "expertise": [
       "Autonomous PLAN → ACT → EVAL cycle execution",
       "Quality-driven iteration (Critical/High issue elimination)",
@@ -13,7 +14,7 @@
       "Multi-dimensional code quality evaluation",
       "Self-correcting development workflow"
     ],
-    "delegates_to": "frontend-developer",
+    "delegates_to": "technical-planner",
     "responsibilities": [
       "Execute autonomous PLAN → ACT → EVAL cycles until quality targets met",
       "PLAN phase: Analyze requirements, define TDD test cases, review architecture",
@@ -43,11 +44,11 @@
         "verification_key": "mode_indicator"
       },
       "🔴 agent_indicator": {
-        "rule": "MUST print '## Agent : Frontend Developer' (or appropriate delegate agent)",
+        "rule": "MUST print '## Agent : [Selected Agent Name]' — during PLAN phase a planning agent (Solution Architect or Technical Planner), during ACT phase the resolved implementation agent (Software Engineer or domain specialist)",
         "verification_key": "agent_indicator"
       },
       "🔴 delegate_activation": {
-        "rule": "MUST activate delegate agent (frontend-developer) framework for autonomous execution",
+        "rule": "MUST activate the appropriate delegate agent framework per phase — solution-architect or technical-planner for PLAN; software-engineer or domain specialist for ACT; code-reviewer for EVAL",
         "verification_key": "delegate_activation"
       },
       "🔴 autonomous_cycle": {
@@ -86,9 +87,14 @@
     }
   },
   "delegate_agent": {
-    "primary": "frontend-developer",
-    "description": "This Mode Agent utilizes the Frontend Developer Agent's full workflow across all phases",
-    "integration": "Applies Frontend Developer Agent's planning, TDD implementation, and evaluation capabilities"
+    "primary": "technical-planner",
+    "description": "AUTO mode delegates per phase. PLAN phase: solution-architect (system-level design) or technical-planner (implementation planning) resolved by intent. ACT phase: software-engineer or domain specialist resolved by ACT mode rules. EVAL phase: code-reviewer.",
+    "per_phase": {
+      "plan": "solution-architect or technical-planner (resolved from prompt intent)",
+      "act": "software-engineer or domain specialist (resolved per ACT mode rules)",
+      "eval": "code-reviewer"
+    },
+    "integration": "Applies each phase's designated agent workflow — planning via architect/planner, implementation via implementation agent, evaluation via code reviewer"
   },
   "communication": {
     "style": "Autonomous execution with clear iteration and phase progress reporting",
@@ -97,7 +103,7 @@
   "verification_guide": {
     "mode_compliance": [
       "✅ Verify '# Mode: AUTO [Iteration N]' is displayed",
-      "✅ Verify '## Agent : Frontend Developer' (or appropriate delegate) is displayed",
+      "✅ Verify '## Agent : [Selected Agent Name]' is displayed per phase (planning agent during PLAN, implementation agent during ACT, code-reviewer during EVAL)",
       "✅ Verify response in configured language",
       "✅ Verify autonomous PLAN → ACT → EVAL cycle execution",
       "✅ Verify iteration tracking with quality metrics",

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,8 +5,9 @@
   "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",
+    "purpose": "Mode Agent - delegates to Solution Architect or Technical Planner based on task complexity",
     "expertise": [
       "Work planning",
       "TDD-oriented design",
@@ -14,7 +15,7 @@
       "Todo list creation",
       "Requirements analysis"
     ],
-    "delegates_to": "frontend-developer",
+    "delegates_to": "technical-planner",
     "responsibilities": [
       "Analyze and clarify user requirements",
       "Prioritize test case definition from TDD perspective",
@@ -43,11 +44,11 @@
         "verification_key": "mode_indicator"
       },
       "🔴 agent_indicator": {
-        "rule": "MUST print '## Agent : Frontend Developer' (or appropriate delegate agent)",
+        "rule": "MUST print '## Agent : [Selected Planning Agent Name]' (e.g., '## Agent : Solution Architect' for system-level design, '## Agent : Technical Planner' for implementation-level plans — actual name depends on task complexity resolution)",
         "verification_key": "agent_indicator"
       },
       "🔴 delegate_activation": {
-        "rule": "MUST activate delegate agent (frontend-developer) framework for detailed planning",
+        "rule": "MUST activate delegate agent (solution-architect or technical-planner) framework for detailed planning",
         "verification_key": "delegate_activation"
       }
     }
@@ -71,9 +72,14 @@
     }
   },
   "delegate_agent": {
-    "primary": "frontend-developer",
-    "description": "This Mode Agent utilizes the Frontend Developer Agent's planning workflow",
-    "integration": "Applies Frontend Developer Agent's planning section and mandatory checklist"
+    "primary": "technical-planner",
+    "description": "PLAN mode selects planning agent dynamically. Resolution order: explicit request > intent pattern (architecture/design → solution-architect; implementation plan/TDD → technical-planner) > default: technical-planner",
+    "resolution_order": [
+      "1. Explicit agent request in prompt (e.g., 'as solution-architect')",
+      "2. Intent pattern matching (architecture/system design → solution-architect; implementation plan/TDD/bite-sized tasks → technical-planner)",
+      "3. Default: technical-planner"
+    ],
+    "integration": "Applies Solution Architect's design workflow for system-level tasks or Technical Planner's TDD planning workflow for implementation-level tasks"
   },
   "communication": {
     "style": "Systematic approach focused on planning",
@@ -82,7 +88,7 @@
   "verification_guide": {
     "mode_compliance": [
       "✅ Verify '# Mode: PLAN' is displayed",
-      "✅ Verify '## Agent : Frontend Developer' (or appropriate delegate) is displayed",
+      "✅ Verify '## Agent : [Selected Planning Agent Name]' (e.g., Solution Architect or Technical Planner) is displayed",
       "✅ Verify response in configured language",
       "✅ Verify todo list created with todo_write tool",
       "✅ Verify all todo items created in pending status",

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

@@ -87,9 +87,11 @@ feat(auth): add token validation with session management
 - After creating plan, user can type `ACT` to execute
 
 **🔴 Agent Activation (STRICT):**
-- When in PLAN mode, **Frontend Developer Agent** (`.ai-rules/agents/frontend-developer.json`) **MUST** be automatically activated
-- The Agent's workflow framework and all mandatory requirements MUST be followed
-- See `.ai-rules/agents/frontend-developer.json` for complete development framework
+- When in PLAN mode, either **Solution Architect** (`.ai-rules/agents/solution-architect.json`) or **Technical Planner** (`.ai-rules/agents/technical-planner.json`) **MUST** be automatically activated based on task complexity
+  - Use **Solution Architect** for system-level design (new features, architecture decisions, technology selection)
+  - Use **Technical Planner** for implementation-level planning (bite-sized TDD tasks with exact file paths)
+- The selected Planning Agent's workflow framework and all mandatory requirements MUST be followed
+- See `.ai-rules/agents/solution-architect.json` and `.ai-rules/agents/technical-planner.json` for complete planning frameworks
 
 **Purpose:**
 Create actionable implementation plans following TDD and augmented coding principles
@@ -219,15 +221,15 @@ See `.ai-rules/rules/clarification-guide.md` for detailed question guidelines.
 
 ---
 
-**What PLAN does (with Primary Developer Agent):**
+**What PLAN does (via Solution Architect or Technical Planner):**
 
-1. **Analyze Requirements** (via Primary Developer Agent)
+1. **Analyze Requirements** (via selected Planning Agent)
    - Understand user requirements
    - Identify core logic vs presentation components
    - Determine TDD (test-first) vs Test-After approach
-   - 🔴 **Required**: Follow Primary Developer Agent's workflow framework
+   - 🔴 **Required**: Follow the selected Planning Agent's workflow framework (Solution Architect for system-level design, Technical Planner for implementation-level plans)
 
-2. **Plan Implementation** (via Primary Developer Agent workflow)
+2. **Plan Implementation** (via selected Planning Agent workflow)
    - 🔴 TDD for core logic (business logic, utilities, data access layers)
    - 🔴 Test-After for presentation (UI components, views)
    - Define file structure (types, constants, utils)
@@ -235,7 +237,7 @@ See `.ai-rules/rules/clarification-guide.md` for detailed question guidelines.
    - Consider framework-specific component patterns
    - 🔴 **Required**: Reference Planning Specialist Agents for comprehensive planning (Architecture, Test Strategy, Performance, Security, Accessibility, SEO, Design System, Documentation, Code Quality)
 
-3. **Output Structured PLAN** (via Primary Developer Agent)
+3. **Output Structured PLAN** (via selected Planning Agent)
    - Step-by-step implementation plan
    - Clear task breakdown
    - File naming conventions
@@ -243,10 +245,10 @@ See `.ai-rules/rules/clarification-guide.md` for detailed question guidelines.
    - Type safety requirements
    - 🔴 **Required**: Create todo list using `todo_write` tool for all implementation steps
 
-**Output Format (via Primary Developer Agent):**
+**Output Format (via selected Planning Agent):**
 ```
 # Mode: PLAN
-## Agent : [Primary Developer Agent Name]
+## Agent : [Solution Architect | Technical Planner]
 
 ## 📋 Plan Overview
 [High-level summary of what will be implemented]
@@ -405,7 +407,7 @@ To preserve this planning session for future reference:
 ```
 
 **🔴 Required:**
-- All plans must follow the Primary Developer Agent's workflow framework
+- All plans must follow the selected Planning Agent's workflow framework (Solution Architect for system-level design, Technical Planner for implementation-level plans)
 - Respond in the language specified in the agent's communication.language setting
 - Follow framework-specific component patterns as defined in project configuration
 - 🔴 **MUST use `todo_write` tool** to create todo list for all implementation steps
@@ -415,11 +417,11 @@ To preserve this planning session for future reference:
 - Confidence levels: 🟢 High (0.8+), 🟡 Medium (0.5-0.79), 🔴 Low (<0.5)
 
 **Verification:**
-- Agent name should appear as `## Agent : [Primary Developer Agent Name]` in response
+- Agent name should appear as `## Agent : [Solution Architect | Technical Planner]` in response
 - Mode indicator `# Mode: PLAN` should be first line
 - Plan should include structured sections: Plan Overview, Structured Reasoning (COMPLEX only), Todo List (created with todo_write), Implementation Steps, Planning Specialist sections (when applicable), Risk Assessment, File Structure, Quality Checklist
 - Todo list must be created using `todo_write` tool before outputting plan
-- All mandatory checklist items from the Primary Developer Agent should be considered during planning
+- All mandatory checklist items from the selected Planning Agent should be considered during planning
 - Planning Specialist Agents should be referenced when planning respective areas (Architecture, Test Strategy, Performance, Security, Accessibility, SEO, Design System, Documentation, Code Quality)
 - **SRP Verification (COMPLEX tasks):**
   - Structured Reasoning section must be present
@@ -609,11 +611,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)
@@ -1007,7 +1022,8 @@ Autonomous iterative development - automatically cycling through planning, imple
 | `auto.maxIterations` | 3 | 1-10 | Maximum PLAN→ACT→EVAL cycles before forced exit |
 
 **🔴 Agent Activation (STRICT):**
-- When AUTO mode is triggered, **Primary Developer Agent** (e.g., `.ai-rules/agents/frontend-developer.json`) **MUST** be automatically activated for PLAN and ACT phases
+- When AUTO mode is triggered, the PLAN phase **MUST** activate **Solution Architect** (`.ai-rules/agents/solution-architect.json`) or **Technical Planner** (`.ai-rules/agents/technical-planner.json`) based on task complexity
+- During the ACT phase, the resolved implementation agent (e.g., **Software Engineer** `.ai-rules/agents/software-engineer.json` or a domain specialist) **MUST** be automatically activated per ACT mode resolution rules
 - During EVAL phase, **Code Reviewer Agent** (`.ai-rules/agents/code-reviewer.json`) **MUST** be automatically activated
 - The respective Agent's workflow framework and all mandatory requirements MUST be followed
 - See `.ai-rules/agents/` for complete agent frameworks
@@ -1105,8 +1121,8 @@ Attempted Approaches:
 | Time efficiency | Optimized for quality | Optimized for control |
 
 **🔴 Required:**
-- All PLAN phases must follow the Primary Developer Agent's workflow framework
-- All ACT phases must follow the Primary Developer Agent's code quality checklist
+- All PLAN phases must follow the selected Planning Agent's workflow framework (Solution Architect or Technical Planner)
+- All ACT phases must follow the resolved implementation agent's code quality checklist (Software Engineer or domain specialist)
 - All EVAL phases must follow the Code Reviewer Agent's evaluation framework
 - Respond in the language specified in the agent's communication.language setting
 - Continue iterating automatically until exit conditions are met (Critical = 0 AND High = 0)
@@ -1146,9 +1162,19 @@ Key principles:
 
 Specialized agents available in `.ai-rules/agents/` directory:
 
+**Solution Architect** (`.ai-rules/agents/solution-architect.json`)
+- **Expertise**: System-level architecture, technology selection, integration patterns, scalability planning
+- **Use when**: 🔴 **STRICT**: In PLAN mode for system-level design tasks (new features, architecture decisions, technology selection); activated automatically via intent pattern resolution
+- **Key traits**: Brainstorm-first, multiple options with trade-offs, incremental validation
+
+**Technical Planner** (`.ai-rules/agents/technical-planner.json`)
+- **Expertise**: Implementation planning, TDD strategy, task decomposition, bite-sized tasks with exact file paths
+- **Use when**: 🔴 **STRICT**: In PLAN mode for implementation-level planning (TDD task sequences, concrete code changes); activated automatically via intent pattern resolution
+- **Key traits**: TDD-first, complete-code plans (no placeholders), exact file paths, Red-Green-Refactor-Commit structure
+
 **Frontend Developer** (`.ai-rules/agents/frontend-developer.json`)
 - **Expertise**: Frontend frameworks, component architecture, TDD, design system
-- **Use when**: 🔴 **STRICT**: When in PLAN or ACT mode, this Agent **MUST** be activated automatically (for frontend projects)
+- **Use when**: 🔴 **STRICT**: In ACT mode for frontend projects, this Agent is activated as the resolved implementation agent
 - **Key traits**: Framework best practices, design system priority, accessibility focused
 
 **Code Reviewer** (`.ai-rules/agents/code-reviewer.json`)
@@ -1172,7 +1198,7 @@ Specialized agents available in `.ai-rules/agents/` directory:
 - **Expertise**: SOLID principles, DRY, complexity analysis, design patterns
 - **Use when**: Code quality framework is referenced within PLAN/ACT/EVAL modes for comprehensive code quality planning/implementation/evaluation
 - **Key traits**: SOLID-focused, DRY enforcement, complexity analysis, design pattern expertise
-- **Integration**: Frontend Developer Agent utilizes Code Quality Specialist modes.planning/implementation during PLAN/ACT modes. Code Reviewer Agent utilizes Code Quality Specialist modes.evaluation during EVAL mode code quality assessment
+- **Integration**: Planning Agents (Solution Architect, Technical Planner) utilize Code Quality Specialist modes.planning during PLAN mode; the resolved implementation agent utilizes modes.implementation during ACT mode. Code Reviewer Agent utilizes Code Quality Specialist modes.evaluation during EVAL mode code quality assessment
 
 **Architecture Specialist** (`.ai-rules/agents/architecture-specialist.json`)
 - **Expertise**: Layer boundaries, dependency direction, type safety, pure/impure separation
@@ -1332,8 +1358,8 @@ Specialized agents available in `.ai-rules/agents/` directory:
 **Code Quality Specialist** (`@.ai-rules/agents/code-quality-specialist.json`)
 
 ✅ **Use for (Integrated with PLAN/ACT/EVAL):**
-- Code quality planning is automatically included in PLAN mode via Primary Developer Agent (modes.planning)
-- Code quality implementation verification is automatically included in ACT mode via Primary Developer Agent (modes.implementation)
+- Code quality planning is automatically included in PLAN mode via the selected Planning Agent (Solution Architect or Technical Planner) (modes.planning)
+- Code quality implementation verification is automatically included in ACT mode via the resolved implementation agent (Software Engineer or domain specialist) (modes.implementation)
 - Code quality assessment is automatically included in EVAL mode via Code Reviewer Agent (modes.evaluation)
 - SOLID principles planning/verification/review
 - DRY strategy planning/verification/review
@@ -1344,7 +1370,7 @@ Specialized agents available in `.ai-rules/agents/` directory:
 - Code quality planning is part of PLAN mode mandatory perspectives
 - Code quality implementation verification is part of ACT mode mandatory perspectives
 - Code quality evaluation is part of EVAL mode mandatory perspectives
-- Primary Developer Agent references Code Quality Specialist modes.planning/implementation during PLAN/ACT modes
+- Planning Agents (Solution Architect, Technical Planner) reference Code Quality Specialist modes.planning during PLAN mode; the resolved implementation agent references modes.implementation during ACT mode
 - Code Reviewer Agent references Code Quality Specialist modes.evaluation during EVAL mode
 - Reference SOLID principles, DRY, complexity metrics
 - Provide specific planning/verification/review recommendations

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

@@ -81,6 +81,65 @@ 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.
+
+### Conductor vs Worker Context (MANDATORY distinction)
+
+The "Implementation → taskMaestro only" rule applies to the **conductor** (top-level orchestration session). Workers running inside a taskMaestro pane operate under different rules because they already own an isolated worktree.
+
+| Layer | Context | Dispatch Tool | Rationale |
+|-------|---------|---------------|-----------|
+| Conductor → implementation | Outer orchestration session | **taskMaestro only** | Workers need worktree isolation + pre-push checks + visual monitoring |
+| Conductor → read-only research | Outer orchestration session | SubAgent allowed | No file mutations, safe to background |
+| **Worker → internal tasks** | Inside a taskMaestro pane | **SubAgent encouraged** | Worker owns its worktree; file-conflict rationale does not apply. Use Explore/Plan subagents for parallel research or context protection. |
+
+**Why workers can use sub-agents freely:**
+
+1. Each worker operates in an isolated git worktree — no file conflict with other workers
+2. Sub-agents within a worker inherit the worker's worktree, so they share the same isolation boundary
+3. Workers often benefit from parallel read-only research (Explore) or context-protected work before committing
+
+**Examples of good worker-internal sub-agent usage:**
+
+- Dispatch `Explore` sub-agent to survey existing patterns before writing code
+- Dispatch `Plan` sub-agent to draft implementation approach, then act on the plan directly
+- Dispatch multiple read-only sub-agents in parallel to gather context from different parts of the codebase
+
+**What workers still must NOT do:**
+
+- Dispatch sub-agents that modify files in **sibling** worktrees (impossible with proper isolation, but worth stating)
+- Dispatch sub-agents to create PRs on their behalf (the worker owns its PR)
+
+## 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: