diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 86f9759..e5f6d51 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -16,10 +16,10 @@ concurrency: on: push: branches: [main] - paths-ignore: ['*.md', '**/docs/**'] + paths-ignore: ['**/docs/**'] pull_request: branches: [main] - paths-ignore: ['*.md', '**/docs/**'] + paths-ignore: ['**/docs/**'] workflow_dispatch: jobs: diff --git a/CHANGELOG.md b/CHANGELOG.md index 763df1d..589b7c8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,19 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.5.0] - 2026-08-21 + ### Added - **Model Groups manager** — added `/model-groups` with durable project/global JSON persistence, boot validation, CRUD TUI flows, per-model thinking levels, and operator notifications for invalid configs or unavailable model refs. - **Model Groups spawn routing** — `spawn` can route children through an optional exact Model Group name with names-only prompt guidance, `#group` autocomplete sugar that shows model/thinking details, authenticated random entry selection, thinking inheritance/clamping, and routed/fallback result identity lines. +- **Frontmatter-driven model selection** — skills and prompts can declare `model`, `model-group`, and `thinking` frontmatter to control model routing and reasoning level per invocation. Resolved during idle input and visibly blocked while streaming; an explicit `model` overrides `model-group`; multi-slash model IDs are supported; invalid values block command expansion with operator notifications, and invalid thinking warns while a valid model still applies. +- **Handoff `discardPages`** — the handoff tool accepts `discardPages` to prune stale notebook pages, staged transactionally via a sequential epoch and committed only after compaction succeeds; interrupted or failed discards retain pages. Notebook rehydration is branch-scoped with generation markers and an epoch watermark, ignores future-format entries, and handoff now verifies notebook completeness first and reports completion truthfully after the discard commit. ### Changed -- Improved Model Groups editing with a searchable complete-result, ten-visible-row add-model picker and a prompt-free inline group-name editor. -- Migrated child spawning to Pi's public selected-model and child-owned runtime APIs, added `max` thinking support, and disposed every created child session exactly once across completion, failure, abort, and reset races. Pi 0.82.0 and Node 22.19.0 are now the documented minimums; parent-only transient provider/auth state fails explicitly without model fallback. +- **Model Groups editing** — searchable complete-result and ten-visible-row add-model pickers, plus a prompt-free inline group-name editor. +- **Spawn lifecycle** — migrated child spawning to Pi's public selected-model and child-owned runtime APIs, added `max` thinking support, and disposed every created child session exactly once across completion, failure, abort, and reset races. Pi 0.84.1 and Node 22.19.0 are now the documented minimums; parent-only transient provider/auth state fails explicitly without model fallback. ### Fixed -- Model Groups add-model navigation now uses Pi's key matcher for Escape/left-arrow handling and filters provider/model choices to authenticated models. +- **Model Groups add-model navigation** — now uses Pi's key matcher for Escape/left-arrow handling and filters provider/model choices to authenticated models. ## [0.4.0] - 2026-07-22 @@ -146,7 +150,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - **Comprehensive test suite** — 50+ tests covering spawn execution and rendering (concurrency, cancellation, truncation, stale detection, ownership lifecycle, microtask batching), ledger tools (add/get/list, staleness, rehydration, empty states, prompt hints), handoff (tool, command, compaction), watchdog (nudge injection, enforcement), and extension lifecycle. - **MIT licensed** — open-source permissive license. -[Unreleased]: https://github.com/agenticoding/pi-agenticoding/compare/v0.4.0...HEAD +[Unreleased]: https://github.com/agenticoding/pi-agenticoding/compare/v0.5.0...HEAD +[0.5.0]: https://github.com/agenticoding/pi-agenticoding/compare/v0.4.0...v0.5.0 [0.4.0]: https://github.com/agenticoding/pi-agenticoding/compare/v0.3.0...v0.4.0 [0.3.0]: https://github.com/agenticoding/pi-agenticoding/compare/v0.2.0...v0.3.0 [0.2.0]: https://github.com/agenticoding/pi-agenticoding/compare/v0.1.0...v0.2.0 diff --git a/README.md b/README.md index de6aa64..3451c1b 100644 --- a/README.md +++ b/README.md @@ -1,107 +1,160 @@ # pi-agenticoding [![pi.dev package](https://img.shields.io/badge/pi.dev-package-purple)](https://pi.dev/packages/pi-agenticoding) -[![npm version](https://img.shields.io/badge/npm-0.4.0-blue)](https://www.npmjs.com/package/pi-agenticoding) +[![npm version](https://img.shields.io/npm/v/pi-agenticoding?logo=npm)](https://www.npmjs.com/package/pi-agenticoding) +[![CI](https://github.com/agenticoding/pi-agenticoding/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/agenticoding/pi-agenticoding/actions/workflows/test.yml) [![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE) -![Status](https://img.shields.io/badge/status-active-brightgreen) -> Context tools for [Pi](https://pi.dev): `spawn`, `notebook`, and `handoff` — so the agent manages its own context instead of rotting in a long transcript. +> A composable workflow layer for [Pi](https://pi.dev). Define task-specific workflows in saved prompts or skills, with declarative policy, short-lived shared memory, provider-independent delegation, and deliberate context boundaries. -## Why +**Give each task the workflow it needs: the right models, memory, permissions, and context boundaries.** -Long coding sessions [degrade well before the token ceiling](https://agenticoding.ai/context-engineering). Auto-compact and manual `/compact` are lossy summarizer passes — you must fire them early, steer them well, and hope the compression step kept the right facts. The agent does not author that cut. +## Quick start -**pi-agenticoding flips that.** It gives the LLM tools to isolate noisy work, keep task-scoped notes across deliberate cuts, and restart clean on purpose — with optional readonly when you want research without mutating the tree. - -Keeping that context small is also cheaper: most coding spend is **input** tokens, and provider prefix caches only stay warm for a few minutes of idle time. - -Deeper rationale: [docs/why.md](docs/why.md) · companion book: [agenticoding.ai](https://agenticoding.ai) - -## Features - -- **Spawn** — run research or implementation in a clean child context so the parent stays focused -- **Model Groups** — manage durable project/global model pools with `/model-groups`; route `spawn` by an exact group name, with `#group` autocomplete showing model/thinking details -- **Notebook** — task-scoped named pages for facts and decisions; survives handoff, dies with the conversation (`/new`) — no forever-memory rot -- **Handoff** — deliberate clean restart with a task prompt when the topic changes or context turns to noise -- **Topic** — same problem → prefer spawn; new problem → prefer handoff (human-set topics win) -- **Readonly** — explore and plan without writing the tree (`/readonly`, Ctrl+Shift+R, or `--readonly`); macOS/Linux can OS-sandbox bash, Windows is classifier-only -- **Visibility** — status bar shows context pressure, notebook count, topic, and readonly; warning at high usage - -## Install - -Requires the [Pi](https://pi.dev) coding agent. +Requires [Pi](https://pi.dev) 0.84.1 or later and Node.js 22.19.0 or later. ```bash pi install npm:pi-agenticoding ``` -Disable pi's built-in compaction so **handoff** owns deliberate restarts: +To let **handoff** own deliberate restarts, disable Pi's built-in compaction in `~/.pi/agent/settings.json`: ```json -// ~/.pi/agent/settings.json { "compaction": { "enabled": false } } ``` -**You should get:** tools `spawn`, `notebook_write`, `notebook_read`, `notebook_index`, `notebook_topic_set`, and `handoff`. The status bar can show context usage, notebook count, active topic, and readonly when enabled. +You now have `spawn`, notebook, and `handoff` tools; `/model-groups`, `/readonly`, `/notebook`, and `/handoff` commands; and status indicators for context pressure, notebook state, topic, and readonly posture. + +## Repeat the workflow, not the steering + +Coding agents can research, implement, and review, but operators still have to define which specialists to involve, which models fill those roles, what may modify the tree, and which decisions must survive noisy exploration. + +pi-agenticoding moves that procedure into saved prompts or skills. Model Groups keep roles independent of provider choices, `spawn` isolates specialist work, the notebook carries only canonical decisions, and `handoff` starts the next phase without dragging forward the transcript. + +## Example: make critical review repeatable + +Save a readonly review procedure as `.pi/prompts/review.md`, so every changeset receives the same evidence requirements, review dimensions, and scope discipline. + +
+View the complete critical-review workflow + +``````text +--- +description: Critical code review before committing changes +argument-hint: "[description of intended changes]" +readonly: true +model-group: review +--- +You are the project maintainer and an expert code reviewer. + +The intent behind the changes in the working tree was: +````` +$@ +````` +Analyze the current changeset: + +- Explain what was done and how, and why based on the git changes +- Include exact files and line numbers supporting your claims + +Think step-by-step through each aspect below, focusing solely on the changes in the working tree. + +1. **Architecture & Design** + - Verify conformance to project architecture + - Check module responsibilities are respected and contracts aren't violated + - Ensure changes align with the original intent and that invariants are maintained + - Consider the scope the changes touch at, library, user facing, etc and review with this context in mind +2. **Code Quality** + - Code must be self-explanatory and readable + - Verify high quality comments for non-obvious patterns + - Complete docs comments for public APIs + - Style must match surrounding code style. Check related files and verify continuity and consistency + - Changes must be minimal - nothing unneeded + - Follow KISS principle + - Conformance to surrounding architecture +3. **Maintainability** + - Optimize for future LLM agents working on the codebase + - Ensure intent is clear and unambiguous + - Verify comments and docs remain in sync with code + - Verify documentation is present inline when necessary + - Reuses as much as possible from existing code +4. **User Experience** + - Identify areas where extra effort would significantly improve UX + - Balance simplicity with meaningful enhancements +5. **Tests** + - Spawn an agent to research the current test coverage then search the web for industry best practices for testing external invariants, constraints, and user-facing contracts so tests are stable across refactors, shareable, and run reliably in CI. Verify tests are up to standards. +6. **Logging and Observability** + - Verify that the logs available truly add operative value to the end user and don't pollute for little value. +7. **Scope** - are there additions, removals or changes not mentioned in the above intent? + +**REMEMBER, the review has multiple dimensions: tech debt, correctness, and effects on the user** + +Review the changes critically. Focus on issues that matter. Stay within the current scope of the changes, do NOT expand the scope. DO NOT EDIT ANYTHING - only review. + +If you spawned agents, wait until all agents complete. Finally, spawn a final agent to independently review all findings. +`````` + +
+ +Configure the `review` role once with `/model-groups`, then invoke the workflow with the intended change: + +```text +/review parser refactor and test cleanup +``` -### Compatibility +**Result:** one command applies the same review dimensions, delegated test research, and independent final pass to every changeset. The prompt owns the stable procedure; the `review` group owns the replaceable model choice. -pi-agenticoding requires **Pi 0.82.0 or later** and **Node.js 22.19.0 or later**. Spawn passes the final selected public model into a child-owned runtime. Persisted, environment-based, and extension-rediscoverable provider/auth configuration is available to children; parent-only transient credentials, inline provider factories, or in-memory catalog changes are not guaranteed to be rediscoverable. In that unsupported case, spawn reports the child resolution/auth failure and does not silently select another model. +Pi expands `$@` into the supplied intent and starts the parent reviewer with the workflow's model role and readonly posture. The parent can route focused `spawn` calls to specialist roles, wait for their condensed findings, and perform the final synthesis. Children cannot spawn or handoff, so orchestration stays with the parent. ## How it works -``` -You: "Add OAuth to the backend" - - notebook_topic_set("oauth") - spawn("research OAuth best practices") - spawn("audit current auth code") - │ - ▼ - notebook_write("oauth-decisions", "Flow: PKCE. Scope: read+write.") - │ - ├── spawn("implement token endpoint") - └── spawn("write tests") - │ - ▼ - handoff("Wire OAuth routes into the middleware stack. - Notebook page 'oauth-decisions' holds the constraints.") -``` +| Part | Role in the workflow | +|---|---| +| **Saved prompts and skills** | Define reusable procedures and frontmatter policy for review, migration, debugging, research, or project-specific work. | +| **Spawn** | Runs focused sub-agents in clean contexts without adding their full transcripts to the parent. Children inherit cwd, readonly posture, active registered parent tools executable in the child session, including MCP/extension tools such as ChunkHound, and child-local notebook tools; they cannot spawn grandchildren or handoff. | +| **Model Groups** | Map semantic roles to replaceable provider/model pools, globally or per project. | +| **Notebook** | Carries canonical decisions and constraints across parent, children, and handoffs, then disappears with the work stream. | +| **Handoff** | Starts the next phase with a directed prompt instead of a noisy transcript. | + +This pattern scales from critical review to separate research, implementation, migration, and debugging passes. -The agent set a topic, spawned research, saved decisions, delegated implementation, and handed off when context got noisy. **You said one sentence.** +## Why use it -## Primitives +- **Repeat expertise, not steering** — version the procedure and constraints instead of rebuilding them in conversation. +- **Change models without changing workflows** — prompts name roles; Model Groups hold provider/model choices. +- **Add perspectives deliberately** — role-specific passes can use different model families, reducing dependence on one family's blind spots and [self-preference](https://arxiv.org/abs/2404.13076). Provider diversity is only a proxy for model-family and training-pipeline diversity. +- **Preserve decisions, not transcripts** — the short-lived notebook keeps canonical state while `spawn` and `handoff` protect the parent context. See [why agent-managed context](docs/why.md). -| | | +## Compatibility and limits + +| Area | Current behavior | |---|---| -| **Spawn** | Subtask in a clean child context. Parent orchestrates; siblings run in parallel. Children inherit active registered parent tools executable in the child session — MCP/extension tools such as ChunkHound — plus child-local notebook tools. Children cannot spawn grandchildren or handoff. Omit `group` to inherit the parent model/thinking. An unknown group reports fallback to the parent. A known group randomly selects among configured/authenticated usable entries and fails before child creation if none are usable. The selected entry supplies the model and, when configured, overrides explicit/inherited thinking before Pi clamps it; the final selected public model runs in the child-owned runtime. | -| **Notebook** | Named pages coupled to this conversation/task. Carries memory across handoff; cleared on `/new`. Not a long-lived memory store — lifetime matches the work, so it cannot go stale across unrelated sessions. | -| **Handoff** | Write a prompt, compact, resume clean. Notebook holds reusable memory for this task; the prompt holds only remaining situational context. | -| **Readonly** | Blocks write/edit and guards bash while researching. Spawn inherits the posture. **macOS/Linux:** bash can run under OS sandbox (`sandbox-exec` / `bwrap`) — syscall-level write denial outside temp. **Windows:** no OS sandbox — **best-effort command classifier only** (interpreters and clever pipes can bypass). A coding guardrail on every OS — not a hardened security boundary. | +| **Runtime** | Requires Pi 0.84.1+ and Node.js 22.19.0+. Spawn passes the selected public model into a child-owned runtime. Persisted, environment-based, and extension-rediscoverable provider/auth configuration is available; parent-only transient credentials, inline provider factories, and in-memory catalog changes may not be. Resolution failures are explicit and never silently select another model. | +| **Frontmatter** | `model: /` overrides `model-group`; `thinking: off|minimal|low|medium|high|xhigh|max` is capability-clamped and overrides group thinking; `readonly` is boolean. Interactive model selection runs at idle input, while readonly is deferred to `before_agent_start`. Model/thinking changes are sticky. Failed or streaming selection blocks expansion; headless/RPC invocations ignore this policy. | +| **Group routing** | A known group samples uniformly **with replacement** from authenticated, usable entries, so repeated calls may select the same model. Unknown spawn groups visibly fall back to the parent; known groups with no usable entries fail before child creation. There is no weighting, no-repeat selection, health routing, retry/failover, or optimizer. | +| **Context and cache** | Spawn creates a separate child context; handoff starts a new input prefix. A model/provider switch starts a different cache—the extension creates cache-aware boundaries, not cache preservation or provider cache configuration. | +| **Delegation** | Children return condensed results and cannot spawn or handoff. There is no worktree isolation or per-child granular tool policy. | +| **Memory** | Notebook pages are branch- and work-stream-scoped, survive handoff, and clear with `/new`; they are not forever memory. Handoff can transactionally discard stale pages. | -**Commands:** `/handoff` · `/notebook` · `/notebook ` · `/readonly` · `Ctrl+Shift+R` · `--readonly` +## Readonly and security -## Comparison +Readonly blocks write/edit and guards bash while researching; children inherit the posture. macOS uses `sandbox-exec`; Linux uses `bwrap` when available, otherwise only the command classifier remains. Windows is classifier-only. Interpreters and indirection can bypass classification. **Readonly is a coding guardrail, not a hardened security boundary.** -| Approach | Who decides | Across cuts | -|---|---|---| -| Platform auto-compaction | Runtime (late threshold) | Blunt lossy summary | -| `/compact` or `/clear` | User (timing + steer) | Lossy summarizer pass / paste | -| Forever “memory” stores | Background / RAG | Accumulates, goes stale, needs invalidation | -| **pi-agenticoding** | **Agent** | **Task-scoped notebook + handoff prompt** | +Toggle it with `/readonly`, `Ctrl+Shift+R`, `--readonly`, or workflow frontmatter. Skills and prompts can instruct models to run code and use tools, so review workflow files before trusting them. -## Learn more +## Documentation and help - [Why agent-managed context](docs/why.md) -- [Architecture](docs/architecture.md) -- [Agentic Coding](https://agenticoding.ai) — companion methodology +- [Architecture and exact lifecycle behavior](docs/architecture.md) +- [Changelog](CHANGELOG.md) +- [Questions, bugs, and feature requests](https://github.com/agenticoding/pi-agenticoding/issues) - [Pi package page](https://pi.dev/packages/pi-agenticoding) +- [Agentic Coding](https://agenticoding.ai) — companion methodology ## Contributing -Contributions welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the project workflow and quality expectations. +Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the project workflow and quality expectations. ## License diff --git a/package-lock.json b/package-lock.json index 13ffdd9..33a50ac 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "pi-agenticoding", - "version": "0.4.0", + "version": "0.5.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "pi-agenticoding", - "version": "0.4.0", + "version": "0.5.0", "license": "MIT", "devDependencies": { "@earendil-works/pi-ai": "0.84.1", diff --git a/package.json b/package.json index fad0ec9..aa55cca 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "pi-agenticoding", - "version": "0.4.0", + "version": "0.5.0", "type": "module", "description": "Context management primitives for the pi coding agent — spawn, notebook, handoff", "license": "MIT",