opencode-agile-agent 1.0.4 → 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,37 +61,58 @@ 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
-- 25 agents
-- 14 skills
-- 7 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`, `review`, `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.
-- The compact planning bundle is proposal.md, goal.md, spec.md, task.md, and important.md.
+- `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 `proposal.md`, `goal.md`, `spec.md`, `task.md`, and `important.md`.
+- `@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.
 - Use `node bin/sync-templates.js` after editing `.opencode`.
+- `AGENTS.md` is generated per installed project and is not stored as a reusable template.
 
 ## Requirements
 - Node.js 16+

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, writeFileSync, readFileSync, 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,18 +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.
-  - Detects the project stack automatically.
-  - Copies .opencode and generates AGENTS.md.
+What it does:
+  - Asks one yes/no question.
+  - Merges .opencode into the current project.
+  - Optionally merges opencode.json into the project root.
 
 Commands:
   --help, -h   Show this help message
@@ -65,234 +65,168 @@ Commands:
   process.exit(0);
 }
 
-function shouldCopyPath(path) {
-  return !path.includes(`${sep}node_modules${sep}`) && !path.endsWith(`${sep}node_modules`);
-}
-
-function detectProjectContext() {
-  const defaults = {
-    projectName: 'My Project',
-    framework: 'Generic',
-    language: 'JavaScript',
-    styling: 'Follow existing styles',
-    stateManagement: 'None / follow existing patterns',
-    testing: 'Follow existing tests',
-  };
-
-  const packageJsonPath = join(projectRoot, 'package.json');
-
-  if (!existsSync(packageJsonPath)) {
-    return defaults;
-  }
-
-  try {
-    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
-    const deps = { ...(packageJson.dependencies ?? {}), ...(packageJson.devDependencies ?? {}) };
-    const has = (name) => Boolean(deps[name]);
-
-    const framework = has('next')
-      ? 'Next.js'
-      : has('nuxt')
-        ? 'Nuxt.js'
-        : has('@angular/core')
-          ? 'Angular'
-          : has('svelte')
-          ? 'Svelte'
-          : has('vue') || has('vue2') || has('vue3')
-              ? 'Vue'
-              : has('react-native') || has('expo')
-                ? 'React Native'
-              : has('react') || has('react-dom')
-                ? 'React'
-                : has('express')
-                  ? 'Express'
-                  : has('fastify')
-                    ? 'Fastify'
-                    : has('nestjs') || has('@nestjs/core')
-                      ? 'NestJS'
-                      : 'Generic';
-
-    const language = has('typescript') || existsSync(join(rootDir, 'tsconfig.json'))
-      ? 'TypeScript'
-      : 'JavaScript';
-
-    const styling = has('tailwindcss')
-      ? 'Tailwind'
-      : has('styled-components')
-        ? 'Styled Components'
-        : has('sass') || has('scss')
-          ? 'SCSS'
-          : has('css-modules')
-            ? 'CSS Modules'
-            : 'Follow existing styles';
-
-    const stateManagement = has('pinia')
-      ? 'Pinia'
-      : has('zustand')
-        ? 'Zustand'
-        : has('redux') || has('@reduxjs/toolkit')
-          ? 'Redux'
-          : has('mobx')
-            ? 'MobX'
-            : 'None / follow existing patterns';
-
-    const testing = has('vitest')
-      ? 'Vitest'
-      : has('jest')
-        ? 'Jest'
-        : has('playwright')
-          ? 'Playwright'
-          : has('cypress')
-            ? 'Cypress'
-            : 'Follow existing tests';
-
-    return {
-      ...defaults,
-      projectName: packageJson.name || defaults.projectName,
-      framework,
-      language,
-      styling,
-      stateManagement,
-      testing,
-    };
-  } catch {
-    return defaults;
-  }
-}
-
-function generateAgentsMd(context) {
-  return `# AGENTS.md - ${context.projectName}
-
-> Instructions for AI agents working on this project.
->
-> How to build lives here; what to build comes from feature specs.
-
----
-
-## Project Stack
-
-- Framework: ${context.framework}
-- Language: ${context.language}
-- State Management: ${context.stateManagement}
-- Styling: ${context.styling}
-- Testing: ${context.testing}
-
----
-
-## Core Documentation
-
-Review these before making architectural or styling decisions:
-
-| Document | Purpose | Location |
-|----------|---------|----------|
-| OpenCode README | Kit overview and flow | .opencode/README.md |
-| OpenCode Architecture | Agent lifecycle and gates | .opencode/ARCHITECTURE.md |
-| Agent prompts | Role-specific behavior | .opencode/agents/*.md |
-| Commands | Custom slash commands | .opencode/commands/*.md |
-| Rules | Shared coding standards | .opencode/rules/*.md |
-
----
-
-## OpenCode Delivery Model
+function shouldCopyPath(path) {
+  return !path.includes(`${sep}node_modules${sep}`) && !path.endsWith(`${sep}node_modules`);
+}
 
-- Primary agent: @feature-lead
-- First call: @context-gatherer maps the current project state before planning or proof.
-- Other agents are subagents and are called with @ awareness.
-- Security-sensitive work: @security-auditor first, then @penetration-tester for redteam validation when needed.
+function isAppendableTextFile(path) {
+  return path.endsWith('.md') || path.endsWith('.txt') || path.endsWith('.gitignore');
+}
 
-## Compact Context Bundle
+function isJsonFile(path) {
+  return extname(path) === '.json';
+}
 
-- proposal.md: why, value, scope
-- goal.md: target outcome, constraints, default choice
-- spec.md: contract, data flow, edge cases, risks
-- task.md: ordered checklist, dependencies, owners
-- important.md: facts, blockers, links, decisions
+function appendUniqueContent(targetPath, sourceContent) {
+  const targetContent = readFileSync(targetPath, 'utf8');
+  const trimmedSource = sourceContent.trim();
+  if (!trimmedSource || targetContent.includes(trimmedSource)) {
+    return 'skipped';
+  }
 
-## Archive
+  const nextContent = `${targetContent.trimEnd()}\n\n${trimmedSource}\n`;
+  writeFileSync(targetPath, nextContent);
+  return 'appended';
+}
 
-- Archive completed bundles in .opencode/archive/<feature-slug>/.
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
 
-## Decision Style
-
-- Default first: choose a safe default when the downside is small.
-- Ask only when scope, security, or architecture changes materially.
-- Keep handoffs compact and explicit.
-
----
-
-## Code Conventions
-
-### File Naming
-
-| Type | Pattern | Example |
-|------|---------|---------|
-| Components | PascalCase.tsx | UserCard.tsx |
-| Pages | PascalCasePage.tsx | LoginPage.tsx |
-| Stores | camelCase.store.ts | auth.store.ts |
-| Hooks/Composables | useCamelCase.ts | useAuth.ts |
-| Types | camelCase.types.ts | user.types.ts |
-| Utils | camelCase.utils.ts | date.utils.ts |
-| API | camelCase.api.ts | auth.api.ts |
-| Tests | *.test.ts or *.spec.ts | auth.test.ts |
-
-### Code Style
-
-- Indentation: 2 spaces
-- Quotes: single
-- Semicolons: required
-- Line Width: 100
-- Trailing Commas: es5
-
----
-
-## Project-Specific Rules
-
-- Keep changes aligned to the compact spec bundle.
-- Prefer defaults when a tradeoff is low risk.
-- Surface options only when the decision changes scope, security, or architecture.
-
----
-
-## Architecture Patterns
-
-### State Management
-
-- Describe where state lives.
-- Keep async work inside the owning module.
-- Make loading and error states explicit.
-
-### API Layer
-
-- Keep request and response shapes explicit.
-- Normalize errors near the boundary.
-- Version breaking contract changes.
-
-### Component Structure
-
-- Keep presentation and side effects separated.
-- Put validation near the boundary.
-- Make loading and error states visible.
-
----
-
-## Testing Standards
-
-- Unit tests: pure logic and helper functions.
-- Integration tests: API calls and service boundaries.
-- E2E tests: critical user journeys.
-- Quality gate: verify behavior before release.
-
----
-
-## Quick Reference
-
-- Validate templates: node bin/validate-templates.js
-- Sync templates: node bin/sync-templates.js
-- Entry point: @feature-lead
-`;
-}
-
-async function install() {
+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);
   log.title('OpenCode Agile Agent Installer');
 
