agentxchain 2.10.0 → 2.12.0

package/README.md

@@ -25,7 +25,7 @@ npm install -g agentxchain
 Or run without installing:
 
 ```bash
-npx agentxchain init --governed -y
+npx agentxchain init --governed --dir my-agentxchain-project -y
 ```
 
 ## Testing
@@ -49,7 +49,7 @@ Duplicate execution remains intentional for the current 36-file slice until a la
 ### Governed workflow
 
 ```bash
-npx agentxchain init --governed -y
+npx agentxchain init --governed --dir my-agentxchain-project -y
 cd my-agentxchain-project
 git init
 git add -A
@@ -58,10 +58,16 @@ agentxchain status
 agentxchain step --role pm
 ```
 
+The default governed dev runtime is `claude --print` with stdin prompt delivery. If your local coding agent uses a different launch contract, set it during scaffold creation:
+
+```bash
+npx agentxchain init --governed --dir my-agentxchain-project --dev-command ./scripts/dev-agent.sh --dev-prompt-transport dispatch_bundle_only -y
+```
+
 If you want template-specific planning artifacts from day one:
 
 ```bash
-npx agentxchain init --governed --template api-service -y
+npx agentxchain init --governed --template api-service --dir my-agentxchain-project -y
 ```
 
 Built-in governed templates:
@@ -83,7 +89,7 @@ agentxchain step --role qa
 agentxchain approve-completion
 ```
 
-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.
+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. If you override the dev runtime, either include `{prompt}` for argv delivery or set `--dev-prompt-transport` explicitly.
 
 ### Migrate a legacy project
 
@@ -99,7 +105,7 @@ agentxchain step
 
 | Command | What it does |
 |---|---|
-| `init --governed [--template <id>]` | Create a governed project, optionally with project-shape-specific planning artifacts |
+| `init --governed [--dir <path>] [--template <id>]` | Create a governed project, optionally in-place or in an explicit target directory, 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 |
@@ -109,6 +115,7 @@ agentxchain step
 | `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 |
+| `template validate` | Prove the template registry, workflow-kit scaffold contract, and planning artifact completeness (`--json` exposes a `workflow_kit` block) |
 | `verify protocol` | Run the shipped protocol conformance suite against a target implementation |
 | `dashboard` | Open the local governance dashboard in your browser for repo-local runs or multi-repo coordinator initiatives, including pending gate approvals |
 | `plugin install|list|remove` | Install, inspect, or remove governed hook plugins backed by `agentxchain-plugin.json` manifests |

package/bin/agentxchain.js

@@ -69,6 +69,7 @@ import { escalateCommand } from '../src/commands/escalate.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 { runCommand } from '../src/commands/run.js';
 import { approveTransitionCommand } from '../src/commands/approve-transition.js';
 import { approveCompletionCommand } from '../src/commands/approve-completion.js';
 import { dashboardCommand } from '../src/commands/dashboard.js';
@@ -114,7 +115,10 @@ program
   .description('Create a new AgentXchain project folder')
   .option('-y, --yes', 'Skip prompts, use defaults')
   .option('--governed', 'Create a governed project (orchestrator-owned state)')
+  .option('--dir <path>', 'Scaffold target directory. Use "." for in-place bootstrap.')
   .option('--template <id>', 'Governed scaffold template: generic, api-service, cli-tool, library, web-app')
+  .option('--dev-command <parts...>', 'Governed local-dev command parts. Include {prompt} for argv prompt delivery.')
+  .option('--dev-prompt-transport <mode>', 'Governed local-dev prompt transport: argv, stdin, dispatch_bundle_only')
   .option('--schema-version <version>', 'Schema version (3 for legacy, or use --governed for current)')
   .action(initCommand);
 
@@ -245,6 +249,9 @@ verifyCmd
   .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('--remote <url>', 'Remote HTTP conformance endpoint base URL')
+  .option('--token <token>', 'Bearer token for remote HTTP conformance endpoint')
+  .option('--timeout <ms>', 'Per-fixture remote HTTP timeout in milliseconds', '30000')
   .option('--format <format>', 'Output format: text or json', 'text')
   .action(verifyProtocolCommand);
 
@@ -304,6 +311,16 @@ program
   .option('--auto-reject', 'Auto-reject and retry on validation failure')
   .action(stepCommand);
 
