@naxodev/apnea 0.1.0

package/CONTEXT.md

@@ -0,0 +1,61 @@
+# Apnea
+
+A host-neutral package that runs a multi-role development workflow inside Herdr panes, using file-backed handoffs instead of hidden subagents.
+
+## Language
+
+**Run**:
+One user goal executed end-to-end until a PR description artifact exists.
+_Avoid_: Session, job, workflow instance
+
+**Phase**:
+A planner-owned vertical slice of the goal with acceptance checks and verify commands.
+_Avoid_: Step, ticket, task (when meaning the slice)
+
+**Phase package**:
+The written contract that bounds one phase for the coder (files, steps, checks, non-goals).
+_Avoid_: Spec, ticket body, prompt
+
+**Dispatch**:
+One assignment of work to a single role for a single gate.
+_Avoid_: Subagent call, tool call, spawn
+
+**Round**:
+One rework iteration on a (phase, gate) after CHANGES_REQUIRED.
+_Avoid_: Retry, attempt (unless crash/timeout)
+
+**Verdict**:
+The reviewer's binary decision: APPROVED or CHANGES_REQUIRED.
+_Avoid_: Status, result (use those for dispatch completion)
+
+**Nits**:
+Optional non-blocking notes attached to an APPROVED verdict.
+_Avoid_: Soft fail, approved with changes
+
+**Brief**:
+Package-owned role identity document (harness-agnostic).
+_Avoid_: System prompt, agent md (when meaning the shared contract)
+
+**Artifact**:
+A role's required output file for a dispatch, with machine-readable front-matter.
+_Avoid_: Log, transcript, marker
+
+**Gate**:
+A tool-enforced precondition (step legality, verdict, verify commands, dirty-tree).
+_Avoid_: Check, hook
+
+**Profile**:
+A globally defined harness launch template declaring oneshot and/or interactive commands.
+_Avoid_: Model, provider, harness (when meaning the named config entry)
+
+**Role**:
+A fixed part in the loop (orchestrator, planner, reviewer, coder) with a fixed interaction mode.
+_Avoid_: Agent, subagent
+
+**Orchestrator**:
+The hybrid scheduler that drives tools and never implements product code.
+_Avoid_: Parent agent, main agent
+
+**Verify command**:
+A shell command from the phase package that must exit zero before commit.
+_Avoid_: Test (when meaning the gate command list)

package/CONTRIBUTING.md

