opencode-agile-agent 1.2.0 → 1.2.1

package/README.md

@@ -7,10 +7,53 @@ Scaffold the OpenCode spec-driven agent kit into any project with one confirmati
 - `npx opencode-agile-agent@latest`
 - `npx create-opencode-agile`
 
+## Example Command Flow
+
+### Start a new project
+1. Run `npx opencode-agile-agent` inside the repo you want to set up.
+2. Ask the main agent to clarify the project direction first.
+3. Use `/brainstorm` if the idea is still fuzzy.
+4. Use `/plan` once the scope is clear enough to turn into `brief.md`, `spec.md`, `task.md`, `notes.md`, and `status.yaml`.
+5. Use `/create` when you want the first implementation pass to begin.
+6. Use `/test` and `/review` before considering the first slice done.
+7. Use `/archive` when the finished slice is approved and worth preserving as a summary.
+
+Example:
+```text
+/brainstorm build a small SaaS app for tracking invoices for freelancers
+/plan turn this into an MVP with auth, invoice CRUD, and dashboard
+/create implement the MVP from the approved plan
+/test cover the critical flows
+/review check if this is safe to ship
+/archive summarize what shipped in the approved MVP slice
+```
+
+### Start a new feature in an existing project
+1. Start with `/brainstorm` if the request is ambiguous.
+2. Use `/plan` to define the feature boundary and acceptance criteria.
+3. Use `/create` to implement the approved feature slice.
+4. Use `/test` to verify behavior and nearby paths.
+5. Use `/review` for the final quality gate.
+6. Use `/archive` after approval to store a finished work summary.
+7. Use `/status` anytime you want a compact progress snapshot.
+
+Example:
+```text
+/plan add team invitations with email, role selection, and acceptance flow
+/create implement the invitations feature
+/test verify invite creation, email sending, and acceptance flow
+/review check for regressions, dead code, and spec drift
+/archive summarize the approved invitations slice
+```
+
 ## Install Flow
 - The installer asks one yes/no question.
 - Framework, language, and project name are auto-detected.
-- Confirmed installs copy `.opencode` into the current project root and generate `AGENTS.md` there.
+- Confirmed installs merge `.opencode` into the current project root instead of replacing it.
+- If `templates/opencode.json` exists, the installer also creates or merges `opencode.json` in the project root.
+- If the project already uses `opencode.jsonc` (and not `opencode.json`), the installer skips config installation to avoid creating a competing config file.
+- Missing files are created. Existing `.md`, `.txt`, and `.gitignore` files receive appended template content when it is not already present.
+- Existing `.json` files are merged key-wise without clobbering existing values. Other structured files like `.ts` and `.yaml` are left in place and are not overwritten.
 - Declining exits immediately.
 
 ## Local Install
@@ -18,33 +61,53 @@ Scaffold the OpenCode spec-driven agent kit into any project with one confirmati
 - The installer writes to the current working directory, not the package directory.
 
 ## What Gets Installed
-- 26 agents
-- 14 skills
-- 10 commands
+- 15 agents
+- 15 skills
+- 11 commands
+- 1 runtime plugin
 - Shared rules, docs, and project config
 
+## Plannotator Integration
+
+- The template includes `templates/opencode.json` with `@plannotator/opencode@latest` configured.
+- With Plannotator enabled, `/plan` will use `submit_plan` (when available) to open a browser UI for plan approval and feedback.
+
 ## Custom Commands
 - `.opencode/commands/*.md` holds the slash commands.
 - Each command uses Markdown frontmatter plus a prompt body, matching OpenCode's command format.
-- The command set is `brainstorm`, `create`, `debug`, `plan`, `progress`, `reframe`, `review`, `rubber-duck`, `status`, and `test`.
+- The command set is `archive`, `assign-models`, `brainstorm`, `check-progress`, `create`, `plan`, `reframe`, `review`, `rubber-duck`, `status`, and `test`.
 
 ## Design Notes
 - Skills are compact, philosophy-first, and loaded by intent.
