agentpack-cli 0.1.7 → 0.1.9

package/docs/ROADMAP.md

@@ -2,9 +2,12 @@
 
 ## North Star
 
-Agentpack is a local task-state layer for AI coding agents. It captures useful working context that usually gets lost in long sessions, restarts, and compaction: decisions, dead ends, inspected sources, evidence, checkpoints, and budgeted resumes.
+Agentpack makes agent continuity native to the repo.
 
-Agentpack is not an orchestrator or a broad automatic memory engine. It is the portable context ledger for humans, single agents, and agent teams working on a repo.
+It is a neutral task passport for agentic workspaces: a compact, portable record of decisions, source conclusions, evidence, dead ends, checkpoints, and next actions that survives chat compaction, client switches, worktree handoffs, machines, branches, and orchestrators.
+
+See [VISION.md](VISION.md) for the fuller strategic framing.
+See [TASK-PASSPORT.md](TASK-PASSPORT.md) for the target Task Passport schema and state transitions.
 
 ## Product Principles
 
@@ -22,24 +25,28 @@ Agentpack is not an orchestrator or a broad automatic memory engine. It is the p
 
 ## State Model
 
-Agentpack has four layers:
+Agentpack has five layers:
 
 1. Tool install: the `agentpack` binary is installed once on a developer machine.
 2. Repo init: each repo gets its own local `.agentpack/` directory.
 3. Repo source cache: inspected source conclusions and file hashes can be reused across tasks in the same repo.
-4. Task ledger: goal, status, decisions, dead ends, evidence, checkpoints, and exports belong to a workstream, not to a chat.
+4. Task Passport: objective, constraints, write scope, status, decisions, dead ends, evidence, verification, checkpoints, and next actions belong to one coherent unit of work.
+5. Role lanes: Scout, Builder, Reviewer, and Archivist can contribute to the current passport without creating separate tasks.
 
 Agent sessions and web chats are transport surfaces. They should be able to resume, write, and hand off a task, but they are not first-class Agentpack state.
 
-Sharing ledger state across machines or teammates is intentionally post-local-stability work. Prefer explicit sanitized export/import bundles before considering committed or synced shared state.
+One active Task Passport owns the work in a repo worktree by default. Multiple passports can exist as closed history, parked work, or separate worktree handoffs, but Agentpack should not become a backlog manager or a code-conflict resolver.
+
+Sharing passport state across machines or teammates is intentionally post-local-stability work. Prefer explicit sanitized export/import bundles before considering committed or synced shared state.
 
 Target task UX:
 
 ```bash
 agentpack init
-agentpack task start "Claude Desktop MCP install"
+agentpack task start "Claude Desktop MCP install" --write-scope src/integrations/install.ts --write-scope docs/INTEGRATIONS.md
 agentpack task list
 agentpack task switch claude-desktop-mcp-install
+agentpack task passport
 agentpack resume --preset agent
 agentpack checkpoint -m "Desktop config tested"
 agentpack task close
@@ -54,14 +61,38 @@ Target file shape:
   tasks/
     current
     claude-desktop-mcp-install/
-      state.json
+      passport.json
       events.jsonl
       checkpoints/
       evidence/
       exports/
 ```
 
