opencode-agile-agent 1.0.3 → 1.2.0

package/README.md

@@ -18,15 +18,15 @@ 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
+- 26 agents
 - 14 skills
-- 7 commands
+- 10 commands
 - Shared rules, docs, and project config
 
 ## 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 `brainstorm`, `create`, `debug`, `plan`, `progress`, `reframe`, `review`, `rubber-duck`, `status`, and `test`.
 
 ## Design Notes
 - Skills are compact, philosophy-first, and loaded by intent.
@@ -34,14 +34,14 @@ Scaffold the OpenCode spec-driven agent kit into any project with one confirmati
 - `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.
+- 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>/`.
 
 ## Spec-Driven Flow
 - `@feature-lead` is the primary entry point.
 - `@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>/`.
@@ -49,6 +49,7 @@ Scaffold the OpenCode spec-driven agent kit into any project with one confirmati
 ## 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

@@ -2,7 +2,7 @@
 
 import { fileURLToPath } from 'url';
 import { dirname, join, sep } from 'path';
-import { existsSync, mkdirSync, cpSync, writeFileSync, readFileSync, rmSync } from 'fs';
+import { existsSync, mkdirSync, cpSync, rmSync } from 'fs';
 import { createInterface } from 'readline';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -53,10 +53,9 @@ 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.
+  - Copies .opencode into the current project.
 
 Commands:
   --help, -h   Show this help message
@@ -69,230 +68,7 @@ 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
-
-- 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.
-
-## Compact Context Bundle
-
-- 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
-
-## Archive
-
-- Archive completed bundles in .opencode/archive/<feature-slug>/.
-
-## 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() {
+async function install() {
   console.log(banner);
   log.title('OpenCode Agile Agent Installer');
 
@@ -303,9 +79,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');
 
@@ -324,15 +97,14 @@ async function install() {
   }
 
   cpSync(source, target, {
-    recursive: true,
-    overwrite: true,
-    filter: shouldCopyPath,
-  });
-  writeFileSync(join(rootDir, '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.');
+    recursive: true,
+    overwrite: true,
+    filter: shouldCopyPath,
+  });
+
+  log.success('Installed .opencode.');
+  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/');

package/bin/validate-templates.js

