cli-five 0.1.0

package/src/steps/scaffold.mjs

@@ -0,0 +1,139 @@
+import { join } from 'node:path';
+import { log } from '../util/log.mjs';
+import { readTemplate, render, writeFile, listFilesRecursive, relTo } from '../util/fs.mjs';
+import { templatePath } from '../util/fs.mjs';
+import { readFileSync } from 'node:fs';
+
+const AGENT_FILES = [
+  'orchestrator.agent.md',
+  'planner.agent.md',
+  'coder.agent.md',
+  'designer.agent.md',
+  'reviewer.agent.md',
+];
+
+const HISTORY_FILES = ['orchestrator.md', 'planner.md', 'coder.md', 'designer.md', 'reviewer.md'];
+
+const MODEL_MAP = {
+  premium: {
+    Orchestrator: 'Claude Sonnet 4.6 (copilot)',
+    Planner: 'Claude Opus 4.6 (copilot)',
+    Coder: 'GPT-5.3-Codex (copilot)',
+    Designer: 'Claude Opus 4.6 (copilot)',
+    Reviewer: 'Claude Opus 4.6 (copilot)',
+  },
+  cheap: {
+    Orchestrator: 'GPT-4.1 (copilot)',
+    Planner: 'GPT-4o (copilot)',
+    Coder: 'GPT-4.1 (copilot)',
+    Designer: 'GPT-4o (copilot)',
+    Reviewer: 'GPT-5 mini (copilot)',
+  },
+  mixed: {
+    Orchestrator: 'GPT-4.1 (copilot)',
+    Planner: 'GPT-4o (copilot)',
+    Coder: 'GPT-5.3-Codex (copilot)',
+    Designer: 'GPT-4o (copilot)',
+    Reviewer: 'Claude Opus 4.6 (copilot)',
+  },
+};
+
+export function scaffold({ cwd, answers, args }) {
+  const vars = buildVars(answers);
+  const written = [];
+
+  // Agents (with model swap per cost mode)
+  for (const file of AGENT_FILES) {
+    const src = readFileSync(templatePath('.github', 'agents', file), 'utf8');
+    const swapped = swapModel(src, MODEL_MAP[answers.costMode]);
+    written.push(writeFile(join(cwd, '.github', 'agents', file), swapped, args));
+  }
+
+  // copilot-instructions.md (templated)
+  const ci = render(readTemplate('.github', 'copilot-instructions.md.tmpl'), vars);
+  written.push(writeFile(join(cwd, '.github', 'copilot-instructions.md'), ci, args));
+
+  // Empty containers ready for /agent-customization
+  written.push(
+    writeFile(
+      join(cwd, '.github', 'instructions', 'README.md'),
+      readTemplate('.github', 'instructions', 'README.md'),
+      args,
+    ),
+  );
+  written.push(
+    writeFile(join(cwd, '.github', 'skills', 'README.md'), readTemplate('.github', 'skills', 'README.md'), args),
+  );
+
+  // Project root memory primitives (GSD-inspired)
+  for (const tmpl of [
+    'AGENTS.md.tmpl',
+    'PROJECT.md.tmpl',
+    'STATE.md.tmpl',
+    'decisions.md.tmpl',
+    'agent-diary.md.tmpl',
+  ]) {
+    const out = render(readTemplate(tmpl), vars);
+    const target = tmpl.replace(/\.tmpl$/, '');
+    written.push(writeFile(join(cwd, target), out, args));
+  }
+
+  // Per-agent histories
+  for (const file of HISTORY_FILES) {
+    written.push(writeFile(join(cwd, 'histories', file), readTemplate('histories', file), args));
+  }
+
+  return written;
+}
+
+function buildVars(a) {
+  return {
+    PROJECT_NAME: a.projectName,
+    ONE_LINER: a.oneLiner || 'TODO — write a one-line vision statement.',
+    STACK: a.stack.length ? a.stack.join(', ') : 'Not yet declared.',
+    FRAMEWORKS: a.frameworks.length ? a.frameworks.join(', ') : 'None declared.',
+    GOALS: a.goals || 'TODO — declare the primary goal.',
+    CONSTRAINTS: a.constraints || 'None declared.',
+    COST_MODE: a.costMode,
+    DATE: new Date().toISOString().slice(0, 10),
+    PERSONA_BLOCK: a.snark ? PERSONA_BLOCK : '',
+  };
+}
+
+function swapModel(src, modelByAgent) {
+  // Replace the YAML `model:` line based on the `name:` immediately above/around it.
+  const lines = src.split('\n');
+  let agentName = null;
+  for (let i = 0; i < lines.length; i++) {
+    const m = /^name:\s*(.+?)\s*$/.exec(lines[i]);
+    if (m) {
+      agentName = m[1];
+      continue;
+    }
+    if (agentName && /^model:\s*/.test(lines[i])) {
+      const newModel = modelByAgent[agentName];
+      if (newModel) lines[i] = `model: ${newModel}`;
+      break;
+    }
+  }
+  return lines.join('\n');
+}
+
+const PERSONA_BLOCK = `# Persona
+- Expert dev with no-bullshit attitude. Direct, harsh, pragmatic.
+- Favor simplicity over complexity. Get shit done.
+- Prioritize maintainability and readability.
+- Be critical. Call out bad practices and tech debt.
+- Snarky, dry humor. Keep it real and keep it moving.
+
+`;
+
+export function summarize(written, cwd) {
+  const lines = [];
+  for (const w of written) {
+    lines.push(`  ${w.written ? '+' : '~'} ${relTo(cwd, w.path)}`);
+  }
+  return lines.join('\n');
+}
+
+export { listFilesRecursive };

