@dreb/coding-agent 1.16.0

package/examples/sdk/README.md

@@ -0,0 +1,144 @@
+# SDK Examples
+
+Programmatic usage of dreb coding-agent via `createAgentSession()`.
+
+## Examples
+
+| File | Description |
+|------|-------------|
+| `01-minimal.ts` | Simplest usage with all defaults |
+| `02-custom-model.ts` | Select model and thinking level |
+| `03-custom-prompt.ts` | Replace or modify system prompt |
+| `04-skills.ts` | Discover, filter, or replace skills |
+| `05-tools.ts` | Built-in tools, custom tools |
+| `06-extensions.ts` | Logging, blocking, result modification |
+| `07-context-files.ts` | AGENTS.md context files |
+| `08-slash-commands.ts` | File-based slash commands |
+| `09-api-keys-and-oauth.ts` | API key resolution, OAuth config |
+| `10-settings.ts` | Override compaction, retry, terminal settings |
+| `11-sessions.ts` | In-memory, persistent, continue, list sessions |
+| `12-full-control.ts` | Replace everything, no discovery |
+
+## Running
+
+```bash
+cd packages/coding-agent
+npx tsx examples/sdk/01-minimal.ts
+```
+
+## Quick Reference
+
+```typescript
+import { getModel } from "@dreb/ai";
+import {
+  AuthStorage,
+  createAgentSession,
+  DefaultResourceLoader,
+  ModelRegistry,
+  SessionManager,
+  SettingsManager,
+  codingTools,
+  readOnlyTools,
+  readTool, bashTool, editTool, writeTool,
+} from "@dreb/coding-agent";
+
+// Auth and models setup
+const authStorage = AuthStorage.create();
+const modelRegistry = new ModelRegistry(authStorage);
+
+// Minimal
+const { session } = await createAgentSession({ authStorage, modelRegistry });
+
+// Custom model
+const model = getModel("anthropic", "claude-opus-4-5");
+const { session } = await createAgentSession({ model, thinkingLevel: "high", authStorage, modelRegistry });
+
+// Modify prompt
+const loader = new DefaultResourceLoader({
+  systemPromptOverride: (base) => `${base}\n\nBe concise.`,
+});
+await loader.reload();
+const { session } = await createAgentSession({ resourceLoader: loader, authStorage, modelRegistry });
+
+// Read-only
+const { session } = await createAgentSession({ tools: readOnlyTools, authStorage, modelRegistry });
+
+// In-memory
+const { session } = await createAgentSession({
+  sessionManager: SessionManager.inMemory(),
+  authStorage,
+  modelRegistry,
+});
+
+// Full control
+const customAuth = AuthStorage.create("/my/app/auth.json");
+customAuth.setRuntimeApiKey("anthropic", process.env.MY_KEY!);
+const customRegistry = new ModelRegistry(customAuth);
+
+const resourceLoader = new DefaultResourceLoader({
+  systemPromptOverride: () => "You are helpful.",
+  extensionFactories: [myExtension],
+  skillsOverride: () => ({ skills: [], diagnostics: [] }),
+  agentsFilesOverride: () => ({ agentsFiles: [] }),
+  promptsOverride: () => ({ prompts: [], diagnostics: [] }),
+});
+await resourceLoader.reload();
+
+const { session } = await createAgentSession({
+  model,
+  authStorage: customAuth,
+  modelRegistry: customRegistry,
+  resourceLoader,
+  tools: [readTool, bashTool],
+  customTools: [{ tool: myTool }],
+  sessionManager: SessionManager.inMemory(),
+  settingsManager: SettingsManager.inMemory(),
+});
+
+// Run prompts
+session.subscribe((event) => {
+  if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+    process.stdout.write(event.assistantMessageEvent.delta);
+  }
+});
+await session.prompt("Hello");
+```
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `authStorage` | `AuthStorage.create()` | Credential storage |
+| `modelRegistry` | `new ModelRegistry(authStorage)` | Model registry |
+| `cwd` | `process.cwd()` | Working directory |
+| `agentDir` | `~/.dreb/agent` | Config directory |
+| `model` | From settings/first available | Model to use |
+| `thinkingLevel` | From settings/"off" | off, low, medium, high |
+| `tools` | `codingTools` | Built-in tools |
+| `customTools` | `[]` | Additional tool definitions |
+| `resourceLoader` | DefaultResourceLoader | Resource loader for extensions, skills, prompts, themes |
+| `sessionManager` | `SessionManager.create(cwd)` | Persistence |
+| `settingsManager` | `SettingsManager.create(cwd, agentDir)` | Settings overrides |
+
+## Events
+
+```typescript
+session.subscribe((event) => {
+  switch (event.type) {
+    case "message_update":
+      if (event.assistantMessageEvent.type === "text_delta") {
+        process.stdout.write(event.assistantMessageEvent.delta);
+      }
+      break;
+    case "tool_execution_start":
+      console.log(`Tool: ${event.toolName}`);
+      break;
+    case "tool_execution_end":
+      console.log(`Result: ${event.result}`);
+      break;
+    case "agent_end":
+      console.log("Done");
+      break;
+  }
+});
+```

