@rajat-rastogi/maestro 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Rajat Rastogi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,254 @@
+# Maestro
+
+**Autonomous AI coding orchestrator.** Maestro reads a markdown plan file, executes each
+task using a fresh Claude Code or GitHub Copilot session, validates after every step,
+commits the result, and runs a multi-phase code review — all without human intervention.
+
+---
+
+## How It Works
+
+```
+Plan File  →  Phase 1: Tasks  →  Phase 2: First Review  →  Phase 3: Second Review  →  Phase 4: Finalize
+               (N tasks,           (single agent,            (multi-agent,               (optional
+                validate +          broad pass)               targeted pass)               cleanup)
+                commit each)
+```
+
+1. **Parse** — Maestro reads your markdown plan and extracts tasks (checkboxes) and
+   validation commands.
+2. **Execute** — Each task is sent to a fresh AI session. The session runs until all
+   checkboxes are marked complete.
+3. **Validate** — After each task, shell validation commands run. On failure, a retry
+   is triggered (up to `task_retry_count`).
+4. **Commit** — A git commit is made after each successful task.
+5. **Review** — Two review phases run over the full diff: Phase 2 catches broad issues,
+   Phase 3 runs multiple specialist agents on targeted concerns.
+6. **Finalize** — Optional cleanup pass (disabled by default).
+
+---
+
+## Prerequisites
+
+- **Node.js ≥ 22**
+- **Git**
+- At least one AI provider:
+  - **Claude Code**: `npm install -g @anthropic-ai/claude-code` — then `claude login`
+  - **GitHub Copilot**: `npm install -g @github/copilot` — then `gh auth login`
+
+---
+
+## Installation
+
+```sh
+npm install -g @rajat-rastogi/maestro
+```
+
+---
+
+## Quick Start
+
+**1. Write a plan file** (`docs/plans/my-feature.md`):
+
+```markdown
+# Plan: Add greeting endpoint
+
+## Overview
+Add a /greet route that returns a personalised JSON greeting.
+
+## Validation Commands
+- `npm run build`
+- `npm test`
+
+### Task 1: Create the route handler
+- [ ] Create `src/routes/greet.ts` with a `GET /greet?name=` handler
+- [ ] Export `greetRouter` from the file
+- [ ] Add unit test in `src/routes/greet.test.ts`
+
+### Task 2: Wire into Express app
+- [ ] Import `greetRouter` in `src/app.ts`
+- [ ] Register at `/greet` before the catch-all handler
+```
+
+**2. Run it:**
+
+```sh
+maestro docs/plans/my-feature.md
+```
+
+**3. Watch the output** — each task is executed, validated, and committed automatically.
+When all tasks are done Maestro prints `ALL_TASKS_DONE` and kicks off the review phases.
+
+---
+
+## Plan File Format
+
+```markdown
+# Plan: <Title>
+
+## Overview
+One-paragraph description of the goal.
+
+## Validation Commands
+- `command that must pass after every task`
+- `another command`
+
+### Task 1: <Title>
+- [ ] Specific, verifiable deliverable
+- [ ] Another deliverable
+
+#### Validation Commands
+- `command that only runs after this task`
+
+### Task 2: <Title>
+- [ ] Deliverable
+```
+
+**Rules:**
+- `## Validation Commands` (top-level) — runs after **every** task.
+- `#### Validation Commands` (under a task) — runs only after that task.
+- Each checkbox must be a specific, observable outcome — Claude marks it `[x]` when done.
+- Every task should leave the codebase in a compilable, passing state.
+
+---
+
+## CLI Reference
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `[plan-file]` | Path to the markdown plan to execute | — |
+| `--provider <name>` | AI provider: `copilot` or `claude` | `copilot` |
+| `-m, --max-iterations <n>` | Maximum task execution iterations | `50` |
+| `--max-external-iterations <n>` | Second-review iteration limit (0 = auto) | `0` |
+| `-r, --review` | Skip tasks; run review pipeline on current branch | — |
+| `-t, --tasks-only` | Run tasks only; skip all reviews | — |
+| `-b, --base-ref <ref>` | Override default branch for review diffs | auto |
+| `--skip-finalize` | Skip finalize step | — |
+| `--worktree` | Run in an isolated git worktree | — |
+| `--plan <description>` | Create a plan file interactively via AI | — |
+| `-s, --serve` | Start live web dashboard | — |
+| `--replay` | Browse completed runs in offline dashboard | — |
+| `-p, --port <n>` | Web dashboard port | `8080` |
+| `-w, --watch <dir>` | Extra directory to watch for progress files | — |
+| `-d, --debug` | Enable debug logging | — |
+| `--no-color` | Disable ANSI color output | — |
+| `--plan-tips` | Show plan authoring best practices | — |
+| `--docs` | Open full reference documentation in browser | — |
+| `--config` | Open web UI to view/edit configuration | — |
+| `--reset` | Interactively reset global config to defaults | — |
+| `--dump-defaults <dir>` | Extract embedded defaults to a directory | — |
+| `--config-dir <dir>` | Override config directory | — |
+
+---
+
+## Configuration
+
+Maestro merges configuration from four layers (highest priority first):
+
+1. **CLI flags** — `--provider`, `--max-iterations`, etc.
+2. **Project config** — `.maestro/config` in the current working directory
+3. **Global config** — `~/.config/maestro/config`
+4. **Embedded defaults** — shipped inside the package
+
+Config files use INI format. You only need to set keys that differ from the defaults.
+
+### Config Keys
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `ai_provider` | `copilot` | `copilot` or `claude` |
+| `claude_command` | `claude` | Claude Code executable |
+| `claude_args` | (see defaults) | Extra args passed to Claude |
+| `claude_error_patterns` | (see defaults) | Patterns that signal a fatal Claude error |
+| `copilot_command` | `copilot` | Copilot executable |
+| `copilot_args` | `--autopilot --allow-all` | Extra args passed to Copilot |
+| `copilot_error_patterns` | (see defaults) | Patterns that signal a fatal Copilot error |
+| `max_iterations` | `50` | Max AI iterations per task |
+| `max_external_iterations` | `0` | Review iteration limit (0 = auto) |
+| `iteration_delay_ms` | `2000` | Delay between iterations (ms) |
+| `task_retry_count` | `1` | Retries on validation failure |
+| `validation_timeout_ms` | `60000` | Validation command timeout (0 = unlimited) |
+| `finalize_enabled` | `false` | Enable Phase 4 finalize step |
+| `use_worktree` | `false` | Run in isolated git worktree |
+| `plans_dir` | `docs/plans` | Default directory for plan files |
+| `default_branch` | (auto) | Base branch for review diffs |
+| `vcs_command` | `git` | VCS executable |
+| `push_on_complete` | `false` | Push branch after all phases complete |
+| `port` | `8080` | Web dashboard port |
+| `watch_dirs` | — | Comma-separated extra dirs for dashboard |
+| `color_task` | `#00ff00` | Task phase color |
+| `color_review` | `#00ffff` | Review phase color |
+| `color_signal` | `#ff6464` | Signal color (ALL_TASKS_DONE etc.) |
+| `color_warn` | `#ffff00` | Warning color |
+| `color_error` | `#ff0000` | Error color |
+| `color_info` | `#b4b4b4` | Info / default text color |
+| `color_timestamp` | `#8a8a8a` | Timestamp color |
+
+Edit your global config:
+
+```sh
+maestro --config     # opens browser-based editor
+```
+
+Or edit `~/.config/maestro/config` directly (INI format).
+
+---
+
+## AI Providers
+
+### Claude Code
+
+```sh
+npm install -g @anthropic-ai/claude-code
+claude login
+```
+
+Set in config: `ai_provider = claude`.
+
+### GitHub Copilot
+
+```sh
+npm install -g @github/copilot
+gh auth login
+```
+
+Set in config: `ai_provider = copilot` (this is the default).
+
+---
+
+## Web Dashboard
+
+| Command | What it does |
+|---------|-------------|
+| `maestro <plan> --serve` | Live dashboard — streams task progress in real time |
+| `maestro --replay` | Offline dashboard — browse completed run logs |
+| `maestro --config` | Config editor — view and change all settings in a browser UI |
+
+All dashboards run locally on `http://localhost:8080` (or your configured port).
+
+---
+
+## Writing Good Plans
+
+A few key tips (run `maestro --plan-tips` for the full guide):
+
+- **Validation must pass at every step** — not just when all tasks are done. Use
+  conditional checks (`existsSync`) if a file is created by a later task.
+- **Checkboxes are verifiable outcomes** — write `Create src/foo.ts with exported bar()`
+  not `Work on the foo module`.
+- **Each task should leave the build green** — no intentionally broken intermediate states.
+- **Prefer independent tasks** — tasks that don't depend on files from other tasks are
+  safer, easier to retry, and useful with `--tasks-only`.
+- **Sequential dependencies** — if Task 3 imports a file created by Task 1, use the
+  incremental validation pattern so Task 2 doesn't fail.
+
+---
+
+## --docs
+
+```sh
+maestro --docs
+```
+
+Opens the full reference documentation (this content, as a formatted HTML page) in your
+default browser — no internet connection required, served from the local install.