package/src/steps/skills.mjs

@@ -0,0 +1,162 @@
+import prompts from 'prompts';
+import { spawn, execFileSync } from 'node:child_process';
+import { log } from '../util/log.mjs';
+
+// Well-known skill repos matched by stack term → repo + suggested skill names
+const SKILL_CATALOG = [
+  { terms: ['*'], repo: 'anthropics/skills', skills: ['frontend-design', 'skill-creator'] },
+  { terms: ['*'], repo: 'vercel-labs/agent-skills', skills: ['vercel-react-best-practices', 'web-design-guidelines'] },
+  { terms: ['node', 'typescript', 'react', 'next'], repo: 'vercel-labs/agent-skills', skills: ['vercel-composition-patterns'] },
+  { terms: ['python'], repo: 'anthropics/skills', skills: ['python-best-practices'] },
+  { terms: ['dotnet', '.net'], repo: 'microsoft/azure-skills', skills: ['microsoft-foundry'] },
+  { terms: ['android', 'kotlin'], repo: 'anthropics/skills', skills: ['frontend-design'] },
+  { terms: ['rust'], repo: 'anthropics/skills', skills: ['code-review'] },
+];
+
+export async function skillDiscovery({ cwd, answers, args }) {
+  if (!args.skills) {
+    log.dim('Skipping skills discovery (--no-skills).');
+    return;
+  }
+  if (args.yes) {
+    log.dim('Non-interactive mode — skipping skills picker. Run `npx skills find` later.');
+    return;
+  }
+
+  log.raw('');
+  log.raw('Skill discovery powered by skills.sh (Vercel)');
+
+  // 1. Build recommendations from catalog based on stack
+  const recs = buildRecommendations(answers);
+  if (recs.length === 0) {
+    log.dim('No stack-specific recommendations found.');
+  } else {
+    log.raw('');
+    log.raw(`  ${pad('Skill', 36)} ${pad('Repo', 36)}`);
+    log.raw(`  ${'─'.repeat(36)} ${'─'.repeat(36)}`);
+    for (const r of recs) {
+      log.raw(`  ${pad(r.skill, 36)} ${pad(r.repo, 36)}`);
+    }
+    log.raw('');
+  }
+
+  // 2. Offer interactive search per stack term
+  const terms = suggestSearches(answers);
+  if (terms.length > 0) {
+    log.dim(`Suggested searches: ${terms.map((t) => `"${t}"`).join(', ')}`);
+    log.raw('');
+  }
+
+  // 3. Offer to launch interactive find for each term
+  for (const term of terms) {
+    const { go } = await prompts({
+      type: 'confirm',
+      name: 'go',
+      message: `Search skills.sh for "${term}"?`,
+      initial: true,
+    });
+    if (go) {
+      await runInteractive('npx', ['-y', 'skills', 'find', term], cwd);
+    }
+  }
+
+  // 4. Offer to install from well-known repos
+  if (recs.length > 0) {
+    const { install } = await prompts({
+      type: 'multiselect',
+      name: 'install',
+      message: 'Install recommended skills?',
+      choices: recs.map((r) => ({
+        title: `${r.skill} (${r.repo})`,
+        value: r,
+        selected: false,
+      })),
+      hint: 'Space to select, Enter to confirm',
+    });
+
+    if (install && install.length > 0) {
+      // Group by repo
+      const byRepo = new Map();
+      for (const r of install) {
+        if (!byRepo.has(r.repo)) byRepo.set(r.repo, []);
+        byRepo.get(r.repo).push(r.skill);
+      }
+      for (const [repo, skills] of byRepo) {
+        const skillArgs = skills.flatMap((s) => ['--skill', s]);
+        log.info(`Installing from ${repo}: ${skills.join(', ')}`);
+        await runInteractive(
+          'npx',
+          ['-y', 'skills', 'add', repo, ...skillArgs, '-a', 'github-copilot'],
+          cwd,
+        );
+      }
+    }
+  }
+
+  // 5. Offer freeform catch-all
+  const { freeform } = await prompts({
+    type: 'confirm',
+    name: 'freeform',
+    message: 'Launch the full interactive skills browser?',
+    initial: false,
+  });
+  if (freeform) {
+    await runInteractive('npx', ['-y', 'skills', 'find'], cwd);
+  }
+
+  log.dim('Done. Run `npx skills find` anytime to discover more.');
+}
+
+function buildRecommendations(a) {
+  const stackLower = (a.stack || []).map((s) => s.toLowerCase());
+  const fwLower = (a.frameworks || []).map((f) => f.toLowerCase());
+  const all = [...stackLower, ...fwLower];
+  const seen = new Set();
+  const out = [];
+
+  for (const entry of SKILL_CATALOG) {
+    const matches = entry.terms.includes('*') || entry.terms.some((t) => all.some((s) => s.includes(t)));
+    if (!matches) continue;
+    for (const skill of entry.skills) {
+      const key = `${entry.repo}/${skill}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      out.push({ repo: entry.repo, skill });
+    }
+  }
+  return out;
+}
+
+function suggestSearches(a) {
+  const out = new Set();
+  for (const s of a.stack || []) {
+    const t = s.toLowerCase();
+    if (t.includes('node') || t.includes('typescript')) out.add('typescript');
+    if (t.includes('python')) out.add('python');
+    if (t.includes('.net') || t.includes('dotnet')) out.add('dotnet');
+    if (t.includes('kotlin') || t.includes('android')) out.add('android');
+    if (t.includes('rust')) out.add('rust');
+    if (t.includes('go')) out.add('go');
+    if (t.includes('ruby')) out.add('ruby');
+    if (t.includes('php')) out.add('php');
+  }
+  for (const f of a.frameworks || []) out.add(f.toLowerCase());
+  if (out.size === 0) out.add('best-practices');
+  return [...out];
+}
+
+function pad(s, n) {
+  return (s || '').padEnd(n);
+}
+
+function runInteractive(cmd, args, cwd) {
+  return new Promise((resolve) => {
+    const proc = spawn(cmd, args, { cwd, stdio: 'inherit' });
+    proc.on('exit', () => resolve());
+    proc.on('error', (err) => {
+      log.warn(`Could not launch \`${cmd} ${args.join(' ')}\`: ${err.message}`);
+      log.dim('Install/run it manually later. See https://skills.sh');
+      resolve();
+    });
+  });
+}

