agentxchain 0.8.8 → 2.2.0

package/README.md

@@ -1,6 +1,18 @@
 # agentxchain
 
-CLI for multi-agent coordination in your IDE. Define a team of AI agents, let them take turns building your project — each in its own IDE window.
+CLI for governed multi-agent software delivery.
+
+The canonical mode is governed delivery: orchestrator-owned state, structured turn results, phase gates, mandatory challenge, and explicit human approvals where required.
+
+Legacy IDE-window coordination is still shipped as a compatibility mode for teams that want lock-based handoff in Cursor, VS Code, or Claude Code.
+
+## Docs
+
+- [Quickstart](https://agentxchain.dev/docs/quickstart/)
+- [CLI reference](https://agentxchain.dev/docs/cli/)
+- [Adapter reference](https://agentxchain.dev/docs/adapters/)
+- [Protocol spec (v6)](https://agentxchain.dev/docs/protocol/)
+- [Why governed multi-agent delivery matters](https://agentxchain.dev/why/)
 
 ## Install
 
@@ -11,192 +23,180 @@ npm install -g agentxchain
 Or run without installing:
 
 ```bash
-npx agentxchain init
+npx agentxchain init --governed -y
 ```
 
-## Quick start
+## Quick Start
 
-### Happy path: net-new project
+### Governed workflow
 
 ```bash
-npx agentxchain init
-cd my-agentxchain-project   # default with init -y, or your chosen folder name
-agentxchain kickoff
+npx agentxchain init --governed -y
+cd my-agentxchain-project
+git init
+git add -A
+git commit -m "initial governed scaffold"
+agentxchain status
+agentxchain step --role pm
 ```
 
-### Happy path: existing project
-
-Run these commands from inside your existing project folder:
+If you want template-specific planning artifacts from day one:
 
 ```bash
-agentxchain doctor
-agentxchain generate
-agentxchain kickoff
+npx agentxchain init --governed --template api-service -y
 ```
 
-Each agent runs in its own Cursor window for a single turn at a time. The referee loop (`watch` / `supervise --autonudge`) determines the next agent and wakes that specific session.
+Built-in governed templates:
 
-Agents are now required to maintain `TALK.md` as the human-readable handoff log each turn.
+- `generic`: baseline governed scaffold
+- `api-service`: API contract, operational readiness, error budget
+- `cli-tool`: command surface, platform support, distribution checklist
+- `web-app`: user flows, UI acceptance, browser support
 
-## Commands
-
-| Command | What it does |
-|---------|-------------|
-| `init` | Create project folder with agents, protocol files, and templates |
-| `kickoff` | Guided PM-first flow: PM kickoff, validate, launch remaining, release |
-| `start` | Open a Cursor window per agent + copy prompts to clipboard |
-| `supervise` | Run watcher and optional AppleScript auto-nudge together |
-| `generate` | Regenerate agent files from `agentxchain.json` |
-| `validate` | Enforce PM signoff + waves/phases + turn artifact schema |
-| `status` | Show lock holder, phase, turn number, agents |
-| `doctor` | Validate local setup (tools, trigger flow, accessibility checks) |
-| `claim` | Human takes control (agents stop claiming) |
-| `release` | Hand lock back to agents |
-| `stop` | Stop watch daemon, end Claude Code sessions; Cursor/VS Code chats close manually |
-| `branch` | Show/set Cursor branch override for launches |
-| `watch` | Referee loop: validates turns, writes next trigger, and force-releases stale locks |
-| `config` | View/edit config, add/remove agents, change rules |
-| `rebind` | Rebuild Cursor workspace/prompt bindings for agents |
-| `update` | Self-update CLI from npm |
-
-### Full command list
+`step` writes a turn-scoped bundle under `.agentxchain/dispatch/turns/<turn_id>/` and expects a staged result at `.agentxchain/staging/<turn_id>/turn-result.json`. Typical continuation:
 
 ```bash
-agentxchain init
-agentxchain status
-agentxchain start
-agentxchain kickoff
-agentxchain stop
-agentxchain branch
-agentxchain config
-agentxchain rebind
-agentxchain generate
-agentxchain watch
-agentxchain supervise
-agentxchain claim
-agentxchain release
-agentxchain update
-agentxchain doctor
-agentxchain validate
+agentxchain validate --mode turn
+agentxchain accept-turn
+agentxchain approve-transition
+agentxchain step --role dev
+agentxchain step --role qa
+agentxchain approve-completion
 ```
 
-### IDE options
+Default governed scaffolding configures QA as `api_proxy` with `ANTHROPIC_API_KEY`. For a provider-free walkthrough, switch the QA runtime to `manual` before the QA step.
+
+### Migrate a legacy project
 
 ```bash
-agentxchain start                   # Cursor (default) — one window per agent
-agentxchain start --ide vscode      # VS Code — uses .agent.md custom agents + hooks
-agentxchain start --ide claude-code # Claude Code — spawns CLI processes
+agentxchain migrate
+agentxchain status
+agentxchain step
 ```
 
-### Additional flags
+## Command Sets
 
-```bash
-agentxchain kickoff                # guided first-run PM-first workflow
-agentxchain kickoff --ide vscode   # guided flow for VS Code mode
-agentxchain kickoff --send         # with Cursor auto-nudge auto-send enabled
-agentxchain kickoff --interval 2   # nudge poll interval override
-agentxchain kickoff --no-autonudge # skip auto-nudge prompt
-
-agentxchain start --agent pm        # launch only one specific agent
-agentxchain start --remaining       # launch all agents except PM (PM-first flow)
-agentxchain start --dry-run         # preview agents without launching
-agentxchain validate --mode kickoff # required before --remaining
-agentxchain validate --mode turn --agent pm
-agentxchain validate --json         # machine-readable validation output
-agentxchain watch --daemon          # run watch in background
-agentxchain supervise --autonudge   # run watch + AppleScript nudge loop
-agentxchain supervise --autonudge --send   # auto-press Enter after paste
-agentxchain supervise --interval 2  # set auto-nudge poll interval
-agentxchain rebind                  # regenerate agent prompt/workspace bindings
-agentxchain rebind --open           # regenerate and reopen all Cursor agent windows
-agentxchain rebind --agent pm       # regenerate one agent binding only
-agentxchain claim --agent pm        # guarded claim as agent turn owner
-agentxchain release --agent pm      # guarded release as agent turn owner
-agentxchain release --force         # force-release non-human holder lock
-agentxchain config --set "rules.strict_next_owner true"  # TALK-only next owner (no cyclic fallback)
-```
+### Governed
 
-## macOS auto-nudge (AppleScript)
+| Command | What it does |
+|---|---|
+| `init --governed [--template <id>]` | Create a governed project, optionally with project-shape-specific planning artifacts |
+| `migrate` | Convert a legacy v3 project to governed format |
+| `status` | Show current run, template, phase, turn, and approval state |
+| `resume` | Initialize or continue a governed run and assign the next turn |
+| `step` | Run one governed turn end to end or resume an active turn |
+| `accept-turn` | Accept the staged governed turn result |
+| `reject-turn` | Reject the staged result, retry, or reassign |
+| `approve-transition` | Approve a pending human-gated phase transition |
+| `approve-completion` | Approve a pending human-gated run completion |
+| `validate` | Validate governed kickoff wiring, a staged turn, or both |
+| `verify protocol` | Run the shipped protocol conformance suite against a target implementation |
+| `dashboard` | Open the read-only governance dashboard in your browser for repo-local runs or multi-repo coordinator initiatives |
+| `plugin install|list|remove` | Install, inspect, or remove governed hook plugins backed by `agentxchain-plugin.json` manifests |
+
+### Shared utilities
 
-**Recommended:** `agentxchain supervise --autonudge` (starts `watch` + auto-nudge together). Requires macOS, `jq`, and Accessibility for Terminal + Cursor.
+| Command | What it does |
+|---|---|
+| `config` | View or edit project configuration |
+| `update` | Update the CLI from npm |
 
-```bash
-agentxchain supervise --autonudge
-agentxchain supervise --autonudge --send   # paste + Enter
-```
+### Legacy v3 compatibility
 
-**Advanced (debugging):** from a checkout of `cli/`, run the script alone while `watch` is already running:
+| Command | What it does |
+|---|---|
+| `init` | Create a legacy project folder |
+| `start` | Launch legacy agents in IDE sessions |
+| `kickoff` | Guided PM-first legacy setup flow |
+| `watch` | Referee loop for legacy lock-based handoff |
+| `supervise` | Run `watch` plus optional macOS auto-nudge |
+| `claim` / `release` | Human override of legacy lock ownership |
+| `rebind` | Rebuild Cursor bindings |
+| `generate` | Regenerate VS Code agent files |
+| `branch` | Manage Cursor branch override for launches |
+| `doctor` | Check local environment and setup |
+| `stop` | Stop watch daemon and local sessions |
+
+## Governed Flow
+
+1. `agentxchain step` initializes or resumes the run if needed.
+2. It assigns the next role for the current phase.
+3. It writes `.agentxchain/dispatch/turns/<turn_id>/`.
+4. The assigned role writes `.agentxchain/staging/<turn_id>/turn-result.json`.
+5. The orchestrator validates and either accepts, rejects, advances phase, pauses for approval, or completes the run.
+
+## Protocol Conformance
+
+AgentXchain ships a conformance kit under `.agentxchain-conformance/`. Use it to prove a runner or fork still implements the governed workflow contract:
 
 ```bash
-bash scripts/run-autonudge.sh --project "/absolute/path/to/your-project" [--send]
-bash scripts/stop-autonudge.sh
+agentxchain verify protocol --tier 3 --target .
 ```
 
-Notes:
-- Requires macOS (`osascript`) and `jq` (`brew install jq`)
-- Grant Accessibility permissions to Terminal and Cursor
-- The script watches `.agentxchain-trigger.json`, which is written by `agentxchain watch`
-- `run-autonudge.sh` now requires watch to be running first
-- The script only nudges when it finds a unique matching agent window (no random fallback)
+Useful flags:
 
-## How it works
+- `--tier 1|2|3`: maximum conformance tier to verify
+- `--surface <name>`: isolate one surface such as `state_machine`, `dispatch_manifest`, or `coordinator`
+- `--format json`: emit a machine-readable report for CI
+- `--target <path>`: point at the root containing `.agentxchain-conformance/capabilities.json`
 
-### Cursor mode (default)
+Important governed files:
 
-1. `agentxchain kickoff` launches PM first for human-product alignment
-2. Each window gets a unique prompt copied to clipboard
-3. Kickoff validates PM signoff and launches remaining agents
-4. Agent prompts are single-turn: claim → work → validate → release → stop
-5. Agents use the latest `Next owner:` in `TALK.md` to pick who goes next (fallback: config order)
-6. Human can `claim` to pause and `release` to resume anytime
+```text
+agentxchain.json
+.agentxchain/state.json
+.agentxchain/history.jsonl
+.agentxchain/decision-ledger.jsonl
+.agentxchain/dispatch/turns/<turn_id>/
+.agentxchain/staging/<turn_id>/turn-result.json
+TALK.md
+.planning/
+```
 
-### VS Code mode
+### Runtime support today
 
-1. `agentxchain init` generates `.github/agents/*.agent.md` (VS Code custom agents) and `.github/hooks/` (lifecycle hooks)
-2. VS Code discovers custom agents in Chat when using **GitHub Copilot** agents (see Microsoft docs)
-3. The `Stop` hook acts as referee — hands off to next agent automatically
+- `manual`: implemented
+- `local_cli`: implemented
+- `api_proxy`: implemented for synchronous review-only turns and stages a provider-backed result during `step`
 
-### Turn ownership
+## Legacy IDE Mode
 
-Agent turns are handoff-driven:
-- Each turn appends a `Next owner:` in `TALK.md` with a valid agent id
-- `watch`/`supervise` dispatches the next trigger from that handoff
-- `claim --agent <id>` enforces that expected owner (with guarded fallback)
+Legacy mode is still useful if you specifically want one IDE session per agent and lock-file coordination.
 
-## Key features
+```bash
+agentxchain start                   # Cursor (default)
+agentxchain start --ide vscode
+agentxchain start --ide claude-code
+agentxchain kickoff
+agentxchain supervise --autonudge
+```
 
-- **One window per agent** — each agent has its own Cursor window and chat session
-- **Referee-driven coordination** — `watch`/`supervise` wakes the next correct agent each turn
-- **Works in Cursor, VS Code, Claude Code** — adapters for each IDE
-- **User-defined teams** — any number of agents, any roles
-- **No API keys or cloud required** — everything runs locally
-- **Human-in-the-loop** — claim/release to intervene anytime
-- **Team templates** — SaaS MVP, Landing Page, Bug Squad, API Builder, Refactor Team
-- **Lock TTL** — `watch` can force-release stale locks as a safety net
+In this mode, agents hand off through `lock.json`, `state.json`, triggers, and `TALK.md`. For new projects, prefer governed mode unless IDE-window choreography is the goal.
 
-## VS Code extension (optional)
+## macOS Auto-Nudge
 
-The VSIX is not committed to the repo. Build/package from `cli/vscode-extension/` (see that folder’s README or `vsce package`), then:
+`supervise --autonudge` is legacy-only and macOS-only.
 
 ```bash
-code --install-extension /path/to/agentxchain-*.vsix
+agentxchain supervise --autonudge
+agentxchain supervise --autonudge --send
 ```
 
-## Publish updates (maintainers)
-
-```bash
-cd cli
-bash scripts/publish-npm.sh              # patch bump + publish
-bash scripts/publish-npm.sh minor        # minor bump + publish
-```
+Requires:
 
-If `NPM_TOKEN` exists in `agentXchain.dev/.env` (project root), the script uses it automatically.
+- `osascript`
+- `jq`
+- Accessibility permissions for Terminal and Cursor
 
 ## Links
 
 - [agentxchain.dev](https://agentxchain.dev)
+- [Quickstart](https://agentxchain.dev/docs/quickstart/)
+- [CLI reference](https://agentxchain.dev/docs/cli/)
+- [Adapter reference](https://agentxchain.dev/docs/adapters/)
+- [Protocol spec (v6)](https://agentxchain.dev/docs/protocol/)
 - [GitHub](https://github.com/shivamtiwari93/agentXchain.dev)
-- [Protocol v3 spec](https://github.com/shivamtiwari93/agentXchain.dev/blob/main/PROTOCOL-v3.md)
+- [Legacy Protocol v3 spec](https://github.com/shivamtiwari93/agentXchain.dev/blob/main/PROTOCOL-v3.md)
 
 ## License
 

package/bin/agentxchain.js

@@ -59,9 +59,33 @@ import { generateCommand } from '../src/commands/generate.js';
 import { doctorCommand } from '../src/commands/doctor.js';
 import { superviseCommand } from '../src/commands/supervise.js';
 import { validateCommand } from '../src/commands/validate.js';
+import { verifyProtocolCommand } from '../src/commands/verify.js';
 import { kickoffCommand } from '../src/commands/kickoff.js';
 import { rebindCommand } from '../src/commands/rebind.js';
 import { branchCommand } from '../src/commands/branch.js';
+import { migrateCommand } from '../src/commands/migrate.js';
+import { resumeCommand } from '../src/commands/resume.js';
+import { acceptTurnCommand } from '../src/commands/accept-turn.js';
+import { rejectTurnCommand } from '../src/commands/reject-turn.js';
+import { stepCommand } from '../src/commands/step.js';
+import { approveTransitionCommand } from '../src/commands/approve-transition.js';
+import { approveCompletionCommand } from '../src/commands/approve-completion.js';
+import { dashboardCommand } from '../src/commands/dashboard.js';
+import {
+  pluginInstallCommand,
+  pluginListCommand,
+  pluginRemoveCommand,
+  pluginUpgradeCommand,
+} from '../src/commands/plugin.js';
+import { templateSetCommand } from '../src/commands/template-set.js';
+import { templateListCommand } from '../src/commands/template-list.js';
+import {
+  multiInitCommand,
+  multiStatusCommand,
+  multiStepCommand,
+  multiApproveGateCommand,
+  multiResyncCommand,
+} from '../src/commands/multi.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
@@ -70,24 +94,27 @@ const program = new Command();
 
 program
   .name('agentxchain')
-  .description('Multi-agent coordination in your IDE')
+  .description('Governed multi-agent software delivery orchestration')
   .version(pkg.version);
 
 program
   .command('init')
   .description('Create a new AgentXchain project folder')
   .option('-y, --yes', 'Skip prompts, use defaults')
+  .option('--governed', 'Create a governed project (orchestrator-owned state)')
+  .option('--template <id>', 'Governed scaffold template: generic, api-service, cli-tool, web-app')
+  .option('--schema-version <version>', 'Schema version (3 for legacy, or use --governed for current)')
   .action(initCommand);
 
 program
   .command('status')
-  .description('Show lock status, phase, and agents')
+  .description('Show current run or lock status')
   .option('-j, --json', 'Output as JSON')
   .action(statusCommand);
 
 program
   .command('start')
-  .description('Launch agents in your IDE')
+  .description('Launch legacy v3 agents in your IDE')
   .option('--ide <ide>', 'Target IDE: cursor, vscode, claude-code', 'cursor')
   .option('--agent <id>', 'Launch a specific agent only')
   .option('--remaining', 'Launch all remaining agents except PM (for PM-first flow)')
@@ -96,7 +123,7 @@ program
 
 program
   .command('kickoff')
-  .description('Guided PM-first first-run workflow')
+  .description('Guided legacy PM-first first-run workflow')
   .option('--ide <ide>', 'Target IDE: cursor, vscode, claude-code', 'cursor')
   .option('--send', 'When using Cursor auto-nudge, auto-send nudges')
   .option('--interval <seconds>', 'Auto-nudge poll interval in seconds', '3')
@@ -176,10 +203,164 @@ program
 
 program
   .command('validate')
-  .description('Validate Get Shit Done docs and QA protocol artifacts')
+  .description('Validate project protocol artifacts')
   .option('--mode <mode>', 'Validation mode: kickoff, turn, full', 'full')
   .option('--agent <id>', 'Expected agent for last history entry (turn mode)')
   .option('-j, --json', 'Output as JSON')
   .action(validateCommand);
 
+const verifyCmd = program
+  .command('verify')
+  .description('Verify protocol conformance targets');
+
+verifyCmd
+  .command('protocol')
+  .description('Run the protocol conformance fixture suite against a target implementation')
+  .option('--tier <tier>', 'Conformance tier to verify (1, 2, or 3)', '1')
+  .option('--surface <surface>', 'Restrict verification to a single surface')
+  .option('--target <path>', 'Target root containing .agentxchain-conformance/capabilities.json', '.')
+  .option('--format <format>', 'Output format: text or json', 'text')
+  .action(verifyProtocolCommand);
+
+program
+  .command('migrate')
+  .description('Migrate a legacy v3 project to governed format')
+  .option('-y, --yes', 'Skip confirmation prompts')
+  .option('-j, --json', 'Output migration report as JSON')
+  .action(migrateCommand);
+
+program
+  .command('resume')
+  .description('Resume a governed project: initialize or continue a run and assign the next turn')
+  .option('--role <role>', 'Override the target role (default: phase entry role)')
+  .option('--turn <id>', 'Target a specific retained turn when multiple exist')
+  .action(resumeCommand);
+
+program
+  .command('accept-turn')
+  .description('Accept the currently staged governed turn result')
+  .option('--turn <id>', 'Target a specific active turn when multiple turns exist')
+  .option('--resolution <mode>', 'Conflict resolution mode for conflicted turns (standard, human_merge)', 'standard')
+  .action(acceptTurnCommand);
+
+program
+  .command('reject-turn')
+  .description('Reject the current governed turn result and retry or escalate')
+  .option('--turn <id>', 'Target a specific active turn when multiple turns exist')
+  .option('--reason <reason>', 'Operator reason for the rejection')
+  .option('--reassign', 'Immediately re-dispatch a conflicted turn with conflict context')
+  .action(rejectTurnCommand);
+
+program
+  .command('step')
+  .description('Run a single governed turn: assign, dispatch, wait, validate, accept/reject')
+  .option('--role <role>', 'Override the target role (default: phase entry role)')
+  .option('--resume', 'Resume waiting for an already-active turn')
+  .option('--turn <id>', 'Target a specific active turn (required with --resume when multiple turns exist)')
+  .option('--poll <seconds>', 'Polling interval for manual adapter in seconds', '2')
+  .option('--verbose', 'Stream local_cli subprocess output while the turn is running')
+  .option('--auto-reject', 'Auto-reject and retry on validation failure')
+  .action(stepCommand);
+
+program
+  .command('approve-transition')
+  .description('Approve a pending phase transition that requires human sign-off')
+  .action(approveTransitionCommand);
+
+program
+  .command('approve-completion')
+  .description('Approve a pending run completion that requires human sign-off')
+  .action(approveCompletionCommand);
+
+program
+  .command('dashboard')
+  .description('Open the read-only governance dashboard in your browser')
+  .option('--port <port>', 'Server port', '3847')
+  .option('--no-open', 'Do not auto-open the browser')
+  .action(dashboardCommand);
+
+const pluginCmd = program
+  .command('plugin')
+  .description('Manage governed project plugins');
+
+pluginCmd
+  .command('install <source>')
+  .description('Install a plugin from a local path, archive, or npm package spec')
+  .option('--config <json>', 'Inline JSON plugin config validated against config_schema')
+  .option('--config-file <path>', 'Read plugin config JSON from a file')
+  .option('-j, --json', 'Output as JSON')
+  .action(pluginInstallCommand);
+
+pluginCmd
+  .command('list')
+  .description('List installed plugins')
+  .option('-j, --json', 'Output as JSON')
+  .action(pluginListCommand);
+
+pluginCmd
+  .command('remove <name>')
+  .description('Remove an installed plugin')
+  .option('-j, --json', 'Output as JSON')
+  .action(pluginRemoveCommand);
+
+pluginCmd
+  .command('upgrade <name> [source]')
+  .description('Upgrade an installed plugin atomically, rolling back on failure')
+  .option('--config <json>', 'Inline JSON plugin config validated against config_schema')
+  .option('--config-file <path>', 'Read plugin config JSON from a file')
+  .option('-j, --json', 'Output as JSON')
+  .action(pluginUpgradeCommand);
+
+const templateCmd = program
+  .command('template')
+  .description('Manage governed project templates');
+
+templateCmd
+  .command('set <id>')
+  .description('Set or change the governed template for this project')
+  .option('-y, --yes', 'Skip confirmation prompt')
+  .option('--dry-run', 'Print what would change without writing anything')
+  .action(templateSetCommand);
+
+templateCmd
+  .command('list')
+  .description('List available governed templates')
+  .option('-j, --json', 'Output as JSON')
+  .action(templateListCommand);
+
+const multiCmd = program
+  .command('multi')
+  .description('Multi-repo coordinator orchestration');
+
+multiCmd
+  .command('init')
+  .description('Bootstrap a multi-repo coordinator run')
+  .option('-j, --json', 'Output as JSON')
+  .action(multiInitCommand);
+
+multiCmd
+  .command('status')
+  .description('Show coordinator status and repo-run snapshots')
+  .option('-j, --json', 'Output as JSON')
+  .action(multiStatusCommand);
+
+multiCmd
+  .command('step')
+  .description('Select the next workstream and dispatch a coordinator turn')
+  .option('-j, --json', 'Output as JSON')
+  .action(multiStepCommand);
+
+multiCmd
+  .command('approve-gate')
+  .description('Approve a pending phase transition or completion gate')
+  .option('-j, --json', 'Output as JSON')
+  .action(multiApproveGateCommand);
+
+multiCmd
+  .command('resync')
+  .description('Detect divergence and rebuild coordinator state from repo authority')
+  .option('-j, --json', 'Output as JSON')
+  .option('--dry-run', 'Detect divergence without resyncing')
+  .action(multiResyncCommand);
+
 program.parse();