-This keeps source knowledge reusable across a repo while preventing unrelated feature work from mixing decisions, dead ends, and next actions.
+This keeps source knowledge reusable across a repo while preventing unrelated work from mixing decisions, dead ends, and next actions. If another open passport claims overlapping write scope, Agentpack should warn and point the user toward reusing the current passport, parking one task, or moving work into a separate worktree.
+
+Target consistency checks:
+
+- current passport branch/head/worktree are visible in context
+- source conclusions are validated by file hash
+- write-scope overlap is detected before new work starts
+- role lanes are advisory and scoped; Scout/Reviewer are read-oriented, Builder claims writes, Archivist records durable handoff state
+- checkpoints remain append-only snapshots for recovery and handoff
+
+## Dogfood Success Metrics
+
+Agentpack should prove itself first in this repo. Measure whether it reduces repeated work and handoff friction while keeping the ledger compact.
+
+Useful signals:
+
+- resume usefulness: a fresh agent can explain the current task, constraints, relevant files, risks, and next action after `load_context` or `resume`
+- re-read avoidance: unchanged source conclusions let agents skip re-opening files unless the task requires fresh inspection
+- dead-end avoidance: recorded failed approaches are not repeated in later sessions
+- handoff time: a new agent can continue meaningful work within a few minutes after context load
+- verification quality: important changes have evidence, test output, or explicit reasoning attached before checkpoint
+- ledger health: `agentpack doctor` reports zero changed or missing source records before release-like handoff
+- overhead: recording useful state stays lightweight enough that it does not interrupt normal coding flow
+
+The target is reliable continuation of the work that was worth preserving.
 
 ## v0.1: Usable Manual CLI
 
@@ -115,7 +146,10 @@ Demo story:
 - Stable `.agentpack/` schema.
 - Stable CLI.
 - Stable MCP tools.
-- Task/workstream separation.
+- Task Passport schema and one-current-passport workflow.
+- Workstream separation for parked work, history, and worktree handoffs.
+- Lightweight role lanes for Scout, Builder, Reviewer, and Archivist.
+- Write-scope and stale-state warnings.
 - Security model documented.
 - npm publish as `agentpack-cli`.
 - Good demo and examples.

package/docs/TASK-PASSPORT.md