@@ -0,0 +1,21 @@
+# Contributing to Apnea
+
+See the workspace [CONTRIBUTING.md](../../CONTRIBUTING.md) for setup, release, and trusted publishing instructions.
+
+Run the core package gates with:
+
+```sh
+bunx nx run-many -t typecheck test format:check package:check smoke --projects=apnea
+```
+
+Run the Pi adapter gates with:
+
+```sh
+bunx nx run-many -t typecheck test format:check package:check smoke --projects=pi-apnea
+```
+
+Keep workflow behavior, protocol resources, briefs, and schemas in `@naxodev/apnea`. Keep Pi registration, Pi resources, and Pi-specific role launching in `@naxodev/pi-apnea`.
+
+Both adapters must bind the shared operation registry. The Pi adapter must call it in process rather than invoke the CLI.
+
+Compatible core patches flow through the Pi package's dependency range. Incompatible host interface changes require coordinated releases of both packages.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nacho Vazquez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,163 @@
+# @naxodev/apnea
+
+Apnea drives a multi-role development loop — plan, review, code, review, verify, commit — where
+each role runs in its own real terminal pane and hands off work through files on disk instead of
+a hidden subagent. Any harness that can run a shell command can hold the orchestrator seat.
+
+## The loop
+
+```text
+plan → plan review → phase package → code → code review → verify+commit → …
+→ pr-description
+```
+
+Roles can be different harnesses (Pi, Claude, Codex, …) via **global profiles**. Project config
+only rebinds roles to profile names that already exist.
+
+## Requirements
+
+- **bun `>=1.3.7`.** Needed to **run** the tool, not just to build it: the installed `bin` is
+  `dist/cli.js` with a `#!/usr/bin/env bun` shebang, and npm does not enforce the `engines.bun`
+  key. If you install `@naxodev/apnea` globally with only `node` on `PATH`, the `apnea` command
+  will fail on first invocation — this is the most likely first-run failure for a new user.
+- **herdr**, for pane-based dispatch. The optional `floating` pane style additionally needs
+  **herdr ≥ 0.7.4** plus the linked plugin (see [`docs/protocol/config.md`](docs/protocol/config.md)).
+- **jj or git.** Per [ADR 0007](docs/adr/0007-jj-first-commits.md), if neither is present
+  auto-commit is refused.
+- **At least one agent CLI** — `pi`, `claude`, or `codex`.
+
+## Install
+
+```bash
+bun install -g @naxodev/apnea
+# or
+npm install -g @naxodev/apnea
+```
+
+For Pi, install the separate adapter:
+
+```bash
+pi install npm:@naxodev/pi-apnea
+```
+
+From source, for contributors:
+
+```bash
+cd packages/apnea
+bun install
+bun run build
+./dist/cli.js help
+```
+
+Optionally put it on `PATH`, e.g. `ln -s "$(pwd)/dist/cli.js" ~/.local/bin/apnea`.
+
+## Sixty-second quickstart
+
+1. `apnea setup` — writes global profiles to `~/.config/apnea/config.json` (and the herdr
+   `apnea` plugin, if herdr is present).
+2. `apnea start "<goal>"` — starts a run against your working copy.
+3. `apnea status` — a read-only snapshot of where the run stands and what to call next.
+
+`apnea status` with no run in progress looks like this:
+
+```console
+$ apnea status
+OK: no active run
+next: apnea start
+{
+  "has_state": false
+}
+```
+
+## CLI reference
+
+Any harness that can run a shell command can hold the orchestrator seat — the CLI and the Pi
+tools share one definition in `extension/registry.ts`, so they cannot drift apart (see
+[ADR 0009](docs/adr/0009-cli-driver-split.md)).
+
+### Operations
+
+One row per operation. The CLI verb and the `/apnea` subcommand are the same word — they share a
+single definition in `extension/registry.ts`, so they cannot drift apart (see
+[ADR 0009](docs/adr/0009-cli-driver-split.md)). The two were listed as separate tables until one
+of them went stale; a reader could not tell which.
+
+| Operation             | Pi tool                 | Flags                                        | Purpose                                                        |
+| --------------------- | ----------------------- | -------------------------------------------- | -------------------------------------------------------------- |
+| `setup`               | —                       | `[--project] [--force] [--agents-md]`        | global profiles, optional project bindings, `AGENTS.md` primer |
+| `start <goal>`        | `workflow_start`        | `[--allow-dirty] [--slug=name]` _(CLI only)_ | start a run                                                    |
+| `resume` / `abandon`  | `workflow_start`        |                                              | resume or abandon                                              |
+| `status`              | `workflow_status`       |                                              | read-only snapshot                                             |
+| `dispatch <kind>`     | `dispatch_role`         | `[--rework]`                                 | launch a role                                                  |
+| `wait`                | `workflow_wait`         | `[--poll=<ms>] [--budget=<ms>]` _(CLI only)_ | wait for the pending artifact                                  |
+| `commit [message]`    | `workflow_commit_phase` | `[--done]`                                   | verify + commit phase                                          |
+| `reset-rounds <gate>` | —                       | `[--i-am-human]` _(CLI only)_                | **human only**                                                 |
+
+Prefix with `/` inside Pi (`/apnea status`), or run it as a shell command (`apnea status`).
+`/apnea-start` and `/apnea-status` are short aliases.
+
+`reset-rounds` is not a Pi tool. It exists only as `apnea reset-rounds` and `/apnea reset-rounds`.
+Only the CLI gates it — it refuses unless stdin/stdout are a terminal and a human retypes the gate
+key, or passes `--i-am-human`. The slash command has no such gate: `/apnea` is already a human at
+a terminal. See [ADR 0002](docs/adr/0002-orchestrator-authority.md).
+
+`apnea wait` is resumable: exit `3` means the call's budget ran out but the role hasn't timed out,
+so call `apnea wait` again. Exit codes: `0` ok, `1` refused/error, `2` usage, `3` still waiting.
+See [`docs/protocol/config.md`](docs/protocol/config.md) for the budget-floor arithmetic behind
+`--poll` and `--budget`.
+
+### Setup flags
+
+```text
+/apnea setup              # ~/.config/apnea/config.json from PATH (+ herdr apnea plugin when herdr is present)
+/apnea setup --project    # also .apnea/config.json role→profile only
+/apnea setup --agents-md  # also write/refresh an AGENTS.md loop primer at the repo root
+```
+
+`pane_style` (`regular` default, `floating` opt-in) lives in config; floating needs herdr ≥ 0.7.4
+
+- the linked plugin — see [`docs/protocol/config.md`](docs/protocol/config.md).
+
+The `@naxodev/pi-apnea` adapter applies Pi-specific role launch behavior. The core package remains
+host-neutral.
+
+Fallback: skill `apnea-setup` or prompt `/apnea-init` (both point at the same rules). **No config
+UI in v1.**
+
+## Maturity status
+
+**What you can rely on:** the loop, the artifact contract, and the CLI are implemented, and the
+extension suite is green — CI runs it on every pull request.
+
+**What may still change:** the command surface and config shape may move before `1.0`. This is
+`0.1.0` — breaking changes will land in minor bumps, not patches.
+
+**Non-goals for v1:** worktrees, parallel coders, push/PR automation, memory store, native
+CLAUDE.md injection, force-approve, config UI.
+
+## Docs
+
+| Doc                                                            | Purpose                |
+| -------------------------------------------------------------- | ---------------------- |
+| [`CONTEXT.md`](CONTEXT.md)                                     | Glossary               |
+| [`docs/protocol/overview.md`](docs/protocol/overview.md)       | Loop, steps, tools     |
+| [`docs/protocol/artifacts.md`](docs/protocol/artifacts.md)     | Paths + front-matter   |
+| [`docs/protocol/config.md`](docs/protocol/config.md)           | Profiles + trust model |
+| [`docs/protocol/manual-gate.md`](docs/protocol/manual-gate.md) | Bootstrap acceptance   |
+| [`docs/adr/`](docs/adr/)                                       | Decisions              |
+| [`briefs/`](briefs/)                                           | Role briefs            |
+
+## Contributing
+
+Build, test, typecheck commands, version-control conventions, and what CI enforces are in
+[`CONTRIBUTING.md`](CONTRIBUTING.md).
+
+## Security
+
+Apnea runs repo-controlled text through agent CLIs by design — read
+[`SECURITY.md`](SECURITY.md) for the trust model before pointing it at a repository you don't
+trust, and for how to report a vulnerability.
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