package/defaults/agents/documentation.txt

@@ -0,0 +1,18 @@
+# documentation
+# This agent reviews documentation completeness.
+
+Review the code changes in this branch for:
+- Public API functions/methods/classes that have no documentation at all
+- README updates needed for new features that users need to know about
+- Missing or outdated configuration documentation
+- Missing or misleading error messages (errors that don't help the user understand what to do)
+
+Do NOT report:
+- Missing inline comments for self-explanatory code
+- Documentation style preferences
+- Minor documentation improvements
+
+Report findings as: file:line - description (or "README - <what's needed>")
+Severity prefix: MAJOR / MINOR
+
+If documentation is adequate for the changes made, output exactly: NO ISSUES FOUND

package/defaults/agents/implementation.txt

@@ -0,0 +1,16 @@
+# implementation
+# This agent verifies the code actually does what the plan describes.
+
+Review the code changes in this branch and compare against the plan file to verify:
+- Does the implementation actually achieve what each task in the plan describes?
+- Are all the requirements from each task's checklist met?
+- Are there any missing pieces that should have been implemented?
+- Are there any deviations from the plan that might cause problems?
+- Does the feature work end-to-end as the plan intended?
+
+Read the plan file to understand what was supposed to be implemented before reviewing.
+
+Report findings as: file:line - description (or "Plan task N: <what's missing>")
+Severity prefix: CRITICAL / MAJOR / MINOR
+
+If the implementation matches the plan, output exactly: NO ISSUES FOUND

package/defaults/agents/quality.txt

@@ -0,0 +1,19 @@
+# quality
+# This agent reviews for bugs, security issues, and reliability problems.
+
+Review the code changes introduced in this branch vs {{DEFAULT_BRANCH}} for:
+- Bugs and logic errors that could cause incorrect behavior
+- Security vulnerabilities (injection, XSS, auth bypass, SSRF, insecure deserialization, etc.)
+- Race conditions and concurrency issues
+- Unhandled error cases and missing error propagation
+- Memory leaks or resource leaks (unclosed files, connections, etc.)
+- Null/undefined dereferences and boundary conditions
+- Input validation gaps at system boundaries
+
+Focus only on code introduced or modified in this branch. Do not report pre-existing issues that were not touched.
+
+Report findings as: file:line - description
+Severity prefix: CRITICAL / MAJOR / MINOR
+Example: MAJOR src/auth.ts:42 - JWT token is not verified before use
+
+If no issues found, output exactly: NO ISSUES FOUND

package/defaults/agents/simplification.txt

@@ -0,0 +1,19 @@
+# simplification
+# This agent looks for over-engineering and unnecessary complexity.
+
+Review the code changes in this branch for:
+- Unnecessary abstractions for one-time operations (premature abstraction)
+- Dead code or code that can never be reached
+- Premature optimization that adds complexity without a clear performance need
+- Over-engineered solutions to simple problems
+- Duplicate code that could be consolidated without adding abstraction overhead
+- Unnecessary dependencies or large libraries used for trivial tasks
+- Feature flags or backwards-compat shims for changes that could just be direct
+
+The right amount of complexity is the minimum needed for the current task.
+Three similar lines of code is often better than a premature abstraction.
+
+Report findings as: file:line - description
+Severity prefix: MAJOR / MINOR (rarely CRITICAL for over-engineering)
+
+If the implementation is appropriately simple, output exactly: NO ISSUES FOUND

package/defaults/agents/testing.txt

@@ -0,0 +1,16 @@
+# testing
+# This agent reviews test coverage and test quality.
+
+Review the code changes in this branch for:
+- Missing unit tests for new functions and methods
+- Missing integration tests for new API endpoints or major workflows
+- Tests that don't actually assert meaningful behavior (testing implementation details instead of behavior)
+- Edge cases not covered by tests (empty inputs, boundary values, error paths)
+- Tests that could pass vacuously (no assertions, trivial assertions)
+- Flaky tests (time-dependent, order-dependent, environment-dependent)
+
+Report findings as: file:line - description
+Severity prefix: CRITICAL / MAJOR / MINOR
+Example: MAJOR src/auth.ts - No tests for JWT expiry handling
+
+If test coverage is adequate, output exactly: NO ISSUES FOUND

package/defaults/config

@@ -0,0 +1,46 @@
+# Maestro configuration file
+# Lines starting with # are comments.
+# Uncomment and change only what you need — all settings have sensible defaults.
+
+# AI Provider — choose which CLI to use for task execution and reviews
+# ai_provider = copilot               # 'copilot' (default) or 'claude'
+
+# Claude Code provider settings (used when ai_provider = claude)
+# claude_command = claude
+# claude_args = --dangerously-skip-permissions --output-format stream-json --verbose
+# claude_error_patterns = You've hit your limit,API Error:,cannot be launched inside another Claude Code session
+
+# GitHub Copilot provider settings (used when ai_provider = copilot)
+# copilot_command = copilot
+# copilot_args = --autopilot --allow-all
+# copilot_error_patterns = authentication required,Copilot is not enabled,rate limit exceeded
+
+# Iteration limits
+# max_external_iterations = 0   # 0 = auto (max(3, max_iterations/5))
+# iteration_delay_ms = 2000
+# task_retry_count = 1
+# validation_timeout_ms = 60000 # ms before a hung validation command is killed (0 = no limit)
+
+# Finalize step (disabled by default)
+# finalize_enabled = false
+
+# Git
+# use_worktree = false
+# plans_dir = docs/plans
+# default_branch =              # auto-detected from git if not set
+# vcs_command = git             # change to a wrapper for hg repos
+# push_on_complete = false
+
+# Web dashboard
+# port = 8080
+# watch_dirs =                  # comma-separated list of directories to watch
+
+# Colors (24-bit RGB hex)
+# color_task          = #00ff00
+# color_review        = #00ffff
+# color_claude_eval   = #64c8ff
+# color_warn          = #ffff00
+# color_error         = #ff0000
+# color_signal        = #ff6464
+# color_timestamp     = #8a8a8a
+# color_info          = #b4b4b4

package/defaults/plan-tips.md

@@ -0,0 +1,50 @@
+# Maestro Plan Authoring Best Practices
+
+## Validation Commands
+
+### Global commands run after EVERY task
+The `## Validation Commands` section defines commands that run after each task
+completes — not just the last one. Every command must pass at every intermediate stage.
+
+**Good — passes at every stage:**
+- `npm run build`   — compiles whatever has been built so far
+- `tsc --noEmit`    — type-checks files that exist
+- `npm test`        — runs tests for features already implemented
+
+**Bad — only passes when all tasks are done:**
+- Integration tests that reference files created by later tasks
+- `node -e "import('./src/index.js')..."` when index.js is Task 3's output
+
+### Incremental validation pattern
+If your validation must reference a file that doesn't exist until a later task,
+wrap it conditionally:
+
+    node --input-type=module -e "
+      import { existsSync } from 'fs';
+      if (existsSync('./src/index.js')) {
+        const m = await import('./src/index.js');
+        console.log(m.greet('world'));
+      } else {
+        console.log('partial build ok');
+      }
+    "
+
+### Each task should leave the codebase valid
+Design tasks so the codebase compiles and existing tests pass after every task.
+Avoid tasks that intentionally break the build temporarily.
+
+## Task Design
+
+### Checkboxes are specific, observable outcomes
+Write each checkbox as a verifiable deliverable:
+- ✓ `- [ ] Create src/greet.ts with exported greet(name): string function`
+- ✗ `- [ ] Work on the greet module`  (too vague — Claude may not mark it done)
+
+### Prefer tasks that stand alone
+When possible, design tasks that don't depend on files from other tasks.
+This makes validation simpler and allows partial runs (--tasks-only) to be useful
+at any stopping point.
+
+### Sequential dependencies — use conditional validation
+If tasks must build on each other (Task 1 creates a file Task 3 imports),
+use the incremental validation pattern above so intermediate tasks don't fail.

package/defaults/prompts/finalize.txt

@@ -0,0 +1,14 @@
+You are performing a final cleanup step after all tasks and reviews are complete on this feature branch.
+
+Default branch: {{DEFAULT_BRANCH}}
+Plan file: {{PLAN_FILE}}
+
+Default behavior:
+1. Rebase the feature branch onto {{DEFAULT_BRANCH}} to get a clean linear history
+2. If there are many small commits, squash them into logical groups (e.g., one commit per major feature area)
+3. Ensure all commit messages follow conventional commit format
+
+Only perform actions that are safe and reversible. Do not force-push to shared branches.
+Do not push to any remote unless explicitly configured to do so.
+
+Report what you did. If nothing needs to be done, say so.

package/defaults/prompts/hint_analysis.txt

@@ -0,0 +1,38 @@
+You are a maestro plan diagnostician. A task validation has failed after all retries.
+Determine whether this failure is caused by a structural problem in the plan document
+itself (wrong validation ordering, missing setup step, command referencing something
+not yet created) or a normal code bug / transient error the coding agent should fix.
+
+== FULL PLAN DOCUMENT ==
+{{PLAN_CONTENT}}
+
+== TASK THAT FAILED ==
+Task {{TASK_INDEX}}: {{TASK_TITLE}}
+
+== VALIDATION ERROR OUTPUT ==
+{{VALIDATION_ERRORS}}
+
+== RECENT PROGRESS LOG (last 60 lines) ==
+{{PROGRESS_TAIL}}
+
+== INSTRUCTIONS ==
+Read the full plan above. Pay special attention to:
+- Which global "## Validation Commands" run after every task
+- Whether a future task in the plan will set up something the failing command needs
+- Whether the failing task's validation commands reference work not done until later
+
+If this is a PLAN DOCUMENT PROBLEM (validation command too early, references a
+file/script not yet set up, ordering issue), respond with ONLY this JSON block:
+
+```json
+{
+  "title": "<one sentence, max 80 chars>",
+  "explanation": "<2-4 sentences: what plan problem caused this, reference the specific command/file and which task will set it up if applicable>",
+  "suggestion": "<2-4 sentences: concrete fix the plan author can make — e.g. move command to per-task validation on Task N. Mention 'maestro --plan-tips' for guidance.>"
+}
+```
+
+If this is a NORMAL CODE BUG or TRANSIENT ERROR (compile error, test failure,
+runtime exception — something the coding agent should fix, not a plan issue),
+respond with exactly this and nothing else:
+NO_PLAN_ISSUE

package/defaults/prompts/plan_create.txt

@@ -0,0 +1,36 @@
+You are helping a developer create a detailed maestro plan file.
+
+The developer wants to: {{DESCRIPTION}}
+
+The working directory is: {{CWD}}
+
+Please:
+1. Use your file reading tools to explore the project — read package.json, look at the
+   src/ directory structure, and examine files relevant to the described change.
+2. Based on your exploration, ask the developer 3–5 clarifying questions to understand:
+   - Exact scope and requirements
+   - Which files/modules to create or modify
+   - What validation commands should run (build, test, lint)
+   - Any constraints, design preferences, or edge cases to handle
+
+Format your questions as a numbered list. Be specific and reference what you found in the
+codebase. After your questions, print exactly this line:
+---QUESTIONS_COMPLETE---
+
+IMPORTANT — Two levels of validation:
+
+Global "## Validation Commands" run after EVERY task. Only include commands
+that already pass from Task 1 (e.g. `npm run build` if a build script exists).
+
+Per-task "#### Validation Commands" run only after that specific task:
+
+  ### Task 5: Write tests
+  - [ ] Create test file
+
+  #### Validation Commands
+  - `npm test`
+
+Use per-task validation for commands that depend on work done in that task
+(e.g. `npm test` only after the test runner is installed and tests are written).
+Do NOT put `npm test` in global Validation Commands if the test runner
+doesn't exist yet at the start of the plan.

package/defaults/prompts/review_first.txt

@@ -0,0 +1,37 @@
+You are performing a comprehensive code review of changes introduced on the current branch vs the default branch ({{DEFAULT_BRANCH}}).
+
+Plan file: {{PLAN_FILE}}
+Goal: {{GOAL}}
+Progress log: {{PROGRESS_FILE}}
+
+{{DIFF_INSTRUCTION}}
+
+Launch the following review agents in parallel using the Task tool:
+
+{{agent:quality}}
+
+{{agent:implementation}}
+
+{{agent:testing}}
+
+{{agent:simplification}}
+
+{{agent:documentation}}
+
+After all agents complete, produce the output in exactly this format:
+
+MERGED FINDINGS FROM ALL AGENTS:
+1. <agent-name>: <finding or "No issues found">
+2. <agent-name>: <finding or "No issues found">
+... (one entry per finding across all agents, numbered sequentially)
+
+ISSUE CLASSIFICATION:
+For each finding:
+<number>. <brief description>
+   - <reasoning bullet>
+   - CLASSIFICATION: CONFIRMED | FALSE POSITIVE - <reason>
+
+After classifying all findings:
+- If there are CONFIRMED issues: fix them directly by modifying the relevant files, then output REVIEW_DONE
+- If all findings are FALSE POSITIVE or there are no findings: output exactly: No confirmed issues to fix.
+  Then output REVIEW_DONE

package/defaults/prompts/review_second.txt

@@ -0,0 +1,36 @@
+You are performing a focused second-pass code review. Only report CRITICAL and MAJOR issues — minor issues and cosmetic changes are explicitly out of scope.
+
+Plan file: {{PLAN_FILE}}
+Goal: {{GOAL}}
+Default branch: {{DEFAULT_BRANCH}}
+
+{{DIFF_INSTRUCTION}}
+
+Launch the following review agents in parallel using the Task tool:
+
+{{agent:quality}}
+
+{{agent:implementation}}
+
+Focus only on:
+- Critical bugs that will cause crashes, data loss, or security vulnerabilities
+- Major logic errors that prevent the feature from working correctly
+- Serious performance problems that will impact production
+
+Do NOT report:
+- Minor style issues
+- Documentation gaps (unless public API is completely undocumented)
+- Cosmetic improvements
+- Nice-to-have refactors
+
+After all agents complete, produce output in this format:
+
+MERGED FINDINGS FROM ALL AGENTS:
+1. <agent-name>: <finding or "No critical/major issues found">
+
+ISSUE CLASSIFICATION:
+(same format as first review — CONFIRMED or FALSE POSITIVE)
+
+- If CONFIRMED critical/major issues exist: fix them, then output REVIEW_DONE
+- If none: output exactly: No confirmed issues to fix.
+  Then output REVIEW_DONE

package/defaults/prompts/task.txt

@@ -0,0 +1,23 @@
+You are implementing a specific task from a software feature plan. Your job is to implement exactly this task — no more, no less.
+
+Plan file: {{PLAN_FILE}}
+Goal: {{GOAL}}
+Progress log: {{PROGRESS_FILE}}
+Default branch: {{DEFAULT_BRANCH}}
+
+Task to implement:
+
+{{TASK_CONTENT}}
+
+Instructions:
+- Read the plan file to understand the full feature context before implementing
+- Implement ONLY this task — do not implement future tasks
+- Make all necessary file changes to complete the task's checkboxes
+- Run the validation commands listed in the plan's ## Validation Commands section after implementation
+- If validation fails, fix the issues and re-run validation
+- When all checkboxes in this task are complete and validation passes, update the plan file: change - [ ] to - [x] for each completed checkbox in this task
+- Do NOT mark checkboxes complete unless validation actually passes
+- Do not modify files unrelated to this task
+- Do not touch the default branch ({{DEFAULT_BRANCH}})
+- After marking checkboxes complete, stop — do not proceed to future tasks
+- The external loop will handle committing and moving to the next task