@@ -0,0 +1,227 @@
+# Task Passport
+
+Task Passport is the handoff artifact for one coherent unit of agentic work.
+
+It captures the reviewed state a future agent needs in order to continue the current task without rediscovering context, repeating dead ends, or guessing what is safe to touch.
+
+## Model
+
+Default rule:
+
+- one active Task Passport owns a repo worktree
+- a repo may keep many completed or parked passports over time
+- worktrees can carry different active passports
+- the shared repo source cache remains repo-level
+- decisions, dead ends, evidence, checkpoints, and next actions become passport-scoped
+
+This keeps source knowledge reusable while preventing unrelated work from mixing task state.
+
+## File Shape
+
+Target local layout:
+
+```text
+.agentpack/
+  config.json
+  sources.json
+  tasks/
+    current
+    task_20260518_source_cleanup/
+      passport.json
+      events.jsonl
+      checkpoints/
+      evidence/
+      exports/
+```
+
+`tasks/current` is a small pointer to the active task id for this worktree. If it is missing, Agentpack can fall back to the current v0 repo-level state.
+
+## Passport Schema
+
+`passport.json` should be compact, readable, and safe to inspect manually.
+
+```json
+{
+  "schemaVersion": 1,
+  "id": "task_20260518_source_cleanup",
+  "title": "Add source cache cleanup commands",
+  "status": "active",
+  "createdAt": "2026-05-18T11:00:00.000Z",
+  "updatedAt": "2026-05-18T11:30:00.000Z",
+  "closedAt": null,
+  "objective": "Let Agentpack remove stale source records safely.",
+  "constraints": [
+    "Preserve existing source add/status behavior",
+    "Do not delete source records broadly without an explicit guard"
+  ],
+  "branch": "main",
+  "baseHead": "8d22011",
+  "currentHead": "21fe674",
+  "worktree": "/path/to/repo",
+  "writeScope": [
+    "src/operations.ts",
+    "src/cli/index.ts",
+    "tests/agentpack.test.ts",
+    "docs/CLI.md"
+  ],
+  "risk": "low",
+  "roles": {
+    "scout": {
+      "status": "done",
+      "summary": "Inspected source add/status flow and tests."
+    },
+    "builder": {
+      "status": "done",
+      "summary": "Implemented remove/prune commands inside declared write scope."
+    },
+    "reviewer": {
+      "status": "done",
+      "summary": "Verified tests, doctor, and dogfood cleanup."
+    },
+    "archivist": {
+      "status": "done",
+      "summary": "Recorded source conclusions, evidence, and checkpoint."
+    }
+  },
+  "verification": {
+    "status": "passed",
+    "evidence": [
+      "evt_example_test_output"
+    ],
+    "summary": "npm test passed; doctor clean after source cache refresh."
+  },
+  "nextActions": [
+    "Design Task Passport schema and state transitions"
+  ],
+  "tags": [
+    "source-cache",
+    "trust-foundation"
+  ]
+}
+```
+
+Required fields for v1:
+
+- `schemaVersion`
+- `id`
+- `title`
+- `status`
+- `createdAt`
+- `updatedAt`
+- `objective`
+- `branch`
+- `baseHead`
+- `worktree`
+- `writeScope`
+- `nextActions`
+
+Optional but recommended:
+
+- `constraints`
+- `currentHead`
+- `risk`
+- `roles`
+- `verification`
+- `tags`
+- `closedAt`
+
+## Statuses
+
+Initial statuses:
+
+- `active`: current work is in progress in this worktree
+- `parked`: intentionally paused and not the current task
+- `blocked`: waiting on user input, external dependency, or unresolved risk
+- `verifying`: implementation is done, but evidence/review is not complete
+- `completed`: task finished with verification or explicit acceptance
+- `abandoned`: task stopped and should not be resumed without a new decision
+
+Default context should show the active passport in full, and show parked or blocked passports only as compact references unless explicitly requested.
+
+## State Transitions
+
+Allowed transitions:
+
+```text
+none -> active              task start
+active -> parked            task park
+parked -> active            task switch/resume
+active -> blocked           task block
+blocked -> active           task unblock/resume
+active -> verifying         task verify
+verifying -> active         verification found more work
+verifying -> completed      verification passed
+active -> completed         small/docs task accepted directly
+active -> abandoned         task abandon
+parked -> abandoned         stale parked task is discarded
+blocked -> abandoned        blocked task is discarded
+```
+
+Closed statuses are `completed` and `abandoned`. Closed passports remain inspectable history but should not appear in the default resume unless they are query-relevant.
+
+## CLI Shape
+
+Target first CLI surface:
+
+```bash
+agentpack task start "Add source cache cleanup commands" \
+  --objective "Let Agentpack remove stale source records safely" \
+  --write-scope src/operations.ts \
+  --write-scope src/cli/index.ts
+
+agentpack task list
+agentpack task passport
+agentpack task switch task_20260518_source_cleanup
+agentpack task audit
+agentpack task park
+agentpack task block --reason "Waiting for API decision"
+agentpack task verify
+agentpack task close
+```
+
+`resume` and MCP `load_context` read the current passport automatically when one exists, then show the broader repo-level ledger below it.
+
+`task audit` is a diagnostic pass for continuity risk. It checks the current passport for branch/head drift, missing next actions, open verification, stale source conclusions, and closed-current-task anomalies.
+
+## Role Lanes
+
+Roles are coordination lanes inside one passport, not separate tasks.
+
+- Scout: read-oriented; records source conclusions, risks, and known unknowns
+- Builder: write-oriented; works inside the declared write scope
+- Reviewer: read-oriented; checks diff, tests, risks, and regression surface
+- Archivist: state-oriented; records evidence, checkpoints, and handoff notes
+
+For v1, roles should be metadata and prompts, not a multi-agent runtime. Orchestrators can later map their own workers onto these lanes.
+
+## Consistency Rules
+
+Agentpack should warn before work continues when:
+
+- the current git branch does not match the passport branch
+- the current git head moved since the last passport update
+- the current worktree path does not match the passport worktree
+- a source conclusion in the current context is changed or missing
+- a new active passport would overlap another open passport's write scope
+- a Builder role attempts changes outside the declared write scope
+- a task is marked completed without evidence or an explicit acceptance note
+
+Agentpack should not try to resolve code conflicts. It should point the user toward one of three safe paths:
+
+- reuse the current passport
+- park one task before starting another
+- move parallel work into a separate worktree
+
+## Migration
+
+Existing v0 packs should remain valid.
+
+When task support is introduced, Agentpack can create an initial passport from the current repo-level state:
+
+- `goal` becomes `objective`
+- `currentStatus` becomes a summary or active status note
+- `nextActions` copy into the passport
+- existing events remain readable as legacy repo-level events
+- `sources.json` stays repo-level
+
+This avoids breaking existing users while moving new work into passport-scoped ledgers.