package/package.json

@@ -0,0 +1,123 @@
+{
+	"name": "@dreb/coding-agent",
+	"version": "1.16.0",
+	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
+	"type": "module",
+	"drebConfig": {
+		"name": "dreb",
+		"configDir": ".dreb"
+	},
+	"bin": {
+		"dreb": "dist/cli.js"
+	},
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		},
+		"./hooks": {
+			"types": "./dist/core/hooks/index.d.ts",
+			"import": "./dist/core/hooks/index.js"
+		},
+		"./rpc": {
+			"types": "./dist/modes/rpc/index.d.ts",
+			"import": "./dist/modes/rpc/index.js"
+		},
+		"./buddy": {
+			"types": "./dist/core/buddy/index.d.ts",
+			"import": "./dist/core/buddy/index.js"
+		}
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"dist",
+		"agents",
+		"skills",
+		"docs",
+		"examples",
+		"CHANGELOG.md"
+	],
+	"scripts": {
+		"clean": "shx rm -rf dist",
+		"dev": "tsgo -p tsconfig.build.json --watch --preserveWatchOutput",
+		"build": "tsgo -p tsconfig.build.json && shx chmod +x dist/cli.js && npm run copy-assets",
+		"build:binary": "npm --prefix ../tui run build && npm --prefix ../ai run build && npm --prefix ../agent run build && npm run build && bun build --compile ./dist/bun/cli.js --outfile dist/dreb && npm run copy-binary-assets",
+		"copy-assets": "shx mkdir -p dist/modes/interactive/theme && shx cp src/modes/interactive/theme/*.json dist/modes/interactive/theme/ && shx mkdir -p dist/core/export-html/vendor && shx cp src/core/export-html/template.html src/core/export-html/template.css src/core/export-html/template.js dist/core/export-html/ && shx cp src/core/export-html/vendor/*.js dist/core/export-html/vendor/",
+		"copy-binary-assets": "shx cp package.json dist/ && shx cp README.md dist/ && shx cp CHANGELOG.md dist/ && shx mkdir -p dist/theme && shx cp src/modes/interactive/theme/*.json dist/theme/ && shx mkdir -p dist/export-html/vendor && shx cp src/core/export-html/template.html dist/export-html/ && shx cp src/core/export-html/vendor/*.js dist/export-html/vendor/ && shx cp -r docs dist/ && shx cp -r examples dist/ && shx cp ../../node_modules/@silvia-odwyer/photon-node/photon_rs_bg.wasm dist/",
+		"test": "vitest --run",
+		"prepublishOnly": "npm run clean && npm run build"
+	},
+	"dependencies": {
+		"@dreb/agent-core": "^1.0.0",
+		"@dreb/ai": "^1.0.0",
+		"@dreb/tui": "^1.0.0",
+		"@huggingface/transformers": "^4.0.1",
+		"@mariozechner/jiti": "^2.6.2",
+		"@silvia-odwyer/photon-node": "^0.3.4",
+		"ajv": "^8.17.1",
+		"chalk": "^5.5.0",
+		"cli-highlight": "^2.1.11",
+		"diff": "^8.0.2",
+		"extract-zip": "^2.0.1",
+		"file-type": "^21.1.1",
+		"glob": "^13.0.1",
+		"hosted-git-info": "^9.0.2",
+		"ignore": "^7.0.5",
+		"marked": "^15.0.12",
+		"minimatch": "^10.2.3",
+		"proper-lockfile": "^4.1.2",
+		"strip-ansi": "^7.1.0",
+		"tree-sitter-c": "^0.24.1",
+		"tree-sitter-cpp": "^0.23.4",
+		"tree-sitter-go": "^0.25.0",
+		"tree-sitter-java": "^0.23.5",
+		"tree-sitter-javascript": "^0.25.0",
+		"tree-sitter-python": "^0.25.0",
+		"tree-sitter-rust": "^0.24.0",
+		"tree-sitter-typescript": "^0.23.2",
+		"undici": "^7.19.1",
+		"web-tree-sitter": "^0.26.8",
+		"yaml": "^2.8.2"
+	},
+	"overrides": {
+		"rimraf": "6.1.2",
+		"gaxios": {
+			"rimraf": "6.1.2"
+		}
+	},
+	"optionalDependencies": {
+		"@mariozechner/clipboard": "^0.3.2"
+	},
+	"devDependencies": {
+		"@types/diff": "^7.0.2",
+		"@types/hosted-git-info": "^3.0.5",
+		"@types/ms": "^2.1.0",
+		"@types/node": "^24.3.0",
+		"@types/proper-lockfile": "^4.1.4",
+		"shx": "^0.4.0",
+		"typescript": "^5.7.3",
+		"vitest": "^3.2.4"
+	},
+	"keywords": [
+		"coding-agent",
+		"ai",
+		"llm",
+		"cli",
+		"tui",
+		"agent"
+	],
+	"author": "Drew Brereton",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/aebrer/dreb.git",
+		"directory": "packages/coding-agent"
+	},
+	"engines": {
+		"node": ">=20.6.0"
+	}
+}