-- `security-gate` decides when a change needs a security gate or redteam phase.
-- `redteam-validation` simulates attacker behavior and proves exploitability.
-- `qa-automation-engineer` is support-only for harness and CI plumbing, not the default test path.
-- `orchestrator` is optional; default routing stays with `feature-lead` and the owning specialists.
+- `artifact-discipline` and `clean-code` are the core quality spine.
+- `session-artifacts` is the runtime spine that preserves active feature state and safe handoffs.
+- `retrospective-writer` captures reusable lessons from real failures and asks whether they should become a skill or rule.
+- `archiver` is a dedicated archive-summary agent, not just a final step bolted onto the lead.
+- `session_artifact_repo_delta` guards summaries and reviews against drift from the real git state.
 - The compact planning bundle is brief.md, spec.md, task.md, notes.md, and status.yaml.
 - `@feature-lead` is the primary entry point; the rest are subagents.
-- Completed feature bundles are archived in `.opencode/archive/<feature-slug>/`.
+- `.opencode/artifacts/` is local runtime state and is git-ignored by the installed template.
+- Completed work summaries are archived in `.opencode/archive/<feature-slug>.md`.
+
+## Flow Notes
+- The default command spine is `/brainstorm -> /plan -> /create -> /test -> /review -> /archive`.
+- The flow is not rigid. You can reuse commands mid-stream when the work needs them.
+- Examples:
+  - `/brainstorm` again when implementation reveals ambiguity.
+  - `/plan` again when scope changes materially.
+  - `/test` on an intermediate risky slice.
+  - `/review` before the whole feature is finished.
+  - `/archive` for one completed slice while larger work continues.
 
 ## Spec-Driven Flow
 - `@feature-lead` is the primary entry point.
+- `session_artifact_current` restores active feature state before deeper work.
 - `@context-gatherer` maps the current project before any planning or proof.
 - `@project-planner` and `@system-analyst` build `brief.md`, `spec.md`, `task.md`, `notes.md`, and `status.yaml`.
 - `@developer` implements the approved spec.
-- `@test-engineer`, `@security-auditor`, `@penetration-tester`, and `@pr-reviewer` close the loop.
-- `@feature-lead` archives the completed bundle in `.opencode/archive/<feature-slug>/`.
+- `@test-engineer`, `@retrospective-writer`, `@security-auditor`, and `@pr-reviewer` close the loop.
+- When a resolved failure exposes a durable lesson, ask whether to promote it into a reusable skill or rule.
+- `@feature-lead` archives the completed work summary in `.opencode/archive/<feature-slug>.md` through the artifact finalizer.
 
 ## Template Source Of Truth
 - `templates/.opencode` mirrors the project kit.

package/bin/cli.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 
-import { fileURLToPath } from 'url';
-import { dirname, join, sep } from 'path';
-import { existsSync, mkdirSync, cpSync, rmSync } from 'fs';
-import { createInterface } from 'readline';
+import { fileURLToPath } from 'url';
+import { dirname, extname, join, sep } from 'path';
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'fs';
+import { createInterface } from 'readline';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -45,17 +45,18 @@ const question = (prompt) => new Promise((resolve) => {
   rl.question(prompt, resolve);
 });
 
