agentplane 0.1.3 → 0.1.4

package/README.md

@@ -5,53 +5,83 @@
 [![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)
 
-Agent Plane is an offline-first CLI for running policy-driven agent workflows inside real repositories.
-It turns "AI magic" into a predictable process with approvals, role boundaries, and audit-friendly artifacts.
+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.
 
-## Features
+## Why Agent Plane
 
-- 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.
+- 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.
 
-## Install
+## 5-minute start
+
+Install and initialize the CLI:
 
 ```bash
 npm install -g agentplane
+agentplane init
+agentplane quickstart
 ```
 
-Or run without installing:
+Create your first task and run the workflow:
 
 ```bash
-npx agentplane --help
+agentplane task new --title "First task" --description "Describe the change" --priority med --owner ORCHESTRATOR --tag docs
+agentplane verify <task-id>
+agentplane finish <task-id>
 ```
 
-## Requirements
+Prefer `npx` instead of a global install?
 
-- Node.js >= 20
+```bash
+npx agentplane init
+npx agentplane quickstart
+```
 
-## Quickstart
+## What gets installed automatically
 
-Initialize a repository:
+- `.agentplane/` is created with config, tasks, agents, and caches.
+- `AGENTS.md` is created if missing and defines the policy/guardrails.
+- Built-in agent definitions are copied into `.agentplane/agents/`.
+- Optional recipes can install additional agents when you run `agentplane recipes install ...`.
 
-```bash
-npx agentplane init
+## Guardrails and artifacts
+
+- 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:
+
+```text
+Preflight -> Plan -> Approval -> Tasks -> Verify -> Finish -> Export
 ```
 
-See the built-in quickstart guide:
+## Features
+
+- 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.
+
+## Install
 
 ```bash
-npx agentplane quickstart
+npm install -g agentplane
 ```
 
-Switch workflow mode if you need a structured team flow:
+Or run without installing:
 
 ```bash
-npx agentplane config set workflow_mode branch_pr
+npx agentplane --help
 ```
 
+## Requirements
+
+- Node.js >= 20
+
 ## Common Commands
 
 ```bash
@@ -73,15 +103,6 @@ agentplane recipes list
 - 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
 
-## How it works
-
-Agent Plane expects a repository policy file (`AGENTS.md`) plus a project config (`.agentplane/config.json`).
-Together, they define role boundaries, approval gates, and the execution pipeline:
-
-```text
-Preflight -> Plan -> Approval -> Tasks -> Verify -> Finish -> Export
-```
-
 ## Support
 
 - Issues: https://github.com/basilisk-labs/agentplane/issues

package/dist/run-cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-cli.d.ts","sourceRoot":"","sources":["../src/run-cli.ts"],"names":[],"mappings":"AAo8QA,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA4/D5D"}
+{"version":3,"file":"run-cli.d.ts","sourceRoot":"","sources":["../src/run-cli.ts"],"names":[],"mappings":"AA69QA,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA4/D5D"}

package/dist/run-cli.js

@@ -437,7 +437,7 @@ const BRANCH_STATUS_USAGE_EXAMPLE = "agentplane branch status --base main";
 const BRANCH_REMOVE_USAGE = "Usage: agentplane branch remove [--branch <name>] [--worktree <path>] [--force] [--quiet]";
 const BRANCH_REMOVE_USAGE_EXAMPLE = "agentplane branch remove --branch task/20260203-F1Q8AB --worktree .agentplane/worktrees/task";
 const UPGRADE_USAGE = "Usage: agentplane upgrade [--tag <tag>] [--dry-run] [--no-backup] [--source <repo-url>] [--bundle <path|url>] [--checksum <path|url>]";
-const UPGRADE_USAGE_EXAMPLE = "agentplane upgrade --tag v0.1.3 --dry-run";
+const UPGRADE_USAGE_EXAMPLE = "agentplane upgrade --tag v0.1.4 --dry-run";
 const INIT_USAGE = "Usage: agentplane init --ide <...> --workflow <...> --hooks <...> --require-plan-approval <...> --require-network-approval <...> [--recipes <...>] [--yes] [--force|--backup]";
 const INIT_USAGE_EXAMPLE = "agentplane init --ide codex --workflow direct --hooks false --require-plan-approval true --require-network-approval true --yes";
 const CONFIG_SET_USAGE = "Usage: agentplane config set <key> <value>";
@@ -3016,7 +3016,7 @@ async function cmdTaskNew(opts) {
             comments: [],
             doc_version: 2,
             doc_updated_at: nowIso(),
-            doc_updated_by: "agentplane",
+            doc_updated_by: flags.owner,
             id_source: "generated",
         };
         if (requiresVerify(flags.tags, config.tasks.verify.required_tags) &&
@@ -3149,6 +3149,7 @@ async function cmdTaskAdd(opts) {
         const tags = dedupeStrings(flags.tags);
         const dependsOn = dedupeStrings(flags.dependsOn);
         const verify = dedupeStrings(flags.verify);
+        const docUpdatedBy = (flags.commentAuthor ?? "").trim() || flags.owner;
         if (requiresVerify(tags, config.tasks.verify.required_tags) && verify.length === 0) {
             throw new CliError({
                 exitCode: 2,
@@ -3171,7 +3172,7 @@ async function cmdTaskAdd(opts) {
                 : [],
             doc_version: 2,
             doc_updated_at: nowIso(),
-            doc_updated_by: "agentplane",
+            doc_updated_by: docUpdatedBy,
             id_source: "explicit",
         }));
         if (backend.writeTasks) {
@@ -3844,10 +3845,15 @@ async function cmdTaskScaffold(opts) {
                 comments: [],
                 doc_version: 2,
                 doc_updated_at: nowIso(),
-                doc_updated_by: "agentplane",
+                doc_updated_by: "UNKNOWN",
             };
         if (flags.title)
             baseTask.title = flags.title;
+        if (typeof baseTask.doc_updated_by !== "string" ||
+            baseTask.doc_updated_by.trim().length === 0 ||
+            baseTask.doc_updated_by.trim().toLowerCase() === "agentplane") {
+            baseTask.doc_updated_by = baseTask.owner?.trim() ? baseTask.owner : "UNKNOWN";
+        }
         const frontmatter = taskDataToFrontmatter(baseTask);
         const body = ensureDocSections("", config.tasks.doc.required_sections);
         const text = renderTaskReadme(frontmatter, body);
@@ -3983,7 +3989,7 @@ async function cmdTaskComment(opts) {
             comments: [...existing, { author: opts.author, body: opts.body }],
             doc_version: 2,
             doc_updated_at: nowIso(),
-            doc_updated_by: "agentplane",
+            doc_updated_by: opts.author,
         };
         await backend.writeTask(next);
         process.stdout.write(`${successMessage("commented", opts.taskId)}\n`);
@@ -4086,7 +4092,7 @@ async function cmdTaskSetStatus(opts) {
             comments,
             doc_version: 2,
             doc_updated_at: nowIso(),
-            doc_updated_by: "agentplane",
+            doc_updated_by: resolveDocUpdatedBy(task, opts.author),
         };
         if (opts.commit) {
             const commitInfo = await readCommitInfo(resolved.gitRoot, opts.commit);
@@ -5365,7 +5371,7 @@ async function cmdStart(opts) {
             comments: commentsValue,
             doc_version: 2,
             doc_updated_at: nowIso(),
-            doc_updated_by: "agentplane",
+            doc_updated_by: opts.author,
         };
         await backend.writeTask(nextTask);
         let commitInfo = null;
@@ -5441,7 +5447,7 @@ async function cmdBlock(opts) {
             comments: commentsValue,
             doc_version: 2,
             doc_updated_at: nowIso(),
-            doc_updated_by: "agentplane",
+            doc_updated_by: opts.author,
         };
         await backend.writeTask(nextTask);
         let commitInfo = null;
@@ -5542,7 +5548,7 @@ async function cmdFinish(opts) {
                 comments: commentsValue,
                 doc_version: 2,
                 doc_updated_at: nowIso(),
-                doc_updated_by: "agentplane",
+                doc_updated_by: opts.author,
             };
             await backend.writeTask(nextTask);
         }
@@ -7071,6 +7077,23 @@ function setMarkdownSection(body, section, text) {
 function normalizeDocSectionName(section) {
     return section.trim().replaceAll(/\s+/g, " ").toLowerCase();
 }
+function normalizeDocUpdatedBy(value) {
+    const trimmed = value?.trim() ?? "";
+    if (!trimmed)
+        return "";
+    if (trimmed.toLowerCase() === "agentplane")
+        return "";
+    return trimmed;
+}
+function resolveDocUpdatedBy(task, author) {
+    const fromAuthor = normalizeDocUpdatedBy(author);
+    if (fromAuthor)
+        return fromAuthor;
+    const fromTask = normalizeDocUpdatedBy(typeof task.doc_updated_by === "string" ? task.doc_updated_by : undefined);
+    if (fromTask)
+        return fromTask;
+    return normalizeDocUpdatedBy(typeof task.owner === "string" ? task.owner : undefined);
+}
 function splitCombinedHeadingLines(doc) {
     const lines = doc.replaceAll("\r\n", "\n").split("\n");
     const out = [];

package/dist/task-backend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"task-backend.d.ts","sourceRoot":"","sources":["../src/task-backend.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"task-backend.d.ts","sourceRoot":"","sources":["../src/task-backend.ts"],"names":[],"mappings":"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"}

package/dist/task-backend.js

@@ -42,13 +42,158 @@ function normalizeDoc(text) {
         .join("\n")
         .trim();
 }
+function normalizeDocSectionName(section) {
+    return section.trim().replaceAll(/\s+/g, " ").toLowerCase();
+}
+function normalizeSectionLines(lines) {
+    const trimmedLines = [...lines];
+    while (trimmedLines.length > 0 && trimmedLines[0]?.trim() === "")
+        trimmedLines.shift();
+    while (trimmedLines.length > 0 && trimmedLines.at(-1)?.trim() === "")
+        trimmedLines.pop();
+    const out = [];
+    let inFence = false;
+    let pendingBlank = false;
+    for (const line of trimmedLines) {
+        const fenceCheck = line.trimStart();
+        if (fenceCheck.startsWith("```")) {
+            if (pendingBlank) {
+                out.push("");
+                pendingBlank = false;
+            }
+            out.push(line);
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence) {
+            out.push(line);
+            continue;
+        }
+        if (line.trim() === "") {
+            pendingBlank = true;
+            continue;
+        }
+        if (pendingBlank) {
+            out.push("");
+            pendingBlank = false;
+        }
+        out.push(line);
+    }
+    return out;
+}
+function splitCombinedHeadingLines(doc) {
+    const lines = doc.replaceAll("\r\n", "\n").split("\n");
+    const out = [];
+    let inFence = false;
+    for (const line of lines) {
+        const trimmed = line.trimStart();
+        if (trimmed.startsWith("```")) {
+            inFence = !inFence;
+            out.push(line);
+            continue;
+        }
+        if (!inFence && line.includes("## ")) {
+            const matches = [...line.matchAll(/##\s+/g)];
+            if (matches.length > 1 && matches[0]?.index === 0) {
+                let start = 0;
+                for (let i = 1; i < matches.length; i += 1) {
+                    const idx = matches[i]?.index ?? 0;
+                    const chunk = line.slice(start, idx).trimEnd();
+                    if (chunk)
+                        out.push(chunk);
+                    start = idx;
+                }
+                const last = line.slice(start).trimEnd();
+                if (last)
+                    out.push(last);
+                continue;
+            }
+        }
+        out.push(line);
+    }
+    return out;
+}
+function normalizeTaskDoc(doc) {
+    const normalized = doc.replaceAll("\r\n", "\n");
+    const trimmed = normalized.replaceAll(/^\n+|\n+$/g, "");
+    if (!trimmed)
+        return "";
+    const lines = splitCombinedHeadingLines(trimmed);
+    const sections = new Map();
+    const order = [];
+    const pendingSeparator = new Set();
+    let currentKey = null;
+    for (const line of lines) {
+        const match = /^##\s+(.*)$/.exec(line.trim());
+        if (match) {
+            const title = match[1]?.trim() ?? "";
+            const key = normalizeDocSectionName(title);
+            if (key) {
+                const existing = sections.get(key);
+                if (existing) {
+                    if (existing.lines.some((entry) => entry.trim() !== "")) {
+                        pendingSeparator.add(key);
+                    }
+                }
+                else {
+                    sections.set(key, { title, lines: [] });
+                    order.push(key);
+                }
+                currentKey = key;
+                continue;
+            }
+        }
+        if (currentKey) {
+            const entry = sections.get(currentKey);
+            if (!entry)
+                continue;
+            if (pendingSeparator.has(currentKey) && line.trim() !== "") {
+                entry.lines.push("");
+                pendingSeparator.delete(currentKey);
+            }
+            entry.lines.push(line);
+        }
+    }
+    if (order.length === 0)
+        return trimmed;
+    const out = [];
+    for (const key of order) {
+        const section = sections.get(key);
+        if (!section)
+            continue;
+        const normalizedLines = normalizeSectionLines(section.lines);
+        if (normalizedLines.length > 0) {
+            out.push(`## ${section.title}`, "", ...normalizedLines, "");
+        }
+        else {
+            out.push(`## ${section.title}`, "", "");
+        }
+    }
+    return out.join("\n").trimEnd();
+}
 function docChanged(existing, updated) {
     return normalizeDoc(existing) !== normalizeDoc(updated);
 }
+function normalizeUpdatedBy(value) {
+    if (typeof value !== "string")
+        return "";
+    const trimmed = value.trim();
+    if (!trimmed)
+        return "";
+    if (trimmed.toLowerCase() === DEFAULT_DOC_UPDATED_BY.toLowerCase())
+        return "";
+    return trimmed;
+}
 function ensureDocMetadata(task, updatedBy) {
     task.doc_version = DOC_VERSION;
     task.doc_updated_at = nowIso();
-    task.doc_updated_by = updatedBy ?? DEFAULT_DOC_UPDATED_BY;
+    const explicit = normalizeUpdatedBy(updatedBy);
+    if (updatedBy !== undefined) {
+        task.doc_updated_by =
+            explicit || resolveDocUpdatedByFromTask(task, DEFAULT_DOC_UPDATED_BY);
+        return;
+    }
+    task.doc_updated_by = resolveDocUpdatedByFromTask(task, DEFAULT_DOC_UPDATED_BY);
 }
 function lastCommentAuthor(comments) {
     if (!Array.isArray(comments))
@@ -69,31 +214,34 @@ function lastCommentAuthor(comments) {
 }
 function resolveDocUpdatedByFromFrontmatter(frontmatter, updatedBy, fallback) {
     if (updatedBy !== undefined) {
-        const trimmed = updatedBy.trim();
-        return trimmed.length > 0 ? trimmed : fallback;
+        const explicit = normalizeUpdatedBy(updatedBy);
+        if (explicit)
+            return explicit;
     }
     const author = lastCommentAuthor(frontmatter.comments);
     if (author)
         return author;
-    const existing = frontmatter.doc_updated_by;
-    if (typeof existing === "string") {
-        const trimmed = existing.trim();
-        if (trimmed)
-            return trimmed;
-    }
-    return fallback;
+    const existing = normalizeUpdatedBy(frontmatter.doc_updated_by);
+    if (existing)
+        return existing;
+    const owner = normalizeUpdatedBy(frontmatter.owner);
+    if (owner)
+        return owner;
+    const fallbackValue = normalizeUpdatedBy(fallback);
+    return fallbackValue || fallback;
 }
 function resolveDocUpdatedByFromTask(task, fallback) {
     const author = lastCommentAuthor(task.comments);
     if (author)
         return author;
-    const existing = task.doc_updated_by;
-    if (typeof existing === "string") {
-        const trimmed = existing.trim();
-        if (trimmed)
-            return trimmed;
-    }
-    return fallback;
+    const existing = normalizeUpdatedBy(task.doc_updated_by);
+    if (existing)
+        return existing;
+    const owner = normalizeUpdatedBy(task.owner);
+    if (owner)
+        return owner;
+    const fallbackValue = normalizeUpdatedBy(fallback);
+    return fallbackValue || fallback;
 }
 function isDocSectionHeader(line) {
     return DOC_SECTION_HEADER_RE.test(line.trim());
@@ -121,10 +269,11 @@ export function extractTaskDoc(body) {
             break;
         }
     }
-    return lines.slice(startIdx, endIdx).join("\n").trimEnd();
+    const doc = lines.slice(startIdx, endIdx).join("\n").trimEnd();
+    return normalizeTaskDoc(doc);
 }
 export function mergeTaskDoc(body, doc) {
-    const docText = String(doc ?? "").replaceAll(/^\n+|\n+$/g, "");
+    const docText = normalizeTaskDoc(String(doc ?? ""));
     if (docText) {
         const lines = body ? body.split("\n") : [];
         let prefixIdx = null;
@@ -263,7 +412,7 @@ function taskDataToExport(task) {
             : [],
         doc_version: task.doc_version ?? DOC_VERSION,
         doc_updated_at: task.doc_updated_at ?? "",
-        doc_updated_by: task.doc_updated_by ?? DEFAULT_DOC_UPDATED_BY,
+        doc_updated_by: resolveDocUpdatedByFromTask(task, DEFAULT_DOC_UPDATED_BY),
         dirty: Boolean(task.dirty),
         id_source: task.id_source ?? "generated",
     };
@@ -445,7 +594,7 @@ export class LocalBackend {
             payload.doc_updated_at = nowIso();
         }
         if (payload.doc_updated_by === undefined || payload.doc_updated_by === "") {
-            payload.doc_updated_by = this.updatedBy;
+            payload.doc_updated_by = resolveDocUpdatedByFromTask(task, this.updatedBy);
         }
         await mkdir(path.dirname(readme), { recursive: true });
         const text = renderTaskReadme(payload, body || "");

package/dist/version.js

@@ -1,3 +1,3 @@
 export function getVersion() {
-    return "0.1.3";
+    return "0.1.4";
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentplane",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Agent Plane CLI for task workflows, recipes, and project automation.",
   "keywords": [
     "agentplane",
@@ -54,6 +54,6 @@
     "prepublishOnly": "npm run prepack"
   },
   "dependencies": {
-    "@agentplaneorg/core": "0.1.3"
+    "@agentplaneorg/core": "0.1.4"
   }
 }