package/SECURITY.md

@@ -0,0 +1,35 @@
+# Security
+
+Apnea runs an automated loop that executes repo-controlled text through agent CLIs. That is a
+real trust boundary, not an incidental detail, and it is worth stating plainly before you point
+this tool at a repository.
+
+## Trust model
+
+- **Repo-controlled argv is not allowed.** Profiles and every `cmd_*` array resolve only from
+  `~/.config/apnea/config.json` plus package defaults. A project-local `.apnea/config.json`
+  that sets `cmd`, `cmd_oneshot`, `cmd_interactive`, or `bin` hard-errors at start. Project
+  config may only rebind roles to profile names that already exist, and set caps and timeouts.
+- **Repo-controlled text is an accepted prompt-injection surface.** Tasks, plans, verify
+  commands, and vendored briefs are all repo text that reaches an agent CLI. This is
+  **disclosed, not solved.** Running Apnea over a repository you do not trust hands that
+  repository's text to an agent running with your credentials.
+- **Planner-authored verify commands execute at the commit gate**, in the project working
+  directory, in the same trust domain as the coder writing source. Their output goes to
+  `verify.log`.
+
+See [`docs/protocol/config.md`](docs/protocol/config.md) (Trust model section) and
+[`docs/adr/0006-config-trust-model.md`](docs/adr/0006-config-trust-model.md) for the full
+rationale.
+
+## Supported versions
+
+The package is pre-1.0. Only the latest release receives fixes.
+
+## Reporting a vulnerability
+
+Please report vulnerabilities through
+[GitHub private vulnerability reporting](https://github.com/naxodev/ai/security) on
+`naxodev/ai` - open the repository's Security tab and select "Report a vulnerability".
+
+Do not open a public issue for a security report.

package/briefs/coder.md

@@ -0,0 +1,40 @@
+# Brief: coder
+
+You implement exactly one **Phase package**. You do not commit, re-plan, or expand scope.
+
+## Inputs
+
+Task file names:
+
+- path to phase package (read fully)
+- optional path to prior code-review on rework
+- exact **Artifact** path for your result
+
+## Work
+
+1. Read the phase package.
+2. Implement only listed steps/files.
+3. Run the package’s verify commands yourself; paste command + exit + tail of output into your result body.
+4. Write the result artifact:
+
+```yaml
+---
+status: done
+---
+```
+
+Body: what changed, files touched, verify transcript, residual risks.
+
+## Rework
+
+If the task is a follow-up after `CHANGES_REQUIRED`:
+
+- Read the code-review artifact.
+- Fix only what the review requires within the same phase package.
+- Do not renegotiate scope; escalate via your result body if the package is wrong.
+
+## Rules
+
+- No `git commit` / `jj describe` / push — orchestrator commits after review + verify gate.
+- Do not edit `.apnea/state.json`.
+- Prefer smallest diff that satisfies acceptance checks.

package/briefs/orchestrator.md

@@ -0,0 +1,49 @@
+# Brief: orchestrator
+
+You schedule an Apnea **Run**. You do not implement product code, edit app source, or hand-edit `.apnea/state.json`.
+
+## Authority
+
+- Prefer Apnea tools when available: `workflow_start`, `dispatch_role`, `workflow_wait`, `workflow_commit_phase`, `workflow_status`.
+- Do **not** call `workflow_reset_rounds` — reset-rounds is not a model-facing tool at all; it is human-only, on the CLI and `/apnea reset-rounds` (ADR 0002).
+- If Apnea tools are absent, use the `apnea` CLI — same loop, same refusals.
+
+## Loop
+
+1. Start run (clean tree unless allow-dirty / resume). **Start only writes state — do not stop here.**
+2. Immediately dispatch **planner** (`kind=plan`) → wait for plan artifact.
+3. Dispatch **reviewer** (plan review) → wait for verdict.
+4. On `CHANGES_REQUIRED`, re-dispatch planner then reviewer (new round).
+5. On `APPROVED`, dispatch planner for **phase package**.
+6. Dispatch **coder** with phase package path.
+7. Dispatch **reviewer** (code review) → wait.
+8. On `CHANGES_REQUIRED` with `rework: code` or no rework field, re-dispatch coder with `rework=true`, then reviewer.
+9. On `CHANGES_REQUIRED` with `rework: phase_package`, dispatch planner for the revised phase package, then coder and reviewer. The package dispatch advances the review round automatically.
+10. On `APPROVED`, commit phase (run verify commands first).
+11. Repeat from phase packaging until planner reports no remaining phases.
+12. Dispatch planner for `pr-description.md`.
+
+## Rules
+
+- One outstanding Dispatch at a time.
+- Read verdicts only from artifact front-matter.
+- Never push remotes or open PRs.
+
+## Active recovery (do this before escalating)
+
+On timeout, idle-without-artifact, or a silent role pane: **fix it yourself** before
+bothering the human. Tools already auto-nudge and re-submit prompts; when they
+don't, the orchestrator still owns recovery.
+
+1. `herdr pane get <pending_pane_id>` — is the pane alive? agent_status?
+2. `herdr pane read <id> --source recent-unwrapped --lines 80` — did the prompt land?
+   - Prompt sitting in the input / INSERT / "Pasted text" → `herdr pane send-keys <id> Enter`.
+   - Agent idle, no artifact → `herdr pane run <id>` with a short nudge naming the exact artifact path.
+   - Agent working / API retrying → `workflow_wait` again (do not re-dispatch yet).
+   - Pane missing / harness exited to bare shell → `dispatch_role` same kind (no rework flag).
+3. Only escalate after recovery failed twice, or on: round cap, dirty reviewer tree, illegal step, VCS confusion.
+
+## Escalate (after recovery fails)
+
+Cap hit, dirty reviewer tree, illegal state, or two failed recovery attempts.
+Report a status-style summary (step, pending artifact, pane, last agent_status, what you tried).

package/briefs/planner.md

@@ -0,0 +1,54 @@
+# Brief: planner
+
+You produce plans and phase packages for an Apnea **Run**. You do not implement product code.
+
+## Inputs
+
+The Dispatch task file names:
+
+- goal
+- paths for prior artifacts (plan, plan-review, etc.)
+- exact **Artifact** path you must write
+
+## Outputs
+
+### Full plan (`plan.md` or tasked path)
+
+Include:
+
+- goal restatement
+- ordered **Phases** (vertical slices)
+- per phase: intent, files likely touched, acceptance checks, **verify commands**, dependencies, non-goals
+- definition of done for the whole run
+
+Front-matter:
+
+```yaml
+---
+status: done
+---
+```
+
+### Phase package (`phase-package.md`)
+
+Only the **current** phase, detailed enough for a weaker coder:
+
+- exact steps
+- files to touch / not touch
+- acceptance checks
+- verify commands (must be runnable)
+- non-goals
+
+Front-matter: `status: done` only.
+
+When code review requests `rework: phase_package`, revise the package at the newly tasked round path. Read the cited review, preserve approved-plan scope, and do not overwrite the prior round's package.
+
+### PR description (`pr-description.md`)
+
+When tasked at terminus: summarize phases delivered, test plan, residual risk. Front-matter: `status: done` only.
+
+## Rules
+
+- On plan rework, revise the **full plan**, not a silent delta file (unless the task says otherwise).
+- Never invent artifact paths; use the task’s path.
+- Prefer small phases that each leave the tree green under verify commands.

package/briefs/reviewer.md

@@ -0,0 +1,40 @@
+# Brief: reviewer
+
+You are a **Gate**. You do not implement product code. You must not modify application source or tests (file-content dirty tree is a protocol failure).
+
+## Plan review
+
+Read `plan.md` (path in task). Check:
+
+- phases are vertical slices with acceptance + **verify commands**
+- verify commands look sane (not `rm -rf`, not empty)
+- scope is coherent; missing risks called out
+
+Write the tasked artifact with:
+
+```yaml
+---
+status: done
+verdict: APPROVED # or CHANGES_REQUIRED
+nits: | # optional; only with APPROVED
+  ...
+---
+```
+
+Body: findings, ordered by severity.
+
+## Code review
+
+Order matters:
+
+1. Read **phase package** and compare to approved **plan**. If the package drifts, return `CHANGES_REQUIRED` with `rework: phase_package` before deep code review.
+2. Review diff / coder result against the phase package only (no scope expansion).
+3. Check claimed verify output if present; you do not need to re-run tests if readonly, but flag missing evidence.
+
+Use `rework: code | phase_package` with a code-review `CHANGES_REQUIRED` verdict. Use `code` for implementation defects and `phase_package` for planner-owned package defects. Omit `rework` on `APPROVED`.
+
+## Rules
+
+- Binary **Verdict** only; nits never replace CHANGES_REQUIRED.
+- Do not commit, push, or “fix while reviewing.”
+- Write only the tasked artifact path (and nothing under app source).