agentplane 0.3.5 → 0.3.6

package/README.md

@@ -3,122 +3,150 @@
 [![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)
 [![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://github.com/basilisk-labs/agentplane/blob/main/docs/user/prerequisites.mdx)
+[![Node.js 20+](https://img.shields.io/badge/Node.js-20%2B-3c873a.svg)](https://agentplane.org/docs/user/prerequisites)
 
-Agent Plane is a policy-driven framework for running LLM agents inside real repositories. It turns "AI magic" into an engineering process: explicit approvals, role boundaries, and a reproducible execution pipeline. The goal is simple: make agents boring, safe, and auditable.
+**Git-native control plane for auditable agent work.**
 
-## Why Agent Plane
+Put coding agents on a governed Git workflow.
 
-- You want agents that behave predictably inside real repos.
-- You need human approvals, clear roles, and traceable artifacts.
-- You want guardrails by default, not optional add-ons.
-- You want an offline-first CLI that keeps state local and inspectable.
+`agentplane` is the CLI for AgentPlane. It runs locally inside a git repository, not in a hosted runtime, and adds visible workflow artifacts such as `AGENTS.md` or `CLAUDE.md`, `.agentplane/`, task records, verification state, and deterministic closure. Teams use it when they want agent work to stay explicit, inspectable, and governed inside the repository instead of behaving like an opaque assistant.
 
-## 5-minute start
+## What agentplane is
 
-Install and initialize the CLI:
+`agentplane` is a repo-native CLI workflow for agent-driven development.
+
+- It runs in your repository and keeps workflow state local.
+- It adds approvals, task state, verification, and finish to agent work.
+- It supports both `direct` and `branch_pr` workflow modes.
+- It keeps repository artifacts visible instead of hiding execution behind a hosted control plane.
+
+## Why teams use it
+
+Teams use `agentplane` when changing files is not enough and they need the work itself to stay legible.
+
+- **Trust comes from visible process.** Plans, verification, and finish are recorded instead of implied.
+- **The workflow stays local.** There is no hosted control plane between your repository and your team.
+- **Git remains first-class.** `agentplane` governs agent work inside commits and repository state instead of bypassing them.
+- **The same CLI fits different review styles.** Use `direct` for short loops or `branch_pr` for stricter integration.
+
+## What appears in your repository
+
+`agentplane init` creates a visible workflow surface inside the repository.
+
+```text
+AGENTS.md or CLAUDE.md   Policy gateway for the repository
+.agentplane/            Repo-local workspace and workflow state
+.agentplane/config.json Current repo configuration
+.agentplane/agents/     Installed agent profiles
+.agentplane/tasks/      Per-task records and evidence
+.agentplane/WORKFLOW.md Current workflow contract
+```
+
+You may also see `.agentplane/tasks.json` later if you export a task snapshot, and `.agentplane/workflows/last-known-good.md` as part of the workflow runtime state.
+
+## Install and first run
 
 ```bash
 npm install -g agentplane
+```
+
+Run the CLI inside the git repository you want to govern:
+
+```bash
+cd /path/to/your-repository
 agentplane init
 agentplane quickstart
 ```
 
-`agentplane init` is human-oriented: interactive onboarding includes workflow/backend selection,
-policy gateway selection (`--policy-gateway codex|claude` -> `AGENTS.md` or `CLAUDE.md`),
-execution profile selection (`conservative|balanced|aggressive`), approval toggles, and optional recipes.
+If the directory is not a git repository yet, `agentplane init` initializes git first.
 
-Create your first task and run the workflow:
+`agentplane init` is interactive by default. It lets you choose the workflow mode, backend, gateway file (`AGENTS.md` or `CLAUDE.md`), execution profile, and optional recipe setup.
 
-```bash
-agentplane task new --title "First task" --description "Describe the change" --priority med --owner ORCHESTRATOR --tag docs
-agentplane verify <task-id> --ok --by ORCHESTRATOR --note "Verified"
-agentplane finish <task-id> --author ORCHESTRATOR --body "Verified: done" --result "First task completed"
-```
+On the first run it creates the visible workflow surface:
 
-Prefer `npx` instead of a global install?
+- `AGENTS.md` or `CLAUDE.md`
+- `.agentplane/config.json`
+- `.agentplane/tasks/`
+- `.agentplane/agents/`
+- `.agentplane/WORKFLOW.md`
+
+Prefer not to install globally:
 
 ```bash
 npx agentplane init
 npx agentplane quickstart
 ```
 
-## What gets installed automatically
+## First task flow
 
-- `.agentplane/` is created with config, tasks, agents, and caches.
-- The selected policy gateway file is created if missing and defines the policy/guardrails:
-  `AGENTS.md` (Codex) or `CLAUDE.md` (Claude Code).
-- Built-in agent definitions are copied into `.agentplane/agents/`.
-- Optional recipes can install additional agents when you run `agentplane recipes install ...`.
-- `.agentplane/config.json` stores execution defaults under `execution` (profile, reasoning effort, tool budget, safety gates).
+Create a task and record the plan:
 
-## Upgrade review reports
+```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
+```
 
-After `agentplane upgrade` (auto or agent-assisted mode), a machine-readable review report is written under `.agentplane/.upgrade/`:
+If your repository requires explicit plan approval, run:
 
-- Agent mode: `.agentplane/.upgrade/agent/<runId>/review.json`
-- Auto mode: `.agentplane/.upgrade/last-review.json`
+```bash
+agentplane task plan approve <task-id> --by ORCHESTRATOR
+```
 
-If any entry has `needsSemanticReview: true`, treat it as a signal to create an `UPGRADER` task to perform a semantic prompt merge.
+Then start work, record verification, and finish:
 
-## Guardrails and artifacts
+```bash
+agentplane task start-ready <task-id> --author DOCS --body "Start: ..."
+agentplane task verify-show <task-id>
+agentplane verify <task-id> --ok --by REVIEWER --note "Looks good"
+agentplane finish <task-id> --author DOCS --body "Verified: ..." --result "One-line outcome" --commit <git-rev>
+```
 
-- Approval gates for plans and network access (configured in `.agentplane/config.json`).
-- Role boundaries (ORCHESTRATOR, PLANNER, CODER, INTEGRATOR, etc.).
-- Agent definitions in `.agentplane/agents/`.
-- Task records in `.agentplane/tasks/` with a snapshot export in `.agentplane/tasks.json`.
-- A visible, reproducible pipeline:
+That is the shortest believable first-win path: initialize the repo, create a task, verify the change, and close it through the recorded workflow instead of an unstructured agent session.
 
-```text
-Preflight -> Plan -> Approval -> Tasks -> Verify -> Finish -> Export
-```
+## Workflow modes
 
-## Features
+### `direct`
 
-- Policy-first execution with explicit approvals and guardrails.
-- Role-based workflows for teams: ORCHESTRATOR, PLANNER, CREATOR, INTEGRATOR, etc.
-- Two workflow modes: `direct` (single checkout) and `branch_pr` (worktrees + integration).
-- Task tracking, verification, and exports baked in.
-- Recipes for repeatable setup and automation.
+- single checkout
+- fast local iteration
+- deterministic close commit on `finish` by default
+- best fit for solo work or short loops
 
-## Install
+### `branch_pr`
 
-```bash
-npm install -g agentplane
-```
+- per-task branch or worktree flow
+- explicit PR artifacts under `.agentplane/tasks/<task-id>/pr/`
+- stricter handoff and integration discipline
+- better fit for teams that want implementation separated from integration
 
-Or run without installing:
+## When to use it
 
-```bash
-npx agentplane --help
-```
+Use `agentplane` when:
 
-## Requirements
+- you want coding agents to work inside a real git repository
+- you need explicit task state, approvals, verification, and closure
+- you want repo-local workflow artifacts instead of a hidden assistant session
 
-- Node.js >= 20
+Do not use `agentplane` when:
 
-## Common Commands
+- you want a hosted agent platform
+- you want a generic prompt framework
+- you want the tool to hide git or replace your editor
 
-```bash
-agentplane --help
-agentplane quickstart
-agentplane role ORCHESTRATOR
-agentplane role UPGRADER
-agentplane config show
-agentplane task list
-agentplane task new --title "..." --description "..." --priority med --owner ORCHESTRATOR --tag docs
-agentplane verify <task-id> --ok --by ORCHESTRATOR --note "Verified"
-agentplane finish <task-id> --author ORCHESTRATOR --body "Verified: done" --result "Task completed"
-agentplane recipes list
-```
+## Requirements
+
+- Node.js 20+
 
-## Docs and Guides
+## Documentation
 
-- Documentation index: https://github.com/basilisk-labs/agentplane/tree/main/docs
-- Workflow overview: https://github.com/basilisk-labs/agentplane/blob/main/docs/user/workflow.mdx
-- CLI commands: https://github.com/basilisk-labs/agentplane/blob/main/docs/user/commands.mdx
-- Project layout: https://github.com/basilisk-labs/agentplane/blob/main/docs/developer/project-layout.mdx
-- Recipes: https://github.com/basilisk-labs/agentplane/tree/main/agentplane-recipes
+- Overview: https://agentplane.org/docs/user/overview
+- Setup: https://agentplane.org/docs/user/setup
+- Workflow: https://agentplane.org/docs/user/workflow
+- Commands: https://agentplane.org/docs/user/commands
+- Backends: https://agentplane.org/docs/user/backends
+- CLI reference: https://agentplane.org/docs/user/cli-reference.generated
+- Release notes: https://agentplane.org/docs/releases
+- Recipes repository: https://github.com/basilisk-labs/agentplane/tree/main/agentplane-recipes
 
 ## Support
 

package/assets/AGENTS.md

@@ -17,7 +17,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`, then apply `## LOAD RULES` before any mutation.
+- 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.
 
 ---
 
@@ -83,7 +83,7 @@ node .agentplane/policy/check-routing.mjs
 ## TOOLING
 
 - Use `## COMMANDS` as the canonical command source.
-- Use `agentplane quickstart` as the canonical installed startup path and `agentplane role <ROLE>` for role-specific deltas.
+- Use `agentplane quickstart` as the canonical installed startup path and `agentplane role <ROLE>` to activate the current role before role-scoped planning or execution.
 - For policy changes, routing validation MUST pass via `node .agentplane/policy/check-routing.mjs`.
 
 ---
@@ -131,10 +131,12 @@ Routing constraints:
 - MUST create/reuse executable task IDs for any repo-state mutation.
 - MUST use `agentplane` commands for task lifecycle updates; MUST NOT manually edit `.agentplane/tasks.json`.
 - MUST run `agentplane task plan approve ...` and `agentplane task start-ready ...` sequentially (never in parallel).
+- MUST activate `agentplane role ORCHESTRATOR` for planning and `agentplane role <ROLE>` for the active task owner before owner-scoped execution or verification.
 - MUST keep repository artifacts in English by default (unless user explicitly requests another language for a specific artifact).
 - MUST NOT fabricate repository facts.
 - MUST stage/commit only intentional changes for the active task scope.
 - MUST stop and request re-approval when scope, risk, or verification criteria materially drift.
+- MUST NOT let ORCHESTRATOR perform owner-scoped implementation or verification once a task owner is known, unless the approved plan explicitly makes ORCHESTRATOR the owner.
 
 Role boundaries:
 

package/bin/dist-guard.js

@@ -1,7 +1,11 @@
 import { execFileSync } from "node:child_process";
 import path from "node:path";
 import { readFile, stat } from "node:fs/promises";
-import { collectWatchedRuntimeSnapshot, compareWatchedRuntimeSnapshots } from "./runtime-watch.js";
+import {
+  collectWatchedRuntimeSnapshot,
+  compareWatchedRuntimeSnapshots,
+  isRuntimeRelevantWatchedFile,
+} from "./runtime-watch.js";
 
 async function exists(p) {
   try {
@@ -63,14 +67,20 @@ function workingTreeChangedPaths(cwd, watchedPaths) {
         const normalized = String(line ?? "");
         return normalized.length > 3 ? normalized.slice(3).trim() : "";
       })
-      .filter(Boolean),
+      .filter((filePath) => Boolean(filePath) && isRuntimeRelevantWatchedFile(filePath)),
   );
 }
 
 function committedChangedPathsSince(cwd, fromGitHead, watchedPaths) {
   if (!fromGitHead) return [];
   return uniqueSorted(
-    listGitPaths(cwd, ["diff", "--name-only", `${fromGitHead}..HEAD`, "--", ...watchedPaths]),
+    listGitPaths(cwd, [
+      "diff",
+      "--name-only",
+      `${fromGitHead}..HEAD`,
+      "--",
+      ...watchedPaths,
+    ]).filter((filePath) => isRuntimeRelevantWatchedFile(filePath)),
   );
 }
 

package/bin/runtime-watch.d.ts

@@ -15,6 +15,7 @@ export type WatchedRuntimeSnapshotComparison = {
   changedPaths: string[];
 };
 
+export function isRuntimeRelevantWatchedFile(filePath: string): boolean;
 export function getWatchedRuntimePathsForPackage(packageName: string): string[];
 export function collectWatchedRuntimeSnapshot(
   packageDir: string,

package/bin/runtime-watch.js

@@ -17,6 +17,15 @@ function normalizePath(value) {
   return value.split(path.sep).join("/");
 }
 
+export function isRuntimeRelevantWatchedFile(filePath) {
+  const normalized = normalizePath(filePath);
+  const inSourceTree = normalized.startsWith("src/") || normalized.includes("/src/");
+  if (!inSourceTree) return true;
+  if (normalized.includes("/__snapshots__/")) return false;
+  const baseName = path.posix.basename(normalized);
+  return !/\.(?:test)\.[cm]?[jt]sx?$/u.test(baseName);
+}
+
 async function exists(targetPath) {
   try {
     await stat(targetPath);
@@ -76,9 +85,11 @@ export async function collectWatchedRuntimeSnapshot(packageDir, watchedPaths) {
   const uniqueAbsoluteFiles = [...new Set(absoluteFiles)].toSorted((a, b) => a.localeCompare(b));
   const files = [];
   for (const absolutePath of uniqueAbsoluteFiles) {
+    const relativePath = normalizePath(path.relative(packageDir, absolutePath));
+    if (!isRuntimeRelevantWatchedFile(relativePath)) continue;
     const content = await readFile(absolutePath);
     files.push({
-      path: normalizePath(path.relative(packageDir, absolutePath)),
+      path: relativePath,
       sha256: fileHash(content),
       size_bytes: content.byteLength,
     });
@@ -96,15 +107,21 @@ function snapshotFileMap(snapshot) {
 }
 
 export function compareWatchedRuntimeSnapshots(recordedSnapshot, currentSnapshot) {
+  const recordedFiles = recordedSnapshot.files.filter((file) =>
+    isRuntimeRelevantWatchedFile(file.path),
+  );
+  const currentFiles = currentSnapshot.files.filter((file) =>
+    isRuntimeRelevantWatchedFile(file.path),
+  );
   if (
-    recordedSnapshot.snapshotHash === currentSnapshot.snapshotHash &&
-    recordedSnapshot.files.length === currentSnapshot.files.length
+    snapshotHash(recordedFiles) === snapshotHash(currentFiles) &&
+    recordedFiles.length === currentFiles.length
   ) {
     return { ok: true, changedPaths: [] };
   }
 
-  const recordedMap = snapshotFileMap(recordedSnapshot);
-  const currentMap = snapshotFileMap(currentSnapshot);
+  const recordedMap = snapshotFileMap({ ...recordedSnapshot, files: recordedFiles });
+  const currentMap = snapshotFileMap({ ...currentSnapshot, files: currentFiles });
   const changedPaths = [...new Set([...recordedMap.keys(), ...currentMap.keys()])]
     .filter((filePath) => recordedMap.get(filePath) !== currentMap.get(filePath))
     .toSorted((a, b) => a.localeCompare(b));

package/bin/stale-dist-policy.js

@@ -21,13 +21,19 @@ function isConfigInspectionCommand(args) {
 }
 
 function isTaskInspectionCommand(args) {
-  return args[0] === "task" && ["list", "show", "verify-show"].includes(args[1] ?? "");
+  if (args[0] !== "task") return false;
+  if (["list", "show", "verify-show", "next", "search"].includes(args[1] ?? "")) return true;
+  return args[1] === "doc" && args[2] === "show";
 }
 
 function isRoleOrQuickstartCommand(args) {
   return args[0] === "quickstart" || args[0] === "role";
 }
 
+function isReadyInspectionCommand(args) {
+  return args[0] === "ready";
+}
+
 export function classifyStaleDistPolicy(argv = process.argv) {
   const args = normalizeArgs(argv);
   if (
@@ -36,7 +42,8 @@ export function classifyStaleDistPolicy(argv = process.argv) {
     isHelpOrVersionCommand(args) ||
     isRoleOrQuickstartCommand(args) ||
     isConfigInspectionCommand(args) ||
-    isTaskInspectionCommand(args)
+    isTaskInspectionCommand(args) ||
+    isReadyInspectionCommand(args)
   ) {
     return { mode: "warn_and_run", reason: "read_only_diagnostic" };
   }