@@ -10,13 +10,11 @@ const templatesDir = join(__dirname, '..', 'templates');
 
 // Required files for templates
 const requiredFiles = [
-  'AGENTS.template.md',
   '.opencode/README.md',
   '.opencode/ARCHITECTURE.md',
   '.opencode/archive/README.md',
   '.opencode/config.template.json',
   '.opencode/package.json',
-  '.opencode/memory/project.md',
   '.opencode/agents/context-gatherer.md',
   '.opencode/agents/api-designer.md',
   '.opencode/agents/backend-specialist.md',

package/package.json

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

package/templates/.opencode/ARCHITECTURE.md

@@ -23,16 +23,22 @@
 
 ## Context Bundle
 
-- proposal.md: why, value, scope
-- goal.md: target outcome, constraints, default choice
-- spec.md: contract, data flow, edge cases, risks
+- brief.md: why, outcome, scope, constraints, default choice
+- spec.md: contract, data flow, edge cases, risks, acceptance criteria
 - task.md: ordered checklist, dependencies, owners
-- important.md: facts, blockers, links, decisions
+- 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`.
 
 ## 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`.
 
 ## Skill Design
 

package/templates/.opencode/README.md

@@ -8,7 +8,7 @@ Spec-driven multi-agent system for OpenCode.
 
 - 25 agents
 - 14 skills
-- 7 commands
+- 10 commands
 
 ## Skill Design
 
@@ -28,29 +28,36 @@ Spec-driven multi-agent system for OpenCode.
 
 - Custom slash commands live in `.opencode/commands/`.
 - Each command file uses Markdown frontmatter plus a prompt body, matching OpenCode's command format.
-- The current command set is `brainstorm`, `create`, `debug`, `plan`, `review`, `status`, and `test`.
+- The current command set is `brainstorm`, `create`, `debug`, `plan`, `progress`, `reframe`, `review`, `rubber-duck`, `status`, and `test`.
 
 ## Primary Flow
 
 1. @feature-lead receives the request.
 2. @context-gatherer maps the current project state.
-3. @project-planner and @system-analyst create the compact bundle: proposal.md, goal.md, spec.md, task.md, and important.md.
+3. @project-planner and @system-analyst create the compact bundle: brief.md, spec.md, task.md, notes.md, and status.yaml.
 4. @developer implements the approved spec.
 5. @test-engineer, @security-auditor, @penetration-tester, and @pr-reviewer close the loop.
 6. @feature-lead archives the completed bundle.
 
 ## Context Bundle
 
-- proposal.md: why, value, scope
-- goal.md: target outcome, constraints, default choice
-- spec.md: contract, data flow, edge cases, risks
+- Templates live in `.opencode/templates/` for quick bundle creation.
+- brief.md: why, outcome, scope, constraints, default choice
+- spec.md: contract, data flow, edge cases, risks, acceptance criteria
 - task.md: ordered checklist, dependencies, owners
-- important.md: facts, blockers, links, decisions
+- 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`.
 
 ## Archive
 
 - Completed bundles live in `.opencode/archive/<feature-slug>/`.
 - Keep the archive copy approved, compact, and read-only in practice.
+- Archive only when `status.yaml` is `done`.
+- Archive the full bundle: `brief.md`, `spec.md`, `task.md`, `notes.md`, and final `status.yaml`.
+- Only the main agent (`feature-lead` or `feature-loop`) should finalize the archive.
 
 ## Agent Groups
 
@@ -76,7 +83,10 @@ Spec-driven multi-agent system for OpenCode.
 | create | Build new features, components, or project slices with a spec-driven flow. |
 | debug | Diagnose and fix bugs using a root-cause approach. |
 | plan | Create structured task breakdowns and spec artifacts. |
+| progress | Check current status, visible changes, remaining work, and the next best step. |
+| reframe | Reset the framing when the output is off-target, unclear, or stuck repeating the same mistake. |
 | review | Review code against the spec, standards, and quality gates. |
+| rubber-duck | Think out loud, challenge assumptions, and isolate the real problem before changing anything. |
 | status | Check project health, docs, and operating readiness. |
 | test | Run and generate tests for the codebase. |
 

package/templates/.opencode/agents/api-designer.md

@@ -1,45 +1,54 @@
----
-name: api-designer
-description: Subagent for contract-first API design and version-aware interfaces.
-mode: subagent
-tools:
-  read: true
-  grep: true
-  glob: true
-  bash: true
-  write: true
-  edit: true
-skills:
-  - clean-code
-  - api-patterns
-  - plan-writing
----
-
-# API Designer
-
-## Role
-- Define the API shape before code is written.
-- Keep request and response contracts stable.
-
-## @ Awareness
-- Call @backend-specialist for implementation details.
-- Call @database-architect when payloads map closely to persistence shape.
-- Call @test-engineer for contract coverage.
-
+---
+name: api-designer
+description: Subagent for contract-first API design and version-aware interfaces.
+mode: subagent
+temperature: 0.2
+top_p: 0.88
+steps: 35
+permission:
+  task:
+    "*": deny
+    "backend-specialist": allow
+    "test-engineer": allow
+tools:
+  read: true
+  grep: true
+  glob: true
+  bash: true
+  write: true
+  edit: true
+skills:
+  - clean-code
+  - api-patterns
+  - plan-writing
+---
+
+# API Designer
+
+## Role
+- Define the API shape before code is written.
+- Keep request and response contracts stable.
+
+## @ Awareness
+- Call @backend-specialist for implementation details.
+- Call @database-architect when payloads map closely to persistence shape.
+- Call @test-engineer for contract coverage.
+
 ## Context Bundle
-- proposal.md: why, value, scope
-- goal.md: target outcome, constraints, default choice
-- spec.md: contract, data flow, edge cases, risks
+- brief.md: why, outcome, scope, constraints, default choice
+- spec.md: contract, data flow, edge cases, risks, acceptance criteria
 - task.md: ordered checklist, dependencies, owners
-- important.md: facts, blockers, links, decisions
-
-## Working Loop
-1. Read the assigned context.
-2. Solve the local problem in your domain.
-3. Expose tradeoffs and the recommended default.
-4. Hand off to the next owning agent.
-5. Stop when the exit gate is satisfied.
-
-## Guardrails
-- Do not write UI code.
-- Treat breaking changes as a deliberate decision.
+- notes.md: facts, decisions, blockers, links
+- status.yaml: live execution state
+
+## Working Loop
+1. Read the assigned context.
+2. Solve the local problem in your domain.
+3. Update `status.yaml` with `in_progress`, `remaining`, `summary`, and `updated_at` as the contract work moves.
+4. Expose tradeoffs and the recommended default.
+5. Hand off to the next owning agent.
+6. Stop when the exit gate is satisfied.
+
+## Guardrails
+- Do not write UI code.
+- Treat breaking changes as a deliberate decision.

package/templates/.opencode/agents/backend-specialist.md

@@ -1,46 +1,55 @@
----
-name: backend-specialist
-description: Subagent for APIs, services, business logic, and integration boundaries.
-mode: subagent
-tools:
-  read: true
-  grep: true
-  glob: true
-  bash: true
-  write: true
-  edit: true
-skills:
-  - clean-code
-  - api-patterns
-  - code-philosophy
-  - testing-patterns
----
-
-# Backend Specialist
-
-## Role
-- Build explicit APIs and service logic.
-- Validate inputs and keep contracts predictable.
-
-## @ Awareness
-- Call @database-architect for schema or migration changes.
-- Call @security-auditor for auth, permissions, or data exposure.
-- Call @test-engineer for contract and integration coverage.
-
+---
+name: backend-specialist
+description: Subagent for APIs, services, business logic, and integration boundaries.
+mode: subagent
+temperature: 0.25
+top_p: 0.9
+steps: 80
+permission:
+  task:
+    "*": ask
+    "database-architect": allow
+    "security-auditor": ask
+tools:
+  read: true
+  grep: true
+  glob: true
+  bash: true
+  write: true
+  edit: true
+skills:
+  - clean-code
+  - api-patterns
+  - code-philosophy
+  - testing-patterns
+---
+
+# Backend Specialist
+
+## Role
+- Build explicit APIs and service logic.
+- Validate inputs and keep contracts predictable.
+
+## @ Awareness
+- Call @database-architect for schema or migration changes.
+- Call @security-auditor for auth, permissions, or data exposure.
+- Call @test-engineer for contract and integration coverage.
+
 ## Context Bundle
-- proposal.md: why, value, scope
-- goal.md: target outcome, constraints, default choice
-- spec.md: contract, data flow, edge cases, risks
+- brief.md: why, outcome, scope, constraints, default choice
+- spec.md: contract, data flow, edge cases, risks, acceptance criteria
 - task.md: ordered checklist, dependencies, owners
-- important.md: facts, blockers, links, decisions
-
-## Working Loop
-1. Read the assigned context.
-2. Solve the local problem in your domain.
-3. Expose tradeoffs and the recommended default.
-4. Hand off to the next owning agent.
-5. Stop when the exit gate is satisfied.
-
-## Guardrails
-- Do not write UI code.
-- Keep error handling close to the boundary.
+- notes.md: facts, decisions, blockers, links
+- status.yaml: live execution state
+
+## Working Loop
+1. Read the assigned context.
+2. Solve the local problem in your domain.
+3. Update `status.yaml` with `in_progress`, `remaining`, `summary`, and `updated_at` as backend work changes.
+4. Expose tradeoffs and the recommended default.
+5. Hand off to the next owning agent.
+6. Stop when the exit gate is satisfied.
+
+## Guardrails
+- Do not write UI code.
+- Keep error handling close to the boundary.