devflow-kit 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -5,6 +5,42 @@ All notable changes to DevFlow will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.6.0] - 2026-03-19
+
+### Added
+- **Ambient agent orchestration**: ORCHESTRATED tier spawns agent pipelines for IMPLEMENT, DEBUG, PLAN intents
+- **Orchestration skills**: `implementation-orchestration`, `debug-orchestration`, `plan-orchestration` for ambient agent pipelines
+- **`knowledge-persistence` skill** (#145) — extraction procedure, lock protocol, loading instructions for project knowledge
+- **Knowledge loading phase** (#145) — `/debug`, `/specify`, `/self-review` now load project knowledge at startup
+- **Pitfall recording phase** (#145) — `/code-review`, `/resolve` record pitfalls to `.memory/knowledge/pitfalls.md`
+- **Knowledge directory** (#145) — `.memory/knowledge/` with `decisions.md` (ADR-NNN, append-only) and `pitfalls.md` (area-specific gotchas)
+
+### Changed
+- **Ambient mode**: Three depth tiers (QUICK/GUIDED/ORCHESTRATED) replacing old QUICK/GUIDED/ELEVATE
+- **Ambient mode**: GUIDED tier for small-scope IMPLEMENT (≤2 files), simple DEBUG, focused PLAN, and REVIEW — main session with skills + Simplifier
+- **Ambient mode**: BUILD intent renamed to IMPLEMENT for clarity
+- **Coder agent**: Added `test-driven-development` and `search-first` to permanent skills
+- **Command phase numbering** (#145) — renumbered fractional phases to sequential integers across 12 command files
+
+### Fixed
+- **Agent metadata** (#146) — fixed `subagent_type` in debug, added missing YAML frontmatter
+- **Plugin count** (#146) — corrected to "8 core + 9 optional"
+- **Skills catalog** (#146) — cataloged 3 missing skills in reference
+- **Debug command** (#147) — removed non-standard `name=` parameter
+- **Plugin descriptions** (#147, #148) — synced across plugin.json, plugins.ts, marketplace.json
+- **Simplifier agent** (#148) — added Output/Boundaries sections
+- **Plugin metadata** (#148) — added homepage/repository/license/keywords to 3 plugins
+
+### Removed
+- **`/ambient` command**: Ambient mode is now hook-only. Use `devflow ambient --enable` to activate.
+
+### Behavioral Changes
+- EXPLORE intent now always classifies as QUICK (was split QUICK/GUIDED)
+- Simple text edits ("Update the README") classify as QUICK (was BUILD/GUIDED)
+- Debug agent budget cap removed — agents scale to investigation needs
+
+---
+
 ## [1.5.0] - 2026-03-13
 
 ### Added
@@ -866,6 +902,7 @@ devflow init
 ---
 
 [Unreleased]: https://github.com/dean0x/devflow/compare/v1.4.0...HEAD
+[1.6.0]: https://github.com/dean0x/devflow/compare/v1.5.0...v1.6.0
 [1.5.0]: https://github.com/dean0x/devflow/compare/v1.4.0...v1.5.0
 [1.4.0]: https://github.com/dean0x/devflow/compare/v1.3.3...v1.4.0
 [1.3.3]: https://github.com/dean0x/devflow/compare/v1.3.2...v1.3.3

package/README.md

@@ -24,7 +24,7 @@ DevFlow adds structured commands that handle the full lifecycle: specify feature
 - **Full-lifecycle implementation** — spec, explore, plan, code, validate, refine in one command
 - **Automatic session memory** — survives restarts, `/clear`, and context compaction
 - **Parallel debugging** — competing hypotheses investigated simultaneously
-- **31 quality skills** — 9 auto-activating core, 8 optional language/ecosystem, plus specialized review and agent skills
+- **35 quality skills** — 9 auto-activating core, 8 optional language/ecosystem, plus specialized review, agent, and orchestration skills
 
 ## Quick Start
 
@@ -48,7 +48,7 @@ Then in Claude Code:
 | `devflow-resolve` | `/resolve` | Process review issues — fix or defer to tech debt |
 | `devflow-debug` | `/debug` | Parallel hypothesis debugging |
 | `devflow-self-review` | `/self-review` | Self-review workflow (Simplifier + Scrutinizer) |
-| `devflow-ambient` | `/ambient` | Ambient mode — auto-loads relevant skills based on each prompt |
+| `devflow-ambient` | (hook) | Ambient mode — intent classification with agent orchestration |
 | `devflow-core-skills` | (auto) | Auto-activating quality enforcement skills |
 
 ## Command Details
@@ -198,7 +198,10 @@ DevFlow creates project documentation in `.docs/` and working memory in `.memory
 .memory/
 ├── WORKING-MEMORY.md         # Auto-maintained by Stop hook
 ├── PROJECT-PATTERNS.md       # Accumulated patterns across sessions
-└── backup.json               # Pre-compact git state snapshot
+├── backup.json               # Pre-compact git state snapshot
+└── knowledge/
+    ├── decisions.md           # Architectural decisions (ADR-NNN, append-only)
+    └── pitfalls.md            # Known pitfalls (area-specific gotchas)
 ```
 
 ## Workflow Examples

package/dist/commands/ambient.js

@@ -122,7 +122,7 @@ export const ambientCommand = new Command('ambient')
         }
         await fs.writeFile(settingsPath, updated, 'utf-8');
         p.log.success('Ambient mode enabled — UserPromptSubmit hook registered');
-        p.log.info(color.dim('Relevant skills will now auto-load based on each prompt'));
+        p.log.info(color.dim('Skills auto-load and agents orchestrate based on each prompt'));
     }
     if (options.disable) {
         const updated = removeAmbientHook(settingsContent);

package/dist/commands/init.js

@@ -62,7 +62,7 @@ export const initCommand = new Command('init')
     .option('--plugin <names>', 'Install specific plugin(s), comma-separated (e.g., implement,code-review)')
     .option('--teams', 'Enable Agent Teams (peer debate, adversarial review)')
     .option('--no-teams', 'Disable Agent Teams (use parallel subagents instead)')
-    .option('--ambient', 'Enable ambient mode (auto-loads relevant skills for every prompt)')
+    .option('--ambient', 'Enable ambient mode (classifies intent, loads skills, orchestrates agents)')
     .option('--no-ambient', 'Disable ambient mode')
     .option('--memory', 'Enable working memory (session context preservation)')
     .option('--no-memory', 'Disable working memory hooks')
@@ -176,7 +176,7 @@ export const initCommand = new Command('init')
         const ambientChoice = await p.select({
             message: 'Enable ambient mode?',
             options: [
-                { value: true, label: 'Yes (Recommended)', hint: 'Auto-loads relevant skills for each prompt' },
+                { value: true, label: 'Yes (Recommended)', hint: 'Classifies intent, loads skills, orchestrates agents' },
                 { value: false, label: 'No', hint: 'Full control — load skills manually' },
             ],
         });

package/dist/plugins.js

@@ -7,59 +7,59 @@
 export const DEVFLOW_PLUGINS = [
     {
         name: 'devflow-core-skills',
-        description: 'Auto-activating quality enforcement (foundation layer)',
+        description: 'Auto-activating quality enforcement skills - foundation layer for all DevFlow plugins',
         commands: [],
         agents: [],
         skills: ['core-patterns', 'docs-framework', 'git-safety', 'git-workflow', 'github-patterns', 'input-validation', 'search-first', 'test-driven-development', 'test-patterns'],
     },
     {
         name: 'devflow-specify',
-        description: 'Interactive feature specification',
+        description: 'Interactive feature specification - creates well-defined GitHub issues',
         commands: ['/specify'],
         agents: ['skimmer', 'synthesizer'],
         skills: ['agent-teams'],
     },
     {
         name: 'devflow-implement',
-        description: 'Complete task implementation workflow',
+        description: 'Complete task implementation workflow with exploration, planning, and coding',
         commands: ['/implement'],
         agents: ['git', 'skimmer', 'synthesizer', 'coder', 'simplifier', 'scrutinizer', 'shepherd', 'validator'],
-        skills: ['agent-teams', 'implementation-patterns', 'self-review'],
+        skills: ['agent-teams', 'implementation-patterns', 'knowledge-persistence', 'self-review'],
     },
     {
         name: 'devflow-code-review',
-        description: 'Comprehensive code review',
+        description: 'Comprehensive code review with parallel specialized agents',
         commands: ['/code-review'],
         agents: ['git', 'reviewer', 'synthesizer'],
-        skills: ['agent-teams', 'architecture-patterns', 'complexity-patterns', 'consistency-patterns', 'database-patterns', 'dependencies-patterns', 'documentation-patterns', 'performance-patterns', 'regression-patterns', 'review-methodology', 'security-patterns', 'test-patterns'],
+        skills: ['agent-teams', 'architecture-patterns', 'complexity-patterns', 'consistency-patterns', 'database-patterns', 'dependencies-patterns', 'documentation-patterns', 'knowledge-persistence', 'performance-patterns', 'regression-patterns', 'review-methodology', 'security-patterns', 'test-patterns'],
     },
     {
         name: 'devflow-resolve',
-        description: 'Process and fix review issues',
+        description: 'Process and fix code review issues with risk assessment',
         commands: ['/resolve'],
         agents: ['git', 'resolver', 'simplifier'],
-        skills: ['agent-teams', 'implementation-patterns', 'security-patterns'],
+        skills: ['agent-teams', 'implementation-patterns', 'knowledge-persistence', 'security-patterns'],
     },
     {
         name: 'devflow-debug',
-        description: 'Debugging with competing hypotheses',
+        description: 'Debugging workflows with competing hypothesis investigation using agent teams',
         commands: ['/debug'],
-        agents: ['git'],
-        skills: ['agent-teams', 'git-safety'],
+        agents: ['git', 'synthesizer'],
+        skills: ['agent-teams', 'git-safety', 'knowledge-persistence'],
     },
     {
         name: 'devflow-self-review',
-        description: 'Self-review workflow (Simplifier + Scrutinizer)',
+        description: 'Self-review workflow: Simplifier + Scrutinizer for code quality',
         commands: ['/self-review'],
         agents: ['simplifier', 'scrutinizer', 'validator'],
         skills: ['self-review', 'core-patterns'],
     },
     {
         name: 'devflow-ambient',
-        description: 'Ambient mode — auto-loads relevant skills based on each prompt',
+        description: 'Ambient mode — intent classification with proportional agent orchestration',
         commands: ['/ambient'],
-        agents: [],
-        skills: ['ambient-router'],
+        agents: ['coder', 'validator', 'simplifier', 'scrutinizer', 'shepherd', 'skimmer', 'reviewer'],
+        skills: ['ambient-router', 'implementation-orchestration', 'debug-orchestration', 'plan-orchestration'],
     },
     {
         name: 'devflow-audit-claude',
@@ -71,7 +71,7 @@ export const DEVFLOW_PLUGINS = [
     },
     {
         name: 'devflow-typescript',
-        description: 'TypeScript language patterns (type safety, generics, utility types)',
+        description: 'TypeScript language patterns - type safety, generics, utility types, type guards',
         commands: [],
         agents: [],
         skills: ['typescript'],
@@ -79,7 +79,7 @@ export const DEVFLOW_PLUGINS = [
     },
     {
         name: 'devflow-react',
-        description: 'React framework patterns (hooks, state, composition, performance)',
+        description: 'React framework patterns - hooks, state management, composition, performance',
         commands: [],
         agents: [],
         skills: ['react'],
@@ -87,7 +87,7 @@ export const DEVFLOW_PLUGINS = [
     },
     {
         name: 'devflow-accessibility',
-        description: 'Web accessibility patterns (WCAG, ARIA, keyboard navigation)',
+        description: 'Web accessibility patterns - WCAG compliance, ARIA roles, keyboard navigation, focus management',
         commands: [],
         agents: [],
         skills: ['accessibility'],
@@ -95,7 +95,7 @@ export const DEVFLOW_PLUGINS = [
     },
     {
         name: 'devflow-frontend-design',
-        description: 'Frontend design patterns (typography, color, spacing, motion)',
+        description: 'Frontend design patterns - typography, color systems, spacing, motion, responsive design',
         commands: [],
         agents: [],
         skills: ['frontend-design'],
@@ -103,7 +103,7 @@ export const DEVFLOW_PLUGINS = [
     },
     {
         name: 'devflow-go',
-        description: 'Go language patterns (error handling, interfaces, concurrency)',
+        description: 'Go language patterns - error handling, interfaces, concurrency, package design',
         commands: [],
         agents: [],
         skills: ['go'],
@@ -111,7 +111,7 @@ export const DEVFLOW_PLUGINS = [
     },
     {
         name: 'devflow-java',
-        description: 'Java language patterns (records, sealed classes, composition)',
+        description: 'Java language patterns - records, sealed classes, composition, modern Java features',
         commands: [],
         agents: [],
         skills: ['java'],
@@ -119,7 +119,7 @@ export const DEVFLOW_PLUGINS = [
     },
     {
         name: 'devflow-python',
-        description: 'Python language patterns (type hints, protocols, data modeling)',
+        description: 'Python language patterns - type hints, protocols, dataclasses, async programming',
         commands: [],
         agents: [],
         skills: ['python'],
@@ -127,7 +127,7 @@ export const DEVFLOW_PLUGINS = [
     },
     {
         name: 'devflow-rust',
-        description: 'Rust language patterns (ownership, error handling, type system)',
+        description: 'Rust language patterns - ownership, borrowing, error handling, type-driven design',
         commands: [],
         agents: [],
         skills: ['rust'],

package/dist/utils/post-install.js

@@ -425,11 +425,16 @@ export async function createMemoryDir(verbose, cwd) {
     const memoryDir = path.join(cwd ?? process.cwd(), '.memory');
     try {
         await fs.mkdir(memoryDir, { recursive: true });
+        await fs.mkdir(path.join(memoryDir, 'knowledge'), { recursive: true });
         if (verbose) {
             p.log.success('.memory/ directory ready');
         }
     }
-    catch { /* may already exist */ }
+    catch (e) {
+        if (verbose) {
+            p.log.warn(`Failed to create .memory/ directory: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
 }
 /**
  * Migrate memory files from .docs/ to .memory/.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devflow-kit",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Agentic Development Toolkit for Claude Code - Enhance AI-assisted development with intelligent commands and workflows",
   "type": "module",
   "bin": {

package/plugins/devflow-accessibility/.claude-plugin/plugin.json

@@ -4,7 +4,7 @@
   "author": {
     "name": "Dean0x"
   },
-  "version": "1.5.0",
+  "version": "1.6.0",
   "homepage": "https://github.com/dean0x/devflow",
   "repository": "https://github.com/dean0x/devflow",
   "license": "MIT",

package/plugins/devflow-ambient/.claude-plugin/plugin.json

@@ -1,12 +1,33 @@
 {
   "name": "devflow-ambient",
-  "description": "Ambient mode — auto-loads relevant skills for every prompt",
+  "description": "Ambient mode — intent classification with proportional agent orchestration",
   "author": {
     "name": "Dean0x"
   },
-  "version": "1.5.0",
-  "agents": [],
+  "version": "1.6.0",
+  "homepage": "https://github.com/dean0x/devflow",
+  "repository": "https://github.com/dean0x/devflow",
+  "license": "MIT",
+  "keywords": [
+    "ambient",
+    "intent",
+    "classification",
+    "orchestration",
+    "agents"
+  ],
+  "agents": [
+    "coder",
+    "validator",
+    "simplifier",
+    "scrutinizer",
+    "shepherd",
+    "skimmer",
+    "reviewer"
+  ],
   "skills": [
-    "ambient-router"
+    "ambient-router",
+    "implementation-orchestration",
+    "debug-orchestration",
+    "plan-orchestration"
   ]
 }

package/plugins/devflow-ambient/README.md

@@ -1,23 +1,8 @@
 # devflow-ambient
 
-Ambient mode — auto-loads relevant skills based on each prompt, no explicit commands needed.
+Ambient mode — classifies intent and applies proportional effort via a `UserPromptSubmit` hook. No slash command — ambient mode activates automatically on every prompt when enabled.
 
-## Command
-
-### `/ambient`
-
-Classify user intent and apply proportional skill enforcement to any prompt.
-
-```bash
-/ambient add a login form          # BUILD/GUIDED — loads TDD + implementation-patterns
-/ambient fix the auth error        # DEBUG/GUIDED — loads test-patterns + core-patterns
-/ambient where is the config?      # EXPLORE/QUICK — responds normally, zero overhead
-/ambient refactor the auth system  # BUILD/ELEVATE — suggests /implement
-```
-
-## Always-On Mode
-
-Enable ambient classification on every prompt without typing `/ambient`:
+## Activation
 
 ```bash
 devflow ambient --enable    # Register UserPromptSubmit hook
@@ -25,25 +10,59 @@ devflow ambient --disable   # Remove hook
 devflow ambient --status    # Check if enabled
 ```
 
-When enabled, a `UserPromptSubmit` hook injects a classification preamble before every prompt. Slash commands (`/implement`, `/code-review`, etc.) and short confirmations ("yes", "ok") are skipped automatically.
+When enabled, the hook injects a classification preamble before every prompt. Slash commands (`/implement`, `/code-review`, etc.) and short confirmations ("yes", "ok") are skipped automatically. Git operations (`commit`, `push`, `merge`, etc.) are fast-pathed to zero overhead.
 
 ## How It Works
 
-1. **Classify intent** — BUILD, DEBUG, REVIEW, PLAN, EXPLORE, or CHAT
-2. **Classify depth** — QUICK (zero overhead), GUIDED (2-3 skills), or ELEVATE (workflow nudge)
+1. **Classify intent** — IMPLEMENT, DEBUG, REVIEW, PLAN, EXPLORE, or CHAT
+2. **Classify depth** — QUICK, GUIDED, or ORCHESTRATED (scope-based)
 3. **Apply proportionally**:
-   - QUICK: respond normally
-   - GUIDED: load relevant skills, enforce TDD for BUILD
-   - ELEVATE: respond + recommend full workflow command
+   - QUICK: respond normally (zero overhead)
+   - GUIDED: load skills, implement in main session, spawn Simplifier after code changes
+   - ORCHESTRATED: load skills, orchestrate full agent pipeline
+
+## Three-Tier Classification
+
+| Depth | When | What Happens |
+|-------|------|-------------|
+| QUICK | Chat, exploration, git ops, config, trivial edits | Zero overhead — respond normally |
+| GUIDED | Small-scope IMPLEMENT (≤2 files), clear DEBUG, focused PLAN, REVIEW | Load skills → main session works → Simplifier cleanup |
+| ORCHESTRATED | Large-scope IMPLEMENT (>2 files), vague DEBUG, system-level PLAN | Load skills → spawn agent pipeline |
+
+### Intent × Depth Matrix
+
+| Intent | GUIDED | ORCHESTRATED |
+|--------|--------|-------------|
+| IMPLEMENT | ≤2 files, single module | >2 files, multi-module |
+| DEBUG | Clear error with stack trace/location | Vague/cross-cutting bug |
+| PLAN | Focused design question | System-level architecture |
+| REVIEW | Always GUIDED | — |
+
+## GUIDED Behavior
+
+Skills are loaded via the Skill tool and work happens in the main session:
+
+| Intent | Skills | Main Session Work | Post-Work |
+|--------|--------|-------------------|-----------|
+| IMPLEMENT | test-driven-development, implementation-patterns, search-first | Implement with TDD | `Task(subagent_type="Simplifier")` |
+| DEBUG | core-patterns, test-patterns | Investigate, diagnose, fix | `Task(subagent_type="Simplifier")` |
+| PLAN | implementation-patterns, core-patterns | Explore and design | — |
+| REVIEW | self-review, core-patterns | Review directly | — |
+
+## ORCHESTRATED Pipelines
 
-## Depth Tiers
+| Intent | Pipeline |
+|--------|----------|
+| IMPLEMENT | Pre-flight → Coder → Validator → Simplifier → Scrutinizer → Shepherd |
+| DEBUG | Hypotheses → parallel Explores → convergence → report → offer fix |
+| PLAN | Skimmer → Explores → Plan agent → gap validation |
 
-| Depth | When | Overhead |
-|-------|------|----------|
-| QUICK | Chat, simple exploration, git/devops ops, single-word confirmations | ~0 tokens |
-| GUIDED | BUILD/DEBUG/REVIEW/PLAN, 1-5 file scope | ~500-1000 tokens (skill reads) |
-| ELEVATE | Multi-file, architectural, system-wide scope | ~0 extra tokens (nudge only) |
+These are lightweight variants of `/implement`, `/debug`, and the Plan phase of `/implement` — focused on the immediate task without full lifecycle features (PR creation, knowledge persistence, retry loops).
 
 ## Skills
 
 - `ambient-router` — Intent + depth classification, skill selection matrix
+- `test-driven-development` — TDD enforcement for IMPLEMENT (GUIDED + ORCHESTRATED)
+- `implementation-orchestration` — Agent pipeline for IMPLEMENT/ORCHESTRATED
+- `debug-orchestration` — Agent pipeline for DEBUG/ORCHESTRATED
+- `plan-orchestration` — Agent pipeline for PLAN/ORCHESTRATED

package/plugins/devflow-ambient/agents/coder.md

@@ -0,0 +1,135 @@
+---
+name: Coder
+description: Autonomous task implementation on feature branch. Implements, tests, and commits.
+model: inherit
+skills: core-patterns, git-safety, implementation-patterns, git-workflow, test-patterns, test-driven-development, search-first, input-validation
+---
+
+# Coder Agent
+
+You are an autonomous implementation specialist working on a feature branch. You receive a task with an execution plan from the orchestrator and implement it completely, including testing and committing. You operate independently, making implementation decisions without requiring approval for each step.
+
+## Input Context
+
+You receive from orchestrator:
+- **TASK_ID**: Unique identifier (e.g., "task-2025-01-15_1430")
+- **TASK_DESCRIPTION**: What to implement
+- **BASE_BRANCH**: Branch this feature branch was created from (PR target)
+- **EXECUTION_PLAN**: Synthesized plan with steps, files, tests
+- **PATTERNS**: Codebase patterns to follow
+- **CREATE_PR**: Whether to create PR when done (true/false)
+
+**Domain hint** (optional):
+- **DOMAIN**: `backend` | `frontend` | `tests` | `fullstack` - Load/apply relevant domain skills
+
+**Sequential execution context** (when part of multi-Coder chain):
+- **PRIOR_PHASE_SUMMARY**: Implementation summary from previous Coder (see format below)
+- **FILES_FROM_PRIOR_PHASE**: Files created that must be read and understood
+- **HANDOFF_REQUIRED**: true if another Coder follows this one
+
+## Responsibilities
+
+1. **Orient on branch state** (always, before any implementation):
+   - Run `git log --oneline --stat -n 10` to scan recent commit history on this branch
+   - Run `git status` and `git diff --stat` and `git diff --cached --stat` to see uncommitted/unstaged work
+   - Cross-reference changed files against EXECUTION_PLAN to identify what's relevant to your task
+   - Read those relevant files to understand interfaces, types, naming conventions, error handling, and testing patterns established by prior work
+   - If PRIOR_PHASE_SUMMARY is provided, use it to validate your understanding — actual code is authoritative, summaries are supplementary
+   - If `.memory/knowledge/decisions.md` exists, read it. Apply prior architectural decisions relevant to this task. Avoid contradicting accepted decisions without documenting a new ADR.
+   - If `.memory/knowledge/pitfalls.md` exists, scan for pitfalls in files you're about to modify.
+
+2. **Load domain skills**: Based on DOMAIN hint and files in scope, dynamically load relevant language/ecosystem skills by reading their SKILL.md. Only load skills that are installed:
+   - `backend` (TypeScript): Read `~/.claude/skills/typescript/SKILL.md`, `~/.claude/skills/input-validation/SKILL.md`
+   - `backend` (Go): Read `~/.claude/skills/go/SKILL.md`
+   - `backend` (Java): Read `~/.claude/skills/java/SKILL.md`
+   - `backend` (Python): Read `~/.claude/skills/python/SKILL.md`
+   - `backend` (Rust): Read `~/.claude/skills/rust/SKILL.md`
+   - `frontend`: Read `~/.claude/skills/react/SKILL.md`, `~/.claude/skills/typescript/SKILL.md`, `~/.claude/skills/accessibility/SKILL.md`, `~/.claude/skills/frontend-design/SKILL.md`
+   - `tests`: Read `~/.claude/skills/test-patterns/SKILL.md`, `~/.claude/skills/typescript/SKILL.md`
+   - `fullstack`: Combine backend + frontend skills
+   - If a Read fails (skill not installed), skip it silently and continue.
+
+3. **Implement the plan**: Work through execution steps systematically, creating and modifying files. Follow existing patterns. Type everything. Use Result types if codebase uses them.
+
+4. **Write tests**: Add tests for new functionality. Cover happy path, error cases, and edge cases. Follow existing test patterns.
+
+5. **Run tests**: Execute the test suite. Fix any failures. All tests must pass before proceeding.
+
+6. **Commit and push**: Create atomic commits with clear messages. Reference TASK_ID. Push to remote.
+
+7. **Create PR** (if CREATE_PR=true): Create pull request against BASE_BRANCH with summary and testing notes.
+
+8. **Generate handoff** (if HANDOFF_REQUIRED=true): Include implementation summary for next Coder (see Output section).
+
+## Principles
+
+1. **Work on feature branch** - All operations happen on the current feature branch
+2. **Branch orientation first** - Always orient on branch state before writing code; actual code is authoritative over summaries
+3. **Pattern discovery first** - Before writing code, find similar implementations and match their conventions
+4. **Be decisive** - Make confident implementation choices. Don't present alternatives or ask permission for tactical decisions
+5. **Follow existing patterns** - Match codebase style, don't invent new conventions
+6. **Small, focused changes** - Don't scope creep beyond the plan
+7. **Fail honestly** - If blocked, report clearly with what was completed
+
+## Output
+
+Return structured completion status:
+
+```markdown
+## Coder Report: {TASK_ID}
+
+### Status: COMPLETE | FAILED | BLOCKED
+
+### Implementation
+- Files created: {n}
+- Files modified: {n}
+- Tests added: {n}
+
+### Commits
+- {sha} {message}
+
+### PR (if created)
+- URL: {pr_url}
+
+### Key Decisions (if any)
+- {Decision}: {rationale}
+
+### Blockers (if any)
+{Description of blocker or failure with recommendation}
+```
+
+**If HANDOFF_REQUIRED=true**, append implementation summary for next Coder:
+
+```markdown
+## Phase {N} Implementation Summary
+
+### Files Created/Modified
+- `path/file.ts` - {purpose, key exports}
+
+### Patterns Established
+- Naming: {e.g., "UserRepository pattern for data access"}
+- Error handling: {e.g., "Result types with DomainError"}
+- Testing: {e.g., "Integration tests in tests/integration/"}
+
+### Key Decisions
+- {Decision with rationale}
+
+### Integration Points for Next Phase
+- {Interfaces to implement against}
+- {Functions to call}
+- {Types to import}
+```
+
+## Boundaries
+
+**Escalate to orchestrator:**
+- Discovered dependency on another task
+- Scope significantly larger than planned
+- Breaking changes to shared interfaces
+- Prior phase code is broken or incomplete (in sequential execution)
+
+**Never:**
+- Switch branches during implementation
+- Push to branches other than your feature branch
+- Merge PRs (orchestrator handles this)
+- Trust handoff summaries without reading actual code