From 8cf9d36acba80a35cdaa8a321940dfed7b07c90c Mon Sep 17 00:00:00 2001 From: Val Alexander <68980965+BunsDev@users.noreply.github.com> Date: Sun, 24 May 2026 14:26:16 -0500 Subject: [PATCH] =?UTF-8?q?docs(guide):=20scaffold=20the=20CastCodes=20?= =?UTF-8?q?=E2=86=92=20Coven=20demo=20loop?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a six-page demo loop walkthrough under content/docs/guide/demo-loop/ matching the five "Next" roadmap items: index — overview, mermaid flow, links to each step open-project — project root + daemon handshake launch-session — harness choice, prompt, POST /sessions watch-session — pane streaming, status transitions, event cursor inspect-changes — diff review and validation (Coven-doesn't-own-diffs framing) finish-loop — the four explicit outcomes: merge, PR, archive, sacrifice Each step page is a "heavy scaffold": Fumadocs , , and mockups carrying the flow, accurate CLI commands for every action, links into the existing harness/daemon/openapi references, and explicit `> TODO: CastCodes UI` markers where the cockpit-side UI details still need to be filled in (launcher labels, pane chrome, diff view shortcuts, merge-action semantics). Wired into content/docs/guide/meta.json after `cast-codes` and before `architecture` so the reading order matches the onboarding flow. Co-Authored-By: Claude Opus 4.7 (1M context) --- content/docs/guide/demo-loop/finish-loop.mdx | 106 +++++++++++++++++ content/docs/guide/demo-loop/index.mdx | 40 +++++++ .../docs/guide/demo-loop/inspect-changes.mdx | 94 +++++++++++++++ .../docs/guide/demo-loop/launch-session.mdx | 109 ++++++++++++++++++ content/docs/guide/demo-loop/meta.json | 12 ++ content/docs/guide/demo-loop/open-project.mdx | 91 +++++++++++++++ .../docs/guide/demo-loop/watch-session.mdx | 103 +++++++++++++++++ content/docs/guide/meta.json | 1 + 8 files changed, 556 insertions(+) create mode 100644 content/docs/guide/demo-loop/finish-loop.mdx create mode 100644 content/docs/guide/demo-loop/index.mdx create mode 100644 content/docs/guide/demo-loop/inspect-changes.mdx create mode 100644 content/docs/guide/demo-loop/launch-session.mdx create mode 100644 content/docs/guide/demo-loop/meta.json create mode 100644 content/docs/guide/demo-loop/open-project.mdx create mode 100644 content/docs/guide/demo-loop/watch-session.mdx diff --git a/content/docs/guide/demo-loop/finish-loop.mdx b/content/docs/guide/demo-loop/finish-loop.mdx new file mode 100644 index 0000000..a786bb2 --- /dev/null +++ b/content/docs/guide/demo-loop/finish-loop.mdx @@ -0,0 +1,106 @@ +--- +title: "Step 5 — Finish the loop" +description: "Every session ends explicitly: merge, PR, archive, or sacrifice. Pick one and the loop closes." +--- + +import { Callout } from 'fumadocs-ui/components/callout'; +import { Step, Steps } from 'fumadocs-ui/components/steps'; +import { Mermaid } from '@/components/mermaid'; + +A session that never ends explicitly is the failure mode Coven exists to prevent. Step 5 is the rule: pick one of four outcomes, and the loop closes. No "ghost" sessions, no implicit completion. + +## The four outcomes + +|Yes, ship it| Merge["Merge to branch"] + Inspect -->|Yes, but needs review| PR["Open a pull request"] + Inspect -->|No, but keep the log| Archive["Archive session"] + Inspect -->|No, throw it away| Sacrifice["Sacrifice session"] +`} /> + +| Outcome | What it means | Reversible? | +| --- | --- | --- | +| **Merge** | The agent's worktree changes land on your active branch. | Yes (revert commit). | +| **PR** | A pull request is opened for review. | Yes (close the PR). | +| **Archive** | The session record + event log stay; the live PTY stops. | Yes (rejoin replays the log). | +| **Sacrifice** | The session record, event log, and worktree are deleted. | No. | + +## The flow + + + + ### Merge + + Land the worktree's changes on your active branch. Useful when you trust the work and want it in mainline immediately. + + > TODO: CastCodes UI — the "Merge" pane menu action. Document whether it: (a) merges the worktree branch into the active branch in your main checkout, (b) replays the diff as a commit, (c) something else. Also document the cleanup of the worktree afterward. + + CLI equivalent: + + ```bash + git checkout main + git merge + git worktree remove + coven sessions archive + ``` + + + + ### Open a PR + + Push the worktree branch and open a pull request — the standard review path when you want a teammate (or your future self) to look first. + + > TODO: CastCodes UI — pane action label. Confirm whether it (a) just runs `gh pr create`, (b) opens a draft PR form, (c) integrates with a specific provider. + + CLI equivalent: + + ```bash + git push -u origin + gh pr create --title "..." --body "..." + coven sessions archive + ``` + + + + ### Archive + + Stop the PTY (if still running), but keep the session record and event log so you can rejoin and replay the work later. Useful when you don't want to ship the changes but want to remember what the agent tried. + + ```bash + coven sessions archive + ``` + + Archived sessions appear in `coven sessions --all` and remain replayable through `coven rejoin --replay`. + + + + ### Sacrifice + + Delete the session record, its event log, and (if it lived in a per-lane worktree) the worktree itself. This is the explicit "throw it all away" path. + + ```bash + coven sessions sacrifice + ``` + + + Sacrifice is irreversible. The event log is gone — there's no replay. Use this when the agent's attempt was a dead end and the log isn't worth keeping. + + + + +## Why "explicit either way" matters + +Implicit cleanup is how agent workflows accumulate ghost branches, untracked worktrees, and "wait, what did the agent change?" mysteries. The demo loop is built around the inverse: + +- **Step 1** makes the *project boundary* explicit (root and cwd). +- **Step 2** makes the *intent* explicit (harness + prompt + title). +- **Step 3** makes the *work* explicit (live pane + event log). +- **Step 4** makes the *result* explicit (diff + validation). +- **Step 5** makes the *outcome* explicit (one of four, by your choice). + +If you finished step 5, the session is closed. The next loop starts again at step 1. + + + Loop closed. Return to [the demo loop overview](/docs/guide/demo-loop) or start a new loop from [step 1](/docs/guide/demo-loop/open-project). + diff --git a/content/docs/guide/demo-loop/index.mdx b/content/docs/guide/demo-loop/index.mdx new file mode 100644 index 0000000..b587524 --- /dev/null +++ b/content/docs/guide/demo-loop/index.mdx @@ -0,0 +1,40 @@ +--- +title: "The CastCodes → Coven demo loop" +description: "The five-step path from an open project to a finished agent session — open, launch, watch, inspect, finish." +--- + +import { Callout } from 'fumadocs-ui/components/callout'; +import { Mermaid } from '@/components/mermaid'; + +The demo loop is the canonical end-to-end story for working in Coven through CastCodes. It traces a single piece of intent from the moment you open a project to the moment you explicitly finish the session — merge, PR, archive, or sacrifice. The same loop runs from the `coven` CLI without CastCodes; this guide just adds the visible cockpit on top. + + + Every step makes the agent's work explicit. There is no hidden background work, no implicit completion. Intent enters at step 1; an artifact (merged code, PR, archived log, or deleted session) leaves at step 5. + + +## The five steps + + S2["2. Launch session"] + S2 --> S3["3. Watch session"] + S3 --> S4["4. Inspect changes"] + S4 --> S5["5. Finish loop"] + S5 -.-> S1 +`} /> + +| Step | What you do | Where it happens | +| --- | --- | --- | +| [1. Open project](/docs/guide/demo-loop/open-project) | Pick a project root and confirm the daemon is running. | CastCodes project sidebar + `coven daemon status` | +| [2. Launch session](/docs/guide/demo-loop/launch-session) | Choose a harness, write a prompt, kick it off. | CastCodes agent launcher or `coven run ""` | +| [3. Watch session](/docs/guide/demo-loop/watch-session) | Watch output stream into a visible pane. | CastCodes session pane or `coven sessions` / `coven rejoin` | +| [4. Inspect changes](/docs/guide/demo-loop/inspect-changes) | Read the diff, run validation, decide. | CastCodes diff view + your usual test/lint commands | +| [5. Finish loop](/docs/guide/demo-loop/finish-loop) | Merge, PR, archive, or sacrifice. Explicit either way. | CastCodes pane menu or `coven sessions archive` / `sacrifice` | + +## CLI parity + +Every step in the loop has a CLI equivalent in [the `coven` reference](/docs/cli). CastCodes is the visible cockpit — useful, not required. If you're scripting the loop in CI or working over SSH, the CLI runs the same daemon and the same harness sessions. + + + This page set is the first pass at the demo-loop docs. Each step page is a scaffold with the right structure, accurate CLI commands, and TODO markers for the CastCodes-side UI details (screenshots, exact menu labels). Track progress under the `community/roadmap-loop` group in the [Docs Issue Plan](/docs/reference/issue-plan). + diff --git a/content/docs/guide/demo-loop/inspect-changes.mdx b/content/docs/guide/demo-loop/inspect-changes.mdx new file mode 100644 index 0000000..24f4c1a --- /dev/null +++ b/content/docs/guide/demo-loop/inspect-changes.mdx @@ -0,0 +1,94 @@ +--- +title: "Step 4 — Inspect files and diffs" +description: "Read what the agent changed, run validation, and decide whether the work is acceptable before finishing the loop." +--- + +import { Callout } from 'fumadocs-ui/components/callout'; +import { Step, Steps } from 'fumadocs-ui/components/steps'; +import { File, Files, Folder } from 'fumadocs-ui/components/files'; + +The harness has been editing files on disk inside the project root. Step 4 is the human check: read the diff, run your usual validation, and form an opinion about whether step 5 should merge or sacrifice the work. + +## What "inspect" means in Coven + +Coven does not own diffs or test runners — it owns the **session** (a PTY-backed harness invocation and its event log). File changes are just regular edits in your working tree, observable through git, your editor, or CastCodes' file browser. Coven's contribution is making it obvious *which session* produced *which changes*. + + + + + + + + + + + + + + +The agent's edits land in your source files. The session record and event log stay under `~/.coven/` (or `$COVEN_HOME`) — they're not committed. + + + If you launched the session into a per-lane git worktree (the CastCodes default for parallel agent lanes — see the "Git worktree isolation per agent lane" roadmap row), the changes live in that worktree, not in your main checkout. Step 5 will help you decide what to do with the lane. + + +## The flow + + + + ### Open the diff + + > TODO: CastCodes UI — exact path to the diff view. Is it a pane sibling to the agent pane, a dedicated tab, or an overlay? Document keyboard shortcuts (next file / hunk). + + From the CLI, the usual `git status` / `git diff` work in the session's worktree: + + ```bash + git status + git diff --stat + git diff path/to/changed-file + ``` + + + + ### Validate + + Run your tests, type checker, linter — whatever you would run before any other commit. Coven does not run these for you. + + ```bash + npm test + npm run typecheck + npm run lint + ``` + + > TODO: CastCodes UI — is there a "Run validation" button on the pane that runs configured scripts? If so, document the configuration source (package.json scripts? a CastCodes-specific file?). + + + + ### Re-engage the agent (optional) + + If the agent missed something, you can send input to the same session — see [Step 3 → Send input](/docs/guide/demo-loop/watch-session). For a more significant follow-up, launch a new session from step 2 with a refined prompt and let it pick up the worktree state. + + + + ### Form a verdict + + You're now ready to decide between the four explicit outcomes in step 5: merge, PR, archive, or sacrifice. + + + +## CLI equivalent + +```bash +# Find the worktree associated with this session (if launched into one) +coven sessions show + +# Replay output later if needed +coven rejoin --replay + +# View the full event log +coven sessions log +``` + + + Continue to [Step 5 — Finish the loop](/docs/guide/demo-loop/finish-loop). Every session ends explicitly. + diff --git a/content/docs/guide/demo-loop/launch-session.mdx b/content/docs/guide/demo-loop/launch-session.mdx new file mode 100644 index 0000000..406d405 --- /dev/null +++ b/content/docs/guide/demo-loop/launch-session.mdx @@ -0,0 +1,109 @@ +--- +title: "Step 2 — Launch a session" +description: "Choose a harness, write a prompt, and spawn a Coven-backed Codex or Claude Code session inside the project." +--- + +import { Callout } from 'fumadocs-ui/components/callout'; +import { Step, Steps } from 'fumadocs-ui/components/steps'; +import { Mermaid } from '@/components/mermaid'; + +A session is a single harness invocation: a PTY-backed Codex or Claude Code process running inside the project, with its output recorded to the daemon's event log. CastCodes lets you launch one from a menu; the CLI's `coven run` does the same thing. + +## What gets created + +When you launch, the daemon: + +1. Writes a `SessionRecord` to the SQLite ledger with `status: "created"`. +2. Spawns the harness with the requested `cwd`, `prompt`, and `title`. +3. Begins appending `OutputEvent` / `StatusEvent` rows to the session's event log. +4. Flips the record to `status: "running"`. + +The session is now reachable by id from the API (`/api/v1/sessions/`), the CLI (`coven sessions`), and CastCodes (it appears as a new pane). + +## The flow + + + + ### Pick a harness + + Coven ships with two adapters in `coven.daemon.v1`: + + - **`codex`** — OpenAI Codex CLI. See [Harnesses → Codex](/docs/harnesses/codex). + - **`claude`** — Anthropic Claude Code. See [Harnesses → Claude Code](/docs/harnesses/claude-code). + + Other harnesses are tracked in the [roadmap](/docs/reference/roadmap) under "Additional harness adapters." + + > TODO: CastCodes UI — the launcher's harness picker control. Is it a dropdown, a radio, a multi-select for parallel lanes? Document the exact behavior plus the keyboard shortcut. + + + + ### Write the prompt + + The prompt is passed to the harness as its final argument — Codex and Claude Code each interpret it as the initial task. Keep it scoped to one outcome; you can always launch another session for a follow-up. + + > TODO: CastCodes UI — does the prompt input support history? Templates? Cast Codes shortcuts ([Cast Codes](/docs/guide/cast-codes)) for prompts like `/fix` or `/explain`? + + + + ### Launch + + CastCodes posts to the daemon's session endpoint. The PTY spawns; output starts flowing to the new pane. + + > TODO: CastCodes UI — confirm whether the launch button is one click, two-step (prepare → confirm), or whether multi-select launches N panes at once. See the roadmap row "Multi-select agent launches" — that's the path for parallel lanes. + + + +## CLI equivalent + +```bash +coven run codex "fix the failing tests" + +# Equivalent explicit form: +coven run \ + --harness codex \ + --project ~/code/example-project \ + --title "fix tests" \ + "fix the failing tests" +``` + +Or directly via the socket API: + +```bash +curl --unix-socket "$HOME/.coven/coven.sock" \ + -X POST -H 'content-type: application/json' \ + -d '{ + "projectRoot": "/Users/example/example-project", + "cwd": "/Users/example/example-project", + "harness": "codex", + "prompt": "fix the failing tests", + "title": "fix tests" + }' \ + http://localhost/api/v1/sessions +``` + +See [the API reference](/docs/openapi/sessions/create-session) for the full request shape. + +## Launch path + +>D: POST /api/v1/sessions { projectRoot, cwd, harness, prompt, title } + D->>L: INSERT SessionRecord (status: created) + D->>H: spawn harness in PTY + H-->>D: stdout/stderr stream + D->>L: append OutputEvent rows; flip status to running + D-->>CC: 201 { id, status: "running", ... } +`} /> + + + The daemon validates `projectRoot` and `cwd` (cwd must canonicalize inside the project root) and allowlists `harness` to the two adapters above. Anything else fails closed with `error.code: "invalid_request"` — branch on the code, not the message text. + + + + Continue to [Step 3 — Watch the session](/docs/guide/demo-loop/watch-session). Output is streaming. + diff --git a/content/docs/guide/demo-loop/meta.json b/content/docs/guide/demo-loop/meta.json new file mode 100644 index 0000000..ea37345 --- /dev/null +++ b/content/docs/guide/demo-loop/meta.json @@ -0,0 +1,12 @@ +{ + "title": "Demo Loop", + "description": "End-to-end walkthrough from open-project to finish.", + "pages": [ + "index", + "open-project", + "launch-session", + "watch-session", + "inspect-changes", + "finish-loop" + ] +} diff --git a/content/docs/guide/demo-loop/open-project.mdx b/content/docs/guide/demo-loop/open-project.mdx new file mode 100644 index 0000000..fc3313a --- /dev/null +++ b/content/docs/guide/demo-loop/open-project.mdx @@ -0,0 +1,91 @@ +--- +title: "Step 1 — Open the project" +description: "Pick a project root and confirm the Coven daemon is running there before any agent work begins." +--- + +import { Callout } from 'fumadocs-ui/components/callout'; +import { Step, Steps } from 'fumadocs-ui/components/steps'; +import { File, Files, Folder } from 'fumadocs-ui/components/files'; +import { Mermaid } from '@/components/mermaid'; + +A Coven session is always scoped to a project root — an absolute path on this machine that the daemon canonicalizes and uses as the trust boundary for harness `cwd` checks. Step 1 is making that root explicit, both to the daemon and to CastCodes. + +## What "project root" means + +Coven's daemon will refuse any session whose harness `cwd` does not canonicalize inside the requested `projectRoot`. The project root you open in CastCodes is the same string you would pass to `coven run --project ` or to a `POST /api/v1/sessions` request. + + + + + + + + + + + + +Anything inside `example-project/` is a valid `cwd`. Anything outside is rejected before the harness starts. + +## The flow + + + + ### Start (or confirm) the daemon + + The daemon owns session state, the SQLite ledger, and the socket. CastCodes will refuse to launch agent panes if the daemon is unreachable, and so will the CLI. + + ```bash + coven daemon start + coven daemon status # expect pid + socket path + ``` + + If `coven daemon status` reports nothing, see [Daemon lifecycle](/docs/daemon/lifecycle). + + + + ### Open the project in CastCodes + + > TODO: CastCodes UI specifics — exact label for the project picker (currently "Open Project"?), keyboard shortcut, whether dragging a folder onto the dock works, and where the project root is stored in user preferences. + + Once opened, the project root appears in the CastCodes sidebar and is the implicit `--project` for every agent pane launched from this window. + + + + ### Confirm CastCodes sees the daemon + + The agent panel renders a status pill (green) when CastCodes can reach `coven.daemon.v1`. If the pill is amber, the daemon isn't running on this machine; if it's red, CastCodes hit an error talking to the socket. + + > TODO: screenshot of the agent-panel status pill in each state. + + + +## CLI equivalent + +There is no separate "open project" command in Coven. The project root is just an argument: + +```bash +# `coven run` accepts an absolute path; if omitted, the cwd is used. +coven run codex --project ~/code/example-project "fix the failing tests" +``` + +## Handshake (under the hood) + +>D: GET /api/v1/health + D-->>CC: 200 { apiVersion, covenVersion, daemon } + CC->>D: GET /api/v1/capabilities + D-->>CC: 200 { adapters: ["codex","claude"], actions: [...] } + CC->>FS: stat(projectRoot) + FS-->>CC: ok + Note over CC,D: Project is "open" — no session created yet. +`} /> + + + Continue to [Step 2 — Launch a session](/docs/guide/demo-loop/launch-session). The project is open; nothing is running yet. + diff --git a/content/docs/guide/demo-loop/watch-session.mdx b/content/docs/guide/demo-loop/watch-session.mdx new file mode 100644 index 0000000..0d6be1b --- /dev/null +++ b/content/docs/guide/demo-loop/watch-session.mdx @@ -0,0 +1,103 @@ +--- +title: "Step 3 — Watch the session" +description: "Output streams into a visible pane. Session state is observable from CastCodes and from the daemon's event log." +--- + +import { Callout } from 'fumadocs-ui/components/callout'; +import { Step, Steps } from 'fumadocs-ui/components/steps'; +import { Mermaid } from '@/components/mermaid'; + +Once the harness is running, CastCodes streams its output into a pane and reflects state transitions in the agent panel. From the CLI, the same stream is reachable by polling `/api/v1/sessions//events` with a cursor, or by rejoining the session interactively. + +## What you see + +| Where | What | Source | +| --- | --- | --- | +| Session pane (live) | Raw PTY output, including ANSI colors. | `OutputEvent` rows from the event log. | +| Status bar / pill | `running`, `completed`, `failed`, `killed`, `orphaned`. | `SessionRecord.status` + `StatusEvent` rows. | +| Sidebar entry | Title, harness, age, status. | `GET /api/v1/sessions`. | +| Event log (CLI) | Replayable stream, monotonic `seq` cursor. | `GET /api/v1/sessions//events`. | + +## The flow + + + + ### The pane appears + + A new pane mounts in CastCodes for the session id. The first output bytes arrive within a few hundred milliseconds of launch. + + > TODO: CastCodes UI — pane chrome (title bar, status pill, copy/clear/scrollback controls). Does it auto-scroll, and how is "you have new output below" surfaced? + + + + ### Output streams + + Coven does not buffer-then-flush; lines hit the pane as the harness emits them. If the harness opens a paging interactive prompt, you can forward input — see step "Send input" below. + + > TODO: CastCodes UI — does the input box at the bottom of the pane auto-focus when the harness expects stdin? + + + + ### State transitions + + When the harness exits, the status pill flips to `completed` (exit 0), `failed` (non-zero), or `killed` (you sent a kill). If the daemon was stopped mid-run, the next start sees the session as `orphaned`. + + > TODO: screenshot per state. + + + + ### Send input (optional) + + Some harnesses prompt for confirmation. You can forward bytes to the PTY without leaving the pane. + + > TODO: CastCodes UI — input affordance. Is there a separate "send line" vs "send raw key" mode? + + + +## CLI equivalent + +```bash +# Live list with status +coven sessions + +# Tail output for one session +coven rejoin + +# Send input to a running session +echo "y" | coven sessions input +``` + +Or via the API directly: + +```bash +# Replayable event stream with afterSeq cursor for resume +curl --unix-socket "$HOME/.coven/coven.sock" \ + "http://localhost/api/v1/sessions//events?afterSeq=0" +``` + +See [Events → List events](/docs/openapi/events/list-events) and [Sessions → Send input](/docs/openapi/sessions/send-session-input). + +## Cursor-based replay + +>D: GET /events?afterSeq=0 + D->>L: read seq > 0 + L-->>D: page of events + nextCursor + D-->>Client: { events, nextCursor: { afterSeq: 42 }, hasMore: true } + Note over Client: Persist afterSeq=42 for resume after disconnect. + Client->>D: GET /events?afterSeq=42 + D-->>Client: next page +`} /> + + + `afterSeq` is monotonic per session. If CastCodes or your CLI disconnects, just resume from the last persisted cursor — no events are dropped, none are replayed twice. + + + + Continue to [Step 4 — Inspect changes](/docs/guide/demo-loop/inspect-changes). The agent's edits are on disk; time to read them. + diff --git a/content/docs/guide/meta.json b/content/docs/guide/meta.json index 266f90a..6be5449 100644 --- a/content/docs/guide/meta.json +++ b/content/docs/guide/meta.json @@ -8,6 +8,7 @@ "install", "concepts", "cast-codes", + "demo-loop", "architecture" ] }