package/docs/VISION.md

@@ -0,0 +1,64 @@
+# Vision
+
+## Strategic North Star
+
+Agentpack makes agent continuity native to the repo.
+
+It is a neutral task passport for agentic workspaces: a compact, portable record of decisions, source conclusions, evidence, dead ends, checkpoints, and next actions that survives chat compaction, client switches, worktree handoffs, machines, branches, and orchestrators.
+
+## Product Bet
+
+As agent UIs evolve from chat boxes into execution workspaces, handoffs will become common: chat to worktree, IDE to background agent, local repo to cloud sandbox, Claude to Codex, Cursor to CI.
+
+Branches and transcripts are not enough. Agents need reviewed task state that is portable, inspectable, and client-neutral.
+
+Codex, Claude Code, Cursor, LangGraph, Temporal, OpenAI Agents SDK, and similar systems can own execution loops, retries, approvals, tool calls, and durable runs. Agentpack should own the neutral repo-scoped continuity layer that those surfaces can share.
+
+## What Agentpack Should Own
+
+- repo-native continuity
+- task passports as the handoff artifact
+- semantic checkpoints
+- source-inspection cache
+- dead-end memory
+- evidence-linked handoffs
+- MCP-first access
+- portable bundles between worktrees, machines, and clients
+- orchestrator recipes later
+
+## Task Passport Model
+
+A Task Passport is the handoff artifact for one coherent unit of agentic work. It should capture the objective, constraints, write scope, relevant source conclusions, decisions, dead ends, evidence, verification state, checkpoints, and next actions.
+
+See [TASK-PASSPORT.md](TASK-PASSPORT.md) for the target schema and state transitions.
+
+One active Task Passport should own the work in a repo worktree by default. A repo can keep many closed or parked passports over time, but Agentpack should not turn one working directory into a backlog or a multi-task merge engine.
+
+Workstreams are how passports stay separated across repo work, branches, and worktrees. They are for history, parked work, and handoff boundaries, not a substitute for issue tracking or code conflict resolution.
+
+Multi-role agents should collaborate inside one Task Passport:
+
+- Scout: inspect sources and record source conclusions
+- Builder: make changes inside the declared write scope
+- Reviewer: check the diff, risks, and verification
+- Archivist: record evidence, checkpoints, and handoff state
+
+Agentpack should support those role lanes as lightweight prompts, metadata, and consistency checks before it attempts any heavier orchestration.
+
+## Operating Principles
+
+- Git stores code state. Agentpack stores reviewed task state.
+- Execution engines run the work. Agentpack preserves what future agents need to continue it.
+- Continuity should be native to the repo, not reconstructed from chat history.
+- One Task Passport owns the current work; multiple roles can contribute to it.
+- Prefer small, inspectable, local files before hosted sync or hidden databases.
+- Prefer portable MCP, CLI, and file surfaces over framework lock-in.
+- Record durable context, not every action.
+
+## Scope Boundaries
+
+- Keep the core artifact focused on reviewed task state.
+- Keep backlog, issue tracking, and code merge conflict resolution in the tools that already own them.
+- Keep execution loops, retries, approvals, tool calls, and durable runs in execution engines.
+- Keep the core workflow local-first; hosted sync can remain optional future work.
+- Keep deterministic file, hash, and source summaries as the default before adding embeddings or network calls.