-const args = process.argv.slice(2);
-if (args.includes('--help') || args.includes('-h')) {
-  console.log(`
-OpenCode Agile Agent Installer
+const args = process.argv.slice(2);
+if (args.includes('--help') || args.includes('-h')) {
+  console.log(`
+OpenCode Agile Agent Installer
 
 Usage:
   opencode-agile-agent
 
 What it does:
   - Asks one yes/no question.
-  - Copies .opencode into the current project.
+  - Merges .opencode into the current project.
+  - Optionally merges opencode.json into the project root.
 
 Commands:
   --help, -h   Show this help message
@@ -64,9 +65,166 @@ Commands:
   process.exit(0);
 }
 
-function shouldCopyPath(path) {
-  return !path.includes(`${sep}node_modules${sep}`) && !path.endsWith(`${sep}node_modules`);
-}
+function shouldCopyPath(path) {
+  return !path.includes(`${sep}node_modules${sep}`) && !path.endsWith(`${sep}node_modules`);
+}
+
+function isAppendableTextFile(path) {
+  return path.endsWith('.md') || path.endsWith('.txt') || path.endsWith('.gitignore');
+}
+
+function isJsonFile(path) {
+  return extname(path) === '.json';
+}
+
+function appendUniqueContent(targetPath, sourceContent) {
+  const targetContent = readFileSync(targetPath, 'utf8');
+  const trimmedSource = sourceContent.trim();
+  if (!trimmedSource || targetContent.includes(trimmedSource)) {
+    return 'skipped';
+  }
+
+  const nextContent = `${targetContent.trimEnd()}\n\n${trimmedSource}\n`;
+  writeFileSync(targetPath, nextContent);
+  return 'appended';
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function mergeJsonValues(targetValue, sourceValue) {
+  if (Array.isArray(targetValue) && Array.isArray(sourceValue)) {
+    const seen = new Set(targetValue.map((item) => JSON.stringify(item)));
+    const merged = [...targetValue];
+    for (const item of sourceValue) {
+      const key = JSON.stringify(item);
+      if (!seen.has(key)) {
+        seen.add(key);
+        merged.push(item);
+      }
+    }
+    return merged;
+  }
+
+  if (isPlainObject(targetValue) && isPlainObject(sourceValue)) {
+    const merged = { ...sourceValue };
+    for (const [key, value] of Object.entries(targetValue)) {
+      if (Object.prototype.hasOwnProperty.call(sourceValue, key)) {
+        merged[key] = mergeJsonValues(value, sourceValue[key]);
+      } else {
+        merged[key] = value;
+      }
+    }
+    return merged;
+  }
+
+  return targetValue;
+}
+
+function mergeJsonFile(targetPath, sourceContent) {
+  try {
+    const sourceJson = JSON.parse(sourceContent);
+    const targetJson = JSON.parse(readFileSync(targetPath, 'utf8'));
+    const merged = mergeJsonValues(targetJson, sourceJson);
+    const nextContent = `${JSON.stringify(merged, null, 2)}\n`;
+    if (nextContent === readFileSync(targetPath, 'utf8')) {
+      return 'skipped';
+    }
+    writeFileSync(targetPath, nextContent);
+    return 'merged';
+  } catch {
+    return 'skipped';
+  }
+}
+
+function mergeDirectory(sourceDir, targetDir, stats) {
+  if (!existsSync(targetDir)) {
+    mkdirSync(targetDir, { recursive: true });
+  }
+
+  for (const entry of readdirSync(sourceDir, { withFileTypes: true })) {
+    const sourcePath = join(sourceDir, entry.name);
+    const targetPath = join(targetDir, entry.name);
+
+    if (!shouldCopyPath(sourcePath)) {
+      continue;
+    }
+
+    if (entry.isDirectory()) {
+      mergeDirectory(sourcePath, targetPath, stats);
+      continue;
+    }
+
+    if (!entry.isFile()) {
+      continue;
+    }
+
+    if (!existsSync(targetPath)) {
+      writeFileSync(targetPath, readFileSync(sourcePath));
+      stats.created += 1;
+      continue;
+    }
+
+    if (!statSync(targetPath).isFile()) {
+      stats.skipped += 1;
+      continue;
+    }
+
+    if (isJsonFile(sourcePath)) {
+      const result = mergeJsonFile(targetPath, readFileSync(sourcePath, 'utf8'));
+      if (result === 'merged') {
+        stats.appended += 1;
+      } else {
+        stats.skipped += 1;
+      }
+      continue;
+    }
+
+    if (!isAppendableTextFile(sourcePath)) {
+      stats.skipped += 1;
+      continue;
+    }
+
+    const result = appendUniqueContent(targetPath, readFileSync(sourcePath, 'utf8'));
+    if (result === 'appended') {
+      stats.appended += 1;
+    } else {
+      stats.skipped += 1;
+    }
+  }
+}
+
+function mergeProjectConfig(templatesDir, projectRoot, stats) {
+  const sourceConfig = join(templatesDir, 'opencode.json');
+  if (!existsSync(sourceConfig) || !statSync(sourceConfig).isFile()) {
+    return;
+  }
+
+  const targetJson = join(projectRoot, 'opencode.json');
+  const targetJsonc = join(projectRoot, 'opencode.jsonc');
+  if (!existsSync(targetJson) && existsSync(targetJsonc)) {
+    // Avoid generating a second competing config file in repos that already
+    // use JSONC. Ask the user to merge manually.
+    stats.skipped += 1;
+    log.warn('Found opencode.jsonc. Skipping opencode.json install; merge templates/opencode.json manually if desired.');
+    return;
+  }
+
+  const sourceContent = readFileSync(sourceConfig, 'utf8');
+  if (!existsSync(targetJson)) {
+    writeFileSync(targetJson, sourceContent);
+    stats.created += 1;
+    return;
+  }
+
+  const result = mergeJsonFile(targetJson, sourceContent);
+  if (result === 'merged') {
+    stats.appended += 1;
+  } else {
+    stats.skipped += 1;
+  }
+}
 
 async function install() {
   console.log(banner);
@@ -89,20 +247,16 @@ async function install() {
     return;
   }
 
-  if (!existsSync(target)) {
-    mkdirSync(target, { recursive: true });
-  } else {
-    rmSync(target, { recursive: true, force: true });
-    mkdirSync(target, { recursive: true });
-  }
-
-  cpSync(source, target, {
-    recursive: true,
-    overwrite: true,
-    filter: shouldCopyPath,
-  });
+  if (!existsSync(target)) {
+    mkdirSync(target, { recursive: true });
+  }
+
+  const stats = { created: 0, appended: 0, skipped: 0 };
+  mergeDirectory(source, target, stats);
+  mergeProjectConfig(templatesDir, projectRoot, stats);
 
-  log.success('Installed .opencode.');
+  log.success('Installed .opencode in merge mode.');
+  log.info(`Created ${stats.created} files, appended ${stats.appended} text files, skipped ${stats.skipped} existing files.`);
   log.title('Done');
   console.log('Start with @feature-lead and add or update AGENTS.md manually if your repo needs one.');
 

package/bin/validate-templates.js

@@ -10,57 +10,57 @@ const templatesDir = join(__dirname, '..', 'templates');
 
 // Required files for templates
 const requiredFiles = [
+  'opencode.json',
+  '.opencode/.gitignore',
   '.opencode/README.md',
   '.opencode/ARCHITECTURE.md',
   '.opencode/archive/README.md',
+  '.opencode/artifacts/README.md',
   '.opencode/config.template.json',
   '.opencode/package.json',
+  '.opencode/plugins/session-artifacts.ts',
+  '.opencode/agents/retrospective-writer.md',
+  '.opencode/agents/archiver.md',
   '.opencode/agents/context-gatherer.md',
-  '.opencode/agents/api-designer.md',
   '.opencode/agents/backend-specialist.md',
-  '.opencode/agents/code-archaeologist.md',
-  '.opencode/agents/database-architect.md',
   '.opencode/agents/debugger.md',
   '.opencode/agents/developer.md',
   '.opencode/agents/devops-engineer.md',
-  '.opencode/agents/documentation-writer.md',
-  '.opencode/agents/explorer-agent.md',
   '.opencode/agents/feature-lead.md',
   '.opencode/agents/frontend-specialist.md',
-  '.opencode/agents/game-developer.md',
-  '.opencode/agents/mobile-developer.md',
-  '.opencode/agents/orchestrator.md',
-  '.opencode/agents/penetration-tester.md',
   '.opencode/agents/performance-optimizer.md',
   '.opencode/agents/pr-reviewer.md',
-  '.opencode/agents/product-manager.md',
   '.opencode/agents/project-planner.md',
-  '.opencode/agents/qa-automation-engineer.md',
   '.opencode/agents/security-auditor.md',
-  '.opencode/agents/seo-specialist.md',
   '.opencode/agents/system-analyst.md',
   '.opencode/agents/test-engineer.md',
   '.opencode/commands/brainstorm.md',
+  '.opencode/commands/archive.md',
+  '.opencode/commands/assign-models.md',
+  '.opencode/commands/check-progress.md',
   '.opencode/commands/create.md',
-  '.opencode/commands/debug.md',
   '.opencode/commands/plan.md',
+  '.opencode/commands/reframe.md',
   '.opencode/commands/review.md',
+  '.opencode/commands/rubber-duck.md',
   '.opencode/commands/status.md',
   '.opencode/commands/test.md',
   '.opencode/skills/api-patterns/SKILL.md',
+  '.opencode/skills/archive-writing/SKILL.md',
+  '.opencode/skills/artifact-discipline/SKILL.md',
   '.opencode/skills/brainstorming/SKILL.md',
+  '.opencode/skills/clarify-first/SKILL.md',
   '.opencode/skills/clean-code/SKILL.md',
   '.opencode/skills/code-philosophy/SKILL.md',
   '.opencode/skills/context-archive/SKILL.md',
   '.opencode/skills/context-gathering/SKILL.md',
-  '.opencode/skills/frontend-design/SKILL.md',
-  '.opencode/skills/intelligent-routing/SKILL.md',
-  '.opencode/skills/parallel-agents/SKILL.md',
+'.opencode/skills/intelligent-routing/SKILL.md',
   '.opencode/skills/plan-writing/SKILL.md',
-  '.opencode/skills/redteam-validation/SKILL.md',
   '.opencode/skills/security-gate/SKILL.md',
   '.opencode/skills/systematic-debugging/SKILL.md',
   '.opencode/skills/testing-patterns/SKILL.md',
+  '.opencode/templates/review-summary.template.md',
+  '.opencode/templates/session-summary.template.md',
   '.opencode/rules/coding-standards.md',
   '.opencode/rules/git-conventions.md',
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-agile-agent",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "AI Agile Spec-Driven Development - Install .opencode agile agent system into any project",
   "keywords": [
     "ai",

package/templates/.opencode/ARCHITECTURE.md

@@ -1,88 +1,112 @@
-# OpenCode Agent Kit - Architecture
-
-## Overview
+# OpenCode Agent Kit — Architecture
 
-- 26 agents
-- 25 agents
-- 14 skills
-- 7 commands
-- Primary agent: feature-lead
-- All other agents are subagents and communicate through @ handoffs
+## Overview
+- 15 agents, 19 skills, 11 commands, 1 runtime plugin
+- Primary: feature-lead
+- All others are subagents communicating through @ handoffs
+- `session-artifacts` is the runtime spine for active feature state and handoff safety
 
 ## Request Lifecycle
-
 1. User request lands with @feature-lead.
-2. @context-gatherer maps the current project and active work.
-3. Discovery and planning create the compact context bundle.
-4. Build agents implement the approved spec.
-5. Quality agents review, test, and harden the change.
-6. Security-sensitive changes pass through @security-auditor and @penetration-tester before approval.
-7. Any failure loops back to the owning agent.
-8. Approved feature bundles are archived under .opencode/archive/<feature-slug>/.
-9. feature-lead synthesizes the final outcome.
-
-## Context Bundle
+2. @feature-lead **clarifies first** — iterates questions until scope, intent, and business value are clear. If user has no idea, offers default + trade-offs.
+3. `session_artifact_current` restores active feature state.
+4. @context-gatherer maps current project and active work.
+5. If new feature: create context bundle + status.yaml. If continuing: refresh the active artifact.
+6. Discovery and planning produce the compact context bundle.
+7. Build agents implement the approved spec from canonical handoff packets.
+8. Quality agents review, test, and harden.
+9. Security-sensitive changes pass through @security-auditor.
+10. Any failure loops back to the owning agent.
+11. When the flow may compact before the final gates, @retrospective-writer captures a compact checkpoint.
+12. After a meaningful failure is resolved, the agent may ask whether the lesson should become a reusable skill or rule.
+13. Approved work summaries archived under `.opencode/archive/<feature-slug>.md` through the artifact finalizer.
+14. @archiver writes the final archive record.
+15. feature-lead synthesizes the final outcome.
 
-- brief.md: why, outcome, scope, constraints, default choice
+## Context Bundle
+Create only for new features. Skip if no active feature and user is continuing work.
+- brief.md: why, outcome, business context, scope, constraints, default choice
 - spec.md: contract, data flow, edge cases, risks, acceptance criteria
 - task.md: ordered checklist, dependencies, owners
 - notes.md: facts, decisions, blockers, links
 - status.yaml: live execution state
 
-- `status.yaml` is the live execution artifact; the markdown files stay as stable planning/reference context.
-- `status.yaml.status` allowed values: `active`, `blocked`, `review`, `done`.
+`status.yaml.status` allowed: `brainstorm`, `planning`, `implementation`, `verification`, `review`, `done`, `blocked`.
 
 ## Archive
-
-- Archive completed bundles in `.opencode/archive/<feature-slug>/`.
-- Keep archive entries compact and aligned with the approved bundle.
-- Archive only when `status.yaml` is `done`.
-- Archive the full bundle: `brief.md`, `spec.md`, `task.md`, `notes.md`, and final `status.yaml`.
-- Finalize archive only from the main agent handling the request: `feature-lead` or `feature-loop`.
+- Archive in `.opencode/archive/<feature-slug>.md`.
+- Include the shipped summary, changed surfaces, verification signal, and remaining follow-up.
+- Finalize only when `status.yaml` is `done`.
+- Finalize only from the primary agent.
 
 ## Skill Design
-
 - Skills are small, philosophy-first mental models.
-- Skill descriptions should state the trigger and the decision domain.
+- Skill descriptions state the trigger and decision domain.
 - Prefer the smallest skill that changes the next decision.
-
-## Role Map
-
+- `artifact-discipline` keeps runtime state out of prompt memory.
+- `session-closeout` leaves a durable checkpoint before compaction or pause.
+- Use `cross-model-regression` when risky changes need multiple specialist checks across different reviewer models.
+- Promote lessons from repeated or costly failures only when they create durable guidance.
+
+## Runtime Spine
+- Active work lives in `.opencode/artifacts/features/<feature-slug>/`.
+- `.opencode/artifacts/` is local runtime state and should be git-ignored.
+- Planning docs and runtime evidence live side-by-side but stay separate.
+- Every subagent should start from `session_artifact_handoff` instead of a document dump.
+- `session_artifact_repo_delta` guards against drift between artifact state and git state.
+- Archive remains the immutable shipped summary.
+
+## Flow Rules
+- The default command spine is `/brainstorm -> /plan -> /create -> /test -> /review -> /archive`.
+- The flow is resumable and non-linear. Any command can be re-entered when the work needs that lens.
+- Re-plan on scope drift, re-brainstorm on ambiguity, re-test on risky changes, and re-review at meaningful checkpoints.
+- Use @retrospective-writer when a failure may deserve a reusable lesson.
+
+## Role Map
+
 | Stage | Agents | Responsibility |
 |-------|--------|----------------|
-| Primary | feature-lead | Owns the request, tradeoffs, and the final gate loop |
-| Context | context-gatherer | Map the current project state and archive-ready history |
-| Coordination | project-planner, explorer-agent | Split, map, and sequence the work |
-| Advanced | orchestrator | Optional multi-domain synthesis pass |
-| Product | product-manager | Define problem, value, priorities, and release scope |
-| Spec | system-analyst, api-designer, database-architect | Create the compact context bundle and contracts |
-| Build | developer, frontend-specialist, backend-specialist, mobile-developer, game-developer, devops-engineer | Implement the approved spec |
-| Quality | test-engineer, security-auditor, penetration-tester, performance-optimizer, debugger, pr-reviewer | Verify, review, and harden |
-| Automation | qa-automation-engineer | Build and maintain test harnesses and repeatable validation |
-| Output | documentation-writer, seo-specialist | Explain and publish clearly |
-| Maintenance | code-archaeologist | Clean and simplify legacy code |
-
+| Primary | feature-lead | Own request, tradeoffs, final gate loop |
+| Archive | archiver | Write compact archive summaries for approved work |
+| Learning | retrospective-writer | Capture a reusable failure lesson and decide whether it should become a skill or rule |
+| Context | context-gatherer | Map project state and archive-ready history |
+| Coordination | project-planner | Split, map, sequence work |
+| Spec | system-analyst | Create compact context bundle and contracts |
+| Build | developer, frontend-specialist, backend-specialist, devops-engineer | Implement approved spec |
+| Quality | test-engineer, security-auditor, performance-optimizer, debugger, pr-reviewer | Verify, review, harden |
+
 ## Command Map
 
 | Command | Entry | Exit |
 |---------|-------|------|
-| brainstorm | @feature-lead receives the request. | One recommended path is clear. |
-| create | @feature-lead receives the feature request. | Implementation matches the spec. |
-| debug | @feature-lead scopes the bug and the impact. | The original failure no longer reproduces. |
-| plan | @feature-lead receives the request. | The planning bundle is short and complete. |
-| review | @feature-lead hands the change to @pr-reviewer. | Either APPROVED or CHANGES REQUESTED is clear. |
-| status | @feature-lead asks for the current project state. | The current health is easy to understand. |
-| test | @feature-lead defines the test scope. | The important paths are covered. |
-
-## Gate Rules
-
-- Do not hand off to build until the spec bundle is clear.
-- Do not hand off to review until implementation is complete.
-- Do not ship until the review gate is clean.
-- Loop back to the owning agent when a gate fails.
-
-## Decision Rule
-
-- Prefer defaults when the tradeoff is low risk.
-- Escalate to the user only when scope, security, or architecture changes materially.
-- Keep all context compact enough for a subagent to finish without asking again.
+| archive | @archiver closes approved work | Archive path and saved summary are explicit |
+| brainstorm | @feature-lead receives request or ambiguity returns | One recommended path is clear |
+| check-progress | @feature-lead needs a git-aware status read | Current state and next step are explicit |
+| create | @feature-lead receives feature request | Implementation matches spec |
+| plan | @feature-lead receives request or scope drift | Planning bundle is short and complete |
+| review | @feature-lead hands change to @pr-reviewer at any meaningful checkpoint | APPROVED or CHANGES REQUESTED |
+| reframe | @feature-lead detects a framing mismatch | Better direction and next step are explicit |
+| rubber-duck | @feature-lead needs to reason before changing code | Assumptions and next check are explicit |
+| status | @feature-lead asks for project state | Current health is easy to understand |
+| test | @feature-lead defines test scope | Important paths are covered |
+
+## Gate Rules
+- Do not hand off to build until spec bundle is clear.
+- Do not hand off to review until implementation is complete.
+- Do not ship until review gate is clean.
+- Do not archive until repo delta is reconciled.
+- Loop back to owning agent when a gate fails.
+
+## Decision Rules
+- Prefer defaults when tradeoff is low risk AND business intent is clear.
+- Escalate to user when scope, security, or architecture changes materially.
+- Keep context compact enough for a subagent to finish without asking again.
+- Pass intent in prompts and retrieve documents through tools.
+
+## Clarification Rules
+- **Iterate until clear**: Keep asking until scope, intent, and business value are unambiguous.
+- **No hallucination**: If you don't know, ask. Never assume user intent.
+- **Default + trade-offs**: If user has no idea, propose a default path with trade-offs. Let them choose.
+- **Business before technical**: Capture who, what value, and success criteria before any technical planning.
+- **State assumptions**: Flag what you inferred and what is unverified.
+- **Compact but complete**: Keep context bundle output compact, but never skip user requirements.