+program
+  .command('run')
+  .description('Drive a governed run to completion: multi-turn execution with gate prompting')
+  .option('--role <role>', 'Override the initial role (default: config-driven selection)')
+  .option('--max-turns <n>', 'Maximum turns before stopping (default: 50)', parseInt)
+  .option('--auto-approve', 'Auto-approve all gates (non-interactive mode)')
+  .option('--verbose', 'Stream adapter subprocess output')
+  .option('--dry-run', 'Print what would be dispatched without executing')
+  .action(runCommand);
+
 program
   .command('approve-transition')
   .description('Approve a pending phase transition that requires human sign-off')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentxchain",
-  "version": "2.10.0",
+  "version": "2.12.0",
   "description": "CLI for AgentXchain — governed multi-agent software delivery",
   "type": "module",
   "bin": {
@@ -20,6 +20,7 @@
     "test:node": "node --test test/*.test.js",
     "preflight:release": "bash scripts/release-preflight.sh",
     "preflight:release:strict": "bash scripts/release-preflight.sh --strict",
+    "postflight:release": "bash scripts/release-postflight.sh",
     "build:macos": "bun build bin/agentxchain.js --compile --target=bun-darwin-arm64 --outfile=dist/agentxchain-macos-arm64",
     "build:linux": "bun build bin/agentxchain.js --compile --target=bun-linux-x64 --outfile=dist/agentxchain-linux-x64",
     "publish:npm": "bash scripts/publish-npm.sh"

package/src/commands/init.js

@@ -1,11 +1,12 @@
 import { writeFileSync, readFileSync, existsSync, mkdirSync, readdirSync } from 'fs';
-import { join, resolve, dirname } from 'path';
+import { basename, join, relative, resolve, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import chalk from 'chalk';
 import inquirer from 'inquirer';
 import { CONFIG_FILE, LOCK_FILE, STATE_FILE } from '../lib/config.js';
 import { generateVSCodeFiles } from '../lib/generate-vscode.js';
 import { loadGovernedTemplate, VALID_GOVERNED_TEMPLATE_IDS } from '../lib/governed-templates.js';
+import { VALID_PROMPT_TRANSPORTS } from '../lib/normalized-config.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const TEMPLATES_DIR = join(__dirname, '../templates');
@@ -93,9 +94,16 @@ const GOVERNED_ROLES = {
   }
 };
 
+const DEFAULT_GOVERNED_LOCAL_DEV_RUNTIME = Object.freeze({
+  type: 'local_cli',
+  command: ['claude', '--print'],
+  cwd: '.',
+  prompt_transport: 'stdin',
+});
+
 const GOVERNED_RUNTIMES = {
   'manual-pm': { type: 'manual' },
-  'local-dev': { type: 'local_cli', command: ['claude', '--print', '-p', '{prompt}'], cwd: '.', prompt_transport: 'argv' },
+  'local-dev': DEFAULT_GOVERNED_LOCAL_DEV_RUNTIME,
   'api-qa': { type: 'api_proxy', provider: 'anthropic', model: 'claude-sonnet-4-6', auth_env: 'ANTHROPIC_API_KEY' },
   'manual-director': { type: 'manual' }
 };
@@ -353,8 +361,92 @@ ${role.write_authority === 'authoritative'
 `;
 }
 
-export function scaffoldGoverned(dir, projectName, projectId, templateId = 'generic') {
+function commandHasPromptPlaceholder(parts = []) {
+  return parts.some((part) => typeof part === 'string' && part.includes('{prompt}'));
+}
+
+function resolveGovernedLocalDevRuntime(opts = {}) {
+  const customCommand = Array.isArray(opts.devCommand)
+    ? opts.devCommand.map((part) => String(part).trim()).filter(Boolean)
+    : null;
+  const explicitTransport = typeof opts.devPromptTransport === 'string' && opts.devPromptTransport.trim()
+    ? opts.devPromptTransport.trim()
+    : null;
+
+  if (explicitTransport && !VALID_PROMPT_TRANSPORTS.includes(explicitTransport)) {
+    throw new Error(`Unknown --dev-prompt-transport "${explicitTransport}". Valid values: ${VALID_PROMPT_TRANSPORTS.join(', ')}`);
+  }
+
+  if (!customCommand?.length) {
+    const command = [...DEFAULT_GOVERNED_LOCAL_DEV_RUNTIME.command];
+    if (explicitTransport === 'argv') {
+      throw new Error('Default local dev command does not include {prompt}. Use --dev-command ... {prompt} for argv mode.');
+    }
+    return {
+      runtime: {
+        ...DEFAULT_GOVERNED_LOCAL_DEV_RUNTIME,
+        command,
+        prompt_transport: explicitTransport || DEFAULT_GOVERNED_LOCAL_DEV_RUNTIME.prompt_transport,
+      },
+    };
+  }
+
+  const hasPlaceholder = commandHasPromptPlaceholder(customCommand);
+
+  if (!explicitTransport && !hasPlaceholder) {
+    throw new Error('Custom --dev-command must either include {prompt} or set --dev-prompt-transport explicitly.');
+  }
+
+  if (explicitTransport === 'argv' && !hasPlaceholder) {
+    throw new Error('--dev-prompt-transport argv requires {prompt} in --dev-command.');
+  }
+
+  if (explicitTransport && explicitTransport !== 'argv' && hasPlaceholder) {
+    throw new Error(`--dev-prompt-transport ${explicitTransport} must not be combined with {prompt} in --dev-command.`);
+  }
+
+  return {
+    runtime: {
+      type: 'local_cli',
+      command: customCommand,
+      cwd: '.',
+      prompt_transport: explicitTransport || 'argv',
+    },
+  };
+}
+
+function formatGovernedRuntimeCommand(runtime) {
+  return Array.isArray(runtime?.command) ? runtime.command.join(' ') : String(runtime?.command || '');
+}
+
+function resolveInitDirOption(dirOption) {
+  if (dirOption == null) return null;
+  const value = String(dirOption).trim();
+  if (!value) {
+    throw new Error('--dir must not be empty.');
+  }
+  return value;
+}
+
+function inferProjectNameFromTarget(targetPath, fallbackName) {
+  const inferred = basename(resolve(process.cwd(), targetPath));
+  return inferred && inferred.trim() ? inferred : fallbackName;
+}
+
+function formatInitTarget(dir) {
+  const rel = relative(process.cwd(), dir);
+  if (!rel) return '.';
+  if (!rel.startsWith('..')) return rel;
+  return dir;
+}
+
+export function scaffoldGoverned(dir, projectName, projectId, templateId = 'generic', runtimeOptions = {}) {
   const template = loadGovernedTemplate(templateId);
+  const { runtime: localDevRuntime } = resolveGovernedLocalDevRuntime(runtimeOptions);
+  const runtimes = {
+    ...GOVERNED_RUNTIMES,
+    'local-dev': localDevRuntime,
+  };
   const config = {
     schema_version: '1.0',
     template: template.id,
@@ -364,7 +456,7 @@ export function scaffoldGoverned(dir, projectName, projectId, templateId = 'gene
       default_branch: 'main'
     },
     roles: GOVERNED_ROLES,
-    runtimes: GOVERNED_RUNTIMES,
+    runtimes,
     routing: GOVERNED_ROUTING,
     gates: GOVERNED_GATES,
     budget: {
@@ -475,6 +567,14 @@ export function scaffoldGoverned(dir, projectName, projectId, templateId = 'gene
 async function initGoverned(opts) {
   let projectName, folderName;
   const templateId = opts.template || 'generic';
+  let explicitDir;
+
+  try {
+    explicitDir = resolveInitDirOption(opts.dir);
+  } catch (err) {
+    console.error(chalk.red(`  Error: ${err.message}`));
+    process.exit(1);
+  }
 
   if (!VALID_GOVERNED_TEMPLATE_IDS.includes(templateId)) {
     console.error(chalk.red(`  Error: Unknown template "${templateId}".`));
@@ -489,29 +589,44 @@ async function initGoverned(opts) {
   }
 
   if (opts.yes) {
-    projectName = 'My AgentXchain Project';
-    folderName = slugify(projectName);
+    projectName = explicitDir
+      ? inferProjectNameFromTarget(explicitDir, 'My AgentXchain Project')
+      : 'My AgentXchain Project';
+    folderName = explicitDir || slugify(projectName);
   } else {
     const { name } = await inquirer.prompt([{
       type: 'input',
       name: 'name',
       message: 'Project name:',
-      default: 'My AgentXchain Project'
+      default: explicitDir
+        ? inferProjectNameFromTarget(explicitDir, 'My AgentXchain Project')
+        : 'My AgentXchain Project'
     }]);
     projectName = name;
-    folderName = slugify(projectName);
+    folderName = explicitDir || slugify(projectName);
 
-    const { folder } = await inquirer.prompt([{
-      type: 'input',
-      name: 'folder',
-      message: 'Folder name:',
-      default: folderName
-    }]);
-    folderName = folder;
+    if (!explicitDir) {
+      const { folder } = await inquirer.prompt([{
+        type: 'input',
+        name: 'folder',
+        message: 'Folder name:',
+        default: folderName
+      }]);
+      folderName = folder;
+    }
   }
 
   const dir = resolve(process.cwd(), folderName);
+  const targetLabel = formatInitTarget(dir);
   const projectId = slugify(projectName);
+  let localDevRuntime;
+
+  try {
+    ({ runtime: localDevRuntime } = resolveGovernedLocalDevRuntime(opts));
+  } catch (err) {
+    console.error(chalk.red(`  Error: ${err.message}`));
+    process.exit(1);
+  }
 
   if (existsSync(dir) && existsSync(join(dir, CONFIG_FILE))) {
     if (!opts.yes) {
@@ -530,10 +645,10 @@ async function initGoverned(opts) {
 
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
 
-  scaffoldGoverned(dir, projectName, projectId, templateId);
+  scaffoldGoverned(dir, projectName, projectId, templateId, opts);
 
   console.log('');
-  console.log(chalk.green(`  ✓ Created governed project ${chalk.bold(folderName)}/`));
+  console.log(chalk.green(`  ✓ Created governed project ${chalk.bold(targetLabel)}/`));
   console.log('');
   console.log(`    ${chalk.dim('├──')} agentxchain.json  ${chalk.dim('(governed)')}`);
   console.log(`    ${chalk.dim('├──')} .agentxchain/`);
@@ -549,10 +664,13 @@ async function initGoverned(opts) {
   console.log('');
   console.log(`  ${chalk.dim('Roles:')} pm, dev, qa, eng_director`);
   console.log(`  ${chalk.dim('Template:')} ${templateId}`);
+  console.log(`  ${chalk.dim('Dev runtime:')} ${formatGovernedRuntimeCommand(localDevRuntime)} ${chalk.dim(`(${localDevRuntime.prompt_transport})`)}`);
   console.log(`  ${chalk.dim('Protocol:')} governed convergence`);
   console.log('');
   console.log(`  ${chalk.cyan('Next:')}`);
-  console.log(`    ${chalk.bold(`cd ${folderName}`)}`);
+  if (dir !== process.cwd()) {
+    console.log(`    ${chalk.bold(`cd ${targetLabel}`)}`);
+  }
   console.log(`    ${chalk.bold('agentxchain step')} ${chalk.dim('# run the first governed turn')}`);
   console.log(`    ${chalk.bold('agentxchain status')} ${chalk.dim('# inspect phase, gate, and turn state')}`);
   console.log('');
@@ -564,11 +682,20 @@ export async function initCommand(opts) {
   }
 
   let project, agents, folderName, rules;
+  let explicitDir;
+  try {
+    explicitDir = resolveInitDirOption(opts.dir);
+  } catch (err) {
+    console.error(chalk.red(`  Error: ${err.message}`));
+    process.exit(1);
+  }
 
   if (opts.yes) {
-    project = 'My AgentXchain project';
+    project = explicitDir
+      ? inferProjectNameFromTarget(explicitDir, 'My AgentXchain project')
+      : 'My AgentXchain project';
     agents = DEFAULT_AGENTS;
-    folderName = slugify(project);
+    folderName = explicitDir || slugify(project);
     rules = {
       max_consecutive_claims: 2,
       require_message: true,
@@ -618,7 +745,9 @@ export async function initCommand(opts) {
         type: 'input',
         name: 'projectName',
         message: 'Project name:',
-        default: 'My AgentXchain project'
+        default: explicitDir
+          ? inferProjectNameFromTarget(explicitDir, 'My AgentXchain project')
+          : 'My AgentXchain project'
       }]);
       project = projectName;
     } else {
@@ -626,7 +755,9 @@ export async function initCommand(opts) {
         type: 'input',
         name: 'projectName',
         message: 'Project name:',
-        default: 'My AgentXchain project'
+        default: explicitDir
+          ? inferProjectNameFromTarget(explicitDir, 'My AgentXchain project')
+          : 'My AgentXchain project'
       }]);
       project = projectName;
       agents = {};
@@ -681,14 +812,16 @@ export async function initCommand(opts) {
       }
     }
 
-    folderName = slugify(project);
-    const { folder } = await inquirer.prompt([{
-      type: 'input',
-      name: 'folder',
-      message: 'Folder name:',
-      default: folderName
-    }]);
-    folderName = folder;
+    folderName = explicitDir || slugify(project);
+    if (!explicitDir) {
+      const { folder } = await inquirer.prompt([{
+        type: 'input',
+        name: 'folder',
+        message: 'Folder name:',
+        default: folderName
+      }]);
+      folderName = folder;
+    }
   }
 
   const dir = resolve(process.cwd(), folderName);