agentplane 0.4.2 → 0.4.3

package/README.md

@@ -1,22 +1,21 @@
-# AgentPlane
+# AgentPlane CLI
+
+**The open-source audit layer for coding agents.**
+
+`agentplane` is a local CLI that turns Claude Code, Codex, Cursor, Aider, and similar coding-agent
+work into reviewable, reversible Git artifacts.
 
 [![npm](https://img.shields.io/npm/v/agentplane.svg)](https://www.npmjs.com/package/agentplane)
 [![Downloads](https://img.shields.io/npm/dm/agentplane.svg)](https://www.npmjs.com/package/agentplane)
+[![GitHub stars](https://img.shields.io/github/stars/basilisk-labs/agentplane?style=flat)](https://github.com/basilisk-labs/agentplane/stargazers)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/basilisk-labs/agentplane/blob/main/LICENSE)
 [![Node.js 20+](https://img.shields.io/badge/Node.js-20%2B-3c873a.svg)](https://agentplane.org/docs/user/prerequisites)
 
-**Use coding agents without losing Git discipline.**
-
-`agentplane` is a local CLI that makes Claude Code, Codex, Cursor, Aider, and similar coding-agent
-work auditable inside your Git repository:
-
-```text
-task -> plan -> approve -> implement -> verify -> finish
-```
+[![SLSA v1 provenance](https://img.shields.io/badge/SLSA-v1-success)](https://registry.npmjs.org/-/npm/v1/attestations/agentplane@latest)
+[![Trusted publisher](https://img.shields.io/badge/npm-trusted%20publisher-blue)](https://docs.npmjs.com/generating-provenance-statements)
+[![Recipes signed: Ed25519](https://img.shields.io/badge/recipes-Ed25519%20signed-111827)](https://agentplane.org/docs/recipes)
 
-No hosted runtime. No hidden control plane. Everything stays in your repo.
-
-## Install
+## Install in 30 seconds
 
 ```bash
 npm i -g agentplane
@@ -24,141 +23,95 @@ agentplane init
 agentplane quickstart
 ```
 
-Requirements:
-
-- Node.js 20+
-- Git repository
-- Local terminal
-
-Prefer not to install globally:
+Prefer no global install:
 
 ```bash
 npx agentplane init
 npx agentplane quickstart
 ```
 
-## Why it exists
-
-Coding agents can change files. Teams still need to know what happened:
-
-- What task was the agent solving?
-- What plan was approved?
-- What changed in the repository?
-- What was verified?
-- Why was the task considered finished?
-
-AgentPlane adds a visible workflow layer around agent work without replacing Git, your editor, or
-your terminal.
+Requirements: Node.js 20+, Git, and a local terminal.
 
-## What appears in your repository
-
-`agentplane init` creates a visible workflow surface:
+## What you get after `agentplane init`
 
 ```text
 AGENTS.md or CLAUDE.md   Policy gateway for the repository
 .agentplane/            Repo-local workflow workspace
-.agentplane/config.json Current workflow configuration
+.agentplane/WORKFLOW.md Current workflow/config contract
 .agentplane/agents/     Installed agent profiles
 .agentplane/tasks/      Per-task records and evidence
-.agentplane/WORKFLOW.md Materialized workflow contract
+.agentplane/workflows/  Last-known-good workflow snapshot
 ```
 
-These artifacts make agent work inspectable. A reviewer can see what policy governed the repo, what
-task was active, what plan was accepted, what checks ran, and how the task was closed.
-
-## First task flow
+AgentPlane does not run a hosted control plane. It records the task trail inside the repository you
+already review.
 
-Create a task and record the plan:
-
-```bash
-agentplane task new --title "First task" --description "Describe the change" --priority med --owner DOCS --tag docs
-agentplane task plan set <task-id> --text "Explain the plan" --updated-by DOCS
-```
-
-If your repository requires explicit plan approval, run:
+## One task loop
 
 ```bash
+agentplane task new --title "Fix parser edge case" --description "Reject empty labels." --owner CODER --tag code
+agentplane task plan set <task-id> --text "Add a fixture, tighten validation, and run focused tests." --updated-by CODER
 agentplane task plan approve <task-id> --by ORCHESTRATOR
-```
-
-Then start work, record verification, and finish:
-
-```bash
-agentplane task start-ready <task-id> --author DOCS --body "Start: ..."
+agentplane task start-ready <task-id> --author CODER --body "Start: implementing parser validation with focused tests."
+# Run Claude Code, Codex, Cursor, Aider, or edit manually.
 agentplane task verify-show <task-id>
-agentplane verify <task-id> --ok --by DOCS --note "Checks passed"
-agentplane finish <task-id> --author DOCS --body "Verified: checks passed." --result "One-line outcome" --commit <git-rev>
+agentplane verify <task-id> --ok --by CODER --note "Focused tests passed."
+agentplane finish <task-id> --author CODER --result "Parser rejects empty labels." --commit <git-rev>
 ```
 
-That is the shortest useful path: initialize the repo, create a task, verify the change, and close it
-through recorded workflow state instead of an unstructured agent session.
+The visible output is the point: a reviewer can inspect task intent, plan, verification, and closure
+from Git-visible files.
 
-## Without vs with AgentPlane
+Roles like `CODER` and `ORCHESTRATOR` are configurable agent IDs. See
+[Agents](https://agentplane.org/docs/user/agents).
 
-| Without AgentPlane       | With AgentPlane                 |
-| ------------------------ | ------------------------------- |
-| Prompt in chat           | Task is recorded                |
-| Agent edits files        | Plan is explicit                |
-| Human inspects diff      | Approval is visible             |
-| Context is scattered     | Verification is stored          |
-| Verification is implicit | Finish creates closure evidence |
-| Closure is manual        | Everything lives close to Git   |
-
-## Workflow modes
+## Agent Change Record
 
-### `direct`
+Every task can produce an **Agent Change Record (ACR)**, a deterministic JSON evidence projection
+of intent, accepted plan, verification result, policy decisions, and closure commit.
 
-Fast local loops in the current checkout. Good for solo work, prototypes, and short tasks.
-
-### `branch_pr`
-
-Structured per-task branch and PR-style handoff. Good for teams, stricter review, and integration
-boundaries.
+```bash
+agentplane acr generate <task-id> --work-commit HEAD --write
+agentplane acr validate .agentplane/tasks/<task-id>/acr.json
+agentplane acr check <task-id> --require-plan-approved --require-verification
+agentplane acr --help
+```
 
-## Who it is for
+Schema: https://agentplane.org/schemas/acr-v0.1.schema.json
 
-- Developers using Claude Code, Codex, Cursor, Aider, or local coding agents.
-- Maintainers who want agent changes to remain reviewable.
-- Teams that need task state, verification, and closure before merging agent-generated work.
-- Local-first builders who do not want a hosted agent runtime between their repo and their workflow.
+## Workflow modes
 
-## What it is not
+- `direct` keeps work in the current checkout for fast local loops.
+- `branch_pr` creates per-task branches, worktrees, PR artifacts, and integration handoff.
 
-- Not a hosted agent platform.
-- Not a prompt framework.
-- Not a replacement for Git.
-- Not a replacement for your editor.
-- Not a replacement for Claude Code, Codex, Cursor, or Aider.
+## Compatible with
 
-## Workflow guides
+Claude Code, Codex CLI, Cursor agent, Aider, GitHub Actions agent runners, and MCP-driven
+workflows. AgentPlane does not replace them; it records what they did and whether your gates passed.
 
-Start from the guide that matches your current stack:
+## Recipes
 
-- [AgentPlane + Claude Code](https://agentplane.org/docs/workflow-guides/claude-code)
-- [AgentPlane + Codex](https://agentplane.org/docs/workflow-guides/codex)
-- [AgentPlane + Cursor](https://agentplane.org/docs/workflow-guides/cursor)
-- [AgentPlane + Aider](https://agentplane.org/docs/workflow-guides/aider)
-- [AgentPlane + GitHub Actions](https://agentplane.org/docs/workflow-guides/github-actions)
-- [AgentPlane + branch_pr workflow](https://agentplane.org/docs/workflow-guides/branch-pr)
+Recipes are signed, versioned behavior modules for AgentPlane:
 
-Installable recipes are separate signed packages; the current catalog starts with
-[Code Map](https://agentplane.org/docs/recipes/code-map).
+```bash
+agentplane recipes list-remote
+agentplane recipes install code-map --refresh --yes
+```
 
-## Documentation
+Start with [Code Map](https://agentplane.org/docs/recipes/code-map).
 
-Start here:
+## Docs
 
 - [Overview](https://agentplane.org/docs/user/overview)
 - [Setup](https://agentplane.org/docs/user/setup)
-- [Workflow](https://agentplane.org/docs/user/workflow)
 - [Task lifecycle](https://agentplane.org/docs/user/task-lifecycle)
-- [Commands](https://agentplane.org/docs/user/commands)
-- [CLI reference](https://agentplane.org/docs/user/cli-reference.generated)
+- [Workflow guides](https://agentplane.org/docs/workflow-guides)
+- [Recipes](https://agentplane.org/docs/recipes)
+- [Comparison](https://agentplane.org/docs/compare)
 
-## Support
+## Repository
 
-- [Issues](https://github.com/basilisk-labs/agentplane/issues)
-- [Contributing](https://github.com/basilisk-labs/agentplane/blob/main/CONTRIBUTING.md)
+https://github.com/basilisk-labs/agentplane
 
 ## License
 

package/assets/AGENTS.md

@@ -21,7 +21,7 @@ Detailed procedures live in canonical modules from `## CANONICAL DOCS`.
 - Repository type: user project initialized with `agentplane`.
 - Gateway role: keep this file compact and deterministic; move scenario-specific details to policy modules.
 - CLI rule: use `agentplane` from `PATH`; if unavailable, stop and request installation guidance (do not invent repo-local entrypoints).
-- Startup shortcut: run `## COMMANDS -> Preflight`, then use `agentplane quickstart`; activate `agentplane role ORCHESTRATOR` for planning and `agentplane role <ROLE>` for the active owner before owner-scoped execution; then apply `## LOAD RULES` before any mutation. The guarded route is determined by `workflow_mode` in `.agentplane/config.json`; use `agentplane quickstart` as the canonical summary of the active path before mutating. In `branch_pr`, start from `agentplane work start ... --worktree`; in `direct`, stay in the current checkout and use the task lifecycle route.
+- Startup shortcut: run `## COMMANDS -> Preflight`, then use `agentplane quickstart`; activate `agentplane role ORCHESTRATOR` for planning and `agentplane role <ROLE>` for the active owner before owner-scoped execution; then apply `## LOAD RULES` before any mutation. The guarded route is determined by `workflow.mode` in `.agentplane/WORKFLOW.md`; use `agentplane quickstart` as the canonical summary of the active path before mutating. In `branch_pr`, start from `agentplane work start ... --worktree`; in `direct`, stay in the current checkout and use the task lifecycle route.
 
 <!-- /ap:fragment -->
 <!-- ap:fragment id="gateway.agents.source_of_truth.sources.of.truth" slot="source_of_truth" mutability="replaceable" -->
@@ -33,7 +33,7 @@ Priority order (highest first):
 1. Enforcement: CI, tests, linters, hooks, CLI validations.
 2. Policy gateway: `AGENTS.md`.
 3. Canonical policy modules from `## CANONICAL DOCS`.
-4. CLI guidance: `agentplane quickstart`, `agentplane role <ROLE>`, `.agentplane/config.json`.
+4. CLI guidance: `agentplane quickstart`, `agentplane role <ROLE>`, `.agentplane/WORKFLOW.md`.
 5. Reference examples from `## REFERENCE EXAMPLES`.
 
 Conflict rule:
@@ -135,8 +135,8 @@ Condition: task includes mutation (file edits, task-state changes, commits, merg
 
 ### Conditional imports (linear IF -> LOAD contract)
 
-1. IF `workflow_mode=direct` THEN LOAD `@.agentplane/policy/workflow.direct.md`.
-2. IF `workflow_mode=branch_pr` THEN LOAD `@.agentplane/policy/workflow.branch_pr.md`.
+1. IF `workflow.mode=direct` THEN LOAD `@.agentplane/policy/workflow.direct.md`.
+2. IF `workflow.mode=branch_pr` THEN LOAD `@.agentplane/policy/workflow.branch_pr.md`.
 3. IF task touches release/version/publish THEN LOAD `@.agentplane/policy/workflow.release.md`.
 4. IF task runs `agentplane upgrade` or touches `.agentplane/.upgrade/**` THEN LOAD `@.agentplane/policy/workflow.upgrade.md`.
 5. IF task modifies implementation code paths THEN LOAD `@.agentplane/policy/dod.code.md`.

package/assets/policy/incidents.md

@@ -13,3 +13,5 @@
 - id: INC-20260501-03 | date: 2026-05-01 | scope: Make post-publish release evidence PR recovery authenticate gh so successful releases do not end as failed after publication. | tags: ci, release, workflow | match: ci, release, workflow, make, post, publish, evidence, recovery, authenticate, successful, releases, not, end, failed, after, publication | failure: Release evidence gh CLI steps now set GH_TOKEN from github.token. | advice: Added GH_TOKEN env to release evidence PR check/create/merge steps and contract coverage. | rule: Analogous Make post-publish release evidence PR recovery authenticate gh so successful releases do not end as failed after publication. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202605012054-HS993A; commit c329da9be70f | enforcement: manual | fixability: external | state: open
 - id: INC-20260501-04 | date: 2026-05-01 | scope: Update the Homebrew formula renderer and tap formula so fresh AgentPlane releases install without Homebrew npm min-release-age blocking fresh package dependencies. | tags: release, workflow | match: release, workflow, update, the, homebrew, formula, renderer, and, tap, fresh, agentplane, releases, install, without, npm, min | failure: Updated render-homebrew-formula to install the cached npm tarball without std_npm_args/min-release-age, added contract coverage, and pushed basilisk-labs/homebrew-tap c6d3e94 for v0.4.1. Local Homebrew install reached Cellar successfully; final link was blocked only by an existing /opt/homebrew/bin/agentplane npm-global symlink. | advice: Run brew link --overwrite agentplane when an old npm-global symlink is present; standalone no-Node install requires a future native/bundled CLI artifact. | rule: Analogous Update the Homebrew formula renderer and tap formula so fresh AgentPlane releases install without Homebrew npm min-release-age blocking fresh package dependencies. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202605012143-NEK3E8; commit 43bc2ed84a23 | enforcement: manual | fixability: external | state: open
 - id: INC-20260503-01 | date: 2026-05-03 | scope: Port the artifacts_language configuration and PR artifact language validation from the stale cli-artifacts branch onto current main, preserving current v0.4.2 release state. | tags: code, release, workflow | match: code, release, workflow, port, the, artifacts, language, configuration, and, artifact, validation, from, stale, cli, branch, onto | failure: Ported artifacts_language=en and PR artifact language validation onto current main; stale trust branch was not merged because it would reintroduce old task states. | advice: No rework required before PR. | rule: Analogous Port the artifacts_language configuration and PR artifact language validation from the stale cli-artifacts branch onto current main, preserving current v0.4.2 release state. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202605030733-BHD4S4; commit c66cff3d6f16 | enforcement: manual | fixability: external | state: open
+- id: INC-20260503-02 | date: 2026-05-03 | scope: Update standalone release artifact smoke testing to accept the current doctor OK output and surface doctor output on failures so v0.4.2 publish can complete. | tags: code, release, testing | match: code, release, testing, update, standalone, artifact, smoke, accept, the, current, doctor, output, and, surface, failures, publish | failure: Publish run 25273723107 failed before npm/tag at standalone linux-x64 doctor smoke because the script expected 'doctor OK' but current CLI emits 'doctor (OK)'. | advice: Smoke now accepts both legacy and current doctor OK markers and includes doctor output on failure. | rule: Analogous Update standalone release artifact smoke testing to accept the current doctor OK output and surface doctor output on failures so v0.4.2 publish can complete. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202605030807-DBY2RS; commit 2c98719336c8 | enforcement: manual | fixability: external | state: open
+- id: INC-20260503-03 | date: 2026-05-03 | scope: Split AgentPlane default sign-off identity from repo-wide manual DCO validation and make .agentplane/tasks.json an optional generated export snapshot rather than tracked required state. | tags: code, git, tasks | match: code, git, tasks, split, agentplane, default, sign, off, identity, from, repo, wide, manual, dco, validation, and | failure: Full hook-run suite was not used as final evidence because an unrelated existing pre-push scenario still tries to git add .agentplane/config.json after the WORKFLOW-only migration. | advice: Focused checks pass; remaining doctor warning is outside this task scope. | rule: Analogous Split AgentPlane default sign-off identity from repo-wide manual DCO validation and make .agentplane/tasks.json an optional generated export snapshot rather than tracked required state. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202605031737-9A4FWX; commit eda55d00831b | enforcement: manual | fixability: external | state: open

package/bin/agentplane.js

@@ -2,7 +2,7 @@
 import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import path from "node:path";
-import { stat } from "node:fs/promises";
+import { mkdir, rm, stat } from "node:fs/promises";
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 import { distExists, isPackageBuildFresh } from "./dist-guard.js";
@@ -186,6 +186,95 @@ function renderStalePolicyWarning(reason) {
   return "warning: allowing read-only diagnostic command to run with a stale repo build inside the framework checkout.\n";
 }
 
+function staleAutoBootstrapEnabled() {
+  return (process.env.AGENTPLANE_DEV_AUTO_BOOTSTRAP ?? "1").trim() !== "0";
+}
+
+function alreadyTriedStaleAutoBootstrap() {
+  return (process.env.AGENTPLANE_DEV_AUTO_BOOTSTRAPPED ?? "").trim() === "1";
+}
+
+async function withBootstrapLock(repoRoot, fn) {
+  const lockParent = path.join(repoRoot, ".agentplane", "cache");
+  const lockDir = path.join(lockParent, "framework-dev-bootstrap.lock");
+  await mkdir(lockParent, { recursive: true });
+  try {
+    await mkdir(lockDir, { recursive: false });
+  } catch (error) {
+    if (error?.code !== "EEXIST") throw error;
+    process.stderr.write(
+      "error: another framework dev bootstrap is already running.\n" +
+        `Retry after the lock is released: ${path.relative(repoRoot, lockDir)}\n`,
+    );
+    process.exitCode = 2;
+    return true;
+  }
+
+  try {
+    return await fn();
+  } finally {
+    await rm(lockDir, { recursive: true, force: true });
+  }
+}
+
+async function autoBootstrapAndRerun(repoRoot, staleReasons, commandPolicy) {
+  if (!staleAutoBootstrapEnabled() || alreadyTriedStaleAutoBootstrap()) return false;
+
+  const commandText = process.argv
+    .slice(2)
+    .map((value) => String(value ?? "").trim())
+    .filter(Boolean)
+    .join(" ");
+  process.stderr.write(
+    "info: stale repo build detected; running framework dev bootstrap before command.\n" +
+      `command: ${commandText || "<unknown>"}\n` +
+      `detected: ${staleReasons.join(", ")}\n` +
+      `reason: ${commandPolicy.reason}\n`,
+  );
+
+  return await withBootstrapLock(repoRoot, async () => {
+    const bootstrap = spawnSync("bun", ["run", "framework:dev:bootstrap"], {
+      cwd: repoRoot,
+      stdio: "inherit",
+      env: {
+        ...process.env,
+        AGENTPLANE_DEV_AUTO_BOOTSTRAP: "0",
+      },
+    });
+
+    if (bootstrap.error || bootstrap.status !== 0) {
+      const reason = bootstrap.error?.message ?? `exit ${bootstrap.status ?? "unknown"}`;
+      process.stderr.write(
+        `error: automatic framework dev bootstrap failed (${reason}).\n` +
+          "Manual fallback:\n" +
+          FRAMEWORK_DEV_MANUAL_REPAIR_COMMANDS.map((command) => `  ${command}\n`).join(""),
+      );
+      process.exitCode = bootstrap.status ?? 2;
+      return true;
+    }
+
+    const rerun = spawnSync(
+      process.execPath,
+      [fileURLToPath(import.meta.url), ...process.argv.slice(2)],
+      {
+        cwd: process.cwd(),
+        stdio: "inherit",
+        env: {
+          ...process.env,
+          AGENTPLANE_DEV_AUTO_BOOTSTRAPPED: "1",
+        },
+      },
+    );
+    if (rerun.error) {
+      process.stderr.write(`error: failed to rerun after bootstrap: ${rerun.error.message}\n`);
+      process.exitCode = 2;
+      return true;
+    }
+    process.exitCode = rerun.status ?? (rerun.signal ? 1 : 0);
+    return true;
+  });
+}
+
 function missingRepoRuntimeDependencies(agentplaneRoot) {
   const requireFromAgentplane = createRequire(path.join(agentplaneRoot, "package.json"));
   const frameworkRoot = path.resolve(agentplaneRoot, "..", "..");
@@ -300,6 +389,10 @@ async function assertDistUpToDate() {
 
     const commandPolicy = classifyStaleDistPolicy(process.argv);
     if (commandPolicy.mode === "warn_and_run") {
+      if (await autoBootstrapAndRerun(repoRoot, staleReasons, commandPolicy)) {
+        return false;
+      }
+
       const commandText = process.argv
         .slice(2)
         .map((value) => String(value ?? "").trim())

package/dist/.build-manifest.json

@@ -2,7 +2,7 @@
   "schema_version": 1,
   "manifest_kind": "package",
   "package_name": "agentplane",
-  "package_version": "0.4.2",
-  "git_head": "2c98719336c87cbe2aaf196d14b32c841a9defa1",
-  "watched_runtime_snapshot_hash": "56c2045c93aa3da808e26b1dc2396f28fbdcbe7a9c1ba9db50362d2432b0f257"
+  "package_version": "0.4.3",
+  "git_head": "04ccc002125560cd2ec87094e20cd5a9907d2016",
+  "watched_runtime_snapshot_hash": "5a534e101008bc57436f81a2364408cd0c5368241c43b43a4a814875fa750f68"
 }