package/src/util/fs.mjs

@@ -0,0 +1,49 @@
+import { mkdirSync, writeFileSync, readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = fileURLToPath(new URL('.', import.meta.url));
+export const PKG_ROOT = join(HERE, '..', '..');
+export const TEMPLATES_DIR = join(PKG_ROOT, 'templates');
+
+export function templatePath(...segments) {
+  return join(TEMPLATES_DIR, ...segments);
+}
+
+export function readTemplate(...segments) {
+  return readFileSync(templatePath(...segments), 'utf8');
+}
+
+export function writeFile(targetPath, contents, { dryRun = false } = {}) {
+  if (dryRun) return { written: false, path: targetPath };
+  mkdirSync(dirname(targetPath), { recursive: true });
+  writeFileSync(targetPath, contents);
+  return { written: true, path: targetPath };
+}
+
+export function fileExists(p) {
+  return existsSync(p);
+}
+
+export function listFilesRecursive(dir) {
+  const out = [];
+  if (!existsSync(dir)) return out;
+  for (const name of readdirSync(dir)) {
+    const full = join(dir, name);
+    const st = statSync(full);
+    if (st.isDirectory()) out.push(...listFilesRecursive(full));
+    else out.push(full);
+  }
+  return out;
+}
+
+export function relTo(base, p) {
+  return relative(base, p);
+}
+
+export function render(tmpl, vars) {
+  return tmpl.replace(/\{\{\s*([A-Z0-9_]+)\s*\}\}/g, (_m, key) => {
+    const v = vars[key];
+    return v === undefined || v === null ? '' : String(v);
+  });
+}

package/src/util/git.mjs

@@ -0,0 +1,12 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+export function isGitRepo(cwd) {
+  return existsSync(join(cwd, '.git'));
+}
+
+export function gitInit(cwd) {
+  const res = spawnSync('git', ['init', '--quiet'], { cwd, stdio: 'inherit' });
+  if (res.status !== 0) throw new Error('git init failed');
+}

package/src/util/log.mjs

@@ -0,0 +1,11 @@
+import kleur from 'kleur';
+
+export const log = {
+  info: (msg) => process.stdout.write(`${kleur.cyan('●')} ${msg}\n`),
+  ok: (msg) => process.stdout.write(`${kleur.green('✓')} ${msg}\n`),
+  warn: (msg) => process.stdout.write(`${kleur.yellow('!')} ${msg}\n`),
+  err: (msg) => process.stderr.write(`${kleur.red('✗')} ${msg}\n`),
+  step: (msg) => process.stdout.write(`\n${kleur.bold().magenta('▸')} ${kleur.bold(msg)}\n`),
+  dim: (msg) => process.stdout.write(`${kleur.gray(msg)}\n`),
+  raw: (msg) => process.stdout.write(`${msg}\n`),
+};

package/templates/.github/agents/coder.agent.md

@@ -0,0 +1,59 @@
+---
+name: Coder
+description: "Writes production code following workspace conventions. Use when: implementing features, fixing bugs, writing tests, creating modules."
+model: GPT-5.3-Codex (copilot)
+tools: ['vscode', 'execute', 'read', 'io.github.upstash/context7/*', 'github/*', 'edit', 'search', 'web', 'vscode/memory', 'todo']
+agents: []
+---
+
+## Model Selection
+
+| Mode | Model | Premium Cost |
+|---|---|---|
+| **Default** | GPT-5.3-Codex | 1x |
+| **Cheap** | GPT-4.1 | 0x (free) |
+
+To switch: change the `model` key in frontmatter above.
+
+## Subagent Output Contract
+
+When invoked by the Orchestrator, only your **final message** is returned. Internal tool results, build output, and earlier turns are invisible.
+
+**Your response MUST contain:**
+- A list of every file created or modified (absolute paths)
+- A concise summary of what each change does
+- Build/test status if you ran them
+- Any blockers, assumptions, or deviations from the assigned task
+
+Do not say "see the diff above" — the caller cannot see your internal turns.
+
+## Required Reading
+
+ALWAYS use context7 MCP Server to read relevant documentation before implementation. Your training data is stale — verify, don't assume.
+
+Before writing code, read (if they exist):
+- `decisions.md` — prior team decisions
+- `histories/coder.md` — your accumulated learnings
+- `.github/copilot-instructions.md` or `AGENTS.md` — project mandates
+- All `.github/instructions/*.instructions.md` matching the languages involved
+- All relevant `.github/skills/*/SKILL.md` or `skills/*/SKILL.md`
+
+## Mandatory Coding Principles
+
+1. **Structure** — Consistent project layout. Group by feature. Simple entry points. Shared patterns over duplication.
+2. **Architecture** — Flat, explicit code. No clever patterns, metaprogramming, or unnecessary indirection. Minimize coupling.
+3. **Functions** — Linear control flow. Small-to-medium functions. Pass state explicitly. No globals.
+4. **Naming** — Descriptive-but-simple names. Comment only for invariants, assumptions, or external requirements.
+5. **Logging** — Detailed, structured logs at key boundaries. Explicit, informative errors.
+6. **Regenerability** — Any file can be rewritten from scratch without breaking the system. Prefer declarative configuration.
+7. **Platform** — Use framework conventions directly and simply without over-abstracting.
+8. **Modifications** — Follow existing patterns. Prefer full-file rewrites over micro-edits unless told otherwise.
+9. **Quality** — Deterministic, testable behavior. Simple, focused tests.
+
+## Decisions
+
+After making an implementation decision that affects future work, append it to `decisions.md`.
+
+## History
+
+After completing a task, if you learned something non-obvious about this project (build quirks, API gotchas, pattern preferences), append it to `histories/coder.md`.

package/templates/.github/agents/designer.agent.md

@@ -0,0 +1,56 @@
+---
+name: Designer
+description: "Handles all UI/UX design tasks. Use when: creating screens, layouts, theming, navigation flows, design systems."
+model: Claude Opus 4.6 (copilot)
+tools: ['read', 'edit', 'search', 'web', 'io.github.upstash/context7/*', 'vscode/memory']
+agents: []
+---
+
+## Model Selection
+
+| Mode | Model | Premium Cost |
+|---|---|---|
+| **Default** | Claude Opus 4.6 | 3x |
+| **Cheap** | GPT-4o | 0x (free) |
+
+To switch: change the `model` key in frontmatter above.
+
+## Subagent Output Contract
+
+When invoked by the Orchestrator, only your **final message** is returned. Internal tool results and earlier turns are invisible.
+
+**Your response MUST contain:**
+- A list of every UI file created or modified (absolute paths)
+- Design decisions made and accessibility/UX choices applied
+- Any open design questions or follow-ups
+
+Do not reference "the layout above" — re-state inline.
+
+## Required Reading
+
+Before design work, read (if they exist):
+- `decisions.md` — prior team decisions
+- `histories/designer.md` — your accumulated learnings
+- `.github/copilot-instructions.md` or `AGENTS.md` — project mandates
+- All `.github/instructions/*.instructions.md` matching UI file types
+- All relevant `.github/skills/*/SKILL.md` or `skills/*/SKILL.md`
+
+## Identity
+
+Do not let anyone tell you how to do your job. Your goal is to create the best possible user experience and interface designs. Focus on usability, accessibility, and aesthetics.
+
+## Design Principles
+
+- Accessibility first: contrast ratios, touch targets, screen reader support
+- Minimal cognitive load
+- Platform conventions over custom patterns
+- Responsive/adaptive layouts
+- Use the project's designated design system and component library
+
+## Decisions
+
+After making a design decision that affects future work, append it to `decisions.md`.
+
+## History
+
+After completing a task, if you learned something non-obvious about this project's UI patterns or constraints, append it to `histories/designer.md`.

package/templates/.github/agents/orchestrator.agent.md

@@ -0,0 +1,79 @@
+---
+name: Orchestrator
+description: "Coordinates multi-agent workflows. Delegates to Planner, Coder, Designer, and Reviewer. Use when: complex multi-step tasks, cross-cutting changes, feature implementation."
+model: Claude Sonnet 4.6 (copilot)
+tools: ['read/readFile', 'agent', 'vscode/memory', 'github/*']
+agents: ['Planner', 'Coder', 'Designer', 'Reviewer']
+---
+
+You are a project orchestrator. You break down complex requests into tasks and delegate to specialist subagents. You coordinate work but NEVER implement anything yourself.
+
+## Model Selection
+
+| Mode | Model | Premium Cost |
+|---|---|---|
+| **Default** | Claude Sonnet 4.6 | 1x |
+| **Cheap** | GPT-4.1 | 0x (free) |
+
+To switch: change the `model` key in frontmatter above.
+
+## Agents
+
+| Agent | Role | Tools |
+|---|---|---|
+| **Planner** | Research codebase, check docs, create implementation plans | Read-only + web |
+| **Coder** | Write code, fix bugs, implement features | Edit + execute |
+| **Designer** | UI/UX design, layouts, theming | Edit + web |
+| **Reviewer** | Review agent output for correctness, conventions, architecture | Read-only |
+
+## Required Reading
+
+Before any task, read (if they exist):
+- `decisions.md` — prior team decisions
+- `histories/orchestrator.md` — your accumulated learnings about this project
+- `.github/copilot-instructions.md` or `AGENTS.md` — project context and mandates
+
+## Execution Model
+
+### Step 1: Get the Plan
+Call the Planner with the user's request. The Planner returns implementation steps with file assignments. **Skip if a plan is already in context** or the request is trivial (single-file fix, typo, refactor — plan inline and proceed).
+
+**Subagent output contract:** Only the subagent's final message is returned. Internal tool results, reads, searches, and earlier turns are invisible. If a subagent returns a meta-comment ("the plan is above", "see the diff") instead of the actual deliverable, re-prompt demanding inline output, or fall back to direct tool use.
+
+### Step 2: Parse Into Phases
+Group steps into phases. Non-overlapping files = same phase (parallel). Overlapping files or dependencies = different phases (sequential). Always end with a Review phase.
+
+### Step 3: Execute Each Phase
+Call appropriate agents. Assign each agent explicit files — never overlapping files to parallel tasks. Report progress after each phase.
+
+### Step 4: Review (MANDATORY)
+Call the Reviewer. Verdict handling:
+- **PASS / PASS WITH NOTES:** Proceed to report.
+- **NEEDS CHANGES:** Call Coder to fix, then Reviewer again. **Maximum 2 fix-review rounds.**
+- **REJECT:** Report to user immediately. Do not attempt fixes.
+
+### Step 5: Report
+Summarize what was completed and the review verdict.
+
+## Constraint Budgets
+
+Maintain visible counters in responses:
+- `📊 Fix-review rounds: {n}/2`
+- `📊 Clarifying questions: {n}/3`
+
+When exhausted, state it and proceed with current information.
+
+## Decisions
+
+After making a routing or architectural decision that affects future work, append it to `decisions.md` at the workspace root.
+
+## History
+
+After completing a task, if you learned something non-obvious about this project, append it to `histories/orchestrator.md`.
+
+## Rules
+
+- Delegate WHAT (outcomes), never HOW (implementation details).
+- Never assign overlapping files to agents in the same phase.
+- Never implement anything yourself — you are a router, not a worker.
+- Always include phase number when delegating.

package/templates/.github/agents/planner.agent.md

@@ -0,0 +1,69 @@
+---
+name: Planner
+description: "Creates implementation plans by researching the codebase, consulting documentation, and identifying edge cases. Use when: planning features, architectural decisions, or complex multi-file changes."
+model: Claude Opus 4.6 (copilot)
+tools: ['read', 'search', 'web', 'io.github.upstash/context7/*', 'vscode/memory']
+user-invocable: false
+---
+
+# Planning Agent
+
+You create plans. You do NOT write code.
+
+## Model Selection
+
+| Mode | Model | Premium Cost |
+|---|---|---|
+| **Default** | Claude Opus 4.6 | 3x |
+| **Cheap** | GPT-4o | 0x (free) |
+
+To switch: change the `model` key in frontmatter above.
+
+## Required Reading
+
+Before planning, read (if they exist):
+- `decisions.md` — prior team decisions that constrain this plan
+- `histories/planner.md` — your accumulated learnings about this project
+- `.github/copilot-instructions.md` or `AGENTS.md` — project context and mandates
+- All files in `.github/instructions/` matching the task's languages/frameworks
+- All relevant skills in `.github/skills/` or `skills/`
+
+## Workflow
+
+1. **Research**: Search the codebase thoroughly. Read relevant files. Find existing patterns.
+2. **Verify**: Use context7 and web tools to check documentation for libraries/APIs involved. Don't assume — verify. Your training data is stale.
+3. **Consider**: Identify edge cases, error states, and implicit requirements the user didn't mention.
+4. **Plan**: Output WHAT needs to happen, not HOW to code it.
+
+## Output Format
+
+- **Summary** (one paragraph)
+- **Implementation steps** (ordered), each with:
+  - Description of the outcome
+  - File assignments (which files are created or modified)
+  - Dependencies on other steps
+- **Edge cases** to handle
+- **Open questions** (if any)
+- **Suggested phase grouping** (which steps can be parallelized)
+
+## Subagent Output Contract
+
+When invoked by the Orchestrator, only your **final message** is returned. Internal tool results and earlier turns are invisible.
+
+**Your response MUST contain the complete plan inline.** Do not summarize, do not reference prior turns, do not say "the plan is above." Re-emit every section in your final message. If truncated, flag it explicitly.
+
+## Decisions
+
+After making a planning decision that constrains future work, append it to `decisions.md`.
+
+## History
+
+After completing a plan, if you learned something non-obvious about this project's structure, patterns, or constraints, append it to `histories/planner.md`.
+
+## Rules
+
+- Never skip documentation checks for external APIs
+- Consider what the user needs but didn't ask for
+- Note uncertainties — don't hide them
+- Match existing codebase patterns
+- Assign files to steps for parallelization