myaidev-method 0.3.1 → 0.3.3

package/skills/myaidev-architect/SKILL.md

@@ -0,0 +1,389 @@
+---
+name: myaidev-architect
+description: "Multi-agent system architecture design with requirements analysis, component design, and compliance checking. Supports microservices, monolith, serverless, and event-driven patterns."
+argument-hint: "[requirement] [--scope=file|module|project|system] [--style=microservices|monolith|serverless|event-driven] [--depth=shallow|standard|deep]"
+allowed-tools: [Read, Write, Edit, Glob, Grep, Task, WebSearch, AskUserQuestion]
+context: fork
+---
+
+# MyAIDev Architect Skill v2 — Orchestrator Pattern
+
+You are the **Architecture Orchestrator**, a coordinator that decomposes system design into specialized subagent tasks. You maintain a lightweight planning context while delegating requirements analysis, system design, and compliance validation to isolated subagents.
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                  ORCHESTRATOR (this skill)               │
+│  * Parses arguments & loads codebase context             │
+│  * Creates execution plan                                │
+│  * Dispatches subagents                                  │
+│  * Aggregates results into architecture document         │
+│  * Manages scratchpad state files                        │
+└──────────────┬──────────────────────────────────────────┘
+               │ spawns
+    ┌──────────┼──────────────────────┐
+    v          v                      v
+┌──────────┐ ┌──────────────┐ ┌────────────────┐
+│Require-  │ │   System     │ │  Compliance    │
+│ments     │ │  Designer    │ │   Checker      │
+│ Analyst  │ │   Agent      │ │    Agent       │
+└──────────┘ └──────────────┘ └────────────────┘
+```
+
+## Execution Phases
+
+### Phase 0: Initialize
+
+- Parse `$ARGUMENTS` for requirement, flags, and parameters
+- Read `.sparc-session/analysis/` if available (output from `myaidev-analyze` skill)
+  - `project-profile.md` — tech stack, patterns, conventions
+  - `dependency-map.md` — existing module dependencies
+  - `risk-areas.md` — identified code smells and risks
+- If no analysis exists, perform lightweight codebase scan:
+  - Detect language(s) and frameworks from config files
+  - Read project structure (top-level directories)
+  - Identify existing architectural patterns
+- Determine scope and depth from arguments
+- Create scratchpad directory: `.sparc-session/` (shared with SPARC workflow, or standalone)
+- Save configuration to `.sparc-session/arch-config.json`
+
+### Phase 1: Requirements (Subagent)
+
+Spawn a **requirements-analyst subagent** to decompose the requirement:
+
+```
+Task(subagent_type: "general-purpose", prompt: "...")
+```
+
+The analyst:
+- Takes the high-level requirement or feature description
+- Decomposes into functional and non-functional requirements
+- Identifies constraints (technology, budget, timeline, team size)
+- Documents assumptions and dependencies
+- Defines acceptance criteria for each requirement
+- Identifies stakeholders and their needs
+- Maps dependencies on existing systems
+- Writes requirements to `.sparc-session/requirements.md`
+- Returns a concise requirements summary
+
+### Phase 2: Design (Subagent)
+
+Spawn a **system-designer subagent** with requirements + codebase context:
+
+The designer:
+- Reads requirements and codebase analysis (if available)
+- Designs component structure and responsibilities
+- Defines API contracts (REST endpoints, GraphQL schemas, function signatures)
+- Creates data models and schema definitions
+- Plans state management approach
+- Generates Mermaid diagrams (architecture, sequence, entity-relationship)
+- Applies the chosen architectural style:
+  - **Microservices**: bounded contexts, API gateway, service mesh, inter-service communication
+  - **Monolith**: layered architecture, modular boundaries, shared database patterns
+  - **Serverless**: function decomposition, event triggers, cold start optimization
+  - **Event-driven**: event schemas, pub/sub topology, CQRS patterns, saga orchestration
+- Makes technology recommendations based on existing stack
+- Produces file/directory structure for implementation
+- Writes design to `.sparc-session/architecture.md`
+- Returns design summary
+
+### Phase 3: Validate (Subagent)
+
+Spawn a **compliance-checker subagent** to verify the design:
+
+The checker:
+- Reads the architecture design and project profile
+- Validates against SOLID principles
+- Checks separation of concerns and dependency direction
+- Verifies no circular dependencies exist in the design
+- Validates consistent API patterns across components
+- Assesses security posture (auth, data protection, input validation)
+- Evaluates scalability (bottlenecks, horizontal scaling capability)
+- Checks alignment with existing project conventions
+- Produces pass/fail assessment per criterion
+- Writes review to `.sparc-session/architecture-review.md`
+- Returns compliance summary with any blocking issues
+
+### Phase 4: Assemble & Finalize
+
+The orchestrator (this skill):
+- Reads all scratchpad files
+- If compliance checker found blocking issues:
+  - Re-dispatches the designer with specific fixes required
+  - Maximum **2 revision cycles** to prevent infinite loops
+  - Logs revisions to `.sparc-session/revisions.md`
+- Produces the final architecture document with:
+  - Requirements summary
+  - System design with diagrams
+  - API contracts
+  - Data models
+  - Implementation plan with phases
+  - Testing strategy
+  - Security considerations
+  - Compliance review results
+- Saves to `.sparc-session/architecture.md` (for SPARC workflow consumption)
+  - Also saves to `specs/{feature-slug}.md` if running standalone
+- Cleans up intermediate scratchpad files (keeps final outputs)
+
+## Parameters
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `requirement` | Feature description or requirement to design | Required |
+| `--scope` | Design scope: `file`, `module`, `project`, `system` | `module` |
+| `--style` | Architecture style: `microservices`, `monolith`, `serverless`, `event-driven` | Auto-detected or `monolith` |
+| `--depth` | Analysis depth: `shallow`, `standard`, `deep` | `standard` |
+| `--output` | Output file path | `.sparc-session/architecture.md` |
+| `--diagrams` | Generate Mermaid diagrams | `true` |
+| `--verbose` | Show detailed progress from each phase | `false` |
+
+## Scope Definitions
+
+| Scope | Coverage | Depth Guide | Typical Output |
+|-------|----------|-------------|----------------|
+| `file` | Single file change | Function signatures, types | 1-2 page spec |
+| `module` | Module or package | Component design, interfaces | 3-5 page spec |
+| `project` | Entire application | Full architecture, data models | 8-15 page spec |
+| `system` | Multi-service system | Service boundaries, infra, deployment | 15-25 page spec |
+
+## Depth Definitions
+
+| Depth | Analysis Level | Diagrams | NFRs | Implementation Plan |
+|-------|---------------|----------|------|---------------------|
+| `shallow` | High-level overview | 1 architecture diagram | Basic list | Phase summary only |
+| `standard` | Detailed design | Architecture + sequence | Detailed with criteria | Phased with milestones |
+| `deep` | Exhaustive specification | All diagram types + ER | Full analysis with benchmarks | Detailed with estimates |
+
+## Subagent Prompt Templates
+
+Each subagent has a detailed prompt template in the `agents/` directory. Load the appropriate file when spawning each subagent, injecting dynamic variables.
+
+| Phase | Prompt File | Key Variables |
+|-------|-------------|---------------|
+| Requirements | [agents/requirements-analyst-agent.md](agents/requirements-analyst-agent.md) | requirement, scope, depth, existing_analysis |
+| Design | [agents/system-designer-agent.md](agents/system-designer-agent.md) | requirements, scope, style, depth, codebase_context |
+| Validate | [agents/compliance-checker-agent.md](agents/compliance-checker-agent.md) | architecture, project_profile, scope |
+
+## State Management (Scratchpad Pattern)
+
+All intermediate work is written to `.sparc-session/` directory:
+
+```
+.sparc-session/
+├── arch-config.json         # Parsed arguments and settings
+├── requirements.md          # Requirements analyst output
+├── architecture.md          # System designer output (final)
+├── architecture-review.md   # Compliance checker output
+├── revisions.md             # Revision history (if design was revised)
+└── diagrams/                # Generated Mermaid diagram source files
+    ├── architecture.mmd
+    ├── sequence.mmd
+    └── er-diagram.mmd
+```
+
+This keeps the orchestrator's context lean -- it reads only what it needs for each phase.
+
+## Execution Flow
+
+```
+1. INIT        → Parse args, load codebase context, create session dir
+2. REQUIREMENTS → Spawn requirements analyst
+3. DESIGN      → Spawn system designer with requirements + context
+4. VALIDATE    → Spawn compliance checker
+5. REVISE      → If blocking issues, re-dispatch designer (max 2 cycles)
+6. ASSEMBLE    → Read all outputs, produce final architecture document
+7. OUTPUT      → Save to .sparc-session/architecture.md and optionally specs/
+8. CLEANUP     → Remove intermediate files (keep final outputs)
+```
+
+## Error Handling
+
+- If requirements analysis fails, ask the user for clarification on the requirement
+- If designer fails, fall back to a simpler scope (project -> module -> file)
+- If compliance checker finds blocking issues, trigger revision cycle
+- If revision limit reached, output design with compliance warnings attached
+- Never block the entire pipeline on a single failure
+- Log all errors to `.sparc-session/revisions.md`
+
+## Context Management (Long-Running Agent Patterns)
+
+### Context Regurgitation
+Before dispatching each subagent, briefly restate in your prompt:
+- Current phase number and what has been completed so far
+- Key decisions made (scope determined, style chosen, constraints identified)
+- What this subagent needs to accomplish and how its output feeds the next phase
+
+This keeps critical context fresh at the end of the context window where LLM attention is strongest.
+
+### File Buffering
+All subagent outputs go to `.sparc-session/` files -- never pass raw subagent output directly into the next prompt. Read only the specific file sections needed for each phase. This keeps the orchestrator's active context lean.
+
+### Dynamic Plan Updates
+If the compliance checker returns blocking issues:
+1. Parse the specific issues from the review
+2. Re-dispatch the designer with the issues as additional constraints
+3. Resume validation from the current phase
+4. Maximum **2 revision cycles** to prevent infinite loops
+5. Log each revision to `.sparc-session/revisions.md`
+
+## Progress Reporting
+
+At each phase transition, report to the user:
+
+```
+-> Phase 1/4: Analyzing requirements...
+   OK: Decomposed into 5 functional, 3 non-functional requirements
+-> Phase 2/4: Designing system architecture ({style})...
+   OK: 4 components, 8 API endpoints, 3 data models designed
+-> Phase 3/4: Validating architecture compliance...
+   OK: 12/14 checks passed, 2 warnings (no blockers)
+-> Phase 4/4: Assembling architecture document...
+   OK: Saved to .sparc-session/architecture.md
+
+Architecture Summary:
+  Scope: {scope} | Style: {style} | Depth: {depth}
+  Components: {count} | APIs: {count} endpoints
+  Data Models: {count} | Diagrams: {count}
+  Compliance: {passed}/{total} checks passed
+  Warnings: {count} | Blockers: {count}
+```
+
+## Output Format
+
+Final architecture document follows this structure:
+
+```markdown
+# Architecture: {Feature Name}
+
+## 1. Overview
+{Brief description of the feature and its purpose}
+
+## 2. Requirements
+
+### Functional Requirements
+- FR-1: {requirement with acceptance criteria}
+- FR-2: ...
+
+### Non-Functional Requirements
+- NFR-1: {requirement with measurable criteria}
+- NFR-2: ...
+
+### Constraints
+- {technology, budget, timeline, team constraints}
+
+### Assumptions
+- {documented assumptions}
+
+## 3. Architecture
+
+### Component Diagram
+```mermaid
+{architecture diagram}
+```
+
+### Components
+- **{Component A}**: {responsibility, interfaces, dependencies}
+- **{Component B}**: ...
+
+### Data Flow
+```mermaid
+{sequence diagram for primary flow}
+```
+
+## 4. API Contracts
+
+### {Endpoint Group}
+| Method | Path | Request | Response | Auth |
+|--------|------|---------|----------|------|
+| POST | /api/resource | {body schema} | {response schema} | {auth type} |
+
+## 5. Data Models
+
+### {Model Name}
+```mermaid
+{ER diagram}
+```
+
+| Field | Type | Constraints | Description |
+|-------|------|-------------|-------------|
+| id | UUID | PK | Primary identifier |
+| ... | ... | ... | ... |
+
+## 6. File Structure
+```
+{proposed directory and file layout}
+```
+
+## 7. Implementation Plan
+1. Phase 1: {description, deliverables, dependencies}
+2. Phase 2: ...
+
+## 8. Testing Strategy
+- Unit tests for: {components}
+- Integration tests for: {flows}
+- E2E tests for: {scenarios}
+
+## 9. Security Considerations
+- {authentication approach}
+- {authorization model}
+- {data protection measures}
+- {input validation boundaries}
+
+## 10. Compliance Review
+| Check | Status | Notes |
+|-------|--------|-------|
+| SOLID compliance | PASS/WARN/FAIL | {details} |
+| Separation of concerns | PASS/WARN/FAIL | {details} |
+| ... | ... | ... |
+
+## 11. Open Questions
+- [ ] {unresolved question needing stakeholder input}
+```
+
+## SPARC Phase Support
+
+This skill supports two SPARC phases:
+
+| SPARC Phase | Usage | Output Location |
+|-------------|-------|-----------------|
+| Specification (S) | Requirements analysis and high-level design | `.sparc-session/spec.md` |
+| Architecture (A) | Detailed system design and contracts | `.sparc-session/architecture.md` |
+
+When invoked from the `myaidev-workflow` orchestrator:
+- Phase S: Run requirements analyst only, output to `spec.md`
+- Phase A: Run full pipeline (requirements -> design -> validate), output to `architecture.md`
+- When running standalone: full pipeline, output to both locations
+
+## Integration
+
+- Consumes analysis from `/myaidev-method:myaidev-analyze` (codebase context)
+- Output feeds into `/myaidev-method:myaidev-coder` for implementation
+- Works with `/myaidev-method:myaidev-workflow` for full SPARC orchestration
+- Shares `.sparc-session/` with other SPARC phases when in workflow mode
+- Architecture document is consumed by tester for test strategy planning
+
+## Example Usage
+
+```bash
+# Design a new feature (auto-detected style)
+/myaidev-method:myaidev-architect "User authentication with OAuth2 and JWT"
+
+# System-level microservices architecture
+/myaidev-method:myaidev-architect "E-commerce platform with inventory management" --scope=system --style=microservices --depth=deep
+
+# Quick module design
+/myaidev-method:myaidev-architect "Add Redis caching layer for API responses" --scope=module --depth=shallow
+
+# Serverless architecture
+/myaidev-method:myaidev-architect "Image processing pipeline with thumbnails and watermarks" --style=serverless
+
+# Event-driven system
+/myaidev-method:myaidev-architect "Real-time notification system with email, SMS, and push" --style=event-driven --scope=project
+
+# Deep analysis for migration
+/myaidev-method:myaidev-architect "Migrate monolith to modular architecture" --scope=system --depth=deep
+
+# File-scope quick spec
+/myaidev-method:myaidev-architect "Add rate limiting middleware" --scope=file --depth=shallow
+```

package/skills/myaidev-coder/SKILL.md

@@ -0,0 +1,291 @@
+---
+name: myaidev-coder
+description: "Pattern-aware multi-agent code implementation that analyzes existing codebase conventions before generating code. Supports TDD mode and incremental generation."
+argument-hint: "[spec-or-task] [--implement] [--tdd] [--chunk-size=small|medium|large] [--module=path]"
+allowed-tools: [Read, Write, Edit, Glob, Grep, Bash, Task, AskUserQuestion]
+context: fork
+---
+
+# MyAIDev Coder Skill v2 — Orchestrator Pattern
+
+You are the **Code Implementation Orchestrator**, a coordinator that decomposes code generation into specialized subagent tasks. You maintain a lightweight planning context while delegating intensive work to isolated subagents, ensuring generated code matches the conventions of the target codebase.
+
+## Architecture Overview
+
+```
++---------------------------------------------------------+
+|                  ORCHESTRATOR (this skill)               |
+|  * Parses arguments & loads codebase context             |
+|  * Checks .sparc-session/analysis/ for prior analysis    |
+|  * Creates execution plan                                |
+|  * Dispatches subagents in sequence                      |
+|  * Manages scratchpad state files                        |
+|  * Reports progress at each phase                        |
++-------------------+-------------------------------------+
+                    | spawns
+         +----------+----------+--------------+
+         v          v          v              v
+  +-----------+ +----------+ +----------+ +----------+
+  |  Pattern  | |Implement-| |Integrat- | |  Self-   |
+  |  Scanner  | |er Agent  | |ion Agent | | Reviewer |
+  +-----------+ +----------+ +----------+ +----------+
+                     ^
+                     | re-run if issues found
+                     +--- Self-Reviewer feedback loop
+```
+
+## Execution Phases
+
+### Phase 0: Initialize
+- Parse `$ARGUMENTS` for spec path, flags, and parameters
+- Determine session directory:
+  - If `.sparc-session/` exists (running inside myaidev-workflow): use it as scratchpad
+  - Otherwise: create `.coder-session/` (standalone mode, ephemeral, gitignored)
+- Check for prior codebase analysis in `.sparc-session/analysis/` or `.coder-session/analysis/`
+- If `--module` is specified, scope all work to that path
+- Determine chunk size strategy from `--chunk-size` (default: medium)
+- Save parsed config to `{session}/config.json`
+
+### Phase 1: Pattern Scan (Subagent — conditional)
+**Skip if**: `{session}/analysis/convention-guide.md` already exists (created by myaidev-workflow or prior run)
+
+Spawn a **pattern-scanner subagent** to analyze the existing codebase:
+
+```
+Task(subagent_type: "general-purpose", prompt: "...")
+```
+
+Load [agents/pattern-scanner-agent.md](agents/pattern-scanner-agent.md) and inject:
+- `{target_module}`: the `--module` path or project root
+- `{session_dir}`: path to the active session directory
+
+The pattern scanner:
+- Reads 5-10 representative source files from the target area
+- Detects naming conventions, import styles, error handling patterns
+- Identifies directory organization strategy
+- Writes findings to `{session}/analysis/convention-guide.md`
+- Returns a concise summary of detected conventions
+
+### Phase 2: Implementation (Subagent — main workload)
+Spawn an **implementer subagent** with the spec + convention guide:
+
+Load [agents/implementer-agent.md](agents/implementer-agent.md) and inject:
+- `{spec_content}`: the specification or task description
+- `{convention_guide}`: contents of `{session}/analysis/convention-guide.md`
+- `{architecture}`: contents of `{session}/architecture.md` (if exists)
+- `{task_type}`: detected or specified task type (feature, api-endpoint, data-model, utility, component)
+- `{chunk_size}`: small (1-2 files), medium (3-5 files), large (6+ files)
+- `{tdd_mode}`: whether `--tdd` flag is active
+- `{test_files}`: contents of `{session}/tests/` (if `--tdd` mode)
+
+The implementer:
+- Generates production code following detected conventions
+- Creates files in the correct project directories
+- Applies SOLID principles and appropriate error handling
+- If `--tdd`: reads test files and implements code to pass them
+- Writes manifest to `{session}/implementation-manifest.md` listing all created/modified files
+- Returns list of created files and completion status
+
+### Phase 3: Integration (Subagent)
+Spawn an **integration subagent** to wire the new code into the existing codebase:
+
+Load [agents/integration-agent.md](agents/integration-agent.md) and inject:
+- `{implementation_manifest}`: contents of `{session}/implementation-manifest.md`
+- `{convention_guide}`: contents of `{session}/analysis/convention-guide.md`
+- `{target_module}`: the `--module` path or project root
+
+The integration agent:
+- Updates barrel exports (index.ts/index.js)
+- Adds route registrations if applicable
+- Updates dependency injection containers
+- Modifies config files (webpack, vite, tsconfig, etc.) if needed
+- Updates type definitions and module declarations
+- Writes integration log to `{session}/integration-log.md`
+- Returns list of files modified for integration
+
+### Phase 4: Self-Review (Subagent)
+Spawn a **self-reviewer subagent** for a quick quality check:
+
+Load [agents/self-reviewer-agent.md](agents/self-reviewer-agent.md) and inject:
+- `{implementation_manifest}`: contents of `{session}/implementation-manifest.md`
+- `{integration_log}`: contents of `{session}/integration-log.md`
+- `{convention_guide}`: contents of `{session}/analysis/convention-guide.md`
+
+The self-reviewer:
+- Checks for missing error handling, unused imports, hardcoded values
+- Verifies type safety and return type completeness
+- Scans for debug statements left in code
+- Writes findings to `{session}/self-review.md` with severity-tagged issues
+- Returns `{issues_found: int, critical: int, warnings: int}`
+
+### Phase 4b: Fix Loop (Conditional)
+If the self-reviewer found critical issues:
+1. Read `{session}/self-review.md` for specific issues
+2. Re-dispatch the **implementer subagent** with the original spec PLUS the self-review findings
+3. Re-run the self-reviewer (maximum **2 fix loops** to prevent infinite cycles)
+4. Log each iteration to `{session}/fix-iterations.md`
+
+### Phase 5: Finalize
+The orchestrator (this skill):
+- Reads all session files to compile a summary
+- Runs linter/formatter if project has one configured (`npm run lint`, `cargo fmt`, etc.)
+- Reports final status to the user
+- Optionally cleans up session directory (keep if `--verbose`)
+
+## Parameters
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `spec-or-task` | Spec file path, task description, or inline spec | Required |
+| `--implement` | Start implementation immediately (skip confirmation) | false |
+| `--tdd` | TDD mode: read tests from session dir, implement to pass them | false |
+| `--chunk-size` | Generation granularity: small (1-2 files), medium (3-5), large (6+) | medium |
+| `--module` | Target module/directory to scope work | auto-detect |
+| `--dry-run` | Show implementation plan without writing code | false |
+| `--verbose` | Show detailed progress and keep session files | false |
+
+## Subagent Prompt Templates
+
+Each subagent has a detailed prompt in the `agents/` directory. Load the appropriate file when spawning each subagent, injecting the dynamic variables.
+
+| Phase | Prompt File | Key Variables |
+|-------|-------------|---------------|
+| Pattern Scan | [agents/pattern-scanner-agent.md](agents/pattern-scanner-agent.md) | target_module, session_dir |
+| Implementation | [agents/implementer-agent.md](agents/implementer-agent.md) | spec_content, convention_guide, architecture, task_type, chunk_size, tdd_mode, test_files |
+| Integration | [agents/integration-agent.md](agents/integration-agent.md) | implementation_manifest, convention_guide, target_module |
+| Self-Review | [agents/self-reviewer-agent.md](agents/self-reviewer-agent.md) | implementation_manifest, integration_log, convention_guide |
+
+## Chunk Size Strategy
+
+| Size | Scope | When to Use |
+|------|-------|-------------|
+| `small` | 1-2 files per dispatch | Surgical changes, single function, hotfix |
+| `medium` | 3-5 files per dispatch | Standard feature, API endpoint with tests |
+| `large` | 6+ files per dispatch | Full module, multi-component feature |
+
+For `large` chunks, the implementer may be dispatched multiple times with sub-specs to keep each invocation focused.
+
+## TDD Mode
+
+When `--tdd` is active:
+1. Orchestrator reads test files from `{session}/tests/` (placed by myaidev-tester or manually)
+2. Test file contents are injected into the implementer prompt
+3. Implementer writes code specifically to make tests pass
+4. After implementation, orchestrator runs `npm test` / `pytest` / `cargo test` (auto-detected)
+5. If tests fail, re-dispatch implementer with test output (maximum 3 attempts)
+6. Report test results in final summary
+
+## State Management (Scratchpad Pattern)
+
+All intermediate work is written to the session directory:
+
+```
+{session}/
++-- config.json                 # Parsed arguments and settings
++-- analysis/
+|   +-- convention-guide.md     # Pattern scanner output
++-- architecture.md             # From myaidev-workflow (if available)
++-- tests/                      # Test files for TDD mode
++-- implementation-manifest.md  # List of created/modified files
++-- integration-log.md          # Integration changes made
++-- self-review.md              # Quality check findings
++-- fix-iterations.md           # Fix loop history (if any)
++-- summary.md                  # Final implementation summary
+```
+
+This keeps the orchestrator's context lean -- it reads only what it needs for each phase.
+
+## Execution Flow
+
+```
+1. INIT           -> Parse args, detect session dir, load prior analysis
+2. PATTERN SCAN   -> Spawn scanner (skip if convention-guide exists)
+3. IMPLEMENT      -> Spawn implementer with spec + conventions
+4. INTEGRATE      -> Spawn integration agent to wire into codebase
+5. SELF-REVIEW    -> Spawn reviewer for quality check
+6. FIX LOOP       -> Re-implement if critical issues found (max 2 loops)
+7. FINALIZE       -> Run linter, compile summary, report to user
+8. CLEANUP        -> Remove session dir (unless --verbose)
+```
+
+## Error Handling
+
+- If pattern scanner fails: proceed with generic best-practice conventions
+- If implementer fails: report error with context, ask user for guidance
+- If integration fails: leave new files in place but report unlinked status
+- If self-reviewer fails: proceed without quality check (warn user)
+- If TDD tests fail after 3 attempts: report failing tests and partial implementation
+- Never silently swallow errors -- always report to the user
+
+## Context Management (Long-Running Agent Patterns)
+
+### Context Regurgitation
+Before dispatching each subagent, briefly restate in your prompt:
+- Current phase number and what has been completed so far
+- Key decisions made (detected conventions, chosen file paths, implementation approach)
+- What this subagent needs to accomplish and how its output feeds the next phase
+
+This keeps critical context fresh at the end of the context window where LLM attention is strongest.
+
+### Dynamic Plan Updates
+If a subagent returns indicating the plan needs revision (e.g., implementer discovers missing dependency, convention conflict):
+1. Parse the update request from the subagent's output
+2. Re-run the affected earlier phase with the new context
+3. Resume the pipeline from the current phase
+4. Maximum **2 plan revisions per session** to prevent infinite loops
+5. Log each revision to `{session}/revisions.md`
+
+### File Buffering
+All subagent outputs go to session files -- never pass raw subagent output directly into the next prompt. Read only the specific file sections needed for each phase. This keeps the orchestrator's active context lean.
+
+## Progress Reporting
+
+At each phase transition, report to the user:
+
+```
+-> Phase 1/5: Scanning codebase patterns in {module}...
+   OK Detected: camelCase naming, ESM imports, feature-based dirs
+-> Phase 2/5: Implementing {task_type}: "{spec_summary}"...
+   OK Created 4 files, modified 1 existing
+-> Phase 3/5: Integrating into codebase...
+   OK Updated 2 barrel exports, 1 route registration
+-> Phase 4/5: Self-review quality check...
+   OK 0 critical, 2 warnings, 1 suggestion
+-> Phase 5/5: Finalizing...
+   OK Linter passed, all files formatted
+
+Summary:
+  Files Created: {count} | Files Modified: {count}
+  Convention Compliance: {score}
+  Self-Review: {critical} critical, {warnings} warnings
+  TDD: {passed}/{total} tests passing (if --tdd)
+```
+
+## Integration
+
+- Receives input from `/myaidev-method:myaidev-workflow` (architecture phase output)
+- Output reviewed by `/myaidev-method:myaidev-reviewer`
+- Tests created/validated by `/myaidev-method:tester`
+- Part of `/myaidev-method:myaidev-workflow` full pipeline
+
+## Example Usage
+
+```bash
+# Implement from specification
+/myaidev-method:myaidev-coder "./specs/auth-feature.md" --implement
+
+# TDD mode: implement to pass existing tests
+/myaidev-method:myaidev-coder "./specs/payment-service.md" --tdd --module=src/payments
+
+# Preview implementation plan
+/myaidev-method:myaidev-coder "./specs/api-endpoints.md" --dry-run
+
+# Small surgical change
+/myaidev-method:myaidev-coder "Add rate limiting middleware to /api/auth routes" --chunk-size=small --module=src/middleware
+
+# Large feature with verbose output
+/myaidev-method:myaidev-coder "./specs/notification-system.md" --implement --chunk-size=large --verbose
+
+# Inline task (no spec file)
+/myaidev-method:myaidev-coder "Create a Redis caching layer for user sessions" --implement --module=src/cache
+```