| name | projects |
| description | Project context management. PROACTIVE — use when the user references a project (by name or as "this repo", "current work"), asks to add/update/complete a project, says "store under a named project", "track this", "what am I working on", "my projects", "my priorities". Also triggered by ISC/ISA terminology — ISC stands for Ideal State Criteria, a project's verifiable done-conditions stored as `ISC-N:` lines in the Criteria section of its ISA.md spec. Phrases like "ISC", "open/opening the ISC", "open ISCs" (unfinished criteria), "create/creating a ticket for a project", "new ticket", or "project ticket" all map here: use `list-isc` to read them, `add-isc` to create one, `complete-isc`/`reopen-isc` to change status. |
| argument-hint | ["list | create | resume | add-next | add-blocker | add-decision | add-handoff | update-section | criteria | isa-init | complete | archive | pause"] |
Manage the user's project registry. Each project lives at ~/.pal/memory/projects/{slug}/ISA.md. Frontmatter holds operational state (next steps, blockers, handoff); the body holds ISA spec sections (Problem, Goal, Criteria, Context, Decisions, etc.). The Stop hook auto-touches updated whenever the cwd resolves into a registered project — just being in the project keeps it warm.
CLI
All operations go through the canonical CLI:
bun ~/.pal/tools/project.ts <command> [args]
Output is JSON.
| Command | Purpose |
|---|
list | All registered projects with status, path, updated, stale flag, and counts |
create [name] [--path PATH] [--objectives "a;b;c"] | Register a project. Defaults: name=basename(cwd), path=cwd. Slug must be [a-z0-9_-]+ |
resume <name> | Print the full project ISA — all frontmatter and body sections |
add-next <name> "text" | Append a next step (array, instantly appendable) |
add-blocker <name> "text" | Append a blocker (array, instantly appendable) |
add-decision <name> "decision" "rationale" | Log a timestamped decision entry to the Decisions section |
add-handoff <name> "text" | Overwrite the handoff field (single-value, replaces) |
rm-next | rm-blocker <name> <index> | Remove a next/blocker entry by zero-based index |
update-section <name> <section> "content" | Set an ISA body section (problem, goal, criteria, vision, constraints, out_of_scope, context, decisions, changelog) |
criteria <name> | Print the Criteria section (verifiable success conditions) |
isa-init <name> | Mark a project as ISA-initialized |
complete <name> / archive <name> / pause <name> / unpause <name> | Status transitions |
rm <name> | Delete the project directory entirely |
ISA Sections
The body of each ISA.md holds spec sections. Use update-section to set them:
| Section | Key | What goes here |
|---|
| Problem | problem | Why this project exists; the pain or gap being addressed |
| Goal | goal | What success looks like (may be bullet list) |
| Criteria | criteria | Open ISCs (Ideal State Criteria) — testable done conditions. Holds only the open set; completing an ISC moves it to the Changelog |
| Vision | vision | Long-horizon aspiration beyond the immediate goal |
| Constraints | constraints | Non-negotiable limits (budget, time, tech, compatibility) |
| Out of Scope | out_of_scope | What this project explicitly does NOT cover |
| Context | context | Stable facts / references (e.g. "reference impl lives at ~/pai") |
| Decisions | decisions | Auto-managed by add-decision; dated bullet list |
| Changelog | changelog | Archive of completed ISCs (complete-isc moves them here under a dated ### Archived heading) plus any milestone notes |
ISC archive model. complete-isc does not just check a box — it moves the ISC line out of Criteria and into the Changelog archive, so Criteria always reflects exactly the open work and never bloats the context loaded at session start. list-isc <name> shows open ISCs by default; pass --closed (archived only) or --all (open + archived) to read finished ones. reopen-isc pulls an archived ISC back into the open set. prune-isc <name> backfills legacy projects by sweeping any done ISCs still sitting in Criteria into the archive in one pass.
Routing
| Intent | Action |
|---|
| "what am I working on", "my projects", "priorities" | list — summarize active and recently-touched projects |
| "tell me about " | resume <name> — present current state, highlight blockers and next steps |
| "register this" / "track this" / cwd is unregistered work | create (default the name from cwd basename, confirm before writing) |
| "store under : X" / "note on : X" | Pick the field — durable reference → update-section <slug> context "...", work item → add-next, obstacle → add-blocker. If unclear, ask. |
| "we decided X because Y" | add-decision <name> "X" "Y" |
| "handoff for " / "next session pick up at X" | add-handoff <name> "<text>" |
| "set the goal for " / "describe the problem" | update-section <name> goal "..." or update-section <name> problem "..." |
| "what are the criteria for " / "what counts as done" | criteria <name> |
| "mark X complete" / "X is done" | complete <name> |
| "park " / "pause " | pause <name> |
| "archive " | archive <name> |
Proactive registration
When SessionStart context flags the current cwd as unregistered (e.g. 💡 cwd <path> is not yet registered; suggest registering if substantive work begins) and the user starts substantive work (not just "hi"), surface the suggestion conversationally before the second tool call:
"I see we're in <basename> and it's not registered yet — want me to add it as a project?"
- Default name = the FULL last path segment of cwd, lowercased. For
/repos/portable-agent-layer → portable-agent-layer. Never split on -.
- Confirm before creating. Never auto-create without explicit user approval ("yes", "do it", "register").
- Capture context in conversation. If the user accepts but doesn't volunteer a goal, ask one short question, or infer from the last few messages and confirm.
When NOT to suggest registration
- cwd has no project marker (
.git, package.json, pyproject.toml, Cargo.toml, go.mod, etc.) — it's a notes folder, not a project.
- The user is clearly browsing or doing a one-off task.
- An ancestor of multiple registered projects is the cwd (e.g. a generic dev root) — that's browse mode by design.
- You're unsure. Err toward not registering.
Append-as-you-go
When the user describes next steps, blockers, or decisions during normal work, invoke the relevant subcommand to keep state current — that's the dynamism this system is built for. Don't invoke for fleeting comments, hypotheticals, or things the user is just thinking through. Wait for a clear declarative ("let's add X", "Z is blocking us"), not a question or musing.
Examples
Storing a reference under an existing project
User: "store under <project> that a reference implementation exists in this repo"
→ Identify the project from `list` (or by name)
→ Durable reference, not a task → update-section
→ bun ~/.pal/tools/project.ts update-section <slug> context "Reference implementation lives in this repo"
Registering the current repo
User: "track this project"
→ Default name from cwd basename, confirm with user
→ bun ~/.pal/tools/project.ts create --path "$(pwd)" --objectives "first objective; second objective"
Logging a decision
User: "we decided <decision> because <reason>"
→ bun ~/.pal/tools/project.ts add-decision <slug> "<decision>" "<reason>"
Setting the goal and criteria
User: "set the goal for pal to 'ship ISA support with full test coverage'"
→ bun ~/.pal/tools/project.ts update-section pal goal "ship ISA support with full test coverage"
Completing a project
User: "mark <project> as complete"
→ Confirm
→ bun ~/.pal/tools/project.ts complete <slug>
Anti-patterns
- Don't dump the full ISA.md. Summarize. The user can ask for the raw payload.
- Don't write without confirming the field choice on ambiguous "store" requests. A context fact sticks forever; a next step implies follow-up — these are different commitments.
- Don't edit ISA.md files directly. Always use the CLI — it timestamps
updated and keeps the schema valid.
Rules
- Always check
list (or resume <name>) before writing — match an existing project rather than spawning a near-duplicate.
- Slugs are
[a-z0-9_-]+. Never rename a slug; if the display name needs to change, that's a code-side concern, not a slug change.
- The Stop hook handles
updated automatically when cwd matches path — no manual touch needed just to mark a project alive.
- Always announce a new ISC with the 🎟️ emoji — every single time, no exceptions. Whenever you open an ISC (
add-isc), report it back to the user on its own line prefixed with the ticket emoji and the ISC number, e.g. 🎟️ ISC #71 — <title>. This holds in every response mode and context (ALGORITHM, NATIVE, or a bare reply); opening an ISC without the 🎟️ marker is a defect.