@@ -303,9 +237,6 @@ async function install() {
     return;
   }
 
-  const context = detectProjectContext();
-  log.info(`Detected project: ${context.projectName} (${context.framework}, ${context.language})`);
-
   const source = join(templatesDir, '.opencode');
   const target = join(projectRoot, '.opencode');
 
@@ -316,23 +247,18 @@ 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,
-  });
-  writeFileSync(join(projectRoot, 'AGENTS.md'), generateAgentsMd(context), 'utf-8');
-
-  log.success('Installed .opencode and generated AGENTS.md.');
-  log.title('Done');
-  console.log('Start with @feature-lead and review .opencode/README.md for the flow.');
+  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 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.');
 
   rl.close();
 }

package/bin/sync-templates.js

@@ -9,8 +9,6 @@ const __dirname = dirname(__filename);
 const rootDir = join(__dirname, '..');
 const sourceOpencode = join(rootDir, '.opencode');
 const targetTemplates = join(rootDir, 'templates');
-const sourceTemplate = join(rootDir, 'AGENTS.template.md');
-const targetTemplate = join(targetTemplates, 'AGENTS.template.md');
 
 function skipNodeModules(path) {
   return !path.includes(`${sep}node_modules${sep}`) && !path.endsWith(`${sep}node_modules`);
@@ -38,8 +36,4 @@ cpSync(sourceOpencode, join(targetTemplates, '.opencode'), {
   filter: skipNodeModules,
 });
 
-if (existsSync(sourceTemplate)) {
-  cpSync(sourceTemplate, targetTemplate, { force: true });
-}
-
-console.log('Synced .opencode and AGENTS.template.md to templates/');
+console.log('Synced .opencode to templates/');