feat: improve agent config

.agents/plugins/marketplace.json

@@ -15,7 +15,7 @@
     {
       "name": "flow",
       "description": "Unified toolkit for Context-Driven Development with spec-first planning, TDD workflow, and Beads integration",
-      "version": "0.20.0",
+      "version": "0.20.1",
       "source": { "source": "local", "path": "./plugins/flow" },
       "policy": { "installation": "AVAILABLE" },
       "category": "Development",

.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
     {
       "name": "flow",
       "description": "Unified toolkit for Context-Driven Development with spec-first planning, TDD workflow, and Beads integration",
-      "version": "0.20.0",
+      "version": "0.20.1",
       "source": "./",
       "author": {
         "name": "cofin"

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "flow",
   "description": "Unified toolkit for Context-Driven Development with spec-first planning, TDD workflow, and Beads integration",
-  "version": "0.20.0",
+  "version": "0.20.1",
   "author": {
     "name": "cofin"
   },
@@ -11,6 +11,7 @@
   "keywords": ["flow", "context-driven-development", "beads", "tdd", "ai-agent", "workflow", "spec-first", "skills", "slash-commands", "subagents"],
   "skills": ["./skills/"],
   "commands": ["./commands/"],
+  "agents": ["./agents/"],
   "hooks": "./hooks/hooks-claude.json",
   "userConfig": {
     "useBeads": {

.codex-plugin/plugin.json

@@ -0,0 +1,23 @@
+{
+  "name": "flow",
+  "version": "0.20.1",
+  "description": "Unified toolkit for Context-Driven Development with spec-first planning, TDD workflow, and Beads integration",
+  "author": { "name": "cofin" },
+  "homepage": "https://github.com/cofin/flow",
+  "repository": "https://github.com/cofin/flow",
+  "license": "MIT",
+  "keywords": ["flow", "context-driven-development", "beads", "tdd", "ai-agent", "workflow", "spec-first", "skills"],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Flow",
+    "shortDescription": "Context-driven planning, TDD implementation, and Beads-backed memory",
+    "category": "Development",
+    "capabilities": ["Read", "Write"],
+    "defaultPrompt": [
+      "Use the Flow router and flow-setup to set up this project",
+      "Use the Flow router and flow-planning to create a PRD for user authentication",
+      "Use the Flow router and flow-planning to refine this spec into implementation-ready tasks",
+      "Use the Flow router and flow-execution to implement the current flow with TDD and verification"
+    ]
+  }
+}

.codex/INSTALL.md

@@ -5,7 +5,7 @@ Flow ships as a native Codex plugin via marketplace.
 ## Prerequisites
 
 - Codex CLI 0.117.0+ (with marketplace support; verify with `codex --version`)
-- [Beads CLI](https://github.com/steveyegge/beads)
+- [Beads CLI](https://github.com/gastownhall/beads)
 
 ## Install
 
@@ -39,6 +39,8 @@ Use Flow to implement the current flow with TDD
 
 The Flow skill responds to all `/flow:*` intents (`setup`, `prd`, `plan`, `implement`, `sync`, `status`, `refresh`, `research`, `docs`, etc.).
 
+Repo-local subagents live in `.codex/agents/*.toml`. They are pure TOML, inherit tools from the active Codex session, and do not define a per-agent `tools` allowlist.
+
 ## Recommended Codex settings
 
 In `~/.codex/config.toml`, set plan-mode reasoning effort high (Codex has no plugin-author hook for an artifact-directory equivalent to Gemini's `plan.directory`):

.codex/agents/code-reviewer.toml

@@ -0,0 +1,8 @@
+name = "code-reviewer"
+description = "Review Flow specs, plans, and implementation changes for correctness, risk, and missing verification."
+nickname_candidates = ["code reviewer", "reviewer"]
+developer_instructions = """
+Review like an owner. Prioritize correctness, security, behavior regressions, host integration schema mistakes, missing tests, and missing verification evidence.
+
+Lead with concrete findings ordered by severity. Include file references and explain the failure mode. If there are no findings, say so and call out remaining test gaps or residual risk.
+"""

.codex/agents/executor.toml

@@ -0,0 +1,8 @@
+name = "executor"
+description = "Execute Flow implementation tasks with TDD, Beads notes, verification, and sync discipline."
+nickname_candidates = ["executor", "flow executor"]
+developer_instructions = """
+Execute Flow implementation work from the current spec or Beads task.
+
+Use Beads as the source of truth. Record investigation findings with bd note, follow Red-Green-Refactor, run the canonical verification commands, and never claim completion without fresh evidence.
+"""

.codex/agents/plan-generator.toml

@@ -0,0 +1,8 @@
+name = "plan-generator"
+description = "Generate zero-ambiguity Flow specs and implementation worksheets after codebase analysis."
+nickname_candidates = ["planner", "plan generator"]
+developer_instructions = """
+Create Flow planning worksheets that a low-context implementer can execute correctly on the first pass.
+
+Read the relevant code first, identify exact files and commands, write concrete TDD tasks, and route unclear requirements back into refinement instead of hand-waving.
+"""

.codex/agents/prd-orchestrator.toml

@@ -0,0 +1,8 @@
+name = "prd-orchestrator"
+description = "Analyze broad goals and produce Flow PRD roadmaps with implementation-ready child flows."
+nickname_candidates = ["orchestrator", "prd orchestrator"]
+developer_instructions = """
+Turn broad goals into Flow PRD roadmaps.
+
+Complete research up front, split work into coherent child flows, preserve decisions in Beads notes, and validate the roadmap with code-reviewer before presenting it as ready.
+"""

.cursor/rules/flow.mdc

@@ -0,0 +1,10 @@
+---
+description: Use Flow for context-driven development workflows in repositories with .agents context.
+alwaysApply: true
+---
+
+When a repository has `.agents/`, use the Flow workflow for planning, implementation, sync, status, review, finish, archive, and Beads-backed task memory.
+
+After the `flow` router skill triggers, load the matching lifecycle skill: `flow-setup`, `flow-planning`, `flow-execution`, `flow-sync-status`, or `flow-completion`.
+
+Prefer the installed Flow skills and the repository `AGENTS.md` instructions. Do not rely on a repository `.cursor-plugin/plugin.json`; Cursor consumes rules and project instructions from its supported customization surfaces.

.github/agents/code-reviewer.agent.md

@@ -0,0 +1,6 @@
+---
+name: code-reviewer
+description: Review Flow specs, plans, and implementation changes for correctness, risk, and missing verification.
+---
+
+Review Flow work for correctness, host integration schema mistakes, missing tests, and missing verification evidence. Lead with concrete findings.

.github/agents/executor.agent.md

@@ -0,0 +1,6 @@
+---
+name: executor
+description: Execute Flow implementation tasks with TDD, Beads notes, verification, and sync discipline.
+---
+
+Execute Flow implementation tasks from the active spec or Beads task. Preserve context in Beads notes, follow TDD, and verify before completion claims.

.github/agents/plan-generator.agent.md

@@ -0,0 +1,6 @@
+---
+name: plan-generator
+description: Generate zero-ambiguity Flow specs and implementation worksheets after codebase analysis.
+---
+
+Generate Flow specs and implementation worksheets with exact file targets, TDD steps, and validation commands.

.github/agents/prd-orchestrator.agent.md

@@ -0,0 +1,6 @@
+---
+name: prd-orchestrator
+description: Analyze broad goals and produce Flow PRD roadmaps with implementation-ready child flows.
+---
+
+Turn broad goals into Flow PRD roadmaps. Complete research before planning child flows and validate the roadmap before presenting it.

.github/workflows/check.yml

@@ -31,7 +31,7 @@ jobs:
 
       - name: Install dependencies
         run: |
-          uv sync --dev
+          uv sync --extra dev
 
       - name: Set up Node.js
         uses: actions/setup-node@v4

.github/workflows/release.yml

@@ -25,7 +25,7 @@ jobs:
           enable-cache: true
 
       - name: Validate shipped manifests
-        run: uv run tools/validate-skills.py
+        run: uv run --extra dev tools/validate-skills.py
 
       - name: Build package
         run: make build

.opencode/INSTALL.md

@@ -36,14 +36,14 @@ Verify by asking: `What is your Flow configuration?`
 
 ## Migrating from Legacy Install
 
-If you previously installed Flow with manual agent/command files, remove them:
+If you previously installed Flow with older single-agent command files, remove them:
 
 ```bash
 rm -f ~/.config/opencode/agents/flow.md
 rm -f ~/.config/opencode/commands/flow-*.md
 ```
 
-The plugin handles everything — no separate agent or command files needed.
+The plugin handles context injection. Flow's repo-local `.opencode/agents/*.md` files provide optional native subagents for hosts that read project agent files.
 
 ## Updating
 

.opencode/agents/code-reviewer.md

@@ -0,0 +1,13 @@
+---
+name: code-reviewer
+description: Review Flow specs, plans, and implementation changes for correctness, risk, and missing verification.
+mode: subagent
+tools:
+  read: true
+  grep: true
+  glob: true
+  bash: true
+  webFetch: true
+---
+
+Review Flow work for behavioral bugs, invalid host schemas, stale setup commands, missing tests, and missing verification evidence. Lead with findings ordered by severity.

.opencode/agents/executor.md

@@ -0,0 +1,15 @@
+---
+name: executor
+description: Execute Flow implementation tasks with TDD, Beads notes, verification, and sync discipline.
+mode: subagent
+tools:
+  read: true
+  grep: true
+  glob: true
+  bash: true
+  edit: true
+  write: true
+  webFetch: true
+---
+
+Execute the current Flow task with Beads notes, Red-Green-Refactor, and fresh verification before completion claims.

.opencode/agents/plan-generator.md

@@ -0,0 +1,15 @@
+---
+name: plan-generator
+description: Generate zero-ambiguity Flow specs and implementation worksheets after codebase analysis.
+mode: subagent
+tools:
+  read: true
+  grep: true
+  glob: true
+  bash: true
+  edit: true
+  write: true
+  webFetch: true
+---
+
+Create implementation-ready Flow specs with exact file targets, task order, test commands, and acceptance checks.

.opencode/agents/prd-orchestrator.md

@@ -0,0 +1,15 @@
+---
+name: prd-orchestrator
+description: Analyze broad goals and produce Flow PRD roadmaps with implementation-ready child flows.
+mode: subagent
+tools:
+  read: true
+  grep: true
+  glob: true
+  bash: true
+  edit: true
+  write: true
+  webFetch: true
+---
+
+Analyze broad Flow goals, complete research up front, and produce PRD roadmaps split into implementation-ready flows.

.opencode/plugins/flow.js

@@ -56,10 +56,12 @@ function buildSessionContext() {
     '- When user says "implement", "plan", "spec", "prd", "sync", "status": immediately invoke the matching Flow workflow rather than staying in generic chat mode',
     '- When editing files in .agents/specs/: invoke flow skill for context',
     '- When user mentions "beads", "bd", or backend migration: invoke flow skill',
+    '- Route lifecycle detail through flow-setup, flow-planning, flow-execution, flow-sync-status, or flow-completion after the flow router skill triggers',
     '- When a spec or PRD exists but task detail is coarse: invoke flow-refine before implementation or subagent dispatch',
     '- Do not finish PRD or planning work while obvious research gaps remain',
     '',
     'Key commands: /flow:setup, /flow:prd, /flow:plan, /flow:implement, /flow:sync, /flow:status, /flow:refresh',
+    'Lifecycle skills: flow-setup, flow-planning, flow-execution, flow-sync-status, flow-completion.',
     '',
     'All spec/design docs go in .agents/specs/ (not docs/superpowers/specs/).',
     'Before dispatching subagents, preserve context with the relevant spec/PRD, patterns, knowledge chapters, learnings, affected files, and verification requirements.',