package/skills/mach6-implement/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: mach6-implement
+description: "Implement a plan from a PR, or fix review findings / CI failures. Usage: mach6-implement 42 [finding-numbers] or mach6-implement 42 ci"
+argument-hint: "<pr-number> [finding-numbers | ci]"
+---
+
+# mach6-implement — Implement Plans, Fix Findings, or Fix CI
+
+**User input:** $ARGUMENTS
+
+This skill has two modes:
+- **Implement mode** (just a PR number): reads the plan comment and implements it
+- **Fix mode** (with finding numbers or `ci`): fixes specific review findings or CI failures
+
+## Global Rules
+
+1. **GitHub as shared memory** — Plans, reviews, and assessments are on the PR as comments with HTML markers.
+2. **No `#N` in comment bodies** — Use "finding 3", "item 3" etc. instead.
+3. **Safe git** — Never use `git add -A` or `git add .`. Stage files by name. Never stage secrets.
+4. **Task tracking** — Use the `tasks_update` tool to show progress.
+
+## Step 1: Parse input
+
+Extract:
+- **PR number** (required)
+- **Finding numbers** to fix (optional — e.g., `1,2,3`)
+- **`ci`** flag (optional — fix CI failures instead of review findings)
+
+If only a PR number is given → **implement mode**.
+If finding numbers or `ci` → **fix mode**.
+
+## Step 2: Checkout
+
+```bash
+gh pr checkout <pr-number>
+git pull
+```
+
+---
+
+## Implement Mode (PR number only)
+
+### Step 3i: Read the plan and full PR context
+
+Read ALL PR comments and the PR body to get complete context:
+```bash
+gh pr view <pr-number> --json title,body,comments
+```
+
+Find the plan comment (contains `<!-- mach6-plan -->` marker) from the comments. If no plan comment exists, tell the user and suggest running `/skill:mach6-plan` first.
+
+Also read any progress updates, prior review findings, assessments, and discussion — all of this context informs implementation.
+
+### Step 4i: Set up task tracking
+
+Create tasks based on the plan's deliverables/features. Example:
+```
+tasks_update([
+  { id: "read", title: "Read plan and codebase", status: "in_progress" },
+  { id: "feature-1", title: "Implement feature 1", status: "pending" },
+  { id: "feature-2", title: "Implement feature 2", status: "pending" },
+  { id: "test", title: "Add/update tests", status: "pending" },
+  { id: "verify", title: "Build and verify", status: "pending" }
+])
+```
+
+### Step 5i: Read the codebase
+
+Read all files mentioned in the plan. Understand the existing code before making changes.
+
+### Step 6i: Implement
+
+Use the `feature-dev` subagent to implement each deliverable. `feature-dev` is a **pre-existing agent definition** shipped with dreb — it has full tool access (read, write, edit, grep, find, ls, bash, search) and uses a strong-tier model with a provider fallback list. Do not override its model unless there's a specific reason.
+
+**For each deliverable in the plan**, launch a `feature-dev` subagent via the `subagent` tool. Provide each agent with:
+- The specific deliverable to implement (files to modify, what to change, expected behavior)
+- The full plan context and any relevant PR discussion
+- The list of files to read for understanding existing patterns
+- Instructions to run tests and linting after making changes
+- **If the plan includes tests for this deliverable, tests MUST be written as part of the implementation — not deferred**
+
+**Test coverage is part of the deliverable, not an afterthought.** If the plan specifies tests for a deliverable, the feature-dev agent must implement them. If the target package lacks test infrastructure, add it.
+
+**Parallelism:** If deliverables are independent (don't modify the same files), run their `feature-dev` agents in parallel. If they have dependencies, use chain mode or run them sequentially — later features may depend on earlier ones.
+
+**Small plans (1-2 simple deliverables):** You may implement directly instead of delegating, if the changes are straightforward enough that subagent overhead isn't justified.
+
+Update task tracking as each deliverable completes.
+
+### Step 7i: Verify
+
+After all `feature-dev` agents complete:
+- Run the project's test suite
+- Run any linting/formatting tools
+- Build the project if applicable
+- Verify each deliverable from the plan is addressed
+- If any agent reported issues or partial completion, address the gaps
+
+Suggest next step: `/skill:mach6-push` then `/skill:mach6-review <pr-number>` for review.
+
+---
+
+## Fix Mode (finding numbers or `ci`)
+
+### Step 3f: Set up task tracking
+
+```
+tasks_update([
+  { id: "gather", title: "Gather findings to fix", status: "in_progress" },
+  { id: "fix", title: "Implement fixes", status: "pending" },
+  { id: "verify", title: "Verify fixes", status: "pending" }
+])
+```
+
+### Step 4f: Gather context
+
+#### If `ci` was specified:
+
+```bash
+gh pr checks <pr-number>
+gh run view <run-id> --log-failed
+```
+
+Read the failed CI logs and identify issues. Extract test failures, stack traces, error messages. If all checks pass, report this and stop.
+
+#### If finding numbers were specified:
+
+Read ALL PR comments to get full context:
+```bash
+gh pr view <pr-number> --json title,body,comments
+```
+
+Find the review (`<!-- mach6-review -->`) and assessment (`<!-- mach6-assessment -->`) comments, then extract the specific findings to fix. Prior progress comments and discussion may also provide useful context.
+
+#### If no finding numbers and not `ci`:
+
+Read ALL PR comments, find review/assessment comments, present genuine findings, and ask which to fix.
+
+### Step 5f: Batch sizing
+
+- **Simple fixes** (typos, naming, imports): ~10 per batch
+- **Moderate fixes** (logic changes, refactors): ~6 per batch
+- **Complex fixes** (architecture, new features): ~3 per batch
+
+If more than batch size, fix first batch and tell user to re-run.
+
+### Step 6f: Implement fixes
+
+Use the `feature-dev` subagent to implement fixes. `feature-dev` is a **pre-existing agent definition** shipped with dreb — it has full tool access and uses a strong-tier model with a provider fallback list. Do not override its model unless there's a specific reason.
+
+**For each finding** (or batch of related findings), launch a `feature-dev` subagent with:
+- The finding description and the assessment's classification/reasoning
+- The specific files and code locations involved
+- Instructions on what to fix and how
+- Instructions to run tests after fixing
+
+**Parallelism:** If findings touch different files, run their `feature-dev` agents in parallel. If findings overlap (same file/function), batch them into a single agent.
+
+**Simple fixes** (typos, naming, one-line changes): You may fix these directly instead of delegating.
+
+Defer out-of-scope items to new issues. Update task tracking per finding.
+
+### Step 7f: Verify
+
+After all `feature-dev` agents complete:
+- Run tests and linting
+- Verify each fix addresses its finding
+- If any agent reported issues, address the gaps
+
+Suggest next step: `/skill:mach6-push` then `/skill:mach6-review <pr-number>` for re-review.

package/skills/mach6-issue/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: mach6-issue
+description: "Assess an existing GitHub issue (explore codebase, identify scope/risks/ambiguities, post assessment) or create a new structured issue. Usage: mach6-issue 42 (assess) or mach6-issue (create) or mach6-issue <description> (create with context)"
+argument-hint: "[issue-number | description]"
+---
+
+# mach6-issue — Assess or Create Issue
+
+**User input:** $ARGUMENTS
+
+## Global Rules
+
+1. **GitHub as shared memory** — Plans, reviews, assessments, and progress are posted as PR/issue comments so any future session can pick up context.
+2. **HTML markers** — Use `<!-- mach6-assessment -->`, `<!-- mach6-plan -->`, `<!-- mach6-review -->`, `<!-- mach6-progress -->` as the first line of comment bodies for reliable discovery.
+3. **No `#N` in comment bodies** — GitHub auto-links `#N` to issues/PRs. Use "finding 3", "item 3", "stage 2" etc. instead.
+4. **Safe git** — Never use `git add -A` or `git add .`. Stage files by name. Never stage secrets (.env, credentials, tokens, keys).
+5. **Task tracking** — Use the `tasks_update` tool to show progress through multi-step commands.
+6. **Project conventions** — Check for CLAUDE.md, AGENTS.md, .dreb/CONTEXT.md, and CONTRIBUTING.md before planning or implementing.
+
+## Determine Mode
+
+If the input is a number, run **ASSESS** mode. Otherwise, run **CREATE** mode.
+
+---
+
+## ASSESS Mode
+
+**Assess an existing GitHub issue — explore the codebase, identify scope/risks/ambiguities, post assessment.**
+
+### Step 1: Set up task tracking
+
+```
+tasks_update([
+  { id: "read", title: "Read issue and comments", status: "in_progress" },
+  { id: "explore", title: "Explore relevant codebase", status: "pending" },
+  { id: "assess", title: "Analyze and assess", status: "pending" },
+  { id: "post", title: "Post assessment", status: "pending" }
+])
+```
+
+### Step 2: Read the issue
+
+```bash
+gh issue view <number>
+gh issue view <number> --comments
+```
+
+Parse: problem statement, constraints, requirements, acceptance criteria, prior discussion, linked PRs.
+
+Update task: read → completed, explore → in_progress.
+
+### Step 3: Explore the codebase
+
+Launch 2-3 Explore subagents in parallel targeting different aspects. Agent definitions specify their own model with a provider fallback list — defaults work across providers and are fine for most cases. Override only with good reason (e.g. a particularly complex issue warrants a stronger tier).
+- **Relevant code**: Find existing code related to the issue, trace implementation patterns
+- **Architecture**: Map relevant architecture layers, abstractions, data flow
+- **Prior work**: Check for related branches, PRs, or commits
+
+Each agent should return 5-10 key files. After agents complete, read all identified files.
+
+Update task: explore → completed, assess → in_progress.
+
+### Step 4: Assess
+
+Present to the user:
+1. **Summary**: The issue in your own words
+2. **Current state**: What exists today that's relevant
+3. **Gaps**: What's missing, broken, or unclear
+4. **Ambiguities**: Underspecified aspects or open questions
+5. **Scope**: Size and complexity estimate
+6. **Risks**: Pitfalls, edge cases, architectural concerns
+
+### Step 5: Post assessment
+
+Post as an issue comment:
+
+```bash
+gh issue comment <number> --body "<!-- mach6-assessment -->
+## Issue Assessment
+
+<assessment content>
+
+---
+*Automated assessment by mach6*"
+```
+
+Update task: post → completed.
+
+Suggest next step: `/skill:mach6-plan <number>`
+
+---
+
+## CREATE Mode
+
+**Create a new structured GitHub issue from context or description.**
+
+### Step 1: Gather context
+
+If a description was provided, use it as the starting point. Otherwise, ask the user what they want to create an issue for.
+
+Check if the repository has issue templates:
+```bash
+ls .github/ISSUE_TEMPLATE/ 2>/dev/null
+```
+If templates exist, read them and select the most appropriate one.
+
+Explore the codebase if needed to understand the relevant area.
+
+### Step 2: Draft the issue
+
+Create a structured issue with:
+- **Title**: Clear, concise, action-oriented (under 80 chars, imperative form)
+- **Summary**: 2-3 sentences describing the problem or feature
+- **Current Behavior** (for bugs/improvements): What happens now
+- **Proposed Behavior**: What should happen
+- **Acceptance Criteria**: Bullet list of verifiable conditions that define "done"
+- **Context**: Links to related PRs, issues, or discussions
+- **Technical Notes**: Implementation hints, relevant files, architectural considerations
+- **Labels**: Suggest appropriate labels based on the issue type
+
+Present the draft to the user for approval.
+
+### Step 3: Create the issue
+
+```bash
+gh issue create --title "<title>" --body "<body>" [--label "<labels>"]
+```
+
+Report the issue number and URL. Suggest next step: `/skill:mach6-plan <number>`

package/skills/mach6-plan/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: mach6-plan
+description: "Explore codebase, create implementation plan, create feature branch with dummy commit, open draft PR, post plan as PR comment. Everything lives on the PR from this point forward. Usage: mach6-plan 42"
+argument-hint: "<issue-number>"
+---
+
+# mach6-plan — Plan, Branch, and Open PR
+
+**User input:** $ARGUMENTS
+
+This command is strictly for **planning**. Do NOT implement any code changes — no file edits, no file writes.
+
+## Global Rules
+
+1. **GitHub as shared memory** — Plans, reviews, assessments, and progress are posted as PR/issue comments so any future session can pick up context.
+2. **HTML markers** — Use `<!-- mach6-plan -->` as the first line of plan comment bodies for reliable discovery.
+3. **No `#N` in comment bodies** — GitHub auto-links `#N` to issues/PRs. Use "finding 3", "item 3", "stage 2" etc. instead.
+4. **Safe git** — Never use `git add -A` or `git add .`. Stage files by name. Never stage secrets.
+5. **Task tracking** — Use the `tasks_update` tool to show progress through multi-step commands.
+6. **Project conventions** — Check for CLAUDE.md, AGENTS.md, .dreb/CONTEXT.md, and CONTRIBUTING.md before planning.
+
+## Step 1: Set up task tracking
+
+```
+tasks_update([
+  { id: "read", title: "Read issue and context", status: "in_progress" },
+  { id: "explore", title: "Explore codebase", status: "pending" },
+  { id: "plan", title: "Draft implementation plan", status: "pending" },
+  { id: "branch", title: "Create branch and draft PR", status: "pending" },
+  { id: "post", title: "Post plan to PR", status: "pending" }
+])
+```
+
+## Step 2: Read the issue
+
+```bash
+gh issue view <number>
+gh issue view <number> --comments
+```
+
+Parse everything: problem statement, constraints, requirements, acceptance criteria, prior discussion, any existing assessment comments (look for `<!-- mach6-assessment -->`).
+
+Update task: read → completed, explore → in_progress.
+
+## Step 3: Read project conventions
+
+Check for and read (first found):
+- CONTRIBUTING.md, DEVELOPMENT.md, .github/CONTRIBUTING.md
+- CLAUDE.md, AGENTS.md, .dreb/CONTEXT.md
+
+Extract planning-relevant guidance: project layers, testing expectations, coding conventions.
+
+## Step 4: Explore the codebase
+
+Launch 2-3 Explore subagents in parallel. Agent definitions specify their own model with a provider fallback list — defaults work across providers and are fine for most cases. Override only with good reason (e.g. a particularly large or complex codebase warrants a stronger tier).
+- **Similar features**: Find existing code that solves related problems, trace implementation patterns
+- **Architecture**: Map relevant architecture layers, abstractions, data flow
+- **Integration points**: Identify where new code connects to existing systems
+
+Include project conventions in each agent's context. Each agent returns 5-10 key files. Read all identified files.
+
+Update task: explore → completed, plan → in_progress.
+
+## Step 5: Draft the plan
+
+Create an implementation plan with:
+- Clear analysis of the problem
+- **Deliverables**: What will be produced (be specific)
+- **Acceptance criteria**: How to verify the work is done
+- **Files to create or modify**: List each with what changes
+- **Testing approach**: What tests to write, what to verify
+- **Risks and open questions**: Anything that might derail implementation
+
+The plan should be **high-level on implementation details** (avoid cascading spec errors from over-specifying) but **specific on deliverables and acceptance criteria**.
+
+**Project-layer coverage:** Cross-check the plan against discovered project layers. Every affected layer should be addressed.
+
+**Test coverage is mandatory, not optional.** Every new behavior, command handler, formatting function, or event wiring must include tests in the plan. If the target package lacks test infrastructure, the plan must include setting it up as a deliverable — this cannot be deferred. The testing approach should specify:
+- Which test files to create or modify
+- What behaviors to verify (happy paths, error paths, edge cases)
+- What test infrastructure/helpers are needed (mocks, factories, fixtures)
+
+Present the plan to the user. Discuss and revise if they have feedback.
+
+Update task: plan → completed, branch → in_progress.
+
+## Step 6: Create branch and draft PR
+
+```bash
+# Derive branch name from issue
+# Format: feature/issue-<N>-<slug> (slug = 3-5 words from title, lowercase, hyphens)
+git checkout -b feature/issue-<N>-<slug>
+
+# Create an empty commit so the PR can be opened
+git commit --allow-empty -m "chore: open PR for issue <N>"
+
+git push -u origin feature/issue-<N>-<slug>
+
+# Open draft PR
+gh pr create --draft --title "<title>" --body "Closes #<N>
+
+<brief description>
+
+Implementation plan posted as a comment below."
+```
+
+Update task: branch → completed, post → in_progress.
+
+## Step 7: Post plan to PR
+
+```bash
+gh pr comment <pr-number> --body "<!-- mach6-plan -->
+## Implementation Plan
+
+<full plan content>
+
+---
+*Plan created by mach6*"
+```
+
+Update task: post → completed.
+
+Suggest next step: implement the plan, then `/skill:mach6-push` when ready.