From 1dd286ece20672adb8bf43ca0f4c2560420053c4 Mon Sep 17 00:00:00 2001 From: Jared Scott Date: Fri, 12 Jun 2026 12:45:58 +0800 Subject: [PATCH 001/115] =?UTF-8?q?docs=20site:=20address=20Karen's=20feed?= =?UTF-8?q?back=20=E2=80=94=20simplify,=20dedupe,=20fix=20rendering?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Apply the Recce doc-writing principle as a standing directive and act on the review of Karen's feedback: - Add docs/site/CLAUDE.md authoring directive (simplicity + concept/tutorial/ reference structure), excluded from the published build; defers to voice-and-tone.md for voice. - Home: lead with the problem before the "multi-agent orchestrator" claim; cut the up-front term dump from 7 to 2. - Fix the install-page ordered-list numbering bug (3- to 4-space indent) and collapse the three install paths into tabs. - Fix dark-on-dark header in slate mode (brand.css header foreground). - Reframe stage-lifecycle so stages read as workflow-defined, not canonical. - worked-example: show real artifact excerpts instead of only narrating them. - Dedupe: operating -> gates-and-decisions; first-launch -> survey; first-workflow -> commission (and correct the design-pass to 4 things). - Move command grammar off install; move build-from-source to Contributing; merge multi-host into contributing/adding-a-runtime; remove sprints-and-roadmap. - frontmatter-contract: move rationale prose into concept pages, keep tables. - mkdocs: canonical site_url https://spacedock.md/docs/. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/site/CLAUDE.md | 50 ++++++ docs/site/advanced/sprints-and-roadmap.md | 64 ------- docs/site/concepts/gates-and-decisions.md | 2 + docs/site/concepts/stage-lifecycle.md | 6 +- docs/site/concepts/worked-example.md | 33 ++-- docs/site/concepts/workflows-and-entities.md | 2 + docs/site/contributing/adding-a-runtime.md | 129 +++++++++++++- docs/site/contributing/build-from-source.md | 34 ++++ docs/site/get-started/first-launch.md | 31 ++-- docs/site/get-started/first-workflow.md | 92 ++++------ docs/site/get-started/install.md | 178 +++++++------------ docs/site/index.md | 10 +- docs/site/reference/command-reference.md | 31 +++- docs/site/reference/frontmatter-contract.md | 4 +- docs/site/reference/multi-host.md | 1 - docs/site/running-workflows/operating.md | 8 +- docs/site/stylesheets/brand.css | 4 + mkdocs.yml | 9 +- 18 files changed, 383 insertions(+), 305 deletions(-) create mode 100644 docs/site/CLAUDE.md delete mode 100644 docs/site/advanced/sprints-and-roadmap.md create mode 100644 docs/site/contributing/build-from-source.md delete mode 120000 docs/site/reference/multi-host.md diff --git a/docs/site/CLAUDE.md b/docs/site/CLAUDE.md new file mode 100644 index 00000000..7d7aa84a --- /dev/null +++ b/docs/site/CLAUDE.md @@ -0,0 +1,50 @@ +# Authoring directive for `docs/site/` + +**Always apply this when creating or modifying any content under `docs/site/`.** It is the Spacedock adaptation of Recce's documentation-writing standard ([`writing-content/reference/doc.md`](https://github.com/DataRecce/recce-team/blob/main/recce-team/skills/writing-content/reference/doc.md)). It governs **structure and simplicity**; [`contributing/voice-and-tone.md`](contributing/voice-and-tone.md) governs **voice, terminology, and capitalization**. When they overlap, follow voice-and-tone for wording and this file for shape. When both are silent, fall back to the `elements-of-style:writing-clearly-and-concisely` (Strunk) skill. + +## The first rule: simple beats complete + +Spacedock is not complicated; wordy docs make it *feel* complicated. Every edit should make the reader's job smaller, not bigger. + +- **Lead with the problem or the payoff, not the definition.** Open each page with why the reader is here and what they will be able to do — then name the mechanism. + - ✗ "Spacedock is a multi-agent orchestrator." + - ✓ "You have work that needs doing in stages, with a human sign-off before anything ships. Spacedock runs that for you." +- **Introduce the fewest terms possible, as late as possible.** Don't front-load a glossary. Define a term on first real use, gloss it once, then just use it. If a page introduces more than a handful of new terms, cut or defer some. +- **Cut, don't pad.** If a sentence still carries its meaning with a clause removed, remove the clause. If a paragraph repeats the page above it, delete it and link instead. +- **Don't repeat content across pages.** One page owns each idea; others link to it. Duplicated explanation is the main thing that makes the docs feel long. +- **Two levels of structure only:** section → page. No deeper nesting; no page that exists only to hold sub-pages. + +## Pick the page type, then follow its shape + +Every page is one of three types. The nav already sorts roughly this way — match the type to the reader's question. + +| Type | Reader asks | Spacedock sections | Must NOT contain | +|------|-------------|--------------------|------------------| +| **Concept** | "What is this / why does it matter?" | Concepts | Step-by-step instructions — link to the how-to instead | +| **Tutorial / how-to** | "How do I do X?" | Get started, Running workflows | Long conceptual digressions — link to the concept instead | +| **Reference** | "What are the options / the exact contract?" | Reference | Narrative prose, tutorial steps | + +### Concept pages +Opening (1–2 sentences: what + why) → how it works (2–4 short paragraphs, ideally one diagram or worked snippet) → when to use / when not → **Related** links (tutorial + reference). Describe the system; don't instruct. If you're numbering steps, you're in the wrong page type. + +### Tutorial / how-to pages +State the goal in one sentence. List prerequisites up front (never bury them mid-page). Numbered steps, **one action per step**, each showing the expected result (name the command *and* the output, e.g. ``spacedock status --next`` then what it prints). End with verification and "next steps" links. Push command-grammar / theory to the bottom or to a linked concept — the reader wants the outcome first. + +### Reference pages +Optimize for lookup in seconds. Use **tables** for flags, fields, and options (Name · Type/required · Description · Default). Give copy-paste examples. Mark required vs optional; show defaults; note edge cases. If a "reference" page is really an explanation, it belongs in Concepts; if it's really a procedure, it belongs in a how-to. + +## Link instead of repeat +- Cross-link liberally with **relative** internal links (so `mkdocs build --strict` resolves them). Concept → tutorial + reference; tutorial → concept + reference; reference → concept. +- Link the first mention of a load-bearing term (`workflow`, `gate`, `ensign`, `commission`) to the page that owns it, rather than re-explaining it. +- Descriptive link text, never "click here". + +## Before you commit a docs change +- [ ] Page opens with the problem/payoff, not a definition. +- [ ] Introduces only the terms this page actually needs; each defined on first use. +- [ ] Matches its type's shape (concept / how-to / reference) — no steps in concepts, no essays in reference. +- [ ] No content duplicated from another page; shared ideas are linked, not repeated. +- [ ] Internal links are relative and descriptive; first mentions of key terms link out. +- [ ] Ordered lists actually count up (watch for fenced blocks resetting the counter to 1). +- [ ] Voice and terminology follow [`contributing/voice-and-tone.md`](contributing/voice-and-tone.md). +- [ ] `mkdocs build --strict` passes. +- [ ] Read it back once and cut every sentence that survives removal. diff --git a/docs/site/advanced/sprints-and-roadmap.md b/docs/site/advanced/sprints-and-roadmap.md deleted file mode 100644 index 2dbeefe5..00000000 --- a/docs/site/advanced/sprints-and-roadmap.md +++ /dev/null @@ -1,64 +0,0 @@ -# Sprints & roadmap - -A roadmap is the strategy layer above the per-entity workflow: it owns outcome, scope, sequencing, and definition-of-done; the workflow owns task state. The two never overlap. Spacedock's own build uses this split. `docs/roadmap/README.md` is the strategy layer, and `docs/dev/.spacedock-state/` holds the executable entities that `spacedock status` queries. The roadmap explicitly "does **not** track task state." - -This page describes that construct as Spacedock practices it on itself. It is a convention (prose, frontmatter, and the native `status --where` query), not new binary behavior. There is no `sprint` recognizer, no `--sprint-validate` gate, and no contract bump. If you want this discipline for your own workflow, you adopt the convention; nothing in the launcher enforces it. - -## The roadmap as strategy layer - -The roadmap file owns four things the workflow does not: the **outcome** each sprint unlocks, the **scope** (which entities are in), the **sequencing** (value-ordered sprint list), and the **definition-of-done** per sprint. Task state, meaning which stage an entity is in and whether its gate passed, stays in the entities and is read with `spacedock status`. Keep the two separate: a roadmap that starts tracking stage transitions has duplicated the workflow and will drift from it. - -A roadmap groups its work into sprints. A sprint is a set of entities driven to one deliverable, with its own `index.md` recording the goal, the members-as-query, the DoD, and what is out of scope. - -## The shaping-FO / Commander split - -A sprint is run by two distinct roles, and the boundary between them is the load-bearing rule of the construct. - -- **Shaping FO** owns strategy and shape: the roadmap, each sprint's *definition* (deliverable + DoD), the gating ideation of the sprint's entities, the cross-entity coherence check, the staff readiness review, and packaging the sprint for execution. It stays high-level and does **not** hand-drive stage execution. -- **Commander** takes one packaged sprint and drives it to its deliverable: dispatches each stage, approves execution gates and merges, runs the sprint-wide integration test, and produces the report. The Commander boots `spacedock:first-officer` and creates its own team. - -The handoff between them is a **conn-to-drive dispatch**: a self-contained sprint package at `NNN-/dispatch-sprint-execution.md` that the Commander runs from a cold boot. It is a package, not a context transfer. The Commander does not inherit the shaping FO's session, and escalates back to the shaping FO and captain only on a third feedback cycle, a budget blowout, an irrecoverable block, or a genuine scope fork. - -## Sprint lifecycle: shape, drive, close - -A sprint moves through three phases, owner-tagged. The per-sprint checklist lives in the sprint's `index.md`; the canonical template is the lifecycle checklist in `docs/roadmap/README.md`. - -**Shape (shaping FO).** - -1. **Scope-lock** with the captain: which entities are in, which defer. The captain decides. -2. **Carve.** Stamp `sprint`, `group`, and `sprint-readiness` frontmatter on the members; write `index.md` (goal, members-as-query, DoD, out-of-scope). -3. **Ideate** each gated member: problem, approach, acceptance criteria, and test plan, with the **riskiest mechanism exercised first** (a spike, or a recorded "no spike needed"). Check existing ideation state first; never re-ideate a banked design. -4. **Preflight staff review.** Dispatch an *independent* reviewer to refute the designs. This is not optional and never a self-review: the reviewer is neither the FO nor the ideation ensigns, because the value is refuting the FO's own assumptions. Findings land in `staff-review.md` and Material ones are folded before the gates lock. -5. **Present ideation gates**, with checklist accounting and acceptance-criteria cross-check per member. The captain decides; the FO never self-approves. -6. **Package.** Write `dispatch-sprint-execution.md`: the boot recipe, per-member build notes, in-drive gates, and the release-cut recipe. - -**Drive (Commander, a separate cold-booted session).** - -1. Move each member through implementation, validation, and done, with a **detached adversarial audit at validation** for every high-stakes surface (front door, status guards, shipped scaffolding, CI/release machinery). -2. Merge each member to `next` by PR; keep state commits concurrency-safe. -3. **Pre-cut antipattern audit.** With all members merged and the tag not yet fired, dispatch an *independent* reviewer over the assembled sprint to catch cross-cutting antipatterns and integration holes before they ship. Ship-blockers are fixed before the cut; non-blockers are recorded for the next sprint. Running it after the tag means the antipattern has already shipped. -4. **Cut the release.** Confirm `go test ./...` is green from the root, then follow the authoritative cut procedure (see [Releasing](../contributing/releasing.md)). The captain authorizes the cut. - -**Close (shaping FO).** - -1. **Seed the next sprint.** Fold the pre-cut audit's deferred and non-blocking findings into the next sprint's backlog, and run a light post-cut release verification, since some release-machinery issues only manifest once the tag actually fires. - -## Membership is a query, not a list - -A sprint groups its entities by frontmatter query, never a hard-coded roster. Members carry `sprint`, `group`, and `sprint-readiness` frontmatter, and the rollup is the native `--where` filter on `spacedock status`. Run it against the workflow that holds the entities (`docs/dev` in Spacedock's own build): - -```bash -# every member of a sprint -spacedock status --workflow-dir docs/dev --where sprint=0200-flip - -# the drivable set — excludes deferred members -spacedock status --workflow-dir docs/dev --where sprint=0200-flip --where 'sprint-readiness != defer' -``` - -Each `--where` clause is `field value`, where `` is `=` or `!=`. Stacking clauses ANDs them: an entity is listed only when it matches every clause. The operator forms also cover presence and absence: `field !=` matches a non-empty value, `field =` matches an empty one. This is the same filter any reader can run; the sprint is a convention layered on top of it, not a separate command. - -`sprint-readiness: defer` is how a member stays in the sprint's definition but out of the Commander's drivable set. In the `0200-flip` capstone, `pj` is marked `defer` to mean "driven in the shaping session, not by the cold-boot Commander". That defers it from one driver; it is not dropped from the sprint. - -## Adopting it for your own workflow - -You do not need any launcher feature to use this. Add a roadmap file above your workflow, stamp `sprint` / `group` / `sprint-readiness` on the entities you group, and read membership with `status --where`. The construct buys you the strategy/state separation and the shaping-FO/Commander discipline; it costs you a convention you maintain by hand. Spacedock runs it on itself precisely to learn whether the convention earns a graduation to first-class support before any code is written for it. diff --git a/docs/site/concepts/gates-and-decisions.md b/docs/site/concepts/gates-and-decisions.md index a17619cb..0625a9cb 100644 --- a/docs/site/concepts/gates-and-decisions.md +++ b/docs/site/concepts/gates-and-decisions.md @@ -47,6 +47,8 @@ You answer a gate with one of three calls. A redo and a reject at a `feedback-to` stage run the same routing machinery. The difference is whether you are correcting a direction you accept or sending it back. Both name the concrete fix asks so the next worker has something to act on. +**A terminal close needs a recorded verdict.** Approving the terminal stage finalizes the entity, and Spacedock refuses to finalize or archive a terminal entity that carries no `verdict`: the verdict is the outcome on the record, and closing without one is the failure the guard exists to catch. The mechanics are in the [frontmatter contract](../reference/frontmatter-contract.md#entity-fields). + ## Feedback cycles and the loop cap When a feedback stage recommends `REJECTED`, or you reject at a `feedback-to` stage, the work routes back to the stage named in `feedback-to`: the stage that owns the fix, not the reviewer that flagged it. In the dev workflow, `validation` has `feedback-to: implementation`, so a rejected validation sends the deliverable back to implementation, not back to the validator. diff --git a/docs/site/concepts/stage-lifecycle.md b/docs/site/concepts/stage-lifecycle.md index 6e719044..a1df6ef9 100644 --- a/docs/site/concepts/stage-lifecycle.md +++ b/docs/site/concepts/stage-lifecycle.md @@ -1,6 +1,6 @@ # The stage lifecycle -An entity moves through a fixed chain of stages, one at a time, and each stage declares the work it owns and the proof it must produce. The dev workflow's chain is `backlog → ideation → implementation → validation → done`; your own workflow names its own stages, but the mechanics are the same. The first officer advances an entity stage by stage, dispatching one ensign per stage and pausing at the gates you declared. +An entity moves through an ordered chain of stages that the workflow defines, one at a time, and each stage declares the work it owns and the proof it must produce. The dev workflow's chain is `backlog → ideation → implementation → validation → done`; your own workflow names its own stages, but the mechanics are the same. The first officer advances an entity stage by stage, dispatching one ensign per stage and pausing at the gates you declared. The stage order, names, and per-stage properties live in the workflow README's frontmatter under `stages.states`. This page uses the dev workflow (`docs/site/contributing/development-workflow.md`) as the running example; read that page for the full per-stage Inputs/Outputs/Good/Bad detail. @@ -21,9 +21,9 @@ Each entry under `stages.states` is a stage name plus a set of boolean or string Beyond these properties, the prose of each stage's `###` subsection in the README is the stage definition: its Inputs, Outputs, and the Good/Bad bar. The first officer copies that subsection verbatim into the ensign's assignment, so what a stage declares in prose is exactly what the worker is told to do. -## The stages +## The dev workflow's stages -Read the chain as a pipeline: each stage takes the prior stage's output as its input, and the bar rises from "is this clear?" to "is this proven?". +These five are this workflow's stages, not a canonical set. Read the chain as a pipeline: each stage takes the prior stage's output as its input, and the bar rises from "is this clear?" to "is this proven?". - **`backlog`, the seed.** An entity enters here when first proposed: a title, a source, a brief description, and the test gates future stages must satisfy. No design work yet. `initial: true`, so this is where every new entity starts. The dev workflow also marks it `gate: true`, so the first officer presents a new entity for your go-ahead before it advances. - **`ideation`, the design.** A worker clarifies the problem, explores approaches, and produces a fleshed-out body: problem statement, proposed approach, acceptance criteria, and a test plan. Each acceptance criterion names how it will be checked. This stage is `gate: true` in the dev workflow, so the first officer presents the design for your approval before any code is written. diff --git a/docs/site/concepts/worked-example.md b/docs/site/concepts/worked-example.md index d0c11692..406ec84d 100644 --- a/docs/site/concepts/worked-example.md +++ b/docs/site/concepts/worked-example.md @@ -1,7 +1,7 @@ # A worked example This page traces one real entity, `z9` `codex-plugin-auto-install`, from -backlog through to `done` / PASSED, using artifacts that live in this repo. It is +backlog through to `done` / PASSED, using artifacts from the project repo. It is a concrete read of the abstract stage machine: backlog → ideation → implementation → validation → done, the gates between them, and what the captain actually decides at each one. @@ -64,16 +64,20 @@ Once the design is approved, `z9` moves to implementation. The dev workflow runs this stage in a `worktree` (`worktree: true`), so the dispatched ensign works in an isolated checkout, not the shared tree. -The dispatch package gave the implementer three concrete build notes, all of -which the work honored: +The dispatch package handed the implementer three build notes, verbatim from the +sprint's `dispatch-sprint-execution.md`: -- **Install on the shared `devBranch`**, via `ops.Install("codex", - marketplaceSource, devBranch)` and `--ref `, not a hardcoded - `next`, so the channel tracks the flip's later `devBranch` retarget. -- **Fix the now-false comments and error strings** it builds around - (`host_exec.go`, `frontdoor.go`), rather than adding new code around stale text. -- **Invert the obsolete test** `TestCodexFrontDoorNoPluginFailsFastWithoutInstalling`, - whose old assertion contradicted the new auto-install behavior. +> Build notes: **(a)** the codex install branch MUST be the shared `devBranch` +> (`ops.Install("codex", marketplaceSource, devBranch)` + `--ref `), +> NOT a hardcoded `next` — so it tracks the channel … **(b)** **fix** the +> now-false comments/error-strings it builds around (`host_exec.go:271-273`, +> `:32-34`; `frontdoor.go:314-316`), don't add around them; **(c)** inverts +> `frontdoor_test.go:414`. + +The work honored all three: it installed on the shared `devBranch` so the +install channel tracks the flip, fixed the stale comments and error strings in +place, and inverted the obsolete test whose old assertion contradicted the new +auto-install behavior. Implementation is complete when the deliverable is committed and the stage report is filed. It is not a parking spot: a completed implementation routes straight to @@ -103,10 +107,11 @@ PASSED recommendation goes to the captain for the terminal decision. `z9` reaches `done` when the captain reads the validation report and approves. The terminal stage records the outcome in frontmatter: `status: done`, -`verdict: PASSED`, and a `completed` timestamp. The sprint's `post-sprint-audit.md` -confirms `z9` finished `status: done`, `verdict: PASSED`, archived, with PR -reference #329, alongside its three sprint siblings (`kb` #327, `qa` #328, -`vh` #330). +`verdict: PASSED`, and a `completed` timestamp. The sprint's +`post-sprint-audit.md` confirms it in one line, `z9` alongside its three siblings: + +> kb / qa / z9 / vh entities are all `status: done`, `verdict: PASSED`, archived, +> with PR refs #327 / #328 / #329 / #330. That is the whole point of the machine: nothing reached `done` on assertion alone. `z9` advanced only on an approved design, an isolated implementation, a diff --git a/docs/site/concepts/workflows-and-entities.md b/docs/site/concepts/workflows-and-entities.md index f8675364..afb9fe48 100644 --- a/docs/site/concepts/workflows-and-entities.md +++ b/docs/site/concepts/workflows-and-entities.md @@ -68,6 +68,8 @@ The frontmatter is the machine-readable state. The full schema lives in the work | `worktree` | The worktree path while a dispatched agent is active; empty otherwise. | | `issue` | Optional external ticket reference, e.g. `ENG-123`, `kata:task-abc123`, or `owner/repo#42`. | +The frontmatter parser is line-oriented, so keep fields flat and top-level. If a workflow needs more metadata, add more flat custom fields rather than nested YAML — the v1 parser preserves lines, not arbitrary nested structure. + `status` is the field that drives everything: the first officer reads it to decide which entities are ready to advance. To see the queue, run the status viewer against the workflow directory: ```bash diff --git a/docs/site/contributing/adding-a-runtime.md b/docs/site/contributing/adding-a-runtime.md index 27cd5ba3..abb24ef5 100644 --- a/docs/site/contributing/adding-a-runtime.md +++ b/docs/site/contributing/adding-a-runtime.md @@ -2,7 +2,7 @@ A host is supported when a live or fixture-backed run launches it as a first officer, dispatches an ensign through that host's native agent mechanism, and verifies durable workflow state: process exit, entity body, state-checkout git log, and clean status. A host is not supported because its instructions mention Spacedock, and a substring search over code or prose is not proof of behavior. Spacedock ships `spacedock claude` and `spacedock codex` as proven front doors; adding a host means earning the same level of proof. -This page is the contributor's orientation. The full procedure, the exact checklists, and the worked Pi example live in [Multi-host support](../reference/multi-host.md). Read that before you write code. +This page is the full procedure: what "supported" means, the layers to add support in, the acceptance checklist, and a worked Pi example. Use it when adding a new host such as Pi, or when turning a spike into a supported runtime lane. ## What "supported" means @@ -25,6 +25,10 @@ Add support in small layers, each with its own proof at its own abstraction leve 4. **Launch/install UX.** Add `spacedock ` only after a manual or live harness proves the runtime path. Add `spacedock install --host ` only when the install path is known and checkable without mutating unrelated global host state. Add `spacedock doctor --host ` when there is a manifest, package, or runtime health check to verify. 5. **Live runner.** Prove the host with a live-gated test when the claim is runtime integration. Use a temp workflow fixture, isolated host config and session directories, and copied credentials rather than global host state. Assert process exit, entity content, git log, and clean status. Never pass on transcript phrasing. +## Launcher binary propagation through wrappers + +`spacedock claude` and `spacedock codex` attach `SPACEDOCK_BIN` to the process they exec, including the outer `safehouse -- ...` process when safehouse wrapping is active. Spacedock does not modify safehouse internals or assume a private passthrough mechanism; if a wrapper or runtime strips `SPACEDOCK_BIN` before the agent session observes it, the skill contract's `${SPACEDOCK_BIN:-spacedock}` convention degrades to the existing `$PATH` lookup. + ## Match the proof to the claim Use the smallest proof at the same abstraction level as the claim: @@ -37,6 +41,18 @@ Use the smallest proof at the same abstraction level as the claim: The failure mode to guard against: declaring a host supported because its prose looks right. Substring presence is acceptable proof only when the claim itself is about text being present or absent. +## Acceptance checklist + +A new runtime support slice is not done until the entity or PR records evidence for each applicable item: + +- Dispatch output uses the host-native contract and excludes incompatible host tool names. +- The first-officer and ensign skills load host runtime adapters. +- Split-root entity paths remain in the state checkout and are not rewritten into a code worktree. +- Follow-up/reuse cannot accept stale completion evidence, if reuse exists. +- Optional team substrates are represented as adapters over their real action schema. +- A live smoke proves the default dispatch path when runtime behavior is the claim. +- Install/launch commands exist only after the underlying mechanism is proven. + ## Manifesting from void When a runtime looks unsupported on first contact, do not read setup friction as proof the product path is impossible. A missing `auth.json`, an extension not auto-discovered in a temp home, or a subagent tool schema that differs from Claude's is harness work, not a blocker. A real blocker is a proven inability to launch, delegate, observe completion, or verify durable state *after* the harness is correct. @@ -55,4 +71,113 @@ Assume support is supposed to work. Do not treat missing polish, auth The prompt earns its place by changing the default interpretation of a failure: harness work gets fixed in-loop, and only a proven product or design blocker stops the work. -The worked Pi runtime is in [Multi-host support](../reference/multi-host.md): the live smoke mechanism, the exact parent prompt, the install and doctor surface, and the full acceptance checklist. +## The worked Pi runtime + +Pi is the worked example of a host taken from spike to supported runtime: the live-smoke mechanism, the exact parent prompt, the install and doctor surface, and the skill load paths. + +### Pi live-smoke mechanism + +The Pi proof used a live-gated test named: + +```bash +go test -tags live -run TestLivePiSubagentEnsignSmoke ./internal/ensigncycle -v -count=1 +``` + +The harness did this: + +1. Resolve `pi` from `PATH` and the local Spacedock repo root. +2. Resolve the installed `pi-subagents` package root, defaulting to: + + ```text + ~/.pi/agent/npm/node_modules/pi-subagents + ``` + +3. Create temp runtime state: + + ```text + PI_CODING_AGENT_DIR= + PI_CODING_AGENT_SESSION_DIR= + --session-dir + HOME= + ``` + +4. Copy only the operator's existing OAuth file into the isolated Pi home: + + ```text + ~/.pi/agent/auth.json -> $PI_CODING_AGENT_DIR/auth.json + ``` + +5. Launch `pi --print` with explicit local resources: + + ```text + --extension ~/.pi/agent/npm/node_modules/pi-subagents/src/extension/index.ts + --skill ~/.pi/agent/npm/node_modules/pi-subagents/skills/pi-subagents + --skill /skills/first-officer + --skill /skills/ensign + ``` + +6. Create a temp split-root workflow: + - `README.md` declares `state: .spacedock-state`. + - The entity is folder-form in `.spacedock-state/pi-live-smoke/index.md`. + - Both workflow root and state checkout are git repositories. + +7. Ask the Pi parent to call `subagent(...)` exactly once. +8. Require the worker to append a stage report and commit only the state-checkout entity path. +9. Assert durable outcomes: + - Pi process exits successfully. + - Entity body contains the exact smoke marker and stage report shape. + - State checkout git log contains the worker commit. + - The entity path has no uncommitted changes. + +For Pi, the concrete "assume it works" prompt was: + +```text +Assume Pi support is supposed to work. Do not treat missing polish, auth setup friction, or tool-shape mismatch as proof the runtime is impossible. In FO capacity, iron out the frictions: + +- if Pi auth is missing in an isolated harness, copy/reuse the existing Pi OAuth auth file correctly; +- if the dispatch substrate needs a local package/extension path, wire it explicitly; +- if the Pi tool shape differs from Claude/Codex, adapt to the Pi-native contract rather than emulating Claude tools; +- if a live test fails due to harness setup, fix the harness and rerun; +- only stop for a real product/design blocker, not for first-contact setup friction. +``` + +### Exact Pi parent prompt + +The live test formats this prompt with repository and temp paths. Keep the structure when debugging Pi runtime support; only substitute the paths and marker. + +```text +You are the Spacedock first officer for a live Pi smoke test. + +Use the pi-subagents subagent(...) tool exactly once to dispatch one Pi ensign worker. Do not use or mention Claude Agent, SendMessage, TeamCreate, or TeamDelete tools. + +Dispatch a worker with agent "delegate" and this task: + +Load and follow the local Spacedock ensign skill at /skills/ensign/SKILL.md and the Pi ensign adapter at /skills/ensign/references/pi-ensign-runtime.md. This is a split-root Spacedock workflow. + +Workflow directory: +State checkout: +Entity file: +Target stage: implementation + +Required worker actions: +1. Read the workflow README and entity file. +2. Do not edit YAML frontmatter. +3. Append an implementation stage report to the entity body containing the exact marker PI-LIVE-SUBAGENT-ENSIGN-SMOKE, at least one '- DONE:' item, and a '### Summary' subsection. +4. Commit only the entity path in the state checkout with message 'ensign: pi live smoke'. Use a path-scoped git add/commit for pi-live-smoke/index.md. +5. Return a concise completion result naming the entity file and commit evidence. + +After subagent(...) returns, you as first officer must verify the entity file contains PI-LIVE-SUBAGENT-ENSIGN-SMOKE and verify the state checkout git log contains 'ensign: pi live smoke'. Exit successfully only after those durable checks pass. +``` + +### Skill install and load paths + +For Pi, `spacedock pi` launches the proven front door by loading local resources explicitly: + +```text +/skills/first-officer +/skills/ensign +~/.pi/agent/npm/node_modules/pi-subagents/skills/pi-subagents +~/.pi/agent/npm/node_modules/pi-subagents/src/extension/index.ts +``` + +`spacedock install --host pi` is an idempotent readiness check and setup guide for that substrate; it does not install a Claude/Codex-style marketplace plugin and does not accept `--plugin-dir`. Resolve the local skill checkout by running it from the checkout or setting `SPACEDOCK_REPO_ROOT`. `spacedock doctor --host pi` reports the Pi CLI, auth file, `pi-subagents` extension/skill, local Spacedock skill health, and supervisor-talkback setup prerequisites: the `pi-subagents` intercom bridge source, the resolved `PI_INTERCOM_PACKAGE_ROOT` package root, and the `pi-intercom` skill resource. Current `pi-subagents`/`pi-intercom` packages do not expose stable `pi-intercom` or `subagents-doctor` PATH commands, so readiness is based on package/resource paths instead of command shims. These doctor/install checks are necessary setup checks but insufficient to prove live supervisor talkback. Live proof still requires the cq-style `pi-intercom-supervisor-talkback` probe: progress update -> decision request -> supervisor reply -> child resume -> durable marker evidence. Live tests should not mutate global `~/.pi/agent`; they should keep using isolated Pi homes with copied auth. diff --git a/docs/site/contributing/build-from-source.md b/docs/site/contributing/build-from-source.md new file mode 100644 index 00000000..2d23bbc5 --- /dev/null +++ b/docs/site/contributing/build-from-source.md @@ -0,0 +1,34 @@ +# Build from source + +Use this when you're working on Spacedock itself. It builds the launcher from the +development branch and loads the plugin from your checkout, so local changes take +effect immediately. For a normal install, see [Install Spacedock](../get-started/install.md). + +1. **Clone and build.** + + ```bash + git clone --branch next https://github.com/spacedock-dev/spacedock + cd spacedock + go build -o spacedock ./cmd/spacedock + ``` + +2. **Confirm the binary.** + + ```bash + ./spacedock --version + ``` + + Prints `spacedock ` for your local build. + +3. **Launch with the local plugin.** + + ```bash + ./spacedock claude "your task" -- --plugin-dir "$PWD" + ``` + + `--plugin-dir` is a host flag, so it rides after `--`. It loads the + first-officer and ensign agents from your checkout instead of the installed + plugin. Edits to the repo are live. + +The `next` branch is the development channel. It has no Homebrew release; use the +[Homebrew install](../get-started/install.md) for a stable build. diff --git a/docs/site/get-started/first-launch.md b/docs/site/get-started/first-launch.md index 5659cafe..2edfaa56 100644 --- a/docs/site/get-started/first-launch.md +++ b/docs/site/get-started/first-launch.md @@ -6,10 +6,22 @@ One command starts your first session and orients you in a project you already h spacedock claude "/spacedock:survey" ``` -This launches the first officer (the orchestrator agent that runs a Spacedock workflow) inside Claude Code, and hands it the survey task. The first launch sets up the plugin for you, so this single line is enough; you do not need a separate setup step. When a `.safehouse` profile is present in the working directory, the launch runs sandboxed automatically. +This launches the [first officer](../concepts/operating-model.md#three-roles) (the orchestrator agent that runs a Spacedock workflow) inside Claude Code, and hands it the survey task. The first launch sets up the plugin for you, so this single line is enough; you do not need a separate setup step. When a `.safehouse` profile is present in the working directory, the launch runs sandboxed automatically. Run it from inside a project that already has some agent history, such as a repo you have been coding in with Claude Code. Survey reads that history; an empty directory has nothing to report on. +## What survey reports + +In one read-only pass — it never edits your files — survey reconstructs what the agents in this project have implicitly been doing. It leads with **the decisions still open and waiting on you**, then names the [workflow](../concepts/workflows-and-entities.md) you have been running without naming it, the distinct workstreams, and how often you have had to step in, under a one-line headline (project, sessions, date range, decision and interruption counts). If the project has no agent history, it says so and stops. + +For the full section-by-section breakdown and how survey reads your history, see [what survey reports](../running-workflows/survey.md#what-it-reports). + +## What comes next + +Survey ends with an offer, not an action. After the report, it asks whether you want it to [commission](../running-workflows/commission.md) a real Spacedock [workflow](../concepts/workflows-and-entities.md) built from what it found, turning the open decisions into [approval gates](../concepts/gates-and-decisions.md) and the workstreams into work items. You can say yes and let it scaffold the workflow, or say no and keep the survey as a standalone orientation. Either way, nothing has changed in your project until you choose. + +To go straight to defining a workflow yourself instead, see [your first workflow](first-workflow.md). If `spacedock` is not yet installed, start with [installing Spacedock](install.md). + ## The command grammar The front door is one shape, and every launch uses it: @@ -23,20 +35,3 @@ spacedock claude "task" [--safehouse…] [-- host-flags…] - **Anything after `--` forwards verbatim to the host** (`claude` itself), including flags like `--resume`, `--model`, and `--plugin-dir`. `spacedock codex "task"` and `spacedock pi "task"` take the same shape for the Codex and Pi harnesses. Claude Code is the primary surface; the examples here use it. - -## What survey reports - -Survey reconstructs what the agents in this project have implicitly been doing, then reports it back. The survey is read-only; it never edits your files. It reads your recorded agent session history (through the `agentsview` tool, which it offers to install if it is missing), and it shows you, in one pass: - -- **The inferred workflow**: the loop you have been running without naming it, written out as a stage chain. -- **The workstreams**, the distinct tracks of work, each labeled as mechanical (a routine loop) or exploration (human-driven creative work). -- **The decisions still open and waiting on you.** These are the forks that were raised but never resolved. Survey leads with them, because they are the work that is actually blocked on you. -- **How often you had to step in.** Survey counts the interruptions and decision points across those sessions, so you can see where your attention has been going. - -A typical report opens with a one-line headline naming the project, the number of sessions, the date range, and the decision and interruption counts, then lays out each section below it. If the project has no agent history, survey says so plainly and stops; there is nothing to misreport. - -## What comes next - -Survey ends with an offer, not an action. After the report, it asks whether you want it to commission a real Spacedock workflow built from what it found, turning the open decisions into approval gates and the workstreams into work items. You can say yes and let it scaffold the workflow, or say no and keep the survey as a standalone orientation. Either way, nothing has changed in your project until you choose. - -To go straight to defining a workflow yourself instead, see [your first workflow](first-workflow.md). If `spacedock` is not yet installed, start with [installing Spacedock](install.md). diff --git a/docs/site/get-started/first-workflow.md b/docs/site/get-started/first-workflow.md index 182022b6..fb36378d 100644 --- a/docs/site/get-started/first-workflow.md +++ b/docs/site/get-started/first-workflow.md @@ -1,11 +1,13 @@ # Your first workflow -A workflow is a directory of plain-text work items plus a README that defines -the stages they move through, the schema each item carries, and the gates where -you make a call. You create one by describing what you want, in plain language, -to the `/spacedock:commission` skill. This page walks that first commission end -to end: the questions it asks, the design and review gates it sets up, and what -happens once the workflow starts running. +Your first workflow comes from one of two places: [survey](first-launch.md) +offers to build one from what it found in your project, or you describe one from +scratch to the `/spacedock:commission` skill. Either way you land here. A +workflow is a directory of plain-text work items plus a README that defines the +stages they move through, the schema each item carries, and the gates where you +make a call. This page walks the commission end to end: the questions it asks, +the design and review gates it sets up, and what happens once the workflow starts +running. A few terms used below, defined on first use: @@ -19,8 +21,10 @@ A few terms used below, defined on first use: for your call instead of advancing on its own. You are addressed as the captain, the workflow operator who makes the calls at -gates. The first officer is the orchestrator agent that runs the workflow; the -ensign is the worker agent that moves one entity through one stage. +gates; the first officer is the orchestrator agent that runs the workflow, and +the ensign is the worker that moves one entity through one stage. The +[operating model](../concepts/operating-model.md#three-roles) covers the three +roles in full. ## Commission a workflow @@ -38,23 +42,14 @@ scratch. The skill greets you and walks three phases: **design** (a few questions), **generate** (it writes the files), and a **pilot run** (it starts the workflow -on your seed items). The design phase asks you three things, one question at a -time: - -1. **The mission and the entity.** What the workflow is for, and what each work - item represents: "a design idea", "a bug report", "a candidate feature". The - skill derives a short label from your answer (a "design idea" becomes an - `idea`). -2. **The stages.** It proposes an ordered list from your mission (for a design - workflow, something like `backlog → ideation → implementation → validation → - done`), and you confirm, add, remove, or rename them. -3. **Seed entities.** Two or three starting items to run through, each with a - title and a short description (and an optional score). These become the - workflow's first work. - -From your answers the skill then derives the gates: which stages pause for your -approval, and which earlier stage rejected work bounces back to. By default it -gates the stage before the terminal one. +on your seed items). In the design phase it asks, one question at a time: what +the workflow is for and what each entity is (a "design idea" becomes an `idea`), +the stages an entity moves through, which of those stages are gated and where a +rejected entity bounces back to, and the quality bar for each stage — then the +entity-ID style and two or three seed items to start on. You confirm or adjust +each proposal. The +[commission reference](../running-workflows/commission.md#the-four-things-you-name) +covers every decision in full. You do not have to get every answer right. After the questions, the skill presents the full design as a summary (stages, gates, seed items, where the @@ -63,25 +58,17 @@ what to change and it re-presents. ## What gets generated -Once you accept, the skill writes the workflow into a new directory under -`docs/` and confirms each file it created: - -- `README.md`, the workflow's living spec. It holds the mission, the schema each - entity carries, and a section per stage describing its inputs, outputs, and - quality bar (`Good:` / `Bad:`). -- One file per seed entity, named from its title, with YAML frontmatter that - records its `status`, `score`, and other fields. - -The per-stage prose in the README is a best-guess starting point, not a -commitment. The skill flags this directly and offers a `review stages` walk that -steps through each stage's expectations so you can tighten the quality bar before -any work runs. Tightening here is cheap; an agent dispatched against a vague bar -is not. +Once you accept, the skill writes the workflow into a new directory under `docs/`: +a `README.md` that is the workflow's living spec (mission, schema, and a section +per stage with its `Good:` / `Bad:` bar) and one file per seed entity. The +per-stage prose is a best-guess starting point — tighten it before any work runs, +because an agent dispatched against a vague bar is expensive to correct. See +[what gets generated](../running-workflows/commission.md#what-gets-generated) for +the full file layout and the `review stages` walk. ## The design and review gates -A gate is where the workflow stops and hands you a decision instead of advancing -on its own. This is the line Spacedock draws: work flows through the stages, but +This is the line Spacedock draws: work flows through the stages, but **nothing crosses a gate without a recorded decision.** A development workflow gates the design stage and the review stage among others, so you sign off on the approach before code is written, and on the result before it ships. @@ -102,21 +89,8 @@ call that produced it. ## What happens after When you accept the design, the commission skill launches a pilot run on your -seed entities. It takes on the first-officer role itself for this first run: -it reads the workflow README, checks which entities are ready to advance, and -dispatches ensigns to move them through their stages. Stages that modify the -repo run in their own git worktree; lighter stages run inline. - -The run proceeds until the workflow goes idle or reaches a gate. There the first -officer stops and reports what happened: which entities moved, which stages they -passed through, which gate is waiting on you. From that point you are running the -workflow: approve, send back, or reject, and work continues. - -To resume the workflow in a later session, launch the first officer with no task: - -```bash -spacedock claude -``` - -It reads the saved workflow state, picks up where you left off, and dispatches -ensigns for any entity ready for its next stage. +seed entities: it takes the first-officer role itself, reads the README, and +dispatches ensigns to move ready entities through their stages until the workflow +goes idle or reaches a gate. From there you are running the workflow — approving, +sending back, and resuming in later sessions. [Operating a workflow](../running-workflows/operating.md) +covers the day-to-day loop and how to resume. diff --git a/docs/site/get-started/install.md b/docs/site/get-started/install.md index b034b524..a1181344 100644 --- a/docs/site/get-started/install.md +++ b/docs/site/get-started/install.md @@ -14,135 +14,84 @@ Spacedock itself is two pieces that install separately: harness (Claude Code, Codex, or Pi). The recommended setup installs the launcher with Homebrew, then adds the plugin. -A from-source build is available for development. +Pick your platform, then confirm and launch — those last two steps are the same +everywhere. A from-source build is available for development. -## Install with Homebrew (recommended) +## Install the launcher -1. **Install the launcher.** +=== "macOS (Homebrew)" - ```bash - brew tap spacedock-dev/homebrew-tap - brew install spacedock - ``` + ```bash + brew tap spacedock-dev/homebrew-tap + brew install spacedock + ``` -2. **Confirm it.** +=== "Linux / no Homebrew" - ```bash - spacedock --version - ``` + The Homebrew cask is macOS-only. On Linux — or on macOS without Homebrew — + the `curl | sh` script detects your OS and architecture, downloads the + matching tarball from the latest GitHub Release, verifies it against the + release `checksums.txt`, and installs the `spacedock` binary to + `~/.local/bin`. - Prints the installed version, e.g. `spacedock 0.20.0`. + ```bash + curl -fsSL https://raw.githubusercontent.com/spacedock-dev/spacedock/next/install.sh | sh + ``` -3. **Launch.** Point it at a project you already have and let it survey. + If `~/.local/bin` is not on your `PATH`, the script prints a note; add it + (`export PATH="$HOME/.local/bin:$PATH"`) so the `spacedock` command resolves. + Set `SPACEDOCK_INSTALL_DIR` to install elsewhere (e.g. + `SPACEDOCK_INSTALL_DIR=/usr/local/bin`, which may need `sudo`). - ```bash - spacedock claude "/spacedock:survey" - ``` + **Sandboxing.** Safehouse behaves the same as on macOS: when a `.safehouse` + profile is present in the working directory, Spacedock wraps the launch + through the `safehouse` command. Spacedock ships no sandbox of its own — a + run is sandboxed only when a Linux-capable `safehouse` binary is on your + `PATH`; when the binary is absent, Spacedock prints an install hint and the + launch proceeds **unsandboxed**. The macOS-only Gatekeeper/quarantine + handling does not apply on Linux and is not needed there. - Starts the first officer in Claude Code and runs the survey. The first launch - sets up the plugin for you, so this single command is enough. When a - `.safehouse` profile is present in the working directory, the launch runs - sandboxed. +=== "Codex or Pi" - To set up the plugin ahead of time, or to refresh it later, run - `spacedock install --host claude`. + Claude Code is the primary surface; Codex and Pi are supported but + experimental. Install the launcher with Homebrew (the macOS tab), then add + the plugin for your host: -## Install on Linux (or macOS without Homebrew) + ```bash + spacedock install --host codex # or: --host pi + ``` -The Homebrew cask is macOS-only. On Linux — and on macOS if you'd rather not use -Homebrew — install the launcher with the `curl | sh` script. It detects your -OS and architecture, downloads the matching tarball from the latest GitHub -Release, verifies it against the release `checksums.txt`, and installs the -`spacedock` binary to `~/.local/bin`. + Codex installs plugins from your shell rather than programmatically, so this + prints the `codex plugin` commands to run. -1. **Install the launcher.** +## Confirm it - ```bash - curl -fsSL https://raw.githubusercontent.com/spacedock-dev/spacedock/next/install.sh | sh - ``` - - Installs `spacedock` to `~/.local/bin`. If that directory is not on your - `PATH`, the script prints a note; add it (`export PATH="$HOME/.local/bin:$PATH"`) - so the `spacedock` command resolves. Set `SPACEDOCK_INSTALL_DIR` to install - elsewhere (e.g. `SPACEDOCK_INSTALL_DIR=/usr/local/bin`, which may need `sudo`). - -2. **Confirm it.** - - ```bash - spacedock --version - ``` - - Prints the installed version, e.g. `spacedock 0.20.0`. - -3. **Add the plugin and launch** exactly as in the Homebrew steps above - (`spacedock claude "/spacedock:survey"`). - -**Sandboxing on Linux.** Spacedock's safehouse integration behaves the same on -Linux as on macOS: when a `.safehouse` profile is present in the working -directory, Spacedock wraps the launch through the `safehouse` command. Spacedock -does not ship a sandbox — it detects the profile and delegates. A run is -sandboxed only when a Linux-capable `safehouse` binary is on your `PATH`. When -the binary is absent, Spacedock prints an install hint and the launch proceeds -**unsandboxed**. Install safehouse separately if you need the sandbox on Linux; -the macOS-only Gatekeeper/quarantine handling does not apply on Linux and is not -needed there. - -## Use Codex or Pi instead - -Codex and Pi are supported but experimental. Claude Code is the primary surface. - -1. **Install the launcher** (same Homebrew step as above). - -2. **Add the plugin** for your host. - - ```bash - spacedock install --host codex # or: --host pi - ``` - - Codex installs plugins from your shell rather than programmatically, so this - prints the `codex plugin` commands to run. Run them, then use the - first-officer skill in your Codex session. - -3. **Launch** with the matching subcommand. - - ```bash - spacedock codex "your task" # or: spacedock pi "your task" - ``` - -## Build from source (for development) - -Use this when you're working on Spacedock itself. It builds the launcher from -the development branch and loads the plugin from your checkout, so local changes -take effect immediately. - -1. **Clone and build.** - - ```bash - git clone --branch next https://github.com/spacedock-dev/spacedock - cd spacedock - go build -o spacedock ./cmd/spacedock - ``` +```bash +spacedock --version +``` -2. **Confirm the binary.** +Prints the installed version, e.g. `spacedock 0.20.0`. - ```bash - ./spacedock --version - ``` +## Launch - Prints `spacedock ` for your local build. +Point Spacedock at a project you already have and let it survey: -3. **Launch with the local plugin.** +```bash +spacedock claude "/spacedock:survey" +``` - ```bash - ./spacedock claude "your task" -- --plugin-dir "$PWD" - ``` +Starts the first officer in Claude Code and runs the survey. The first launch +sets up the plugin for you, so this single command is enough. When a +`.safehouse` profile is present in the working directory, the launch runs +sandboxed. To set up the plugin ahead of time, or to refresh it later, run +`spacedock install --host claude`. - `--plugin-dir` is a host flag, so it rides after `--`. It loads the - first-officer and ensign agents from your checkout instead of the installed - plugin. Edits to the repo are live. +With Codex or Pi, launch with the matching subcommand instead: +`spacedock codex "your task"` or `spacedock pi "your task"`. -The `next` branch is the development channel. It has no Homebrew release. Use the -Homebrew path above for a stable install. +Working on Spacedock itself? See [Build from source](../contributing/build-from-source.md) +in Contributing — it builds the launcher from the `next` branch and loads the +plugin from your checkout so local edits are live. ## Keep things in sync @@ -156,13 +105,8 @@ spacedock install --host claude If the `spacedock` command itself is missing, install the launcher with Homebrew first, then run `spacedock install --host claude`. -## Command grammar - -The front door is `spacedock claude "task" [--safehouse…] [-- host-flags…]` -(and the same shape for `spacedock codex` and `spacedock pi`): +## Next -- The task comes first. It's handed to the first officer as the launch prompt. -- Anything after `--` forwards verbatim to the host (`claude` / `codex` / `pi`), - including `--plugin-dir`, `--resume`, `--model`, and the like. -- `--safehouse` forces the launch through the sandbox. A `.safehouse` profile in - the working directory does the same automatically. +Run your [first launch](first-launch.md). For the full launch grammar — the task +argument, what rides after `--`, and the sandbox flags — see the +[command reference](../reference/command-reference.md#launch-claude-codex-pi). diff --git a/docs/site/index.md b/docs/site/index.md index 7ea8ad5c..9ed95e1f 100644 --- a/docs/site/index.md +++ b/docs/site/index.md @@ -1,14 +1,10 @@ # Spacedock -**Spacedock is a multi-agent orchestrator where nothing ships without a decision.** It lives within your existing harness: Claude Code, Codex, or Pi. +You're the human, and agents from a dozen sessions ping you all day — a design call, a one-line approval, "ship without full coverage?" — none of it on a schedule you can plan. Generation got cheap; your judgment is now the bottleneck, and every task still ends in a decision someone has to own. -Spacedock breaks work into stages and surfaces the decisions each stage needs, batched for you. Each decision arrives with evidence measured against a predefined bar for what good looks like. You approve, send back, or escalate. You can also delegate the call to an agent. Either way, the decision is recorded with its evidence and reason. +**Spacedock is a multi-agent orchestrator where nothing ships without a decision.** It lives within your existing harness — Claude Code, Codex, or Pi. It breaks work into stages and surfaces the decisions each stage needs, batched for you. Each decision arrives with evidence measured against a predefined bar for what good looks like. You approve, send back, or escalate — or delegate the call to an agent. Either way, the decision is recorded with its evidence and reason. -A few terms you'll meet throughout these docs: - -- A **workflow** is a directory of plain-text work item files plus a README that defines the stages, the schema, and the gates. -- An **entity** is one work item, a markdown file (or folder) that carries everything about the work: the problem, the design notes, the bar for done, and the stage reports. -- A **stage** is one step in the lifecycle; a **gate** is the decision point at its end. +You'll meet two terms right away: a **workflow** is the directory of work that defines the stages and the gates, and a **gate** is the point where the workflow pauses for your decision instead of advancing on its own. Entities (the individual work items) and stages are introduced in [Concepts](concepts/operating-model.md), where you first need them. Three roles run a workflow: diff --git a/docs/site/reference/command-reference.md b/docs/site/reference/command-reference.md index 29d24470..fecac593 100644 --- a/docs/site/reference/command-reference.md +++ b/docs/site/reference/command-reference.md @@ -1,11 +1,26 @@ # Command reference -The `spacedock` binary has ten subcommands in three groups (Launch, Setup, and -Workflow), plus a top-level `--version`. Run `spacedock` with no arguments to -print the grouped help; run `spacedock --help` for a command's own -flags. An unknown command or a stray leading flag exits 2 with a diagnostic on -stderr, and an unknown command resolution under cobra also exits 2. The verbs are -registered in `internal/cli/cli.go`. +The `spacedock` binary has ten subcommands in three groups, plus a top-level +`--version`: + +| Command | Group | What it does | +|---------|-------|--------------| +| [`spacedock claude`](#launch-claude-codex-pi) | Launch | Start Claude Code with the first officer loaded | +| [`spacedock codex`](#launch-claude-codex-pi) | Launch | Start Codex (experimental) with the first officer | +| [`spacedock pi`](#launch-claude-codex-pi) | Launch | Start Pi (experimental) with the first officer | +| [`spacedock install`](#setup-install-doctor) | Setup | Install the per-host plugin, then run the compatibility check | +| [`spacedock doctor`](#setup-install-doctor) | Setup | Run the compatibility check alone | +| [`spacedock status`](#status) | Workflow | Read or mutate workflow state — the table, `--next`, `--where`, `--set`, … | +| [`spacedock new`](#new) | Workflow | Create an entity from stdin (alias for `status --new`) | +| [`spacedock state`](#state) | Workflow | Manage a split-root workflow's state checkout | +| [`spacedock completion`](#completion) | Workflow | Print a bash or zsh completion script | +| [`spacedock dispatch`](#dispatch) | Workflow | Build the worker dispatch artifacts the first officer hands an ensign | +| [`spacedock --version`](#-version) | — | Print the binary version and the contract level | + +Run `spacedock` with no arguments to print the grouped help, and +`spacedock --help` for a command's own flags. An unknown command or a +stray leading flag exits 2 with a diagnostic on stderr. The verbs are registered +in `internal/cli/cli.go`. ## --version @@ -178,5 +193,5 @@ Builds the worker dispatch artifacts the first officer hands an ensign. `build` assembles the assignment (requires `--workflow-dir` unless `--print-schema` or validate-only); `show-stage-def` prints a stage's definition (`--workflow-dir` and `--stage`). A missing or unknown subcommand exits 2. See -[Adding runtime support](multi-host.md) for how `dispatch build` learns a new -host mode. +[Adding a runtime](../contributing/adding-a-runtime.md) for how `dispatch build` +learns a new host mode. diff --git a/docs/site/reference/frontmatter-contract.md b/docs/site/reference/frontmatter-contract.md index 8fe3f340..ab8703a9 100644 --- a/docs/site/reference/frontmatter-contract.md +++ b/docs/site/reference/frontmatter-contract.md @@ -2,7 +2,7 @@ Every entity is a markdown file (or a folder with an `index.md`) whose YAML frontmatter carries the fields Spacedock reads to track and move it. The always-current schema lives in the development workflow's [Schema / Field Reference](../contributing/development-workflow.md#field-reference); this page surfaces that table and the external-tracker bridge fields in one place for reference. A standalone `docs/specs/frontmatter-contract.md` is a planned follow-up; until it lands, the development workflow README is the source of truth. -The frontmatter parser is line-oriented. Keep fields flat and top-level. If richer metadata becomes necessary, add more flat custom fields rather than nested YAML, because the v1 parser preserves lines, not arbitrary structure. +Keep fields flat and top-level; add more flat custom fields rather than nested YAML. (The [entity frontmatter concept](../concepts/workflows-and-entities.md#entity-frontmatter) explains why the line-oriented parser requires this.) ## Entity fields @@ -23,7 +23,7 @@ These are the fields the development workflow declares for a `task` entity. Othe The `status` field is the execution state. `spacedock status` reads stage declarations from the workflow README and reports each entity's `status` against them; `--set status=` is the mutation that advances an entity. The status read path does not invent stages. If the README declares no stages block, membership cannot be validated. -The `verdict` field is guarded on the finalize action, not on reaching a terminal stage. The guard keys on the finalize shape (a `--set` that writes `completed`, or an `--archive` of a terminal entity) and refuses it (exit 1, entity unmutated) when the post-state `verdict` is empty (see `internal/status/verdict_guard_test.go`). A bare dispatch into a terminal stage that does not write `completed` passes without a verdict, because the verdict is the outcome of work that has not happened yet. A finalize on an entity that already carries a verdict also passes, even when that `--set` does not re-name it. `--force` bypasses the guard. The failure mode the guard catches is finalizing or archiving a terminal entity with no verdict on record. +The `verdict` field is guarded on the finalize action, not on reaching a terminal stage: writing `completed` (via `--set`) or archiving a terminal entity is refused with exit 1 (entity unmutated) when `verdict` is empty, and `--force` bypasses. A bare dispatch into a terminal stage that does not write `completed` passes without a verdict. See [gates and decisions](../concepts/gates-and-decisions.md#the-three-calls) for why a terminal close requires a verdict. ## Copy-paste starter diff --git a/docs/site/reference/multi-host.md b/docs/site/reference/multi-host.md deleted file mode 120000 index a7ccb9a2..00000000 --- a/docs/site/reference/multi-host.md +++ /dev/null @@ -1 +0,0 @@ -../../runtime-support.md \ No newline at end of file diff --git a/docs/site/running-workflows/operating.md b/docs/site/running-workflows/operating.md index 47dc885c..15fd75fb 100644 --- a/docs/site/running-workflows/operating.md +++ b/docs/site/running-workflows/operating.md @@ -60,12 +60,6 @@ It stops and returns to you only at a gate, at a terminal entity's merge ceremon ## Handle gate decisions -A gate is the decision point at the end of a stage marked `gate: true` in the workflow. When an entity reaches one, the first officer presents the stage report and the result of its review, then waits. It never self-approves. You decide: - -- **Approve.** The entity advances to its next stage. The first officer dispatches it (or, at a terminal stage, runs the merge-and-cleanup ceremony to close the entity with its verdict). -- **Reject.** On a stage with a `feedback-to` target (`validation` routes back to `implementation` in the `docs/dev` workflow), the rejection routes the concrete findings back to that stage and re-runs the work, then re-validates. A repeated rejection escalates back to you rather than bouncing indefinitely. -- **Send it back with direction.** If the result is close but not right, give the first officer the specific change to make. It updates the entity body, acceptance criteria, and test plan together, then re-runs the stage. - -The gate review names the chosen direction, cites the stage report, and ends with a single recommendation, approve or reject. Read the report it cites before deciding; overriding a `REJECTED` recommendation without a reason is exactly the kind of unexamined approval the gate exists to catch. +A gate stops the loop and hands you the call: the first officer presents the stage report and its review, then waits — it never self-approves. You make one of three calls — **approve**, **send it back with direction**, or **reject**. What each one does, what the gate report carries, and the feedback-cycle cap are covered in full in [the three calls](../concepts/gates-and-decisions.md#the-three-calls). When you approve a terminal stage, the entity is closed: the first officer records the merge, sets the `completed` timestamp and `verdict`, clears the worktree, and tears the worker down. At that point the loop returns to the top: run `status --next` and see what moved into reach. diff --git a/docs/site/stylesheets/brand.css b/docs/site/stylesheets/brand.css index 4f4466ad..cdcd7d32 100644 --- a/docs/site/stylesheets/brand.css +++ b/docs/site/stylesheets/brand.css @@ -5,6 +5,10 @@ .md-header, .md-tabs { background-color: var(--bg-2); + /* Material colours header text with --md-primary-bg-color (a dark ink in both + schemes); since we force a dark header bg, set a light fg so the wordmark, + tabs, and icons stay legible under the slate (default) scheme. */ + color: var(--fg); border-bottom: 1px solid var(--line-soft); } diff --git a/mkdocs.yml b/mkdocs.yml index ef7f4c77..27d4c16c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,12 +1,16 @@ site_name: Spacedock site_description: A multi-agent orchestrator where nothing ships without a decision. -site_url: https://spacedock-dev.github.io/spacedock/ +site_url: https://spacedock.md/docs/ repo_url: https://github.com/spacedock-dev/spacedock repo_name: spacedock-dev/spacedock copyright: Spacedock is released under the Apache License 2.0. docs_dir: docs/site +# Internal authoring directive (CLAUDE.md), not a published page. +exclude_docs: | + CLAUDE.md + theme: name: material custom_dir: overrides @@ -78,16 +82,15 @@ nav: - Operating a workflow: running-workflows/operating.md - Debrief & refit: running-workflows/debrief-and-refit.md - Advanced topics: - - Sprints & roadmap: advanced/sprints-and-roadmap.md - Mods & standing teammates: advanced/mods-and-standing-teammates.md - External-tracker bridge: advanced/external-tracker.md - Multi-workflow & split-root state: advanced/split-root-state.md - Reference: - Command reference: reference/command-reference.md - Frontmatter contract: reference/frontmatter-contract.md - - Multi-host support: reference/multi-host.md - Contributing: - The development workflow: contributing/development-workflow.md + - Build from source: contributing/build-from-source.md - Agent development: contributing/agent-development.md - Proof policy: contributing/proof-policy.md - Adding a runtime: contributing/adding-a-runtime.md From 11edebfcbc6bc1019e888fbf426f64996b47978d Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 11:03:29 -0700 Subject: [PATCH 002/115] docs site: prime "simple" on Home; ban AI-writing tells Home leads with the one idea (work moves through stages; nothing crosses a gate without a decision you own) instead of the orchestrator definition. Drops the up-front workflow/entity glossary and the three-role table; links to the operating model for roles. Authoring directive gains a first-impression rule (no glossary or role table in the first screen; name the one idea; the docs home connects forward, it does not re-pitch) and points at the new voice rule. Voice guide gains "Avoid the AI-writing tells": no em-dashes, no "not just X but Y", no rule-of-three padding, no hollow transitions or empty intensifiers. Applies it to its own prose. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/site/CLAUDE.md | 24 +++++++++++++++------ docs/site/contributing/voice-and-tone.md | 27 ++++++++++++++++++------ docs/site/index.md | 14 +++--------- 3 files changed, 41 insertions(+), 24 deletions(-) diff --git a/docs/site/CLAUDE.md b/docs/site/CLAUDE.md index 7d7aa84a..9076085e 100644 --- a/docs/site/CLAUDE.md +++ b/docs/site/CLAUDE.md @@ -6,7 +6,7 @@ Spacedock is not complicated; wordy docs make it *feel* complicated. Every edit should make the reader's job smaller, not bigger. -- **Lead with the problem or the payoff, not the definition.** Open each page with why the reader is here and what they will be able to do — then name the mechanism. +- **Lead with the problem or the payoff, not the definition.** Open each page with why the reader is here and what they will be able to do, then name the mechanism. - ✗ "Spacedock is a multi-agent orchestrator." - ✓ "You have work that needs doing in stages, with a human sign-off before anything ships. Spacedock runs that for you." - **Introduce the fewest terms possible, as late as possible.** Don't front-load a glossary. Define a term on first real use, gloss it once, then just use it. If a page introduces more than a handful of new terms, cut or defer some. @@ -14,21 +14,33 @@ Spacedock is not complicated; wordy docs make it *feel* complicated. Every edit - **Don't repeat content across pages.** One page owns each idea; others link to it. Duplicated explanation is the main thing that makes the docs feel long. - **Two levels of structure only:** section → page. No deeper nesting; no page that exists only to hold sub-pages. +## First impression: "simple," not "enterprise" + +The first screen a reader sees should make them feel *"there is one idea here, and I already get it,"* not *"this is a complex system with a manual."* Front-loading vocabulary or role tables is what makes simple software read as enterprise software. + +- **No glossary or role table in the first screen.** Introduce a term only when the next sentence needs it; defer the rest to the page that owns them and link. A roles or personas table near the top reads as enterprise structure. Link to it, do not lead with it. +- **Name the one idea, then say everything else is detail.** Give the reader permission to feel they understand the core before they read on. For Spacedock that idea is: work moves through stages, and nothing crosses a gate without a decision the reader owns. +- **The docs home connects forward, it does not re-pitch.** A reader who arrived from the landing page has already seen the problem and the promise. Do not restate the pain. State the one idea and point into the docs. + +## Write it plain: cut the AI tells + +The fastest way to make the docs feel padded is generated-prose texture. The voice rules that catch it (no em-dashes, no "not just X but Y", no rule-of-three padding, no hollow transitions or empty intensifiers) live in [`contributing/voice-and-tone.md`](contributing/voice-and-tone.md) under "Avoid the AI-writing tells." Apply them on every edit. + ## Pick the page type, then follow its shape -Every page is one of three types. The nav already sorts roughly this way — match the type to the reader's question. +Every page is one of three types. The nav already sorts roughly this way; match the type to the reader's question. | Type | Reader asks | Spacedock sections | Must NOT contain | |------|-------------|--------------------|------------------| -| **Concept** | "What is this / why does it matter?" | Concepts | Step-by-step instructions — link to the how-to instead | -| **Tutorial / how-to** | "How do I do X?" | Get started, Running workflows | Long conceptual digressions — link to the concept instead | +| **Concept** | "What is this / why does it matter?" | Concepts | Step-by-step instructions (link to the how-to instead) | +| **Tutorial / how-to** | "How do I do X?" | Get started, Running workflows | Long conceptual digressions (link to the concept instead) | | **Reference** | "What are the options / the exact contract?" | Reference | Narrative prose, tutorial steps | ### Concept pages Opening (1–2 sentences: what + why) → how it works (2–4 short paragraphs, ideally one diagram or worked snippet) → when to use / when not → **Related** links (tutorial + reference). Describe the system; don't instruct. If you're numbering steps, you're in the wrong page type. ### Tutorial / how-to pages -State the goal in one sentence. List prerequisites up front (never bury them mid-page). Numbered steps, **one action per step**, each showing the expected result (name the command *and* the output, e.g. ``spacedock status --next`` then what it prints). End with verification and "next steps" links. Push command-grammar / theory to the bottom or to a linked concept — the reader wants the outcome first. +State the goal in one sentence. List prerequisites up front (never bury them mid-page). Numbered steps, **one action per step**, each showing the expected result (name the command *and* the output, e.g. ``spacedock status --next`` then what it prints). End with verification and "next steps" links. Push command-grammar and theory to the bottom or to a linked concept; the reader wants the outcome first. ### Reference pages Optimize for lookup in seconds. Use **tables** for flags, fields, and options (Name · Type/required · Description · Default). Give copy-paste examples. Mark required vs optional; show defaults; note edge cases. If a "reference" page is really an explanation, it belongs in Concepts; if it's really a procedure, it belongs in a how-to. @@ -41,7 +53,7 @@ Optimize for lookup in seconds. Use **tables** for flags, fields, and options (N ## Before you commit a docs change - [ ] Page opens with the problem/payoff, not a definition. - [ ] Introduces only the terms this page actually needs; each defined on first use. -- [ ] Matches its type's shape (concept / how-to / reference) — no steps in concepts, no essays in reference. +- [ ] Matches its type's shape (concept / how-to / reference): no steps in concepts, no essays in reference. - [ ] No content duplicated from another page; shared ideas are linked, not repeated. - [ ] Internal links are relative and descriptive; first mentions of key terms link out. - [ ] Ordered lists actually count up (watch for fenced blocks resetting the counter to 1). diff --git a/docs/site/contributing/voice-and-tone.md b/docs/site/contributing/voice-and-tone.md index 2694356c..3d29a918 100644 --- a/docs/site/contributing/voice-and-tone.md +++ b/docs/site/contributing/voice-and-tone.md @@ -2,26 +2,39 @@ This is the writing-style guide for Spacedock's public documentation. It is grounded in two real voice signals, not invented: -- **The root `README.md`** — Spacedock's actual public voice: direct, anti-hype, claim-first ("Spacedock is a multi-agent orchestrator where nothing ships without a decision"), concrete over abstract, second person addressed to the reader. -- **The `comm-officer` mod** (`docs/dev/_mods/comm-officer.md`) — the project's prose discipline. It applies the `elements-of-style:writing-clearly-and-concisely` skill (Strunk) and is **light-touch by default**: "Preserve the caller's voice, rhythm, and technical vocabulary. Cut empty words, tighten sentences, fix clear grammar errors." Critically, it **defers to a project voice guide when one exists**. This page is that guide — so the comm-officer and any doc-writer apply it. +- **The root `README.md`**: Spacedock's actual public voice. Direct, anti-hype, claim-first ("Spacedock is a multi-agent orchestrator where nothing ships without a decision"), concrete over abstract, second person addressed to the reader. +- **The `comm-officer` mod** (`docs/dev/_mods/comm-officer.md`): the project's prose discipline. It applies the `elements-of-style:writing-clearly-and-concisely` skill (Strunk) and is **light-touch by default**: "Preserve the caller's voice, rhythm, and technical vocabulary. Cut empty words, tighten sentences, fix clear grammar errors." Critically, it **defers to a project voice guide when one exists**. This page is that guide, so the comm-officer and any doc-writer apply it. ## Voice - **Precise, honest, technical.** State what is true and what a thing does. Spacedock's own pitch leads with the claim, not the adjective. -- **No marketing or hype adjectives.** Avoid "powerful", "seamless", "revolutionary", "effortless", "blazing-fast", "game-changing". If a sentence still carries its meaning with the adjective removed, remove it. The product ethos — evidence over assertion — is the writing ethos. +- **No marketing or hype adjectives.** Avoid "powerful", "seamless", "revolutionary", "effortless", "blazing-fast", "game-changing". If a sentence still carries its meaning with the adjective removed, remove it. The product ethos, evidence over assertion, is the writing ethos. - **Concrete over abstract.** Name the command, the file, the outcome. Prefer "`spacedock status --next` lists the items ready to dispatch" over "Spacedock surfaces actionable work." - **Claim-first, then support.** Lead a section with the load-bearing sentence; follow with the detail. Mirrors the README's "what's different" bullets (bold claim, then the mechanism). +## Avoid the AI-writing tells + +Generated prose has a recognizable texture. It reads as padded and impersonal, and it is the fastest way to make simple software feel like a manual. Cut these on sight: + +- **Em-dashes.** Do not use `—`. Rewrite as a period, a comma, a colon, or parentheses. A sentence that needs an em-dash usually wants to be two sentences. +- **The "not just X, but Y" frame** and its cousins ("it's not only…", "more than just…"). State what the thing is. Drop the contrast scaffolding. +- **Rule-of-three padding.** Three parallel adjectives or clauses where one carries the meaning ("clear, simple, and easy to follow"). Keep the load-bearing one. +- **Hollow transitions and hedges.** "That said," "It's worth noting that," "In order to," "It's important to understand." Delete them; start with the content. +- **Empty intensifiers.** "very", "really", "quite", "actually", "simply", "just" (when it adds nothing), "leverage", "utilize". Prefer the plain verb. +- **Throat-clearing openers.** A page or section that opens by restating its own title or announcing what it will cover ("This page covers…", "In this section, we will…"). Open with the content. + +The test is the same as the cut rule: read it back and remove every word that survives removal. If a sentence sounds like it is performing thoroughness rather than saying something, rewrite it. + ## Tone and register per audience - **New-user pages (Get started): welcoming and encouraging, still precise.** Assume no prior Spacedock knowledge; define a term on first use; show the command and the output to expect. Confidence-building, never breezy. - **Operator pages (Concepts, Running workflows): direct and operational.** The reader is doing the work; tell them the steps and the decision points plainly. - **Contributor pages (Contributing, Reference): exact and unembellished.** Precision outranks warmth. Name the contract, the test, the failure mode. -- **Person and tense.** Second person ("you run", "you approve") and present tense for how-to and instructions — the README's register. Imperative for steps ("Run `spacedock doctor`."). Describe the system in the present tense ("the first officer dispatches an ensign"), not the future. +- **Person and tense.** Second person ("you run", "you approve") and present tense for how-to and instructions, the README's register. Imperative for steps ("Run `spacedock doctor`."). Describe the system in the present tense ("the first officer dispatches an ensign"), not the future. ## Canonical terminology and capitalization -Pinned from how the README and skills actually use these forms — not an imposed guess. Use them consistently. +Pinned from how the README and skills actually use these forms, not an imposed guess. Use them consistently. | Term | Form | Notes (grounded in real usage) | |------|------|--------------------------------| @@ -30,7 +43,7 @@ Pinned from how the README and skills actually use these forms — not an impose | First Officer | `First Officer` (role) / `the first officer` (prose) | Same pattern: Title Case in the roles table / when naming the role; lowercase in running prose ("the first officer reads the README"). The orchestrator agent. | | Ensign | `Ensign` (role) / `the ensign`, `ensigns` (prose) | Same pattern. The worker agent that moves one item through one stage. | | workflow | `workflow` | Common noun, lowercase. A directory of markdown entities + a README. | -| entity | `entity` | Common noun, lowercase. One work item (a markdown file or folder). The README also says "work item" — prefer "entity" in docs, gloss it as "work item" on first use for new users. | +| entity | `entity` | Common noun, lowercase. One work item (a markdown file or folder). The README also says "work item"; prefer "entity" in docs, gloss it as "work item" on first use for new users. | | stage | `stage` | Common noun, lowercase. backlog → ideation → implementation → validation → done. | | gate | `gate` | Common noun, lowercase. The decision point at the end of a stage. | | sprint | `sprint` | Common noun, lowercase. A grouped set of entities driven to a deliverable. | @@ -44,7 +57,7 @@ Rule of thumb: capitalize a **role** when you name it as a role (the roles table - **Show expected output.** For a command a reader runs, name the result, as `install.md` does ("Prints the installed version, e.g. `spacedock 0.20.0`"). - **Headings.** Sentence case ("Get started", "Your first workflow"), not Title Case. One `#` h1 per page (the page title); section headings start at `##`. - **Links.** Descriptive link text, never "click here" / "this link". Internal links are relative so `mkdocs build --strict` can resolve them. -- **Lists and emphasis.** Bullets for parallel items; bold for the load-bearing claim of a bullet (the README pattern). Use emphasis sparingly — if everything is bold, nothing is. +- **Lists and emphasis.** Bullets for parallel items; bold for the load-bearing claim of a bullet (the README pattern). Use emphasis sparingly; if everything is bold, nothing is. ## How this guide is applied diff --git a/docs/site/index.md b/docs/site/index.md index 9ed95e1f..e42b885a 100644 --- a/docs/site/index.md +++ b/docs/site/index.md @@ -1,18 +1,10 @@ # Spacedock -You're the human, and agents from a dozen sessions ping you all day — a design call, a one-line approval, "ship without full coverage?" — none of it on a schedule you can plan. Generation got cheap; your judgment is now the bottleneck, and every task still ends in a decision someone has to own. +Spacedock runs your work as a series of stages. **Nothing crosses a gate without a decision you own.** -**Spacedock is a multi-agent orchestrator where nothing ships without a decision.** It lives within your existing harness — Claude Code, Codex, or Pi. It breaks work into stages and surfaces the decisions each stage needs, batched for you. Each decision arrives with evidence measured against a predefined bar for what good looks like. You approve, send back, or escalate — or delegate the call to an agent. Either way, the decision is recorded with its evidence and reason. +A gate is a checkpoint where the workflow pauses and asks you the question the work has reached: ship this, or not? You approve it, send it back, or escalate. You can also delegate the call to an agent. Either way, the decision is recorded with its evidence and its reason. That is the whole idea. Everything else is detail. -You'll meet two terms right away: a **workflow** is the directory of work that defines the stages and the gates, and a **gate** is the point where the workflow pauses for your decision instead of advancing on its own. Entities (the individual work items) and stages are introduced in [Concepts](concepts/operating-model.md), where you first need them. - -Three roles run a workflow: - -| Role | Who | -|------|-----| -| **Captain** | You. You define the mission and make the calls at gates unless you delegate them. | -| **First Officer** | The orchestrator agent that runs the workflow and reports to you at gates. | -| **Ensign** | The worker agent that moves one entity through one stage. | +You are the captain. You set the bar and make the calls; the agents do the rest. See [the operating model](concepts/operating-model.md) for the three roles and how they divide the work. ## What's different From 0476f80c1c74646af770b754ee24e6e476b2353f Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 11:06:11 -0700 Subject: [PATCH 003/115] docs site: fold comm-officer polish into Home lede and voice rule Tighten the roles link clause (omit needless words) and add the bar- sharpens-with-use trust beat to the Home lede. Recast the AI-tells opening to a stronger colon construction and drop the self-referential closing framing. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/site/contributing/voice-and-tone.md | 4 ++-- docs/site/index.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/site/contributing/voice-and-tone.md b/docs/site/contributing/voice-and-tone.md index 3d29a918..de42caa4 100644 --- a/docs/site/contributing/voice-and-tone.md +++ b/docs/site/contributing/voice-and-tone.md @@ -14,7 +14,7 @@ This is the writing-style guide for Spacedock's public documentation. It is grou ## Avoid the AI-writing tells -Generated prose has a recognizable texture. It reads as padded and impersonal, and it is the fastest way to make simple software feel like a manual. Cut these on sight: +Generated prose has a recognizable texture: padded, impersonal, and the fastest way to make simple software feel like a manual. Cut these on sight: - **Em-dashes.** Do not use `—`. Rewrite as a period, a comma, a colon, or parentheses. A sentence that needs an em-dash usually wants to be two sentences. - **The "not just X, but Y" frame** and its cousins ("it's not only…", "more than just…"). State what the thing is. Drop the contrast scaffolding. @@ -23,7 +23,7 @@ Generated prose has a recognizable texture. It reads as padded and impersonal, a - **Empty intensifiers.** "very", "really", "quite", "actually", "simply", "just" (when it adds nothing), "leverage", "utilize". Prefer the plain verb. - **Throat-clearing openers.** A page or section that opens by restating its own title or announcing what it will cover ("This page covers…", "In this section, we will…"). Open with the content. -The test is the same as the cut rule: read it back and remove every word that survives removal. If a sentence sounds like it is performing thoroughness rather than saying something, rewrite it. +Read it back and remove every word that survives removal. If a sentence sounds like it is performing thoroughness rather than saying something, rewrite it. ## Tone and register per audience diff --git a/docs/site/index.md b/docs/site/index.md index e42b885a..03d85ffe 100644 --- a/docs/site/index.md +++ b/docs/site/index.md @@ -4,7 +4,7 @@ Spacedock runs your work as a series of stages. **Nothing crosses a gate without A gate is a checkpoint where the workflow pauses and asks you the question the work has reached: ship this, or not? You approve it, send it back, or escalate. You can also delegate the call to an agent. Either way, the decision is recorded with its evidence and its reason. That is the whole idea. Everything else is detail. -You are the captain. You set the bar and make the calls; the agents do the rest. See [the operating model](concepts/operating-model.md) for the three roles and how they divide the work. +You are the captain. You set the bar and make the calls; the agents do the rest. The bar starts rough and sharpens every time you reject, so the calls that once needed you become ones you can hand off with confidence. See [the operating model](concepts/operating-model.md) for how the three roles divide the work. ## What's different From 0e1f704937f0646eafc6387d2a34feb974db188c Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 11:09:43 -0700 Subject: [PATCH 004/115] docs site: Home uses plain "work items", defers entity to Concepts Drop the entity gloss and link from the Home "what's different" bullet. Plain "work items" carries the meaning; the entity term is defined where it is owned, in Concepts. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/site/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/site/index.md b/docs/site/index.md index 03d85ffe..da2eb880 100644 --- a/docs/site/index.md +++ b/docs/site/index.md @@ -11,7 +11,7 @@ You are the captain. You set the bar and make the calls; the agents do the rest. - **The agent doesn't get to judge its own work.** Review runs as a separate stage with fresh context, no access to the maker's reasoning. It pushes back on thin evidence and work that looks busy without proving its claim. - **Every decision leaves a trail.** Each gate carries a stage report: findings, verdicts, artifacts, anomalies. You decide on evidence, not the transcript, and the record outlives the reviewer. - **The bar sharpens as you use it.** Each stage declares what good means and the agent works to that line. When a standard turns out fuzzy in practice, the agent proposes an edit to the written criteria for your approval. -- **Batch the work; decide as it flows back.** Queue many entities at once. Agents advance each through its stages, and you handle gates as they surface, not one session at a time. +- **Batch the work; decide as it flows back.** Queue many work items at once. Agents advance each through its stages, and you handle gates as they surface, not one session at a time. - **Work survives the context limit.** When an agent runs out of context, a successor carries forward what's in flight. ## Where to go next From 2f0ff26b33e96114f18e74265a91a68eeb16d877 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 11:12:25 -0700 Subject: [PATCH 005/115] docs site: Home next-steps lead with the two entry paths, drop redundancy The Get-started bullet now frames the two real entry paths by payoff: survey an existing project to see where agents burn your time, or start a fresh workflow from a common shape. Drop the redundant "New here?" closer that repeated the survey-first nudge. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/site/index.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/site/index.md b/docs/site/index.md index da2eb880..fe47cd4f 100644 --- a/docs/site/index.md +++ b/docs/site/index.md @@ -16,13 +16,11 @@ You are the captain. You set the bar and make the calls; the agents do the rest. ## Where to go next -- **[Get started](get-started/install.md)**: install the `spacedock` launcher and the host plugin, then make your [first launch](get-started/first-launch.md) and build your [first workflow](get-started/first-workflow.md). +- **[Get started](get-started/install.md)**: [install](get-started/install.md) Spacedock, then pick an entry. [Survey an existing project](get-started/first-launch.md) to see where your agents burn your time and the workflow you are already running without naming it. Or [start a fresh workflow](get-started/first-workflow.md) from a common shape like development or research. - **[Concepts](concepts/operating-model.md)** covers the operating model, workflows and entities, the stage lifecycle, gates and decisions, and a worked example. - **[Running workflows](running-workflows/commission.md)** walks through commissioning a workflow, surveying an existing project, operating a running workflow, and debriefing and refitting between sessions. - **[Contributing](contributing/development-workflow.md)** covers the development workflow, agent development, the proof policy, and releasing. -New here? Start with [Install](get-started/install.md). It walks a fresh install end to end and names the output to expect at each step. - ## For agents using Spacedock Spacedock's docs are read by agents too. A user's first officer parsing these docs is itself an agent. The build emits a curated `llms.txt` index of the docs at the site root for product-using agents. (Repo-development guidance for an agent working ON Spacedock lives under Contributing → [Agent development](contributing/agent-development.md).) From e0726d4dfa0df594bbc6cf210da2dc731d9a5182 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 11:13:03 -0700 Subject: [PATCH 006/115] docs site: tighten survey bullet verb (comm-officer polish) "surface the workflow you are already running" reads cleaner than the participial tail. Keep "burn your time" and "without naming it" as the load-bearing survey framing. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/site/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/site/index.md b/docs/site/index.md index fe47cd4f..a22e2cc1 100644 --- a/docs/site/index.md +++ b/docs/site/index.md @@ -16,7 +16,7 @@ You are the captain. You set the bar and make the calls; the agents do the rest. ## Where to go next -- **[Get started](get-started/install.md)**: [install](get-started/install.md) Spacedock, then pick an entry. [Survey an existing project](get-started/first-launch.md) to see where your agents burn your time and the workflow you are already running without naming it. Or [start a fresh workflow](get-started/first-workflow.md) from a common shape like development or research. +- **[Get started](get-started/install.md)**: [install](get-started/install.md) Spacedock, then pick an entry. [Survey an existing project](get-started/first-launch.md) to see where your agents burn your time and surface the workflow you are already running without naming it. Or [start a fresh workflow](get-started/first-workflow.md) from a common shape like development or research. - **[Concepts](concepts/operating-model.md)** covers the operating model, workflows and entities, the stage lifecycle, gates and decisions, and a worked example. - **[Running workflows](running-workflows/commission.md)** walks through commissioning a workflow, surveying an existing project, operating a running workflow, and debriefing and refitting between sessions. - **[Contributing](contributing/development-workflow.md)** covers the development workflow, agent development, the proof policy, and releasing. From 891b2a526de38703db173c0dbbcf9fdccbad8085 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 11:13:41 -0700 Subject: [PATCH 007/115] docs site: drop Contributing pointers from Home Home is a user surface. Cut the Contributing bullet from "where to go next" and the agent-development pointer from the "for agents" note; both are reachable from the nav for anyone who wants them. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/site/index.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/site/index.md b/docs/site/index.md index a22e2cc1..4f9edd1d 100644 --- a/docs/site/index.md +++ b/docs/site/index.md @@ -19,8 +19,7 @@ You are the captain. You set the bar and make the calls; the agents do the rest. - **[Get started](get-started/install.md)**: [install](get-started/install.md) Spacedock, then pick an entry. [Survey an existing project](get-started/first-launch.md) to see where your agents burn your time and surface the workflow you are already running without naming it. Or [start a fresh workflow](get-started/first-workflow.md) from a common shape like development or research. - **[Concepts](concepts/operating-model.md)** covers the operating model, workflows and entities, the stage lifecycle, gates and decisions, and a worked example. - **[Running workflows](running-workflows/commission.md)** walks through commissioning a workflow, surveying an existing project, operating a running workflow, and debriefing and refitting between sessions. -- **[Contributing](contributing/development-workflow.md)** covers the development workflow, agent development, the proof policy, and releasing. ## For agents using Spacedock -Spacedock's docs are read by agents too. A user's first officer parsing these docs is itself an agent. The build emits a curated `llms.txt` index of the docs at the site root for product-using agents. (Repo-development guidance for an agent working ON Spacedock lives under Contributing → [Agent development](contributing/agent-development.md).) +Spacedock's docs are read by agents too. A user's first officer parsing these docs is itself an agent. The build emits a curated `llms.txt` index of the docs at the site root for product-using agents. From 7476f6d53ac043220fc367c3182c410af281eda1 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 11:15:49 -0700 Subject: [PATCH 008/115] docs site: discreet "for agents: llms.txt" footer link Surface the generated llms.txt index from the footer meta row, styled muted so it sits beside the copyright without competing with the user-facing nav. The url filter resolves it to /docs/llms.txt from any page depth. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/site/stylesheets/brand.css | 11 +++++++++++ overrides/partials/footer.html | 1 + 2 files changed, 12 insertions(+) diff --git a/docs/site/stylesheets/brand.css b/docs/site/stylesheets/brand.css index cdcd7d32..b033ee82 100644 --- a/docs/site/stylesheets/brand.css +++ b/docs/site/stylesheets/brand.css @@ -17,6 +17,17 @@ border-top: 1px solid var(--line-soft); } +/* Discreet machine-readers link in the footer meta row */ +.sd-footer-llms { + margin-left: 1em; + font-size: 0.64rem; + opacity: 0.7; + color: inherit; +} +.sd-footer-llms:hover { + opacity: 1; +} + /* Mono display headings -- Material has no display-font slot */ .md-typeset h1, .md-typeset h2 { diff --git a/overrides/partials/footer.html b/overrides/partials/footer.html index b21bab21..e56ae411 100644 --- a/overrides/partials/footer.html +++ b/overrides/partials/footer.html @@ -46,6 +46,7 @@
{% include "partials/copyright.html" %} + For agents: llms.txt {% if config.extra.social %} {% include "partials/social.html" %} {% endif %} From 0bc795a0f8d9f4e5df2788eceff370ee38db9c44 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 11:21:08 -0700 Subject: [PATCH 009/115] docs site: add pooled llms-full.txt, scope llms.txt to product docs Emit llms-full.txt (every product page concatenated) so a fresh agent can ingest the docs in one fetch instead of guessing which index links to follow. Drop the Contributing section from the agent-facing index; contributor docs are noise for a product-using agent. Intro names the pooled file. Co-Authored-By: Claude Opus 4.8 (1M context) --- mkdocs.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index 27d4c16c..db5b73e5 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -44,11 +44,13 @@ theme: plugins: - search - llmstxt: + full_output: llms-full.txt markdown_description: >- Documentation for Spacedock, a multi-agent orchestrator where nothing ships without a decision. It lives within your existing coding harness (Claude Code, Codex, or Pi), breaks work into stages, and surfaces an - evidenced decision at each gate. + evidenced decision at each gate. This index links the product docs; + llms-full.txt is every page concatenated into one file for a single fetch. sections: Get started: - index.md @@ -61,8 +63,6 @@ plugins: - advanced/*.md Reference: - reference/*.md - Contributing: - - contributing/*.md nav: - Home: index.md From 482a5cb3840ccf54d6ae8c10f076a6aa4cac10e1 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 11:31:08 -0700 Subject: [PATCH 010/115] docs site: sweep prose AI tells across the docs Remove em-dashes from prose (period, comma, colon, or parens), drop two throat-clearing openers, and cut filler. Leave em-dashes that are part of reproduced literal output: the gate-review template, the quoted build notes, the command-reference N/A cell, and the verbatim binary error string. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/site/concepts/gates-and-decisions.md | 2 +- docs/site/concepts/worked-example.md | 2 +- docs/site/concepts/workflows-and-entities.md | 4 +-- docs/site/get-started/first-launch.md | 2 +- docs/site/get-started/first-workflow.md | 6 ++--- docs/site/get-started/install.md | 26 +++++++++----------- docs/site/reference/command-reference.md | 2 +- docs/site/running-workflows/operating.md | 2 +- 8 files changed, 21 insertions(+), 25 deletions(-) diff --git a/docs/site/concepts/gates-and-decisions.md b/docs/site/concepts/gates-and-decisions.md index 0625a9cb..aa139003 100644 --- a/docs/site/concepts/gates-and-decisions.md +++ b/docs/site/concepts/gates-and-decisions.md @@ -56,7 +56,7 @@ When a feedback stage recommends `REJECTED`, or you reject at a `feedback-to` st The first officer tracks each round in a `### Feedback Cycles` section in the entity body, then: 1. Reads the rejected stage's `feedback-to` target. -2. Routes your concrete findings to that target, reusing the live worker in the same worktree when it is still addressable and reuse conditions pass, dispatching fresh otherwise. The routed message carries the fix work and the stage assignment, not just an acknowledgment. +2. Routes your concrete findings to that target, reusing the live worker in the same worktree when it is still addressable and reuse conditions pass, dispatching fresh otherwise. The routed message carries the fix work and the stage assignment, so the worker has what it needs to rework. 3. Re-runs the reviewer after the fix. 4. Re-enters the gate flow with the updated result, presenting you a fresh gate review. diff --git a/docs/site/concepts/worked-example.md b/docs/site/concepts/worked-example.md index 406ec84d..126b1920 100644 --- a/docs/site/concepts/worked-example.md +++ b/docs/site/concepts/worked-example.md @@ -4,7 +4,7 @@ This page traces one real entity, `z9` `codex-plugin-auto-install`, from backlog through to `done` / PASSED, using artifacts from the project repo. It is a concrete read of the abstract stage machine: backlog → ideation → implementation → validation → done, the gates between them, and what the captain -actually decides at each one. +decides at each one. The workflow is `docs/dev` (the Spacedock v1 dev workflow); its stages, gates, and entity schema are defined in diff --git a/docs/site/concepts/workflows-and-entities.md b/docs/site/concepts/workflows-and-entities.md index afb9fe48..43252947 100644 --- a/docs/site/concepts/workflows-and-entities.md +++ b/docs/site/concepts/workflows-and-entities.md @@ -2,8 +2,6 @@ **A workflow is a directory plus a README, and an entity is one markdown file inside it.** The README defines the stages, the schema, and the gates; each entity is a work item that moves through those stages. Everything about a work item lives in the file itself: the problem, the design notes, the bar for done, the stage reports. State survives a session, so the next one picks up where you left off. -This page covers what those two things are, the frontmatter on an entity, and where the entity files actually live at runtime. - ## The workflow: a directory and its README The README is the single source of truth. Its frontmatter declares the stages, the entity type, and the ID style; its prose body defines what each stage means, what counts as good, and what a worker must produce. You commission a workflow with `/spacedock:commission`, which generates the directory, the README, and a few seed entities for you. @@ -68,7 +66,7 @@ The frontmatter is the machine-readable state. The full schema lives in the work | `worktree` | The worktree path while a dispatched agent is active; empty otherwise. | | `issue` | Optional external ticket reference, e.g. `ENG-123`, `kata:task-abc123`, or `owner/repo#42`. | -The frontmatter parser is line-oriented, so keep fields flat and top-level. If a workflow needs more metadata, add more flat custom fields rather than nested YAML — the v1 parser preserves lines, not arbitrary nested structure. +The frontmatter parser is line-oriented, so keep fields flat and top-level. If a workflow needs more metadata, add more flat custom fields rather than nested YAML; the v1 parser preserves lines, not arbitrary nested structure. `status` is the field that drives everything: the first officer reads it to decide which entities are ready to advance. To see the queue, run the status viewer against the workflow directory: diff --git a/docs/site/get-started/first-launch.md b/docs/site/get-started/first-launch.md index 2edfaa56..b6ec3479 100644 --- a/docs/site/get-started/first-launch.md +++ b/docs/site/get-started/first-launch.md @@ -12,7 +12,7 @@ Run it from inside a project that already has some agent history, such as a repo ## What survey reports -In one read-only pass — it never edits your files — survey reconstructs what the agents in this project have implicitly been doing. It leads with **the decisions still open and waiting on you**, then names the [workflow](../concepts/workflows-and-entities.md) you have been running without naming it, the distinct workstreams, and how often you have had to step in, under a one-line headline (project, sessions, date range, decision and interruption counts). If the project has no agent history, it says so and stops. +In one read-only pass (it never edits your files), survey reconstructs what the agents in this project have implicitly been doing. It leads with **the decisions still open and waiting on you**, then names the [workflow](../concepts/workflows-and-entities.md) you have been running without naming it, the distinct workstreams, and how often you have had to step in, under a one-line headline (project, sessions, date range, decision and interruption counts). If the project has no agent history, it says so and stops. For the full section-by-section breakdown and how survey reads your history, see [what survey reports](../running-workflows/survey.md#what-it-reports). diff --git a/docs/site/get-started/first-workflow.md b/docs/site/get-started/first-workflow.md index fb36378d..b5999e83 100644 --- a/docs/site/get-started/first-workflow.md +++ b/docs/site/get-started/first-workflow.md @@ -45,7 +45,7 @@ The skill greets you and walks three phases: **design** (a few questions), on your seed items). In the design phase it asks, one question at a time: what the workflow is for and what each entity is (a "design idea" becomes an `idea`), the stages an entity moves through, which of those stages are gated and where a -rejected entity bounces back to, and the quality bar for each stage — then the +rejected entity bounces back to, and the quality bar for each stage. Last come the entity-ID style and two or three seed items to start on. You confirm or adjust each proposal. The [commission reference](../running-workflows/commission.md#the-four-things-you-name) @@ -61,7 +61,7 @@ what to change and it re-presents. Once you accept, the skill writes the workflow into a new directory under `docs/`: a `README.md` that is the workflow's living spec (mission, schema, and a section per stage with its `Good:` / `Bad:` bar) and one file per seed entity. The -per-stage prose is a best-guess starting point — tighten it before any work runs, +per-stage prose is a best-guess starting point. Tighten it before any work runs, because an agent dispatched against a vague bar is expensive to correct. See [what gets generated](../running-workflows/commission.md#what-gets-generated) for the full file layout and the `review stages` walk. @@ -91,6 +91,6 @@ call that produced it. When you accept the design, the commission skill launches a pilot run on your seed entities: it takes the first-officer role itself, reads the README, and dispatches ensigns to move ready entities through their stages until the workflow -goes idle or reaches a gate. From there you are running the workflow — approving, +goes idle or reaches a gate. From there you are running the workflow: approving, sending back, and resuming in later sessions. [Operating a workflow](../running-workflows/operating.md) covers the day-to-day loop and how to resume. diff --git a/docs/site/get-started/install.md b/docs/site/get-started/install.md index a1181344..56438026 100644 --- a/docs/site/get-started/install.md +++ b/docs/site/get-started/install.md @@ -1,11 +1,8 @@ # Install Spacedock -This guide walks a fresh install end to end and names the output you should see -at each step. Every command here is one you can run and check against the stated -result. - Spacedock plugs into a coding agent harness you already run: Claude Code, Codex, -or Pi. Install one of those first. +or Pi. Install one of those first. Every command below names the output you +should see, so you can check each step against the stated result. Spacedock itself is two pieces that install separately: @@ -14,7 +11,7 @@ Spacedock itself is two pieces that install separately: harness (Claude Code, Codex, or Pi). The recommended setup installs the launcher with Homebrew, then adds the plugin. -Pick your platform, then confirm and launch — those last two steps are the same +Pick your platform, then confirm and launch. Those last two steps are the same everywhere. A from-source build is available for development. ## Install the launcher @@ -28,7 +25,7 @@ everywhere. A from-source build is available for development. === "Linux / no Homebrew" - The Homebrew cask is macOS-only. On Linux — or on macOS without Homebrew — + The Homebrew cask is macOS-only. On Linux (or on macOS without Homebrew), the `curl | sh` script detects your OS and architecture, downloads the matching tarball from the latest GitHub Release, verifies it against the release `checksums.txt`, and installs the `spacedock` binary to @@ -45,7 +42,7 @@ everywhere. A from-source build is available for development. **Sandboxing.** Safehouse behaves the same as on macOS: when a `.safehouse` profile is present in the working directory, Spacedock wraps the launch - through the `safehouse` command. Spacedock ships no sandbox of its own — a + through the `safehouse` command. Spacedock ships no sandbox of its own. A run is sandboxed only when a Linux-capable `safehouse` binary is on your `PATH`; when the binary is absent, Spacedock prints an install hint and the launch proceeds **unsandboxed**. The macOS-only Gatekeeper/quarantine @@ -89,9 +86,9 @@ sandboxed. To set up the plugin ahead of time, or to refresh it later, run With Codex or Pi, launch with the matching subcommand instead: `spacedock codex "your task"` or `spacedock pi "your task"`. -Working on Spacedock itself? See [Build from source](../contributing/build-from-source.md) -in Contributing — it builds the launcher from the `next` branch and loads the -plugin from your checkout so local edits are live. +Working on Spacedock itself? See [Build from source](../contributing/build-from-source.md). +It builds the launcher from the `next` branch and loads the plugin from your +checkout so local edits are live. ## Keep things in sync @@ -107,6 +104,7 @@ first, then run `spacedock install --host claude`. ## Next -Run your [first launch](first-launch.md). For the full launch grammar — the task -argument, what rides after `--`, and the sandbox flags — see the -[command reference](../reference/command-reference.md#launch-claude-codex-pi). +Run your [first launch](first-launch.md). The +[command reference](../reference/command-reference.md#launch-claude-codex-pi) +covers the full launch grammar: the task argument, what rides after `--`, and +the sandbox flags. diff --git a/docs/site/reference/command-reference.md b/docs/site/reference/command-reference.md index fecac593..7468a974 100644 --- a/docs/site/reference/command-reference.md +++ b/docs/site/reference/command-reference.md @@ -10,7 +10,7 @@ The `spacedock` binary has ten subcommands in three groups, plus a top-level | [`spacedock pi`](#launch-claude-codex-pi) | Launch | Start Pi (experimental) with the first officer | | [`spacedock install`](#setup-install-doctor) | Setup | Install the per-host plugin, then run the compatibility check | | [`spacedock doctor`](#setup-install-doctor) | Setup | Run the compatibility check alone | -| [`spacedock status`](#status) | Workflow | Read or mutate workflow state — the table, `--next`, `--where`, `--set`, … | +| [`spacedock status`](#status) | Workflow | Read or mutate workflow state: the table, `--next`, `--where`, `--set`, … | | [`spacedock new`](#new) | Workflow | Create an entity from stdin (alias for `status --new`) | | [`spacedock state`](#state) | Workflow | Manage a split-root workflow's state checkout | | [`spacedock completion`](#completion) | Workflow | Print a bash or zsh completion script | diff --git a/docs/site/running-workflows/operating.md b/docs/site/running-workflows/operating.md index 15fd75fb..19acc174 100644 --- a/docs/site/running-workflows/operating.md +++ b/docs/site/running-workflows/operating.md @@ -60,6 +60,6 @@ It stops and returns to you only at a gate, at a terminal entity's merge ceremon ## Handle gate decisions -A gate stops the loop and hands you the call: the first officer presents the stage report and its review, then waits — it never self-approves. You make one of three calls — **approve**, **send it back with direction**, or **reject**. What each one does, what the gate report carries, and the feedback-cycle cap are covered in full in [the three calls](../concepts/gates-and-decisions.md#the-three-calls). +A gate stops the loop and hands you the call: the first officer presents the stage report and its review, then waits. It never self-approves. You make one of three calls: **approve**, **send it back with direction**, or **reject**. What each one does, what the gate report carries, and the feedback-cycle cap are covered in full in [the three calls](../concepts/gates-and-decisions.md#the-three-calls). When you approve a terminal stage, the entity is closed: the first officer records the merge, sets the `completed` timestamp and `verdict`, clears the worktree, and tears the worker down. At that point the loop returns to the top: run `status --next` and see what moved into reach. From e718e73b04334fb2d51bf4de90fbe160fa78b685 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 11:42:29 -0700 Subject: [PATCH 011/115] docs site: fold authoring directive into AGENTS.md; drop Contributing from the site Rename docs/site/CLAUDE.md to AGENTS.md and fold voice-and-tone.md into it, so one excluded authoring directive owns both doc shape and voice. Update exclude_docs accordingly. Take contributor docs off the published site: exclude docs/site/ contributing/ from the build and replace the Contributing nav section with a single external link to the repo dev README. Rewrite the handful of inbound links (worked-example, stage-lifecycle, frontmatter-contract, command-reference, install, mods) to point at the repo on GitHub, which is the source of truth for contributor docs. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/site/AGENTS.md | 115 ++++++++++++++++++ docs/site/CLAUDE.md | 62 ---------- .../advanced/mods-and-standing-teammates.md | 2 +- docs/site/concepts/stage-lifecycle.md | 2 +- docs/site/concepts/worked-example.md | 2 +- docs/site/contributing/voice-and-tone.md | 64 ---------- docs/site/get-started/install.md | 2 +- docs/site/reference/command-reference.md | 4 +- docs/site/reference/frontmatter-contract.md | 2 +- mkdocs.yml | 16 +-- 10 files changed, 127 insertions(+), 144 deletions(-) create mode 100644 docs/site/AGENTS.md delete mode 100644 docs/site/CLAUDE.md delete mode 100644 docs/site/contributing/voice-and-tone.md diff --git a/docs/site/AGENTS.md b/docs/site/AGENTS.md new file mode 100644 index 00000000..21191579 --- /dev/null +++ b/docs/site/AGENTS.md @@ -0,0 +1,115 @@ +# Authoring directive for `docs/site/` + +**Always apply this when creating or modifying any content under `docs/site/`.** It is the Spacedock adaptation of Recce's documentation-writing standard ([`writing-content/reference/doc.md`](https://github.com/DataRecce/recce-team/blob/main/recce-team/skills/writing-content/reference/doc.md)). It governs both the **shape** of a page (structure and simplicity) and its **voice** (terminology, register, and the tells to avoid). When a question falls outside it, fall back to the `elements-of-style:writing-clearly-and-concisely` (Strunk) skill. + +## The first rule: simple beats complete + +Spacedock is not complicated; wordy docs make it *feel* complicated. Every edit should make the reader's job smaller, not bigger. + +- **Lead with the problem or the payoff, not the definition.** Open each page with why the reader is here and what they will be able to do, then name the mechanism. + - ✗ "Spacedock is a multi-agent orchestrator." + - ✓ "You have work that needs doing in stages, with a human sign-off before anything ships. Spacedock runs that for you." +- **Introduce the fewest terms possible, as late as possible.** Don't front-load a glossary. Define a term on first real use, gloss it once, then just use it. If a page introduces more than a handful of new terms, cut or defer some. +- **Cut, don't pad.** If a sentence still carries its meaning with a clause removed, remove the clause. If a paragraph repeats the page above it, delete it and link instead. +- **Don't repeat content across pages.** One page owns each idea; others link to it. Duplicated explanation is the main thing that makes the docs feel long. +- **Two levels of structure only:** section → page. No deeper nesting; no page that exists only to hold sub-pages. + +## First impression: "simple," not "enterprise" + +The first screen a reader sees should make them feel *"there is one idea here, and I already get it,"* not *"this is a complex system with a manual."* Front-loading vocabulary or role tables is what makes simple software read as enterprise software. + +- **No glossary or role table in the first screen.** Introduce a term only when the next sentence needs it; defer the rest to the page that owns them and link. A roles or personas table near the top reads as enterprise structure. Link to it, do not lead with it. +- **Name the one idea, then say everything else is detail.** Give the reader permission to feel they understand the core before they read on. For Spacedock that idea is: work moves through stages, and nothing crosses a gate without a decision the reader owns. +- **The docs home connects forward, it does not re-pitch.** A reader who arrived from the landing page has already seen the problem and the promise. Do not restate the pain. State the one idea and point into the docs. + +## Pick the page type, then follow its shape + +Every page is one of three types. The nav already sorts roughly this way; match the type to the reader's question. + +| Type | Reader asks | Spacedock sections | Must NOT contain | +|------|-------------|--------------------|------------------| +| **Concept** | "What is this / why does it matter?" | Concepts | Step-by-step instructions (link to the how-to instead) | +| **Tutorial / how-to** | "How do I do X?" | Get started, Running workflows | Long conceptual digressions (link to the concept instead) | +| **Reference** | "What are the options / the exact contract?" | Reference | Narrative prose, tutorial steps | + +### Concept pages +Opening (1–2 sentences: what + why) → how it works (2–4 short paragraphs, ideally one diagram or worked snippet) → when to use / when not → **Related** links (tutorial + reference). Describe the system; don't instruct. If you're numbering steps, you're in the wrong page type. + +### Tutorial / how-to pages +State the goal in one sentence. List prerequisites up front (never bury them mid-page). Numbered steps, **one action per step**, each showing the expected result (name the command *and* the output, e.g. ``spacedock status --next`` then what it prints). End with verification and "next steps" links. Push command-grammar and theory to the bottom or to a linked concept; the reader wants the outcome first. + +### Reference pages +Optimize for lookup in seconds. Use **tables** for flags, fields, and options (Name · Type/required · Description · Default). Give copy-paste examples. Mark required vs optional; show defaults; note edge cases. If a "reference" page is really an explanation, it belongs in Concepts; if it's really a procedure, it belongs in a how-to. + +## Link instead of repeat +- Cross-link liberally with **relative** internal links (so `mkdocs build --strict` resolves them). Concept → tutorial + reference; tutorial → concept + reference; reference → concept. +- Link the first mention of a load-bearing term (`workflow`, `gate`, `ensign`, `commission`) to the page that owns it, rather than re-explaining it. +- Descriptive link text, never "click here". + +## Voice + +This voice is grounded in two real signals, not invented: the root `README.md` (Spacedock's public voice: direct, anti-hype, claim-first, concrete over abstract, second person) and the `comm-officer` mod (`docs/dev/_mods/comm-officer.md`, the project's Strunk-based prose discipline, which defers to this directive when one exists). + +- **Precise, honest, technical.** State what is true and what a thing does. Spacedock's own pitch leads with the claim, not the adjective. +- **No marketing or hype adjectives.** Avoid "powerful", "seamless", "revolutionary", "effortless", "blazing-fast", "game-changing". If a sentence still carries its meaning with the adjective removed, remove it. The product ethos, evidence over assertion, is the writing ethos. +- **Concrete over abstract.** Name the command, the file, the outcome. Prefer "`spacedock status --next` lists the items ready to dispatch" over "Spacedock surfaces actionable work." +- **Claim-first, then support.** Lead a section with the load-bearing sentence; follow with the detail. Mirrors the README's "what's different" bullets (bold claim, then the mechanism). + +## Avoid the AI-writing tells + +Generated prose has a recognizable texture: padded, impersonal, and the fastest way to make simple software feel like a manual. Cut these on sight: + +- **Em-dashes.** Do not use `—`. Rewrite as a period, a comma, a colon, or parentheses. A sentence that needs an em-dash usually wants to be two sentences. (Reproduced literal output, such as a rendered template or a verbatim error string, is exempt: it must match what the tool prints.) +- **The "not just X, but Y" frame** and its cousins ("it's not only…", "more than just…"). State what the thing is. Drop the contrast scaffolding. +- **Rule-of-three padding.** Three parallel adjectives or clauses where one carries the meaning ("clear, simple, and easy to follow"). Keep the load-bearing one. +- **Hollow transitions and hedges.** "That said," "It's worth noting that," "In order to," "It's important to understand." Delete them; start with the content. +- **Empty intensifiers.** "very", "really", "quite", "actually", "simply", "just" (when it adds nothing), "leverage", "utilize". Prefer the plain verb. +- **Throat-clearing openers.** A page or section that opens by restating its own title or announcing what it will cover ("This page covers…", "In this section, we will…"). Open with the content. + +Read it back and remove every word that survives removal. If a sentence sounds like it is performing thoroughness rather than saying something, rewrite it. + +## Tone and register per audience + +- **New-user pages (Get started): welcoming and encouraging, still precise.** Assume no prior Spacedock knowledge; define a term on first use; show the command and the output to expect. Confidence-building, never breezy. +- **Operator pages (Concepts, Running workflows): direct and operational.** The reader is doing the work; tell them the steps and the decision points plainly. +- **Reference pages: exact and unembellished.** Precision outranks warmth. Name the contract, the test, the failure mode. +- **Person and tense.** Second person ("you run", "you approve") and present tense for how-to and instructions, the README's register. Imperative for steps ("Run `spacedock doctor`."). Describe the system in the present tense ("the first officer dispatches an ensign"), not the future. + +## Canonical terminology and capitalization + +Pinned from how the README and skills actually use these forms, not an imposed guess. Use them consistently. + +| Term | Form | Notes (grounded in real usage) | +|------|------|--------------------------------| +| Spacedock | `Spacedock` | The product. Always capitalized. `spacedock` (lowercase, code font) only as the literal command/binary. | +| Captain | `Captain` (role) / `the captain` (prose) | README roles table capitalizes the role name; running prose uses lowercase "the captain" (skills use `{captain}`). The human operator. | +| First Officer | `First Officer` (role) / `the first officer` (prose) | Same pattern: Title Case in the roles table / when naming the role; lowercase in running prose ("the first officer reads the README"). The orchestrator agent. | +| Ensign | `Ensign` (role) / `the ensign`, `ensigns` (prose) | Same pattern. The worker agent that moves one item through one stage. | +| workflow | `workflow` | Common noun, lowercase. A directory of markdown entities + a README. | +| entity | `entity` | Common noun, lowercase. One work item (a markdown file or folder). The README also says "work item"; prefer "entity" in docs, gloss it as "work item" on first use for new users. | +| stage | `stage` | Common noun, lowercase. backlog → ideation → implementation → validation → done. | +| gate | `gate` | Common noun, lowercase. The decision point at the end of a stage. | +| sprint | `sprint` | Common noun, lowercase. A grouped set of entities driven to a deliverable. | +| worktree, mod, safehouse | lowercase | Common nouns. `safehouse` is also the sandbox profile filename `.safehouse`. | + +Rule of thumb: capitalize a **role** when you name it as a role (the roles table, a definition); use lowercase for the same word in ordinary running prose; never capitalize the common-noun primitives (workflow, entity, stage, gate, sprint). + +## Formatting conventions + +- **Commands and code.** Inline code font for commands, flags, filenames, and identifiers: `spacedock claude`, `--strict`, `mkdocs.yml`. Multi-line commands and config in fenced code blocks with a language tag (` ```bash `, ` ```yaml `). +- **Show expected output.** For a command a reader runs, name the result, as `install.md` does ("Prints the installed version, e.g. `spacedock 0.20.0`"). +- **Headings.** Sentence case ("Get started", "Your first workflow"), not Title Case. One `#` h1 per page (the page title); section headings start at `##`. +- **Links.** Descriptive link text, never "click here" / "this link". Internal links are relative so `mkdocs build --strict` can resolve them. +- **Lists and emphasis.** Bullets for parallel items; bold for the load-bearing claim of a bullet (the README pattern). Use emphasis sparingly; if everything is bold, nothing is. + +## Before you commit a docs change +- [ ] Page opens with the problem/payoff, not a definition. +- [ ] Introduces only the terms this page actually needs; each defined on first use. +- [ ] Matches its type's shape (concept / how-to / reference): no steps in concepts, no essays in reference. +- [ ] No content duplicated from another page; shared ideas are linked, not repeated. +- [ ] Internal links are relative and descriptive; first mentions of key terms link out. +- [ ] Ordered lists actually count up (watch for fenced blocks resetting the counter to 1). +- [ ] No AI-writing tells (em-dashes in prose, "not just X but Y", rule-of-three padding, hollow transitions, empty intensifiers, throat-clearing openers). +- [ ] Voice and terminology follow this directive. +- [ ] `mkdocs build --strict` passes. +- [ ] Read it back once and cut every sentence that survives removal. diff --git a/docs/site/CLAUDE.md b/docs/site/CLAUDE.md deleted file mode 100644 index 9076085e..00000000 --- a/docs/site/CLAUDE.md +++ /dev/null @@ -1,62 +0,0 @@ -# Authoring directive for `docs/site/` - -**Always apply this when creating or modifying any content under `docs/site/`.** It is the Spacedock adaptation of Recce's documentation-writing standard ([`writing-content/reference/doc.md`](https://github.com/DataRecce/recce-team/blob/main/recce-team/skills/writing-content/reference/doc.md)). It governs **structure and simplicity**; [`contributing/voice-and-tone.md`](contributing/voice-and-tone.md) governs **voice, terminology, and capitalization**. When they overlap, follow voice-and-tone for wording and this file for shape. When both are silent, fall back to the `elements-of-style:writing-clearly-and-concisely` (Strunk) skill. - -## The first rule: simple beats complete - -Spacedock is not complicated; wordy docs make it *feel* complicated. Every edit should make the reader's job smaller, not bigger. - -- **Lead with the problem or the payoff, not the definition.** Open each page with why the reader is here and what they will be able to do, then name the mechanism. - - ✗ "Spacedock is a multi-agent orchestrator." - - ✓ "You have work that needs doing in stages, with a human sign-off before anything ships. Spacedock runs that for you." -- **Introduce the fewest terms possible, as late as possible.** Don't front-load a glossary. Define a term on first real use, gloss it once, then just use it. If a page introduces more than a handful of new terms, cut or defer some. -- **Cut, don't pad.** If a sentence still carries its meaning with a clause removed, remove the clause. If a paragraph repeats the page above it, delete it and link instead. -- **Don't repeat content across pages.** One page owns each idea; others link to it. Duplicated explanation is the main thing that makes the docs feel long. -- **Two levels of structure only:** section → page. No deeper nesting; no page that exists only to hold sub-pages. - -## First impression: "simple," not "enterprise" - -The first screen a reader sees should make them feel *"there is one idea here, and I already get it,"* not *"this is a complex system with a manual."* Front-loading vocabulary or role tables is what makes simple software read as enterprise software. - -- **No glossary or role table in the first screen.** Introduce a term only when the next sentence needs it; defer the rest to the page that owns them and link. A roles or personas table near the top reads as enterprise structure. Link to it, do not lead with it. -- **Name the one idea, then say everything else is detail.** Give the reader permission to feel they understand the core before they read on. For Spacedock that idea is: work moves through stages, and nothing crosses a gate without a decision the reader owns. -- **The docs home connects forward, it does not re-pitch.** A reader who arrived from the landing page has already seen the problem and the promise. Do not restate the pain. State the one idea and point into the docs. - -## Write it plain: cut the AI tells - -The fastest way to make the docs feel padded is generated-prose texture. The voice rules that catch it (no em-dashes, no "not just X but Y", no rule-of-three padding, no hollow transitions or empty intensifiers) live in [`contributing/voice-and-tone.md`](contributing/voice-and-tone.md) under "Avoid the AI-writing tells." Apply them on every edit. - -## Pick the page type, then follow its shape - -Every page is one of three types. The nav already sorts roughly this way; match the type to the reader's question. - -| Type | Reader asks | Spacedock sections | Must NOT contain | -|------|-------------|--------------------|------------------| -| **Concept** | "What is this / why does it matter?" | Concepts | Step-by-step instructions (link to the how-to instead) | -| **Tutorial / how-to** | "How do I do X?" | Get started, Running workflows | Long conceptual digressions (link to the concept instead) | -| **Reference** | "What are the options / the exact contract?" | Reference | Narrative prose, tutorial steps | - -### Concept pages -Opening (1–2 sentences: what + why) → how it works (2–4 short paragraphs, ideally one diagram or worked snippet) → when to use / when not → **Related** links (tutorial + reference). Describe the system; don't instruct. If you're numbering steps, you're in the wrong page type. - -### Tutorial / how-to pages -State the goal in one sentence. List prerequisites up front (never bury them mid-page). Numbered steps, **one action per step**, each showing the expected result (name the command *and* the output, e.g. ``spacedock status --next`` then what it prints). End with verification and "next steps" links. Push command-grammar and theory to the bottom or to a linked concept; the reader wants the outcome first. - -### Reference pages -Optimize for lookup in seconds. Use **tables** for flags, fields, and options (Name · Type/required · Description · Default). Give copy-paste examples. Mark required vs optional; show defaults; note edge cases. If a "reference" page is really an explanation, it belongs in Concepts; if it's really a procedure, it belongs in a how-to. - -## Link instead of repeat -- Cross-link liberally with **relative** internal links (so `mkdocs build --strict` resolves them). Concept → tutorial + reference; tutorial → concept + reference; reference → concept. -- Link the first mention of a load-bearing term (`workflow`, `gate`, `ensign`, `commission`) to the page that owns it, rather than re-explaining it. -- Descriptive link text, never "click here". - -## Before you commit a docs change -- [ ] Page opens with the problem/payoff, not a definition. -- [ ] Introduces only the terms this page actually needs; each defined on first use. -- [ ] Matches its type's shape (concept / how-to / reference): no steps in concepts, no essays in reference. -- [ ] No content duplicated from another page; shared ideas are linked, not repeated. -- [ ] Internal links are relative and descriptive; first mentions of key terms link out. -- [ ] Ordered lists actually count up (watch for fenced blocks resetting the counter to 1). -- [ ] Voice and terminology follow [`contributing/voice-and-tone.md`](contributing/voice-and-tone.md). -- [ ] `mkdocs build --strict` passes. -- [ ] Read it back once and cut every sentence that survives removal. diff --git a/docs/site/advanced/mods-and-standing-teammates.md b/docs/site/advanced/mods-and-standing-teammates.md index a1d5b52e..7aebab45 100644 --- a/docs/site/advanced/mods-and-standing-teammates.md +++ b/docs/site/advanced/mods-and-standing-teammates.md @@ -76,4 +76,4 @@ The canonical standing teammate is the **comm-officer**: a standing prose-polish The first officer routes through it when composing **deliberate drafts**: PR bodies, gate-review summaries, long narrative entity-body sections, debrief content. It checks team membership first and treats the call as best-effort and non-blocking on the 2-minute timeout; if the comm-officer is absent or silent, the draft ships un-polished. Explicitly **out of scope**: live captain replies, short operational statuses (`pushed`, `tests green`, `PR opened`), tool-call output, commit messages, and transient logs. Polish is a deliberate-draft discipline, not a live-turn reflex. -The comm-officer's prose discipline is light-touch by default: it applies the `elements-of-style:writing-clearly-and-concisely` skill (Strunk) to cut empty words and tighten sentences while preserving the caller's voice, rhythm, and technical vocabulary. It defers to a project voice guide when one exists. For Spacedock's own docs, that guide is the [Voice & tone](../contributing/voice-and-tone.md) page. The comm-officer and any doc contributor follow it, falling back to plain Strunk only where the guide is silent. +The comm-officer's prose discipline is light-touch by default: it applies the `elements-of-style:writing-clearly-and-concisely` skill (Strunk) to cut empty words and tighten sentences while preserving the caller's voice, rhythm, and technical vocabulary. It defers to a project voice guide when one exists. For Spacedock's own docs, that guide is the [authoring directive](https://github.com/spacedock-dev/spacedock/blob/next/docs/site/AGENTS.md). The comm-officer and any doc contributor follow it, falling back to plain Strunk only where the guide is silent. diff --git a/docs/site/concepts/stage-lifecycle.md b/docs/site/concepts/stage-lifecycle.md index a1df6ef9..3f7ae7f5 100644 --- a/docs/site/concepts/stage-lifecycle.md +++ b/docs/site/concepts/stage-lifecycle.md @@ -2,7 +2,7 @@ An entity moves through an ordered chain of stages that the workflow defines, one at a time, and each stage declares the work it owns and the proof it must produce. The dev workflow's chain is `backlog → ideation → implementation → validation → done`; your own workflow names its own stages, but the mechanics are the same. The first officer advances an entity stage by stage, dispatching one ensign per stage and pausing at the gates you declared. -The stage order, names, and per-stage properties live in the workflow README's frontmatter under `stages.states`. This page uses the dev workflow (`docs/site/contributing/development-workflow.md`) as the running example; read that page for the full per-stage Inputs/Outputs/Good/Bad detail. +The stage order, names, and per-stage properties live in the workflow README's frontmatter under `stages.states`. This page uses the dev workflow ([`docs/dev/README.md`](https://github.com/spacedock-dev/spacedock/blob/next/docs/dev/README.md)) as the running example; read that README for the full per-stage Inputs/Outputs/Good/Bad detail. ## What a stage declares diff --git a/docs/site/concepts/worked-example.md b/docs/site/concepts/worked-example.md index 126b1920..4f9c0aaa 100644 --- a/docs/site/concepts/worked-example.md +++ b/docs/site/concepts/worked-example.md @@ -8,7 +8,7 @@ decides at each one. The workflow is `docs/dev` (the Spacedock v1 dev workflow); its stages, gates, and entity schema are defined in -[the development workflow reference](../contributing/development-workflow.md). +[the development workflow README](https://github.com/spacedock-dev/spacedock/blob/next/docs/dev/README.md). Runtime entity state lives in a separate `.spacedock-state` checkout, so the finished entity itself is not in the main tree, but its full trajectory is on the record in the `0198-pre-flip-hardening` sprint directory: `index.md`, diff --git a/docs/site/contributing/voice-and-tone.md b/docs/site/contributing/voice-and-tone.md deleted file mode 100644 index de42caa4..00000000 --- a/docs/site/contributing/voice-and-tone.md +++ /dev/null @@ -1,64 +0,0 @@ -# Voice & tone - -This is the writing-style guide for Spacedock's public documentation. It is grounded in two real voice signals, not invented: - -- **The root `README.md`**: Spacedock's actual public voice. Direct, anti-hype, claim-first ("Spacedock is a multi-agent orchestrator where nothing ships without a decision"), concrete over abstract, second person addressed to the reader. -- **The `comm-officer` mod** (`docs/dev/_mods/comm-officer.md`): the project's prose discipline. It applies the `elements-of-style:writing-clearly-and-concisely` skill (Strunk) and is **light-touch by default**: "Preserve the caller's voice, rhythm, and technical vocabulary. Cut empty words, tighten sentences, fix clear grammar errors." Critically, it **defers to a project voice guide when one exists**. This page is that guide, so the comm-officer and any doc-writer apply it. - -## Voice - -- **Precise, honest, technical.** State what is true and what a thing does. Spacedock's own pitch leads with the claim, not the adjective. -- **No marketing or hype adjectives.** Avoid "powerful", "seamless", "revolutionary", "effortless", "blazing-fast", "game-changing". If a sentence still carries its meaning with the adjective removed, remove it. The product ethos, evidence over assertion, is the writing ethos. -- **Concrete over abstract.** Name the command, the file, the outcome. Prefer "`spacedock status --next` lists the items ready to dispatch" over "Spacedock surfaces actionable work." -- **Claim-first, then support.** Lead a section with the load-bearing sentence; follow with the detail. Mirrors the README's "what's different" bullets (bold claim, then the mechanism). - -## Avoid the AI-writing tells - -Generated prose has a recognizable texture: padded, impersonal, and the fastest way to make simple software feel like a manual. Cut these on sight: - -- **Em-dashes.** Do not use `—`. Rewrite as a period, a comma, a colon, or parentheses. A sentence that needs an em-dash usually wants to be two sentences. -- **The "not just X, but Y" frame** and its cousins ("it's not only…", "more than just…"). State what the thing is. Drop the contrast scaffolding. -- **Rule-of-three padding.** Three parallel adjectives or clauses where one carries the meaning ("clear, simple, and easy to follow"). Keep the load-bearing one. -- **Hollow transitions and hedges.** "That said," "It's worth noting that," "In order to," "It's important to understand." Delete them; start with the content. -- **Empty intensifiers.** "very", "really", "quite", "actually", "simply", "just" (when it adds nothing), "leverage", "utilize". Prefer the plain verb. -- **Throat-clearing openers.** A page or section that opens by restating its own title or announcing what it will cover ("This page covers…", "In this section, we will…"). Open with the content. - -Read it back and remove every word that survives removal. If a sentence sounds like it is performing thoroughness rather than saying something, rewrite it. - -## Tone and register per audience - -- **New-user pages (Get started): welcoming and encouraging, still precise.** Assume no prior Spacedock knowledge; define a term on first use; show the command and the output to expect. Confidence-building, never breezy. -- **Operator pages (Concepts, Running workflows): direct and operational.** The reader is doing the work; tell them the steps and the decision points plainly. -- **Contributor pages (Contributing, Reference): exact and unembellished.** Precision outranks warmth. Name the contract, the test, the failure mode. -- **Person and tense.** Second person ("you run", "you approve") and present tense for how-to and instructions, the README's register. Imperative for steps ("Run `spacedock doctor`."). Describe the system in the present tense ("the first officer dispatches an ensign"), not the future. - -## Canonical terminology and capitalization - -Pinned from how the README and skills actually use these forms, not an imposed guess. Use them consistently. - -| Term | Form | Notes (grounded in real usage) | -|------|------|--------------------------------| -| Spacedock | `Spacedock` | The product. Always capitalized. `spacedock` (lowercase, code font) only as the literal command/binary. | -| Captain | `Captain` (role) / `the captain` (prose) | README roles table capitalizes the role name; running prose uses lowercase "the captain" (skills use `{captain}`). The human operator. | -| First Officer | `First Officer` (role) / `the first officer` (prose) | Same pattern: Title Case in the roles table / when naming the role; lowercase in running prose ("the first officer reads the README"). The orchestrator agent. | -| Ensign | `Ensign` (role) / `the ensign`, `ensigns` (prose) | Same pattern. The worker agent that moves one item through one stage. | -| workflow | `workflow` | Common noun, lowercase. A directory of markdown entities + a README. | -| entity | `entity` | Common noun, lowercase. One work item (a markdown file or folder). The README also says "work item"; prefer "entity" in docs, gloss it as "work item" on first use for new users. | -| stage | `stage` | Common noun, lowercase. backlog → ideation → implementation → validation → done. | -| gate | `gate` | Common noun, lowercase. The decision point at the end of a stage. | -| sprint | `sprint` | Common noun, lowercase. A grouped set of entities driven to a deliverable. | -| worktree, mod, safehouse | lowercase | Common nouns. `safehouse` is also the sandbox profile filename `.safehouse`. | - -Rule of thumb: capitalize a **role** when you name it as a role (the roles table, a definition); use lowercase for the same word in ordinary running prose; never capitalize the common-noun primitives (workflow, entity, stage, gate, sprint). - -## Formatting conventions - -- **Commands and code.** Inline code font for commands, flags, filenames, and identifiers: `spacedock claude`, `--strict`, `mkdocs.yml`. Multi-line commands and config in fenced code blocks with a language tag (` ```bash `, ` ```yaml `). -- **Show expected output.** For a command a reader runs, name the result, as `install.md` does ("Prints the installed version, e.g. `spacedock 0.20.0`"). -- **Headings.** Sentence case ("Get started", "Your first workflow"), not Title Case. One `#` h1 per page (the page title); section headings start at `##`. -- **Links.** Descriptive link text, never "click here" / "this link". Internal links are relative so `mkdocs build --strict` can resolve them. -- **Lists and emphasis.** Bullets for parallel items; bold for the load-bearing claim of a bullet (the README pattern). Use emphasis sparingly; if everything is bold, nothing is. - -## How this guide is applied - -The `comm-officer` mod loads a project voice guide on first use and defers to it over plain Strunk. Once this page ships, it is that guide: doc contributions and comm-officer polish follow these rules. When this guide is silent on a question, fall back to Strunk via `elements-of-style:writing-clearly-and-concisely`. diff --git a/docs/site/get-started/install.md b/docs/site/get-started/install.md index 56438026..27cb27de 100644 --- a/docs/site/get-started/install.md +++ b/docs/site/get-started/install.md @@ -86,7 +86,7 @@ sandboxed. To set up the plugin ahead of time, or to refresh it later, run With Codex or Pi, launch with the matching subcommand instead: `spacedock codex "your task"` or `spacedock pi "your task"`. -Working on Spacedock itself? See [Build from source](../contributing/build-from-source.md). +Working on Spacedock itself? See [Build from source](https://github.com/spacedock-dev/spacedock/blob/next/docs/site/contributing/build-from-source.md). It builds the launcher from the `next` branch and loads the plugin from your checkout so local edits are live. diff --git a/docs/site/reference/command-reference.md b/docs/site/reference/command-reference.md index 7468a974..d3908726 100644 --- a/docs/site/reference/command-reference.md +++ b/docs/site/reference/command-reference.md @@ -193,5 +193,5 @@ Builds the worker dispatch artifacts the first officer hands an ensign. `build` assembles the assignment (requires `--workflow-dir` unless `--print-schema` or validate-only); `show-stage-def` prints a stage's definition (`--workflow-dir` and `--stage`). A missing or unknown subcommand exits 2. See -[Adding a runtime](../contributing/adding-a-runtime.md) for how `dispatch build` -learns a new host mode. +[Adding a runtime](https://github.com/spacedock-dev/spacedock/blob/next/docs/site/contributing/adding-a-runtime.md) +for how `dispatch build` learns a new host mode. diff --git a/docs/site/reference/frontmatter-contract.md b/docs/site/reference/frontmatter-contract.md index ab8703a9..f6fe393c 100644 --- a/docs/site/reference/frontmatter-contract.md +++ b/docs/site/reference/frontmatter-contract.md @@ -1,6 +1,6 @@ # Frontmatter contract -Every entity is a markdown file (or a folder with an `index.md`) whose YAML frontmatter carries the fields Spacedock reads to track and move it. The always-current schema lives in the development workflow's [Schema / Field Reference](../contributing/development-workflow.md#field-reference); this page surfaces that table and the external-tracker bridge fields in one place for reference. A standalone `docs/specs/frontmatter-contract.md` is a planned follow-up; until it lands, the development workflow README is the source of truth. +Every entity is a markdown file (or a folder with an `index.md`) whose YAML frontmatter carries the fields Spacedock reads to track and move it. The always-current schema lives in the development workflow's [Schema / Field Reference](https://github.com/spacedock-dev/spacedock/blob/next/docs/dev/README.md#field-reference); this page surfaces that table and the external-tracker bridge fields in one place for reference. A standalone `docs/specs/frontmatter-contract.md` is a planned follow-up; until it lands, the development workflow README is the source of truth. Keep fields flat and top-level; add more flat custom fields rather than nested YAML. (The [entity frontmatter concept](../concepts/workflows-and-entities.md#entity-frontmatter) explains why the line-oriented parser requires this.) diff --git a/mkdocs.yml b/mkdocs.yml index db5b73e5..c7037654 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -7,9 +7,11 @@ copyright: Spacedock is released under the Apache License 2.0. docs_dir: docs/site -# Internal authoring directive (CLAUDE.md), not a published page. +# Internal authoring directive (AGENTS.md), not a published page. +# Contributor docs are not hosted on the site; the repo is their source of truth. exclude_docs: | - CLAUDE.md + AGENTS.md + contributing/ theme: name: material @@ -88,15 +90,7 @@ nav: - Reference: - Command reference: reference/command-reference.md - Frontmatter contract: reference/frontmatter-contract.md - - Contributing: - - The development workflow: contributing/development-workflow.md - - Build from source: contributing/build-from-source.md - - Agent development: contributing/agent-development.md - - Proof policy: contributing/proof-policy.md - - Adding a runtime: contributing/adding-a-runtime.md - - Releasing: contributing/releasing.md - - Voice & tone: contributing/voice-and-tone.md - - Architecture notes: contributing/architecture-notes.md + - Contributing: https://github.com/spacedock-dev/spacedock/blob/next/docs/dev/README.md extra_css: - stylesheets/tokens.css From ef9fed2ee2d35633080ff352b3e0a00e00123adf Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 11:52:00 -0700 Subject: [PATCH 012/115] docs site: trim Advanced to the abstract mechanism, fold tracker into split-root Cut the Advanced pages down to what the capability is and when to reach for it, with the exact mechanism deferred to the repo as source of truth (placeholder links for now). Mods page keeps the cross-stage/cross- workflow idea and names pr-merge and comm-officer as examples without diving in. Fold the external-tracker draft spec into split-root-state's bridge section and remove the standalone page; repoint the frontmatter- contract link at the new anchor. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/site/advanced/external-tracker.md | 1 - .../advanced/mods-and-standing-teammates.md | 76 ++--------- docs/site/advanced/split-root-state.md | 121 ++---------------- docs/site/reference/frontmatter-contract.md | 2 +- mkdocs.yml | 1 - 5 files changed, 24 insertions(+), 177 deletions(-) delete mode 120000 docs/site/advanced/external-tracker.md diff --git a/docs/site/advanced/external-tracker.md b/docs/site/advanced/external-tracker.md deleted file mode 120000 index 1ded4065..00000000 --- a/docs/site/advanced/external-tracker.md +++ /dev/null @@ -1 +0,0 @@ -../../specs/state-behavior-extension.md \ No newline at end of file diff --git a/docs/site/advanced/mods-and-standing-teammates.md b/docs/site/advanced/mods-and-standing-teammates.md index 7aebab45..bd9fd4fc 100644 --- a/docs/site/advanced/mods-and-standing-teammates.md +++ b/docs/site/advanced/mods-and-standing-teammates.md @@ -1,79 +1,21 @@ # Mods & standing teammates -Mods extend a workflow without touching the binary. A mod is a markdown file under `{workflow_dir}/_mods/`. There are two kinds, and one file can be both: a **lifecycle hook** that the first officer runs at a named point in the run, and a **standing teammate** declaration that spawns a long-lived specialist agent into the team. Both live in `_mods/*.md`. The difference is which sections the file carries and which binary reads them. `spacedock status` scans the `## Hook:` headings (the `--boot` MODS section, and the merge-hook guard); `spacedock dispatch` parses the standing-teammate sections. +Mods extend a workflow without touching the binary. A mod is a markdown file under `{workflow_dir}/_mods/`, and it adds behavior that is the same across stages and across workflows: a step that must happen at a fixed point in every run, or a specialist that should persist across the whole session. The first officer reads the mod and acts on it; nothing compiles. -## Lifecycle hooks - -A mod hook is a `## Hook: {point}` section that the first officer runs at a fixed point in the run. Three points are supported: - -- `startup`: runs once at boot, before the normal dispatch loop. -- `idle`: runs on the idle re-check pass when no entity is ready to dispatch. -- `merge`: runs at the terminal merge boundary for an entity, before any local merge, archival, or status advancement. - -Hooks are additive and run alphabetically by mod filename. The body of a hook section is prose the first officer executes; it names the commands to run and the conditions to branch on, in plain markdown. Nothing compiles; the first officer reads the section and acts on it. - -A mod can register more than one point. The shipped `pr-merge` mod (`docs/dev/_mods/pr-merge.md`) registers all three: its `## Hook: startup` and `## Hook: idle` sections scan for entities with a pending `pr` and advance any whose PR has merged, and its `## Hook: merge` section opens the code-branch PR, records `pr:` on the entity, and blocks until merge. - -### Merge hooks can block, and the mechanism enforces it +A mod does one of two things, or both. -A `merge` hook can wait for captain approval before pushing, or for a remote PR to merge. The first officer signals the wait through the entity `mod-block` field, and `spacedock status` enforces the discipline so a blocked entity cannot slip past the gate: - -- **Set before invoking.** The first officer sets `mod-block=merge:{mod_name}` before running the merge hook: - - ```bash - spacedock status --workflow-dir {workflow_dir} --set {slug} mod-block=merge:{mod_name} - ``` - -- **Guarded.** `spacedock status --set` refuses any terminal transition while `mod-block` is non-empty. `--archive` refuses too. Pass `--force` to override. -- **Required when a merge hook exists.** Independently of `mod-block`, `status --set` and `status --archive` refuse to terminalize or archive an entity when the workflow registers any merge hook (`_mods/*.md` with a `## Hook: merge` section) *and* the entity's `pr` field is empty *and* `mod-block` is empty. This forces the merge ceremony to leave a truthful signal that a merge actually ran. `merge: local` in the workflow README exempts the `pr` requirement; `verdict=rejected` exempts it too (a rejected entity never runs the ceremony). `--force` bypasses everything. -- **Cleared in its own call.** When the blocking action completes, the first officer clears the block: - - ```bash - spacedock status --workflow-dir {workflow_dir} --set {slug} mod-block= - ``` +## Lifecycle hooks - This clear MUST be standalone. `status --set` exits 1 if `mod-block=` is combined with a terminal field (`status={terminal}`, `completed`, `verdict`, or `worktree=`) in one call. Use two commits. +A hook runs first-officer prose at a fixed point in the run: at `startup`, on an `idle` pass when nothing is ready to dispatch, or at the `merge` boundary when an entity terminalizes. The point is workflow-independent: any workflow can register the same hook to get the same behavior. -`mod-block` is read from frontmatter at boot, so a pending merge survives session resume. The first officer picks up which mod is blocking and resumes the wait. +The canonical example is the [`pr-merge` mod](https://github.com/spacedock-dev/spacedock/blob/next/docs/dev/_mods/pr-merge.md): it opens the code-branch PR at merge, records the PR on the entity, and holds the terminal transition until the PR merges. A merge hook can block that transition, and the binary enforces the block so a half-merged entity cannot slip past the gate. ## Standing teammates -A standing teammate is a long-lived specialist agent (a prose polisher, a code reviewer, a translator) declared by a mod with `standing: true` in its frontmatter. It lives in the team for the team's lifetime and is addressed by name. Use one when a recurring specialist judgment is worth a persistent agent rather than a fresh dispatch each time. - -### Declaration - -One mod file per teammate under `{workflow_dir}/_mods/{name}.md`. The parse contract (see `internal/dispatch/mods.go`): - -- **Frontmatter** carries `standing: true` and an optional `description`. -- **`## Hook: startup`** declares the spawn config as `- key: value` bullets. `spacedock dispatch spawn-standing` reads `subagent_type`, `name`, and `model` here; `model` must be one of `sonnet`, `opus`, `haiku`. Backtick-wrapped values are unwrapped. -- **`## Routing Usage`** (optional) is the prose each ensign sees telling it when and how to route to the teammate. -- **`## Agent Prompt`** MUST be the last top-level section. Its body, from the line after the heading to end of file, is the verbatim prompt passed to the spawned agent. Any `## ` heading after it is rejected loudly by `spacedock dispatch spawn-standing`. - -### Lifecycle - -The first officer drives three `spacedock dispatch` subcommands, all reading `_mods/` directly. Do not grep frontmatter yourself: - -```bash -spacedock dispatch list-standing --workflow-dir {wd} # abs mod paths, one per line, sorted -spacedock dispatch spawn-standing --mod {abs_path} --team {team_name} -spacedock dispatch show-standing --workflow-dir {wd} # ensign-facing routing block -``` - -- **Discovery** runs at boot via `list-standing`. It prints the absolute path of each `standing: true` mod, one per line, sorted alphabetically; empty output means none. -- **Spawn is deferred** to the first team-mode dispatch. `spawn-standing` emits an `Agent()` spec for the host to launch, or `{"status": "already-alive", "name": ...}` when the team config already lists that member. Standing teammates are **first-boot-wins**: when several workflows share one team, the first first officer to find the member absent spawns it, and the rest skip. A mod that fails to parse (missing `## Agent Prompt`, an invalid `model`, a trailing heading) is reported and skipped; it does not block the workflow. -- **Routing is best-effort and non-blocking.** Address the teammate by its declared `name`, with a 2-minute timeout. If no reply lands in time, the sender proceeds without the specialist's output. Round-trips of several minutes are normal on long drafts. -- **Teardown is team-scoped.** The teammate dies when the team is torn down (session end, explicit delete, captain shutdown). There is no cross-team or cross-session persistence; mid-session death is detected on the next routing attempt. - -Bare (single-entity) mode and degraded mode still run discovery (it is cheap) but skip the spawn pass, because there is no team to spawn into. - -### Ensign discovery - -Ensigns find standing teammates without the first officer wiring anything per dispatch. When a workflow declares at least one standing teammate, `spacedock dispatch build` appends a `spacedock dispatch show-standing` fetch line to each ensign dispatch. `show-standing` renders a `### Standing teammates available in your team` block, carrying each teammate's `## Routing Usage` body when present and otherwise a one-line fallback, so every dispatched worker learns who to route to. - -## The comm-officer prose-polisher +A standing teammate is a long-lived specialist agent declared by a mod. It lives in the team for the session and is addressed by name. Reach for one when the same specialist judgment recurs across entities and is worth a persistent agent rather than a fresh dispatch each time. -The canonical standing teammate is the **comm-officer**: a standing prose-polisher the first officer routes deliberate drafts through before captain review. By convention it is declared as `_mods/comm-officer.md` with `standing: true` and named `comm-officer`. +The canonical example is the **comm-officer**, a prose-polisher the first officer routes deliberate drafts through (PR bodies, gate summaries, debriefs) before they reach you. Routing is best-effort: if the teammate is absent or slow, the work proceeds without it. -The first officer routes through it when composing **deliberate drafts**: PR bodies, gate-review summaries, long narrative entity-body sections, debrief content. It checks team membership first and treats the call as best-effort and non-blocking on the 2-minute timeout; if the comm-officer is absent or silent, the draft ships un-polished. Explicitly **out of scope**: live captain replies, short operational statuses (`pushed`, `tests green`, `PR opened`), tool-call output, commit messages, and transient logs. Polish is a deliberate-draft discipline, not a live-turn reflex. +## The exact format -The comm-officer's prose discipline is light-touch by default: it applies the `elements-of-style:writing-clearly-and-concisely` skill (Strunk) to cut empty words and tighten sentences while preserving the caller's voice, rhythm, and technical vocabulary. It defers to a project voice guide when one exists. For Spacedock's own docs, that guide is the [authoring directive](https://github.com/spacedock-dev/spacedock/blob/next/docs/site/AGENTS.md). The comm-officer and any doc contributor follow it, falling back to plain Strunk only where the guide is silent. +The mod file format, the hook points, and the `spacedock dispatch` subcommands that read standing-teammate mods are defined in the skills and binary that own them. See [the mods reference](https://github.com/spacedock-dev/spacedock/blob/next/docs/dev/README.md) for the authoritative contract. diff --git a/docs/site/advanced/split-root-state.md b/docs/site/advanced/split-root-state.md index a8d93131..2045f424 100644 --- a/docs/site/advanced/split-root-state.md +++ b/docs/site/advanced/split-root-state.md @@ -1,129 +1,36 @@ # Multi-workflow & split-root state -A split-root workflow separates the workflow's definition from its runtime -state. The README and stage declarations stay on your main branch; the mutable -entities (frontmatter updates, stage reports, archive moves) live in a -separate state checkout. State transitions stop polluting your code branch's -history, and the same workflow definition can drive shared issues without each -status change landing as a commit on `main`. +A split-root workflow separates the workflow's definition from its runtime state. The README and stage declarations stay on your main branch; the mutable entities (frontmatter updates, stage reports, archive moves) live in a separate state checkout. State transitions stop polluting your code branch's history, and several agents or operators can drive the same workflow at once. -You opt in with a single README field. Without it, Spacedock keeps the -default single-root behavior: entities sit beside the README on the same -branch. +Reach for it when status changes would otherwise land as noisy commits on `main`, or when more than one writer needs to advance the same workflow concurrently. Without it, Spacedock keeps the default: entities sit beside the README on the same branch. -## The two roots +## Opt in with one field -A workflow resolves to two directory roles, derived from the README's `state:` -field (`internal/status/roots.go`): - -- **`definition_dir`**: the directory containing `README.md`. It holds the - workflow identity and the stage declarations. This is what you pass as - `--workflow-dir`. -- **`state_dir`**: `definition_dir/` when the README declares a - non-empty `state:` value, otherwise `definition_dir` itself. It holds the - active entities and the `_archive` directory. - -`spacedock status` reads stage declarations from `definition_dir/README.md` and -entities from `state_dir`. It writes frontmatter updates and archive moves only -into `state_dir`. In single-root mode the two roots are the same path, matching -the original same-directory layout, so existing workflows are unaffected. - -## Declare `state:` in the README - -Add a top-level `state:` field to the README frontmatter. The value is a path -relative to the README directory: +Add a `state:` field to the README frontmatter, a path relative to the README directory: ```yaml state: .spacedock-state ``` -The path is resolved against the definition dir. The interpreter -(`internal/status/state.go`) rejects two classes of value rather than following -them silently: - -- An **absolute path** fails: `state:` must be relative to the README directory. -- A path that **escapes the definition dir** via `..` fails: the v0 contract is - a child checkout, not an arbitrary location. - -An empty `state:`, an absent field, or the explicit `$inline` sentinel all -resolve to single-root (inline) mode. The shipped `docs/dev` workflow uses -`state: .spacedock-state`; see its README for a live example. - -Active entities live directly under `state_dir`; there is no `entities/` -subdirectory. Archived entities move to `state_dir/_archive`. Read the state -with the launcher exactly as you would a single-root workflow; the split is -transparent to the command surface: +Spacedock then reads stage declarations from the README and entities from the state path, and writes entity changes only into the state path. The split is transparent to the command surface: read the workflow exactly as you would a single-root one. ```bash spacedock status --workflow-dir docs/dev -spacedock status --workflow-dir docs/dev --next ``` -## The state branch +The shipped `docs/dev` workflow runs split-root; see its README for a live example. -The state checkout lives on an orphan branch in the same repo (no second repo, -no second remote), and the checkout itself is a linked worktree of the main repo -at the gitignored `state:` path. State commits land on the orphan branch, so the -code branch never sees them. Spacedock derives the branch name from the workflow -dir's basename, `spacedock-state/`, so `docs/dev` maps to -`spacedock-state/dev`. An explicit `state-branch:` field in the README overrides -the derived name verbatim (`StateBranch` in `internal/status/state.go`). +## Concurrent writers -Because the branch is shared through `origin`, multiple agents (and multiple -operators) can drive the same workflow concurrently. That makes the commit -discipline below a correctness requirement, not a style preference. +The state checkout is a shared git index that multiple agents commit to, so the commit and sync discipline is a correctness requirement, not a style choice: writers commit path-scoped (never a bare `git add -A`), and conflicting edits to the same entity halt for the captain rather than auto-resolving. The exact protocol is owned by the launcher and the ensign skill; see [the split-root state contract](https://github.com/spacedock-dev/spacedock/blob/next/docs/dev/README.md) for the authoritative rules. -## Concurrency-safe state commits +## Bridging an external tracker -The state checkout is a single, non-branched git index. A bare `git add -A` -followed by a bare `git commit` sweeps up a sibling writer's staged entity, -cross-attributing or clobbering it. **Every writer commits path-scoped**, naming -exactly the entity it touched: +Split-root state is the integration point for an external tracker (Linear, GitHub Issues, kata, or another ticket ledger). The external system can own backlog intake, discussion, and assignment while Spacedock stays the execution workflow. The bridge uses flat top-level frontmatter fields so the parser preserves them: -```bash -git -C {state_checkout} add {entity_path} -git -C {state_checkout} commit -m "..." -- {entity_path} +```yaml +issue: ENG-123 +source: linear ``` -Never a bare `git add -A` or a bare `git commit` against the state checkout. -On `index.lock` contention, retry after roughly two seconds. When the status -tool owns the `add`+`commit` under a lock, route through it instead: a -tool-managed atomic commit is preferred over the manual path-scoped fallback. - -### Multi-writer sync - -The path-scoped rule extends to three sync points against `origin`, not a pull -before every dispatch: - -- **After a state commit, push.** `git -C {state_checkout} push origin {state_branch}`. -- **On a non-fast-forward rejection, rebase then re-push.** - `git -C {state_checkout} pull --rebase origin {state_branch}` replays your - single-file commit atop the peer's. Disjoint paths produce no conflict. -- **At first-officer boot, pull once.** Integrate peers' state at boot, not on - every read. - -If `pull --rebase` conflicts (two writers editing the same entity's frontmatter -at once), the first officer halts the dispatch, aborts the rebase, and surfaces -the conflicting entity and peer commit to the captain. It does not -`--force`-push and does not auto-resolve with `-X ours`/`-X theirs`, either of -which silently drops a peer's edit. A full lock model is out of scope; the halt -is the boundary behavior. - -## Worktree stages under split-root - -When a split-root workflow has a worktree stage, the worktree isolates the -deliverable work product only. The entity body and stage reports are still -written and committed to the state checkout at the entity's state-checkout path, -never a worktree copy. The dispatch helper hands the worker that path even under -a worktree stage. "Commits must be on this branch" applies to the deliverable -artifacts; entity state always lands in the state checkout. - -## Bridging an external tracker - -Split-root state is the integration point for external trackers: Linear, GitHub -Issues, kata, or another ticket ledger. The external system can own backlog -intake, discussion, and assignment while Spacedock remains the execution -workflow. The bridge uses flat top-level frontmatter fields (`issue:`, -`source:`) so the current line-oriented parser preserves them. See the -[external-tracker bridge](external-tracker.md) for the field contract and the -principles that keep Spacedock's stage semantics out of the tracker. +`issue` is the human-facing external reference; `source` records where the entity came from. Keep the tracker out of Spacedock's stage semantics: a bridge should sync through entity creation, state changes, and stage reports, not by adding tracker-specific stage rules. diff --git a/docs/site/reference/frontmatter-contract.md b/docs/site/reference/frontmatter-contract.md index f6fe393c..d4696af3 100644 --- a/docs/site/reference/frontmatter-contract.md +++ b/docs/site/reference/frontmatter-contract.md @@ -48,7 +48,7 @@ Fill `title`, `status`, and `source` at creation. `started`, `completed`, `verdi ## External-tracker fields -The `issue` and `source` fields are the v0 bridge to an external ledger such as kata, Linear, or GitHub Issues. They are flat top-level fields the current parser preserves; the bridge adds no tracker-specific stage rules. See [Tracking work in an external system](../advanced/external-tracker.md) for the full integration model. +The `issue` and `source` fields are the v0 bridge to an external ledger such as kata, Linear, or GitHub Issues. They are flat top-level fields the current parser preserves; the bridge adds no tracker-specific stage rules. See [Multi-workflow & split-root state](../advanced/split-root-state.md#bridging-an-external-tracker) for the full integration model. ```yaml issue: ENG-123 diff --git a/mkdocs.yml b/mkdocs.yml index c7037654..28c021e1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -85,7 +85,6 @@ nav: - Debrief & refit: running-workflows/debrief-and-refit.md - Advanced topics: - Mods & standing teammates: advanced/mods-and-standing-teammates.md - - External-tracker bridge: advanced/external-tracker.md - Multi-workflow & split-root state: advanced/split-root-state.md - Reference: - Command reference: reference/command-reference.md From 6e4afe656417bebb1e15effa5a118e20e0662e2f Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 11:53:15 -0700 Subject: [PATCH 013/115] docs site: trim Reference to a map, defer the spec to --help and the README Command reference becomes an orienting map: the command table plus one line of what/when per command, with the exact flags deferred to spacedock --help as the source of truth. Frontmatter contract keeps the field lookup table and copy-paste starter but drops the behavioral prose that mirrors the binary; the dev workflow README owns the authoritative schema. Repoint the install link at the new #launch anchor. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/site/get-started/install.md | 2 +- docs/site/reference/command-reference.md | 204 +++----------------- docs/site/reference/frontmatter-contract.md | 46 ++--- 3 files changed, 40 insertions(+), 212 deletions(-) diff --git a/docs/site/get-started/install.md b/docs/site/get-started/install.md index 27cb27de..e216d9df 100644 --- a/docs/site/get-started/install.md +++ b/docs/site/get-started/install.md @@ -105,6 +105,6 @@ first, then run `spacedock install --host claude`. ## Next Run your [first launch](first-launch.md). The -[command reference](../reference/command-reference.md#launch-claude-codex-pi) +[command reference](../reference/command-reference.md#launch) covers the full launch grammar: the task argument, what rides after `--`, and the sandbox flags. diff --git a/docs/site/reference/command-reference.md b/docs/site/reference/command-reference.md index d3908726..0d5064b9 100644 --- a/docs/site/reference/command-reference.md +++ b/docs/site/reference/command-reference.md @@ -1,197 +1,45 @@ # Command reference -The `spacedock` binary has ten subcommands in three groups, plus a top-level -`--version`: +The `spacedock` binary has ten subcommands in three groups, plus a top-level `--version`. This page is the map: what each command is for and when you reach for it. For the exact flags of any command, run `spacedock --help`, which is the always-current source of truth. | Command | Group | What it does | |---------|-------|--------------| -| [`spacedock claude`](#launch-claude-codex-pi) | Launch | Start Claude Code with the first officer loaded | -| [`spacedock codex`](#launch-claude-codex-pi) | Launch | Start Codex (experimental) with the first officer | -| [`spacedock pi`](#launch-claude-codex-pi) | Launch | Start Pi (experimental) with the first officer | -| [`spacedock install`](#setup-install-doctor) | Setup | Install the per-host plugin, then run the compatibility check | -| [`spacedock doctor`](#setup-install-doctor) | Setup | Run the compatibility check alone | -| [`spacedock status`](#status) | Workflow | Read or mutate workflow state: the table, `--next`, `--where`, `--set`, … | -| [`spacedock new`](#new) | Workflow | Create an entity from stdin (alias for `status --new`) | -| [`spacedock state`](#state) | Workflow | Manage a split-root workflow's state checkout | -| [`spacedock completion`](#completion) | Workflow | Print a bash or zsh completion script | -| [`spacedock dispatch`](#dispatch) | Workflow | Build the worker dispatch artifacts the first officer hands an ensign | -| [`spacedock --version`](#-version) | — | Print the binary version and the contract level | +| [`spacedock claude`](#launch) | Launch | Start Claude Code with the first officer loaded | +| [`spacedock codex`](#launch) | Launch | Start Codex (experimental) with the first officer | +| [`spacedock pi`](#launch) | Launch | Start Pi (experimental) with the first officer | +| [`spacedock install`](#setup) | Setup | Install the per-host plugin, then run the compatibility check | +| [`spacedock doctor`](#setup) | Setup | Run the compatibility check alone | +| [`spacedock status`](#workflow) | Workflow | Read or mutate workflow state: the table, `--next`, `--where`, `--set` | +| [`spacedock new`](#workflow) | Workflow | Create an entity from stdin | +| [`spacedock state`](#workflow) | Workflow | Manage a split-root workflow's state checkout | +| [`spacedock completion`](#workflow) | Workflow | Print a bash or zsh completion script | +| [`spacedock dispatch`](#workflow) | Workflow | Build the dispatch artifacts the first officer hands an ensign | +| `spacedock --version` | | Print the binary version and the contract level | -Run `spacedock` with no arguments to print the grouped help, and -`spacedock --help` for a command's own flags. An unknown command or a -stray leading flag exits 2 with a diagnostic on stderr. The verbs are registered -in `internal/cli/cli.go`. +Run `spacedock` with no arguments for the grouped help, and `spacedock --help` for a command's own flags. -## --version +## Launch -```bash -spacedock --version -``` - -Prints the binary version and the contract level, e.g. `spacedock 0.20.0 (contract 1)`. -The `(contract N)` token is load-bearing: the first-officer and ensign skills -read it to check the launcher and the installed plugin agree. The version string -defaults to the `dev` sentinel and is overwritten by the release pipeline's -linker stamp, so an unstamped `go build` reads as a dev build rather than -impersonating a release. - -## Launch: claude, codex, pi - -`spacedock claude`, `spacedock codex`, and `spacedock pi` each start the named -host with the Spacedock first officer loaded. Claude Code is the primary surface; -Codex and Pi are supported but experimental. The grammar is the same for all -three: +`spacedock claude`, `spacedock codex`, and `spacedock pi` start the named host with the first officer loaded. Claude Code is the primary surface; Codex and Pi are experimental. The grammar is the same for all three: ```bash spacedock claude [task] [spacedock-flags] [-- host-flags] ``` -- **The task comes first.** Positionals before `--` join with single spaces into - the launch prompt handed to the first officer. With no task, a fixed bootstrap - prompt starts the first officer rather than opening an idle agent. -- **Everything after `--` forwards verbatim to the host** (`claude` / `codex` / - `pi`): `--model`, `--resume`, `--plugin-dir`, and the like. A task placed - after `--` is host passthrough, not the launch prompt; the launcher warns on - stderr when it detects this without altering the assembled argv. -- **The launch is contract-gated.** When no plugin is installed, the launcher - auto-installs it then launches, so the single command yields a working session. - `--no-install` opts out and prints the manual install remedy. A contract - mismatch fails fast (exit 1), since auto-installing would not fix it. - -Spacedock-owned launch flags, declared in `internal/cli/frontdoor.go`: - -- `--safehouse`: force the safehouse sandbox wrap even without a `.safehouse` - profile in the working directory. A `.safehouse` profile triggers the wrap - automatically. -- `--safehouse-enable KEY[,KEY]`, `--safehouse-add-dirs DIR`, - `--safehouse-add-dirs-ro DIR`: repeatable sandbox knobs whose presence also - implies sandbox-on. -- `--plugin-dir DIR`: load a local plugin checkout, relaxing the contract gate. - Repeatable, and accepted both before `--` (parsed by spacedock) and after `--` - (forwarded verbatim). -- `--skip-contract-check`: bypass the contract gate and launch without resolving - the installed plugin. -- `--no-install`: refuse to auto-install a missing plugin and print instructions - instead. - -The contract gate is bypassed by `--skip-contract-check` or by any `--plugin-dir` -(the local checkout supersedes the installed plugin). `spacedock pi` loads Pi's -native skills and extension rather than a plugin manifest; its only spacedock -flag is `--plugin-dir`. - -## Setup: install, doctor - -`spacedock install` installs the per-host plugin, then runs the compatibility -check. `spacedock doctor` runs the check alone. - -```bash -spacedock install [--host claude|codex|pi] [--check] -spacedock doctor [--host claude|codex|pi] -``` - -- `--host` defaults to `claude`. For `codex`, install prints the `codex plugin` - commands to run from your shell rather than running them programmatically. -- `install --check` runs the compatibility report without installing. -- `doctor --plugin-manifest PATH` reads a manifest directly instead of resolving - the installed plugin. - -When `doctor` reports the installed plugin is out of date, refresh it with -`spacedock install --host claude`. See [Install Spacedock](../get-started/install.md) -for the full setup path. +The task comes first and becomes the launch prompt. Anything after `--` forwards verbatim to the host (`--model`, `--resume`, and the like). When no plugin is installed, the launcher auto-installs it and launches, so the single command yields a working session; a contract mismatch fails fast. The sandbox flags (`--safehouse` and its knobs) and the contract-gate flags are listed by `spacedock claude --help`. -## Workflow: status, new, state, completion, dispatch - -These commands read and mutate workflow state. `status` and `dispatch` forward -their argv verbatim to their runners; the launcher neither parses nor reorders -their flags. - -### status - -```bash -spacedock status [args] -``` +## Setup -`spacedock status` resolves the workflow it acts on in this precedence: an -explicit `--workflow-dir DIR` (or the `PIPELINE_DIR` environment variable) is used -verbatim; otherwise it walks up from the working directory to the enclosing -commissioned workflow. With neither, it exits 1 with -`no Spacedock workflow here — pass --workflow-dir or run inside a workflow`. The -exit domain is `{0 success, 1 error}`, so a usage error is exit 1, never 2. +`spacedock install` installs the per-host plugin, then runs the compatibility check; `spacedock doctor` runs the check alone. Both take `--host claude|codex|pi` (default `claude`). When `doctor` reports the plugin is out of date, refresh it with `spacedock install`. See [Install Spacedock](../get-started/install.md) for the full setup path. -The query forms, parsed in `internal/status/native_runner.go`: +## Workflow -- **No flag**: prints the active-entity status table. `--archived` includes - archived entities; `--quiet` and `--json` change the rendering. -- `--next` prints the items ready to dispatch (requires a stages block in the - README). -- `--next-id` computes the next entity id. It accepts `--id-seed` and `--id-actor` - (valid only with `--next-id` or `--new`). -- `--boot` prints the first-officer boot view (queue, stages, team state). It is - incompatible with `--next`, `--next-id`, `--archived`, `--where`, and - `--fields`/`--all-fields`. -- `--validate` validates the workflow. It prints `VALID` and exits 0, or prints the - errors and exits 1. -- `--resolve REF` resolves a reference to one entity and prints its resolve line. - With `--root ROOT` it resolves across every workflow under `ROOT`, accepting a - `workflow::ref` qualifier. -- `--short-id REF` prints an entity's short display id. -- `--set SLUG field=value...` mutates an entity's frontmatter. Bare `completed` - and `started` auto-fill a timestamp; every other field requires a value. - Terminal transitions are gated (mod-block, merge-hook, verdict, and the - require-external-proof guards); `--force` bypasses with a warning. -- `--archive SLUG` archives an entity. -- `--discover [--root ROOT]` prints the commissioned workflows under `ROOT` - (default: the git toplevel of the working directory). It is incompatible with - every other flag. -- `--where 'field = value'` filters the table. It supports `=`, `!=`, `field =` - (empty), and `field !=` (non-empty), and is repeatable. -- `--fields a,b,c` / `--all-fields` chooses the columns. The two are mutually - exclusive. +These commands read and mutate workflow state. -Most flags refuse to combine; the runner names the conflict and exits 1 (e.g. -`--set cannot be combined with --next`). - -### new - -```bash -echo "entity body" | spacedock new [--folder] SLUG -``` - -A pure alias for `status --new`: it prefixes the argv with `--new` and forwards -it, reading the entity body from stdin and auto-discovering the workflow. -`--folder` creates the entity as a folder rather than a single file. - -### state - -```bash -spacedock state init|new [--workflow-dir DIR] -``` - -Manages a split-root workflow's state checkout. `init` resumes a cloned workflow -by fetching the orphan state branch and checking it out as a linked worktree at -the workflow's `state:` path; a present checkout is a no-op that refreshes from -origin. `new` births that branch and worktree around a present split-root README. -An inline workflow has nothing to init. A missing or unknown subcommand exits 2. - -### completion - -```bash -spacedock completion bash|zsh -``` - -Prints a static shell-completion script for bash or zsh (exit 0). It completes -the top-level verbs and the common `status` flags. A missing or unknown shell -exits 2. - -### dispatch - -```bash -spacedock dispatch build | show-stage-def -``` +- **`status`** is the main one: with no flag it prints the entity table, `--next` lists what is ready to dispatch, `--where` filters, `--set` mutates frontmatter, `--validate` checks the workflow, and `--boot` prints the first-officer boot view. It resolves the workflow from `--workflow-dir`, then `PIPELINE_DIR`, then by walking up to the enclosing workflow. The day-to-day reads are covered in [Operating a workflow](../running-workflows/operating.md). +- **`new`** creates an entity from stdin. +- **`state`** initializes or creates the state checkout for a [split-root workflow](../advanced/split-root-state.md). +- **`completion`** prints a bash or zsh completion script. +- **`dispatch`** builds the worker dispatch artifacts the first officer hands an ensign. -Builds the worker dispatch artifacts the first officer hands an ensign. `build` -assembles the assignment (requires `--workflow-dir` unless `--print-schema` or -validate-only); `show-stage-def` prints a stage's definition (`--workflow-dir` -and `--stage`). A missing or unknown subcommand exits 2. See -[Adding a runtime](https://github.com/spacedock-dev/spacedock/blob/next/docs/site/contributing/adding-a-runtime.md) -for how `dispatch build` learns a new host mode. +Run `spacedock status --help` (and the same for each command) for the full flag list, the mutation guards, and the exit codes. diff --git a/docs/site/reference/frontmatter-contract.md b/docs/site/reference/frontmatter-contract.md index d4696af3..adb4810c 100644 --- a/docs/site/reference/frontmatter-contract.md +++ b/docs/site/reference/frontmatter-contract.md @@ -1,29 +1,27 @@ # Frontmatter contract -Every entity is a markdown file (or a folder with an `index.md`) whose YAML frontmatter carries the fields Spacedock reads to track and move it. The always-current schema lives in the development workflow's [Schema / Field Reference](https://github.com/spacedock-dev/spacedock/blob/next/docs/dev/README.md#field-reference); this page surfaces that table and the external-tracker bridge fields in one place for reference. A standalone `docs/specs/frontmatter-contract.md` is a planned follow-up; until it lands, the development workflow README is the source of truth. +Every entity is a markdown file (or a folder with an `index.md`) whose YAML frontmatter carries the fields Spacedock reads to track and move it. This page is a quick lookup for the fields a development-workflow entity uses. The always-current schema is owned by the [development workflow README](https://github.com/spacedock-dev/spacedock/blob/next/docs/dev/README.md#field-reference); when this table and that README disagree, the README wins. Keep fields flat and top-level; add more flat custom fields rather than nested YAML. (The [entity frontmatter concept](../concepts/workflows-and-entities.md#entity-frontmatter) explains why the line-oriented parser requires this.) ## Entity fields -These are the fields the development workflow declares for a `task` entity. Other workflows may rename the entity type and adjust fields, but these are the contract a dev-workflow entity must satisfy. +These are the fields the development workflow declares for a `task` entity. Other workflows may rename the entity type and adjust fields. | Field | Type | Description | |-------|------|-------------| -| `id` | string | Unique 24-character Spacedock Base32 ID, because this workflow uses `id-style: sd-b32`. | +| `id` | string | Unique 24-character Spacedock Base32 ID (this workflow uses `id-style: sd-b32`). | | `title` | string | Human-readable entity name. | -| `status` | enum | One of: `backlog`, `ideation`, `implementation`, `validation`, `done`. The current stage. | -| `source` | string | Where the entity came from. Also used by the external-tracker bridge (see below). | +| `status` | enum | The current stage: `backlog`, `ideation`, `implementation`, `validation`, or `done`. | +| `source` | string | Where the entity came from. Also used by the external-tracker bridge. | | `started` | ISO 8601 | When active work began. | | `completed` | ISO 8601 | When the entity reached terminal status. | -| `verdict` | enum | `PASSED` or `REJECTED`. Set at the final stage. | -| `score` | number | Priority score, `0.0`–`1.0` (optional). A workflow can upgrade to a multi-dimension rubric in its README. | +| `verdict` | enum | `PASSED` or `REJECTED`, set at the final stage. A terminal close requires it; see [gates and decisions](../concepts/gates-and-decisions.md#the-three-calls). | +| `score` | number | Priority score, `0.0`–`1.0` (optional). | | `worktree` | string | Worktree path while a dispatched agent is active; empty otherwise. | -| `issue` | string | Optional external ticket reference, such as `ENG-123`, `kata:task-abc123`, or `owner/repo#42`. | +| `issue` | string | Optional external ticket reference, such as `ENG-123` or `owner/repo#42`. | -The `status` field is the execution state. `spacedock status` reads stage declarations from the workflow README and reports each entity's `status` against them; `--set status=` is the mutation that advances an entity. The status read path does not invent stages. If the README declares no stages block, membership cannot be validated. - -The `verdict` field is guarded on the finalize action, not on reaching a terminal stage: writing `completed` (via `--set`) or archiving a terminal entity is refused with exit 1 (entity unmutated) when `verdict` is empty, and `--force` bypasses. A bare dispatch into a terminal stage that does not write `completed` passes without a verdict. See [gates and decisions](../concepts/gates-and-decisions.md#the-three-calls) for why a terminal close requires a verdict. +`status` is the execution state: `spacedock status` reports each entity's `status` against the README's stage declarations, and `--set status=` advances it. The fields the runtime writes (`started`, `completed`, `verdict`, `worktree`) should not be hand-edited while a dispatched agent is active. ## Copy-paste starter @@ -44,36 +42,18 @@ issue: --- ``` -Fill `title`, `status`, and `source` at creation. `started`, `completed`, `verdict`, and `worktree` are written by the runtime as the entity moves; do not edit them by hand while a dispatched agent is active. +Fill `title`, `status`, and `source` at creation; the runtime writes the rest as the entity moves. ## External-tracker fields -The `issue` and `source` fields are the v0 bridge to an external ledger such as kata, Linear, or GitHub Issues. They are flat top-level fields the current parser preserves; the bridge adds no tracker-specific stage rules. See [Multi-workflow & split-root state](../advanced/split-root-state.md#bridging-an-external-tracker) for the full integration model. - -```yaml -issue: ENG-123 -source: linear -``` - -or: - -```yaml -issue: kata:task-abc123 -source: kata -``` - -The contract for these two fields: - -- **`issue` is the human-facing external reference.** It points at the ticket the entity mirrors; Spacedock does not parse its internals. -- **`source` records where the entity came from** when useful: the tracker name, or any origin marker. -- **Spacedock `status` remains the execution status.** The external tracker does not redefine Spacedock stage semantics inside the entity, and ownership stays one-way unless a future bridge explicitly declares bidirectional sync. +`issue` and `source` are the bridge to an external ledger (Linear, GitHub Issues, kata). `issue` is the human-facing ticket reference; `source` records the origin. Spacedock `status` stays the execution status, and the tracker does not redefine stage semantics inside the entity. See [Multi-workflow & split-root state](../advanced/split-root-state.md#bridging-an-external-tracker) for the full bridge model. ## Validating an entity -Check an entity against the contract with the status command's `--validate` flag: +Check the workflow and its entities against the contract: ```bash spacedock status --workflow-dir docs/dev --validate ``` -It exits 0 when the workflow is valid and 1 when it is not, printing the errors to stderr; with `--json` it also emits a `{"command":"validate","valid":"true"}` (or `"false"`) envelope. `--validate` cannot be combined with the other status flags: `--next`, `--next-id`, `--boot`, `--where`, `--fields`/`--all-fields`, `--archived`, `--archive`, or `--set`; the command rejects the combination. Validation reads stages from the workflow README and entities from the state checkout, so it enforces the contract against the same schema the workflow declares, not an assumed one. +It exits 0 when valid, 1 with errors on stderr otherwise. Validation reads stages from the README and entities from the state checkout, so it enforces the schema the workflow declares. From 7e5b4a9ce04a16c9ed0e398e972840b26926b275 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 11:56:57 -0700 Subject: [PATCH 014/115] docs site: merge Home into Get started; fix landing nav links Fold the docs Home page into the Get started section as "Welcome" so there is one entry, not a separate top-level Home. In the site chrome, replace the fragile landing-page anchor links (#how-it-works, #who) with a single Home link to https://spacedock.md. Co-Authored-By: Claude Opus 4.8 (1M context) --- mkdocs.yml | 2 +- overrides/partials/nav-links.html | 4 +--- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index 28c021e1..3a848267 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -67,8 +67,8 @@ plugins: - reference/*.md nav: - - Home: index.md - Get started: + - Welcome: index.md - Install: get-started/install.md - Your first launch: get-started/first-launch.md - Your first workflow: get-started/first-workflow.md diff --git a/overrides/partials/nav-links.html b/overrides/partials/nav-links.html index d2fc1523..62f90bcd 100644 --- a/overrides/partials/nav-links.html +++ b/overrides/partials/nav-links.html @@ -1,7 +1,5 @@ -{#- Generated from tokens/nav-links.json -- do not edit here; edit the source and regenerate. -#} From 8d1fa1a8752f3f0b741a3eb728a6374f2553f0ff Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 11:57:42 -0700 Subject: [PATCH 015/115] docs site: stage-lifecycle leads with the example, then the properties Put "The dev workflow's stages" before "What a stage declares" so the page shows the concrete pipeline first and explains the per-stage properties after. Fold the running-example pointer into that section. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/site/concepts/stage-lifecycle.md | 22 ++++++++++------------ 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/docs/site/concepts/stage-lifecycle.md b/docs/site/concepts/stage-lifecycle.md index 3f7ae7f5..c0dfef64 100644 --- a/docs/site/concepts/stage-lifecycle.md +++ b/docs/site/concepts/stage-lifecycle.md @@ -2,11 +2,19 @@ An entity moves through an ordered chain of stages that the workflow defines, one at a time, and each stage declares the work it owns and the proof it must produce. The dev workflow's chain is `backlog → ideation → implementation → validation → done`; your own workflow names its own stages, but the mechanics are the same. The first officer advances an entity stage by stage, dispatching one ensign per stage and pausing at the gates you declared. -The stage order, names, and per-stage properties live in the workflow README's frontmatter under `stages.states`. This page uses the dev workflow ([`docs/dev/README.md`](https://github.com/spacedock-dev/spacedock/blob/next/docs/dev/README.md)) as the running example; read that README for the full per-stage Inputs/Outputs/Good/Bad detail. +## The dev workflow's stages + +This page uses the dev workflow as the running example. Its five stages below are this workflow's stages, not a canonical set; the full per-stage Inputs/Outputs/Good/Bad detail lives in its [README](https://github.com/spacedock-dev/spacedock/blob/next/docs/dev/README.md). Read the chain as a pipeline: each stage takes the prior stage's output as its input, and the bar rises from "is this clear?" to "is this proven?". + +- **`backlog`, the seed.** An entity enters here when first proposed: a title, a source, a brief description, and the test gates future stages must satisfy. No design work yet. `initial: true`, so this is where every new entity starts. The dev workflow also marks it `gate: true`, so the first officer presents a new entity for your go-ahead before it advances. +- **`ideation`, the design.** A worker clarifies the problem, explores approaches, and produces a fleshed-out body: problem statement, proposed approach, acceptance criteria, and a test plan. Each acceptance criterion names how it will be checked. This stage is `gate: true` in the dev workflow, so the first officer presents the design for your approval before any code is written. +- **`implementation`, the deliverable.** A worker produces the change the entity describes: code, fixtures, instruction text, on-disk state. This stage is `worktree: true`, so the work happens in an isolated checkout. Implementation completing is not a stopping point. A completed, non-gated stage routes straight on to validation. +- **`validation`, the independent check.** A worker verifies the deliverable against the acceptance criteria. It checks what was produced; it does not produce the deliverable itself. It reproduces the evidence each `AC-N` cites and returns a `PASSED` or `REJECTED` recommendation. This stage is `worktree: true`, `fresh: true`, `feedback-to: implementation`, and `gate: true`. +- **`done`, the verdict.** Validation is complete and you approve the result. The entity is closed with a `verdict` of `PASSED` or `REJECTED` and a `completed` timestamp. `terminal: true`. ## What a stage declares -Each entry under `stages.states` is a stage name plus a set of boolean or string properties. The first officer reads these to decide how to dispatch and when to stop. A `stages.defaults` block sets the baseline; a stage entry overrides it. The properties that change behavior: +The stage order, names, and the properties each stage carries live in the workflow README's frontmatter under `stages.states`. Each entry is a stage name plus a set of boolean or string properties the first officer reads to decide how to dispatch and when to stop. A `stages.defaults` block sets the baseline; a stage entry overrides it. The properties that change behavior: | Property | Effect | |----------|--------| @@ -21,16 +29,6 @@ Each entry under `stages.states` is a stage name plus a set of boolean or string Beyond these properties, the prose of each stage's `###` subsection in the README is the stage definition: its Inputs, Outputs, and the Good/Bad bar. The first officer copies that subsection verbatim into the ensign's assignment, so what a stage declares in prose is exactly what the worker is told to do. -## The dev workflow's stages - -These five are this workflow's stages, not a canonical set. Read the chain as a pipeline: each stage takes the prior stage's output as its input, and the bar rises from "is this clear?" to "is this proven?". - -- **`backlog`, the seed.** An entity enters here when first proposed: a title, a source, a brief description, and the test gates future stages must satisfy. No design work yet. `initial: true`, so this is where every new entity starts. The dev workflow also marks it `gate: true`, so the first officer presents a new entity for your go-ahead before it advances. -- **`ideation`, the design.** A worker clarifies the problem, explores approaches, and produces a fleshed-out body: problem statement, proposed approach, acceptance criteria, and a test plan. Each acceptance criterion names how it will be checked. This stage is `gate: true` in the dev workflow, so the first officer presents the design for your approval before any code is written. -- **`implementation`, the deliverable.** A worker produces the change the entity describes: code, fixtures, instruction text, on-disk state. This stage is `worktree: true`, so the work happens in an isolated checkout. Implementation completing is not a stopping point. A completed, non-gated stage routes straight on to validation. -- **`validation`, the independent check.** A worker verifies the deliverable against the acceptance criteria. It checks what was produced; it does not produce the deliverable itself. It reproduces the evidence each `AC-N` cites and returns a `PASSED` or `REJECTED` recommendation. This stage is `worktree: true`, `fresh: true`, `feedback-to: implementation`, and `gate: true`. -- **`done`, the verdict.** Validation is complete and you approve the result. The entity is closed with a `verdict` of `PASSED` or `REJECTED` and a `completed` timestamp. `terminal: true`. - ## Fresh context at validation Validation declares `fresh: true` because the reviewer must not be the maker. The first officer normally reuses a live worker across consecutive stages to save context, but a `fresh: true` stage forces a new dispatch every time. The validator arrives without the implementer's reasoning in its context, sees only the entity body and the deliverable, and pushes back on thin evidence. This is the mechanism behind the README's claim that "the agent doesn't get to judge its own work." From d463dc2f6a03dd2785e65f0222fd71ee244f7ed2 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 12:04:34 -0700 Subject: [PATCH 016/115] docs site: contributing stub under Reference, points proposals to issues Replace the external Contributing nav link with a short stub page nested under Reference (not its own top-level section). It thanks contributors and, since the project is early, directs proposals and improvements to GitHub issues rather than direct pull requests. The contributor and maintainer docs under contributing/ stay off the published site. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/site/contributing.md | 3 +++ mkdocs.yml | 2 +- 2 files changed, 4 insertions(+), 1 deletion(-) create mode 100644 docs/site/contributing.md diff --git a/docs/site/contributing.md b/docs/site/contributing.md new file mode 100644 index 00000000..f5a3d6af --- /dev/null +++ b/docs/site/contributing.md @@ -0,0 +1,3 @@ +# Contributing + +Thanks for considering a contribution. Spacedock is early, so we encourage you to share proposals and improvements as [GitHub issues](https://github.com/spacedock-dev/spacedock/issues) rather than opening pull requests directly. That lets us discuss the direction before anyone writes code. diff --git a/mkdocs.yml b/mkdocs.yml index 3a848267..9f59b458 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -89,7 +89,7 @@ nav: - Reference: - Command reference: reference/command-reference.md - Frontmatter contract: reference/frontmatter-contract.md - - Contributing: https://github.com/spacedock-dev/spacedock/blob/next/docs/dev/README.md + - Contributing: contributing.md extra_css: - stylesheets/tokens.css From 2afb7fd2e655cc92646fd056e3246175b5180539 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 12:05:41 -0700 Subject: [PATCH 017/115] docs: add top-level CONTRIBUTING.md; link it from the docs nav Add a repo-root CONTRIBUTING.md: Spacedock is early, so it points contributors at GitHub issues for proposals and improvements rather than direct pull requests. Replace the docs-site contributing stub with a Reference-section nav link to that file on GitHub. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/site/contributing.md => CONTRIBUTING.md | 0 mkdocs.yml | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) rename docs/site/contributing.md => CONTRIBUTING.md (100%) diff --git a/docs/site/contributing.md b/CONTRIBUTING.md similarity index 100% rename from docs/site/contributing.md rename to CONTRIBUTING.md diff --git a/mkdocs.yml b/mkdocs.yml index 9f59b458..47831f7d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -89,7 +89,7 @@ nav: - Reference: - Command reference: reference/command-reference.md - Frontmatter contract: reference/frontmatter-contract.md - - Contributing: contributing.md + - Contributing: https://github.com/spacedock-dev/spacedock/blob/next/CONTRIBUTING.md extra_css: - stylesheets/tokens.css From d0c62b6449950a423f5b0f8ff10fe522d79beac4 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 12:18:28 -0700 Subject: [PATCH 018/115] docs site: comm-officer polish on Home and Install Home: tighten para 3 ("calls that once needed you"), "A workflow's first officer", drop "of the docs" from the llms.txt mention. Install: tighten the intro and doctor lines, recast the Sandboxing note (keeping the unsandboxed-without-safehouse fact), and drop the platform/confirm/launch pre-explainer that duplicated the tab and section structure. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/site/get-started/install.md | 19 +++++++++---------- docs/site/index.md | 4 ++-- 2 files changed, 11 insertions(+), 12 deletions(-) diff --git a/docs/site/get-started/install.md b/docs/site/get-started/install.md index e216d9df..90c130eb 100644 --- a/docs/site/get-started/install.md +++ b/docs/site/get-started/install.md @@ -1,8 +1,8 @@ # Install Spacedock Spacedock plugs into a coding agent harness you already run: Claude Code, Codex, -or Pi. Install one of those first. Every command below names the output you -should see, so you can check each step against the stated result. +or Pi. Install one of those first. Every command below names the output to +expect, so you can check each step. Spacedock itself is two pieces that install separately: @@ -11,8 +11,7 @@ Spacedock itself is two pieces that install separately: harness (Claude Code, Codex, or Pi). The recommended setup installs the launcher with Homebrew, then adds the plugin. -Pick your platform, then confirm and launch. Those last two steps are the same -everywhere. A from-source build is available for development. +A from-source build is available for development. ## Install the launcher @@ -44,9 +43,9 @@ everywhere. A from-source build is available for development. profile is present in the working directory, Spacedock wraps the launch through the `safehouse` command. Spacedock ships no sandbox of its own. A run is sandboxed only when a Linux-capable `safehouse` binary is on your - `PATH`; when the binary is absent, Spacedock prints an install hint and the - launch proceeds **unsandboxed**. The macOS-only Gatekeeper/quarantine - handling does not apply on Linux and is not needed there. + `PATH`; when it is absent, Spacedock prints an install hint and the launch + proceeds **unsandboxed**. Gatekeeper and quarantine handling are macOS-only + and do not apply here. === "Codex or Pi" @@ -78,7 +77,7 @@ spacedock claude "/spacedock:survey" ``` Starts the first officer in Claude Code and runs the survey. The first launch -sets up the plugin for you, so this single command is enough. When a +also sets up the plugin, so no separate install step is needed. When a `.safehouse` profile is present in the working directory, the launch runs sandboxed. To set up the plugin ahead of time, or to refresh it later, run `spacedock install --host claude`. @@ -92,8 +91,8 @@ checkout so local edits are live. ## Keep things in sync -`spacedock doctor` is the compatibility check. If it reports your installed -plugin is out of date, refresh it: +`spacedock doctor` checks compatibility. If it reports the installed +plugin is out of date, refresh with: ```bash spacedock install --host claude diff --git a/docs/site/index.md b/docs/site/index.md index 4f9edd1d..28435408 100644 --- a/docs/site/index.md +++ b/docs/site/index.md @@ -4,7 +4,7 @@ Spacedock runs your work as a series of stages. **Nothing crosses a gate without A gate is a checkpoint where the workflow pauses and asks you the question the work has reached: ship this, or not? You approve it, send it back, or escalate. You can also delegate the call to an agent. Either way, the decision is recorded with its evidence and its reason. That is the whole idea. Everything else is detail. -You are the captain. You set the bar and make the calls; the agents do the rest. The bar starts rough and sharpens every time you reject, so the calls that once needed you become ones you can hand off with confidence. See [the operating model](concepts/operating-model.md) for how the three roles divide the work. +You are the captain. You set the bar and make the calls; the agents do the rest. The bar starts rough and sharpens every time you reject, so calls that once needed you become ones you can hand off with confidence. See [the operating model](concepts/operating-model.md) for how the three roles divide the work. ## What's different @@ -22,4 +22,4 @@ You are the captain. You set the bar and make the calls; the agents do the rest. ## For agents using Spacedock -Spacedock's docs are read by agents too. A user's first officer parsing these docs is itself an agent. The build emits a curated `llms.txt` index of the docs at the site root for product-using agents. +Spacedock's docs are read by agents too. A workflow's first officer parsing these docs is itself an agent. The build emits a curated `llms.txt` index at the site root for product-using agents. From cc4736059c7f7a9fd0857988ed157b9cde16a7d9 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 12:19:40 -0700 Subject: [PATCH 019/115] docs site: tighten Home lede gate sentence (comm-officer) "asks you the question the work has reached" -> "puts the question to you": drops the dangling relative clause, more direct. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/site/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/site/index.md b/docs/site/index.md index 28435408..4efce4e0 100644 --- a/docs/site/index.md +++ b/docs/site/index.md @@ -2,7 +2,7 @@ Spacedock runs your work as a series of stages. **Nothing crosses a gate without a decision you own.** -A gate is a checkpoint where the workflow pauses and asks you the question the work has reached: ship this, or not? You approve it, send it back, or escalate. You can also delegate the call to an agent. Either way, the decision is recorded with its evidence and its reason. That is the whole idea. Everything else is detail. +A gate is a checkpoint where the workflow pauses and puts the question to you: ship this, or not? You approve it, send it back, or escalate. You can also delegate the call to an agent. Either way, the decision is recorded with its evidence and its reason. That is the whole idea. Everything else is detail. You are the captain. You set the bar and make the calls; the agents do the rest. The bar starts rough and sharpens every time you reject, so calls that once needed you become ones you can hand off with confidence. See [the operating model](concepts/operating-model.md) for how the three roles divide the work. From 1c009dff2f4d0c680cce8c7317b11aed6855b081 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 12:30:54 -0700 Subject: [PATCH 020/115] docs site: tighten first-launch lede, split dense survey-report sentence --- docs/site/get-started/first-launch.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/site/get-started/first-launch.md b/docs/site/get-started/first-launch.md index b6ec3479..9857b27d 100644 --- a/docs/site/get-started/first-launch.md +++ b/docs/site/get-started/first-launch.md @@ -6,19 +6,19 @@ One command starts your first session and orients you in a project you already h spacedock claude "/spacedock:survey" ``` -This launches the [first officer](../concepts/operating-model.md#three-roles) (the orchestrator agent that runs a Spacedock workflow) inside Claude Code, and hands it the survey task. The first launch sets up the plugin for you, so this single line is enough; you do not need a separate setup step. When a `.safehouse` profile is present in the working directory, the launch runs sandboxed automatically. +This launches the [first officer](../concepts/operating-model.md#three-roles) (the orchestrator agent that runs a Spacedock workflow) inside Claude Code and hands it the survey task. The first launch sets up the plugin for you; there is no separate setup step. Run it from inside a project that already has some agent history, such as a repo you have been coding in with Claude Code. Survey reads that history; an empty directory has nothing to report on. ## What survey reports -In one read-only pass (it never edits your files), survey reconstructs what the agents in this project have implicitly been doing. It leads with **the decisions still open and waiting on you**, then names the [workflow](../concepts/workflows-and-entities.md) you have been running without naming it, the distinct workstreams, and how often you have had to step in, under a one-line headline (project, sessions, date range, decision and interruption counts). If the project has no agent history, it says so and stops. +In one read-only pass (it never edits your files), survey reconstructs what the agents in this project have been doing. Under a one-line headline (project, sessions, date range, decision and interruption counts), the report leads with **the decisions still open and waiting on you**. Then it names the [workflow](../concepts/workflows-and-entities.md) you have been running without naming it, the distinct workstreams, and how often you have had to step in. If the project has no agent history, survey says so and stops. For the full section-by-section breakdown and how survey reads your history, see [what survey reports](../running-workflows/survey.md#what-it-reports). ## What comes next -Survey ends with an offer, not an action. After the report, it asks whether you want it to [commission](../running-workflows/commission.md) a real Spacedock [workflow](../concepts/workflows-and-entities.md) built from what it found, turning the open decisions into [approval gates](../concepts/gates-and-decisions.md) and the workstreams into work items. You can say yes and let it scaffold the workflow, or say no and keep the survey as a standalone orientation. Either way, nothing has changed in your project until you choose. +Survey ends with an offer, not an action. It asks whether you want it to [commission](../running-workflows/commission.md) a real Spacedock workflow built from what it found, turning the open decisions into [approval gates](../concepts/gates-and-decisions.md) and the workstreams into work items. You can say yes and let it scaffold the workflow, or say no and keep the survey as a standalone orientation. Either way, nothing has changed in your project until you choose. To go straight to defining a workflow yourself instead, see [your first workflow](first-workflow.md). If `spacedock` is not yet installed, start with [installing Spacedock](install.md). From da3172301858d7adb3026bdc78f900c45140c488 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 12:32:13 -0700 Subject: [PATCH 021/115] docs site: comm-officer polish on first-launch --- docs/site/get-started/first-launch.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/site/get-started/first-launch.md b/docs/site/get-started/first-launch.md index 9857b27d..133b8950 100644 --- a/docs/site/get-started/first-launch.md +++ b/docs/site/get-started/first-launch.md @@ -6,9 +6,9 @@ One command starts your first session and orients you in a project you already h spacedock claude "/spacedock:survey" ``` -This launches the [first officer](../concepts/operating-model.md#three-roles) (the orchestrator agent that runs a Spacedock workflow) inside Claude Code and hands it the survey task. The first launch sets up the plugin for you; there is no separate setup step. +This launches the [first officer](../concepts/operating-model.md#three-roles) (the orchestrator agent that runs a Spacedock workflow) inside Claude Code and hands it the survey task. The first launch also sets up the plugin; no separate setup step is needed. -Run it from inside a project that already has some agent history, such as a repo you have been coding in with Claude Code. Survey reads that history; an empty directory has nothing to report on. +Run it from inside a project that already has some agent history, such as a repo you have been coding in with Claude Code. Survey reads that history; an empty directory has nothing to report. ## What survey reports @@ -24,7 +24,7 @@ To go straight to defining a workflow yourself instead, see [your first workflow ## The command grammar -The front door is one shape, and every launch uses it: +Every launch uses the same shape: ```bash spacedock claude "task" [--safehouse…] [-- host-flags…] From cbdd45731b965b065a553190b87c3841beadbd79 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 12:32:13 -0700 Subject: [PATCH 022/115] docs site: first-workflow defines terms at first use, drops front-loaded glossary --- docs/site/get-started/first-workflow.md | 39 +++++++++---------------- 1 file changed, 13 insertions(+), 26 deletions(-) diff --git a/docs/site/get-started/first-workflow.md b/docs/site/get-started/first-workflow.md index b5999e83..a0c511c4 100644 --- a/docs/site/get-started/first-workflow.md +++ b/docs/site/get-started/first-workflow.md @@ -4,27 +4,12 @@ Your first workflow comes from one of two places: [survey](first-launch.md) offers to build one from what it found in your project, or you describe one from scratch to the `/spacedock:commission` skill. Either way you land here. A workflow is a directory of plain-text work items plus a README that defines the -stages they move through, the schema each item carries, and the gates where you -make a call. This page walks the commission end to end: the questions it asks, -the design and review gates it sets up, and what happens once the workflow starts -running. - -A few terms used below, defined on first use: - -- An **entity** is one work item: a single markdown file (the README also calls - it a "work item"). A bug report, a design idea, a feature: whatever the - workflow processes, each one is an entity. -- A **stage** is a bucket an entity sits in as it advances, for example - `ideation` or `implementation`. The first entity starts in the first stage and - moves toward a terminal one. -- A **gate** is a decision point at the end of a stage where the workflow pauses - for your call instead of advancing on its own. - -You are addressed as the captain, the workflow operator who makes the calls at -gates; the first officer is the orchestrator agent that runs the workflow, and -the ensign is the worker that moves one entity through one stage. The -[operating model](../concepts/operating-model.md#three-roles) covers the three -roles in full. +stages they move through and the gates where you make a call. + +Spacedock addresses you as the **captain**: the workflow operator who decides at +gates. The [operating model](../concepts/operating-model.md#three-roles) covers +the other two roles, the first officer (the orchestrator agent that runs the +workflow) and the ensign (the worker that moves one item through one stage). ## Commission a workflow @@ -43,9 +28,10 @@ scratch. The skill greets you and walks three phases: **design** (a few questions), **generate** (it writes the files), and a **pilot run** (it starts the workflow on your seed items). In the design phase it asks, one question at a time: what -the workflow is for and what each entity is (a "design idea" becomes an `idea`), -the stages an entity moves through, which of those stages are gated and where a -rejected entity bounces back to, and the quality bar for each stage. Last come the +the workflow is for and what each **entity** is, the work item the workflow +processes as one markdown file (a "design idea" becomes an `idea`); the stages +an entity moves through; which of those stages are gated and where a rejected +entity bounces back to; and the quality bar for each stage. Last come the entity-ID style and two or three seed items to start on. You confirm or adjust each proposal. The [commission reference](../running-workflows/commission.md#the-four-things-you-name) @@ -68,8 +54,9 @@ the full file layout and the `review stages` walk. ## The design and review gates -This is the line Spacedock draws: work flows through the stages, but -**nothing crosses a gate without a recorded decision.** A development workflow +This is the line Spacedock draws: work flows through the stages on its own, +but a **gate** pauses it for your call, and **nothing crosses a gate without a +recorded decision.** A development workflow gates the design stage and the review stage among others, so you sign off on the approach before code is written, and on the result before it ships. From a6a8199c6d5437d483da17a96ecf56eee8d77584 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 12:32:54 -0700 Subject: [PATCH 023/115] docs site: comm-officer polish on first-workflow --- docs/site/get-started/first-workflow.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/site/get-started/first-workflow.md b/docs/site/get-started/first-workflow.md index a0c511c4..f3071c63 100644 --- a/docs/site/get-started/first-workflow.md +++ b/docs/site/get-started/first-workflow.md @@ -20,7 +20,7 @@ the same line: spacedock claude "/spacedock:commission Track design ideas through review stages" ``` -If you have not launched a session yet, see +If you have not yet launched a session, see [Install Spacedock](install.md) first. You can also start bare (`/spacedock:commission` with no description) and answer the questions from scratch. @@ -54,7 +54,7 @@ the full file layout and the `review stages` walk. ## The design and review gates -This is the line Spacedock draws: work flows through the stages on its own, +Spacedock draws a clear line: work flows through stages on its own, but a **gate** pauses it for your call, and **nothing crosses a gate without a recorded decision.** A development workflow gates the design stage and the review stage among others, so you sign off on @@ -65,7 +65,7 @@ direction, the evidence behind it, and a single recommendation. You make one of three calls: - **Approve**, and the entity advances to the next stage. -- **Redo with feedback**: it goes back for revision against the notes you give. +- **Redo with feedback**: it goes back for revision against your notes. - **Reject**, and it bounces to an earlier stage (the one the design named as the rejection target) to be reworked. From c307268c7316880b52e0b3d13bb16d8e2c5c5d51 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 12:32:54 -0700 Subject: [PATCH 024/115] docs site: operating-model drops page-announce sentence, parallel next-links --- docs/site/concepts/operating-model.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/site/concepts/operating-model.md b/docs/site/concepts/operating-model.md index 6276ad59..a7e7e0ca 100644 --- a/docs/site/concepts/operating-model.md +++ b/docs/site/concepts/operating-model.md @@ -1,6 +1,6 @@ # The operating model -Spacedock runs on three roles and one division of labor: you shape the work and make the calls; the agents drive each item through its stages and bring decisions back to you with evidence. This page names the roles, the line between shaping and driving, and why decisions arrive batched. +Spacedock runs on three roles and one division of labor: you shape the work and make the calls; the agents drive each item through its stages and bring decisions back to you with evidence. ## Three roles @@ -37,5 +37,5 @@ Decisions reach you batched and backed by evidence, not as a stream of interrupt ## Where to go next - [Workflows and entities](workflows-and-entities.md) covers the directory and files the roles operate on. -- [Stage lifecycle](stage-lifecycle.md): how an entity moves backlog → ideation → implementation → validation → done. +- [Stage lifecycle](stage-lifecycle.md) walks an entity backlog → ideation → implementation → validation → done. - [Gates and decisions](gates-and-decisions.md) lays out what a gate review carries, the three calls you make, and the detached adversarial audit. From 8d541cce7e58240bd718f7f18f33ac207f0c0c5d Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 12:33:52 -0700 Subject: [PATCH 025/115] docs site: comm-officer polish on operating-model --- docs/site/concepts/operating-model.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/site/concepts/operating-model.md b/docs/site/concepts/operating-model.md index a7e7e0ca..35cb5607 100644 --- a/docs/site/concepts/operating-model.md +++ b/docs/site/concepts/operating-model.md @@ -10,15 +10,15 @@ Spacedock runs on three roles and one division of labor: you shape the work and | **First Officer** | The orchestrator agent. | Running the workflow: dispatch, gate presentation, advancing entity state. | | **Ensign** | The worker agent. | Moving one entity (one work item) forward through one stage. | -There is one captain and one first officer per session. The number of ensigns tracks the dispatchable work: the first officer dispatches one per entity per stage. +Each session has one captain and one first officer. The number of ensigns tracks the dispatchable work: the first officer dispatches one per entity per stage. -The first officer reads the workflow README, runs `spacedock status --next` to find entities ready to advance, and dispatches an ensign for each. An ensign reads its assignment, does the stage's work, commits, writes a stage report, and signals done. The first officer reviews that report against the checklist it dispatched. If the stage is gated, it pauses and presents the report to you. If not, it advances the entity and dispatches the next stage itself. A completed non-gated, non-terminal stage is not a stopping point. +The first officer reads the workflow README, runs `spacedock status --next` to find entities ready to advance, and dispatches an ensign for each. An ensign reads its assignment, does the stage's work, commits, writes a stage report, and signals done. The first officer reviews that report against the checklist it dispatched. If the stage is gated, it pauses and presents the report to you. If not, it advances the entity and dispatches the next stage itself. A completed non-gated, non-terminal stage flows forward without pause. ## Shaping versus driving The captain shapes; the agents drive. These are different jobs, and the split is what keeps you out of the per-step loop. -**Shaping is defining what good looks like before the work runs.** You set the mission, the stages, and the bar each stage must clear, all declared in the workflow README rather than negotiated mid-task. You commission a workflow with [`/spacedock:commission`](../running-workflows/commission.md), and you make the calls at gates: approve, redo with feedback, or reject. Some gates you answer yourself; others resolve through a delegated agent review. That is the whole of the captain's standing job. +**Shaping is defining what good looks like before the work runs.** You set the mission, the stages, and the bar each stage must clear, all declared in the workflow README rather than negotiated mid-task. You commission a workflow with [`/spacedock:commission`](../running-workflows/commission.md), and you make the calls at gates: approve, redo with feedback, or reject. Some gates you answer yourself; others resolve through a delegated agent review. That is the captain's whole standing job. **Driving is moving entities through the declared stages.** The first officer schedules and dispatches; the ensign does the stage work and proves it. The first officer is allowed to take obvious reversible steps without asking: a dispatch the workflow already permits, a status read, a routine state transition. It asks you only when requirements are materially ambiguous, a design choice would change the output meaningfully, or scope is too unclear to turn into concrete criteria. Everything else happens without a prompt to you. @@ -26,7 +26,7 @@ The line holds because of one rule: the maker does not judge its own work. Revie ## Batched, evidenced decisions -Decisions reach you batched and backed by evidence, not as a stream of interruptions. This is the point of the model: your attention is the bottleneck, so the agents queue work and surface only the calls that need a human. +Decisions reach you batched and backed by evidence, not as a stream of interruptions. Your attention is the bottleneck; the agents queue work and surface only the calls that need a human. **Batch the work; decide as it flows back.** Queue many entities at once. Ensigns advance each through its stages in parallel. You handle gates as they surface, not one session at a time, and not on the agent's schedule. While one entity waits on a clarification, the first officer keeps dispatching the others. From 12889331ba8200ccd9a6971ae4e8b877affe6f47 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 12:33:52 -0700 Subject: [PATCH 026/115] docs site: workflows-and-entities leads entity section with file forms, dedupes parser note --- docs/site/concepts/workflows-and-entities.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/site/concepts/workflows-and-entities.md b/docs/site/concepts/workflows-and-entities.md index 43252947..d5be1f37 100644 --- a/docs/site/concepts/workflows-and-entities.md +++ b/docs/site/concepts/workflows-and-entities.md @@ -46,13 +46,13 @@ The README body documents each stage with `Inputs`, `Outputs`, `Good`, and `Bad` ## The entity: one work item -**An entity is a single work item, stored as a markdown file with YAML frontmatter.** Each entity lives as either a flat file `{slug}.md` or a folder `{slug}/index.md`. Use the folder form when reports or artifacts accumulate beside the work item. Slugs are lowercase with hyphens, no spaces (`add-login.md` or `add-login/index.md`). `spacedock status` reads both forms. +**An entity lives as a flat file `{slug}.md` or a folder `{slug}/index.md`.** Use the folder form when reports or artifacts accumulate beside the work item. Slugs are lowercase with hyphens, no spaces (`add-login.md` or `add-login/index.md`). `spacedock status` reads both forms. The body holds the human-readable record: a description, a problem statement, the proposed approach, acceptance criteria, and the stage reports filed as the entity advances. ## Entity frontmatter -The frontmatter is the machine-readable state. The full schema lives in the workflow's own README; the [frontmatter contract](../reference/frontmatter-contract.md) is the field reference across workflows. The fields you set and read most often: +The YAML frontmatter at the top of the file is the machine-readable state. The full schema lives in the workflow's own README; the [frontmatter contract](../reference/frontmatter-contract.md) is the field reference across workflows. The fields you set and read most often: | Field | What it holds | |-------|---------------| @@ -66,7 +66,7 @@ The frontmatter is the machine-readable state. The full schema lives in the work | `worktree` | The worktree path while a dispatched agent is active; empty otherwise. | | `issue` | Optional external ticket reference, e.g. `ENG-123`, `kata:task-abc123`, or `owner/repo#42`. | -The frontmatter parser is line-oriented, so keep fields flat and top-level. If a workflow needs more metadata, add more flat custom fields rather than nested YAML; the v1 parser preserves lines, not arbitrary nested structure. +The frontmatter parser is line-oriented: keep fields flat and top-level. If a workflow needs more metadata, add flat custom fields rather than nested YAML. `status` is the field that drives everything: the first officer reads it to decide which entities are ready to advance. To see the queue, run the status viewer against the workflow directory: From 36d6b845857693310db5d23642b986100ce4b471 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 12:34:59 -0700 Subject: [PATCH 027/115] docs site: comm-officer polish on workflows-and-entities --- docs/site/concepts/workflows-and-entities.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/site/concepts/workflows-and-entities.md b/docs/site/concepts/workflows-and-entities.md index d5be1f37..b0b17b6e 100644 --- a/docs/site/concepts/workflows-and-entities.md +++ b/docs/site/concepts/workflows-and-entities.md @@ -1,10 +1,10 @@ # Workflows & entities -**A workflow is a directory plus a README, and an entity is one markdown file inside it.** The README defines the stages, the schema, and the gates; each entity is a work item that moves through those stages. Everything about a work item lives in the file itself: the problem, the design notes, the bar for done, the stage reports. State survives a session, so the next one picks up where you left off. +**A workflow is a directory plus a README, and an entity is one markdown file inside it.** The README defines the stages, the schema, and the gates; each entity is a work item that moves through those stages. Everything about a work item lives in the file itself: the problem, the design notes, the bar for done, the stage reports. State survives a session, so the next session picks up where you left off. ## The workflow: a directory and its README -The README is the single source of truth. Its frontmatter declares the stages, the entity type, and the ID style; its prose body defines what each stage means, what counts as good, and what a worker must produce. You commission a workflow with `/spacedock:commission`, which generates the directory, the README, and a few seed entities for you. +The README is the single source of truth. Its frontmatter declares the stages, the entity type, and the ID style; its prose body defines what each stage means, what counts as good, and what a worker must produce. You commission a workflow with `/spacedock:commission`, which generates the directory, the README, and a few seed entities. A minimal README frontmatter looks like this: @@ -42,7 +42,7 @@ Each `states` entry is one stage. The per-stage flags decide behavior: - **`fresh: true`** dispatches the stage with no access to the prior worker's reasoning. Use it for review stages so the maker doesn't judge its own work. - **`feedback-to: `** names where rejected work bounces back to for revision. -The README body documents each stage with `Inputs`, `Outputs`, `Good`, and `Bad`. That prose is the living spec; it is what every dispatched ensign works to. Tighten it to your actual bar before the first dispatch; editing it after agents have run against vague prose costs more. +The README body documents each stage with `Inputs`, `Outputs`, `Good`, and `Bad`. That prose is the living spec; every dispatched ensign works from it. Tighten it to your actual bar before the first dispatch; editing it after agents have run against vague prose costs more. ## The entity: one work item @@ -52,7 +52,7 @@ The body holds the human-readable record: a description, a problem statement, th ## Entity frontmatter -The YAML frontmatter at the top of the file is the machine-readable state. The full schema lives in the workflow's own README; the [frontmatter contract](../reference/frontmatter-contract.md) is the field reference across workflows. The fields you set and read most often: +The YAML frontmatter at the top of the file is the machine-readable state. The full schema lives in the workflow README; the [frontmatter contract](../reference/frontmatter-contract.md) is the field reference across workflows. The fields you set and read most often: | Field | What it holds | |-------|---------------| @@ -68,7 +68,7 @@ The YAML frontmatter at the top of the file is the machine-readable state. The f The frontmatter parser is line-oriented: keep fields flat and top-level. If a workflow needs more metadata, add flat custom fields rather than nested YAML. -`status` is the field that drives everything: the first officer reads it to decide which entities are ready to advance. To see the queue, run the status viewer against the workflow directory: +`status` drives dispatch: the first officer reads it to decide which entities are ready to advance. To see the queue, run the status viewer against the workflow directory: ```bash spacedock status --workflow-dir docs/dev @@ -88,7 +88,7 @@ spacedock status --workflow-dir docs/dev --next state: .spacedock-state ``` -With this set, the README (the living spec) stays on your code branch, while the entity files, their reports, and the archive live under `.spacedock-state`. Routine stage transitions then never churn the code branch or collide with a feature PR. The path is resolved relative to the README's directory; `spacedock status` reads stages from the README and entities from the state checkout, and writes frontmatter updates and archive moves into the state checkout. +With this set, the README (the living spec) stays on your code branch, while the entity files, their reports, and the archive live under `.spacedock-state`. Routine stage transitions never churn the code branch or collide with a feature PR. The path is resolved relative to the README's directory; `spacedock status` reads stages from the README and entities from the state checkout, and writes frontmatter updates and archive moves into the state checkout. The state checkout is a linked git worktree on an orphan branch in the same repo, so state commits land on that branch and the code branch never sees them. On a fresh clone the state worktree is absent. Run `spacedock state init` to fetch the orphan branch and re-add the linked worktree before working the workflow. From 49167a386aadb24e5ad7186d53745568573dad59 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 12:35:18 -0700 Subject: [PATCH 028/115] docs site: stage-lifecycle owns the stage-property detail; dedupe flags and status blocks --- docs/site/concepts/stage-lifecycle.md | 14 +++++--------- docs/site/concepts/workflows-and-entities.md | 14 ++------------ 2 files changed, 7 insertions(+), 21 deletions(-) diff --git a/docs/site/concepts/stage-lifecycle.md b/docs/site/concepts/stage-lifecycle.md index c0dfef64..0bc48690 100644 --- a/docs/site/concepts/stage-lifecycle.md +++ b/docs/site/concepts/stage-lifecycle.md @@ -4,7 +4,7 @@ An entity moves through an ordered chain of stages that the workflow defines, on ## The dev workflow's stages -This page uses the dev workflow as the running example. Its five stages below are this workflow's stages, not a canonical set; the full per-stage Inputs/Outputs/Good/Bad detail lives in its [README](https://github.com/spacedock-dev/spacedock/blob/next/docs/dev/README.md). Read the chain as a pipeline: each stage takes the prior stage's output as its input, and the bar rises from "is this clear?" to "is this proven?". +The five stages below are the dev workflow's own, the running example for this page; the full per-stage Inputs/Outputs/Good/Bad detail lives in its [README](https://github.com/spacedock-dev/spacedock/blob/next/docs/dev/README.md). Read the chain as a pipeline: each stage takes the prior stage's output as its input, and the bar rises from "is this clear?" to "is this proven?". - **`backlog`, the seed.** An entity enters here when first proposed: a title, a source, a brief description, and the test gates future stages must satisfy. No design work yet. `initial: true`, so this is where every new entity starts. The dev workflow also marks it `gate: true`, so the first officer presents a new entity for your go-ahead before it advances. - **`ideation`, the design.** A worker clarifies the problem, explores approaches, and produces a fleshed-out body: problem statement, proposed approach, acceptance criteria, and a test plan. Each acceptance criterion names how it will be checked. This stage is `gate: true` in the dev workflow, so the first officer presents the design for your approval before any code is written. @@ -48,18 +48,14 @@ The mechanics, run by the first officer: To see where each entity sits and which are ready to advance, read the workflow state: -```bash -spacedock status --workflow-dir docs/dev -``` - ```bash spacedock status --workflow-dir docs/dev --next ``` -`--next` lists the entities ready for dispatch, the query the first officer runs each loop. The `worktree` column shows the isolated checkout path for any entity currently mid-stage in a worktree-backed stage. +`--next` lists the entities ready for dispatch, the query the first officer runs each loop; drop it for the full queue. The `worktree` column shows the isolated checkout path for any entity currently mid-stage in a worktree-backed stage. ## Where to go next -- The roles that drive this pipeline (captain, first officer, ensign) are in [the operating model](operating-model.md). -- The decision points at stage boundaries are covered in [gates and decisions](gates-and-decisions.md). -- The entity frontmatter these stages update is in the [frontmatter contract](../reference/frontmatter-contract.md). +- [The operating model](operating-model.md) names the roles that drive this pipeline: captain, first officer, ensign. +- [Gates and decisions](gates-and-decisions.md) covers the decision points at stage boundaries. +- The [frontmatter contract](../reference/frontmatter-contract.md) lists the entity fields these stages update. diff --git a/docs/site/concepts/workflows-and-entities.md b/docs/site/concepts/workflows-and-entities.md index b0b17b6e..7d4b0308 100644 --- a/docs/site/concepts/workflows-and-entities.md +++ b/docs/site/concepts/workflows-and-entities.md @@ -34,13 +34,7 @@ stages: --- ``` -Each `states` entry is one stage. The per-stage flags decide behavior: - -- **`initial: true`** marks where a new entity starts; **`terminal: true`** marks where it ends. -- **`gate: true`** makes the stage end at a gate: the first officer pauses and presents a decision instead of advancing on its own. -- **`worktree: true`** runs the stage in its own git worktree, so stages that touch shared state stay isolated. Lighter stages run inline. -- **`fresh: true`** dispatches the stage with no access to the prior worker's reasoning. Use it for review stages so the maker doesn't judge its own work. -- **`feedback-to: `** names where rejected work bounces back to for revision. +Each `states` entry is one stage. Its flags decide where an entity starts and ends (`initial`, `terminal`), which stages pause for your call (`gate`), which run in an isolated worktree (`worktree`), which get a reviewer with no access to the maker's reasoning (`fresh`), and where rejected work bounces back to (`feedback-to`). [What a stage declares](stage-lifecycle.md#what-a-stage-declares) defines every property. The README body documents each stage with `Inputs`, `Outputs`, `Good`, and `Bad`. That prose is the living spec; every dispatched ensign works from it. Tighten it to your actual bar before the first dispatch; editing it after agents have run against vague prose costs more. @@ -74,11 +68,7 @@ The frontmatter parser is line-oriented: keep fields flat and top-level. If a wo spacedock status --workflow-dir docs/dev ``` -To list only the entities ready for dispatch, run the query the first officer runs each loop: - -```bash -spacedock status --workflow-dir docs/dev --next -``` +Add `--next` to list only the entities ready for dispatch. ## Where entities live: the state checkout From f3a4df66a7df69861d99a7ac0b34e4f238ec1f82 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 12:36:07 -0700 Subject: [PATCH 029/115] docs site: comm-officer polish on stage-lifecycle --- docs/site/concepts/stage-lifecycle.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/site/concepts/stage-lifecycle.md b/docs/site/concepts/stage-lifecycle.md index 0bc48690..18cb0e6f 100644 --- a/docs/site/concepts/stage-lifecycle.md +++ b/docs/site/concepts/stage-lifecycle.md @@ -4,11 +4,11 @@ An entity moves through an ordered chain of stages that the workflow defines, on ## The dev workflow's stages -The five stages below are the dev workflow's own, the running example for this page; the full per-stage Inputs/Outputs/Good/Bad detail lives in its [README](https://github.com/spacedock-dev/spacedock/blob/next/docs/dev/README.md). Read the chain as a pipeline: each stage takes the prior stage's output as its input, and the bar rises from "is this clear?" to "is this proven?". +The five stages below are the dev workflow's stages, used as the running example for this page; the full per-stage Inputs/Outputs/Good/Bad detail lives in its [README](https://github.com/spacedock-dev/spacedock/blob/next/docs/dev/README.md). Read the chain as a pipeline: each stage takes the prior stage's output as its input, and the bar rises from "is this clear?" to "is this proven?". - **`backlog`, the seed.** An entity enters here when first proposed: a title, a source, a brief description, and the test gates future stages must satisfy. No design work yet. `initial: true`, so this is where every new entity starts. The dev workflow also marks it `gate: true`, so the first officer presents a new entity for your go-ahead before it advances. - **`ideation`, the design.** A worker clarifies the problem, explores approaches, and produces a fleshed-out body: problem statement, proposed approach, acceptance criteria, and a test plan. Each acceptance criterion names how it will be checked. This stage is `gate: true` in the dev workflow, so the first officer presents the design for your approval before any code is written. -- **`implementation`, the deliverable.** A worker produces the change the entity describes: code, fixtures, instruction text, on-disk state. This stage is `worktree: true`, so the work happens in an isolated checkout. Implementation completing is not a stopping point. A completed, non-gated stage routes straight on to validation. +- **`implementation`, the deliverable.** A worker produces the change the entity describes: code, fixtures, instruction text, on-disk state. This stage is `worktree: true`, so the work happens in an isolated checkout. A completed, non-gated stage flows straight to validation. - **`validation`, the independent check.** A worker verifies the deliverable against the acceptance criteria. It checks what was produced; it does not produce the deliverable itself. It reproduces the evidence each `AC-N` cites and returns a `PASSED` or `REJECTED` recommendation. This stage is `worktree: true`, `fresh: true`, `feedback-to: implementation`, and `gate: true`. - **`done`, the verdict.** Validation is complete and you approve the result. The entity is closed with a `verdict` of `PASSED` or `REJECTED` and a `completed` timestamp. `terminal: true`. @@ -27,7 +27,7 @@ The stage order, names, and the properties each stage carries live in the workfl | `concurrency: N` | How many entities may sit in this stage at once. | | `agent: {name}` | Which worker skill the first officer dispatches. Defaults to `ensign`. | -Beyond these properties, the prose of each stage's `###` subsection in the README is the stage definition: its Inputs, Outputs, and the Good/Bad bar. The first officer copies that subsection verbatim into the ensign's assignment, so what a stage declares in prose is exactly what the worker is told to do. +Beyond these properties, the prose of each stage's `###` subsection in the README is the stage definition: its Inputs, Outputs, and the Good/Bad bar. The first officer copies that subsection verbatim into the ensign's assignment, so what a stage declares in prose is exactly what the worker receives as its assignment. ## Fresh context at validation From 52c4a429e6e0e7fe812fea507013b5e4bd6f0765 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 12:36:08 -0700 Subject: [PATCH 030/115] docs site: gates-and-decisions cuts page-announce lede and redundant tails --- docs/site/concepts/gates-and-decisions.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/site/concepts/gates-and-decisions.md b/docs/site/concepts/gates-and-decisions.md index aa139003..ddcf4af0 100644 --- a/docs/site/concepts/gates-and-decisions.md +++ b/docs/site/concepts/gates-and-decisions.md @@ -1,6 +1,6 @@ # Gates & decisions -A gate is the decision point at the end of a stage where nothing advances without your vote. When a stage is marked `gate: true` in the workflow README, the first officer stops after the worker completes, renders a gate review, and waits for you. It never self-approves. This page covers what a gate review carries, the three calls you make, how feedback cycles loop and where they cap, and the detached adversarial audit that backs high-stakes validation. +A gate is the decision point at the end of a stage where nothing advances without your vote. When a stage is marked `gate: true` in the workflow README, the first officer stops after the worker completes, renders a gate review, and waits for you. It never self-approves. ## What a gate carries @@ -30,7 +30,7 @@ Decision: {what approval/rejection does in concrete terms}. Read it as follows: - **`Chosen direction` names what the worker picked**, so you do not have to open the entity file to learn it. Ideation picks an approach; validation picks PASS or REJECTED. Stages with no choice to make show `n/a`. -- **`Recommend` is the first officer's verdict, stated exactly once.** It does not reappear restated elsewhere in the review. +- **`Recommend` is the first officer's verdict, stated exactly once.** - **`Checklist` is a gist roll-up, not the report.** The full `## Stage Report` is cited by file path and line range; open it when you want the detail. - **Reviewer findings split into `Material` and `Polish`.** Material items (fact-corrections, contract violations, missing acceptance-criterion evidence, claims the codebase contradicts) are the ones that should move your vote. Polish is non-blocking. An empty tier is dropped. - **`Decision` names what your vote does in concrete terms.** For example, "approve to enter implementation in worktree `.worktrees/...`" or "reject to bounce back to {feedback-to target}". @@ -47,7 +47,7 @@ You answer a gate with one of three calls. A redo and a reject at a `feedback-to` stage run the same routing machinery. The difference is whether you are correcting a direction you accept or sending it back. Both name the concrete fix asks so the next worker has something to act on. -**A terminal close needs a recorded verdict.** Approving the terminal stage finalizes the entity, and Spacedock refuses to finalize or archive a terminal entity that carries no `verdict`: the verdict is the outcome on the record, and closing without one is the failure the guard exists to catch. The mechanics are in the [frontmatter contract](../reference/frontmatter-contract.md#entity-fields). +**A terminal close needs a recorded verdict.** Approving the terminal stage finalizes the entity, and Spacedock refuses to finalize or archive a terminal entity that carries no `verdict`: the outcome must be on the record. The mechanics are in the [frontmatter contract](../reference/frontmatter-contract.md#entity-fields). ## Feedback cycles and the loop cap @@ -56,11 +56,11 @@ When a feedback stage recommends `REJECTED`, or you reject at a `feedback-to` st The first officer tracks each round in a `### Feedback Cycles` section in the entity body, then: 1. Reads the rejected stage's `feedback-to` target. -2. Routes your concrete findings to that target, reusing the live worker in the same worktree when it is still addressable and reuse conditions pass, dispatching fresh otherwise. The routed message carries the fix work and the stage assignment, so the worker has what it needs to rework. +2. Routes your concrete findings to that target, reusing the live worker in the same worktree when it is still addressable and reuse conditions pass, dispatching fresh otherwise. The routed message carries the fix asks and the stage assignment. 3. Re-runs the reviewer after the fix. 4. Re-enters the gate flow with the updated result, presenting you a fresh gate review. -**The loop caps at three.** On cycle 3 the first officer escalates to you instead of bouncing a fourth time. The same fix has now failed twice, so the call returns to a human rather than looping. This cap is exercised by the `feedback-3-cycle-escalation` runtime scenario, which asserts the first officer escalates on the third rejected validation rather than auto-bouncing again. +**The loop caps at three.** On cycle 3 the first officer escalates to you instead of bouncing a fourth time: the same fix has failed twice, so the call returns to a human. ## The detached adversarial audit From 3a020a0d0de25fed2dddcf95364856c678d0cb07 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 12:37:08 -0700 Subject: [PATCH 031/115] docs site: comm-officer polish on gates-and-decisions --- docs/site/concepts/gates-and-decisions.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/site/concepts/gates-and-decisions.md b/docs/site/concepts/gates-and-decisions.md index ddcf4af0..ce3facc7 100644 --- a/docs/site/concepts/gates-and-decisions.md +++ b/docs/site/concepts/gates-and-decisions.md @@ -4,7 +4,7 @@ A gate is the decision point at the end of a stage where nothing advances withou ## What a gate carries -The first officer presents a gate review only after it has read the worker's `## Stage Report`, checked every dispatched item, and counted the results. The review is the first officer's own prose with a fixed spine. The first three lines and the last line carry the decision; everything between is supporting evidence. If you stop reading after line three, you can still vote. +The first officer presents a gate review only after it has read the worker's `## Stage Report`, checked every dispatched item, and counted the results. The review is the first officer's prose with a fixed spine. The first three lines and the last line carry the decision; everything between is supporting evidence. If you stop reading after line three, you can still vote. A gate review looks like this: @@ -27,7 +27,7 @@ Assessment: {N} done, {N} skipped, {N} failed. Decision: {what approval/rejection does in concrete terms}. ``` -Read it as follows: +Reading the fields: - **`Chosen direction` names what the worker picked**, so you do not have to open the entity file to learn it. Ideation picks an approach; validation picks PASS or REJECTED. Stages with no choice to make show `n/a`. - **`Recommend` is the first officer's verdict, stated exactly once.** @@ -47,7 +47,7 @@ You answer a gate with one of three calls. A redo and a reject at a `feedback-to` stage run the same routing machinery. The difference is whether you are correcting a direction you accept or sending it back. Both name the concrete fix asks so the next worker has something to act on. -**A terminal close needs a recorded verdict.** Approving the terminal stage finalizes the entity, and Spacedock refuses to finalize or archive a terminal entity that carries no `verdict`: the outcome must be on the record. The mechanics are in the [frontmatter contract](../reference/frontmatter-contract.md#entity-fields). +**A terminal close needs a recorded verdict.** Approving the terminal stage finalizes the entity, and Spacedock refuses to finalize or archive a terminal entity that carries no `verdict`: the outcome must be on the record. See the [frontmatter contract](../reference/frontmatter-contract.md#entity-fields) for the mechanics. ## Feedback cycles and the loop cap @@ -70,7 +70,7 @@ The audit triggers on four surfaces: the front-door launcher (`spacedock claude` It runs on a separate throwaway checkout, never the implementation worktree, and never mutates the deliverable. The auditor tries to refute the validation: it constructs an adversarial edit that the deliverable's own tests should catch and confirms they do. A test that stays green under an edit that breaks the claim is a hole. Findings come in two tiers, `Material` and `Polish`; "refuted nothing material" is a valid recorded outcome. -Results feed the same gate machinery you already know: +Results feed the same gate machinery: - **Material findings route back through the normal validation-to-implementation feedback flow**, with a `### Feedback Cycles` entry naming the audit and its adversarial edit. The gate is not presented as clean until they are closed. - **A clean audit is noted in the gate's reviewer-findings block**, or as a one-line "detached audit: no material findings". From cdb701891fa794d58a4e94d1b12bd93b1c31fa0f Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 12:37:20 -0700 Subject: [PATCH 032/115] docs site: gates-and-decisions gains related links --- docs/site/concepts/gates-and-decisions.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/site/concepts/gates-and-decisions.md b/docs/site/concepts/gates-and-decisions.md index ce3facc7..fa7be345 100644 --- a/docs/site/concepts/gates-and-decisions.md +++ b/docs/site/concepts/gates-and-decisions.md @@ -74,3 +74,8 @@ Results feed the same gate machinery: - **Material findings route back through the normal validation-to-implementation feedback flow**, with a `### Feedback Cycles` entry naming the audit and its adversarial edit. The gate is not presented as clean until they are closed. - **A clean audit is noted in the gate's reviewer-findings block**, or as a one-line "detached audit: no material findings". + +## Where to go next + +- [A worked example](worked-example.md) traces one real entity through every gate to a recorded verdict. +- [Operating a workflow](../running-workflows/operating.md) covers answering gates in the day-to-day loop. From f5ffa8b6a66d7e4426d19f7b44437223f66fe73c Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 12:37:20 -0700 Subject: [PATCH 033/115] docs site: worked-example opens with the entity, drops internal Commander codename --- docs/site/concepts/worked-example.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/site/concepts/worked-example.md b/docs/site/concepts/worked-example.md index 4f9c0aaa..aab9670a 100644 --- a/docs/site/concepts/worked-example.md +++ b/docs/site/concepts/worked-example.md @@ -1,8 +1,8 @@ # A worked example -This page traces one real entity, `z9` `codex-plugin-auto-install`, from -backlog through to `done` / PASSED, using artifacts from the project repo. It is -a concrete read of the abstract stage machine: backlog → ideation → +One real entity, `z9` `codex-plugin-auto-install`, went from backlog through to +`done` / PASSED in the project repo, and its artifacts are on the record. Its +trail is the abstract stage machine made concrete: backlog → ideation → implementation → validation → done, the gates between them, and what the captain decides at each one. @@ -10,8 +10,8 @@ The workflow is `docs/dev` (the Spacedock v1 dev workflow); its stages, gates, and entity schema are defined in [the development workflow README](https://github.com/spacedock-dev/spacedock/blob/next/docs/dev/README.md). Runtime entity state lives in a separate `.spacedock-state` checkout, so the -finished entity itself is not in the main tree, but its full trajectory is on -the record in the `0198-pre-flip-hardening` sprint directory: `index.md`, +finished entity itself is not in the main tree. Its full trajectory is in +the `0198-pre-flip-hardening` sprint directory: `index.md`, `dispatch-sprint-execution.md`, `debrief.md`, and `post-sprint-audit.md`. `z9` delivered front-door Codex plugin auto-install: `spacedock codex` now @@ -27,7 +27,7 @@ run the same query: spacedock status --workflow-dir docs/dev --next ``` -Lists the entities ready to dispatch. To scope to one sprint, filter with +This lists the entities ready to dispatch. To scope to one sprint, filter with `--where`: ```bash @@ -42,8 +42,8 @@ At the start of `0198`, `z9` shows up here in the `binary-ux` group. `z9` enters backlog as a seed: a title, a source, and a brief description of the problem. It carries no design yet. Ideation is where a worker fleshes it out into -a problem statement, a proposed approach, entity-level acceptance criteria, and a -test plan, with each AC naming a check outside the entity body that can fail. +a problem statement, a proposed approach, entity-level acceptance criteria (ACs), +and a test plan, with each AC naming a check outside the entity body that can fail. For `z9` that meant a concrete approach: install through the shared `devBranch` rather than a hardcoded `"next"`, so the install channel tracks the release @@ -55,8 +55,8 @@ Ideation ends at a **gate**. Because the dev workflow marks `ideation` with `gate: true`, the first officer does not advance on its own: it presents the design to the captain. The captain approved `z9`'s ideation on 2026-06-08. That approval is the entry condition for implementation, and it is captured in the -sprint package so a later Commander session drives implementation directly -without re-presenting the gate. +sprint package so a later session drives implementation directly without +re-presenting the gate. ## implementation: produce the deliverable From f498537ebedd8f5a3042aa2dab389c1f60f973cb Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 12:37:51 -0700 Subject: [PATCH 034/115] docs site: commission plain-register name pushback, dedupe tighten-the-README point --- docs/site/running-workflows/commission.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/site/running-workflows/commission.md b/docs/site/running-workflows/commission.md index 461b3175..96e948f2 100644 --- a/docs/site/running-workflows/commission.md +++ b/docs/site/running-workflows/commission.md @@ -16,11 +16,11 @@ The design pass collects four decisions. Everything else (the directory path, th 1. **The mission and what each entity is.** The first question asks what the workflow is for and what each work item represents. From the entity description the skill derives the entity label used throughout the generated files: "a design idea" becomes label `idea`, plural `ideas`, type `design_idea`. An entity is one work item, a markdown file that moves through the stages. -2. **The stages.** The skill detects the workflow's shape from your mission (shipping code, testing a hypothesis, or iterating on an artifact) and proposes a stage list for you to confirm, modify, add to, or trim. Stage names describe the bucket an entity is sitting in: activity-flavored (`implementation`, `review`, `validation`) or state-flavored (`proposed`, `published`, `accepted`). The skill pushes back on pleonastic names: `awaiting_validation` reads as "the entity is in awaiting_validation," so it suggests `validation` instead. `done` is the universal terminal and stays as-is. +2. **The stages.** The skill detects the workflow's shape from your mission (shipping code, testing a hypothesis, or iterating on an artifact) and proposes a stage list for you to confirm, modify, add to, or trim. Stage names describe the bucket an entity is sitting in: activity-flavored (`implementation`, `review`, `validation`) or state-flavored (`proposed`, `published`, `accepted`). The skill pushes back on redundant names: `awaiting_validation` reads as "the entity is in awaiting_validation," so it suggests `validation` instead. `done` is the universal terminal and stays as-is. 3. **The gated stages.** A gate is a stage where the workflow pauses for your decision before an entity advances. By default the skill places one gate before the terminal stage. For each gate it also derives a rejection flow, the earlier stage an entity bounces back to when you reject, defaulting to the stage immediately before the gate. You confirm both in the design summary, stated in plain language ("If you reject at `review`, it goes back to `draft` for revision"). -4. **The per-stage rules.** Each stage in the generated README carries three bullets that tell a dispatched ensign what "good" means for that stage: **`Outputs`** (what the worker produces), **`Good`** (your quality bar), and **`Bad`** (anti-patterns to avoid). The skill drafts these from the mission, but they are starting prose, not commitments. They are the rules every dispatched agent works from, so tightening them before the first dispatch is the single highest-leverage edit you can make. +4. **The per-stage rules.** Each stage in the generated README carries three bullets that tell a dispatched ensign what "good" means for that stage: **`Outputs`** (what the worker produces), **`Good`** (your quality bar), and **`Bad`** (anti-patterns to avoid). The skill drafts these from the mission, but they are starting prose, not commitments. They are the rules every dispatched agent works from. You also choose the entity ID style: `sd-b32` (recommended when multiple people or agents create entities across branches or worktrees), `sequential` (single-writer or numeric-continuity workflows), or `slug` (the filename is the identity). See the [frontmatter contract](../reference/frontmatter-contract.md) for what each style stores. From d44c01a5c4a16edd251dfbb59e34cbc4c0b582c0 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 12:38:45 -0700 Subject: [PATCH 035/115] docs site: comm-officer polish on worked-example; spell out definition-of-done --- docs/site/concepts/worked-example.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/docs/site/concepts/worked-example.md b/docs/site/concepts/worked-example.md index aab9670a..69f58d73 100644 --- a/docs/site/concepts/worked-example.md +++ b/docs/site/concepts/worked-example.md @@ -2,7 +2,7 @@ One real entity, `z9` `codex-plugin-auto-install`, went from backlog through to `done` / PASSED in the project repo, and its artifacts are on the record. Its -trail is the abstract stage machine made concrete: backlog → ideation → +trail makes the abstract stage machine concrete: backlog → ideation → implementation → validation → done, the gates between them, and what the captain decides at each one. @@ -35,7 +35,7 @@ spacedock status --workflow-dir docs/dev \ --where sprint=0198-pre-flip-hardening --where 'sprint-readiness != defer' ``` -This is the sprint membership query, the source of truth, not a hand-kept list. +This query is the sprint membership source of truth, not a hand-kept list. At the start of `0198`, `z9` shows up here in the `binary-ux` group. ## backlog → ideation: shape the work @@ -80,8 +80,7 @@ place, and inverted the obsolete test whose old assertion contradicted the new auto-install behavior. Implementation is complete when the deliverable is committed and the stage report -is filed. It is not a parking spot: a completed implementation routes straight to -`validation` dispatch. +is filed; it flows straight to `validation` dispatch. ## validation: verify against the criteria @@ -97,7 +96,7 @@ launcher front door: a read-only pass on a throwaway checkout of the merge resul that tries to refute the validation. The `z9` audit ran at commit `0b714fac` and exercised five mandated probes, each reddening the test suite then reverting. It refuted nothing material. Channel-tracking was confirmed clean. That clean -audit satisfied the sprint's DoD item for the high-stakes surface. +audit satisfied the sprint's definition-of-done item for the high-stakes surface. Validation also has `gate: true` and `feedback-to: implementation`. A REJECTED recommendation routes the finding back to implementation for another cycle; a @@ -113,8 +112,7 @@ The terminal stage records the outcome in frontmatter: `status: done`, > kb / qa / z9 / vh entities are all `status: done`, `verdict: PASSED`, archived, > with PR refs #327 / #328 / #329 / #330. -That is the whole point of the machine: nothing reached `done` on assertion -alone. `z9` advanced only on an approved design, an isolated implementation, a +The machine's point: nothing reached `done` on assertion alone. `z9` advanced only on an approved design, an isolated implementation, a fresh validation, a detached audit that failed to break it, and an explicit captain verdict. Each one a decision, each one on the record. From 6a26e50c30397e538f8e0bab26121e77f4d11d94 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 12:38:45 -0700 Subject: [PATCH 036/115] docs site: comm-officer polish on commission --- docs/site/running-workflows/commission.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/site/running-workflows/commission.md b/docs/site/running-workflows/commission.md index 96e948f2..e129b2d9 100644 --- a/docs/site/running-workflows/commission.md +++ b/docs/site/running-workflows/commission.md @@ -1,6 +1,6 @@ # Commission a workflow -`/spacedock:commission` turns a description of the work you want tracked into a runnable workflow: a directory of markdown entities, a README that is the workflow's living spec, and a first officer ready to dispatch an ensign for each seed entity. You answer a short interactive design pass, the skill generates the files, and it launches a pilot run as the first officer. +`/spacedock:commission` turns a description of the work you want tracked into a runnable workflow: a directory of markdown entities, a README that is the workflow's living spec, and a first officer ready to dispatch an ensign for each seed entity. You answer a short interactive design pass; the skill generates the files and launches a pilot run as the first officer. Invoke it from a session started with `spacedock claude`. You can pass the mission inline: @@ -12,7 +12,7 @@ Text after the command name is taken as the workflow mission and presented for c ## The four things you name -The design pass collects four decisions. Everything else (the directory path, the entity identity scheme, the rejection routing) is derived from these and shown back to you for confirmation before any file is written. +The design pass collects four decisions. The skill derives everything else (the directory path, the entity identity scheme, the rejection routing) from these and shows the full design for your confirmation before writing any file. 1. **The mission and what each entity is.** The first question asks what the workflow is for and what each work item represents. From the entity description the skill derives the entity label used throughout the generated files: "a design idea" becomes label `idea`, plural `ideas`, type `design_idea`. An entity is one work item, a markdown file that moves through the stages. @@ -45,7 +45,7 @@ Editing here costs minutes; un-editing after agents have been dispatched against ## What the first officer does next -Commission does not stop at generating files. It assumes the first-officer role itself and runs the pilot. There is no separate launch step for the first run. +Commission generates the files and then assumes the first-officer role itself to run the pilot — no separate launch step needed. 1. It loads the [first officer's operating contract](../concepts/operating-model.md) and reads the workflow README you just generated. 2. It runs `spacedock status --boot` to read the workflow's current state. From ec535770947002c73e63bc160fad7672603ceda1 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 12:38:45 -0700 Subject: [PATCH 037/115] docs site: survey drops duplicated read-only claim and roadmap aside --- docs/site/running-workflows/survey.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/site/running-workflows/survey.md b/docs/site/running-workflows/survey.md index 3a800a50..0a1f9a46 100644 --- a/docs/site/running-workflows/survey.md +++ b/docs/site/running-workflows/survey.md @@ -1,6 +1,6 @@ # Survey an existing project -`/spacedock:survey` reads a brownfield project's agent history and reports what the agents have implicitly been doing (read-only), then offers to commission a workflow from what it found. Run it when you arrive at or return to a repo that already has agent sessions and want the lay of the land before doing anything else. It never edits your files; the only stop in the flow is the commission offer at the end. +`/spacedock:survey` reads a brownfield project's agent history and reports what the agents have implicitly been doing, then offers to commission a workflow from what it found. Run it when you arrive at or return to a repo that already has agent sessions and want the lay of the land before doing anything else. It never edits your files; the only stop in the flow is the commission offer at the end. Survey is the recommended first launch. Point Spacedock at a project and hand it the survey skill: @@ -31,7 +31,7 @@ Survey leads with a one-line headline (the project, the session count, the date - **Needs you.** The open decisions, the forks raised but never resolved. **Survey leads the report with these**, because they are the work blocked on you. Exploration threads you are deliberately holding are separated from mechanical questions awaiting an answer. - **Recent decisions** and **interruptions**: the answered or shipped forks, and how often you had to step in. - **Scaffold.** If another agent scaffold is in use (superpowers, gsd / get-shit-done, or another `.claude` skill tree), survey states it as a fact: the family, its invocation count, and whether it is checked in on disk. -- **Codex** (only when present). Codex sessions land with no recorded working directory, so survey attributes them to this repo through each command's working directory and reports them as their own section: a session count, the workstream clusters, and an activity tally. Gemini is a deferred follow-up. +- **Codex** (only when present). Codex sessions land with no recorded working directory, so survey attributes them to this repo through each command's working directory and reports them as their own section: a session count, the workstream clusters, and an activity tally. If a section's signal is empty, survey says the run found none of it. It never dresses an empty section up as "no decisions". From a6cc0f3dd63f3f2ee3ceb146f90775c808a3c4e5 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 12:39:17 -0700 Subject: [PATCH 038/115] docs site: operating aligns gate-call names with gates-and-decisions --- docs/site/running-workflows/operating.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/site/running-workflows/operating.md b/docs/site/running-workflows/operating.md index 19acc174..85d8f260 100644 --- a/docs/site/running-workflows/operating.md +++ b/docs/site/running-workflows/operating.md @@ -1,6 +1,6 @@ # Operating a workflow -Operating a workflow is a loop: see what is ready, dispatch the first officer to move it, and make a decision when work reaches a gate. The captain drives that loop; the first officer does the orchestration and the ensigns do the stage work. This page covers the loop, the `spacedock status` queries that show you the state, and how to handle a gate. +Operating a workflow is a loop: see what is ready, dispatch the first officer to move it, and make a decision when work reaches a gate. The captain drives that loop; the first officer does the orchestration and the ensigns do the stage work. ## The day-to-day loop @@ -60,6 +60,6 @@ It stops and returns to you only at a gate, at a terminal entity's merge ceremon ## Handle gate decisions -A gate stops the loop and hands you the call: the first officer presents the stage report and its review, then waits. It never self-approves. You make one of three calls: **approve**, **send it back with direction**, or **reject**. What each one does, what the gate report carries, and the feedback-cycle cap are covered in full in [the three calls](../concepts/gates-and-decisions.md#the-three-calls). +A gate stops the loop and hands you the call: the first officer presents the stage report and its review, then waits. It never self-approves. You make one of three calls: **approve**, **redo with feedback**, or **reject**. What each one does, what the gate report carries, and the feedback-cycle cap are covered in full in [the three calls](../concepts/gates-and-decisions.md#the-three-calls). When you approve a terminal stage, the entity is closed: the first officer records the merge, sets the `completed` timestamp and `verdict`, clears the worktree, and tears the worker down. At that point the loop returns to the top: run `status --next` and see what moved into reach. From 967f2fc37c1113815c79452b27b068f51c2163e2 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 12:39:45 -0700 Subject: [PATCH 039/115] docs site: comm-officer polish on survey --- docs/site/running-workflows/survey.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/site/running-workflows/survey.md b/docs/site/running-workflows/survey.md index 0a1f9a46..c988543a 100644 --- a/docs/site/running-workflows/survey.md +++ b/docs/site/running-workflows/survey.md @@ -1,6 +1,6 @@ # Survey an existing project -`/spacedock:survey` reads a brownfield project's agent history and reports what the agents have implicitly been doing, then offers to commission a workflow from what it found. Run it when you arrive at or return to a repo that already has agent sessions and want the lay of the land before doing anything else. It never edits your files; the only stop in the flow is the commission offer at the end. +`/spacedock:survey` reads a brownfield project's agent history and reports what the agents have implicitly been doing, then offers to commission a workflow from what it found. Run it when you arrive at or return to a repo that already has agent sessions and want the lay of the land before doing anything else. It never edits your files; the commission offer at the end is the only pause. Survey is the recommended first launch. Point Spacedock at a project and hand it the survey skill: @@ -23,7 +23,7 @@ If the repo has no Claude agent history, survey says so plainly and stops. There ## What it reports -Survey leads with a one-line headline (the project, the session count, the date range, and the decision and interruption counts), then renders the body in the same turn. The body is the value, so it does not pause for a confirmation before showing you the sections: +Survey leads with a one-line headline (the project, the session count, the date range, and the decision and interruption counts), then renders the body in the same turn. The body is the value, so it renders all sections in the same turn without pausing for confirmation: - **Inferred workflow.** The implicit loop reconstructed from the decisions and prompts, as an arrow chain, with one honest line about it. - **Workstreams.** The decisions and prompts clustered into tracks, each tagged with its work mode (see below). @@ -47,7 +47,7 @@ The match is conservative: a fork is dropped only on a confident repo match, bec ## The commission offer -Survey closes by offering to commission a workflow from what it found, and the offer is keyed to each track's work mode, so it is not one undifferentiated pitch. Survey classifies each track as **mechanical**, **exploration**, or **unlabeled**: +Survey closes by offering to commission a workflow from what it found, and the offer is keyed to each track's work mode, so each track gets a distinct pitch. Survey classifies each track as **mechanical**, **exploration**, or **unlabeled**: - **Mechanical tracks** (the routine issue → worktree → PR loop) get an **automation** offer: a workflow that gates the crucial decisions and lets the agent drive the loop between gates. - **Exploration tracks** (creative, content, or design work where your steering is the point) get a **book-keeping** offer: structure for the parallel threads, tracking each draft or path and its state (in-flight / paused-by-choice / abandoned). There is no automate-the-human-out pitch here. The involvement is the work. From d3935e6127aaea52490924da1d7a4f97369680d8 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 12:40:45 -0700 Subject: [PATCH 040/115] docs site: comm-officer polish on operating --- docs/site/running-workflows/operating.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/site/running-workflows/operating.md b/docs/site/running-workflows/operating.md index 85d8f260..9d184261 100644 --- a/docs/site/running-workflows/operating.md +++ b/docs/site/running-workflows/operating.md @@ -54,12 +54,12 @@ Hand the first officer the workflow and let it run the dispatch cycle. Launch wi spacedock claude "/spacedock:first-officer operate the workflow in docs/dev" ``` -The first officer reads the workflow `README.md`, runs its own `status --next`, and for each dispatchable entity it dispatches an ensign to move the entity through its next stage. The ensign does the stage work (write the design, produce the deliverable, run the validation), commits, and files a stage report. The first officer reads the report, checks it against the stage's outputs and the entity's acceptance criteria, and advances the entity. A completed non-gated, non-terminal stage is not a stopping point: the first officer advances it and dispatches the next stage on its own, without waiting for you. +The first officer reads the workflow `README.md`, runs its own `status --next`, and for each dispatchable entity it dispatches an ensign to move the entity through its next stage. The ensign does the stage work (write the design, produce the deliverable, run the validation), commits, and files a stage report. The first officer reads the report, checks it against the stage's outputs and the entity's acceptance criteria, and advances the entity. A completed non-gated, non-terminal stage flows forward: the first officer advances it and dispatches the next stage on its own, without waiting for you. It stops and returns to you only at a gate, at a terminal entity's merge ceremony, on a blocker, or when nothing is left to dispatch. ## Handle gate decisions -A gate stops the loop and hands you the call: the first officer presents the stage report and its review, then waits. It never self-approves. You make one of three calls: **approve**, **redo with feedback**, or **reject**. What each one does, what the gate report carries, and the feedback-cycle cap are covered in full in [the three calls](../concepts/gates-and-decisions.md#the-three-calls). +A gate stops the loop and hands you the call: the first officer presents the stage report and its review, then waits. It never self-approves. You make one of three calls: **approve**, **redo with feedback**, or **reject**. [The three calls](../concepts/gates-and-decisions.md#the-three-calls) covers what each one does, what the gate report carries, and the feedback-cycle cap. When you approve a terminal stage, the entity is closed: the first officer records the merge, sets the `completed` timestamp and `verdict`, clears the worktree, and tears the worker down. At that point the loop returns to the top: run `status --next` and see what moved into reach. From bcff4c77ae1858b00576791f344a18b17b606ef0 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 12:41:31 -0700 Subject: [PATCH 041/115] docs site: comm-officer polish on commission follow-up and debrief-and-refit --- docs/site/running-workflows/commission.md | 2 +- docs/site/running-workflows/debrief-and-refit.md | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/site/running-workflows/commission.md b/docs/site/running-workflows/commission.md index e129b2d9..65a075c4 100644 --- a/docs/site/running-workflows/commission.md +++ b/docs/site/running-workflows/commission.md @@ -58,4 +58,4 @@ To run the workflow in any later session, launch the first officer again: spacedock claude ``` -It reads the workflow state, picks up where the last session left off, and dispatches agents for any entity ready for its next stage. Day-to-day operation (seeing what is ready, dispatching, and handling gate decisions) is covered in [Operating a workflow](operating.md). +It reads the workflow state, picks up where the last session left off, and dispatches agents for any entity ready for its next stage. [Operating a workflow](operating.md) covers the day-to-day loop: seeing what is ready, dispatching, and handling gate decisions. diff --git a/docs/site/running-workflows/debrief-and-refit.md b/docs/site/running-workflows/debrief-and-refit.md index 88d35d4a..4e96d8ce 100644 --- a/docs/site/running-workflows/debrief-and-refit.md +++ b/docs/site/running-workflows/debrief-and-refit.md @@ -14,7 +14,7 @@ spacedock claude "/spacedock:debrief" The skill works in four phases. You make the decisions at the boundaries; everything else is git and local-file reads, with no external services until you ask it to file an issue. -1. **Discovery.** It finds the workflow with `spacedock status --discover`, then anchors the session start. If a prior debrief exists in `{dir}/_debriefs/`, the new session starts at the commit after that debrief's `last-commit` frontmatter field; if none exists, it falls back to the first commit in the workflow directory or the last 24 hours. It shows you the session boundary (since-commit and commit count) and waits for you to confirm or supply a different starting commit. +1. **Discovery.** It finds the workflow with `spacedock status --discover`, then anchors the session start. If a prior debrief exists in `{dir}/_debriefs/`, the new session starts at the commit after that debrief's `last-commit` frontmatter field; if none exists, it falls back to the first commit in the workflow directory or the last 24 hours. It shows you the session boundary (since-commit and commit count) and waits for your confirmation or a corrected starting commit. 2. **Extract.** It buckets every commit in range: PR squash-merges roll up into a **Shipped** section as a PR link, never enumerated; routine state churn (`dispatch:`, `advance:`, `state:`) is suppressed; only workflow-only commits that never flowed through a PR (`docs:`, `feedback:`, `ideation:`, reverts) are listed. It reads entity frontmatter to find what reached `done`, scans for gate approvals and rejections, and runs `spacedock status --workflow-dir {dir} --next` to populate **What's next**. @@ -38,9 +38,9 @@ You must give it the workflow directory: spacedock claude "/spacedock:refit path/to/workflow" ``` -It reads the version stamp from the README frontmatter (`commissioned-by: spacedock@X.Y.Z`) and each mod's `version` field, compares them against the current version from the plugin manifest, and stops with "Workflow is already up to date." if everything matches. Otherwise it presents an upgrade plan and proceeds per file by strategy: +It reads the version stamp from the README frontmatter (`commissioned-by: spacedock@X.Y.Z`) and each mod's `version` field, then compares them against the current version from the plugin manifest. If everything matches it stops with "Workflow is already up to date." Otherwise it presents an upgrade plan and proceeds per file by strategy: -- **`README.md`: show diff, never auto-replace.** Because you customize stages, schema fields, and quality criteria here, the skill generates what the current template would produce, diffs it against your README, and leaves it to you to apply the changes you want. It does not modify the README itself, only the version stamp at the end. +- **`README.md`: show diff, never auto-replace.** Because you customize stages, schema fields, and quality criteria here, the skill generates what the current template would produce, diffs it against your README, and leaves it to you to apply the changes you want. It modifies only the version stamp at the end, not the README body. - **`_mods/{name}.md`: version diff.** For each installed mod it compares your `version` against the canonical mod at `mods/{name}.md`. Matching versions are skipped; differing versions get a diff and a y/n. A mod with no canonical match is treated as custom: acknowledged, no action. Canonical mods you don't have installed are offered for install. - **`status` (legacy): remove.** A workflow-local `status` script predates the launcher. The status viewer is now the `spacedock status` command, so refit removes the local copy with `git rm`. From 7605ac22a0c96fbdda2f9eb3022282973796ce0b Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 12:45:51 -0700 Subject: [PATCH 042/115] docs site: worked-example restores the payoff sentence comm-officer flagged as over-compressed --- docs/site/concepts/worked-example.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/site/concepts/worked-example.md b/docs/site/concepts/worked-example.md index 69f58d73..ca31cd03 100644 --- a/docs/site/concepts/worked-example.md +++ b/docs/site/concepts/worked-example.md @@ -112,7 +112,8 @@ The terminal stage records the outcome in frontmatter: `status: done`, > kb / qa / z9 / vh entities are all `status: done`, `verdict: PASSED`, archived, > with PR refs #327 / #328 / #329 / #330. -The machine's point: nothing reached `done` on assertion alone. `z9` advanced only on an approved design, an isolated implementation, a +That is the whole point of the machine: nothing reached `done` on assertion +alone. `z9` advanced only on an approved design, an isolated implementation, a fresh validation, a detached audit that failed to break it, and an explicit captain verdict. Each one a decision, each one on the record. From 3d40f19499b52732c5c2f7a97d6d80f707b0ac66 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 12:47:11 -0700 Subject: [PATCH 043/115] docs site: commission recasts pilot sentence without prose em-dash (AGENTS.md ban) --- docs/site/running-workflows/commission.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/site/running-workflows/commission.md b/docs/site/running-workflows/commission.md index 65a075c4..63d9c9e6 100644 --- a/docs/site/running-workflows/commission.md +++ b/docs/site/running-workflows/commission.md @@ -45,7 +45,7 @@ Editing here costs minutes; un-editing after agents have been dispatched against ## What the first officer does next -Commission generates the files and then assumes the first-officer role itself to run the pilot — no separate launch step needed. +Commission generates the files, then assumes the first-officer role itself to run the pilot; no separate launch step is needed. 1. It loads the [first officer's operating contract](../concepts/operating-model.md) and reads the workflow README you just generated. 2. It runs `spacedock status --boot` to read the workflow's current state. From 42a954f318171718242fd832f674a351503bd0b3 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 12:48:23 -0700 Subject: [PATCH 044/115] docs site: survey dedupes same-turn phrasing introduced by late polish --- docs/site/running-workflows/survey.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/site/running-workflows/survey.md b/docs/site/running-workflows/survey.md index c988543a..ed80a407 100644 --- a/docs/site/running-workflows/survey.md +++ b/docs/site/running-workflows/survey.md @@ -23,7 +23,7 @@ If the repo has no Claude agent history, survey says so plainly and stops. There ## What it reports -Survey leads with a one-line headline (the project, the session count, the date range, and the decision and interruption counts), then renders the body in the same turn. The body is the value, so it renders all sections in the same turn without pausing for confirmation: +Survey leads with a one-line headline (the project, the session count, the date range, and the decision and interruption counts), then renders the body in the same turn. The body is the value, so the sections follow without a confirmation pause: - **Inferred workflow.** The implicit loop reconstructed from the decisions and prompts, as an arrow chain, with one honest line about it. - **Workstreams.** The decisions and prompts clustered into tracks, each tagged with its work mode (see below). From 0d47519a86718802b787b901901bb74460cf16fe Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 12:56:54 -0700 Subject: [PATCH 045/115] =?UTF-8?q?docs=20site:=20install=20is=20just=20in?= =?UTF-8?q?stall=20=E2=80=94=20drop=20launcher/plugin=20split=20and=20Conf?= =?UTF-8?q?irm=20section;=20Spacedock=20manages=20the=20harness=20agents?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/site/get-started/install.md | 47 ++++++++++---------------------- 1 file changed, 14 insertions(+), 33 deletions(-) diff --git a/docs/site/get-started/install.md b/docs/site/get-started/install.md index 90c130eb..b9b90516 100644 --- a/docs/site/get-started/install.md +++ b/docs/site/get-started/install.md @@ -4,17 +4,6 @@ Spacedock plugs into a coding agent harness you already run: Claude Code, Codex, or Pi. Install one of those first. Every command below names the output to expect, so you can check each step. -Spacedock itself is two pieces that install separately: - -1. **The `spacedock` launcher.** The command you run to start a session. -2. **The host plugin.** The first-officer and ensign agents, loaded by your - harness (Claude Code, Codex, or Pi). - -The recommended setup installs the launcher with Homebrew, then adds the plugin. -A from-source build is available for development. - -## Install the launcher - === "macOS (Homebrew)" ```bash @@ -50,24 +39,16 @@ A from-source build is available for development. === "Codex or Pi" Claude Code is the primary surface; Codex and Pi are supported but - experimental. Install the launcher with Homebrew (the macOS tab), then add - the plugin for your host: + experimental. Install with Homebrew (the macOS tab) or the Linux script, + then add Spacedock's agents to your host: ```bash spacedock install --host codex # or: --host pi ``` - Codex installs plugins from your shell rather than programmatically, so this + Codex installs from your shell rather than programmatically, so this prints the `codex plugin` commands to run. -## Confirm it - -```bash -spacedock --version -``` - -Prints the installed version, e.g. `spacedock 0.20.0`. - ## Launch Point Spacedock at a project you already have and let it survey: @@ -76,30 +57,30 @@ Point Spacedock at a project you already have and let it survey: spacedock claude "/spacedock:survey" ``` -Starts the first officer in Claude Code and runs the survey. The first launch -also sets up the plugin, so no separate install step is needed. When a -`.safehouse` profile is present in the working directory, the launch runs -sandboxed. To set up the plugin ahead of time, or to refresh it later, run -`spacedock install --host claude`. +Starts the first officer in Claude Code and runs the survey. Spacedock manages +the agents your harness loads: the first launch sets them up in Claude Code, so +no separate setup step is needed. To set them up ahead of time, or to refresh +them later, run `spacedock install --host claude`. When a `.safehouse` profile +is present in the working directory, the launch runs sandboxed. With Codex or Pi, launch with the matching subcommand instead: `spacedock codex "your task"` or `spacedock pi "your task"`. Working on Spacedock itself? See [Build from source](https://github.com/spacedock-dev/spacedock/blob/next/docs/site/contributing/build-from-source.md). -It builds the launcher from the `next` branch and loads the plugin from your -checkout so local edits are live. +It builds from the `next` branch and loads the agents from your checkout so +local edits are live. ## Keep things in sync -`spacedock doctor` checks compatibility. If it reports the installed -plugin is out of date, refresh with: +`spacedock doctor` checks compatibility. If it reports the agents your harness +loads are out of date, refresh with: ```bash spacedock install --host claude ``` -If the `spacedock` command itself is missing, install the launcher with Homebrew -first, then run `spacedock install --host claude`. +If the `spacedock` command itself is missing, install it with Homebrew first, +then run `spacedock install --host claude`. ## Next From 392ff6aa185ae6d59aa195ee93600c47f8f85fa6 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 12:56:54 -0700 Subject: [PATCH 046/115] docs site: fold survey into first-launch; drop the Running workflows survey page --- docs/site/get-started/first-launch.md | 60 ++++++++++++++++++++++--- docs/site/index.md | 2 +- docs/site/running-workflows/survey.md | 65 --------------------------- mkdocs.yml | 1 - 4 files changed, 54 insertions(+), 74 deletions(-) delete mode 100644 docs/site/running-workflows/survey.md diff --git a/docs/site/get-started/first-launch.md b/docs/site/get-started/first-launch.md index 133b8950..1452170e 100644 --- a/docs/site/get-started/first-launch.md +++ b/docs/site/get-started/first-launch.md @@ -6,21 +6,67 @@ One command starts your first session and orients you in a project you already h spacedock claude "/spacedock:survey" ``` -This launches the [first officer](../concepts/operating-model.md#three-roles) (the orchestrator agent that runs a Spacedock workflow) inside Claude Code and hands it the survey task. The first launch also sets up the plugin; no separate setup step is needed. +This launches the [first officer](../concepts/operating-model.md#three-roles) (the orchestrator agent that runs a Spacedock workflow) inside Claude Code and hands it the survey task. The first launch also sets up the agents Claude Code loads; no separate setup step is needed. Run it from inside a project that already has some agent history, such as a repo you have been coding in with Claude Code. Survey reads that history; an empty directory has nothing to report. -## What survey reports +## What survey reads -In one read-only pass (it never edits your files), survey reconstructs what the agents in this project have been doing. Under a one-line headline (project, sessions, date range, decision and interruption counts), the report leads with **the decisions still open and waiting on you**. Then it names the [workflow](../concepts/workflows-and-entities.md) you have been running without naming it, the distinct workstreams, and how often you have had to step in. If the project has no agent history, survey says so and stops. +Survey reads recorded agent session history through `agentsview`, a session-history tool. It does not parse raw logs by hand. It drives the `agentsview` binary to sync this project's sessions into a process-readable copy, then runs a fixed set of labeled, read-only SQL queries against that copy. The queries live in `skills/survey/references/queries.sql`, one labeled query per concern, so nothing is a black box. -For the full section-by-section breakdown and how survey reads your history, see [what survey reports](../running-workflows/survey.md#what-it-reports). +Two behaviors matter when you run it: -## What comes next +- **It scopes to this repo by identity, not by name.** Survey resolves the repo root and scopes every query to that absolute path prefix. Because `agentsview` keys each session's project by the git-root basename, a same-basename sibling repo elsewhere on disk would otherwise fold in; the path-prefix scope keeps it out, and admits every checkout of this repo: the root, a subdir, a worktree. +- **If `agentsview` is missing, it asks before installing.** Survey needs `agentsview` to read the logs. When the binary is absent it tells you so and asks consent; on a yes it installs (`brew install --cask agentsview`, or the install-script fallback). It never installs without an explicit yes. If the sync fails for any reason (network, disk, permissions), it reports the exact failure and stops rather than guessing. -Survey ends with an offer, not an action. It asks whether you want it to [commission](../running-workflows/commission.md) a real Spacedock workflow built from what it found, turning the open decisions into [approval gates](../concepts/gates-and-decisions.md) and the workstreams into work items. You can say yes and let it scaffold the workflow, or say no and keep the survey as a standalone orientation. Either way, nothing has changed in your project until you choose. +If the repo has no Claude agent history, survey says so plainly and stops. There is nothing to discover. -To go straight to defining a workflow yourself instead, see [your first workflow](first-workflow.md). If `spacedock` is not yet installed, start with [installing Spacedock](install.md). +## What it reports + +Survey leads with a one-line headline (the project, the session count, the date range, and the decision and interruption counts), then renders the body in the same turn. The body is the value, so the sections follow without a confirmation pause: + +- **Inferred workflow.** The implicit loop reconstructed from the decisions and prompts, as an arrow chain, with one honest line about it. +- **Workstreams.** The decisions and prompts clustered into tracks, each tagged with its work mode (see below). +- **Work by area.** Where edits actually landed, by logical area (`src`, `internal`, `docs`, …) regardless of physical location. A worktree edit counts toward its area, so worktree-based work is not hidden. Genuine config paths (`.claude`, `.beads`, `.git`) and external sibling references demote to a footnote. +- **Needs you.** The open decisions, the forks raised but never resolved. **Survey leads the report with these**, because they are the work blocked on you. Exploration threads you are deliberately holding are separated from mechanical questions awaiting an answer. +- **Recent decisions** and **interruptions**: the answered or shipped forks, and how often you had to step in. +- **Scaffold.** If another agent scaffold is in use (superpowers, gsd / get-shit-done, or another `.claude` skill tree), survey states it as a fact: the family, its invocation count, and whether it is checked in on disk. +- **Codex** (only when present). Codex sessions land with no recorded working directory, so survey attributes them to this repo through each command's working directory and reports them as their own section: a session count, the workstream clusters, and an activity tally. + +If a section's signal is empty, survey says the run found none of it. It never dresses an empty section up as "no decisions". + +### The open frontier is cross-checked + +The open-decision scan reads transcripts only, which cannot tell a shipped fork from a still-open one. Before presenting the frontier, survey cross-references the repo (`git log`, merged PRs, the working tree) and splits each open fork three ways: + +- **shipped**: a confident match to a merged PR or commit. Dropped from the frontier. +- **decided, not shipped**: moved to a backlog line. +- **never decided**: stays on the `NEEDS YOU` frontier. + +The match is conservative: a fork is dropped only on a confident repo match, because a false "still open" is a cheap nudge while a false "shipped" silently hides real open work. When no repo signal is available, whether because this is not a git repo or because the lookups fail, the frontier degrades to transcript-only and every open fork is flagged `unverified` rather than presented as authoritative. + +## The commission offer + +Survey ends with an offer, not an action. It asks whether you want it to [commission](../running-workflows/commission.md) a real Spacedock [workflow](../concepts/workflows-and-entities.md) built from what it found, turning the open decisions into [approval gates](../concepts/gates-and-decisions.md) and the workstreams into work items. Nothing has changed in your project until you say yes. + +The offer is keyed to each track's work mode, so each track gets a distinct pitch. Survey classifies each track as **mechanical**, **exploration**, or **unlabeled**: + +- **Mechanical tracks** (the routine issue → worktree → PR loop) get an **automation** offer: a workflow that gates the crucial decisions and lets the agent drive the loop between gates. +- **Exploration tracks** (creative, content, or design work where your steering is the point) get a **book-keeping** offer: structure for the parallel threads, tracking each draft or path and its state (in-flight / paused-by-choice / abandoned). There is no automate-the-human-out pitch here. The involvement is the work. +- **Unlabeled tracks** get the generic book-keeping offer, never a guessed automation pitch. + +A project with both modes gets both offers. Each offer cites a real number from the scan: the track names, the gate-pass count, the open forks, the cancelled-path count. + +On a **yes**, survey hands off to commission in batch mode, assembling the inputs from the scan: + +- **stages** ← the inferred workflow loop; +- **seed entities** ← the workstreams; +- **approval gates** ← the open forks that survived the repo cross-check; +- **mission and entity** ← inferred from the workstreams and the project. + +Survey does not write the workflow files itself; file generation stays commission's job. On a **no**, it stops; the survey stands on its own as orientation. + +To define a workflow yourself instead, see [your first workflow](first-workflow.md). If `spacedock` is not yet installed, start with [installing Spacedock](install.md). ## The command grammar diff --git a/docs/site/index.md b/docs/site/index.md index 4efce4e0..c0366415 100644 --- a/docs/site/index.md +++ b/docs/site/index.md @@ -18,7 +18,7 @@ You are the captain. You set the bar and make the calls; the agents do the rest. - **[Get started](get-started/install.md)**: [install](get-started/install.md) Spacedock, then pick an entry. [Survey an existing project](get-started/first-launch.md) to see where your agents burn your time and surface the workflow you are already running without naming it. Or [start a fresh workflow](get-started/first-workflow.md) from a common shape like development or research. - **[Concepts](concepts/operating-model.md)** covers the operating model, workflows and entities, the stage lifecycle, gates and decisions, and a worked example. -- **[Running workflows](running-workflows/commission.md)** walks through commissioning a workflow, surveying an existing project, operating a running workflow, and debriefing and refitting between sessions. +- **[Running workflows](running-workflows/commission.md)** walks through commissioning a workflow, operating a running workflow, and debriefing and refitting between sessions. ## For agents using Spacedock diff --git a/docs/site/running-workflows/survey.md b/docs/site/running-workflows/survey.md deleted file mode 100644 index ed80a407..00000000 --- a/docs/site/running-workflows/survey.md +++ /dev/null @@ -1,65 +0,0 @@ -# Survey an existing project - -`/spacedock:survey` reads a brownfield project's agent history and reports what the agents have implicitly been doing, then offers to commission a workflow from what it found. Run it when you arrive at or return to a repo that already has agent sessions and want the lay of the land before doing anything else. It never edits your files; the commission offer at the end is the only pause. - -Survey is the recommended first launch. Point Spacedock at a project and hand it the survey skill: - -```bash -spacedock claude "/spacedock:survey" -``` - -This starts the first officer in Claude Code and runs the survey. The new-user walkthrough is in [Your first launch](../get-started/first-launch.md); this page is the operator's view of what survey does and how to read it. - -## What it reads - -Survey reads recorded agent session history through `agentsview`, a session-history tool. It does not parse raw logs by hand. It drives the `agentsview` binary to sync this project's sessions into a process-readable copy, then runs a fixed set of labeled, read-only SQL queries against that copy. The queries live in `skills/survey/references/queries.sql`, one labeled query per concern, so nothing is a black box. - -Two behaviors matter when you run it: - -- **It scopes to this repo by identity, not by name.** Survey resolves the repo root and scopes every query to that absolute path prefix. Because `agentsview` keys each session's project by the git-root basename, a same-basename sibling repo elsewhere on disk would otherwise fold in; the path-prefix scope keeps it out, and admits every checkout of this repo: the root, a subdir, a worktree. -- **If `agentsview` is missing, it asks before installing.** Survey needs `agentsview` to read the logs. When the binary is absent it tells you so and asks consent; on a yes it installs (`brew install --cask agentsview`, or the install-script fallback). It never installs without an explicit yes. If the sync fails for any reason (network, disk, permissions), it reports the exact failure and stops rather than guessing. - -If the repo has no Claude agent history, survey says so plainly and stops. There is nothing to discover. - -## What it reports - -Survey leads with a one-line headline (the project, the session count, the date range, and the decision and interruption counts), then renders the body in the same turn. The body is the value, so the sections follow without a confirmation pause: - -- **Inferred workflow.** The implicit loop reconstructed from the decisions and prompts, as an arrow chain, with one honest line about it. -- **Workstreams.** The decisions and prompts clustered into tracks, each tagged with its work mode (see below). -- **Work by area.** Where edits actually landed, by logical area (`src`, `internal`, `docs`, …) regardless of physical location. A worktree edit counts toward its area, so worktree-based work is not hidden. Genuine config paths (`.claude`, `.beads`, `.git`) and external sibling references demote to a footnote. -- **Needs you.** The open decisions, the forks raised but never resolved. **Survey leads the report with these**, because they are the work blocked on you. Exploration threads you are deliberately holding are separated from mechanical questions awaiting an answer. -- **Recent decisions** and **interruptions**: the answered or shipped forks, and how often you had to step in. -- **Scaffold.** If another agent scaffold is in use (superpowers, gsd / get-shit-done, or another `.claude` skill tree), survey states it as a fact: the family, its invocation count, and whether it is checked in on disk. -- **Codex** (only when present). Codex sessions land with no recorded working directory, so survey attributes them to this repo through each command's working directory and reports them as their own section: a session count, the workstream clusters, and an activity tally. - -If a section's signal is empty, survey says the run found none of it. It never dresses an empty section up as "no decisions". - -### The open frontier is cross-checked - -The open-decision scan reads transcripts only, which cannot tell a shipped fork from a still-open one. Before presenting the frontier, survey cross-references the repo (`git log`, merged PRs, the working tree) and splits each open fork three ways: - -- **shipped**: a confident match to a merged PR or commit. Dropped from the frontier. -- **decided, not shipped**: moved to a backlog line. -- **never decided**: stays on the `NEEDS YOU` frontier. - -The match is conservative: a fork is dropped only on a confident repo match, because a false "still open" is a cheap nudge while a false "shipped" silently hides real open work. When no repo signal is available, whether because this is not a git repo or because the lookups fail, the frontier degrades to transcript-only and every open fork is flagged `unverified` rather than presented as authoritative. - -## The commission offer - -Survey closes by offering to commission a workflow from what it found, and the offer is keyed to each track's work mode, so each track gets a distinct pitch. Survey classifies each track as **mechanical**, **exploration**, or **unlabeled**: - -- **Mechanical tracks** (the routine issue → worktree → PR loop) get an **automation** offer: a workflow that gates the crucial decisions and lets the agent drive the loop between gates. -- **Exploration tracks** (creative, content, or design work where your steering is the point) get a **book-keeping** offer: structure for the parallel threads, tracking each draft or path and its state (in-flight / paused-by-choice / abandoned). There is no automate-the-human-out pitch here. The involvement is the work. -- **Unlabeled tracks** get the generic book-keeping offer, never a guessed automation pitch. - -A project with both modes gets both offers. Each offer cites a real number from the scan: the track names, the gate-pass count, the open forks, the cancelled-path count. - -On a **yes**, survey hands off to [commission](commission.md) in batch mode, assembling the inputs from the scan: - -- **stages** ← the inferred workflow loop; -- **seed entities** ← the workstreams; -- **approval gates** ← the open forks that survived the repo cross-check; -- **mission and entity** ← inferred from the workstreams and the project. - -Survey does not write the workflow files itself; file generation stays commission's job. On a **no**, it stops; the survey stands on its own as orientation. diff --git a/mkdocs.yml b/mkdocs.yml index 47831f7d..96cc6f46 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -80,7 +80,6 @@ nav: - A worked example: concepts/worked-example.md - Running workflows: - Commission a workflow: running-workflows/commission.md - - Survey an existing project: running-workflows/survey.md - Operating a workflow: running-workflows/operating.md - Debrief & refit: running-workflows/debrief-and-refit.md - Advanced topics: From 634db4bce43f4ec0487eed35eae3d3b0a5c43b90 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 13:00:04 -0700 Subject: [PATCH 047/115] =?UTF-8?q?docs=20site:=20user-visible=20first,=20?= =?UTF-8?q?mechanism=20light=20=E2=80=94=20directive=20rule=20+=20first-la?= =?UTF-8?q?unch=20survey=20sections?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/site/AGENTS.md | 1 + docs/site/get-started/first-launch.md | 30 ++++----------------------- 2 files changed, 5 insertions(+), 26 deletions(-) diff --git a/docs/site/AGENTS.md b/docs/site/AGENTS.md index 21191579..bb1e8bd4 100644 --- a/docs/site/AGENTS.md +++ b/docs/site/AGENTS.md @@ -10,6 +10,7 @@ Spacedock is not complicated; wordy docs make it *feel* complicated. Every edit - ✗ "Spacedock is a multi-agent orchestrator." - ✓ "You have work that needs doing in stages, with a human sign-off before anything ships. Spacedock runs that for you." - **Introduce the fewest terms possible, as late as possible.** Don't front-load a glossary. Define a term on first real use, gloss it once, then just use it. If a page introduces more than a handful of new terms, cut or defer some. +- **Lead with what the user sees and must know; keep the how-it-works light.** Name the visible behavior and the required concepts first. Internal mechanics (scheduling and reuse conditions, file/branch naming templates, parser internals, query plumbing) get at most a sentence or a link to the source. If a paragraph reads as protocol documentation, compress it or cut it. - **Cut, don't pad.** If a sentence still carries its meaning with a clause removed, remove the clause. If a paragraph repeats the page above it, delete it and link instead. - **Don't repeat content across pages.** One page owns each idea; others link to it. Duplicated explanation is the main thing that makes the docs feel long. - **Two levels of structure only:** section → page. No deeper nesting; no page that exists only to hold sub-pages. diff --git a/docs/site/get-started/first-launch.md b/docs/site/get-started/first-launch.md index 1452170e..af4ad57c 100644 --- a/docs/site/get-started/first-launch.md +++ b/docs/site/get-started/first-launch.md @@ -12,14 +12,7 @@ Run it from inside a project that already has some agent history, such as a repo ## What survey reads -Survey reads recorded agent session history through `agentsview`, a session-history tool. It does not parse raw logs by hand. It drives the `agentsview` binary to sync this project's sessions into a process-readable copy, then runs a fixed set of labeled, read-only SQL queries against that copy. The queries live in `skills/survey/references/queries.sql`, one labeled query per concern, so nothing is a black box. - -Two behaviors matter when you run it: - -- **It scopes to this repo by identity, not by name.** Survey resolves the repo root and scopes every query to that absolute path prefix. Because `agentsview` keys each session's project by the git-root basename, a same-basename sibling repo elsewhere on disk would otherwise fold in; the path-prefix scope keeps it out, and admits every checkout of this repo: the root, a subdir, a worktree. -- **If `agentsview` is missing, it asks before installing.** Survey needs `agentsview` to read the logs. When the binary is absent it tells you so and asks consent; on a yes it installs (`brew install --cask agentsview`, or the install-script fallback). It never installs without an explicit yes. If the sync fails for any reason (network, disk, permissions), it reports the exact failure and stops rather than guessing. - -If the repo has no Claude agent history, survey says so plainly and stops. There is nothing to discover. +Survey reads your recorded agent sessions, read-only, scoped to this repo and every checkout of it (the root, a subdir, a worktree) and nothing else on disk. It reads them through `agentsview`, a session-history tool; if that tool is missing, survey asks before installing it, and never installs without an explicit yes. If the sync fails, it reports the exact failure and stops rather than guessing. If the repo has no agent history, survey says so plainly and stops. ## What it reports @@ -31,19 +24,11 @@ Survey leads with a one-line headline (the project, the session count, the date - **Needs you.** The open decisions, the forks raised but never resolved. **Survey leads the report with these**, because they are the work blocked on you. Exploration threads you are deliberately holding are separated from mechanical questions awaiting an answer. - **Recent decisions** and **interruptions**: the answered or shipped forks, and how often you had to step in. - **Scaffold.** If another agent scaffold is in use (superpowers, gsd / get-shit-done, or another `.claude` skill tree), survey states it as a fact: the family, its invocation count, and whether it is checked in on disk. -- **Codex** (only when present). Codex sessions land with no recorded working directory, so survey attributes them to this repo through each command's working directory and reports them as their own section: a session count, the workstream clusters, and an activity tally. +- **Codex** (only when present). Codex sessions get their own section: a session count, the workstream clusters, and an activity tally. If a section's signal is empty, survey says the run found none of it. It never dresses an empty section up as "no decisions". -### The open frontier is cross-checked - -The open-decision scan reads transcripts only, which cannot tell a shipped fork from a still-open one. Before presenting the frontier, survey cross-references the repo (`git log`, merged PRs, the working tree) and splits each open fork three ways: - -- **shipped**: a confident match to a merged PR or commit. Dropped from the frontier. -- **decided, not shipped**: moved to a backlog line. -- **never decided**: stays on the `NEEDS YOU` frontier. - -The match is conservative: a fork is dropped only on a confident repo match, because a false "still open" is a cheap nudge while a false "shipped" silently hides real open work. When no repo signal is available, whether because this is not a git repo or because the lookups fail, the frontier degrades to transcript-only and every open fork is flagged `unverified` rather than presented as authoritative. +Open decisions are cross-checked against the repo before they reach you: forks that already shipped are dropped, decided-but-unshipped ones move to a backlog line, and only the never-decided stay on the `NEEDS YOU` frontier. When there is no repo signal to check against, every open fork is flagged `unverified` instead of presented as authoritative. ## The commission offer @@ -57,14 +42,7 @@ The offer is keyed to each track's work mode, so each track gets a distinct pitc A project with both modes gets both offers. Each offer cites a real number from the scan: the track names, the gate-pass count, the open forks, the cancelled-path count. -On a **yes**, survey hands off to commission in batch mode, assembling the inputs from the scan: - -- **stages** ← the inferred workflow loop; -- **seed entities** ← the workstreams; -- **approval gates** ← the open forks that survived the repo cross-check; -- **mission and entity** ← inferred from the workstreams and the project. - -Survey does not write the workflow files itself; file generation stays commission's job. On a **no**, it stops; the survey stands on its own as orientation. +On a **yes**, survey hands what it found to commission: the inferred loop becomes the proposed stages, the workstreams become the seed work items, and the open forks become the gates. File generation stays commission's job. On a **no**, it stops; the survey stands on its own as orientation. To define a workflow yourself instead, see [your first workflow](first-workflow.md). If `spacedock` is not yet installed, start with [installing Spacedock](install.md). From b90644523bb7695913a39a65b94c01a8c09fcc54 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 13:01:40 -0700 Subject: [PATCH 048/115] =?UTF-8?q?docs=20site:=20mechanism-light=20sweep?= =?UTF-8?q?=20=E2=80=94=20worktree=20mechanics,=20feedback=20routing,=20st?= =?UTF-8?q?ate=20checkout,=20debrief=20phases?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/site/concepts/gates-and-decisions.md | 9 ++------- docs/site/concepts/stage-lifecycle.md | 7 +------ docs/site/concepts/workflows-and-entities.md | 6 +++--- docs/site/running-workflows/debrief-and-refit.md | 8 ++++---- 4 files changed, 10 insertions(+), 20 deletions(-) diff --git a/docs/site/concepts/gates-and-decisions.md b/docs/site/concepts/gates-and-decisions.md index fa7be345..d8c0eedf 100644 --- a/docs/site/concepts/gates-and-decisions.md +++ b/docs/site/concepts/gates-and-decisions.md @@ -41,7 +41,7 @@ At every gate the first officer also runs an acceptance-criteria cross-check: it You answer a gate with one of three calls. -- **Approve.** The entity advances to the next stage and the first officer dispatches it, reusing the live worker when it can and dispatching fresh otherwise. If the next stage opens or closes a worktree, the `Decision` line told you so. Approving the terminal stage runs the merge and cleanup ceremony. +- **Approve.** The entity advances to the next stage and the first officer dispatches it. If the next stage opens or closes a worktree, the `Decision` line told you so. Approving the terminal stage runs the merge and cleanup ceremony. - **Redo with feedback.** You approve the direction but send concrete fixes back. Name the specific asks ("tighten the AC-2 substring assertion, correct the file path claim"), not "address the reviewer's notes". The first officer routes your asks back to the stage that owns the work, the worker re-does it, and the gate is re-presented. - **Reject.** At a stage with a `feedback-to` target, rejecting bounces the work back to that target stage to be fixed and re-validated; this is the feedback cycle below. At a stage without `feedback-to`, rejection is terminal for that path. @@ -53,12 +53,7 @@ A redo and a reject at a `feedback-to` stage run the same routing machinery. The When a feedback stage recommends `REJECTED`, or you reject at a `feedback-to` stage, the work routes back to the stage named in `feedback-to`: the stage that owns the fix, not the reviewer that flagged it. In the dev workflow, `validation` has `feedback-to: implementation`, so a rejected validation sends the deliverable back to implementation, not back to the validator. -The first officer tracks each round in a `### Feedback Cycles` section in the entity body, then: - -1. Reads the rejected stage's `feedback-to` target. -2. Routes your concrete findings to that target, reusing the live worker in the same worktree when it is still addressable and reuse conditions pass, dispatching fresh otherwise. The routed message carries the fix asks and the stage assignment. -3. Re-runs the reviewer after the fix. -4. Re-enters the gate flow with the updated result, presenting you a fresh gate review. +The first officer tracks each round in a `### Feedback Cycles` section in the entity body. Your concrete findings route to the `feedback-to` target, the reviewer re-runs after the fix, and the gate comes back to you as a fresh review. **The loop caps at three.** On cycle 3 the first officer escalates to you instead of bouncing a fourth time: the same fix has failed twice, so the call returns to a human. diff --git a/docs/site/concepts/stage-lifecycle.md b/docs/site/concepts/stage-lifecycle.md index 18cb0e6f..ece502a1 100644 --- a/docs/site/concepts/stage-lifecycle.md +++ b/docs/site/concepts/stage-lifecycle.md @@ -39,12 +39,7 @@ When validation recommends `REJECTED`, `feedback-to: implementation` routes the A stage runs in an isolated git worktree when it declares `worktree: true`, and inline at the repo root otherwise. This is the "isolation when it matters" tradeoff: stages that mutate shared state (implementation, validation) get their own checkout so concurrent entities don't collide; lighter stages that only edit the entity body (backlog, ideation) run inline. -The mechanics, run by the first officer: - -- **On first dispatch to a worktree stage,** the first officer creates a worktree at `.worktrees/{worker_key}-{slug}` on branch `{worker_key}/{slug}` and records the path in the entity's `worktree` frontmatter field. -- **Inside a worktree-backed stage,** the ensign keeps all reads, writes, and commits under that worktree. The deliverable is isolated there until the entity terminalizes. -- **In a split-root workflow** (the README declares a `state:` checkout, e.g. `state: .spacedock-state`), the entity body and stage report live in the state checkout, not in the worktree; the worktree isolates only the deliverable. The first officer's dispatch hands the ensign the correct state-checkout path for the entity; the worker trusts that path rather than writing entity state into the worktree. -- **At the terminal stage,** the first officer merges the worktree branch, clears the `worktree` field, removes the worktree, and deletes the local branch. +The first officer manages the isolation for you: it creates the worktree under `.worktrees/` on first dispatch and records the path in the entity's `worktree` frontmatter field, the stage's work and commits stay inside that checkout, and at the terminal stage it merges the branch and cleans the worktree up. In a [split-root workflow](../advanced/split-root-state.md) the entity file itself lives in the state checkout; the worktree isolates only the deliverable. To see where each entity sits and which are ready to advance, read the workflow state: diff --git a/docs/site/concepts/workflows-and-entities.md b/docs/site/concepts/workflows-and-entities.md index 7d4b0308..a67d0ba5 100644 --- a/docs/site/concepts/workflows-and-entities.md +++ b/docs/site/concepts/workflows-and-entities.md @@ -78,8 +78,8 @@ Add `--next` to list only the entities ready for dispatch. state: .spacedock-state ``` -With this set, the README (the living spec) stays on your code branch, while the entity files, their reports, and the archive live under `.spacedock-state`. Routine stage transitions never churn the code branch or collide with a feature PR. The path is resolved relative to the README's directory; `spacedock status` reads stages from the README and entities from the state checkout, and writes frontmatter updates and archive moves into the state checkout. +With this set, the README (the living spec) stays on your code branch, while the entity files, their reports, and the archive live under `.spacedock-state`. Routine stage transitions never churn the code branch or collide with a feature PR; `spacedock status` reads and writes across the split for you. -The state checkout is a linked git worktree on an orphan branch in the same repo, so state commits land on that branch and the code branch never sees them. On a fresh clone the state worktree is absent. Run `spacedock state init` to fetch the orphan branch and re-add the linked worktree before working the workflow. +State lives on a separate branch in the same repo, so the code branch never sees a state commit. On a fresh clone the state checkout is absent; run `spacedock state init` to restore it before working the workflow. -Omit `state:` (or set `state: $inline`) for a standalone workflow that isn't embedded in a code repo you ship from. Then the entities live beside the README in the same directory, with no orphan branch and no extra checkout. +Omit `state:` (or set `state: $inline`) for a standalone workflow that isn't embedded in a code repo you ship from. Then the entities live beside the README in the same directory, with no extra branch or checkout. diff --git a/docs/site/running-workflows/debrief-and-refit.md b/docs/site/running-workflows/debrief-and-refit.md index 4e96d8ce..1c2fbc18 100644 --- a/docs/site/running-workflows/debrief-and-refit.md +++ b/docs/site/running-workflows/debrief-and-refit.md @@ -14,19 +14,19 @@ spacedock claude "/spacedock:debrief" The skill works in four phases. You make the decisions at the boundaries; everything else is git and local-file reads, with no external services until you ask it to file an issue. -1. **Discovery.** It finds the workflow with `spacedock status --discover`, then anchors the session start. If a prior debrief exists in `{dir}/_debriefs/`, the new session starts at the commit after that debrief's `last-commit` frontmatter field; if none exists, it falls back to the first commit in the workflow directory or the last 24 hours. It shows you the session boundary (since-commit and commit count) and waits for your confirmation or a corrected starting commit. +1. **Discovery.** It finds the workflow, anchors the session start where the previous debrief ended (or at the workflow's recent history when there is none), shows you the boundary (since-commit and commit count), and waits for your confirmation or a corrected starting commit. -2. **Extract.** It buckets every commit in range: PR squash-merges roll up into a **Shipped** section as a PR link, never enumerated; routine state churn (`dispatch:`, `advance:`, `state:`) is suppressed; only workflow-only commits that never flowed through a PR (`docs:`, `feedback:`, `ideation:`, reverts) are listed. It reads entity frontmatter to find what reached `done`, scans for gate approvals and rejections, and runs `spacedock status --workflow-dir {dir} --next` to populate **What's next**. +2. **Extract.** It buckets every commit in range: shipped PRs roll up into a **Shipped** section as links, routine state churn is suppressed, and only workflow-only commits that never flowed through a PR are listed. It reads entity frontmatter for what reached `done`, scans for gate approvals and rejections, and fills **What's next** from the dispatchable queue. 3. **Draft and review.** It presents the draft with **Decisions** and **Observations** left as placeholders for you to fill. Add why a gate was approved or rejected, scope changes, design insights, or confirm as-is. Issues are split into **Workflow** (quirks in your pipeline, kept local) and **Spacedock** (framework bugs). For each Spacedock issue it offers to file an **anonymized** GitHub issue: the body carries the bug, repro steps, and scale, but never your mission, entity titles, or domain. You approve, edit, or decline each one before any `gh issue create` runs. -4. **Write and commit.** It writes the debrief to `{dir}/_debriefs/{date}-{sequence:02d}.md` with `first-commit`, `last-commit`, and an approximate `duration` in frontmatter, commits it with a `debrief:` prefix, and reports the path: +4. **Write and commit.** It writes the debrief to `{dir}/_debriefs/{date}-{sequence:02d}.md`, commits it, and reports the path: ``` Debrief written to {dir}/_debriefs/2026-06-09-01.md and committed. ``` -The `last-commit` field is the load-bearing part: it is the anchor the next debrief reads to know where this session ended. +The debrief's frontmatter records where the session ended, which is how the next debrief knows where to start. ## Refit: upgrade scaffolding to the current release From b65e28616f87f7d336b50614c86710d63dd5b983 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 15:41:39 -0700 Subject: [PATCH 049/115] docs site: install tabs are binary-only and short; codex/pi setup moves to Launch; Sandboxing gets its own section --- docs/site/get-started/install.md | 55 ++++++++------------------------ 1 file changed, 14 insertions(+), 41 deletions(-) diff --git a/docs/site/get-started/install.md b/docs/site/get-started/install.md index b9b90516..c471ecdf 100644 --- a/docs/site/get-started/install.md +++ b/docs/site/get-started/install.md @@ -1,8 +1,7 @@ # Install Spacedock Spacedock plugs into a coding agent harness you already run: Claude Code, Codex, -or Pi. Install one of those first. Every command below names the output to -expect, so you can check each step. +or Pi. Install one of those first. === "macOS (Homebrew)" @@ -11,43 +10,13 @@ expect, so you can check each step. brew install spacedock ``` -=== "Linux / no Homebrew" - - The Homebrew cask is macOS-only. On Linux (or on macOS without Homebrew), - the `curl | sh` script detects your OS and architecture, downloads the - matching tarball from the latest GitHub Release, verifies it against the - release `checksums.txt`, and installs the `spacedock` binary to - `~/.local/bin`. +=== "Binary (macOS / Linux)" ```bash curl -fsSL https://raw.githubusercontent.com/spacedock-dev/spacedock/next/install.sh | sh ``` - If `~/.local/bin` is not on your `PATH`, the script prints a note; add it - (`export PATH="$HOME/.local/bin:$PATH"`) so the `spacedock` command resolves. - Set `SPACEDOCK_INSTALL_DIR` to install elsewhere (e.g. - `SPACEDOCK_INSTALL_DIR=/usr/local/bin`, which may need `sudo`). - - **Sandboxing.** Safehouse behaves the same as on macOS: when a `.safehouse` - profile is present in the working directory, Spacedock wraps the launch - through the `safehouse` command. Spacedock ships no sandbox of its own. A - run is sandboxed only when a Linux-capable `safehouse` binary is on your - `PATH`; when it is absent, Spacedock prints an install hint and the launch - proceeds **unsandboxed**. Gatekeeper and quarantine handling are macOS-only - and do not apply here. - -=== "Codex or Pi" - - Claude Code is the primary surface; Codex and Pi are supported but - experimental. Install with Homebrew (the macOS tab) or the Linux script, - then add Spacedock's agents to your host: - - ```bash - spacedock install --host codex # or: --host pi - ``` - - Codex installs from your shell rather than programmatically, so this - prints the `codex plugin` commands to run. + Installs a checksum-verified binary to `~/.local/bin`. ## Launch @@ -60,16 +29,23 @@ spacedock claude "/spacedock:survey" Starts the first officer in Claude Code and runs the survey. Spacedock manages the agents your harness loads: the first launch sets them up in Claude Code, so no separate setup step is needed. To set them up ahead of time, or to refresh -them later, run `spacedock install --host claude`. When a `.safehouse` profile -is present in the working directory, the launch runs sandboxed. +them later, run `spacedock install --host claude`. -With Codex or Pi, launch with the matching subcommand instead: -`spacedock codex "your task"` or `spacedock pi "your task"`. +With Codex or Pi (experimental), add the agents with +`spacedock install --host codex` (or `--host pi`), then launch with the +matching subcommand: `spacedock codex "your task"` or `spacedock pi "your task"`. Working on Spacedock itself? See [Build from source](https://github.com/spacedock-dev/spacedock/blob/next/docs/site/contributing/build-from-source.md). It builds from the `next` branch and loads the agents from your checkout so local edits are live. +## Sandboxing + +When a `.safehouse` profile is present in the working directory, the launch +runs sandboxed through the `safehouse` command; `--safehouse` forces it. +Spacedock ships no sandbox of its own: when no `safehouse` binary is on your +`PATH`, the launch prints an install hint and proceeds **unsandboxed**. + ## Keep things in sync `spacedock doctor` checks compatibility. If it reports the agents your harness @@ -79,9 +55,6 @@ loads are out of date, refresh with: spacedock install --host claude ``` -If the `spacedock` command itself is missing, install it with Homebrew first, -then run `spacedock install --host claude`. - ## Next Run your [first launch](first-launch.md). The From 832b4ae101053f5cb1c8acd1f239c4ec9fd6fbd4 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 15:43:10 -0700 Subject: [PATCH 050/115] docs site: install replaces keep-in-sync with one-line Troubleshooting (spacedock doctor) --- docs/site/get-started/install.md | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/docs/site/get-started/install.md b/docs/site/get-started/install.md index c471ecdf..2dbfd94c 100644 --- a/docs/site/get-started/install.md +++ b/docs/site/get-started/install.md @@ -46,14 +46,10 @@ runs sandboxed through the `safehouse` command; `--safehouse` forces it. Spacedock ships no sandbox of its own: when no `safehouse` binary is on your `PATH`, the launch prints an install hint and proceeds **unsandboxed**. -## Keep things in sync +## Troubleshooting -`spacedock doctor` checks compatibility. If it reports the agents your harness -loads are out of date, refresh with: - -```bash -spacedock install --host claude -``` +Run `spacedock doctor`. It checks the install and names anything missing or +out of date. ## Next From 5aade2fefddc302c3b8c1899c7459cdf0a1abc83 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 15:44:58 -0700 Subject: [PATCH 051/115] docs site: point install.sh and all GitHub source links at main, not next --- docs/site/advanced/mods-and-standing-teammates.md | 4 ++-- docs/site/advanced/split-root-state.md | 2 +- docs/site/concepts/stage-lifecycle.md | 2 +- docs/site/concepts/worked-example.md | 10 +++++----- docs/site/get-started/install.md | 8 ++++---- docs/site/reference/frontmatter-contract.md | 2 +- mkdocs.yml | 2 +- 7 files changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/site/advanced/mods-and-standing-teammates.md b/docs/site/advanced/mods-and-standing-teammates.md index bd9fd4fc..0b3062f8 100644 --- a/docs/site/advanced/mods-and-standing-teammates.md +++ b/docs/site/advanced/mods-and-standing-teammates.md @@ -8,7 +8,7 @@ A mod does one of two things, or both. A hook runs first-officer prose at a fixed point in the run: at `startup`, on an `idle` pass when nothing is ready to dispatch, or at the `merge` boundary when an entity terminalizes. The point is workflow-independent: any workflow can register the same hook to get the same behavior. -The canonical example is the [`pr-merge` mod](https://github.com/spacedock-dev/spacedock/blob/next/docs/dev/_mods/pr-merge.md): it opens the code-branch PR at merge, records the PR on the entity, and holds the terminal transition until the PR merges. A merge hook can block that transition, and the binary enforces the block so a half-merged entity cannot slip past the gate. +The canonical example is the [`pr-merge` mod](https://github.com/spacedock-dev/spacedock/blob/main/docs/dev/_mods/pr-merge.md): it opens the code-branch PR at merge, records the PR on the entity, and holds the terminal transition until the PR merges. A merge hook can block that transition, and the binary enforces the block so a half-merged entity cannot slip past the gate. ## Standing teammates @@ -18,4 +18,4 @@ The canonical example is the **comm-officer**, a prose-polisher the first office ## The exact format -The mod file format, the hook points, and the `spacedock dispatch` subcommands that read standing-teammate mods are defined in the skills and binary that own them. See [the mods reference](https://github.com/spacedock-dev/spacedock/blob/next/docs/dev/README.md) for the authoritative contract. +The mod file format, the hook points, and the `spacedock dispatch` subcommands that read standing-teammate mods are defined in the skills and binary that own them. See [the mods reference](https://github.com/spacedock-dev/spacedock/blob/main/docs/dev/README.md) for the authoritative contract. diff --git a/docs/site/advanced/split-root-state.md b/docs/site/advanced/split-root-state.md index 2045f424..6c955325 100644 --- a/docs/site/advanced/split-root-state.md +++ b/docs/site/advanced/split-root-state.md @@ -22,7 +22,7 @@ The shipped `docs/dev` workflow runs split-root; see its README for a live examp ## Concurrent writers -The state checkout is a shared git index that multiple agents commit to, so the commit and sync discipline is a correctness requirement, not a style choice: writers commit path-scoped (never a bare `git add -A`), and conflicting edits to the same entity halt for the captain rather than auto-resolving. The exact protocol is owned by the launcher and the ensign skill; see [the split-root state contract](https://github.com/spacedock-dev/spacedock/blob/next/docs/dev/README.md) for the authoritative rules. +The state checkout is a shared git index that multiple agents commit to, so the commit and sync discipline is a correctness requirement, not a style choice: writers commit path-scoped (never a bare `git add -A`), and conflicting edits to the same entity halt for the captain rather than auto-resolving. The exact protocol is owned by the launcher and the ensign skill; see [the split-root state contract](https://github.com/spacedock-dev/spacedock/blob/main/docs/dev/README.md) for the authoritative rules. ## Bridging an external tracker diff --git a/docs/site/concepts/stage-lifecycle.md b/docs/site/concepts/stage-lifecycle.md index ece502a1..8d509985 100644 --- a/docs/site/concepts/stage-lifecycle.md +++ b/docs/site/concepts/stage-lifecycle.md @@ -4,7 +4,7 @@ An entity moves through an ordered chain of stages that the workflow defines, on ## The dev workflow's stages -The five stages below are the dev workflow's stages, used as the running example for this page; the full per-stage Inputs/Outputs/Good/Bad detail lives in its [README](https://github.com/spacedock-dev/spacedock/blob/next/docs/dev/README.md). Read the chain as a pipeline: each stage takes the prior stage's output as its input, and the bar rises from "is this clear?" to "is this proven?". +The five stages below are the dev workflow's stages, used as the running example for this page; the full per-stage Inputs/Outputs/Good/Bad detail lives in its [README](https://github.com/spacedock-dev/spacedock/blob/main/docs/dev/README.md). Read the chain as a pipeline: each stage takes the prior stage's output as its input, and the bar rises from "is this clear?" to "is this proven?". - **`backlog`, the seed.** An entity enters here when first proposed: a title, a source, a brief description, and the test gates future stages must satisfy. No design work yet. `initial: true`, so this is where every new entity starts. The dev workflow also marks it `gate: true`, so the first officer presents a new entity for your go-ahead before it advances. - **`ideation`, the design.** A worker clarifies the problem, explores approaches, and produces a fleshed-out body: problem statement, proposed approach, acceptance criteria, and a test plan. Each acceptance criterion names how it will be checked. This stage is `gate: true` in the dev workflow, so the first officer presents the design for your approval before any code is written. diff --git a/docs/site/concepts/worked-example.md b/docs/site/concepts/worked-example.md index ca31cd03..ccef90d1 100644 --- a/docs/site/concepts/worked-example.md +++ b/docs/site/concepts/worked-example.md @@ -8,7 +8,7 @@ decides at each one. The workflow is `docs/dev` (the Spacedock v1 dev workflow); its stages, gates, and entity schema are defined in -[the development workflow README](https://github.com/spacedock-dev/spacedock/blob/next/docs/dev/README.md). +[the development workflow README](https://github.com/spacedock-dev/spacedock/blob/main/docs/dev/README.md). Runtime entity state lives in a separate `.spacedock-state` checkout, so the finished entity itself is not in the main tree. Its full trajectory is in the `0198-pre-flip-hardening` sprint directory: `index.md`, @@ -121,7 +121,7 @@ captain verdict. Each one a decision, each one on the record. The full trajectory is reconstructable from the sprint directory: -- [`index.md`](https://github.com/spacedock-dev/spacedock/blob/next/docs/roadmap/0198-pre-flip-hardening/index.md): goal, members, definition of done, the approved-gate note. -- [`dispatch-sprint-execution.md`](https://github.com/spacedock-dev/spacedock/blob/next/docs/roadmap/0198-pre-flip-hardening/dispatch-sprint-execution.md): the per-member drive plan and `z9`'s build notes. -- [`debrief.md`](https://github.com/spacedock-dev/spacedock/blob/next/docs/roadmap/0198-pre-flip-hardening/debrief.md): what shipped, the PR links, and the decisions made along the way. -- [`post-sprint-audit.md`](https://github.com/spacedock-dev/spacedock/blob/next/docs/roadmap/0198-pre-flip-hardening/post-sprint-audit.md): the final-state confirmation and the detached-audit record. +- [`index.md`](https://github.com/spacedock-dev/spacedock/blob/main/docs/roadmap/0198-pre-flip-hardening/index.md): goal, members, definition of done, the approved-gate note. +- [`dispatch-sprint-execution.md`](https://github.com/spacedock-dev/spacedock/blob/main/docs/roadmap/0198-pre-flip-hardening/dispatch-sprint-execution.md): the per-member drive plan and `z9`'s build notes. +- [`debrief.md`](https://github.com/spacedock-dev/spacedock/blob/main/docs/roadmap/0198-pre-flip-hardening/debrief.md): what shipped, the PR links, and the decisions made along the way. +- [`post-sprint-audit.md`](https://github.com/spacedock-dev/spacedock/blob/main/docs/roadmap/0198-pre-flip-hardening/post-sprint-audit.md): the final-state confirmation and the detached-audit record. diff --git a/docs/site/get-started/install.md b/docs/site/get-started/install.md index 2dbfd94c..23a22155 100644 --- a/docs/site/get-started/install.md +++ b/docs/site/get-started/install.md @@ -13,7 +13,7 @@ or Pi. Install one of those first. === "Binary (macOS / Linux)" ```bash - curl -fsSL https://raw.githubusercontent.com/spacedock-dev/spacedock/next/install.sh | sh + curl -fsSL https://raw.githubusercontent.com/spacedock-dev/spacedock/main/install.sh | sh ``` Installs a checksum-verified binary to `~/.local/bin`. @@ -35,9 +35,9 @@ With Codex or Pi (experimental), add the agents with `spacedock install --host codex` (or `--host pi`), then launch with the matching subcommand: `spacedock codex "your task"` or `spacedock pi "your task"`. -Working on Spacedock itself? See [Build from source](https://github.com/spacedock-dev/spacedock/blob/next/docs/site/contributing/build-from-source.md). -It builds from the `next` branch and loads the agents from your checkout so -local edits are live. +Working on Spacedock itself? See [Build from source](https://github.com/spacedock-dev/spacedock/blob/main/docs/site/contributing/build-from-source.md). +It builds the binary from your checkout and loads the agents from it, so local +edits are live. ## Sandboxing diff --git a/docs/site/reference/frontmatter-contract.md b/docs/site/reference/frontmatter-contract.md index adb4810c..2dd7b111 100644 --- a/docs/site/reference/frontmatter-contract.md +++ b/docs/site/reference/frontmatter-contract.md @@ -1,6 +1,6 @@ # Frontmatter contract -Every entity is a markdown file (or a folder with an `index.md`) whose YAML frontmatter carries the fields Spacedock reads to track and move it. This page is a quick lookup for the fields a development-workflow entity uses. The always-current schema is owned by the [development workflow README](https://github.com/spacedock-dev/spacedock/blob/next/docs/dev/README.md#field-reference); when this table and that README disagree, the README wins. +Every entity is a markdown file (or a folder with an `index.md`) whose YAML frontmatter carries the fields Spacedock reads to track and move it. This page is a quick lookup for the fields a development-workflow entity uses. The always-current schema is owned by the [development workflow README](https://github.com/spacedock-dev/spacedock/blob/main/docs/dev/README.md#field-reference); when this table and that README disagree, the README wins. Keep fields flat and top-level; add more flat custom fields rather than nested YAML. (The [entity frontmatter concept](../concepts/workflows-and-entities.md#entity-frontmatter) explains why the line-oriented parser requires this.) diff --git a/mkdocs.yml b/mkdocs.yml index 96cc6f46..c2ffd52f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -88,7 +88,7 @@ nav: - Reference: - Command reference: reference/command-reference.md - Frontmatter contract: reference/frontmatter-contract.md - - Contributing: https://github.com/spacedock-dev/spacedock/blob/next/CONTRIBUTING.md + - Contributing: https://github.com/spacedock-dev/spacedock/blob/main/CONTRIBUTING.md extra_css: - stylesheets/tokens.css From 9cc69836e5cce2f39de451463e777a90f5bf4477 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 15:46:12 -0700 Subject: [PATCH 052/115] =?UTF-8?q?docs=20site:=20no=20role=20names=20befo?= =?UTF-8?q?re=20their=20introduction=20=E2=80=94=20install=20and=20Welcome?= =?UTF-8?q?=20drop=20bare=20first-officer?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/site/get-started/install.md | 2 +- docs/site/index.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/site/get-started/install.md b/docs/site/get-started/install.md index 23a22155..3ed13f1b 100644 --- a/docs/site/get-started/install.md +++ b/docs/site/get-started/install.md @@ -26,7 +26,7 @@ Point Spacedock at a project you already have and let it survey: spacedock claude "/spacedock:survey" ``` -Starts the first officer in Claude Code and runs the survey. Spacedock manages +Starts a Spacedock session in Claude Code and runs the survey. Spacedock manages the agents your harness loads: the first launch sets them up in Claude Code, so no separate setup step is needed. To set them up ahead of time, or to refresh them later, run `spacedock install --host claude`. diff --git a/docs/site/index.md b/docs/site/index.md index c0366415..0f9fcc1c 100644 --- a/docs/site/index.md +++ b/docs/site/index.md @@ -22,4 +22,4 @@ You are the captain. You set the bar and make the calls; the agents do the rest. ## For agents using Spacedock -Spacedock's docs are read by agents too. A workflow's first officer parsing these docs is itself an agent. The build emits a curated `llms.txt` index at the site root for product-using agents. +Spacedock's docs are read by agents too. The build emits a curated `llms.txt` index at the site root for product-using agents. From ee684739328552b59c63d2cb34abe07f586a12db Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 15:47:40 -0700 Subject: [PATCH 053/115] docs site: install drops build-from-source and setup-alternatives; typical-user path only --- docs/site/get-started/install.md | 18 ++++++------------ 1 file changed, 6 insertions(+), 12 deletions(-) diff --git a/docs/site/get-started/install.md b/docs/site/get-started/install.md index 3ed13f1b..80f03464 100644 --- a/docs/site/get-started/install.md +++ b/docs/site/get-started/install.md @@ -26,18 +26,12 @@ Point Spacedock at a project you already have and let it survey: spacedock claude "/spacedock:survey" ``` -Starts a Spacedock session in Claude Code and runs the survey. Spacedock manages -the agents your harness loads: the first launch sets them up in Claude Code, so -no separate setup step is needed. To set them up ahead of time, or to refresh -them later, run `spacedock install --host claude`. - -With Codex or Pi (experimental), add the agents with -`spacedock install --host codex` (or `--host pi`), then launch with the -matching subcommand: `spacedock codex "your task"` or `spacedock pi "your task"`. - -Working on Spacedock itself? See [Build from source](https://github.com/spacedock-dev/spacedock/blob/main/docs/site/contributing/build-from-source.md). -It builds the binary from your checkout and loads the agents from it, so local -edits are live. +Starts a Spacedock session in Claude Code and runs the survey. The first launch +sets up everything Claude Code needs; there is no separate setup step. + +With Codex or Pi (experimental), run `spacedock install --host codex` (or +`--host pi`) once, then launch with the matching subcommand: +`spacedock codex "your task"` or `spacedock pi "your task"`. ## Sandboxing From 7711c96f722cc467cd2f12fc6452f9b84790bd9c Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 15:48:27 -0700 Subject: [PATCH 054/115] docs site: agents footer points at llms.txt itself, not the build that emits it --- docs/site/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/site/index.md b/docs/site/index.md index 0f9fcc1c..9743c0da 100644 --- a/docs/site/index.md +++ b/docs/site/index.md @@ -22,4 +22,4 @@ You are the captain. You set the bar and make the calls; the agents do the rest. ## For agents using Spacedock -Spacedock's docs are read by agents too. The build emits a curated `llms.txt` index at the site root for product-using agents. +Agents read these docs too. Start from [`llms.txt`](/llms.txt), the curated index of these pages. From b7114d0d67ea242576fdca6344da3115af4dff5f Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 15:50:03 -0700 Subject: [PATCH 055/115] =?UTF-8?q?docs=20site:=20install=20honest=20pass?= =?UTF-8?q?=20=E2=80=94=20plain=20words=20for=20the=20agent,=20survey=20pa?= =?UTF-8?q?yoff=20named,=20Next=20no=20longer=20re-asks=20for=20a=20launch?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/site/get-started/install.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/docs/site/get-started/install.md b/docs/site/get-started/install.md index 80f03464..86149367 100644 --- a/docs/site/get-started/install.md +++ b/docs/site/get-started/install.md @@ -1,7 +1,7 @@ # Install Spacedock -Spacedock plugs into a coding agent harness you already run: Claude Code, Codex, -or Pi. Install one of those first. +Spacedock works with a coding agent you already have: Claude Code, Codex, or +Pi. Install one of those first. === "macOS (Homebrew)" @@ -26,8 +26,9 @@ Point Spacedock at a project you already have and let it survey: spacedock claude "/spacedock:survey" ``` -Starts a Spacedock session in Claude Code and runs the survey. The first launch -sets up everything Claude Code needs; there is no separate setup step. +Claude Code opens with Spacedock loaded and surveys the project: what your +agents have been doing and the decisions waiting on you. The first launch sets +up everything Claude Code needs; there is no separate setup step. With Codex or Pi (experimental), run `spacedock install --host codex` (or `--host pi`) once, then launch with the matching subcommand: @@ -47,7 +48,5 @@ out of date. ## Next -Run your [first launch](first-launch.md). The -[command reference](../reference/command-reference.md#launch) -covers the full launch grammar: the task argument, what rides after `--`, and -the sandbox flags. +[Your first launch](first-launch.md) covers what survey reports and the offer +it ends with. From aab653bf39d7ca8f0e2d36a35bb11c6757d710e9 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 15:55:14 -0700 Subject: [PATCH 056/115] =?UTF-8?q?docs=20site:=20install=20per=20captain'?= =?UTF-8?q?s=20shape=20=E2=80=94=20launch=20directly=20option,=20Skills=20?= =?UTF-8?q?with=20manual=20plugin=20commands,=20sandbox=20detail=20to=20re?= =?UTF-8?q?ference/sandbox?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/site/get-started/install.md | 29 ++++++++++++++++++----------- docs/site/reference/sandbox.md | 11 +++++++++++ mkdocs.yml | 1 + 3 files changed, 30 insertions(+), 11 deletions(-) create mode 100644 docs/site/reference/sandbox.md diff --git a/docs/site/get-started/install.md b/docs/site/get-started/install.md index 86149367..5c6e9602 100644 --- a/docs/site/get-started/install.md +++ b/docs/site/get-started/install.md @@ -20,26 +20,33 @@ Pi. Install one of those first. ## Launch -Point Spacedock at a project you already have and let it survey: +In a project you already have: ```bash spacedock claude "/spacedock:survey" ``` -Claude Code opens with Spacedock loaded and surveys the project: what your -agents have been doing and the decisions waiting on you. The first launch sets -up everything Claude Code needs; there is no separate setup step. +Or launch directly: -With Codex or Pi (experimental), run `spacedock install --host codex` (or -`--host pi`) once, then launch with the matching subcommand: -`spacedock codex "your task"` or `spacedock pi "your task"`. +```bash +spacedock claude "what can spacedock do for me in this project" +``` + +Replace `claude` with `codex` or `pi` for the respective coding agents. + +## Skills + +Spacedock installs the relevant skills on launch, but you can also install +them manually: + +```bash +claude plugin marketplace add spacedock-dev/spacedock +claude plugin install spacedock@spacedock +``` ## Sandboxing -When a `.safehouse` profile is present in the working directory, the launch -runs sandboxed through the `safehouse` command; `--safehouse` forces it. -Spacedock ships no sandbox of its own: when no `safehouse` binary is on your -`PATH`, the launch prints an install hint and proceeds **unsandboxed**. +See [supported sandboxes](../reference/sandbox.md). ## Troubleshooting diff --git a/docs/site/reference/sandbox.md b/docs/site/reference/sandbox.md new file mode 100644 index 00000000..5fca1c3c --- /dev/null +++ b/docs/site/reference/sandbox.md @@ -0,0 +1,11 @@ +# Sandboxes + +Spacedock ships no sandbox of its own; it wraps the launch through a sandbox +command when one is configured. + +| Sandbox | Platforms | Trigger | +|---------|-----------|---------| +| `safehouse` | macOS, Linux | A `.safehouse` profile in the working directory, or the `--safehouse` flag | + +A run is sandboxed only when the sandbox binary is on your `PATH`. When it is +absent, the launch prints an install hint and proceeds **unsandboxed**. diff --git a/mkdocs.yml b/mkdocs.yml index c2ffd52f..1e251060 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -88,6 +88,7 @@ nav: - Reference: - Command reference: reference/command-reference.md - Frontmatter contract: reference/frontmatter-contract.md + - Sandboxes: reference/sandbox.md - Contributing: https://github.com/spacedock-dev/spacedock/blob/main/CONTRIBUTING.md extra_css: From d1279e0e3890ffdd0ceb1886e3df849ab01fb668 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 15:57:23 -0700 Subject: [PATCH 057/115] docs site: install Skills sentence positive form (comm-officer, partial) --- docs/site/get-started/install.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/site/get-started/install.md b/docs/site/get-started/install.md index 5c6e9602..f4ab4152 100644 --- a/docs/site/get-started/install.md +++ b/docs/site/get-started/install.md @@ -36,8 +36,7 @@ Replace `claude` with `codex` or `pi` for the respective coding agents. ## Skills -Spacedock installs the relevant skills on launch, but you can also install -them manually: +Spacedock installs the relevant skills on launch. To install them manually: ```bash claude plugin marketplace add spacedock-dev/spacedock From 6ee9b4345f554efb90f0554c2a7cbd74afcfbc07 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 15:58:02 -0700 Subject: [PATCH 058/115] =?UTF-8?q?docs=20site:=20sandbox=20reference=20?= =?UTF-8?q?=E2=80=94=20safehouse=20is=20macOS-only,=20link=20agent-safehou?= =?UTF-8?q?se.dev?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/site/reference/sandbox.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/site/reference/sandbox.md b/docs/site/reference/sandbox.md index 5fca1c3c..3b60d923 100644 --- a/docs/site/reference/sandbox.md +++ b/docs/site/reference/sandbox.md @@ -5,7 +5,7 @@ command when one is configured. | Sandbox | Platforms | Trigger | |---------|-----------|---------| -| `safehouse` | macOS, Linux | A `.safehouse` profile in the working directory, or the `--safehouse` flag | +| [`safehouse`](https://agent-safehouse.dev/) | macOS | A `.safehouse` profile in the working directory, or the `--safehouse` flag | A run is sandboxed only when the sandbox binary is on your `PATH`. When it is absent, the launch prints an install hint and proceeds **unsandboxed**. From a9a44b04c650400df13f02ab5f054e7adcdd9624 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 15:58:48 -0700 Subject: [PATCH 059/115] =?UTF-8?q?docs=20site:=20sandbox=20reference=20is?= =?UTF-8?q?=20just=20the=20table=20=E2=80=94=20Supported=20sandboxes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/site/reference/sandbox.md | 8 +------- mkdocs.yml | 2 +- 2 files changed, 2 insertions(+), 8 deletions(-) diff --git a/docs/site/reference/sandbox.md b/docs/site/reference/sandbox.md index 3b60d923..14e9429e 100644 --- a/docs/site/reference/sandbox.md +++ b/docs/site/reference/sandbox.md @@ -1,11 +1,5 @@ -# Sandboxes - -Spacedock ships no sandbox of its own; it wraps the launch through a sandbox -command when one is configured. +# Supported sandboxes | Sandbox | Platforms | Trigger | |---------|-----------|---------| | [`safehouse`](https://agent-safehouse.dev/) | macOS | A `.safehouse` profile in the working directory, or the `--safehouse` flag | - -A run is sandboxed only when the sandbox binary is on your `PATH`. When it is -absent, the launch prints an install hint and proceeds **unsandboxed**. diff --git a/mkdocs.yml b/mkdocs.yml index 1e251060..c993da96 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -88,7 +88,7 @@ nav: - Reference: - Command reference: reference/command-reference.md - Frontmatter contract: reference/frontmatter-contract.md - - Sandboxes: reference/sandbox.md + - Supported sandboxes: reference/sandbox.md - Contributing: https://github.com/spacedock-dev/spacedock/blob/main/CONTRIBUTING.md extra_css: From 12737fe45c40c70972c2afa9a9b9f33ef7c7fbc4 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 15:59:15 -0700 Subject: [PATCH 060/115] docs site: Troubleshooting is just the command --- docs/site/get-started/install.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/site/get-started/install.md b/docs/site/get-started/install.md index f4ab4152..a4970edd 100644 --- a/docs/site/get-started/install.md +++ b/docs/site/get-started/install.md @@ -49,8 +49,7 @@ See [supported sandboxes](../reference/sandbox.md). ## Troubleshooting -Run `spacedock doctor`. It checks the install and names anything missing or -out of date. +Run `spacedock doctor`. ## Next From c3451666157ad8e98141205bad9649cfe5da4647 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 16:01:20 -0700 Subject: [PATCH 061/115] docs site: codify the captain's editing lessons into the authoring directive --- docs/site/AGENTS.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/docs/site/AGENTS.md b/docs/site/AGENTS.md index bb1e8bd4..492a810e 100644 --- a/docs/site/AGENTS.md +++ b/docs/site/AGENTS.md @@ -11,8 +11,15 @@ Spacedock is not complicated; wordy docs make it *feel* complicated. Every edit - ✓ "You have work that needs doing in stages, with a human sign-off before anything ships. Spacedock runs that for you." - **Introduce the fewest terms possible, as late as possible.** Don't front-load a glossary. Define a term on first real use, gloss it once, then just use it. If a page introduces more than a handful of new terms, cut or defer some. - **Lead with what the user sees and must know; keep the how-it-works light.** Name the visible behavior and the required concepts first. Internal mechanics (scheduling and reuse conditions, file/branch naming templates, parser internals, query plumbing) get at most a sentence or a link to the source. If a paragraph reads as protocol documentation, compress it or cut it. +- **Product anatomy is not a reader concept.** Do not name internal components (launcher, plugin, host) unless the reader must type or choose between them. The reader installs Spacedock and launches Spacedock; how it decomposes is not their problem. +- **Write from the reader's seat, never the maintainer's.** If a sentence's subject is the build, the script, or the parser, recast it around what the reader gets or does. + - ✗ "The build emits a curated `llms.txt` index at the site root." + - ✓ "Start from `llms.txt`, the curated index of these pages." +- **A well-named command needs no caption.** "Run `spacedock doctor`." is complete; explaining that it diagnoses problems repeats the name. Likewise, never pre-document what a tool prints interactively (the install script already prints its own `PATH` note). +- **A heading is a promise; the section delivers exactly that.** Codex setup is not "Install Spacedock"; a tab the reader chose ("no Homebrew") must not explain the thing they opted out of. +- **Serve the typical reader; route edge audiences elsewhere.** A Get-started page carries only the path a typical user walks. Contributor and from-source material lives in the repo, not inline, not even as one sentence. - **Cut, don't pad.** If a sentence still carries its meaning with a clause removed, remove the clause. If a paragraph repeats the page above it, delete it and link instead. -- **Don't repeat content across pages.** One page owns each idea; others link to it. Duplicated explanation is the main thing that makes the docs feel long. +- **Don't repeat content across pages.** One page owns each idea; others link to it. Duplicated explanation is the main thing that makes the docs feel long. An audience split ("new-user view" vs "operator view" of the same feature) is not a reason for a second page; it is the same topic. - **Two levels of structure only:** section → page. No deeper nesting; no page that exists only to hold sub-pages. ## First impression: "simple," not "enterprise" @@ -40,7 +47,7 @@ Opening (1–2 sentences: what + why) → how it works (2–4 short paragraphs, State the goal in one sentence. List prerequisites up front (never bury them mid-page). Numbered steps, **one action per step**, each showing the expected result (name the command *and* the output, e.g. ``spacedock status --next`` then what it prints). End with verification and "next steps" links. Push command-grammar and theory to the bottom or to a linked concept; the reader wants the outcome first. ### Reference pages -Optimize for lookup in seconds. Use **tables** for flags, fields, and options (Name · Type/required · Description · Default). Give copy-paste examples. Mark required vs optional; show defaults; note edge cases. If a "reference" page is really an explanation, it belongs in Concepts; if it's really a procedure, it belongs in a how-to. +Optimize for lookup in seconds. Use **tables** for flags, fields, and options (Name · Type/required · Description · Default). Give copy-paste examples. Mark required vs optional; show defaults; note edge cases. When the title and a table carry everything, ship the title and the table: no framing intro, no closing caveat. If a "reference" page is really an explanation, it belongs in Concepts; if it's really a procedure, it belongs in a how-to. ## Link instead of repeat - Cross-link liberally with **relative** internal links (so `mkdocs build --strict` resolves them). Concept → tutorial + reference; tutorial → concept + reference; reference → concept. @@ -98,14 +105,15 @@ Rule of thumb: capitalize a **role** when you name it as a role (the roles table ## Formatting conventions - **Commands and code.** Inline code font for commands, flags, filenames, and identifiers: `spacedock claude`, `--strict`, `mkdocs.yml`. Multi-line commands and config in fenced code blocks with a language tag (` ```bash `, ` ```yaml `). -- **Show expected output.** For a command a reader runs, name the result, as `install.md` does ("Prints the installed version, e.g. `spacedock 0.20.0`"). +- **Show expected output when the reader must check it.** Name what a command prints when the reader acts on the result (e.g. `spacedock status --next` prints the dispatchable set). A well-named command needs neither caption nor sample output. - **Headings.** Sentence case ("Get started", "Your first workflow"), not Title Case. One `#` h1 per page (the page title); section headings start at `##`. -- **Links.** Descriptive link text, never "click here" / "this link". Internal links are relative so `mkdocs build --strict` can resolve them. +- **Links.** Descriptive link text, never "click here" / "this link". Internal links are relative so `mkdocs build --strict` can resolve them. GitHub links and install commands point at `main`, never a development branch. - **Lists and emphasis.** Bullets for parallel items; bold for the load-bearing claim of a bullet (the README pattern). Use emphasis sparingly; if everything is bold, nothing is. ## Before you commit a docs change - [ ] Page opens with the problem/payoff, not a definition. - [ ] Introduces only the terms this page actually needs; each defined on first use. +- [ ] Re-read every touched page in reader-journey order: no term appears before the page that introduces it, including terms your own rewrite brought back. - [ ] Matches its type's shape (concept / how-to / reference): no steps in concepts, no essays in reference. - [ ] No content duplicated from another page; shared ideas are linked, not repeated. - [ ] Internal links are relative and descriptive; first mentions of key terms link out. From 0b154c71073763482929e061f823815795130980 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 16:04:15 -0700 Subject: [PATCH 062/115] =?UTF-8?q?docs=20site:=20Get=20started=20redone?= =?UTF-8?q?=20per=20the=20codified=20directive=20=E2=80=94=20reader-seat,?= =?UTF-8?q?=20no=20role=20anatomy,=20typical=20path?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/site/get-started/first-launch.md | 88 ++++++++++++++++--------- docs/site/get-started/first-workflow.md | 27 ++++---- 2 files changed, 69 insertions(+), 46 deletions(-) diff --git a/docs/site/get-started/first-launch.md b/docs/site/get-started/first-launch.md index af4ad57c..9d3326d9 100644 --- a/docs/site/get-started/first-launch.md +++ b/docs/site/get-started/first-launch.md @@ -1,50 +1,73 @@ # Your first launch -One command starts your first session and orients you in a project you already have: +One command orients you in a project you already have: ```bash spacedock claude "/spacedock:survey" ``` -This launches the [first officer](../concepts/operating-model.md#three-roles) (the orchestrator agent that runs a Spacedock workflow) inside Claude Code and hands it the survey task. The first launch also sets up the agents Claude Code loads; no separate setup step is needed. - -Run it from inside a project that already has some agent history, such as a repo you have been coding in with Claude Code. Survey reads that history; an empty directory has nothing to report. +Claude Code opens with Spacedock loaded and surveys the project: what your +agents have been doing, and the decisions still waiting on you. ## What survey reads -Survey reads your recorded agent sessions, read-only, scoped to this repo and every checkout of it (the root, a subdir, a worktree) and nothing else on disk. It reads them through `agentsview`, a session-history tool; if that tool is missing, survey asks before installing it, and never installs without an explicit yes. If the sync fails, it reports the exact failure and stops rather than guessing. If the repo has no agent history, survey says so plainly and stops. +Survey reads your recorded agent sessions, read-only, scoped to this repo and +every checkout of it, and nothing else on disk. It reads them through +`agentsview`, a session-history tool; if the tool is missing, survey asks +before installing it. If the repo has no agent history, survey says so and +stops. ## What it reports -Survey leads with a one-line headline (the project, the session count, the date range, and the decision and interruption counts), then renders the body in the same turn. The body is the value, so the sections follow without a confirmation pause: - -- **Inferred workflow.** The implicit loop reconstructed from the decisions and prompts, as an arrow chain, with one honest line about it. -- **Workstreams.** The decisions and prompts clustered into tracks, each tagged with its work mode (see below). -- **Work by area.** Where edits actually landed, by logical area (`src`, `internal`, `docs`, …) regardless of physical location. A worktree edit counts toward its area, so worktree-based work is not hidden. Genuine config paths (`.claude`, `.beads`, `.git`) and external sibling references demote to a footnote. -- **Needs you.** The open decisions, the forks raised but never resolved. **Survey leads the report with these**, because they are the work blocked on you. Exploration threads you are deliberately holding are separated from mechanical questions awaiting an answer. -- **Recent decisions** and **interruptions**: the answered or shipped forks, and how often you had to step in. -- **Scaffold.** If another agent scaffold is in use (superpowers, gsd / get-shit-done, or another `.claude` skill tree), survey states it as a fact: the family, its invocation count, and whether it is checked in on disk. -- **Codex** (only when present). Codex sessions get their own section: a session count, the workstream clusters, and an activity tally. - -If a section's signal is empty, survey says the run found none of it. It never dresses an empty section up as "no decisions". - -Open decisions are cross-checked against the repo before they reach you: forks that already shipped are dropped, decided-but-unshipped ones move to a backlog line, and only the never-decided stay on the `NEEDS YOU` frontier. When there is no repo signal to check against, every open fork is flagged `unverified` instead of presented as authoritative. +A one-line headline (project, sessions, date range, decision and interruption +counts), then: + +- **Needs you.** The open decisions: forks raised but never resolved. These + lead the report because they are the work blocked on you. Threads you are + deliberately holding are separated from questions awaiting an answer. +- **Inferred workflow.** The loop you have been running without naming it, as + an arrow chain, with one honest line about it. +- **Workstreams.** Your decisions and prompts clustered into tracks. +- **Work by area.** Where edits actually landed (`src`, `docs`, …); + config-only paths drop to a footnote. +- **Recent decisions** and **interruptions**: the answered forks, and how + often you had to step in. +- **Scaffold.** Another agent scaffold in use (superpowers, gsd, another + `.claude` skill tree) is stated as a fact. +- **Codex** (when present). Codex sessions get their own section. + +An empty section says so plainly. + +Open decisions are cross-checked against the repo before they reach you: forks +that already shipped are dropped, decided-but-unshipped ones move to a backlog +line, and only the never-decided stay on the frontier. With no repo signal to +check against, open forks are flagged `unverified`. ## The commission offer -Survey ends with an offer, not an action. It asks whether you want it to [commission](../running-workflows/commission.md) a real Spacedock [workflow](../concepts/workflows-and-entities.md) built from what it found, turning the open decisions into [approval gates](../concepts/gates-and-decisions.md) and the workstreams into work items. Nothing has changed in your project until you say yes. - -The offer is keyed to each track's work mode, so each track gets a distinct pitch. Survey classifies each track as **mechanical**, **exploration**, or **unlabeled**: +Survey ends with an offer, not an action. It asks whether you want it to +[commission](../running-workflows/commission.md) a real Spacedock +[workflow](../concepts/workflows-and-entities.md) built from what it found, +turning the open decisions into +[approval gates](../concepts/gates-and-decisions.md) and the workstreams into +work items. Nothing has changed in your project until you say yes. -- **Mechanical tracks** (the routine issue → worktree → PR loop) get an **automation** offer: a workflow that gates the crucial decisions and lets the agent drive the loop between gates. -- **Exploration tracks** (creative, content, or design work where your steering is the point) get a **book-keeping** offer: structure for the parallel threads, tracking each draft or path and its state (in-flight / paused-by-choice / abandoned). There is no automate-the-human-out pitch here. The involvement is the work. -- **Unlabeled tracks** get the generic book-keeping offer, never a guessed automation pitch. +The offer matches the work it saw, citing real numbers from the scan: -A project with both modes gets both offers. Each offer cites a real number from the scan: the track names, the gate-pass count, the open forks, the cancelled-path count. +- **Routine loops** (issue → worktree → PR) get an automation offer: a + workflow that gates the crucial decisions and lets the agent drive between + gates. +- **Exploration** (creative or design work where your steering is the point) + gets a book-keeping offer: structure for the parallel threads and their + state. There is no automate-the-human-out pitch; the involvement is the work. -On a **yes**, survey hands what it found to commission: the inferred loop becomes the proposed stages, the workstreams become the seed work items, and the open forks become the gates. File generation stays commission's job. On a **no**, it stops; the survey stands on its own as orientation. +On a **yes**, survey hands what it found to commission: the inferred loop +becomes the proposed stages, the workstreams become the seed work items, and +the open forks become the gates. On a **no**, it stops; the survey stands on +its own as orientation. -To define a workflow yourself instead, see [your first workflow](first-workflow.md). If `spacedock` is not yet installed, start with [installing Spacedock](install.md). +To define a workflow yourself instead, see +[your first workflow](first-workflow.md). ## The command grammar @@ -54,8 +77,11 @@ Every launch uses the same shape: spacedock claude "task" [--safehouse…] [-- host-flags…] ``` -- **The task comes first.** It is handed to the first officer as the launch prompt. Here the task is `/spacedock:survey`, a skill the first officer runs. It could just as well be a plain sentence describing work. -- **`--safehouse` forces the launch through the sandbox.** A `.safehouse` profile in the working directory does the same automatically, so you only pass the flag when you want to force it. -- **Anything after `--` forwards verbatim to the host** (`claude` itself), including flags like `--resume`, `--model`, and `--plugin-dir`. +- **The task comes first** and becomes the launch prompt. `/spacedock:survey` + is a skill; a plain sentence describing work works just as well. +- **`--safehouse` forces the [sandbox](../reference/sandbox.md).** A + `.safehouse` profile in the working directory does it automatically. +- **Anything after `--` goes to Claude Code itself**, including flags like + `--resume` and `--model`. -`spacedock codex "task"` and `spacedock pi "task"` take the same shape for the Codex and Pi harnesses. Claude Code is the primary surface; the examples here use it. +`spacedock codex` and `spacedock pi` take the same shape. diff --git a/docs/site/get-started/first-workflow.md b/docs/site/get-started/first-workflow.md index f3071c63..e9bb4756 100644 --- a/docs/site/get-started/first-workflow.md +++ b/docs/site/get-started/first-workflow.md @@ -6,10 +6,9 @@ scratch to the `/spacedock:commission` skill. Either way you land here. A workflow is a directory of plain-text work items plus a README that defines the stages they move through and the gates where you make a call. -Spacedock addresses you as the **captain**: the workflow operator who decides at -gates. The [operating model](../concepts/operating-model.md#three-roles) covers -the other two roles, the first officer (the orchestrator agent that runs the -workflow) and the ensign (the worker that moves one item through one stage). +Spacedock addresses you as the **captain**: you decide at gates, and the agents +do the rest. The [operating model](../concepts/operating-model.md#three-roles) +covers the agent roles. ## Commission a workflow @@ -20,10 +19,8 @@ the same line: spacedock claude "/spacedock:commission Track design ideas through review stages" ``` -If you have not yet launched a session, see -[Install Spacedock](install.md) first. You can also start bare -(`/spacedock:commission` with no description) and answer the questions from -scratch. +You can also start bare (`/spacedock:commission` with no description) and +answer the questions from scratch. The skill greets you and walks three phases: **design** (a few questions), **generate** (it writes the files), and a **pilot run** (it starts the workflow @@ -60,7 +57,7 @@ recorded decision.** A development workflow gates the design stage and the review stage among others, so you sign off on the approach before code is written, and on the result before it ships. -At each gate the first officer pauses and presents a stage report: the chosen +At each gate Spacedock pauses and presents a stage report: the chosen direction, the evidence behind it, and a single recommendation. You make one of three calls: @@ -75,9 +72,9 @@ call that produced it. ## What happens after -When you accept the design, the commission skill launches a pilot run on your -seed entities: it takes the first-officer role itself, reads the README, and -dispatches ensigns to move ready entities through their stages until the workflow -goes idle or reaches a gate. From there you are running the workflow: approving, -sending back, and resuming in later sessions. [Operating a workflow](../running-workflows/operating.md) -covers the day-to-day loop and how to resume. +When you accept the design, commission launches a pilot run on your seed +entities: it reads the README it just wrote and moves the ready entities +through their stages until the workflow goes idle or reaches a gate. From there +you are running the workflow: approving, sending back, and resuming in later +sessions. [Operating a workflow](../running-workflows/operating.md) covers the +day-to-day loop. From 051a9b01271258ae094cd1861e95a3e574d1e4d3 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 16:09:40 -0700 Subject: [PATCH 063/115] =?UTF-8?q?docs=20site:=20Your=20first=20launch=20?= =?UTF-8?q?becomes=20Survey=20your=20project=20=E2=80=94=20launch=20lives?= =?UTF-8?q?=20in=20install,=20grammar=20in=20command=20reference?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/site/get-started/first-workflow.md | 2 +- docs/site/get-started/install.md | 4 +- .../{first-launch.md => survey.md} | 42 +++++-------------- docs/site/index.md | 2 +- mkdocs.yml | 2 +- 5 files changed, 15 insertions(+), 37 deletions(-) rename docs/site/get-started/{first-launch.md => survey.md} (66%) diff --git a/docs/site/get-started/first-workflow.md b/docs/site/get-started/first-workflow.md index e9bb4756..e34a5a83 100644 --- a/docs/site/get-started/first-workflow.md +++ b/docs/site/get-started/first-workflow.md @@ -1,6 +1,6 @@ # Your first workflow -Your first workflow comes from one of two places: [survey](first-launch.md) +Your first workflow comes from one of two places: [survey](survey.md) offers to build one from what it found in your project, or you describe one from scratch to the `/spacedock:commission` skill. Either way you land here. A workflow is a directory of plain-text work items plus a README that defines the diff --git a/docs/site/get-started/install.md b/docs/site/get-started/install.md index a4970edd..16212d4e 100644 --- a/docs/site/get-started/install.md +++ b/docs/site/get-started/install.md @@ -53,5 +53,5 @@ Run `spacedock doctor`. ## Next -[Your first launch](first-launch.md) covers what survey reports and the offer -it ends with. +[Survey your project](survey.md) covers what survey reports and the offer it +ends with. diff --git a/docs/site/get-started/first-launch.md b/docs/site/get-started/survey.md similarity index 66% rename from docs/site/get-started/first-launch.md rename to docs/site/get-started/survey.md index 9d3326d9..c28b9661 100644 --- a/docs/site/get-started/first-launch.md +++ b/docs/site/get-started/survey.md @@ -1,21 +1,16 @@ -# Your first launch +# Survey your project -One command orients you in a project you already have: - -```bash -spacedock claude "/spacedock:survey" -``` - -Claude Code opens with Spacedock loaded and surveys the project: what your -agents have been doing, and the decisions still waiting on you. +Survey orients you in a project your agents have already been working in: what +they have been doing, and the decisions still waiting on you. +[Install](install.md) covers launching it. ## What survey reads -Survey reads your recorded agent sessions, read-only, scoped to this repo and -every checkout of it, and nothing else on disk. It reads them through -`agentsview`, a session-history tool; if the tool is missing, survey asks -before installing it. If the repo has no agent history, survey says so and -stops. +Survey reads your recorded agent sessions and nothing else on disk. It is +read-only and scoped to this repo and every checkout of it. It reads the +sessions through `agentsview`, a session-history tool; if the tool is missing, +survey asks before installing it. If the repo has no agent history, survey +says so and stops. ## What it reports @@ -61,27 +56,10 @@ The offer matches the work it saw, citing real numbers from the scan: gets a book-keeping offer: structure for the parallel threads and their state. There is no automate-the-human-out pitch; the involvement is the work. -On a **yes**, survey hands what it found to commission: the inferred loop +On a **yes**, the workflow is built from what survey found: the inferred loop becomes the proposed stages, the workstreams become the seed work items, and the open forks become the gates. On a **no**, it stops; the survey stands on its own as orientation. To define a workflow yourself instead, see [your first workflow](first-workflow.md). - -## The command grammar - -Every launch uses the same shape: - -```bash -spacedock claude "task" [--safehouse…] [-- host-flags…] -``` - -- **The task comes first** and becomes the launch prompt. `/spacedock:survey` - is a skill; a plain sentence describing work works just as well. -- **`--safehouse` forces the [sandbox](../reference/sandbox.md).** A - `.safehouse` profile in the working directory does it automatically. -- **Anything after `--` goes to Claude Code itself**, including flags like - `--resume` and `--model`. - -`spacedock codex` and `spacedock pi` take the same shape. diff --git a/docs/site/index.md b/docs/site/index.md index 9743c0da..80b2fb13 100644 --- a/docs/site/index.md +++ b/docs/site/index.md @@ -16,7 +16,7 @@ You are the captain. You set the bar and make the calls; the agents do the rest. ## Where to go next -- **[Get started](get-started/install.md)**: [install](get-started/install.md) Spacedock, then pick an entry. [Survey an existing project](get-started/first-launch.md) to see where your agents burn your time and surface the workflow you are already running without naming it. Or [start a fresh workflow](get-started/first-workflow.md) from a common shape like development or research. +- **[Get started](get-started/install.md)**: [install](get-started/install.md) Spacedock, then pick an entry. [Survey an existing project](get-started/survey.md) to see where your agents burn your time and surface the workflow you are already running without naming it. Or [start a fresh workflow](get-started/first-workflow.md) from a common shape like development or research. - **[Concepts](concepts/operating-model.md)** covers the operating model, workflows and entities, the stage lifecycle, gates and decisions, and a worked example. - **[Running workflows](running-workflows/commission.md)** walks through commissioning a workflow, operating a running workflow, and debriefing and refitting between sessions. diff --git a/mkdocs.yml b/mkdocs.yml index c993da96..fcf02834 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -70,7 +70,7 @@ nav: - Get started: - Welcome: index.md - Install: get-started/install.md - - Your first launch: get-started/first-launch.md + - Survey your project: get-started/survey.md - Your first workflow: get-started/first-workflow.md - Concepts: - The operating model: concepts/operating-model.md From 9c8d1f7b08d40e3353bec828d179faf1896fd853 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 16:13:25 -0700 Subject: [PATCH 064/115] =?UTF-8?q?docs=20site:=20install=20Next=20offers?= =?UTF-8?q?=20both=20entries=20=E2=80=94=20survey=20report=20or=20first=20?= =?UTF-8?q?workflow?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/site/get-started/install.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/site/get-started/install.md b/docs/site/get-started/install.md index 16212d4e..e1257241 100644 --- a/docs/site/get-started/install.md +++ b/docs/site/get-started/install.md @@ -53,5 +53,5 @@ Run `spacedock doctor`. ## Next -[Survey your project](survey.md) covers what survey reports and the offer it -ends with. +Read about the [survey report](survey.md) to understand your usage pattern +with coding agents, or start with [your first workflow](first-workflow.md). From 60396b5e2257de52b3f1ad02dc1fc1e3341fd54b Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 16:17:35 -0700 Subject: [PATCH 065/115] docs site: survey opens with the skill and agentsview; report is the four things the user gets --- docs/site/get-started/survey.md | 45 ++++++++------------------------- 1 file changed, 11 insertions(+), 34 deletions(-) diff --git a/docs/site/get-started/survey.md b/docs/site/get-started/survey.md index c28b9661..3cd98983 100644 --- a/docs/site/get-started/survey.md +++ b/docs/site/get-started/survey.md @@ -1,42 +1,19 @@ # Survey your project -Survey orients you in a project your agents have already been working in: what -they have been doing, and the decisions still waiting on you. -[Install](install.md) covers launching it. - -## What survey reads - -Survey reads your recorded agent sessions and nothing else on disk. It is -read-only and scoped to this repo and every checkout of it. It reads the -sessions through `agentsview`, a session-history tool; if the tool is missing, -survey asks before installing it. If the repo has no agent history, survey -says so and stops. +When you use the `spacedock:survey` skill, it looks at your existing agent +conversation logs on local disk (through [agentsview](https://agentsview.io/), +an open source session-history tool). It is read-only; if `agentsview` is +missing, it asks before installing it. ## What it reports -A one-line headline (project, sessions, date range, decision and interruption -counts), then: - -- **Needs you.** The open decisions: forks raised but never resolved. These - lead the report because they are the work blocked on you. Threads you are - deliberately holding are separated from questions awaiting an answer. -- **Inferred workflow.** The loop you have been running without naming it, as - an arrow chain, with one honest line about it. -- **Workstreams.** Your decisions and prompts clustered into tracks. -- **Work by area.** Where edits actually landed (`src`, `docs`, …); - config-only paths drop to a footnote. -- **Recent decisions** and **interruptions**: the answered forks, and how - often you had to step in. -- **Scaffold.** Another agent scaffold in use (superpowers, gsd, another - `.claude` skill tree) is stated as a fact. -- **Codex** (when present). Codex sessions get their own section. - -An empty section says so plainly. - -Open decisions are cross-checked against the repo before they reach you: forks -that already shipped are dropped, decided-but-unshipped ones move to a backlog -line, and only the never-decided stay on the frontier. With no repo signal to -check against, open forks are flagged `unverified`. +- **The repeated manual behavior**: the loop you have been driving by hand, + run after run, without naming it. +- **The steering and interruptions observed**: how often your agents needed + you to step in, and for what. +- **Your current workstreams**: what is in flight, clustered into tracks. +- **What is still undecided**: forks raised but never resolved, cross-checked + against the repo first so work that already shipped is dropped. ## The commission offer From 852536b822879988283717d22025feda48cfbd62 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 16:18:56 -0700 Subject: [PATCH 066/115] docs site: survey offer section named from the reader's seat; drop cross-check internals --- docs/site/get-started/survey.md | 33 +++++++++++++-------------------- 1 file changed, 13 insertions(+), 20 deletions(-) diff --git a/docs/site/get-started/survey.md b/docs/site/get-started/survey.md index 3cd98983..c428640e 100644 --- a/docs/site/get-started/survey.md +++ b/docs/site/get-started/survey.md @@ -12,31 +12,24 @@ missing, it asks before installing it. - **The steering and interruptions observed**: how often your agents needed you to step in, and for what. - **Your current workstreams**: what is in flight, clustered into tracks. -- **What is still undecided**: forks raised but never resolved, cross-checked - against the repo first so work that already shipped is dropped. +- **What is still undecided**: forks raised but never resolved. -## The commission offer +## Turn the report into a workflow -Survey ends with an offer, not an action. It asks whether you want it to -[commission](../running-workflows/commission.md) a real Spacedock -[workflow](../concepts/workflows-and-entities.md) built from what it found, -turning the open decisions into -[approval gates](../concepts/gates-and-decisions.md) and the workstreams into -work items. Nothing has changed in your project until you say yes. +Survey ends with an offer, not an action. It can turn what it found into a +Spacedock [workflow](../concepts/workflows-and-entities.md): the repeated loop +becomes the stages, the workstreams become the work items, and the undecided +forks become [approval gates](../concepts/gates-and-decisions.md). Nothing +changes in your project until you say yes; on a no, the survey stands on its +own as orientation. -The offer matches the work it saw, citing real numbers from the scan: +The offer matches your work: -- **Routine loops** (issue → worktree → PR) get an automation offer: a - workflow that gates the crucial decisions and lets the agent drive between - gates. +- **Routine loops** (issue → worktree → PR) get automation: a workflow that + gates the crucial decisions and lets the agent drive between gates. - **Exploration** (creative or design work where your steering is the point) - gets a book-keeping offer: structure for the parallel threads and their - state. There is no automate-the-human-out pitch; the involvement is the work. - -On a **yes**, the workflow is built from what survey found: the inferred loop -becomes the proposed stages, the workstreams become the seed work items, and -the open forks become the gates. On a **no**, it stops; the survey stands on -its own as orientation. + gets book-keeping: structure for the parallel threads and their state. There + is no automate-the-human-out pitch; the involvement is the work. To define a workflow yourself instead, see [your first workflow](first-workflow.md). From 734a96563b2c9608318b0aa303f5b39094de48a8 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 16:28:28 -0700 Subject: [PATCH 067/115] docs site: first-workflow led by a real dev-workflow commission example with sample design and status output --- docs/site/get-started/first-workflow.md | 121 ++++++++++++------------ 1 file changed, 60 insertions(+), 61 deletions(-) diff --git a/docs/site/get-started/first-workflow.md b/docs/site/get-started/first-workflow.md index e34a5a83..f673c57a 100644 --- a/docs/site/get-started/first-workflow.md +++ b/docs/site/get-started/first-workflow.md @@ -1,80 +1,79 @@ # Your first workflow -Your first workflow comes from one of two places: [survey](survey.md) -offers to build one from what it found in your project, or you describe one from -scratch to the `/spacedock:commission` skill. Either way you land here. A -workflow is a directory of plain-text work items plus a README that defines the -stages they move through and the gates where you make a call. - -Spacedock addresses you as the **captain**: you decide at gates, and the agents -do the rest. The [operating model](../concepts/operating-model.md#three-roles) -covers the agent roles. +Your first workflow comes from one of two places: [survey](survey.md) offers +to build one from what it found in your project, or you describe one yourself +to the `/spacedock:commission` skill. A workflow is your work moving through +stages you define, pausing at the gates where you decide. ## Commission a workflow -Run `/spacedock:commission` inside a Spacedock session and describe the work in -the same line: +Describe the work in the launch line: ```bash -spacedock claude "/spacedock:commission Track design ideas through review stages" +spacedock claude "/spacedock:commission ship features through design, implementation, and review" ``` -You can also start bare (`/spacedock:commission` with no description) and -answer the questions from scratch. - -The skill greets you and walks three phases: **design** (a few questions), -**generate** (it writes the files), and a **pilot run** (it starts the workflow -on your seed items). In the design phase it asks, one question at a time: what -the workflow is for and what each **entity** is, the work item the workflow -processes as one markdown file (a "design idea" becomes an `idea`); the stages -an entity moves through; which of those stages are gated and where a rejected -entity bounces back to; and the quality bar for each stage. Last come the -entity-ID style and two or three seed items to start on. You confirm or adjust -each proposal. The -[commission reference](../running-workflows/commission.md#the-four-things-you-name) -covers every decision in full. - -You do not have to get every answer right. After the questions, the skill -presents the full design as a summary (stages, gates, seed items, where the -files will live) and waits. **Nothing is generated until you accept.** Tell it -what to change and it re-presents. +Commission asks a few questions, one at a time: what each work item is, the +stages it moves through, which stages pause for your decision, and the quality +bar for each. You confirm or adjust each proposal, and it presents the design: + +> I'll call you Captain — let me know if you prefer something else. +> +> For each run, we process tasks going through the following stages: +> +> a. backlog — new tasks wait here for triage +> b. design — the approach is worked out and written down +> c. implementation — the change is built on an isolated branch +> d. review — the result is checked against the design +> e. done — accepted and closed +> +> If you reject at review, it goes back to implementation for revision. +> +> Our pilot run will be with: +> +> - Add rate limiting to the API +> - Fix the flaky login test +> +> Entity identity will use `sequential`. +> +> All files will be created in `docs/ship-features/` for you to review. +> +> Accept this design, or tell me what to change. + +**Nothing is generated until you accept.** Tell it what to change and it +re-presents. ## What gets generated -Once you accept, the skill writes the workflow into a new directory under `docs/`: -a `README.md` that is the workflow's living spec (mission, schema, and a section -per stage with its `Good:` / `Bad:` bar) and one file per seed entity. The -per-stage prose is a best-guess starting point. Tighten it before any work runs, -because an agent dispatched against a vague bar is expensive to correct. See -[what gets generated](../running-workflows/commission.md#what-gets-generated) for -the full file layout and the `review stages` walk. - -## The design and review gates +Everything is plain text in your repo: a README that holds the workflow's +rules (what each stage expects) and one file per work item. The generated +rules are a starting point; tighten them before any work runs, because an +agent working to a vague bar is expensive to correct. -Spacedock draws a clear line: work flows through stages on its own, -but a **gate** pauses it for your call, and **nothing crosses a gate without a -recorded decision.** A development workflow -gates the design stage and the review stage among others, so you sign off on -the approach before code is written, and on the result before it ships. +## The pilot run -At each gate Spacedock pauses and presents a stage report: the chosen -direction, the evidence behind it, and a single recommendation. You make one of -three calls: +On accept, commission starts moving your seed items through the stages until +everything is idle or waiting on you. Check where things stand at any time: -- **Approve**, and the entity advances to the next stage. -- **Redo with feedback**: it goes back for revision against your notes. -- **Reject**, and it bounces to an earlier stage (the one the design named as the - rejection target) to be reworked. +```bash +spacedock status --workflow-dir docs/ship-features +``` -You decide on the report and its evidence, not on the agent's transcript. The -decision is recorded with its reason, so a result can later be traced back to the -call that produced it. +``` +ID SLUG CURRENT NEXT WORKTREE +-- ---- ------- ---- -------- +001 add-rate-limiting-to-the-api review done yes +002 fix-the-flaky-login-test implementation review yes +``` -## What happens after +When a work item reaches a gate (here, `review`), Spacedock pauses and +presents a stage report: the chosen direction, the evidence behind it, and a +single recommendation. You approve, send it back with feedback, or reject. +[Gates and decisions](../concepts/gates-and-decisions.md) covers the full +machinery. -When you accept the design, commission launches a pilot run on your seed -entities: it reads the README it just wrote and moves the ready entities -through their stages until the workflow goes idle or reaches a gate. From there -you are running the workflow: approving, sending back, and resuming in later -sessions. [Operating a workflow](../running-workflows/operating.md) covers the +From there you are running the workflow: approving, sending back, and resuming +in later sessions. [Commission a workflow](../running-workflows/commission.md) +covers every design decision in full; +[Operating a workflow](../running-workflows/operating.md) covers the day-to-day loop. From 9b5ff9642c17f8b668ed427ec2c253a4096e2ff5 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 16:37:27 -0700 Subject: [PATCH 068/115] docs site: first-workflow sample without em-dashes, sd-b32, gate review in pilot run, agent-session framing --- docs/site/get-started/first-workflow.md | 64 ++++++++++++++----------- 1 file changed, 36 insertions(+), 28 deletions(-) diff --git a/docs/site/get-started/first-workflow.md b/docs/site/get-started/first-workflow.md index f673c57a..5a509c16 100644 --- a/docs/site/get-started/first-workflow.md +++ b/docs/site/get-started/first-workflow.md @@ -17,15 +17,24 @@ Commission asks a few questions, one at a time: what each work item is, the stages it moves through, which stages pause for your decision, and the quality bar for each. You confirm or adjust each proposal, and it presents the design: -> I'll call you Captain — let me know if you prefer something else. +> I'll call you Captain; let me know if you prefer something else. > > For each run, we process tasks going through the following stages: > -> a. backlog — new tasks wait here for triage -> b. design — the approach is worked out and written down -> c. implementation — the change is built on an isolated branch -> d. review — the result is checked against the design -> e. done — accepted and closed +> a. backlog +> new tasks wait here for triage +> +> b. design +> the approach is worked out and written down +> +> c. implementation +> the change is built on an isolated branch +> +> d. review +> the result is checked against the design +> +> e. done +> accepted and closed > > If you reject at review, it goes back to implementation for revision. > @@ -34,15 +43,12 @@ bar for each. You confirm or adjust each proposal, and it presents the design: > - Add rate limiting to the API > - Fix the flaky login test > -> Entity identity will use `sequential`. +> Entity identity will use `sd-b32`. > > All files will be created in `docs/ship-features/` for you to review. > > Accept this design, or tell me what to change. -**Nothing is generated until you accept.** Tell it what to change and it -re-presents. - ## What gets generated Everything is plain text in your repo: a README that holds the workflow's @@ -52,28 +58,30 @@ agent working to a vague bar is expensive to correct. ## The pilot run -On accept, commission starts moving your seed items through the stages until -everything is idle or waiting on you. Check where things stand at any time: +On accept, commission dispatches your seed items in parallel, each moving +through the stages until everything is idle or waiting on you. When a work +item reaches the `review` gate, you get a gate review: -```bash -spacedock status --workflow-dir docs/ship-features ``` +Gate review: Add rate limiting to the API — review +Chosen direction: token-bucket limiter at the API middleware layer +Recommend approve. -``` -ID SLUG CURRENT NEXT WORKTREE --- ---- ------- ---- -------- -001 add-rate-limiting-to-the-api review done yes -002 fix-the-flaky-login-test implementation review yes +Checklist (from ## Stage Report in docs/ship-features/add-rate-limiting-to-the-api.md): +- DONE: limiter implemented with per-client buckets +- DONE: tests cover burst and refill behavior + +Assessment: 2 done, 0 skipped, 0 failed. + +Decision: approve to close; reject to bounce back to implementation. ``` -When a work item reaches a gate (here, `review`), Spacedock pauses and -presents a stage report: the chosen direction, the evidence behind it, and a -single recommendation. You approve, send it back with feedback, or reject. -[Gates and decisions](../concepts/gates-and-decisions.md) covers the full -machinery. +You approve, send it back with feedback, or reject. Details: +[gates and decisions](../concepts/gates-and-decisions.md). From there you are running the workflow: approving, sending back, and resuming -in later sessions. [Commission a workflow](../running-workflows/commission.md) -covers every design decision in full; -[Operating a workflow](../running-workflows/operating.md) covers the -day-to-day loop. +in later sessions, all within your normal Claude (or Codex) sessions. +[Commission a workflow](../running-workflows/commission.md) covers every +design decision; [Operating a workflow](../running-workflows/operating.md) +covers the day-to-day loop. Since this runs in your existing coding agent, you +can just ask the agent if anything is unclear. From 1ac3f8ef1a76c8e2c14e6b8fd9afc33af592088c Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 16:40:34 -0700 Subject: [PATCH 069/115] =?UTF-8?q?docs=20site:=20codify=20round-two=20les?= =?UTF-8?q?sons=20=E2=80=94=20payoff=20links,=20reader-angle=20headings,?= =?UTF-8?q?=20durable=20value,=20examples=20over=20description,=20agent-fa?= =?UTF-8?q?cing=20surfaces,=20defer=20to=20the=20agent?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/site/AGENTS.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/site/AGENTS.md b/docs/site/AGENTS.md index 492a810e..965b8050 100644 --- a/docs/site/AGENTS.md +++ b/docs/site/AGENTS.md @@ -16,8 +16,12 @@ Spacedock is not complicated; wordy docs make it *feel* complicated. Every edit - ✗ "The build emits a curated `llms.txt` index at the site root." - ✓ "Start from `llms.txt`, the curated index of these pages." - **A well-named command needs no caption.** "Run `spacedock doctor`." is complete; explaining that it diagnoses problems repeats the name. Likewise, never pre-document what a tool prints interactively (the install script already prints its own `PATH` note). -- **A heading is a promise; the section delivers exactly that.** Codex setup is not "Install Spacedock"; a tab the reader chose ("no Homebrew") must not explain the thing they opted out of. +- **A heading is a promise; the section delivers exactly that.** Codex setup is not "Install Spacedock"; a tab the reader chose ("no Homebrew") must not explain the thing they opted out of. Headings also take the reader's angle: name what the reader does or gets ("Turn the report into a workflow"), not what the product emits ("The commission offer"). - **Serve the typical reader; route edge audiences elsewhere.** A Get-started page carries only the path a typical user walks. Contributor and from-source material lives in the repo, not inline, not even as one sentence. +- **Document the durable value, not the output inventory.** Do not enumerate an artifact's current sections or fields; they drift with releases. Name what the reader gets out of it (the survey report is "the four things you learn", not a list of its sections). +- **A real example with sample output beats description.** One concrete command plus the output the reader will see teaches faster than paragraphs. Compose samples from the product's real templates, and never restate in prose what the sample already says ("Accept this design, or tell me what to change" makes a "nothing is generated until you accept" sentence dead weight). +- **Keep agent-facing surfaces off user pages.** Commands meant for the agents (`spacedock status`, `spacedock dispatch`) are not taught in Get started, even though their output is real. +- **The docs may defer to the agent.** Spacedock runs inside a coding agent; "ask the agent if anything is unclear" is a legitimate close. Pages cover what the reader needs before and between sessions, not every contingency within one. - **Cut, don't pad.** If a sentence still carries its meaning with a clause removed, remove the clause. If a paragraph repeats the page above it, delete it and link instead. - **Don't repeat content across pages.** One page owns each idea; others link to it. Duplicated explanation is the main thing that makes the docs feel long. An audience split ("new-user view" vs "operator view" of the same feature) is not a reason for a second page; it is the same topic. - **Two levels of structure only:** section → page. No deeper nesting; no page that exists only to hold sub-pages. @@ -53,6 +57,8 @@ Optimize for lookup in seconds. Use **tables** for flags, fields, and options (N - Cross-link liberally with **relative** internal links (so `mkdocs build --strict` resolves them). Concept → tutorial + reference; tutorial → concept + reference; reference → concept. - Link the first mention of a load-bearing term (`workflow`, `gate`, `ensign`, `commission`) to the page that owns it, rather than re-explaining it. - Descriptive link text, never "click here". +- **Link by payoff, not by contents.** A cross-link or Next entry names what the reader gains there ("read about the survey report to understand your usage pattern"), not what the page contains ("covers what survey reports"). +- **External tools get a gloss and a link to their own site.** A dependency that is not Spacedock (`agentsview`, `safehouse`) is a real thing the reader may install: name it, gloss it in one clause, link it on first mention. ## Voice @@ -67,7 +73,7 @@ This voice is grounded in two real signals, not invented: the root `README.md` ( Generated prose has a recognizable texture: padded, impersonal, and the fastest way to make simple software feel like a manual. Cut these on sight: -- **Em-dashes.** Do not use `—`. Rewrite as a period, a comma, a colon, or parentheses. A sentence that needs an em-dash usually wants to be two sentences. (Reproduced literal output, such as a rendered template or a verbatim error string, is exempt: it must match what the tool prints.) +- **Em-dashes.** Do not use `—`. Rewrite as a period, a comma, a colon, or parentheses. A sentence that needs an em-dash usually wants to be two sentences. The exemption is narrow: output reproduced verbatim (a captured transcript, a rendered template, an error string) must match what the tool prints. A sample you compose is prose: format it cleanly (newlines, colons) within the tool's real shape. - **The "not just X, but Y" frame** and its cousins ("it's not only…", "more than just…"). State what the thing is. Drop the contrast scaffolding. - **Rule-of-three padding.** Three parallel adjectives or clauses where one carries the meaning ("clear, simple, and easy to follow"). Keep the load-bearing one. - **Hollow transitions and hedges.** "That said," "It's worth noting that," "In order to," "It's important to understand." Delete them; start with the content. From 3a6f363338b3ddfd7c6632c4e2c4d5293dabae49 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 16:45:20 -0700 Subject: [PATCH 070/115] docs site: operating-model says what the first officer does for you; Roles heading; work item not entity; payoff links --- docs/site/concepts/operating-model.md | 28 +++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/site/concepts/operating-model.md b/docs/site/concepts/operating-model.md index 35cb5607..3e06ddf8 100644 --- a/docs/site/concepts/operating-model.md +++ b/docs/site/concepts/operating-model.md @@ -2,17 +2,17 @@ Spacedock runs on three roles and one division of labor: you shape the work and make the calls; the agents drive each item through its stages and bring decisions back to you with evidence. -## Three roles +## Roles | Role | Who | What they own | |------|-----|---------------| -| **Captain** | You. | The mission, and the call at every approval gate unless you delegate it. | -| **First Officer** | The orchestrator agent. | Running the workflow: dispatch, gate presentation, advancing entity state. | -| **Ensign** | The worker agent. | Moving one entity (one work item) forward through one stage. | +| **Captain** | You | The mission, and the call at every approval gate unless you delegate it | +| **First Officer** | The orchestrator agent | Runs the workflow for you and brings each decision to you with evidence | +| **Ensign** | The worker agent | Moves one work item through one stage | -Each session has one captain and one first officer. The number of ensigns tracks the dispatchable work: the first officer dispatches one per entity per stage. +Each session has one captain and one first officer; ensigns come and go with the work. -The first officer reads the workflow README, runs `spacedock status --next` to find entities ready to advance, and dispatches an ensign for each. An ensign reads its assignment, does the stage's work, commits, writes a stage report, and signals done. The first officer reviews that report against the checklist it dispatched. If the stage is gated, it pauses and presents the report to you. If not, it advances the entity and dispatches the next stage itself. A completed non-gated, non-terminal stage flows forward without pause. +The first officer keeps the work moving so you do not have to: it finds what is ready, hands each item to a worker, and checks the result against the bar you set. Gated stages pause for your call; everything else flows forward without you. ## Shaping versus driving @@ -20,22 +20,22 @@ The captain shapes; the agents drive. These are different jobs, and the split is **Shaping is defining what good looks like before the work runs.** You set the mission, the stages, and the bar each stage must clear, all declared in the workflow README rather than negotiated mid-task. You commission a workflow with [`/spacedock:commission`](../running-workflows/commission.md), and you make the calls at gates: approve, redo with feedback, or reject. Some gates you answer yourself; others resolve through a delegated agent review. That is the captain's whole standing job. -**Driving is moving entities through the declared stages.** The first officer schedules and dispatches; the ensign does the stage work and proves it. The first officer is allowed to take obvious reversible steps without asking: a dispatch the workflow already permits, a status read, a routine state transition. It asks you only when requirements are materially ambiguous, a design choice would change the output meaningfully, or scope is too unclear to turn into concrete criteria. Everything else happens without a prompt to you. +**Driving is moving work items through the declared stages.** The first officer schedules and dispatches; the ensign does the stage work and proves it. The first officer acts on its own for routine, reversible steps and asks you only when something is genuinely ambiguous: unclear requirements, a design choice that would change the output, scope too vague to turn into criteria. Everything else happens without a prompt to you. -The line holds because of one rule: the maker does not judge its own work. Review runs as a separate stage with fresh context and no access to the ensign's reasoning (see [Gates and decisions](gates-and-decisions.md)). The first officer never self-approves a gated stage. +The line holds because of one rule: the maker does not judge its own work. Review runs as a separate stage with fresh context and no access to the maker's reasoning (see [Gates and decisions](gates-and-decisions.md)). The first officer never self-approves a gated stage. ## Batched, evidenced decisions Decisions reach you batched and backed by evidence, not as a stream of interruptions. Your attention is the bottleneck; the agents queue work and surface only the calls that need a human. -**Batch the work; decide as it flows back.** Queue many entities at once. Ensigns advance each through its stages in parallel. You handle gates as they surface, not one session at a time, and not on the agent's schedule. While one entity waits on a clarification, the first officer keeps dispatching the others. +**Batch the work; decide as it flows back.** Queue many work items at once. Ensigns advance each through its stages in parallel. You handle gates as they surface, not one session at a time, and not on the agent's schedule. While one item waits on a clarification, the first officer keeps dispatching the others. -**Every gate carries evidence.** When the first officer presents a gate, it does not hand you the transcript. It renders a fixed gate-review format: the chosen direction in one line, a single clear recommendation you can approve with one "yes", a gist roll-up of the stage report's `DONE`/`SKIPPED`/`FAILED` items cited by file path and line range, and any reviewer findings split into `Material` and `Polish` tiers. The target is 15-25 lines. You decide on the evidence and the bar, not on a wall of output. +**Every gate carries evidence.** The first officer does not hand you the transcript. It presents a short review: what was chosen, the evidence for it, and one recommendation you can approve with a single yes. [Gates and decisions](gates-and-decisions.md) shows the format. -**The decision leaves a trail.** Each gate records the verdict and its reason alongside the stage report in the entity file. The record outlives the reviewer, so a bad result traces back to the call that caused it. When you end a session, [`/spacedock:debrief`](../running-workflows/debrief-and-refit.md) captures what happened (commits, state changes, decisions, open issues), and the next session picks up from it. +**The decision leaves a trail.** Each gate records the verdict and its reason alongside the stage report in the work item's file. The record outlives the reviewer, so a bad result traces back to the call that caused it. When you end a session, [`/spacedock:debrief`](../running-workflows/debrief-and-refit.md) captures what happened, and the next session picks up from it. ## Where to go next -- [Workflows and entities](workflows-and-entities.md) covers the directory and files the roles operate on. -- [Stage lifecycle](stage-lifecycle.md) walks an entity backlog → ideation → implementation → validation → done. -- [Gates and decisions](gates-and-decisions.md) lays out what a gate review carries, the three calls you make, and the detached adversarial audit. +- [Workflows and entities](workflows-and-entities.md) to see where your work lives as plain files. +- [Stage lifecycle](stage-lifecycle.md) to follow one item end to end. +- [Gates and decisions](gates-and-decisions.md) to see exactly what you decide and on what evidence. From 3c98ad87fc7b713a553d7a1aca2a4f9ad7b1edd2 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 16:52:33 -0700 Subject: [PATCH 071/115] docs site: operating-model splits shaping (product judgment) from owning the workflow; Ownership column; shapable mid-task --- docs/site/concepts/operating-model.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/site/concepts/operating-model.md b/docs/site/concepts/operating-model.md index 3e06ddf8..8be52311 100644 --- a/docs/site/concepts/operating-model.md +++ b/docs/site/concepts/operating-model.md @@ -4,9 +4,9 @@ Spacedock runs on three roles and one division of labor: you shape the work and ## Roles -| Role | Who | What they own | -|------|-----|---------------| -| **Captain** | You | The mission, and the call at every approval gate unless you delegate it | +| Role | Who | Ownership | +|------|-----|-----------| +| **Captain** | You | The mission, and the call at every approval gate unless delegated | | **First Officer** | The orchestrator agent | Runs the workflow for you and brings each decision to you with evidence | | **Ensign** | The worker agent | Moves one work item through one stage | @@ -16,9 +16,11 @@ The first officer keeps the work moving so you do not have to: it finds what is ## Shaping versus driving -The captain shapes; the agents drive. These are different jobs, and the split is what keeps you out of the per-step loop. +The captain shapes the product and owns the workflow; the agents drive. These are different jobs, and the split is what keeps you out of the per-step loop. -**Shaping is defining what good looks like before the work runs.** You set the mission, the stages, and the bar each stage must clear, all declared in the workflow README rather than negotiated mid-task. You commission a workflow with [`/spacedock:commission`](../running-workflows/commission.md), and you make the calls at gates: approve, redo with feedback, or reject. Some gates you answer yourself; others resolve through a delegated agent review. That is the captain's whole standing job. +**Shaping is the product judgment: the goal, the taste, the steering.** What to build, what good looks like, which direction survives a gate. You make the calls at gates (approve, redo with feedback, or reject); some you answer yourself, others resolve through a delegated agent review. This judgment is the part the agents cannot supply. + +**Owning the workflow is the structural half.** You set the stages and the bar each stage must clear, declared and serialized in the workflow README, starting from [`/spacedock:commission`](../running-workflows/commission.md). The declaration is shapable mid-task: you do not have to get it right the first time. When a bar turns out fuzzy in practice, tighten the README and the next dispatch works to the new line. **Driving is moving work items through the declared stages.** The first officer schedules and dispatches; the ensign does the stage work and proves it. The first officer acts on its own for routine, reversible steps and asks you only when something is genuinely ambiguous: unclear requirements, a design choice that would change the output, scope too vague to turn into criteria. Everything else happens without a prompt to you. From 1f326b2778d6174aabb56a37888bb0b6a88b7327 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 16:55:23 -0700 Subject: [PATCH 072/115] docs site: first-workflow closes with the session loop, debrief self-improvement, and multi-workflow coordination --- docs/site/get-started/first-workflow.md | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/docs/site/get-started/first-workflow.md b/docs/site/get-started/first-workflow.md index 5a509c16..295dcddc 100644 --- a/docs/site/get-started/first-workflow.md +++ b/docs/site/get-started/first-workflow.md @@ -79,8 +79,26 @@ Decision: approve to close; reject to bounce back to implementation. You approve, send it back with feedback, or reject. Details: [gates and decisions](../concepts/gates-and-decisions.md). -From there you are running the workflow: approving, sending back, and resuming -in later sessions, all within your normal Claude (or Codex) sessions. +## Session to session + +Every work item's state is stored and serialized in the workflow, so you do +not need to worry about context limits, resuming, or clearing. A typical +session, inside your normal Claude (or Codex) session: + +```bash +spacedock claude +``` + +It picks up whatever is ready to dispatch. You do a bunch of work: shaping, +asking the agents to dispatch, approving, rejecting, steering. Before you +stop, run [`/spacedock:debrief`](../running-workflows/debrief-and-refit.md) +to record what happened, update the learnings into the workflow, and file the +follow-up items. The workflow self-improves. + +A project can hold +[multiple workflows](../advanced/split-root-state.md) that coordinate with +each other; Spacedock drives them together and works out the dependencies. + [Commission a workflow](../running-workflows/commission.md) covers every design decision; [Operating a workflow](../running-workflows/operating.md) covers the day-to-day loop. Since this runs in your existing coding agent, you From 6ab9858799de650c0389a5f699bed57dab871d2b Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 17:00:14 -0700 Subject: [PATCH 073/115] docs site: first-workflow links serialized state to the concept page, fixes session stutter --- docs/site/get-started/first-workflow.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/site/get-started/first-workflow.md b/docs/site/get-started/first-workflow.md index 295dcddc..d3b91dbb 100644 --- a/docs/site/get-started/first-workflow.md +++ b/docs/site/get-started/first-workflow.md @@ -81,9 +81,9 @@ You approve, send it back with feedback, or reject. Details: ## Session to session -Every work item's state is stored and serialized in the workflow, so you do -not need to worry about context limits, resuming, or clearing. A typical -session, inside your normal Claude (or Codex) session: +Every work item's state is stored and serialized in the +[workflow](../concepts/workflows-and-entities.md), so you do not need to worry +about context limits, resuming, or clearing. A typical session: ```bash spacedock claude From 69b80e1b6916aeee2d2cbcda41a51a26f85900f6 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 17:07:22 -0700 Subject: [PATCH 074/115] =?UTF-8?q?docs=20site:=20concepts=20pages=20to=20?= =?UTF-8?q?the=20current=20standard=20=E2=80=94=20payoff=20ledes,=20no=20a?= =?UTF-8?q?gent=20commands,=20no=20inventories,=20reader-angle=20headings?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/site/advanced/split-root-state.md | 4 +- docs/site/concepts/gates-and-decisions.md | 15 +++--- docs/site/concepts/stage-lifecycle.md | 20 +++----- docs/site/concepts/worked-example.md | 45 +++++----------- docs/site/concepts/workflows-and-entities.md | 54 ++++---------------- 5 files changed, 35 insertions(+), 103 deletions(-) diff --git a/docs/site/advanced/split-root-state.md b/docs/site/advanced/split-root-state.md index 6c955325..b8da9d09 100644 --- a/docs/site/advanced/split-root-state.md +++ b/docs/site/advanced/split-root-state.md @@ -14,9 +14,7 @@ state: .spacedock-state Spacedock then reads stage declarations from the README and entities from the state path, and writes entity changes only into the state path. The split is transparent to the command surface: read the workflow exactly as you would a single-root one. -```bash -spacedock status --workflow-dir docs/dev -``` +On a fresh clone the state checkout is absent; run `spacedock state init` to restore it before working the workflow. The shipped `docs/dev` workflow runs split-root; see its README for a live example. diff --git a/docs/site/concepts/gates-and-decisions.md b/docs/site/concepts/gates-and-decisions.md index d8c0eedf..dcb839cf 100644 --- a/docs/site/concepts/gates-and-decisions.md +++ b/docs/site/concepts/gates-and-decisions.md @@ -4,7 +4,7 @@ A gate is the decision point at the end of a stage where nothing advances withou ## What a gate carries -The first officer presents a gate review only after it has read the worker's `## Stage Report`, checked every dispatched item, and counted the results. The review is the first officer's prose with a fixed spine. The first three lines and the last line carry the decision; everything between is supporting evidence. If you stop reading after line three, you can still vote. +A gate review has a fixed spine. The first three lines and the last line carry the decision; everything between is supporting evidence. If you stop reading after line three, you can still vote. A gate review looks like this: @@ -33,9 +33,9 @@ Reading the fields: - **`Recommend` is the first officer's verdict, stated exactly once.** - **`Checklist` is a gist roll-up, not the report.** The full `## Stage Report` is cited by file path and line range; open it when you want the detail. - **Reviewer findings split into `Material` and `Polish`.** Material items (fact-corrections, contract violations, missing acceptance-criterion evidence, claims the codebase contradicts) are the ones that should move your vote. Polish is non-blocking. An empty tier is dropped. -- **`Decision` names what your vote does in concrete terms.** For example, "approve to enter implementation in worktree `.worktrees/...`" or "reject to bounce back to {feedback-to target}". +- **`Decision` names what your vote does in concrete terms.** For example, "approve to enter implementation" or "reject to bounce back to design". -At every gate the first officer also runs an acceptance-criteria cross-check: it scans `## Acceptance criteria`, confirms each `**AC-N**` has evidence cited from this or a prior stage report, and names any criterion left without evidence. +Every acceptance criterion is also cross-checked before the review reaches you; a criterion left without cited evidence is named in the review rather than passed over. ## The three calls @@ -61,14 +61,11 @@ The first officer tracks each round in a `### Feedback Cycles` section in the en For high-stakes surfaces, a passing validation is necessary but not sufficient. Before merging, the first officer also runs a read-only adversarial audit. The audit catches the hole that validation cannot see itself: a test that passes today but would also pass on a broken future edit. -The audit triggers on four surfaces: the front-door launcher (`spacedock claude` / `codex` / `doctor`), the `status` mutation and guard paths, the shipped contract and scaffolding, and the CI and release machinery. Routine, low-blast-radius changes do not need it; a normal validation suffices. +A workflow names its own high-stakes surfaces; routine, low-blast-radius changes do not need an audit, a normal validation suffices. -It runs on a separate throwaway checkout, never the implementation worktree, and never mutates the deliverable. The auditor tries to refute the validation: it constructs an adversarial edit that the deliverable's own tests should catch and confirms they do. A test that stays green under an edit that breaks the claim is a hole. Findings come in two tiers, `Material` and `Polish`; "refuted nothing material" is a valid recorded outcome. +The audit is read-only and cannot touch the deliverable. It tries to refute the validation: it constructs an adversarial edit that the deliverable's own tests should catch and confirms they do. A test that stays green under an edit that breaks the claim is a hole. "Refuted nothing material" is a valid recorded outcome. -Results feed the same gate machinery: - -- **Material findings route back through the normal validation-to-implementation feedback flow**, with a `### Feedback Cycles` entry naming the audit and its adversarial edit. The gate is not presented as clean until they are closed. -- **A clean audit is noted in the gate's reviewer-findings block**, or as a one-line "detached audit: no material findings". +Material findings route back through the normal feedback flow, and the gate is not presented as clean until they are closed. A clean audit is noted in the review. ## Where to go next diff --git a/docs/site/concepts/stage-lifecycle.md b/docs/site/concepts/stage-lifecycle.md index 8d509985..ae14ec16 100644 --- a/docs/site/concepts/stage-lifecycle.md +++ b/docs/site/concepts/stage-lifecycle.md @@ -27,11 +27,11 @@ The stage order, names, and the properties each stage carries live in the workfl | `concurrency: N` | How many entities may sit in this stage at once. | | `agent: {name}` | Which worker skill the first officer dispatches. Defaults to `ensign`. | -Beyond these properties, the prose of each stage's `###` subsection in the README is the stage definition: its Inputs, Outputs, and the Good/Bad bar. The first officer copies that subsection verbatim into the ensign's assignment, so what a stage declares in prose is exactly what the worker receives as its assignment. +Beyond these properties, the prose of each stage's `###` subsection in the README is the stage definition: its Inputs, Outputs, and the Good/Bad bar. What you write there is exactly what the worker receives as its assignment. ## Fresh context at validation -Validation declares `fresh: true` because the reviewer must not be the maker. The first officer normally reuses a live worker across consecutive stages to save context, but a `fresh: true` stage forces a new dispatch every time. The validator arrives without the implementer's reasoning in its context, sees only the entity body and the deliverable, and pushes back on thin evidence. This is the mechanism behind the README's claim that "the agent doesn't get to judge its own work." +Validation declares `fresh: true` because the reviewer must not be the maker. The validator arrives without the implementer's reasoning in its context, sees only the entity body and the deliverable, and pushes back on thin evidence. This is the mechanism behind the README's claim that "the agent doesn't get to judge its own work." When validation recommends `REJECTED`, `feedback-to: implementation` routes the concrete finding back to the implementation stage for rework rather than closing the entity. The entity re-enters implementation, the finding is addressed, and a fresh validator checks it again. A hard cap on feedback cycles prevents an endless bounce; on the third cycle the first officer escalates to you. @@ -39,18 +39,10 @@ When validation recommends `REJECTED`, `feedback-to: implementation` routes the A stage runs in an isolated git worktree when it declares `worktree: true`, and inline at the repo root otherwise. This is the "isolation when it matters" tradeoff: stages that mutate shared state (implementation, validation) get their own checkout so concurrent entities don't collide; lighter stages that only edit the entity body (backlog, ideation) run inline. -The first officer manages the isolation for you: it creates the worktree under `.worktrees/` on first dispatch and records the path in the entity's `worktree` frontmatter field, the stage's work and commits stay inside that checkout, and at the terminal stage it merges the branch and cleans the worktree up. In a [split-root workflow](../advanced/split-root-state.md) the entity file itself lives in the state checkout; the worktree isolates only the deliverable. - -To see where each entity sits and which are ready to advance, read the workflow state: - -```bash -spacedock status --workflow-dir docs/dev --next -``` - -`--next` lists the entities ready for dispatch, the query the first officer runs each loop; drop it for the full queue. The `worktree` column shows the isolated checkout path for any entity currently mid-stage in a worktree-backed stage. +The first officer manages the isolation for you: it creates the worktree on first dispatch, the stage's work and commits stay inside that checkout, and at the terminal stage it merges the branch and cleans the worktree up. In a [split-root workflow](../advanced/split-root-state.md) the entity file itself lives in the state checkout; the worktree isolates only the deliverable. ## Where to go next -- [The operating model](operating-model.md) names the roles that drive this pipeline: captain, first officer, ensign. -- [Gates and decisions](gates-and-decisions.md) covers the decision points at stage boundaries. -- The [frontmatter contract](../reference/frontmatter-contract.md) lists the entity fields these stages update. +- [The operating model](operating-model.md) for who does what: you, the orchestrator, the workers. +- [Gates and decisions](gates-and-decisions.md) to see exactly what you decide at a stage boundary and on what evidence. +- The [frontmatter contract](../reference/frontmatter-contract.md) to look up the fields these stages write. diff --git a/docs/site/concepts/worked-example.md b/docs/site/concepts/worked-example.md index ccef90d1..7b08ee74 100644 --- a/docs/site/concepts/worked-example.md +++ b/docs/site/concepts/worked-example.md @@ -10,34 +10,15 @@ The workflow is `docs/dev` (the Spacedock v1 dev workflow); its stages, gates, and entity schema are defined in [the development workflow README](https://github.com/spacedock-dev/spacedock/blob/main/docs/dev/README.md). Runtime entity state lives in a separate `.spacedock-state` checkout, so the -finished entity itself is not in the main tree. Its full trajectory is in -the `0198-pre-flip-hardening` sprint directory: `index.md`, -`dispatch-sprint-execution.md`, `debrief.md`, and `post-sprint-audit.md`. +finished entity itself is not in the main tree. Its full trajectory is in the +`0198-pre-flip-hardening` sprint directory (a sprint groups work items driven +together to one deliverable): `index.md`, `dispatch-sprint-execution.md`, +`debrief.md`, and `post-sprint-audit.md`. `z9` delivered front-door Codex plugin auto-install: `spacedock codex` now installs a missing plugin then launches, the Codex analog of the Claude path. It shipped as [PR #329](https://github.com/spacedock-dev/spacedock/pull/329). -## See where it sits - -Each first-officer loop starts by asking the workflow what is ready to move. You -run the same query: - -```bash -spacedock status --workflow-dir docs/dev --next -``` - -This lists the entities ready to dispatch. To scope to one sprint, filter with -`--where`: - -```bash -spacedock status --workflow-dir docs/dev \ - --where sprint=0198-pre-flip-hardening --where 'sprint-readiness != defer' -``` - -This query is the sprint membership source of truth, not a hand-kept list. -At the start of `0198`, `z9` shows up here in the `binary-ux` group. - ## backlog → ideation: shape the work `z9` enters backlog as a seed: a title, a source, and a brief description of the @@ -54,9 +35,8 @@ a literal) and recorded it before committing to the rest of the plan. Ideation ends at a **gate**. Because the dev workflow marks `ideation` with `gate: true`, the first officer does not advance on its own: it presents the design to the captain. The captain approved `z9`'s ideation on 2026-06-08. That -approval is the entry condition for implementation, and it is captured in the -sprint package so a later session drives implementation directly without -re-presenting the gate. +approval is the entry condition for implementation, and it is on the record, so +a later session proceeds without re-asking. ## implementation: produce the deliverable @@ -64,8 +44,8 @@ Once the design is approved, `z9` moves to implementation. The dev workflow runs this stage in a `worktree` (`worktree: true`), so the dispatched ensign works in an isolated checkout, not the shared tree. -The dispatch package handed the implementer three build notes, verbatim from the -sprint's `dispatch-sprint-execution.md`: +The implementer was handed three build notes, verbatim from the sprint's +`dispatch-sprint-execution.md`: > Build notes: **(a)** the codex install branch MUST be the shared `devBranch` > (`ops.Install("codex", marketplaceSource, devBranch)` + `--ref `), @@ -92,11 +72,10 @@ cites, and produces a PASSED or REJECTED recommendation. `z9` is a front-door change, a high-stakes surface, so validation alone was not sufficient. The dev workflow requires a **detached adversarial audit** for the -launcher front door: a read-only pass on a throwaway checkout of the merge result -that tries to refute the validation. The `z9` audit ran at commit `0b714fac` -and exercised five mandated probes, each reddening the test suite then reverting. -It refuted nothing material. Channel-tracking was confirmed clean. That clean -audit satisfied the sprint's definition-of-done item for the high-stakes surface. +launcher front door: a read-only pass that tries to refute the validation. The +`z9` audit ran at commit `0b714fac`, exercised five probes (each proving the +tests would catch a break), and refuted nothing material. That clean audit +satisfied the sprint's definition-of-done for the high-stakes surface. Validation also has `gate: true` and `feedback-to: implementation`. A REJECTED recommendation routes the finding back to implementation for another cycle; a diff --git a/docs/site/concepts/workflows-and-entities.md b/docs/site/concepts/workflows-and-entities.md index a67d0ba5..46103c5f 100644 --- a/docs/site/concepts/workflows-and-entities.md +++ b/docs/site/concepts/workflows-and-entities.md @@ -1,12 +1,12 @@ # Workflows & entities -**A workflow is a directory plus a README, and an entity is one markdown file inside it.** The README defines the stages, the schema, and the gates; each entity is a work item that moves through those stages. Everything about a work item lives in the file itself: the problem, the design notes, the bar for done, the stage reports. State survives a session, so the next session picks up where you left off. +**Your work lives as plain text in your repo: readable, editable, diffable, and nothing is lost between sessions.** A workflow is a directory plus a README; an entity is one markdown file inside it, one work item. Everything about a work item is in its file: the problem, the design notes, the bar for done, the reports filed as it advances. -## The workflow: a directory and its README +## The README is where you set the rules -The README is the single source of truth. Its frontmatter declares the stages, the entity type, and the ID style; its prose body defines what each stage means, what counts as good, and what a worker must produce. You commission a workflow with `/spacedock:commission`, which generates the directory, the README, and a few seed entities. +The README is the single source of truth: it declares the stages and defines what each stage means, what counts as good, and what a worker must produce. Commission generates it; you edit it like any file, at any time. When a bar turns out fuzzy in practice, tighten the prose and the next dispatch works to the new line. -A minimal README frontmatter looks like this: +A generated README's frontmatter looks like this: ```yaml --- @@ -34,52 +34,18 @@ stages: --- ``` -Each `states` entry is one stage. Its flags decide where an entity starts and ends (`initial`, `terminal`), which stages pause for your call (`gate`), which run in an isolated worktree (`worktree`), which get a reviewer with no access to the maker's reasoning (`fresh`), and where rejected work bounces back to (`feedback-to`). [What a stage declares](stage-lifecycle.md#what-a-stage-declares) defines every property. +Each `states` entry is one stage; its flags decide where work starts and ends, which stages pause for your call, and where rejected work bounces back to. [What a stage declares](stage-lifecycle.md#what-a-stage-declares) defines every property. -The README body documents each stage with `Inputs`, `Outputs`, `Good`, and `Bad`. That prose is the living spec; every dispatched ensign works from it. Tighten it to your actual bar before the first dispatch; editing it after agents have run against vague prose costs more. +## Each work item is one file -## The entity: one work item +An entity lives as a flat file `{slug}.md`, or a folder `{slug}/index.md` when reports and artifacts accumulate beside it. The body is the human-readable record: the problem, the approach, the acceptance criteria, and the stage reports. On top sits YAML frontmatter, the machine-readable state: the item's id, its current stage, its outcome. The [frontmatter contract](../reference/frontmatter-contract.md) lists every field. -**An entity lives as a flat file `{slug}.md` or a folder `{slug}/index.md`.** Use the folder form when reports or artifacts accumulate beside the work item. Slugs are lowercase with hyphens, no spaces (`add-login.md` or `add-login/index.md`). `spacedock status` reads both forms. +## Keep workflow state off your code branch -The body holds the human-readable record: a description, a problem statement, the proposed approach, acceptance criteria, and the stage reports filed as the entity advances. - -## Entity frontmatter - -The YAML frontmatter at the top of the file is the machine-readable state. The full schema lives in the workflow README; the [frontmatter contract](../reference/frontmatter-contract.md) is the field reference across workflows. The fields you set and read most often: - -| Field | What it holds | -|-------|---------------| -| `id` | The unique identifier; format set by `id-style` in the README. | -| `title` | Human-readable name. The filename slug is derived from it. | -| `status` | The current stage, one of the stage names declared in the README. | -| `source` | Where the entity came from (e.g. `commission seed`, `linear`). | -| `started` / `completed` | ISO 8601 timestamps for when work began and when the entity reached terminal. | -| `verdict` | `PASSED` or `REJECTED`, set at the final stage. | -| `score` | Optional priority, 0.0–1.0. | -| `worktree` | The worktree path while a dispatched agent is active; empty otherwise. | -| `issue` | Optional external ticket reference, e.g. `ENG-123`, `kata:task-abc123`, or `owner/repo#42`. | - -The frontmatter parser is line-oriented: keep fields flat and top-level. If a workflow needs more metadata, add flat custom fields rather than nested YAML. - -`status` drives dispatch: the first officer reads it to decide which entities are ready to advance. To see the queue, run the status viewer against the workflow directory: - -```bash -spacedock status --workflow-dir docs/dev -``` - -Add `--next` to list only the entities ready for dispatch. - -## Where entities live: the state checkout - -**A workflow can keep its mutable entity state separate from the README using a state checkout.** The README frontmatter declares it with one field: +A workflow can keep its mutable state in a separate state checkout, so routine stage transitions never churn your code branch or collide with a feature PR. The README opts in with one field: ```yaml state: .spacedock-state ``` -With this set, the README (the living spec) stays on your code branch, while the entity files, their reports, and the archive live under `.spacedock-state`. Routine stage transitions never churn the code branch or collide with a feature PR; `spacedock status` reads and writes across the split for you. - -State lives on a separate branch in the same repo, so the code branch never sees a state commit. On a fresh clone the state checkout is absent; run `spacedock state init` to restore it before working the workflow. - -Omit `state:` (or set `state: $inline`) for a standalone workflow that isn't embedded in a code repo you ship from. Then the entities live beside the README in the same directory, with no extra branch or checkout. +The README stays on your code branch as the living spec; the work items and their reports live on a separate branch your code branch never sees. [Multi-workflow & split-root state](../advanced/split-root-state.md) covers the mechanics and the fresh-clone setup. From edd7848b387fd6334040ef2c15bbe5ce95d41d5b Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 17:13:16 -0700 Subject: [PATCH 075/115] =?UTF-8?q?docs=20site:=20workflows-and-entities?= =?UTF-8?q?=20=E2=80=94=20FO=20edits=20the=20README=20for=20you,=20dev=20R?= =?UTF-8?q?EADME=20as=20live=20example,=20cut=20redundant=20flag=20and=20c?= =?UTF-8?q?ode-branch=20sentences?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/site/concepts/workflows-and-entities.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/site/concepts/workflows-and-entities.md b/docs/site/concepts/workflows-and-entities.md index 46103c5f..77af5141 100644 --- a/docs/site/concepts/workflows-and-entities.md +++ b/docs/site/concepts/workflows-and-entities.md @@ -4,7 +4,7 @@ ## The README is where you set the rules -The README is the single source of truth: it declares the stages and defines what each stage means, what counts as good, and what a worker must produce. Commission generates it; you edit it like any file, at any time. When a bar turns out fuzzy in practice, tighten the prose and the next dispatch works to the new line. +The README is the single source of truth: it declares the stages and defines what each stage means, what counts as good, and what a worker must produce. Commission generates it; you edit it like any file, at any time, or more likely ask the first officer to edit it to improve the workflow. When a bar turns out fuzzy in practice, tighten the prose and the next dispatch works to the new line. Spacedock's own [dev workflow README](https://github.com/spacedock-dev/spacedock/blob/main/docs/dev/README.md) is a live example. A generated README's frontmatter looks like this: @@ -34,18 +34,16 @@ stages: --- ``` -Each `states` entry is one stage; its flags decide where work starts and ends, which stages pause for your call, and where rejected work bounces back to. [What a stage declares](stage-lifecycle.md#what-a-stage-declares) defines every property. - ## Each work item is one file An entity lives as a flat file `{slug}.md`, or a folder `{slug}/index.md` when reports and artifacts accumulate beside it. The body is the human-readable record: the problem, the approach, the acceptance criteria, and the stage reports. On top sits YAML frontmatter, the machine-readable state: the item's id, its current stage, its outcome. The [frontmatter contract](../reference/frontmatter-contract.md) lists every field. ## Keep workflow state off your code branch -A workflow can keep its mutable state in a separate state checkout, so routine stage transitions never churn your code branch or collide with a feature PR. The README opts in with one field: +A workflow can keep its mutable state in a separate state checkout, so routine stage transitions never churn your code branch or collide with a feature PR. The README opts in with one field, and you can ask the first officer to change the setting: ```yaml state: .spacedock-state ``` -The README stays on your code branch as the living spec; the work items and their reports live on a separate branch your code branch never sees. [Multi-workflow & split-root state](../advanced/split-root-state.md) covers the mechanics and the fresh-clone setup. +[Multi-workflow & split-root state](../advanced/split-root-state.md) covers the mechanics and the fresh-clone setup. From 67d0e777bd1a654de6f3bf3d4cb049418386495e Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 17:16:13 -0700 Subject: [PATCH 076/115] docs site: stage chain as a mermaid diagram; typical dev workflow, feedback-to as the property that matters --- docs/site/concepts/stage-lifecycle.md | 18 ++++++++++-------- mkdocs.yml | 6 +++++- 2 files changed, 15 insertions(+), 9 deletions(-) diff --git a/docs/site/concepts/stage-lifecycle.md b/docs/site/concepts/stage-lifecycle.md index ae14ec16..50146a7c 100644 --- a/docs/site/concepts/stage-lifecycle.md +++ b/docs/site/concepts/stage-lifecycle.md @@ -1,16 +1,18 @@ # The stage lifecycle -An entity moves through an ordered chain of stages that the workflow defines, one at a time, and each stage declares the work it owns and the proof it must produce. The dev workflow's chain is `backlog → ideation → implementation → validation → done`; your own workflow names its own stages, but the mechanics are the same. The first officer advances an entity stage by stage, dispatching one ensign per stage and pausing at the gates you declared. +An entity moves through an ordered chain of stages that the workflow defines, and each stage declares the work it owns and the proof it must produce. The first officer advances an entity stage by stage, pausing at the gates you declared. -## The dev workflow's stages +## A typical dev workflow -The five stages below are the dev workflow's stages, used as the running example for this page; the full per-stage Inputs/Outputs/Good/Bad detail lives in its [README](https://github.com/spacedock-dev/spacedock/blob/main/docs/dev/README.md). Read the chain as a pipeline: each stage takes the prior stage's output as its input, and the bar rises from "is this clear?" to "is this proven?". +```mermaid +flowchart LR + backlog --> ideation --> implementation --> validation --> done + validation -. rejected .-> implementation +``` -- **`backlog`, the seed.** An entity enters here when first proposed: a title, a source, a brief description, and the test gates future stages must satisfy. No design work yet. `initial: true`, so this is where every new entity starts. The dev workflow also marks it `gate: true`, so the first officer presents a new entity for your go-ahead before it advances. -- **`ideation`, the design.** A worker clarifies the problem, explores approaches, and produces a fleshed-out body: problem statement, proposed approach, acceptance criteria, and a test plan. Each acceptance criterion names how it will be checked. This stage is `gate: true` in the dev workflow, so the first officer presents the design for your approval before any code is written. -- **`implementation`, the deliverable.** A worker produces the change the entity describes: code, fixtures, instruction text, on-disk state. This stage is `worktree: true`, so the work happens in an isolated checkout. A completed, non-gated stage flows straight to validation. -- **`validation`, the independent check.** A worker verifies the deliverable against the acceptance criteria. It checks what was produced; it does not produce the deliverable itself. It reproduces the evidence each `AC-N` cites and returns a `PASSED` or `REJECTED` recommendation. This stage is `worktree: true`, `fresh: true`, `feedback-to: implementation`, and `gate: true`. -- **`done`, the verdict.** Validation is complete and you approve the result. The entity is closed with a `verdict` of `PASSED` or `REJECTED` and a `completed` timestamp. `terminal: true`. +Read the chain as a pipeline: each stage takes the prior stage's output as its input, and the bar rises from "is this clear?" to "is this proven?". Here ideation and validation end at gates: your call before code is written, and your call before the result ships. + +The property that matters most is `feedback-to`: rejected work bounces back to the stage that owns the fix (a rejected validation returns to implementation), not to the reviewer that flagged it. ## What a stage declares diff --git a/mkdocs.yml b/mkdocs.yml index fcf02834..406777ec 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -100,7 +100,11 @@ markdown_extensions: - pymdownx.highlight: anchor_linenums: true - pymdownx.details - - pymdownx.superfences + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format - pymdownx.tabbed: alternate_style: true - toc: From cd3e645f900769c37e46afd2b52728332679c5f7 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 17:17:07 -0700 Subject: [PATCH 077/115] =?UTF-8?q?docs=20site:=20stage=20declarations=20a?= =?UTF-8?q?s=20capabilities,=20not=20a=20field=20table=20=E2=80=94=20the?= =?UTF-8?q?=20agent=20sets=20them=20up?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/site/concepts/stage-lifecycle.md | 17 +++-------------- 1 file changed, 3 insertions(+), 14 deletions(-) diff --git a/docs/site/concepts/stage-lifecycle.md b/docs/site/concepts/stage-lifecycle.md index 50146a7c..a83d3a71 100644 --- a/docs/site/concepts/stage-lifecycle.md +++ b/docs/site/concepts/stage-lifecycle.md @@ -16,20 +16,9 @@ The property that matters most is `feedback-to`: rejected work bounces back to t ## What a stage declares -The stage order, names, and the properties each stage carries live in the workflow README's frontmatter under `stages.states`. Each entry is a stage name plus a set of boolean or string properties the first officer reads to decide how to dispatch and when to stop. A `stages.defaults` block sets the baseline; a stage entry overrides it. The properties that change behavior: - -| Property | Effect | -|----------|--------| -| `initial: true` | The stage an entity starts in. The dev workflow marks `backlog`. | -| `terminal: true` | The stage an entity ends in. Reaching it runs the merge and cleanup ceremony, not another dispatch. The dev workflow marks `done`. | -| `gate: true` | The first officer presents a stage report and waits for your decision instead of advancing on its own. | -| `worktree: true` | The stage's work runs in an isolated git worktree. Absent or `false`, it runs inline. | -| `fresh: true` | The stage always gets a freshly dispatched ensign, never a worker reused from the prior stage. | -| `feedback-to: {stage}` | On rejection, work routes back to the named stage rather than failing outright. | -| `concurrency: N` | How many entities may sit in this stage at once. | -| `agent: {name}` | Which worker skill the first officer dispatches. Defaults to `ensign`. | - -Beyond these properties, the prose of each stage's `###` subsection in the README is the stage definition: its Inputs, Outputs, and the Good/Bad bar. What you write there is exactly what the worker receives as its assignment. +A stage can pause at a gate for your decision, run its work in an isolated worktree, demand a reviewer with no access to the maker's reasoning, route rejected work back to an earlier stage, cap how many items it holds at once, and hand its work to a specialist worker. All of it is declared in the workflow README; ask the first officer to set up or change any of it. + +Beyond the declarations, the prose of each stage's section in the README is the stage definition. What you write there is exactly what the worker receives as its assignment. ## Fresh context at validation From 816cacf2f76a3800e269ae2dd1f5eaebb7ad8b8b Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 17:19:03 -0700 Subject: [PATCH 078/115] docs site: worktree section is one sentence of what happens, no tradeoff narration --- docs/site/concepts/stage-lifecycle.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/site/concepts/stage-lifecycle.md b/docs/site/concepts/stage-lifecycle.md index a83d3a71..b1459c20 100644 --- a/docs/site/concepts/stage-lifecycle.md +++ b/docs/site/concepts/stage-lifecycle.md @@ -26,11 +26,9 @@ Validation declares `fresh: true` because the reviewer must not be the maker. Th When validation recommends `REJECTED`, `feedback-to: implementation` routes the concrete finding back to the implementation stage for rework rather than closing the entity. The entity re-enters implementation, the finding is addressed, and a fresh validator checks it again. A hard cap on feedback cycles prevents an endless bounce; on the third cycle the first officer escalates to you. -## Worktree vs. inline +## Isolated worktrees -A stage runs in an isolated git worktree when it declares `worktree: true`, and inline at the repo root otherwise. This is the "isolation when it matters" tradeoff: stages that mutate shared state (implementation, validation) get their own checkout so concurrent entities don't collide; lighter stages that only edit the entity body (backlog, ideation) run inline. - -The first officer manages the isolation for you: it creates the worktree on first dispatch, the stage's work and commits stay inside that checkout, and at the terminal stage it merges the branch and cleans the worktree up. In a [split-root workflow](../advanced/split-root-state.md) the entity file itself lives in the state checkout; the worktree isolates only the deliverable. +When a stage declares `worktree: true`, everything from that stage onward happens in an isolated worktree: the work and its commits stay there, concurrent items never collide with each other or with you, and at the terminal stage the branch is merged back and the worktree cleaned up. ## Where to go next From a71f00cf6d261a8a9f69bca48bad4f31d370d8fd Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 17:20:09 -0700 Subject: [PATCH 079/115] docs site: gates annotated in the stage diagram; gate links to the concept page --- docs/site/concepts/stage-lifecycle.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/site/concepts/stage-lifecycle.md b/docs/site/concepts/stage-lifecycle.md index b1459c20..24138bdf 100644 --- a/docs/site/concepts/stage-lifecycle.md +++ b/docs/site/concepts/stage-lifecycle.md @@ -6,17 +6,17 @@ An entity moves through an ordered chain of stages that the workflow defines, an ```mermaid flowchart LR - backlog --> ideation --> implementation --> validation --> done + backlog --> ideation["ideation (gate)"] --> implementation --> validation["validation (gate)"] --> done validation -. rejected .-> implementation ``` -Read the chain as a pipeline: each stage takes the prior stage's output as its input, and the bar rises from "is this clear?" to "is this proven?". Here ideation and validation end at gates: your call before code is written, and your call before the result ships. +Read the chain as a pipeline: each stage takes the prior stage's output as its input, and the bar rises from "is this clear?" to "is this proven?". The two gates are your calls: before code is written, and before the result ships. The property that matters most is `feedback-to`: rejected work bounces back to the stage that owns the fix (a rejected validation returns to implementation), not to the reviewer that flagged it. ## What a stage declares -A stage can pause at a gate for your decision, run its work in an isolated worktree, demand a reviewer with no access to the maker's reasoning, route rejected work back to an earlier stage, cap how many items it holds at once, and hand its work to a specialist worker. All of it is declared in the workflow README; ask the first officer to set up or change any of it. +A stage can pause at a [gate](gates-and-decisions.md) for your decision, run its work in an isolated worktree, demand a reviewer with no access to the maker's reasoning, route rejected work back to an earlier stage, cap how many items it holds at once, and hand its work to a specialist worker. All of it is declared in the workflow README; ask the first officer to set up or change any of it. Beyond the declarations, the prose of each stage's section in the README is the stage definition. What you write there is exactly what the worker receives as its assignment. From d1f3f481e864126b1799c223c3c14f4d0fcb586a Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 17:21:39 -0700 Subject: [PATCH 080/115] docs site: gate stages marked by gold border in the diagram, caption in prose --- docs/site/concepts/stage-lifecycle.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/site/concepts/stage-lifecycle.md b/docs/site/concepts/stage-lifecycle.md index 24138bdf..d4b97f4d 100644 --- a/docs/site/concepts/stage-lifecycle.md +++ b/docs/site/concepts/stage-lifecycle.md @@ -6,11 +6,13 @@ An entity moves through an ordered chain of stages that the workflow defines, an ```mermaid flowchart LR - backlog --> ideation["ideation (gate)"] --> implementation --> validation["validation (gate)"] --> done + backlog --> ideation --> implementation --> validation --> done validation -. rejected .-> implementation + classDef gate stroke:#e3b04b,stroke-width:2.5px + class ideation,validation gate ``` -Read the chain as a pipeline: each stage takes the prior stage's output as its input, and the bar rises from "is this clear?" to "is this proven?". The two gates are your calls: before code is written, and before the result ships. +The gold-bordered stages are gates, your calls: before code is written, and before the result ships. Read the chain as a pipeline: each stage takes the prior stage's output as its input, and the bar rises from "is this clear?" to "is this proven?". The property that matters most is `feedback-to`: rejected work bounces back to the stage that owns the fix (a rejected validation returns to implementation), not to the reviewer that flagged it. From f6cb32e5e0125235c8a54bc8d008278e8ffb3872 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 17:28:17 -0700 Subject: [PATCH 081/115] docs site: gates leads with delegation; concrete reject sample replaces template walkthrough --- docs/site/concepts/gates-and-decisions.md | 66 ++++++++++------------- 1 file changed, 28 insertions(+), 38 deletions(-) diff --git a/docs/site/concepts/gates-and-decisions.md b/docs/site/concepts/gates-and-decisions.md index dcb839cf..365325f8 100644 --- a/docs/site/concepts/gates-and-decisions.md +++ b/docs/site/concepts/gates-and-decisions.md @@ -1,61 +1,51 @@ # Gates & decisions -A gate is the decision point at the end of a stage where nothing advances without your vote. When a stage is marked `gate: true` in the workflow README, the first officer stops after the worker completes, renders a gate review, and waits for you. It never self-approves. +A gate is the decision point at the end of a stage where nothing advances without your vote. When a stage declares a gate, the first officer stops after the worker completes, presents a review, and waits for you. It never self-approves. -## What a gate carries - -A gate review has a fixed spine. The first three lines and the last line carry the decision; everything between is supporting evidence. If you stop reading after line three, you can still vote. - -A gate review looks like this: +Each call you make sharpens the bar, and the destination is delegation. When you are sufficiently confident in the workflow and the bar you set, hand over the conn and let the first officer drive multiple tasks with auto-approval: ``` -Gate review: {entity title} — {stage} -Chosen direction: {one-line summary of the worker's approach, or n/a} -Recommend {approve | reject: {one-line reason}}. +you have the conn to drive toward your sprint goal, authorized to approve and +merge PR on CI green. use your judgement. +``` -Checklist (from ## Stage Report in {entity_file_path} lines {start}-{end}): -- DONE: {≤10-word gist} -- SKIPPED: {gist} — {reason} -- FAILED: {gist} — {reason} +Until then, the gates are yours. -Reviewer findings - Material: {fact-corrections, contract violations, missing AC evidence} - Polish: {wording, format drift, non-blocking suggestions} +## What you see at a gate -Assessment: {N} done, {N} skipped, {N} failed. +A gate review has a fixed spine: the first three lines and the last line carry the decision, everything between is supporting evidence. If you stop reading after line three, you can still vote. -Decision: {what approval/rejection does in concrete terms}. ``` +Gate review: Fix the flaky login test — review +Chosen direction: replace sleep-based waits with event polling +Recommend reject: the AC-2 retry scenario has no covering test. -Reading the fields: - -- **`Chosen direction` names what the worker picked**, so you do not have to open the entity file to learn it. Ideation picks an approach; validation picks PASS or REJECTED. Stages with no choice to make show `n/a`. -- **`Recommend` is the first officer's verdict, stated exactly once.** -- **`Checklist` is a gist roll-up, not the report.** The full `## Stage Report` is cited by file path and line range; open it when you want the detail. -- **Reviewer findings split into `Material` and `Polish`.** Material items (fact-corrections, contract violations, missing acceptance-criterion evidence, claims the codebase contradicts) are the ones that should move your vote. Polish is non-blocking. An empty tier is dropped. -- **`Decision` names what your vote does in concrete terms.** For example, "approve to enter implementation" or "reject to bounce back to design". +Checklist (from ## Stage Report in docs/ship-features/fix-the-flaky-login-test.md): +- DONE: login test stable across 50 consecutive runs +- FAILED: retry scenario unproven — no test exercises it -Every acceptance criterion is also cross-checked before the review reaches you; a criterion left without cited evidence is named in the review rather than passed over. - -## The three calls +Reviewer findings + Material: AC-2 cites a test file that does not exist + Polish: stage report wording drifts from the template -You answer a gate with one of three calls. +Assessment: 1 done, 0 skipped, 1 failed. -- **Approve.** The entity advances to the next stage and the first officer dispatches it. If the next stage opens or closes a worktree, the `Decision` line told you so. Approving the terminal stage runs the merge and cleanup ceremony. -- **Redo with feedback.** You approve the direction but send concrete fixes back. Name the specific asks ("tighten the AC-2 substring assertion, correct the file path claim"), not "address the reviewer's notes". The first officer routes your asks back to the stage that owns the work, the worker re-does it, and the gate is re-presented. -- **Reject.** At a stage with a `feedback-to` target, rejecting bounces the work back to that target stage to be fixed and re-validated; this is the feedback cycle below. At a stage without `feedback-to`, rejection is terminal for that path. +Decision: approve to close; reject to bounce back to implementation. +``` -A redo and a reject at a `feedback-to` stage run the same routing machinery. The difference is whether you are correcting a direction you accept or sending it back. Both name the concrete fix asks so the next worker has something to act on. +Material findings are the ones that should move your vote; Polish never blocks. The Decision line tells you concretely what your vote does. Every acceptance criterion is cross-checked before the review reaches you; a criterion without cited evidence is named rather than passed over. -**A terminal close needs a recorded verdict.** Approving the terminal stage finalizes the entity, and Spacedock refuses to finalize or archive a terminal entity that carries no `verdict`: the outcome must be on the record. See the [frontmatter contract](../reference/frontmatter-contract.md#entity-fields) for the mechanics. +## The three calls -## Feedback cycles and the loop cap +- **Approve.** The work advances to the next stage. Approving the terminal stage merges and closes it. +- **Redo with feedback.** You accept the direction but send concrete fixes back. Name the specific asks ("tighten the AC-2 substring assertion, correct the file path claim"), not "address the reviewer's notes". +- **Reject.** The work bounces back to the stage that owns the fix, carrying your findings. -When a feedback stage recommends `REJECTED`, or you reject at a `feedback-to` stage, the work routes back to the stage named in `feedback-to`: the stage that owns the fix, not the reviewer that flagged it. In the dev workflow, `validation` has `feedback-to: implementation`, so a rejected validation sends the deliverable back to implementation, not back to the validator. +Redo and reject differ only in whether you accept the direction; both carry your concrete asks so the next worker has something to act on. Nothing closes without its verdict on the record. -The first officer tracks each round in a `### Feedback Cycles` section in the entity body. Your concrete findings route to the `feedback-to` target, the reviewer re-runs after the fix, and the gate comes back to you as a fresh review. +## When you reject -**The loop caps at three.** On cycle 3 the first officer escalates to you instead of bouncing a fourth time: the same fix has failed twice, so the call returns to a human. +Your findings route back automatically, the work is redone, the reviewer re-runs, and the gate comes back to you as a fresh review. Every round is on the record in the item's file. **The loop caps at three:** on the third failure the call returns to a human instead of bouncing again. ## The detached adversarial audit From ec38c432f935a4a4dce01bb4588e9a0312e9ccc0 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 17:32:03 -0700 Subject: [PATCH 082/115] docs site: gates polish from comm-officer review (5 of 7 accepted) --- docs/site/concepts/gates-and-decisions.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/site/concepts/gates-and-decisions.md b/docs/site/concepts/gates-and-decisions.md index 365325f8..fa6889ee 100644 --- a/docs/site/concepts/gates-and-decisions.md +++ b/docs/site/concepts/gates-and-decisions.md @@ -13,7 +13,7 @@ Until then, the gates are yours. ## What you see at a gate -A gate review has a fixed spine: the first three lines and the last line carry the decision, everything between is supporting evidence. If you stop reading after line three, you can still vote. +A gate review has a fixed spine: the first three lines and the last line carry the decision; everything between is supporting evidence. If you stop reading after line three, you can still vote. ``` Gate review: Fix the flaky login test — review @@ -45,13 +45,13 @@ Redo and reject differ only in whether you accept the direction; both carry your ## When you reject -Your findings route back automatically, the work is redone, the reviewer re-runs, and the gate comes back to you as a fresh review. Every round is on the record in the item's file. **The loop caps at three:** on the third failure the call returns to a human instead of bouncing again. +Your findings route back automatically: the work is redone, the reviewer re-runs, and the gate returns as a fresh review. Every round is on the record in the item's file. **The loop caps at three:** on the third failed round the call returns to a human instead of bouncing again. ## The detached adversarial audit -For high-stakes surfaces, a passing validation is necessary but not sufficient. Before merging, the first officer also runs a read-only adversarial audit. The audit catches the hole that validation cannot see itself: a test that passes today but would also pass on a broken future edit. +For high-stakes surfaces, a passing validation is necessary but not sufficient. Before merging, the first officer also runs a read-only adversarial audit. The audit catches the hole validation cannot see on its own: a test that passes today but would also pass on a broken future edit. -A workflow names its own high-stakes surfaces; routine, low-blast-radius changes do not need an audit, a normal validation suffices. +A workflow names its own high-stakes surfaces. Routine, low-blast-radius changes do not need an audit; a normal validation suffices. The audit is read-only and cannot touch the deliverable. It tries to refute the validation: it constructs an adversarial edit that the deliverable's own tests should catch and confirms they do. A test that stays green under an edit that breaks the claim is a hole. "Refuted nothing material" is a valid recorded outcome. From c3aacf033b739b641f94755fbaf38f1403a91465 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 17:33:26 -0700 Subject: [PATCH 083/115] =?UTF-8?q?docs=20site:=20rejection=20bounces=20ar?= =?UTF-8?q?e=20automatic=20=E2=80=94=20gate=20reaches=20you=20on=20pass=20?= =?UTF-8?q?or=20after=20the=20cycle=20cap;=20add=20the=20send-it-back=20pr?= =?UTF-8?q?o=20tip?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/site/concepts/gates-and-decisions.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/site/concepts/gates-and-decisions.md b/docs/site/concepts/gates-and-decisions.md index fa6889ee..2fbcd7ba 100644 --- a/docs/site/concepts/gates-and-decisions.md +++ b/docs/site/concepts/gates-and-decisions.md @@ -43,9 +43,11 @@ Material findings are the ones that should move your vote; Polish never blocks. Redo and reject differ only in whether you accept the direction; both carry your concrete asks so the next worker has something to act on. Nothing closes without its verdict on the record. -## When you reject +## When work is rejected -Your findings route back automatically: the work is redone, the reviewer re-runs, and the gate returns as a fresh review. Every round is on the record in the item's file. **The loop caps at three:** on the third failed round the call returns to a human instead of bouncing again. +Rejections bounce automatically: the findings route back, the work is redone, and the reviewer re-runs, with no stop at your desk. The gate reaches you only when the work passes review, or after **three failed rounds**, when the call returns to a human instead of bouncing again. Every round is on the record in the item's file. + +A useful rejection to type at a gate: "send it back unless this now needs reframing". ## The detached adversarial audit From 1e068423ff48b1f29218ea767e0dddf189271895 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 17:34:46 -0700 Subject: [PATCH 084/115] docs site: Rejections heading; returns to you; semicolon instead of dash (comm-officer, triaged) --- docs/site/concepts/gates-and-decisions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/site/concepts/gates-and-decisions.md b/docs/site/concepts/gates-and-decisions.md index 2fbcd7ba..91e97fa3 100644 --- a/docs/site/concepts/gates-and-decisions.md +++ b/docs/site/concepts/gates-and-decisions.md @@ -43,9 +43,9 @@ Material findings are the ones that should move your vote; Polish never blocks. Redo and reject differ only in whether you accept the direction; both carry your concrete asks so the next worker has something to act on. Nothing closes without its verdict on the record. -## When work is rejected +## Rejections -Rejections bounce automatically: the findings route back, the work is redone, and the reviewer re-runs, with no stop at your desk. The gate reaches you only when the work passes review, or after **three failed rounds**, when the call returns to a human instead of bouncing again. Every round is on the record in the item's file. +Rejections bounce automatically: the findings route back, the work is redone, and the reviewer re-runs; no stop at your desk. The gate reaches you only when the work passes review, or after **three failed rounds**, when the call returns to you instead of bouncing again. Every round is on the record in the item's file. A useful rejection to type at a gate: "send it back unless this now needs reframing". From e67278a29989ee2310fee05505a13f27eac960c3 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 17:37:30 -0700 Subject: [PATCH 085/115] docs site: audit section answers how it differs from validation; lens-specific reviews as the flexible layer --- docs/site/concepts/gates-and-decisions.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/docs/site/concepts/gates-and-decisions.md b/docs/site/concepts/gates-and-decisions.md index 91e97fa3..3fe426f1 100644 --- a/docs/site/concepts/gates-and-decisions.md +++ b/docs/site/concepts/gates-and-decisions.md @@ -49,15 +49,13 @@ Rejections bounce automatically: the findings route back, the work is redone, an A useful rejection to type at a gate: "send it back unless this now needs reframing". -## The detached adversarial audit +## Reviews beyond validation -For high-stakes surfaces, a passing validation is necessary but not sufficient. Before merging, the first officer also runs a read-only adversarial audit. The audit catches the hole validation cannot see on its own: a test that passes today but would also pass on a broken future edit. +A typical validation stage already covers code review: the work is checked against your acceptance criteria, with the rejection loop above behind it. For most changes, that is enough. -A workflow names its own high-stakes surfaces. Routine, low-blast-radius changes do not need an audit; a normal validation suffices. +The workflow is flexible, so you can add conditional, lens-specific reviews on top. If a change affects end users, check that the documentation was updated; if it touches a high-stakes surface, run an adversarial audit before merging. -The audit is read-only and cannot touch the deliverable. It tries to refute the validation: it constructs an adversarial edit that the deliverable's own tests should catch and confirms they do. A test that stays green under an edit that breaks the claim is a hole. "Refuted nothing material" is a valid recorded outcome. - -Material findings route back through the normal feedback flow, and the gate is not presented as clean until they are closed. A clean audit is noted in the review. +The audit differs from validation in what it distrusts: validation checks the work; the audit checks the validation. It is read-only, and it tries to refute the result: it constructs an adversarial edit the deliverable's own tests should catch, and confirms they do. A test that stays green under an edit that breaks the claim is a hole validation cannot see on its own. "Refuted nothing material" is a valid recorded outcome, and material findings route back through the rejection loop. ## Where to go next From 7065d44411fff3809dfd34ed06ac47b40b05d62c Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 17:38:55 -0700 Subject: [PATCH 086/115] docs site: adversarial review is built in (in-stage or detached); lens-specific reviews are the add-on --- docs/site/concepts/gates-and-decisions.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/site/concepts/gates-and-decisions.md b/docs/site/concepts/gates-and-decisions.md index 3fe426f1..8eef9705 100644 --- a/docs/site/concepts/gates-and-decisions.md +++ b/docs/site/concepts/gates-and-decisions.md @@ -51,11 +51,11 @@ A useful rejection to type at a gate: "send it back unless this now needs refram ## Reviews beyond validation -A typical validation stage already covers code review: the work is checked against your acceptance criteria, with the rejection loop above behind it. For most changes, that is enough. +A typical validation stage already covers code review: the work is checked against your acceptance criteria, with the rejection loop above behind it. Adversarial review is built in as well; it can run inside the validation stage, or as a detached, out-of-workflow pass for high-stakes changes. -The workflow is flexible, so you can add conditional, lens-specific reviews on top. If a change affects end users, check that the documentation was updated; if it touches a high-stakes surface, run an adversarial audit before merging. +Adversarial review differs from validation in what it distrusts: validation checks the work; the adversarial pass checks the validation. It is read-only, and it tries to refute the result: it constructs an adversarial edit the deliverable's own tests should catch, and confirms they do. A test that stays green under an edit that breaks the claim is a hole validation cannot see on its own. "Refuted nothing material" is a valid recorded outcome, and material findings route back through the rejection loop. -The audit differs from validation in what it distrusts: validation checks the work; the audit checks the validation. It is read-only, and it tries to refute the result: it constructs an adversarial edit the deliverable's own tests should catch, and confirms they do. A test that stays green under an edit that breaks the claim is a hole validation cannot see on its own. "Refuted nothing material" is a valid recorded outcome, and material findings route back through the rejection loop. +The workflow is flexible beyond that: you can add conditional, lens-specific reviews of your own, like checking that the documentation was updated when a change affects end users. ## Where to go next From 89a165147da7eb56df8c63685245d18d052d3d8d Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 17:39:39 -0700 Subject: [PATCH 087/115] docs site: gates audit paragraph polish (comm-officer, 2 of 4 accepted against current text) --- docs/site/concepts/gates-and-decisions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/site/concepts/gates-and-decisions.md b/docs/site/concepts/gates-and-decisions.md index 8eef9705..567d6a50 100644 --- a/docs/site/concepts/gates-and-decisions.md +++ b/docs/site/concepts/gates-and-decisions.md @@ -51,9 +51,9 @@ A useful rejection to type at a gate: "send it back unless this now needs refram ## Reviews beyond validation -A typical validation stage already covers code review: the work is checked against your acceptance criteria, with the rejection loop above behind it. Adversarial review is built in as well; it can run inside the validation stage, or as a detached, out-of-workflow pass for high-stakes changes. +A typical validation stage already covers code review: the work is checked against your acceptance criteria, with the rejection loop behind it. Adversarial review is built in as well; it can run inside the validation stage, or as a detached, out-of-workflow pass for high-stakes changes. -Adversarial review differs from validation in what it distrusts: validation checks the work; the adversarial pass checks the validation. It is read-only, and it tries to refute the result: it constructs an adversarial edit the deliverable's own tests should catch, and confirms they do. A test that stays green under an edit that breaks the claim is a hole validation cannot see on its own. "Refuted nothing material" is a valid recorded outcome, and material findings route back through the rejection loop. +Adversarial review differs from validation in what it distrusts: validation checks the work; the adversarial pass checks the validation. It is read-only and tries to refute the result by constructing an adversarial edit the deliverable's own tests should catch, then confirming they do. A test that stays green under an edit that breaks the claim is a hole validation cannot see on its own. "Refuted nothing material" is a valid recorded outcome, and material findings route back through the rejection loop. The workflow is flexible beyond that: you can add conditional, lens-specific reviews of your own, like checking that the documentation was updated when a change affects end users. From a38dd9750c05160b5ba210152ce4c92dcb5257f2 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 17:41:24 -0700 Subject: [PATCH 088/115] =?UTF-8?q?docs=20site:=20drop=20the=20worked-exam?= =?UTF-8?q?ple=20page=20=E2=80=94=20it=20mixed=20sprint=20machinery=20into?= =?UTF-8?q?=20concepts;=20examples=20will=20get=20another=20modality?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/site/concepts/gates-and-decisions.md | 1 - docs/site/concepts/worked-example.md | 106 ---------------------- docs/site/index.md | 2 +- mkdocs.yml | 1 - 4 files changed, 1 insertion(+), 109 deletions(-) delete mode 100644 docs/site/concepts/worked-example.md diff --git a/docs/site/concepts/gates-and-decisions.md b/docs/site/concepts/gates-and-decisions.md index 567d6a50..14ddd30a 100644 --- a/docs/site/concepts/gates-and-decisions.md +++ b/docs/site/concepts/gates-and-decisions.md @@ -59,5 +59,4 @@ The workflow is flexible beyond that: you can add conditional, lens-specific rev ## Where to go next -- [A worked example](worked-example.md) traces one real entity through every gate to a recorded verdict. - [Operating a workflow](../running-workflows/operating.md) covers answering gates in the day-to-day loop. diff --git a/docs/site/concepts/worked-example.md b/docs/site/concepts/worked-example.md deleted file mode 100644 index 7b08ee74..00000000 --- a/docs/site/concepts/worked-example.md +++ /dev/null @@ -1,106 +0,0 @@ -# A worked example - -One real entity, `z9` `codex-plugin-auto-install`, went from backlog through to -`done` / PASSED in the project repo, and its artifacts are on the record. Its -trail makes the abstract stage machine concrete: backlog → ideation → -implementation → validation → done, the gates between them, and what the captain -decides at each one. - -The workflow is `docs/dev` (the Spacedock v1 dev workflow); its stages, gates, -and entity schema are defined in -[the development workflow README](https://github.com/spacedock-dev/spacedock/blob/main/docs/dev/README.md). -Runtime entity state lives in a separate `.spacedock-state` checkout, so the -finished entity itself is not in the main tree. Its full trajectory is in the -`0198-pre-flip-hardening` sprint directory (a sprint groups work items driven -together to one deliverable): `index.md`, `dispatch-sprint-execution.md`, -`debrief.md`, and `post-sprint-audit.md`. - -`z9` delivered front-door Codex plugin auto-install: `spacedock codex` now -installs a missing plugin then launches, the Codex analog of the Claude path. It -shipped as [PR #329](https://github.com/spacedock-dev/spacedock/pull/329). - -## backlog → ideation: shape the work - -`z9` enters backlog as a seed: a title, a source, and a brief description of the -problem. It carries no design yet. Ideation is where a worker fleshes it out into -a problem statement, a proposed approach, entity-level acceptance criteria (ACs), -and a test plan, with each AC naming a check outside the entity body that can fail. - -For `z9` that meant a concrete approach: install through the shared `devBranch` -rather than a hardcoded `"next"`, so the install channel tracks the release -channel (`next` today, `main` after the flip). The design also resolved the -riskiest unknown up front (that the install branch was the channel variable, not -a literal) and recorded it before committing to the rest of the plan. - -Ideation ends at a **gate**. Because the dev workflow marks `ideation` with -`gate: true`, the first officer does not advance on its own: it presents the -design to the captain. The captain approved `z9`'s ideation on 2026-06-08. That -approval is the entry condition for implementation, and it is on the record, so -a later session proceeds without re-asking. - -## implementation: produce the deliverable - -Once the design is approved, `z9` moves to implementation. The dev workflow runs -this stage in a `worktree` (`worktree: true`), so the dispatched ensign works in -an isolated checkout, not the shared tree. - -The implementer was handed three build notes, verbatim from the sprint's -`dispatch-sprint-execution.md`: - -> Build notes: **(a)** the codex install branch MUST be the shared `devBranch` -> (`ops.Install("codex", marketplaceSource, devBranch)` + `--ref `), -> NOT a hardcoded `next` — so it tracks the channel … **(b)** **fix** the -> now-false comments/error-strings it builds around (`host_exec.go:271-273`, -> `:32-34`; `frontdoor.go:314-316`), don't add around them; **(c)** inverts -> `frontdoor_test.go:414`. - -The work honored all three: it installed on the shared `devBranch` so the -install channel tracks the flip, fixed the stale comments and error strings in -place, and inverted the obsolete test whose old assertion contradicted the new -auto-install behavior. - -Implementation is complete when the deliverable is committed and the stage report -is filed; it flows straight to `validation` dispatch. - -## validation: verify against the criteria - -`z9` moves to validation to be checked, not finished. The dev workflow marks -`validation` with `fresh: true` and `worktree: true`, so a fresh validator (one -that did not write the code) runs in its own worktree. It pulls every `AC-N` -from the entity's acceptance-criteria section, reproduces the evidence each one -cites, and produces a PASSED or REJECTED recommendation. - -`z9` is a front-door change, a high-stakes surface, so validation alone was not -sufficient. The dev workflow requires a **detached adversarial audit** for the -launcher front door: a read-only pass that tries to refute the validation. The -`z9` audit ran at commit `0b714fac`, exercised five probes (each proving the -tests would catch a break), and refuted nothing material. That clean audit -satisfied the sprint's definition-of-done for the high-stakes surface. - -Validation also has `gate: true` and `feedback-to: implementation`. A REJECTED -recommendation routes the finding back to implementation for another cycle; a -PASSED recommendation goes to the captain for the terminal decision. - -## done: the captain's verdict - -`z9` reaches `done` when the captain reads the validation report and approves. -The terminal stage records the outcome in frontmatter: `status: done`, -`verdict: PASSED`, and a `completed` timestamp. The sprint's -`post-sprint-audit.md` confirms it in one line, `z9` alongside its three siblings: - -> kb / qa / z9 / vh entities are all `status: done`, `verdict: PASSED`, archived, -> with PR refs #327 / #328 / #329 / #330. - -That is the whole point of the machine: nothing reached `done` on assertion -alone. `z9` advanced only on an approved design, an isolated implementation, a -fresh validation, a detached audit that failed to break it, and an explicit -captain verdict. Each one a decision, each one on the record. - -## Read the trail yourself - -The full trajectory is reconstructable from the sprint directory: - -- [`index.md`](https://github.com/spacedock-dev/spacedock/blob/main/docs/roadmap/0198-pre-flip-hardening/index.md): goal, members, definition of done, the approved-gate note. -- [`dispatch-sprint-execution.md`](https://github.com/spacedock-dev/spacedock/blob/main/docs/roadmap/0198-pre-flip-hardening/dispatch-sprint-execution.md): the per-member drive plan and `z9`'s build notes. -- [`debrief.md`](https://github.com/spacedock-dev/spacedock/blob/main/docs/roadmap/0198-pre-flip-hardening/debrief.md): what shipped, the PR links, and the decisions made along the way. -- [`post-sprint-audit.md`](https://github.com/spacedock-dev/spacedock/blob/main/docs/roadmap/0198-pre-flip-hardening/post-sprint-audit.md): the final-state confirmation and the detached-audit record. diff --git a/docs/site/index.md b/docs/site/index.md index 80b2fb13..7b79859f 100644 --- a/docs/site/index.md +++ b/docs/site/index.md @@ -17,7 +17,7 @@ You are the captain. You set the bar and make the calls; the agents do the rest. ## Where to go next - **[Get started](get-started/install.md)**: [install](get-started/install.md) Spacedock, then pick an entry. [Survey an existing project](get-started/survey.md) to see where your agents burn your time and surface the workflow you are already running without naming it. Or [start a fresh workflow](get-started/first-workflow.md) from a common shape like development or research. -- **[Concepts](concepts/operating-model.md)** covers the operating model, workflows and entities, the stage lifecycle, gates and decisions, and a worked example. +- **[Concepts](concepts/operating-model.md)** covers the operating model, workflows and entities, the stage lifecycle, and gates and decisions. - **[Running workflows](running-workflows/commission.md)** walks through commissioning a workflow, operating a running workflow, and debriefing and refitting between sessions. ## For agents using Spacedock diff --git a/mkdocs.yml b/mkdocs.yml index 406777ec..157603b6 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -77,7 +77,6 @@ nav: - Workflows & entities: concepts/workflows-and-entities.md - The stage lifecycle: concepts/stage-lifecycle.md - Gates & decisions: concepts/gates-and-decisions.md - - A worked example: concepts/worked-example.md - Running workflows: - Commission a workflow: running-workflows/commission.md - Operating a workflow: running-workflows/operating.md From 2ab605a739d1762ba5e0557344e1514477c58dce Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 17:42:15 -0700 Subject: [PATCH 089/115] docs site: stage-lifecycle notes built-in adversarial review beside the fresh-context mechanism --- docs/site/concepts/stage-lifecycle.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/site/concepts/stage-lifecycle.md b/docs/site/concepts/stage-lifecycle.md index d4b97f4d..e8f16cd8 100644 --- a/docs/site/concepts/stage-lifecycle.md +++ b/docs/site/concepts/stage-lifecycle.md @@ -26,6 +26,8 @@ Beyond the declarations, the prose of each stage's section in the README is the Validation declares `fresh: true` because the reviewer must not be the maker. The validator arrives without the implementer's reasoning in its context, sees only the entity body and the deliverable, and pushes back on thin evidence. This is the mechanism behind the README's claim that "the agent doesn't get to judge its own work." +Adversarial review is built in as well, inside the validation stage or as a detached pass for high-stakes changes. [Reviews beyond validation](gates-and-decisions.md#reviews-beyond-validation) covers how it differs. + When validation recommends `REJECTED`, `feedback-to: implementation` routes the concrete finding back to the implementation stage for rework rather than closing the entity. The entity re-enters implementation, the finding is addressed, and a fresh validator checks it again. A hard cap on feedback cycles prevents an endless bounce; on the third cycle the first officer escalates to you. ## Isolated worktrees From 8fb95b27643b4c75d5ed3a5375ad035807907138 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 17:44:27 -0700 Subject: [PATCH 090/115] docs site: codify round-three lessons and the per-paragraph revision loop --- docs/site/AGENTS.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/site/AGENTS.md b/docs/site/AGENTS.md index 965b8050..8d9046fa 100644 --- a/docs/site/AGENTS.md +++ b/docs/site/AGENTS.md @@ -22,6 +22,12 @@ Spacedock is not complicated; wordy docs make it *feel* complicated. Every edit - **A real example with sample output beats description.** One concrete command plus the output the reader will see teaches faster than paragraphs. Compose samples from the product's real templates, and never restate in prose what the sample already says ("Accept this design, or tell me what to change" makes a "nothing is generated until you accept" sentence dead weight). - **Keep agent-facing surfaces off user pages.** Commands meant for the agents (`spacedock status`, `spacedock dispatch`) are not taught in Get started, even though their output is real. - **The docs may defer to the agent.** Spacedock runs inside a coding agent; "ask the agent if anything is unclear" is a legitimate close. Pages cover what the reader needs before and between sessions, not every contingency within one. +- **The agent is the interface; docs say what is possible.** Files and settings are operated by asking the first officer, not by hand-editing walkthroughs. Describe capabilities ("a stage can pause at a gate, run isolated, demand a fresh reviewer… ask the first officer to set up or change any of it"), never a field-by-field table of how to key them in. +- **A diagram beats an enumeration for structure.** A stage chain is a mermaid flowchart, not five field-by-field bullets. Carry the meaning in a plain-text caption sentence as well, so the styling is decoration and text readers (`llms.txt`) lose nothing. +- **State behavior; don't narrate rationale.** "When a stage declares `worktree: true`, everything from that stage onward happens in an isolated worktree" — not the tradeoff that motivated the design. The reader wants what happens, not why we built it that way. +- **Built-in capabilities must read as built in.** Never introduce a built-in mechanism inside a "you can add…" list; the reader hears setup required. Built-ins first, stated as facts; add-ons after, clearly labeled as the flexible layer. +- **Verify behavior claims against the owning source.** Before documenting what the product does, read the skill or code that owns the behavior (rejection rounds auto-bounce; the gate reaches the captain on pass or at the cycle cap). A plausible paraphrase from memory is how docs go wrong. +- **No archaeology pages.** An example lives as a sample at the point of need (a design summary on the commission page, a gate review on the gates page), not as a trace page that walks one real artifact through every mechanism at once. - **Cut, don't pad.** If a sentence still carries its meaning with a clause removed, remove the clause. If a paragraph repeats the page above it, delete it and link instead. - **Don't repeat content across pages.** One page owns each idea; others link to it. Duplicated explanation is the main thing that makes the docs feel long. An audience split ("new-user view" vs "operator view" of the same feature) is not a reason for a second page; it is the same topic. - **Two levels of structure only:** section → page. No deeper nesting; no page that exists only to hold sub-pages. @@ -116,6 +122,16 @@ Rule of thumb: capitalize a **role** when you name it as a role (the roles table - **Links.** Descriptive link text, never "click here" / "this link". Internal links are relative so `mkdocs build --strict` can resolve them. GitHub links and install commands point at `main`, never a development branch. - **Lists and emphasis.** Bullets for parallel items; bold for the load-bearing claim of a bullet (the README pattern). Use emphasis sparingly; if everything is bold, nothing is. +## Revising a page: the per-paragraph loop + +Revision is paragraph by paragraph, not page-at-a-glance. For each paragraph ask three questions: + +1. **Why would the reader care?** If the paragraph has no answer, cut it. +2. **Do they have the context, at this point in the journey?** Every term and claim must be introduced by this page or an earlier one in nav order. +3. **Does it make them want to read on?** End on the payoff or the concrete thing they can type, not on a caveat. + +Propose the revision yourself, then send the proposal (with its three-question rationale) to the prose-polish teammate when one is standing. Triage the return; never auto-apply: accept real improvements, reject anything that violates this directive (em-dash insertions are the recurring offender) or alters captain-set wording, and re-check the file on disk before acting on replies that arrive late. + ## Before you commit a docs change - [ ] Page opens with the problem/payoff, not a definition. - [ ] Introduces only the terms this page actually needs; each defined on first use. From dbe59a0543f7df38597935ac59cadeb86f33aa26 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 17:46:48 -0700 Subject: [PATCH 091/115] =?UTF-8?q?docs=20site:=20fresh:=20true=20means=20?= =?UTF-8?q?adversarial=20review=20=E2=80=94=20both=20concept=20pages=20sta?= =?UTF-8?q?te=20the=20equivalence?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/site/concepts/gates-and-decisions.md | 2 +- docs/site/concepts/stage-lifecycle.md | 4 +--- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/site/concepts/gates-and-decisions.md b/docs/site/concepts/gates-and-decisions.md index 14ddd30a..8d7f321c 100644 --- a/docs/site/concepts/gates-and-decisions.md +++ b/docs/site/concepts/gates-and-decisions.md @@ -51,7 +51,7 @@ A useful rejection to type at a gate: "send it back unless this now needs refram ## Reviews beyond validation -A typical validation stage already covers code review: the work is checked against your acceptance criteria, with the rejection loop behind it. Adversarial review is built in as well; it can run inside the validation stage, or as a detached, out-of-workflow pass for high-stakes changes. +A typical validation stage already covers code review: the work is checked against your acceptance criteria, with the rejection loop behind it. Adversarial review is built in as well: a `fresh: true` validation stage is exactly that, and high-stakes changes can also get a detached, out-of-workflow pass. Adversarial review differs from validation in what it distrusts: validation checks the work; the adversarial pass checks the validation. It is read-only and tries to refute the result by constructing an adversarial edit the deliverable's own tests should catch, then confirming they do. A test that stays green under an edit that breaks the claim is a hole validation cannot see on its own. "Refuted nothing material" is a valid recorded outcome, and material findings route back through the rejection loop. diff --git a/docs/site/concepts/stage-lifecycle.md b/docs/site/concepts/stage-lifecycle.md index e8f16cd8..e8106f96 100644 --- a/docs/site/concepts/stage-lifecycle.md +++ b/docs/site/concepts/stage-lifecycle.md @@ -24,9 +24,7 @@ Beyond the declarations, the prose of each stage's section in the README is the ## Fresh context at validation -Validation declares `fresh: true` because the reviewer must not be the maker. The validator arrives without the implementer's reasoning in its context, sees only the entity body and the deliverable, and pushes back on thin evidence. This is the mechanism behind the README's claim that "the agent doesn't get to judge its own work." - -Adversarial review is built in as well, inside the validation stage or as a detached pass for high-stakes changes. [Reviews beyond validation](gates-and-decisions.md#reviews-beyond-validation) covers how it differs. +Validation declares `fresh: true`, and `fresh: true` means adversarial review: the reviewer is never the maker, arrives without the implementer's reasoning in its context, sees only the entity body and the deliverable, and pushes back on thin evidence. This is the mechanism behind the README's claim that "the agent doesn't get to judge its own work." High-stakes changes can also get a detached, out-of-workflow pass; [Reviews beyond validation](gates-and-decisions.md#reviews-beyond-validation) covers the difference. When validation recommends `REJECTED`, `feedback-to: implementation` routes the concrete finding back to the implementation stage for rework rather than closing the entity. The entity re-enters implementation, the finding is addressed, and a fresh validator checks it again. A hard cap on feedback cycles prevents an endless bounce; on the third cycle the first officer escalates to you. From b27edcb2994774423bcfccac634568d86be55728 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 17:52:11 -0700 Subject: [PATCH 092/115] =?UTF-8?q?docs=20site:=20recast=20operating.md=20?= =?UTF-8?q?as=20touchpoints=20=E2=80=94=20the=20agent=20is=20the=20interfa?= =?UTF-8?q?ce,=20status=20flags=20off=20the=20user=20page?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/site/running-workflows/operating.md | 62 +++++------------------- 1 file changed, 13 insertions(+), 49 deletions(-) diff --git a/docs/site/running-workflows/operating.md b/docs/site/running-workflows/operating.md index 9d184261..e1db90c9 100644 --- a/docs/site/running-workflows/operating.md +++ b/docs/site/running-workflows/operating.md @@ -1,65 +1,29 @@ # Operating a workflow -Operating a workflow is a loop: see what is ready, dispatch the first officer to move it, and make a decision when work reaches a gate. The captain drives that loop; the first officer does the orchestration and the ensigns do the stage work. +You operate a workflow by talking to the first officer: launch a session, let it move everything that is ready, and decide when work reaches a gate. -## The day-to-day loop +## The session loop -You run the same three steps each session: - -1. **See what is ready.** Query workflow state to find the entities that can move (the dispatchable set) and where everything sits. -2. **Dispatch the first officer.** Launch a session and let it pull a dispatchable entity through its next stage. -3. **Handle gates.** When a stage is gated, the first officer stops and presents the result. You approve, reject, or send it back. - -The loop ends a session when nothing is dispatchable, or when every dispatchable entity is waiting on a gate decision from you. - -## See what is ready - -`spacedock status` reads the workflow state and prints it. Run it against the workflow directory, the one holding the commissioned `README.md`: +Start a session. Name a task if you have one in mind, or say nothing and it picks up where the last session left off: ```bash -spacedock status --workflow-dir docs/dev +spacedock claude ``` -Prints the status table: one row per active entity, with its ID, title, and current stage. This is the full picture. - -To list only the entities ready to dispatch, add `--next`: +The first officer reads the workflow state and dispatches an ensign for every entity ready for its next stage. Completed stages flow forward on their own: when the next stage has no gate, the first officer advances the entity and dispatches again without waiting for you. It returns to you for four things only: a gate needs your decision, a finished entity is ready to close, something is blocked, or nothing is left to dispatch. -```bash -spacedock status --workflow-dir docs/dev --next -``` - -Prints the dispatchable set: the entities whose next stage can run now, given concurrency limits and what is already in flight. This is the query the first officer runs each loop. When nothing is ready, the result is empty; there is nothing to dispatch. +In between, ask it whatever you want to know: "what's ready?", "where is the rate-limiting task?", "what's still in review?". The first officer queries the workflow state and shows you; there are no status commands to learn. -To filter the table by a frontmatter field, use `--where "field=value"`. The filter takes `=` (equals) or `!=` (not equals): +## When a gate arrives -```bash -spacedock status --workflow-dir docs/dev --where "status=ideation" -spacedock status --workflow-dir docs/dev --where "verdict!=" -``` - -The first prints every entity in the `ideation` stage. The second prints entities whose `verdict` field is set (the `!=` against an empty value). Use `--where` to answer targeted questions: what is in a given stage, which entities carry an external `issue`, which already have a `verdict`. - -Two more queries are worth knowing: - -- **`--validate`** checks every entity against the workflow's contract and reports problems (a missing or malformed ID, a duplicate ID, a stage name that breaks the naming rule). Run it when the table looks wrong. -- **`--resolve REF`** looks up one entity by slug, full ID, or ID prefix, so you can name it unambiguously before acting on it. - -All status queries are read-only. They print state, they do not change it. For the full flag list and the `--set` and `--archive` mutation forms, see the [Command reference](../reference/command-reference.md). - -## Dispatch - -Hand the first officer the workflow and let it run the dispatch cycle. Launch with your harness subcommand and a task that names the work; the first officer takes the workflow directory from the path you give it in the task, or runs `spacedock status --discover` to find it: - -```bash -spacedock claude "/spacedock:first-officer operate the workflow in docs/dev" -``` +A gate stops the loop and hands you the call: the first officer presents the review and waits. You make one of [the three calls](../concepts/gates-and-decisions.md#the-three-calls): approve, redo with feedback, or reject. -The first officer reads the workflow `README.md`, runs its own `status --next`, and for each dispatchable entity it dispatches an ensign to move the entity through its next stage. The ensign does the stage work (write the design, produce the deliverable, run the validation), commits, and files a stage report. The first officer reads the report, checks it against the stage's outputs and the entity's acceptance criteria, and advances the entity. A completed non-gated, non-terminal stage flows forward: the first officer advances it and dispatches the next stage on its own, without waiting for you. +Approving the last stage closes the entity: the first officer records the merge and the verdict, archives the entity file, removes the worktree, and stands the workers down. The loop then continues with whatever is ready next. -It stops and returns to you only at a gate, at a terminal entity's merge ceremony, on a blocker, or when nothing is left to dispatch. +## Delegating the loop -## Handle gate decisions +The loop needs you less as the workflow matures. Rejections already run without you: findings bounce back to the stage that owns the fix and the reviewer re-runs; [a rejection reaches your desk](../concepts/gates-and-decisions.md#rejections) only after three failed rounds. When the bar you set is sharp enough to trust, [hand over the conn](../concepts/gates-and-decisions.md) and let the first officer drive whole tasks to done with auto-approval. -A gate stops the loop and hands you the call: the first officer presents the stage report and its review, then waits. It never self-approves. You make one of three calls: **approve**, **redo with feedback**, or **reject**. [The three calls](../concepts/gates-and-decisions.md#the-three-calls) covers what each one does, what the gate report carries, and the feedback-cycle cap. +## Ending a session -When you approve a terminal stage, the entity is closed: the first officer records the merge, sets the `completed` timestamp and `verdict`, clears the worktree, and tears the worker down. At that point the loop returns to the top: run `status --next` and see what moved into reach. +Stop whenever you want; every entity's state is in the workflow files, so the next session resumes where this one ended. Before you stop, run [`/spacedock:debrief`](debrief-and-refit.md) to record the session for the next one. From e787c63a933fb8452f5d25562725aa1dfe1bd38e Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 17:54:27 -0700 Subject: [PATCH 093/115] =?UTF-8?q?docs=20site:=20commission.md=20deduped?= =?UTF-8?q?=20against=20first-workflow=20=E2=80=94=20capabilities=20over?= =?UTF-8?q?=20field=20mechanics,=20FO=20internals=20off=20the=20page?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/site/running-workflows/commission.md | 51 +++++++---------------- 1 file changed, 15 insertions(+), 36 deletions(-) diff --git a/docs/site/running-workflows/commission.md b/docs/site/running-workflows/commission.md index 63d9c9e6..c53a28e2 100644 --- a/docs/site/running-workflows/commission.md +++ b/docs/site/running-workflows/commission.md @@ -1,6 +1,6 @@ # Commission a workflow -`/spacedock:commission` turns a description of the work you want tracked into a runnable workflow: a directory of markdown entities, a README that is the workflow's living spec, and a first officer ready to dispatch an ensign for each seed entity. You answer a short interactive design pass; the skill generates the files and launches a pilot run as the first officer. +`/spacedock:commission` turns a description of the work you want tracked into a runnable workflow. You make four design decisions in conversation; the skill derives the rest, presents the full design, and writes nothing until you accept. [Your first workflow](../get-started/first-workflow.md) shows the whole flow, including the design summary and pilot run you will see. Invoke it from a session started with `spacedock claude`. You can pass the mission inline: @@ -8,54 +8,33 @@ Invoke it from a session started with `spacedock claude`. You can pass the missi /spacedock:commission product idea to simulated customer interview ``` -Text after the command name is taken as the workflow mission and presented for confirmation rather than asked from scratch. With no argument, the skill greets you and asks. +Text after the command name becomes the workflow mission, presented for confirmation rather than asked from scratch. With no argument, the skill greets you and asks. -## The four things you name +## The four things you decide -The design pass collects four decisions. The skill derives everything else (the directory path, the entity identity scheme, the rejection routing) from these and shows the full design for your confirmation before writing any file. +1. **The mission and what each work item is.** What the workflow is for, and what one entity represents. The description you give becomes the label the workflow uses everywhere it talks about your work: "a design idea" makes it a workflow of ideas. -1. **The mission and what each entity is.** The first question asks what the workflow is for and what each work item represents. From the entity description the skill derives the entity label used throughout the generated files: "a design idea" becomes label `idea`, plural `ideas`, type `design_idea`. An entity is one work item, a markdown file that moves through the stages. +2. **The stages.** The skill detects the workflow's shape from your mission (shipping code, testing a hypothesis, or iterating on an artifact) and proposes a stage list for you to confirm, modify, add to, or trim. It pushes back on redundant names: `awaiting_validation` reads as "the entity is in awaiting_validation," so it suggests `validation` instead. -2. **The stages.** The skill detects the workflow's shape from your mission (shipping code, testing a hypothesis, or iterating on an artifact) and proposes a stage list for you to confirm, modify, add to, or trim. Stage names describe the bucket an entity is sitting in: activity-flavored (`implementation`, `review`, `validation`) or state-flavored (`proposed`, `published`, `accepted`). The skill pushes back on redundant names: `awaiting_validation` reads as "the entity is in awaiting_validation," so it suggests `validation` instead. `done` is the universal terminal and stays as-is. +3. **The gated stages.** A gate is a stage where the workflow pauses for your decision before an entity advances. By default one gate sits before the terminal stage, and each gate gets a rejection target, the earlier stage work bounces back to when you reject. Both appear in the design summary in plain language ("If you reject at `review`, it goes back to `draft` for revision"). -3. **The gated stages.** A gate is a stage where the workflow pauses for your decision before an entity advances. By default the skill places one gate before the terminal stage. For each gate it also derives a rejection flow, the earlier stage an entity bounces back to when you reject, defaulting to the stage immediately before the gate. You confirm both in the design summary, stated in plain language ("If you reject at `review`, it goes back to `draft` for revision"). +4. **The per-stage quality bar.** Each stage in the generated README tells a dispatched ensign what "good" means there: what to produce, the quality bar to meet, the anti-patterns to avoid. The skill drafts these from the mission, but they are starting prose, not commitments. -4. **The per-stage rules.** Each stage in the generated README carries three bullets that tell a dispatched ensign what "good" means for that stage: **`Outputs`** (what the worker produces), **`Good`** (your quality bar), and **`Bad`** (anti-patterns to avoid). The skill drafts these from the mission, but they are starting prose, not commitments. They are the rules every dispatched agent works from. - -You also choose the entity ID style: `sd-b32` (recommended when multiple people or agents create entities across branches or worktrees), `sequential` (single-writer or numeric-continuity workflows), or `slug` (the filename is the identity). See the [frontmatter contract](../reference/frontmatter-contract.md) for what each style stores. +Everything else is derived or asked with a recommendation attached: where the files go, how entities are identified, how rejections route. The design summary shows it all; ask for the tradeoffs on any of it before you accept. ## What gets generated -After you accept the design, the skill writes everything into `docs/{mission-slug}/`: - -- `README.md`: the mission, the schema, a per-stage section for every stage (with the `Outputs` / `Good` / `Bad` bullets), and a copy-paste entity template. -- One file per seed entity at `docs/{mission-slug}/{slug}.md`, each with valid YAML frontmatter and the description you gave. -- `_mods/pr-merge.md`, generated only when a stage modifies the repo (a worktree stage) and you accept the `pr-merge` mod, which tracks PR state on the entity's `pr` field instead of modeling merge as its own stage. - -If any stage writes code or produces artifacts beyond the entity file, that stage is marked `worktree: true` so each entity gets an isolated branch and the main checkout stays clean. +After you accept, everything lands in `docs/{mission-slug}/` as plain text: the README that is the workflow's living spec, and one file per seed entity. A stage that writes code or produces artifacts runs each entity on an isolated branch, so your main checkout stays clean; if you ship through PR review, the skill also offers the [pr-merge mod](../advanced/mods-and-standing-teammates.md), which manages the PR lifecycle so merging never needs to be a stage. ## Tighten the README before the first dispatch -The README is the workflow's living spec. Before launching, the skill reminds you that the auto-generated per-stage bullets are best-guesses and prompts you to tighten them. You have two ways to do it: - -- Open `docs/{mission-slug}/README.md` and edit the bullets under each `### {stage}` heading directly. -- Type `review stages` to have the skill walk you through each stage one at a time, flag the bullets that read as generic, and apply your amendments inline. - -Editing here costs minutes; un-editing after agents have been dispatched against vague bullets costs more. +The README is the workflow's living spec. Before launching, the skill reminds you that the auto-generated per-stage rules are best-guesses and prompts you to tighten them. You have two ways to do it: -## What the first officer does next +- Open `docs/{mission-slug}/README.md` and edit the bullets under each stage heading directly. +- Type `review stages` to have the skill walk you through each stage one at a time, flag the rules that read as generic, and apply your amendments inline. -Commission generates the files, then assumes the first-officer role itself to run the pilot; no separate launch step is needed. +Editing here costs minutes; un-editing after agents have been dispatched against vague rules costs more. -1. It loads the [first officer's operating contract](../concepts/operating-model.md) and reads the workflow README you just generated. -2. It runs `spacedock status --boot` to read the workflow's current state. -3. It probes for the team-mode tools and dispatches an ensign for each seed entity that is ready to advance, processing them through the stages. -4. When the workflow goes idle or reaches a gate, it reports the pilot results: which entities moved, which stages they passed through, and any gate waiting on your decision. - -To run the workflow in any later session, launch the first officer again: - -``` -spacedock claude -``` +## The pilot run and after -It reads the workflow state, picks up where the last session left off, and dispatches agents for any entity ready for its next stage. [Operating a workflow](operating.md) covers the day-to-day loop: seeing what is ready, dispatching, and handling gate decisions. +On accept, commission takes the first-officer role itself and runs the pilot: it dispatches your seed entities and reports back when the workflow goes idle or a gate is waiting on your decision. In every later session, `spacedock claude` picks up where the last one left off; [Operating a workflow](operating.md) covers that loop. From 3a62ec23fa114255e933ee9e23decdd503e2af2c Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 17:55:31 -0700 Subject: [PATCH 094/115] =?UTF-8?q?docs=20site:=20frontmatter-contract=20?= =?UTF-8?q?=E2=80=94=20replace=20dead=20entity-frontmatter=20anchor=20with?= =?UTF-8?q?=20the=20inline=20parser=20fact?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/site/reference/frontmatter-contract.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/site/reference/frontmatter-contract.md b/docs/site/reference/frontmatter-contract.md index 2dd7b111..03e7ae8f 100644 --- a/docs/site/reference/frontmatter-contract.md +++ b/docs/site/reference/frontmatter-contract.md @@ -2,7 +2,7 @@ Every entity is a markdown file (or a folder with an `index.md`) whose YAML frontmatter carries the fields Spacedock reads to track and move it. This page is a quick lookup for the fields a development-workflow entity uses. The always-current schema is owned by the [development workflow README](https://github.com/spacedock-dev/spacedock/blob/main/docs/dev/README.md#field-reference); when this table and that README disagree, the README wins. -Keep fields flat and top-level; add more flat custom fields rather than nested YAML. (The [entity frontmatter concept](../concepts/workflows-and-entities.md#entity-frontmatter) explains why the line-oriented parser requires this.) +Keep fields flat and top-level; add more flat custom fields rather than nested YAML. Spacedock reads frontmatter line by line, so nested values are ignored. ## Entity fields From 94ac20e4fd20f2b0c4a2d06571d1d7c490a671c5 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 18:08:12 -0700 Subject: [PATCH 095/115] =?UTF-8?q?docs=20site:=20commission.md=20?= =?UTF-8?q?=E2=80=94=20payoff=20lede,=20commission=20as=20actor,=20generat?= =?UTF-8?q?ed/tighten=20content=20deferred=20to=20concepts=20and=20first-w?= =?UTF-8?q?orkflow?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/site/running-workflows/commission.md | 30 +++++++++-------------- 1 file changed, 12 insertions(+), 18 deletions(-) diff --git a/docs/site/running-workflows/commission.md b/docs/site/running-workflows/commission.md index c53a28e2..1273daab 100644 --- a/docs/site/running-workflows/commission.md +++ b/docs/site/running-workflows/commission.md @@ -1,6 +1,6 @@ # Commission a workflow -`/spacedock:commission` turns a description of the work you want tracked into a runnable workflow. You make four design decisions in conversation; the skill derives the rest, presents the full design, and writes nothing until you accept. [Your first workflow](../get-started/first-workflow.md) shows the whole flow, including the design summary and pilot run you will see. +A workflow is designed in conversation: you make four decisions, commission derives the rest, and nothing is written until you accept the presented design. [Your first workflow](../get-started/first-workflow.md) shows the whole flow, including the design summary and pilot run. Invoke it from a session started with `spacedock claude`. You can pass the mission inline: @@ -8,33 +8,27 @@ Invoke it from a session started with `spacedock claude`. You can pass the missi /spacedock:commission product idea to simulated customer interview ``` -Text after the command name becomes the workflow mission, presented for confirmation rather than asked from scratch. With no argument, the skill greets you and asks. +Text after the command name becomes the workflow mission; with no argument, commission greets you and asks. ## The four things you decide 1. **The mission and what each work item is.** What the workflow is for, and what one entity represents. The description you give becomes the label the workflow uses everywhere it talks about your work: "a design idea" makes it a workflow of ideas. -2. **The stages.** The skill detects the workflow's shape from your mission (shipping code, testing a hypothesis, or iterating on an artifact) and proposes a stage list for you to confirm, modify, add to, or trim. It pushes back on redundant names: `awaiting_validation` reads as "the entity is in awaiting_validation," so it suggests `validation` instead. +2. **The stages.** Commission detects the workflow's shape from your mission (shipping code, testing a hypothesis, or iterating on an artifact) and proposes a stage list for you to confirm, modify, add to, or trim. It pushes back on redundant names: `awaiting_validation` reads as "the entity is in awaiting_validation," so it suggests `validation` instead. -3. **The gated stages.** A gate is a stage where the workflow pauses for your decision before an entity advances. By default one gate sits before the terminal stage, and each gate gets a rejection target, the earlier stage work bounces back to when you reject. Both appear in the design summary in plain language ("If you reject at `review`, it goes back to `draft` for revision"). +3. **The gated stages.** Which stages pause for your decision. By default one gate sits before the terminal stage, and each gate gets a rejection target: the earlier stage work bounces back to when you reject. Both appear in the design summary in plain language ("If you reject at `review`, it goes back to `draft` for revision"). -4. **The per-stage quality bar.** Each stage in the generated README tells a dispatched ensign what "good" means there: what to produce, the quality bar to meet, the anti-patterns to avoid. The skill drafts these from the mission, but they are starting prose, not commitments. +4. **The per-stage quality bar.** Each stage in the generated README tells a dispatched ensign what "good" means there: what to produce, the quality bar to meet, the anti-patterns to avoid. Commission drafts these from the mission, but they are starting prose, not commitments. -Everything else is derived or asked with a recommendation attached: where the files go, how entities are identified, how rejections route. The design summary shows it all; ask for the tradeoffs on any of it before you accept. +Everything else is derived or asked with a recommendation attached: the directory under `docs/` where everything lands as plain text, how entities are identified, how rejections route. Stages that write code give each entity an isolated worktree, so your main checkout stays clean; if you ship through PR review, commission offers the [pr-merge mod](../advanced/mods-and-standing-teammates.md), which manages the PR lifecycle so merging never needs to be a stage. The design summary shows it all; ask about the tradeoffs before you accept. -## What gets generated +## Two ways to tighten the README -After you accept, everything lands in `docs/{mission-slug}/` as plain text: the README that is the workflow's living spec, and one file per seed entity. A stage that writes code or produces artifacts runs each entity on an isolated branch, so your main checkout stays clean; if you ship through PR review, the skill also offers the [pr-merge mod](../advanced/mods-and-standing-teammates.md), which manages the PR lifecycle so merging never needs to be a stage. +The generated per-stage rules are best-guesses; [tighten them before any work runs](../concepts/workflows-and-entities.md#the-readme-is-where-you-set-the-rules). Either: -## Tighten the README before the first dispatch +- open the README and edit the bullets under each stage heading directly, or +- type `review stages` to have commission walk you through each stage, flag the rules that read as generic, and apply your amendments inline. -The README is the workflow's living spec. Before launching, the skill reminds you that the auto-generated per-stage rules are best-guesses and prompts you to tighten them. You have two ways to do it: +## The pilot run -- Open `docs/{mission-slug}/README.md` and edit the bullets under each stage heading directly. -- Type `review stages` to have the skill walk you through each stage one at a time, flag the rules that read as generic, and apply your amendments inline. - -Editing here costs minutes; un-editing after agents have been dispatched against vague rules costs more. - -## The pilot run and after - -On accept, commission takes the first-officer role itself and runs the pilot: it dispatches your seed entities and reports back when the workflow goes idle or a gate is waiting on your decision. In every later session, `spacedock claude` picks up where the last one left off; [Operating a workflow](operating.md) covers that loop. +On accept, commission takes the first-officer role itself and runs the pilot: it dispatches your seed entities and reports back when the workflow goes idle or a gate needs your decision. From there, [Operate a workflow](operating.md) covers the day-to-day loop. From be2199f1804600473c14ba860d38bd67e9d62e15 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 18:08:12 -0700 Subject: [PATCH 096/115] =?UTF-8?q?docs=20site:=20rename=20Operating=20a?= =?UTF-8?q?=20workflow=20to=20Operate=20a=20workflow=20=E2=80=94=20imperat?= =?UTF-8?q?ive=20register,=20nav=20+=20inbound=20links?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/site/concepts/gates-and-decisions.md | 2 +- docs/site/get-started/first-workflow.md | 2 +- docs/site/reference/command-reference.md | 2 +- docs/site/running-workflows/debrief-and-refit.md | 2 +- docs/site/running-workflows/operating.md | 2 +- mkdocs.yml | 2 +- 6 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/site/concepts/gates-and-decisions.md b/docs/site/concepts/gates-and-decisions.md index 8d7f321c..1298e0d0 100644 --- a/docs/site/concepts/gates-and-decisions.md +++ b/docs/site/concepts/gates-and-decisions.md @@ -59,4 +59,4 @@ The workflow is flexible beyond that: you can add conditional, lens-specific rev ## Where to go next -- [Operating a workflow](../running-workflows/operating.md) covers answering gates in the day-to-day loop. +- [Operate a workflow](../running-workflows/operating.md) covers answering gates in the day-to-day loop. diff --git a/docs/site/get-started/first-workflow.md b/docs/site/get-started/first-workflow.md index d3b91dbb..899754df 100644 --- a/docs/site/get-started/first-workflow.md +++ b/docs/site/get-started/first-workflow.md @@ -100,6 +100,6 @@ A project can hold each other; Spacedock drives them together and works out the dependencies. [Commission a workflow](../running-workflows/commission.md) covers every -design decision; [Operating a workflow](../running-workflows/operating.md) +design decision; [Operate a workflow](../running-workflows/operating.md) covers the day-to-day loop. Since this runs in your existing coding agent, you can just ask the agent if anything is unclear. diff --git a/docs/site/reference/command-reference.md b/docs/site/reference/command-reference.md index 0d5064b9..01c28c5d 100644 --- a/docs/site/reference/command-reference.md +++ b/docs/site/reference/command-reference.md @@ -36,7 +36,7 @@ The task comes first and becomes the launch prompt. Anything after `--` forwards These commands read and mutate workflow state. -- **`status`** is the main one: with no flag it prints the entity table, `--next` lists what is ready to dispatch, `--where` filters, `--set` mutates frontmatter, `--validate` checks the workflow, and `--boot` prints the first-officer boot view. It resolves the workflow from `--workflow-dir`, then `PIPELINE_DIR`, then by walking up to the enclosing workflow. The day-to-day reads are covered in [Operating a workflow](../running-workflows/operating.md). +- **`status`** is the main one: with no flag it prints the entity table, `--next` lists what is ready to dispatch, `--where` filters, `--set` mutates frontmatter, `--validate` checks the workflow, and `--boot` prints the first-officer boot view. It resolves the workflow from `--workflow-dir`, then `PIPELINE_DIR`, then by walking up to the enclosing workflow. The day-to-day reads are covered in [Operate a workflow](../running-workflows/operating.md). - **`new`** creates an entity from stdin. - **`state`** initializes or creates the state checkout for a [split-root workflow](../advanced/split-root-state.md). - **`completion`** prints a bash or zsh completion script. diff --git a/docs/site/running-workflows/debrief-and-refit.md b/docs/site/running-workflows/debrief-and-refit.md index 1c2fbc18..2718b526 100644 --- a/docs/site/running-workflows/debrief-and-refit.md +++ b/docs/site/running-workflows/debrief-and-refit.md @@ -64,4 +64,4 @@ Git is the safety net throughout: `git diff` and `git checkout` recover anything ## Where these fit -Debrief and refit bracket the working loop described in [Operating a workflow](operating.md): you commission once, operate session by session, debrief at the end of a session, and refit when you upgrade Spacedock. For the commands these skills call, see the [Command reference](../reference/command-reference.md). +Debrief and refit bracket the working loop described in [Operate a workflow](operating.md): you commission once, operate session by session, debrief at the end of a session, and refit when you upgrade Spacedock. For the commands these skills call, see the [Command reference](../reference/command-reference.md). diff --git a/docs/site/running-workflows/operating.md b/docs/site/running-workflows/operating.md index e1db90c9..65209623 100644 --- a/docs/site/running-workflows/operating.md +++ b/docs/site/running-workflows/operating.md @@ -1,4 +1,4 @@ -# Operating a workflow +# Operate a workflow You operate a workflow by talking to the first officer: launch a session, let it move everything that is ready, and decide when work reaches a gate. diff --git a/mkdocs.yml b/mkdocs.yml index 157603b6..32524771 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -79,7 +79,7 @@ nav: - Gates & decisions: concepts/gates-and-decisions.md - Running workflows: - Commission a workflow: running-workflows/commission.md - - Operating a workflow: running-workflows/operating.md + - Operate a workflow: running-workflows/operating.md - Debrief & refit: running-workflows/debrief-and-refit.md - Advanced topics: - Mods & standing teammates: advanced/mods-and-standing-teammates.md From d902a91a2ac265ba2c88fc639164416e4fb15b03 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 18:10:21 -0700 Subject: [PATCH 097/115] =?UTF-8?q?docs=20site:=20first-workflow=20close?= =?UTF-8?q?=20=E2=80=94=20commission=20link=20at=20point=20of=20need,=20Op?= =?UTF-8?q?erate=20the=20workflow=20section,=20captain=20closing=20line?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/site/get-started/first-workflow.md | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/docs/site/get-started/first-workflow.md b/docs/site/get-started/first-workflow.md index 899754df..8b3a43ab 100644 --- a/docs/site/get-started/first-workflow.md +++ b/docs/site/get-started/first-workflow.md @@ -54,7 +54,8 @@ bar for each. You confirm or adjust each proposal, and it presents the design: Everything is plain text in your repo: a README that holds the workflow's rules (what each stage expects) and one file per work item. The generated rules are a starting point; tighten them before any work runs, because an -agent working to a vague bar is expensive to correct. +agent working to a vague bar is expensive to correct. Learn more about every +design decision in [Commission a workflow](../running-workflows/commission.md). ## The pilot run @@ -79,7 +80,7 @@ Decision: approve to close; reject to bounce back to implementation. You approve, send it back with feedback, or reject. Details: [gates and decisions](../concepts/gates-and-decisions.md). -## Session to session +## Operate the workflow Every work item's state is stored and serialized in the [workflow](../concepts/workflows-and-entities.md), so you do not need to worry @@ -89,17 +90,18 @@ about context limits, resuming, or clearing. A typical session: spacedock claude ``` -It picks up whatever is ready to dispatch. You do a bunch of work: shaping, -asking the agents to dispatch, approving, rejecting, steering. Before you -stop, run [`/spacedock:debrief`](../running-workflows/debrief-and-refit.md) +It picks up whatever is ready to dispatch. Keep dispatching, approving, +rejecting, steering. Before you stop, run +[`/spacedock:debrief`](../running-workflows/debrief-and-refit.md) to record what happened, update the learnings into the workflow, and file the follow-up items. The workflow self-improves. +[Operate a workflow](../running-workflows/operating.md) covers the details. A project can hold [multiple workflows](../advanced/split-root-state.md) that coordinate with each other; Spacedock drives them together and works out the dependencies. +Since this runs in your existing coding agent, you can just ask the agent if +anything is unclear. -[Commission a workflow](../running-workflows/commission.md) covers every -design decision; [Operate a workflow](../running-workflows/operating.md) -covers the day-to-day loop. Since this runs in your existing coding agent, you -can just ask the agent if anything is unclear. +Now you have the first Spacedock-powered workflow: dispatch and let the agents +work and hum when you stay calm! From 467c9db64cc36e4e2e557df0c1c539fb0bdd0dbd Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 18:12:57 -0700 Subject: [PATCH 098/115] =?UTF-8?q?docs=20site:=20commission.md=20trimmed?= =?UTF-8?q?=20=E2=80=94=20archetypes=20named,=20pilot=20duplication=20drop?= =?UTF-8?q?ped=20for=20a=20dispatch=20close?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/site/running-workflows/commission.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/site/running-workflows/commission.md b/docs/site/running-workflows/commission.md index 1273daab..5340636c 100644 --- a/docs/site/running-workflows/commission.md +++ b/docs/site/running-workflows/commission.md @@ -1,6 +1,6 @@ # Commission a workflow -A workflow is designed in conversation: you make four decisions, commission derives the rest, and nothing is written until you accept the presented design. [Your first workflow](../get-started/first-workflow.md) shows the whole flow, including the design summary and pilot run. +A workflow is designed in conversation: you make four decisions and commission derives the rest. [Your first workflow](../get-started/first-workflow.md) shows the whole flow, including the design summary and pilot run. Invoke it from a session started with `spacedock claude`. You can pass the mission inline: @@ -12,13 +12,13 @@ Text after the command name becomes the workflow mission; with no argument, comm ## The four things you decide -1. **The mission and what each work item is.** What the workflow is for, and what one entity represents. The description you give becomes the label the workflow uses everywhere it talks about your work: "a design idea" makes it a workflow of ideas. +1. **The mission and what each work item is.** The description you give becomes the label the workflow uses everywhere: "a design idea" makes it a workflow of ideas. -2. **The stages.** Commission detects the workflow's shape from your mission (shipping code, testing a hypothesis, or iterating on an artifact) and proposes a stage list for you to confirm, modify, add to, or trim. It pushes back on redundant names: `awaiting_validation` reads as "the entity is in awaiting_validation," so it suggests `validation` instead. +2. **The stages.** Commission matches your mission to a workflow archetype (development: ship code through review; experiment: test a hypothesis against evidence; refinement: iterate on an artifact until it is good enough) and proposes the stage list from it. Confirm, adjust, or trim; it pushes back on redundant names (`awaiting_validation` is just `validation`). -3. **The gated stages.** Which stages pause for your decision. By default one gate sits before the terminal stage, and each gate gets a rejection target: the earlier stage work bounces back to when you reject. Both appear in the design summary in plain language ("If you reject at `review`, it goes back to `draft` for revision"). +3. **The gated stages.** Where the workflow pauses for your decision: by default one gate before the terminal stage, each with a rejection target stated in plain language ("If you reject at `review`, it goes back to `draft` for revision"). -4. **The per-stage quality bar.** Each stage in the generated README tells a dispatched ensign what "good" means there: what to produce, the quality bar to meet, the anti-patterns to avoid. Commission drafts these from the mission, but they are starting prose, not commitments. +4. **The per-stage quality bar.** What "good" means for each stage in the generated README: what to produce, the bar to meet, the anti-patterns to avoid. Starting prose, not commitments. Everything else is derived or asked with a recommendation attached: the directory under `docs/` where everything lands as plain text, how entities are identified, how rejections route. Stages that write code give each entity an isolated worktree, so your main checkout stays clean; if you ship through PR review, commission offers the [pr-merge mod](../advanced/mods-and-standing-teammates.md), which manages the PR lifecycle so merging never needs to be a stage. The design summary shows it all; ask about the tradeoffs before you accept. @@ -29,6 +29,6 @@ The generated per-stage rules are best-guesses; [tighten them before any work ru - open the README and edit the bullets under each stage heading directly, or - type `review stages` to have commission walk you through each stage, flag the rules that read as generic, and apply your amendments inline. -## The pilot run +## After you accept -On accept, commission takes the first-officer role itself and runs the pilot: it dispatches your seed entities and reports back when the workflow goes idle or a gate needs your decision. From there, [Operate a workflow](operating.md) covers the day-to-day loop. +You can now tell the first officer to dispatch your entities. From there, [Operate a workflow](operating.md) covers the day-to-day loop. From 1ae5ee0447624683fb97e58551f412b89a2e9c06 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 18:28:34 -0700 Subject: [PATCH 099/115] =?UTF-8?q?docs=20site:=20split=20debrief-and-refi?= =?UTF-8?q?t=20=E2=80=94=20Debrief=20a=20session=20(friction=20recorded=20?= =?UTF-8?q?and=20revisited)=20in=20running-workflows,=205-line=20Refit=20i?= =?UTF-8?q?n=20advanced?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/site/advanced/refit.md | 3 + docs/site/concepts/operating-model.md | 2 +- docs/site/get-started/first-workflow.md | 2 +- .../running-workflows/debrief-and-refit.md | 67 ------------------- docs/site/running-workflows/debrief.md | 10 +++ docs/site/running-workflows/operating.md | 2 +- mkdocs.yml | 3 +- 7 files changed, 18 insertions(+), 71 deletions(-) create mode 100644 docs/site/advanced/refit.md delete mode 100644 docs/site/running-workflows/debrief-and-refit.md create mode 100644 docs/site/running-workflows/debrief.md diff --git a/docs/site/advanced/refit.md b/docs/site/advanced/refit.md new file mode 100644 index 00000000..c6255226 --- /dev/null +++ b/docs/site/advanced/refit.md @@ -0,0 +1,3 @@ +# Refit a workflow + +When you upgrade Spacedock, run `/spacedock:refit path/to/workflow` to bring the workflow's generated files up to date while leaving your edits in place. Nothing is auto-replaced: you see a diff and decide, file by file, and if a schema change affects your entities, refit proposes the migration and waits for your approval. Git is the safety net; ask the agent about anything else. diff --git a/docs/site/concepts/operating-model.md b/docs/site/concepts/operating-model.md index 8be52311..7344ee2e 100644 --- a/docs/site/concepts/operating-model.md +++ b/docs/site/concepts/operating-model.md @@ -34,7 +34,7 @@ Decisions reach you batched and backed by evidence, not as a stream of interrupt **Every gate carries evidence.** The first officer does not hand you the transcript. It presents a short review: what was chosen, the evidence for it, and one recommendation you can approve with a single yes. [Gates and decisions](gates-and-decisions.md) shows the format. -**The decision leaves a trail.** Each gate records the verdict and its reason alongside the stage report in the work item's file. The record outlives the reviewer, so a bad result traces back to the call that caused it. When you end a session, [`/spacedock:debrief`](../running-workflows/debrief-and-refit.md) captures what happened, and the next session picks up from it. +**The decision leaves a trail.** Each gate records the verdict and its reason alongside the stage report in the work item's file. The record outlives the reviewer, so a bad result traces back to the call that caused it. When you end a session, [`/spacedock:debrief`](../running-workflows/debrief.md) captures what happened, and the next session picks up from it. ## Where to go next diff --git a/docs/site/get-started/first-workflow.md b/docs/site/get-started/first-workflow.md index 8b3a43ab..9d959af4 100644 --- a/docs/site/get-started/first-workflow.md +++ b/docs/site/get-started/first-workflow.md @@ -92,7 +92,7 @@ spacedock claude It picks up whatever is ready to dispatch. Keep dispatching, approving, rejecting, steering. Before you stop, run -[`/spacedock:debrief`](../running-workflows/debrief-and-refit.md) +[`/spacedock:debrief`](../running-workflows/debrief.md) to record what happened, update the learnings into the workflow, and file the follow-up items. The workflow self-improves. [Operate a workflow](../running-workflows/operating.md) covers the details. diff --git a/docs/site/running-workflows/debrief-and-refit.md b/docs/site/running-workflows/debrief-and-refit.md deleted file mode 100644 index 2718b526..00000000 --- a/docs/site/running-workflows/debrief-and-refit.md +++ /dev/null @@ -1,67 +0,0 @@ -# Debrief & refit - -Two maintenance commands keep a workflow durable across sessions and releases. `/spacedock:debrief` captures what happened in a session into a record the next session reads to start with context. `/spacedock:refit` brings an existing workflow's scaffolding up to the current Spacedock version while leaving your local edits in place. You run both as the captain; each pauses for your confirmation before it writes anything. - -## Debrief: capture a session - -`/spacedock:debrief` writes a structured record of a session (shipped entities, newly filed backlog seeds, workflow-only commits, gate decisions, issues, and what's next) to `{dir}/_debriefs/{date}-{sequence}.md` and commits it. The next session's first officer reads the most recent debrief instead of starting cold. - -Run it at the end of a working session, or whenever you want a checkpoint: - -```bash -spacedock claude "/spacedock:debrief" -``` - -The skill works in four phases. You make the decisions at the boundaries; everything else is git and local-file reads, with no external services until you ask it to file an issue. - -1. **Discovery.** It finds the workflow, anchors the session start where the previous debrief ended (or at the workflow's recent history when there is none), shows you the boundary (since-commit and commit count), and waits for your confirmation or a corrected starting commit. - -2. **Extract.** It buckets every commit in range: shipped PRs roll up into a **Shipped** section as links, routine state churn is suppressed, and only workflow-only commits that never flowed through a PR are listed. It reads entity frontmatter for what reached `done`, scans for gate approvals and rejections, and fills **What's next** from the dispatchable queue. - -3. **Draft and review.** It presents the draft with **Decisions** and **Observations** left as placeholders for you to fill. Add why a gate was approved or rejected, scope changes, design insights, or confirm as-is. Issues are split into **Workflow** (quirks in your pipeline, kept local) and **Spacedock** (framework bugs). For each Spacedock issue it offers to file an **anonymized** GitHub issue: the body carries the bug, repro steps, and scale, but never your mission, entity titles, or domain. You approve, edit, or decline each one before any `gh issue create` runs. - -4. **Write and commit.** It writes the debrief to `{dir}/_debriefs/{date}-{sequence:02d}.md`, commits it, and reports the path: - - ``` - Debrief written to {dir}/_debriefs/2026-06-09-01.md and committed. - ``` - -The debrief's frontmatter records where the session ended, which is how the next debrief knows where to start. - -## Refit: upgrade scaffolding to the current release - -`/spacedock:refit` upgrades a workflow's scaffolding files (the README and any installed mods in `_mods/`) to match the current Spacedock version, and migrates entity frontmatter when a schema change requires it. Agent files and the status viewer ship with the plugin, so they are never refit locally. The skill never auto-replaces a file you may have customized; it shows you a diff and you decide. - -You must give it the workflow directory: - -```bash -spacedock claude "/spacedock:refit path/to/workflow" -``` - -It reads the version stamp from the README frontmatter (`commissioned-by: spacedock@X.Y.Z`) and each mod's `version` field, then compares them against the current version from the plugin manifest. If everything matches it stops with "Workflow is already up to date." Otherwise it presents an upgrade plan and proceeds per file by strategy: - -- **`README.md`: show diff, never auto-replace.** Because you customize stages, schema fields, and quality criteria here, the skill generates what the current template would produce, diffs it against your README, and leaves it to you to apply the changes you want. It modifies only the version stamp at the end, not the README body. -- **`_mods/{name}.md`: version diff.** For each installed mod it compares your `version` against the canonical mod at `mods/{name}.md`. Matching versions are skipped; differing versions get a diff and a y/n. A mod with no canonical match is treated as custom: acknowledged, no action. Canonical mods you don't have installed are offered for install. -- **`status` (legacy): remove.** A workflow-local `status` script predates the launcher. The status viewer is now the `spacedock status` command, so refit removes the local copy with `git rm`. - -### Schema migration and ID style - -After scaffolding, refit compares the old and new README `## Schema` and `### Field Reference` sections for changed types or ranges, renamed fields, removed fields, or new required fields. If a change affects entity data, it lists the affected entities, proposes the migration (for example, "Convert score from /25 to 0.0–1.0 by dividing by 25"), and waits for your y/n. On approval it edits **only** the named frontmatter fields with the Edit tool, never an entity body, never a whole-file rewrite. - -Refit preserves the README's `id-style` (`sequential`, `sd-b32`, or `slug`) and never changes it silently. It recommends `sd-b32` only under collaboration pressure (worktree stages, PR/merge mods, multiple creators, branches, offline work) and requires your explicit approval. Before any approved style change it runs `spacedock status --validate` against the workflow and reports failures; the actual ID rewrite is manual in this release. - -### When there is no version stamp - -If the README has no `commissioned-by` stamp, refit cannot tell what the original scaffolding looked like, so it enters **degraded mode** and offers two choices: **stamp only** (add stamps without changing anything, to establish a baseline) or **full refit with review** (show a full diff for every file and require your approval before replacing each). It never auto-replaces an unstamped file. - -When the refit finishes it updates the README stamp to the current version, prints a per-file summary, and suggests the commit: - -```bash -git commit -m "refit: upgrade workflow scaffolding to spacedock@{current_version}" -``` - -Git is the safety net throughout: `git diff` and `git checkout` recover anything you didn't mean to keep. - -## Where these fit - -Debrief and refit bracket the working loop described in [Operate a workflow](operating.md): you commission once, operate session by session, debrief at the end of a session, and refit when you upgrade Spacedock. For the commands these skills call, see the [Command reference](../reference/command-reference.md). diff --git a/docs/site/running-workflows/debrief.md b/docs/site/running-workflows/debrief.md new file mode 100644 index 00000000..14aff45a --- /dev/null +++ b/docs/site/running-workflows/debrief.md @@ -0,0 +1,10 @@ +# Debrief a session + +A workflow improves when friction is recorded and revisited instead of lost when the session ends. `/spacedock:debrief` captures the session into a chronological record of the work completed: what shipped, what you decided at the gates, and where it rubbed. Run it before you stop; the next session's first officer reads the latest debrief and starts with context instead of cold. + +The friction splits two ways: + +- **Workflow friction stays local.** Quirks in your pipeline, fixed by tightening the workflow's README. +- **Spacedock friction goes upstream.** For each framework issue, debrief offers to file an anonymized GitHub issue: the body carries the bug, repro steps, and scale, never your mission, entity titles, or domain. You approve, edit, or decline each one before anything is filed. + +Debrief drafts everything from git and the workflow files, and pauses for you three times: confirm where the session starts, add the why behind decisions and observations, approve each upstream issue. It commits the record, and the next debrief picks up where this one ended. diff --git a/docs/site/running-workflows/operating.md b/docs/site/running-workflows/operating.md index 65209623..06525d30 100644 --- a/docs/site/running-workflows/operating.md +++ b/docs/site/running-workflows/operating.md @@ -26,4 +26,4 @@ The loop needs you less as the workflow matures. Rejections already run without ## Ending a session -Stop whenever you want; every entity's state is in the workflow files, so the next session resumes where this one ended. Before you stop, run [`/spacedock:debrief`](debrief-and-refit.md) to record the session for the next one. +Stop whenever you want; every entity's state is in the workflow files, so the next session resumes where this one ended. Before you stop, run [`/spacedock:debrief`](debrief.md) to record the session for the next one. diff --git a/mkdocs.yml b/mkdocs.yml index 32524771..85c387a9 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -80,10 +80,11 @@ nav: - Running workflows: - Commission a workflow: running-workflows/commission.md - Operate a workflow: running-workflows/operating.md - - Debrief & refit: running-workflows/debrief-and-refit.md + - Debrief a session: running-workflows/debrief.md - Advanced topics: - Mods & standing teammates: advanced/mods-and-standing-teammates.md - Multi-workflow & split-root state: advanced/split-root-state.md + - Refit a workflow: advanced/refit.md - Reference: - Command reference: reference/command-reference.md - Frontmatter contract: reference/frontmatter-contract.md From b37727e5973df4fa3d8647dc11a968a0f60756f4 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 18:32:58 -0700 Subject: [PATCH 100/115] =?UTF-8?q?docs=20site:=20codify=20session=20lesso?= =?UTF-8?q?ns=20=E2=80=94=20heading-dedupe=20alarm,=20journey-ownership,?= =?UTF-8?q?=20flowchart=20test,=20trust-then-defer,=20cadence=20split,=20p?= =?UTF-8?q?olish=20behavior=20re-verify,=20anchor=20check?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/site/AGENTS.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/site/AGENTS.md b/docs/site/AGENTS.md index 8d9046fa..4efc8f9d 100644 --- a/docs/site/AGENTS.md +++ b/docs/site/AGENTS.md @@ -11,6 +11,7 @@ Spacedock is not complicated; wordy docs make it *feel* complicated. Every edit - ✓ "You have work that needs doing in stages, with a human sign-off before anything ships. Spacedock runs that for you." - **Introduce the fewest terms possible, as late as possible.** Don't front-load a glossary. Define a term on first real use, gloss it once, then just use it. If a page introduces more than a handful of new terms, cut or defer some. - **Lead with what the user sees and must know; keep the how-it-works light.** Name the visible behavior and the required concepts first. Internal mechanics (scheduling and reuse conditions, file/branch naming templates, parser internals, query plumbing) get at most a sentence or a link to the source. If a paragraph reads as protocol documentation, compress it or cut it. +- **A paragraph that cannot be restated as one verifiable claim is flowchart.** Behavior checked against the owning skill compresses to a single stated fact; phase-by-phase narration of a skill's internals cuts entirely and the page loses nothing. - **Product anatomy is not a reader concept.** Do not name internal components (launcher, plugin, host) unless the reader must type or choose between them. The reader installs Spacedock and launches Spacedock; how it decomposes is not their problem. - **Write from the reader's seat, never the maintainer's.** If a sentence's subject is the build, the script, or the parser, recast it around what the reader gets or does. - ✗ "The build emits a curated `llms.txt` index at the site root." @@ -22,6 +23,7 @@ Spacedock is not complicated; wordy docs make it *feel* complicated. Every edit - **A real example with sample output beats description.** One concrete command plus the output the reader will see teaches faster than paragraphs. Compose samples from the product's real templates, and never restate in prose what the sample already says ("Accept this design, or tell me what to change" makes a "nothing is generated until you accept" sentence dead weight). - **Keep agent-facing surfaces off user pages.** Commands meant for the agents (`spacedock status`, `spacedock dispatch`) are not taught in Get started, even though their output is real. - **The docs may defer to the agent.** Spacedock runs inside a coding agent; "ask the agent if anything is unclear" is a legitimate close. Pages cover what the reader needs before and between sessions, not every contingency within one. +- **For an agent-operated feature, the page's job is trust, then deferral.** State the guarantees that make handing over safe (nothing is auto-replaced; it waits for your approval), then defer the mechanism to the agent. Detail beyond the guarantee is reassurance theater. - **The agent is the interface; docs say what is possible.** Files and settings are operated by asking the first officer, not by hand-editing walkthroughs. Describe capabilities ("a stage can pause at a gate, run isolated, demand a fresh reviewer… ask the first officer to set up or change any of it"), never a field-by-field table of how to key them in. - **A diagram beats an enumeration for structure.** A stage chain is a mermaid flowchart, not five field-by-field bullets. Carry the meaning in a plain-text caption sentence as well, so the styling is decoration and text readers (`llms.txt`) lose nothing. - **State behavior; don't narrate rationale.** "When a stage declares `worktree: true`, everything from that stage onward happens in an isolated worktree" — not the tradeoff that motivated the design. The reader wants what happens, not why we built it that way. @@ -30,6 +32,9 @@ Spacedock is not complicated; wordy docs make it *feel* complicated. Every edit - **No archaeology pages.** An example lives as a sample at the point of need (a design summary on the commission page, a gate review on the gates page), not as a trace page that walks one real artifact through every mechanism at once. - **Cut, don't pad.** If a sentence still carries its meaning with a clause removed, remove the clause. If a paragraph repeats the page above it, delete it and link instead. - **Don't repeat content across pages.** One page owns each idea; others link to it. Duplicated explanation is the main thing that makes the docs feel long. An audience split ("new-user view" vs "operator view" of the same feature) is not a reason for a second page; it is the same topic. +- **The same heading on two pages is a dedupe alarm.** When two pages grow a section with the same title, they are explaining the same idea twice. Pick the owner; the other page keeps only its delta. This is invisible page by page; it shows up only when reading the pages as a set. +- **Shared ideas resolve to the earliest page in the journey that needs them.** Later pages keep only their delta. Killing a duplicated section rarely loses content; its unique facts usually fit in a tail clause of an adjacent paragraph. +- **Split pages by cadence, not topic.** Two features used at different rhythms (every session vs every upgrade) are two pages, even when both read as the same kind of work. A shared reader moment, not a shared noun, is what makes one page. - **Two levels of structure only:** section → page. No deeper nesting; no page that exists only to hold sub-pages. ## First impression: "simple," not "enterprise" @@ -130,12 +135,13 @@ Revision is paragraph by paragraph, not page-at-a-glance. For each paragraph ask 2. **Do they have the context, at this point in the journey?** Every term and claim must be introduced by this page or an earlier one in nav order. 3. **Does it make them want to read on?** End on the payoff or the concrete thing they can type, not on a caveat. -Propose the revision yourself, then send the proposal (with its three-question rationale) to the prose-polish teammate when one is standing. Triage the return; never auto-apply: accept real improvements, reject anything that violates this directive (em-dash insertions are the recurring offender) or alters captain-set wording, and re-check the file on disk before acting on replies that arrive late. +Propose the revision yourself, then send the proposal (with its three-question rationale) to the prose-polish teammate when one is standing. Triage the return; never auto-apply: accept real improvements, reject anything that violates this directive (em-dash insertions are the recurring offender) or alters captain-set wording, re-verify any suggestion that touches a behavior claim against the owning source (polish can phrase a plausible falsehood), and re-check the file on disk before acting on replies that arrive late. ## Before you commit a docs change - [ ] Page opens with the problem/payoff, not a definition. - [ ] Introduces only the terms this page actually needs; each defined on first use. - [ ] Re-read every touched page in reader-journey order: no term appears before the page that introduces it, including terms your own rewrite brought back. +- [ ] No inbound link targets a heading this change removed or renamed; anchors break silently (`--strict` reports them as INFO, not failures), so grep for the old anchor. - [ ] Matches its type's shape (concept / how-to / reference): no steps in concepts, no essays in reference. - [ ] No content duplicated from another page; shared ideas are linked, not repeated. - [ ] Internal links are relative and descriptive; first mentions of key terms link out. From f1bc3b907ac5c5871264c5973446f20b20ca52a5 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 18:40:51 -0700 Subject: [PATCH 101/115] =?UTF-8?q?docs=20site:=20split=20Multiple=20workf?= =?UTF-8?q?lows=20out=20of=20split-root-state=20=E2=80=94=20coordination?= =?UTF-8?q?=20via=20frontmatter=20annotation,=20split-root=20page=20payoff?= =?UTF-8?q?-first,=20agent=20commit=20discipline=20deferred?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/site/advanced/multi-workflow.md | 7 ++++++ docs/site/advanced/split-root-state.md | 24 ++++---------------- docs/site/concepts/workflows-and-entities.md | 2 +- docs/site/get-started/first-workflow.md | 4 ++-- docs/site/reference/frontmatter-contract.md | 2 +- mkdocs.yml | 3 ++- 6 files changed, 18 insertions(+), 24 deletions(-) create mode 100644 docs/site/advanced/multi-workflow.md diff --git a/docs/site/advanced/multi-workflow.md b/docs/site/advanced/multi-workflow.md new file mode 100644 index 00000000..7096f01b --- /dev/null +++ b/docs/site/advanced/multi-workflow.md @@ -0,0 +1,7 @@ +# Multiple workflows + +Related work rarely fits one pipeline. A project can hold several workflows, each its own directory with its own README, stages, and gates; Spacedock finds them all and operates them at the same time. A typical pair: a benchmark project where one workflow tracks the experiment runs and another ships the harness that supports them. + +There is no hard dependency declaration between workflows. When an entity in one workflow depends on work in another, annotate it in the entity's frontmatter (a flat custom field naming the other item) and the first officer figures it out at dispatch time. + +Workflows in the same repo can also keep their state off your code branch; [split-root state](split-root-state.md) covers that. diff --git a/docs/site/advanced/split-root-state.md b/docs/site/advanced/split-root-state.md index b8da9d09..c28b5ab3 100644 --- a/docs/site/advanced/split-root-state.md +++ b/docs/site/advanced/split-root-state.md @@ -1,30 +1,16 @@ -# Multi-workflow & split-root state +# Split-root state -A split-root workflow separates the workflow's definition from its runtime state. The README and stage declarations stay on your main branch; the mutable entities (frontmatter updates, stage reports, archive moves) live in a separate state checkout. State transitions stop polluting your code branch's history, and several agents or operators can drive the same workflow at once. +A busy workflow generates constant small state commits. Split-root keeps them off your code branch: the README and stage declarations stay on your main branch, while the mutable entity state (frontmatter updates, stage reports, archive moves) lives in a separate state checkout. Your code history stays clean, and several agents or operators can drive the same workflow at once. -Reach for it when status changes would otherwise land as noisy commits on `main`, or when more than one writer needs to advance the same workflow concurrently. Without it, Spacedock keeps the default: entities sit beside the README on the same branch. - -## Opt in with one field - -Add a `state:` field to the README frontmatter, a path relative to the README directory: - -```yaml -state: .spacedock-state -``` - -Spacedock then reads stage declarations from the README and entities from the state path, and writes entity changes only into the state path. The split is transparent to the command surface: read the workflow exactly as you would a single-root one. - -On a fresh clone the state checkout is absent; run `spacedock state init` to restore it before working the workflow. - -The shipped `docs/dev` workflow runs split-root; see its README for a live example. +The README [opts in with one `state:` field](../concepts/workflows-and-entities.md#keep-workflow-state-off-your-code-branch); the split is transparent, and you read the workflow exactly as you would a single-root one. On a fresh clone the state checkout is absent; run `spacedock state init` to restore it. The shipped [`docs/dev` workflow](https://github.com/spacedock-dev/spacedock/tree/main/docs/dev) runs split-root, a live example. ## Concurrent writers -The state checkout is a shared git index that multiple agents commit to, so the commit and sync discipline is a correctness requirement, not a style choice: writers commit path-scoped (never a bare `git add -A`), and conflicting edits to the same entity halt for the captain rather than auto-resolving. The exact protocol is owned by the launcher and the ensign skill; see [the split-root state contract](https://github.com/spacedock-dev/spacedock/blob/main/docs/dev/README.md) for the authoritative rules. +The agents follow the commit and sync discipline that keeps concurrent writers from clobbering each other; it is theirs to follow, not yours. The one case that reaches you: conflicting edits to the same entity halt for your call rather than auto-resolving. ## Bridging an external tracker -Split-root state is the integration point for an external tracker (Linear, GitHub Issues, kata, or another ticket ledger). The external system can own backlog intake, discussion, and assignment while Spacedock stays the execution workflow. The bridge uses flat top-level frontmatter fields so the parser preserves them: +Split-root state is the integration point for an external tracker (Linear, GitHub Issues, or another ticket ledger). The external system can own backlog intake, discussion, and assignment while Spacedock stays the execution workflow. The bridge is two flat frontmatter fields (the [frontmatter contract](../reference/frontmatter-contract.md) explains why they stay flat): ```yaml issue: ENG-123 diff --git a/docs/site/concepts/workflows-and-entities.md b/docs/site/concepts/workflows-and-entities.md index 77af5141..a68ae29e 100644 --- a/docs/site/concepts/workflows-and-entities.md +++ b/docs/site/concepts/workflows-and-entities.md @@ -46,4 +46,4 @@ A workflow can keep its mutable state in a separate state checkout, so routine s state: .spacedock-state ``` -[Multi-workflow & split-root state](../advanced/split-root-state.md) covers the mechanics and the fresh-clone setup. +[Split-root state](../advanced/split-root-state.md) covers the mechanics and the fresh-clone setup. diff --git a/docs/site/get-started/first-workflow.md b/docs/site/get-started/first-workflow.md index 9d959af4..8c74024e 100644 --- a/docs/site/get-started/first-workflow.md +++ b/docs/site/get-started/first-workflow.md @@ -98,8 +98,8 @@ follow-up items. The workflow self-improves. [Operate a workflow](../running-workflows/operating.md) covers the details. A project can hold -[multiple workflows](../advanced/split-root-state.md) that coordinate with -each other; Spacedock drives them together and works out the dependencies. +[multiple workflows](../advanced/multi-workflow.md); Spacedock finds them +and drives them together. Since this runs in your existing coding agent, you can just ask the agent if anything is unclear. diff --git a/docs/site/reference/frontmatter-contract.md b/docs/site/reference/frontmatter-contract.md index 03e7ae8f..53d11810 100644 --- a/docs/site/reference/frontmatter-contract.md +++ b/docs/site/reference/frontmatter-contract.md @@ -46,7 +46,7 @@ Fill `title`, `status`, and `source` at creation; the runtime writes the rest as ## External-tracker fields -`issue` and `source` are the bridge to an external ledger (Linear, GitHub Issues, kata). `issue` is the human-facing ticket reference; `source` records the origin. Spacedock `status` stays the execution status, and the tracker does not redefine stage semantics inside the entity. See [Multi-workflow & split-root state](../advanced/split-root-state.md#bridging-an-external-tracker) for the full bridge model. +`issue` and `source` are the bridge to an external ledger (Linear, GitHub Issues). `issue` is the human-facing ticket reference; `source` records the origin. Spacedock `status` stays the execution status, and the tracker does not redefine stage semantics inside the entity. See [Split-root state](../advanced/split-root-state.md#bridging-an-external-tracker) for the full bridge model. ## Validating an entity diff --git a/mkdocs.yml b/mkdocs.yml index 85c387a9..5f305760 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -83,7 +83,8 @@ nav: - Debrief a session: running-workflows/debrief.md - Advanced topics: - Mods & standing teammates: advanced/mods-and-standing-teammates.md - - Multi-workflow & split-root state: advanced/split-root-state.md + - Multiple workflows: advanced/multi-workflow.md + - Split-root state: advanced/split-root-state.md - Refit a workflow: advanced/refit.md - Reference: - Command reference: reference/command-reference.md From 452f7eb8b279d75d60efa58fd0ef952ee5e99d3b Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 18:45:40 -0700 Subject: [PATCH 102/115] =?UTF-8?q?docs=20site:=20mods=20page=20=E2=80=94?= =?UTF-8?q?=20payoff=20lede,=20reader-seat=20hooks,=20exact-format=20secti?= =?UTF-8?q?on=20folded=20into=20agent=20deferral?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/site/advanced/mods-and-standing-teammates.md | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/docs/site/advanced/mods-and-standing-teammates.md b/docs/site/advanced/mods-and-standing-teammates.md index 0b3062f8..47d3e261 100644 --- a/docs/site/advanced/mods-and-standing-teammates.md +++ b/docs/site/advanced/mods-and-standing-teammates.md @@ -1,14 +1,12 @@ # Mods & standing teammates -Mods extend a workflow without touching the binary. A mod is a markdown file under `{workflow_dir}/_mods/`, and it adds behavior that is the same across stages and across workflows: a step that must happen at a fixed point in every run, or a specialist that should persist across the whole session. The first officer reads the mod and acts on it; nothing compiles. - -A mod does one of two things, or both. +Two needs recur as a workflow matures: a step that must happen at a fixed point in every run (open a PR when work merges), and a specialist whose judgment should persist across the whole session (a prose polisher). A mod adds either: a markdown file in the workflow's `_mods/` directory that the first officer reads and acts on. ## Lifecycle hooks -A hook runs first-officer prose at a fixed point in the run: at `startup`, on an `idle` pass when nothing is ready to dispatch, or at the `merge` boundary when an entity terminalizes. The point is workflow-independent: any workflow can register the same hook to get the same behavior. +A hook adds a step the first officer performs at a fixed point in the run: at `startup`, on an `idle` pass when nothing is ready to dispatch, or at the `merge` boundary when an entity reaches its final stage. The point is workflow-independent: any workflow can register the same hook to get the same behavior. -The canonical example is the [`pr-merge` mod](https://github.com/spacedock-dev/spacedock/blob/main/docs/dev/_mods/pr-merge.md): it opens the code-branch PR at merge, records the PR on the entity, and holds the terminal transition until the PR merges. A merge hook can block that transition, and the binary enforces the block so a half-merged entity cannot slip past the gate. +The canonical example is the [`pr-merge` mod](https://github.com/spacedock-dev/spacedock/blob/main/docs/dev/_mods/pr-merge.md): it opens the code-branch PR at merge, records the PR on the entity, and holds the terminal transition until the PR merges. The block is enforced; a half-merged entity cannot slip past the gate. ## Standing teammates @@ -16,6 +14,4 @@ A standing teammate is a long-lived specialist agent declared by a mod. It lives The canonical example is the **comm-officer**, a prose-polisher the first officer routes deliberate drafts through (PR bodies, gate summaries, debriefs) before they reach you. Routing is best-effort: if the teammate is absent or slow, the work proceeds without it. -## The exact format - -The mod file format, the hook points, and the `spacedock dispatch` subcommands that read standing-teammate mods are defined in the skills and binary that own them. See [the mods reference](https://github.com/spacedock-dev/spacedock/blob/main/docs/dev/README.md) for the authoritative contract. +Ask the agent to install a shipped mod or write a new one; the file format is its job. From d5497cbe8ded9bba44daf9c72e014bb7461f0a2b Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 18:48:20 -0700 Subject: [PATCH 103/115] =?UTF-8?q?docs=20site:=20mods=20lede=20=E2=80=94?= =?UTF-8?q?=20the=20hook=20mechanism=20framing=20(captain),=20plus=20triag?= =?UTF-8?q?ed=20comm-officer=20accepts?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/site/advanced/mods-and-standing-teammates.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/site/advanced/mods-and-standing-teammates.md b/docs/site/advanced/mods-and-standing-teammates.md index 47d3e261..54511f0b 100644 --- a/docs/site/advanced/mods-and-standing-teammates.md +++ b/docs/site/advanced/mods-and-standing-teammates.md @@ -1,17 +1,17 @@ # Mods & standing teammates -Two needs recur as a workflow matures: a step that must happen at a fixed point in every run (open a PR when work merges), and a specialist whose judgment should persist across the whole session (a prose polisher). A mod adds either: a markdown file in the workflow's `_mods/` directory that the first officer reads and acts on. +As a workflow matures, you start wanting behavior that is not any stage's job: a step that must happen at a fixed point in every run (open a PR when work merges), or a specialist whose judgment should persist across the whole session (a prose polisher). A mod is the hook mechanism for exactly this: standardized behavior that hooks into the workflow's run without changing your workflow definition. The stages and gates in your README stay as they are; a mod is one markdown file in the workflow's `_mods/` directory, and the first officer reads it and acts on it. ## Lifecycle hooks -A hook adds a step the first officer performs at a fixed point in the run: at `startup`, on an `idle` pass when nothing is ready to dispatch, or at the `merge` boundary when an entity reaches its final stage. The point is workflow-independent: any workflow can register the same hook to get the same behavior. +A hook adds a step the first officer performs at a fixed point in the run: at `startup`, on an `idle` pass when nothing is ready to dispatch, or at the `merge` boundary when an entity reaches its final stage. Hook points are workflow-independent: any workflow can register the same hook to get the same behavior. The canonical example is the [`pr-merge` mod](https://github.com/spacedock-dev/spacedock/blob/main/docs/dev/_mods/pr-merge.md): it opens the code-branch PR at merge, records the PR on the entity, and holds the terminal transition until the PR merges. The block is enforced; a half-merged entity cannot slip past the gate. ## Standing teammates -A standing teammate is a long-lived specialist agent declared by a mod. It lives in the team for the session and is addressed by name. Reach for one when the same specialist judgment recurs across entities and is worth a persistent agent rather than a fresh dispatch each time. +A standing teammate is a long-lived specialist agent declared by a mod. It stays available for the session and is addressed by name. Reach for one when the same specialist judgment recurs across entities and is worth a persistent agent rather than a fresh dispatch each time. The canonical example is the **comm-officer**, a prose-polisher the first officer routes deliberate drafts through (PR bodies, gate summaries, debriefs) before they reach you. Routing is best-effort: if the teammate is absent or slow, the work proceeds without it. -Ask the agent to install a shipped mod or write a new one; the file format is its job. +Ask the first officer to install a shipped mod or write a new one; the file format is its job. From 82852e8482f1727341aeacff9f8acc667a165c32 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 18:49:27 -0700 Subject: [PATCH 104/115] =?UTF-8?q?docs/dev:=20track=20the=20comm-officer?= =?UTF-8?q?=20standing-teammate=20mod=20=E2=80=94=20the=20docs=20cite=20it?= =?UTF-8?q?=20as=20the=20canonical=20example?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/dev/_mods/comm-officer.md | 148 +++++++++++++++++++++++++++++++++ 1 file changed, 148 insertions(+) create mode 100644 docs/dev/_mods/comm-officer.md diff --git a/docs/dev/_mods/comm-officer.md b/docs/dev/_mods/comm-officer.md new file mode 100644 index 00000000..0cd9f6a2 --- /dev/null +++ b/docs/dev/_mods/comm-officer.md @@ -0,0 +1,148 @@ +--- +name: comm-officer +description: Standing prose-polishing teammate for this workflow +version: 0.1.0 +standing: true +--- + +# Comm Officer + +A standing teammate for prose polish. Kept alive for the captain session once spawned. First FO to boot into a team missing this member spawns it; subsequent workflows in the same session detect it and skip. + +## Hook: startup + +Before entering the normal event loop, check whether the current team (`~/.claude/teams/{team_name}/config.json` members list) contains a member named `comm-officer`. + +- **If present:** log `comm-officer already alive, skipping spawn` and proceed. First-boot-wins. +- **If absent:** spawn using the configuration below, then proceed. + +Spawn configuration: + +- `subagent_type: general-purpose` +- `name: comm-officer` +- `team_name: {current team}` +- `model: sonnet` +- `prompt`: everything in the `## Agent Prompt` section below, verbatim. + +The spawn is fire-and-forget. Do NOT block on the teammate's first idle notification before continuing to normal dispatch. Ensigns will route to it on demand when they need polish; if it's not ready yet when the first request arrives, Claude Code queues the message. + +## Hook: shutdown + +On captain-initiated session teardown (e.g., `/spacedock shutdown-all`, or FO explicit end-of-session), send `{"type":"shutdown_request", "reason":"session ending"}` to `comm-officer`. If the session ends uncleanly (captain closes the window, process terminates), Claude Code tears down the team and the teammate with it; no explicit shutdown needed. + +## Routing guidance (for FO and ensigns) + +**Scope — what `comm-officer` polishes:** + +- **Drafts about to be presented to the captain** — PR bodies, gate review summaries, debrief content, long stage report narratives before they're shown. +- **Entity file contents** — Problem Statement / Proposed Approach / narrative sections of entity bodies before they're committed. + +**Scope — what `comm-officer` does NOT polish:** + +- Direct chat replies to the captain during a live conversation. Conversational latency and voice authenticity matter more than polish; the small latency and rewrite tax is not worth it. +- Short operational statuses (`pushed to origin`, `tests green`, `PR opened at …`). +- Tool-call outputs, commit messages, transient logs. + +If in doubt, ask: "Is this a *draft* that will live somewhere the captain reviews deliberately?" If yes, consider polishing. If the captain is reading it in a live conversation turn, do not polish. + +**Four usage patterns (mirrors Claude Code's read/Edit/Write tool shapes):** + +1. **Text passthrough** — caller sends prose as message body; teammate replies with polished text + notes block; caller does the placement. Use when polished text will be assembled into a larger structure (PR body, multi-part message, live reply to captain). +2. **File-in-place** — caller includes exact phrase `polish this file` + absolute path; teammate reads the file, polishes it, writes it in place, replies with a confirmation + notes. Use when a file already exists on disk with unpolished prose to tighten. +3. **Polish-and-write** (mirrors the Write tool) — caller sends header line `polish and write to {absolute_path}:` followed by the raw prose; teammate polishes, `Write(file_path, polished_content)` (creates or fully overwrites), replies with confirmation + notes. Use when creating a new file whose content IS polished prose (e.g., a draft narrative block). +4. **Polish-and-edit** (mirrors the Edit tool) — caller sends header line `polish and edit {absolute_path}:` followed by two labeled blocks: `old_string:` (exact text to replace, unchanged) and `new_string:` (raw prose to polish then place); teammate polishes new_string, `Edit(file_path, old_string, polished_new_string)`, replies with confirmation + notes. Use when splicing polished prose into an existing file at a specific location (marker replacement, section swap, appending to an anchor). + +Patterns 3 and 4 remove the caller's copy-paste step between "get polished text back" and "write it somewhere." Pattern 1 stays the right choice when the caller needs to review polished text before committing it anywhere. + +**Hard rules:** + +- MUST NOT block on `comm-officer` reply. If no response within 2 minutes or the teammate is unavailable, proceed with un-polished text and note the fallback in the stage report. Polish is best-effort, not load-bearing. +- MUST NOT forward captain directives or sensitive context (API keys, internal URLs, unreleased plans) to `comm-officer` — only the prose to be polished. + +## Routing Usage + +Four caller patterns (mirror Claude's Read/Edit/Write tool shapes). Pick the pattern first, then format the SendMessage body to match. + +1. **Text passthrough** (default — no trigger phrase) — send raw prose as the message body. Reply: polished text first, then `---` + `**Polish notes**` block. Caller places the result. +2. **File-in-place** — send the exact phrase `polish this file` with an absolute path. Teammate Edits/Writes the file in place. Reply: one-line receipt + `---` + `**Polish notes**`. +3. **Polish-and-write** — send header `polish and write to {absolute_path}:` followed by raw prose. Teammate Writes the polished prose to that path (create-or-overwrite). Reply: one-line receipt + `---` + `**Polish notes**`. +4. **Polish-and-edit** — send header `polish and edit {absolute_path}:` followed by labeled blocks `old_string:` (unchanged anchor) and `new_string:` (raw prose to polish). Teammate polishes `new_string` and Edits the file at that anchor. Reply: one-line receipt + `---` + `**Polish notes**`. + +Notes block fields: `Mode`, `Guide applied`, `Changes`, `Flagged for review`. Absolute paths required for patterns 2-4; no inferred targets. Best-effort non-blocking — proceed with un-polished content if no reply within 2 minutes. + +## Agent Prompt + +You are the session's communications officer. Your job is to polish prose for clarity and concision, and return it quickly. + +**Your first action on spawn:** check whether the `elements-of-style:writing-clearly-and-concisely` skill is available in your tool surface (via ToolSearch or equivalent). Then SendMessage to `team-lead` with EXACTLY ONE of these two online messages: + +- If available: `comm-officer online, elements-of-style:writing-clearly-and-concisely skill found, ready for polish requests.` +- If missing: `comm-officer online. WARNING: elements-of-style:writing-clearly-and-concisely skill NOT available in my tool surface — I will apply Strunk & White principles directly, polish quality will be reduced. The captain can install the skill via the elements-of-style plugin and respawn me for full quality. Ready for polish requests in degraded mode.` + +Then idle. Do NOT start polishing anything until you receive a polish request. + +If the skill is available, invoke it for polish. Read the skill's reference material in full on first use this session, then stay resident. If the skill is not available, apply Strunk & White principles from your training directly. + +Four patterns you'll receive (mirroring Claude Code's Read/Edit/Write tools): + +1. **Text passthrough** — caller sends prose as the message body with no mode-trigger phrase. Reply with polished prose + a short notes block. Never touch files in this mode. +2. **File-in-place** — caller explicitly says `polish this file` with an absolute path. You MAY `Edit` or `Write` the file's existing prose sections in place. Reply with confirmation + notes. Do NOT enter this mode unless the caller used that exact trigger phrase. +3. **Polish-and-write** — caller's message opens with the header `polish and write to {absolute_path}:` followed by raw prose. Polish the prose, then use the `Write` tool with that absolute path and your polished content (full-file create-or-overwrite). Reply with confirmation + notes. Only enter this mode if the header is present verbatim. +4. **Polish-and-edit** — caller's message opens with the header `polish and edit {absolute_path}:` followed by two labeled blocks: an `old_string:` block (exact text to locate, unchanged) and a `new_string:` block (raw prose you will polish and place). Polish only the `new_string` prose. Then use the `Edit` tool with that absolute path, the `old_string` you received (unchanged), and your polished `new_string`. Reply with confirmation + notes. Only enter this mode if the header is present verbatim. + +**Boundary rules for all file-writing modes (2, 3, 4):** + +- The caller specifies the write target via absolute path. You do NOT decide where to write; your only decisions are polish choices on the prose. +- If the absolute path is missing, ambiguous, or outside the current project tree, reply with a one-line clarification request and take no action. +- If the `Edit` tool's `old_string` is not found in the target file, reply naming the failure and take no further action — do not guess. +- Keep reply bodies brief for these modes (see reply format below). The file is the deliverable; your message is a receipt. + +**How to reply — hard rules, not suggestions:** + +- Your reply body IS the deliverable. Put the polished prose as the FIRST thing in the message, with no preamble. Do NOT describe what you did — your work IS the reply. +- Each SendMessage is a discrete standalone message. There is no "inline above", no "attached", no "as shown earlier". If content isn't in the body of THIS specific message, it does not exist. +- Never send a summary-only confirmation message instead of the polished text. If you're not ready to deliver polished text yet, don't send anything. +- Always state in the `Guide applied` field which style source you used. If the `elements-of-style:writing-clearly-and-concisely` skill is unavailable, say `none — plain Strunk (skill not available)` explicitly — never silently degrade. + +You are a **standing teammate**: + +- Stay live. Go idle between tasks. Do NOT send `shutdown_request` to the team-lead — the captain or FO initiates teardown, not you. +- Between polish tasks, you do nothing. No speculative edits. No file exploration. No unsolicited skill invocations. +- If you receive a message you don't understand, reply asking for clarification in one short line. Don't guess. + +Your reply format for text-passthrough: + +``` +{polished text} + +--- +**Polish notes** +- Guide applied: {name or "none — plain Strunk" if no project guide applies} +- Changes: {1-3 bullets of the biggest edits} +- Flagged for review: {anything you changed that might warrant human eyes, or "nothing"} +``` + +Your reply format for file-in-place / polish-and-write / polish-and-edit: + +``` +{Polished / Wrote / Edited} {absolute path}. {N} lines {changed/written}. + +--- +**Polish notes** +- Mode: {file-in-place | polish-and-write | polish-and-edit} +- Guide applied: {name or "none"} +- Changes: {1-3 bullets} +- Flagged for review: {anything} +``` + +Keep polish notes under 80 words total. If you're tempted to write more, that's a sign the change was too big — flag it for human review instead of making it. + +Your default is light-touch. Preserve the caller's voice, rhythm, and technical vocabulary. Cut empty words, tighten sentences, fix clear grammar errors. Do NOT rewrite for style unless the caller explicitly asks. + +When a caller's text contains domain jargon (project names, internal terms, acronyms), preserve it unchanged unless you can prove it's a typo. Ask before translating jargon. + +**Preserve disambiguating attributions and parenthetical modifiers.** Parentheticals like "(in another user's workflow)", "(proposed by CL last session)", "(v2 after the rebase)" are usually load-bearing — they tell the reader which instance of a thing is being discussed. Collapsing them into implicit context drops signal. Keep them. If a parenthetical truly is filler (e.g., "(as mentioned earlier)"), cut it and flag the cut. + +**Do not change semantic qualifiers silently.** "The proposed comm-officer" is not the same as "the comm-officer." "The draft summary" is not "the summary." If you change a noun's qualifier, note it in the Changes bullets. + +If a voice guide applies to this project (a `CLAUDE.md`, `tone-preferences.md`, or equivalent), load it on first use and defer to it when it conflicts with Strunk. The captain or dispatching ensign will tell you which guide(s) are in scope for this session — don't go searching on your own. From b391c24d353674ed4d9916910c381ddfbbf3536f Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 18:49:44 -0700 Subject: [PATCH 105/115] docs site: linkify comm-officer to its mod file on main --- docs/site/advanced/mods-and-standing-teammates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/site/advanced/mods-and-standing-teammates.md b/docs/site/advanced/mods-and-standing-teammates.md index 54511f0b..34783853 100644 --- a/docs/site/advanced/mods-and-standing-teammates.md +++ b/docs/site/advanced/mods-and-standing-teammates.md @@ -12,6 +12,6 @@ The canonical example is the [`pr-merge` mod](https://github.com/spacedock-dev/s A standing teammate is a long-lived specialist agent declared by a mod. It stays available for the session and is addressed by name. Reach for one when the same specialist judgment recurs across entities and is worth a persistent agent rather than a fresh dispatch each time. -The canonical example is the **comm-officer**, a prose-polisher the first officer routes deliberate drafts through (PR bodies, gate summaries, debriefs) before they reach you. Routing is best-effort: if the teammate is absent or slow, the work proceeds without it. +The canonical example is the [**comm-officer**](https://github.com/spacedock-dev/spacedock/blob/main/docs/dev/_mods/comm-officer.md), a prose-polisher the first officer routes deliberate drafts through (PR bodies, gate summaries, debriefs) before they reach you. Routing is best-effort: if the teammate is absent or slow, the work proceeds without it. Ask the first officer to install a shipped mod or write a new one; the file format is its job. From 77445b7545cd2f3bd6f4e46304d54033f8c9b970 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 18:51:58 -0700 Subject: [PATCH 106/115] =?UTF-8?q?docs=20site:=20mods=20lede=20=E2=80=94?= =?UTF-8?q?=20mod=20behavior=20could=20be=20stages,=20factored=20out=20bec?= =?UTF-8?q?ause=20common=20across=20workflows?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/site/advanced/mods-and-standing-teammates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/site/advanced/mods-and-standing-teammates.md b/docs/site/advanced/mods-and-standing-teammates.md index 34783853..f39fd880 100644 --- a/docs/site/advanced/mods-and-standing-teammates.md +++ b/docs/site/advanced/mods-and-standing-teammates.md @@ -1,6 +1,6 @@ # Mods & standing teammates -As a workflow matures, you start wanting behavior that is not any stage's job: a step that must happen at a fixed point in every run (open a PR when work merges), or a specialist whose judgment should persist across the whole session (a prose polisher). A mod is the hook mechanism for exactly this: standardized behavior that hooks into the workflow's run without changing your workflow definition. The stages and gates in your README stay as they are; a mod is one markdown file in the workflow's `_mods/` directory, and the first officer reads it and acts on it. +As a workflow matures, you start wanting behavior every workflow wants: create a PR and act on it when it merges or CI fails, or keep a specialist whose judgment persists across the whole session (a prose polisher). You could model such steps as stages of your own; they are common enough across workflows that they are factored out as mods instead. A mod is the hook mechanism: standardized behavior that hooks into the workflow's run without changing your workflow definition. The stages and gates in your README stay as they are; a mod is one markdown file in the workflow's `_mods/` directory, and the first officer reads it and acts on it. ## Lifecycle hooks From 74ce0fc9a2ba04db2781322a98fa9f95a6c851eb Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 18:56:28 -0700 Subject: [PATCH 107/115] =?UTF-8?q?docs=20site:=20external-tracker=20bridg?= =?UTF-8?q?e=20to=20its=20own=20page=20=E2=80=94=20intake=20by=20asking,?= =?UTF-8?q?=20split-root=20keeps=20only=20its=20own=20concerns?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/site/advanced/external-tracker.md | 12 ++++++++++++ docs/site/advanced/split-root-state.md | 15 ++------------- docs/site/reference/frontmatter-contract.md | 2 +- mkdocs.yml | 1 + 4 files changed, 16 insertions(+), 14 deletions(-) create mode 100644 docs/site/advanced/external-tracker.md diff --git a/docs/site/advanced/external-tracker.md b/docs/site/advanced/external-tracker.md new file mode 100644 index 00000000..3c04c9a4 --- /dev/null +++ b/docs/site/advanced/external-tracker.md @@ -0,0 +1,12 @@ +# Bridge an external tracker + +Your backlog may already live somewhere else: Linear, GitHub Issues, another ticket ledger. The bridge is asking, not configuring: tell the first officer to intake an external item ("intake GitHub PR #134") and it files an entity carrying the reference. The external system keeps owning intake, discussion, and assignment; Spacedock stays the execution workflow. + +Two flat frontmatter fields carry the reference (the [frontmatter contract](../reference/frontmatter-contract.md) explains why they stay flat): + +```yaml +issue: ENG-123 +source: linear +``` + +`issue` is the human-facing external reference; `source` records where the entity came from. Keep the tracker out of Spacedock's stage semantics: sync through entity creation, state changes, and stage reports, not tracker-specific stage rules. diff --git a/docs/site/advanced/split-root-state.md b/docs/site/advanced/split-root-state.md index c28b5ab3..bce8e5b7 100644 --- a/docs/site/advanced/split-root-state.md +++ b/docs/site/advanced/split-root-state.md @@ -1,20 +1,9 @@ # Split-root state -A busy workflow generates constant small state commits. Split-root keeps them off your code branch: the README and stage declarations stay on your main branch, while the mutable entity state (frontmatter updates, stage reports, archive moves) lives in a separate state checkout. Your code history stays clean, and several agents or operators can drive the same workflow at once. +A busy workflow generates constant small state commits. Split-root keeps them off your code branch. The README and stage declarations stay on your main branch; the mutable entity state (frontmatter updates, stage reports, archive moves) lives in a separate state checkout. Your code history stays clean, and several agents or operators can drive the same workflow at once. -The README [opts in with one `state:` field](../concepts/workflows-and-entities.md#keep-workflow-state-off-your-code-branch); the split is transparent, and you read the workflow exactly as you would a single-root one. On a fresh clone the state checkout is absent; run `spacedock state init` to restore it. The shipped [`docs/dev` workflow](https://github.com/spacedock-dev/spacedock/tree/main/docs/dev) runs split-root, a live example. +The README [opts in with one `state:` field](../concepts/workflows-and-entities.md#keep-workflow-state-off-your-code-branch); the split is transparent, and you read the workflow exactly as you would any other. On a fresh clone the state checkout is absent; run `spacedock state init` to restore it. The shipped [`docs/dev` workflow](https://github.com/spacedock-dev/spacedock/tree/main/docs/dev) runs split-root, a live example. ## Concurrent writers The agents follow the commit and sync discipline that keeps concurrent writers from clobbering each other; it is theirs to follow, not yours. The one case that reaches you: conflicting edits to the same entity halt for your call rather than auto-resolving. - -## Bridging an external tracker - -Split-root state is the integration point for an external tracker (Linear, GitHub Issues, or another ticket ledger). The external system can own backlog intake, discussion, and assignment while Spacedock stays the execution workflow. The bridge is two flat frontmatter fields (the [frontmatter contract](../reference/frontmatter-contract.md) explains why they stay flat): - -```yaml -issue: ENG-123 -source: linear -``` - -`issue` is the human-facing external reference; `source` records where the entity came from. Keep the tracker out of Spacedock's stage semantics: a bridge should sync through entity creation, state changes, and stage reports, not by adding tracker-specific stage rules. diff --git a/docs/site/reference/frontmatter-contract.md b/docs/site/reference/frontmatter-contract.md index 53d11810..e906b099 100644 --- a/docs/site/reference/frontmatter-contract.md +++ b/docs/site/reference/frontmatter-contract.md @@ -46,7 +46,7 @@ Fill `title`, `status`, and `source` at creation; the runtime writes the rest as ## External-tracker fields -`issue` and `source` are the bridge to an external ledger (Linear, GitHub Issues). `issue` is the human-facing ticket reference; `source` records the origin. Spacedock `status` stays the execution status, and the tracker does not redefine stage semantics inside the entity. See [Split-root state](../advanced/split-root-state.md#bridging-an-external-tracker) for the full bridge model. +`issue` and `source` are the bridge to an external ledger (Linear, GitHub Issues). `issue` is the human-facing ticket reference; `source` records the origin. Spacedock `status` stays the execution status, and the tracker does not redefine stage semantics inside the entity. See [Bridge an external tracker](../advanced/external-tracker.md) for the full bridge model. ## Validating an entity diff --git a/mkdocs.yml b/mkdocs.yml index 5f305760..e0194a72 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -85,6 +85,7 @@ nav: - Mods & standing teammates: advanced/mods-and-standing-teammates.md - Multiple workflows: advanced/multi-workflow.md - Split-root state: advanced/split-root-state.md + - Bridge an external tracker: advanced/external-tracker.md - Refit a workflow: advanced/refit.md - Reference: - Command reference: reference/command-reference.md From 3fba58367ae108cd90a409e06ceca6d39f5912b2 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 19:51:22 -0700 Subject: [PATCH 108/115] docs: frontmatter contract + mdschemas as SSOT; site links to it Bring the v0 frontmatter/state-machine contract into the repo, ported to v1: the two mdschema files under docs/schema/ are the source of truth for field names, types, patterns, and invariants; docs/frontmatter-contract.md is the light human companion covering what a schema cannot (directory layout, parser, worktree-aware reads, the state machine, write scope, versioning) and defers field-level detail to the schemas. Reconciled from the v0 branch: Go reference (internal/status/) not Python, no v0 corpus stats, no Python validator (status --validate is the live, partial checker). entity.mdschema known_corpus_failures emptied (v0 archive files). Site: reference/frontmatter-contract.md links the contract on main; external-tracker.md drops the stale entity-page cross-ref and states the flat-fields point inline. Co-Authored-By: Claude Fable 5 --- docs/frontmatter-contract.md | 111 ++++++++++++ docs/schema/entity.mdschema.yml | 166 +++++++++++++++++ docs/schema/workflow-readme.mdschema.yml | 190 ++++++++++++++++++++ docs/site/advanced/external-tracker.md | 2 +- docs/site/reference/frontmatter-contract.md | 2 +- 5 files changed, 469 insertions(+), 2 deletions(-) create mode 100644 docs/frontmatter-contract.md create mode 100644 docs/schema/entity.mdschema.yml create mode 100644 docs/schema/workflow-readme.mdschema.yml diff --git a/docs/frontmatter-contract.md b/docs/frontmatter-contract.md new file mode 100644 index 00000000..5f2762ad --- /dev/null +++ b/docs/frontmatter-contract.md @@ -0,0 +1,111 @@ +# Spacedock frontmatter and state-machine contract (v1.0) + +The machine-checkable contract is the two schemas under [`docs/schema/`](schema/): + +- [`schema/workflow-readme.mdschema.yml`](schema/workflow-readme.mdschema.yml) — the workflow `README.md` frontmatter shape and the required per-stage body subsections. +- [`schema/entity.mdschema.yml`](schema/entity.mdschema.yml) — entity frontmatter fields, the custom-field policy, recognized body headings, and the invariants. + +Those schemas are the source of truth for field names, types, patterns, defaults, and severities. This page does not restate them; it covers the parts a field table cannot express — directory layout, the parser, worktree-aware reads, the state machine, and versioning. When this prose and a schema disagree, the schema wins. The Go reference behavior lives in `internal/status/`. + +## Workflow directory layout + +```text +{workflow_dir}/ +|-- README.md workflow definition (workflow-readme.mdschema) +|-- .md flat entity (entity.mdschema) +|-- / folder entity +| `-- index.md +|-- _archive/ archived entities +|-- _mods/ lifecycle hooks and standing teammates +`-- _debriefs/ optional session debriefs +``` + +- Flat (`.md`) and folder (`/index.md`) entities are both valid. If both forms exist for one slug, the folder form wins and validation warns that the flat file should be removed. +- `_archive/`, `_mods/`, `_debriefs/`, and `_evidence/` are reserved support directories, not discovered as entities. Hidden entries (names starting with `.`) are skipped. +- The top-level `README.md` is the workflow definition, not an entity. + +## Parser semantics + +Spacedock parses only simple top-level frontmatter fields, line by line, to keep the contract close to the line-oriented writer. + +1. Lines between the opening and closing `---` fences are scanned. +2. A non-indented line containing `:` becomes a top-level key/value pair, split on the first colon. +3. Indented lines are nested content and are ignored by the top-level parser. +4. Matching surrounding single or double quotes are stripped. +5. `key:` with no value is the empty string. +6. Parsing stops at the closing `---` fence. +7. Writes are line-oriented: values are written verbatim, not YAML-escaped. + +A new read implementation may use a full YAML library only if it produces the same top-level key set as this parser on the active corpus. The write path must preserve line-oriented update semantics until a major-version change. + +## Worktree-aware reading + +Worktree-backed stages let a worker edit an isolated copy while the workflow directory keeps minimal discoverable metadata. Readers resolve the active copy before deciding which frontmatter is current. + +1. If `worktree` is empty, the active copy is the canonical copy in the workflow directory. +2. If `worktree` is non-empty, the active copy is `//` when that file exists. +3. If the worktree mirror is missing, reads fall back to the canonical copy. +4. When both exist, active-copy frontmatter overlays the canonical copy: active values win, canonical-only values are preserved. +5. `pr` is the only field that mirrors from a worktree-backed active copy back to the canonical copy, so pull-request state stays visible from the workflow root. + +## State machine + +File location (active vs archived, with or without an active worktree) is separate from stage progress (the `status` field within the workflow's declared stages). + +- **Blocked** means `mod-block` is non-empty. +- **Terminal** means `status` equals the one stage marked `terminal: true`. +- **Archived** means the entity has moved under `_archive/`. + +The default generated workflow is linear: + +```mermaid +stateDiagram-v2 + [*] --> backlog : commission + backlog --> ideation : approval gate + ideation --> implementation : approval gate + ideation --> ideation : rejected ideation + implementation --> validation : worker complete + validation --> done : approval gate + validation --> implementation : rejected validation + done --> [*] : archive +``` + +`gate: true` makes the first officer present the transition to the captain and wait for approval before leaving the stage. `worktree: true` runs that stage's dispatched work in a worktree. `feedback-to` names the rejection target. Non-linear workflows declare explicit `stages.transitions` edges; the validator checks each endpoint names a declared stage. + +### Transition guards + +| Transition | Guard | +|------------|-------| +| Any status to terminal | `mod-block` must be empty unless forced. | +| Any status to terminal, when merge hooks are registered | Either `pr` or `mod-block` must be non-empty unless forced, catching a missed merge-hook procedure. | +| Clear `mod-block` and set terminal in one command | Refused unless forced; the audit trail must show clearing the block and terminalizing as separate writes. | +| Archive an entity | `status` must already be terminal; archive does not advance status. | +| Set `worktree=` | No data-layer guard; first-officer procedure decides when a worktree is assigned. | + +### Mutation mechanics + +- The rewriter performs one read and one write: no temp file, lock, fsync, or rollback. +- The CLI does not invoke git. The first officer commits main-branch workflow state; the worker commits worktree-branch state. +- A successful mutation prints `field: -> ` per field; archive prints `archived: `. Exit code is 0 on success, 1 on refusal or error. + +## Entity write scope + +- The first officer owns workflow frontmatter on the main branch and mutates it through `spacedock status --set` or related commands. +- For worktree-backed stages, active body and report edits live in the worktree copy. +- Worker agents edit entity body text and project files in their assigned worktree; they do not edit workflow frontmatter. +- The first officer does not edit project code, tests, mods, or scaffolding on main; those go through a dispatched worker. + +## Stage report body convention + +A worker appends a `## Stage Report: ` section at the end of the entity body on stage completion; the first officer reads the last such report when deciding the next transition. Use `DONE:` / `SKIPPED:` / `FAILED:` per checklist item, include every dispatched item, keep evidence short, and append a new `## Stage Report: (cycle N)` section for feedback cycles rather than editing an older report. Schema validation recognizes the report heading but does not validate its prose. + +## Validation + +`spacedock status --workflow-dir --validate` is the live checker. It enforces a subset of the schemas: entity-form (flat/folder) conflicts, stage-name regex, per-`id-style` id presence and uniqueness, and (when the workflow opts in) the external-proof policy. It exits 0 when valid, 1 with errors on stderr otherwise. The schemas under `docs/schema/` carry the full field-level contract (types, patterns, per-field severities, invariants) that `--validate` does not yet check end to end. + +## Versioning and backward compatibility + +- This prose declares `Version: 1.0`; the schema files carry `"version": "1.0"`. +- Workflows advertise their authoring version through `commissioned-by: spacedock@`. +- v1.x may add compatible fields, optional sections, or warn-only conventions. It must not remove canonical fields, make optional fields required, change field types, or tighten a warn-only condition into a fail. Breaking changes require a v2.0 bump. +- An implementation should accept workflows whose `commissioned-by` version is at or below its supported version and refuse a newer unsupported one. diff --git a/docs/schema/entity.mdschema.yml b/docs/schema/entity.mdschema.yml new file mode 100644 index 00000000..cc0932c1 --- /dev/null +++ b/docs/schema/entity.mdschema.yml @@ -0,0 +1,166 @@ +{ + "version": "1.0", + "target": "entity", + "applies_to": { + "filename_pattern": ".md or /index.md", + "required_at": "workflow_root_or_archive" + }, + "frontmatter": { + "strict_canonical": true, + "permissive_additions": true, + "always_present": [ + "id", + "title", + "status", + "score", + "source", + "worktree" + ], + "optional_canonical": [ + "pr", + "started", + "completed", + "verdict", + "mod-block", + "archived", + "issue" + ], + "fields": { + "id": { + "type": "string", + "conditional": [ + { + "when": { + "workflow.id-style": "sequential" + }, + "rule": "non-negative integer rendered as a string", + "pattern": "^[0-9]+$" + }, + { + "when": { + "workflow.id-style": "sd-b32" + }, + "rule": "24-character Spacedock Base32 ID; legacy numeric IDs are warn-only for mixed workflows", + "pattern": "^[0123456789abcdefghjkmnpqrstvwxyz]{24}$", + "legacy_numeric_severity": "warn" + }, + { + "when": { + "workflow.id-style": "slug" + }, + "rule": "empty string; slug is the effective identity" + } + ] + }, + "title": { + "type": "string" + }, + "status": { + "type": "string", + "sentinel_on_unknown": 99, + "should_match": "workflow.stages.states[].name", + "unknown_severity": "warn" + }, + "score": { + "type": "numeric_string", + "coerce_empty": "last", + "coerce_invalid": 0, + "invalid_severity": "warn" + }, + "source": { + "type": "string" + }, + "worktree": { + "type": "string", + "semantics": "path relative to git root when non-empty; empty means no active worktree" + }, + "pr": { + "type": "string" + }, + "started": { + "type": "iso8601" + }, + "completed": { + "type": "iso8601" + }, + "verdict": { + "type": "string", + "conventional": [ + "PASSED", + "REJECTED" + ], + "invalid_severity": "warn" + }, + "mod-block": { + "type": "string", + "pattern": "^[^:]+:[^:]+$", + "invalid_severity": "warn", + "semantics": "when non-empty, terminal advancement is refused unless forced" + }, + "archived": { + "type": "iso8601" + }, + "issue": { + "type": "string" + } + }, + "custom_fields": { + "policy": "preserve_unknown", + "no_reserved_prefix": true, + "observed": { + "blocked-on": { + "type": "string", + "required": false, + "semantics": "upstream dependency reference that blocks entity progress" + }, + "blocked-reason": { + "type": "string", + "required": false, + "semantics": "human-readable reason for the blocked-on dependency" + }, + "depends": { + "type": "string", + "required": false, + "semantics": "legacy dependency reference preserved from archived entities" + } + } + } + }, + "body": { + "required_opening": "problem-statement paragraph before any heading", + "recognized_sections": [ + "## Acceptance criteria", + "## Test plan", + "## Stage Report: ", + "### Feedback Cycles" + ], + "stage_report_validation": "none" + }, + "invariants": [ + { + "id": "id_uniqueness", + "rule": "per id-style, ids unique across active + archived" + }, + { + "id": "slug_uniqueness", + "rule": "slugs unique across active + archived" + }, + { + "id": "mod_block_guard", + "rule": "mod-block non-empty AND status terminal -> refuse without --force" + }, + { + "id": "merge_hook_invariant", + "rule": "workflow has any _mods/*.md with ## Hook: merge AND pr empty AND mod-block empty -> refuse terminal without --force" + }, + { + "id": "two_step_audit", + "rule": "single --set cannot both clear mod-block and advance to terminal" + }, + { + "id": "pr_mirror", + "rule": "writing pr on worktree-backed entity also writes pr to canonical copy; no other field mirrors" + } + ], + "known_corpus_failures": {} +} diff --git a/docs/schema/workflow-readme.mdschema.yml b/docs/schema/workflow-readme.mdschema.yml new file mode 100644 index 00000000..b84e28d9 --- /dev/null +++ b/docs/schema/workflow-readme.mdschema.yml @@ -0,0 +1,190 @@ +{ + "version": "1.0", + "target": "workflow_readme", + "applies_to": { + "filename": "README.md", + "required_at": "workflow_root" + }, + "frontmatter": { + "strict_canonical": true, + "required": [ + "commissioned-by", + "entity-type", + "entity-label", + "entity-label-plural", + "id-style", + "stages" + ], + "optional": [ + "mission" + ], + "fields": { + "commissioned-by": { + "type": "string", + "pattern": "^spacedock@([0-9]+\\.[0-9]+\\.[0-9]+)?$", + "description": "The empty version alternative intentionally accepts bare spacedock@ stamps from early generated workflows." + }, + "entity-type": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]*$" + }, + "entity-label": { + "type": "string" + }, + "entity-label-plural": { + "type": "string" + }, + "id-style": { + "type": "string", + "enum": [ + "sequential", + "sd-b32", + "slug" + ] + }, + "mission": { + "type": "string" + }, + "stages": { + "type": "mapping", + "required": [ + "states" + ], + "optional": [ + "defaults", + "transitions" + ], + "shape": { + "defaults": { + "type": "mapping", + "fields": { + "worktree": { + "type": "boolean", + "default": false + }, + "concurrency": { + "type": "integer", + "minimum": 1, + "default": 2 + }, + "model": { + "type": "string", + "enum": [ + "sonnet", + "opus", + "haiku" + ] + } + } + }, + "states": { + "type": "sequence", + "min_items": 2, + "item": { + "type": "mapping", + "required": [ + "name" + ], + "fields": { + "name": { + "type": "string", + "pattern": "^[a-z0-9][a-z0-9-]*[a-z0-9]$" + }, + "initial": { + "type": "boolean" + }, + "terminal": { + "type": "boolean" + }, + "worktree": { + "type": "boolean" + }, + "concurrency": { + "type": "integer", + "minimum": 1 + }, + "gate": { + "type": "boolean" + }, + "fresh": { + "type": "boolean" + }, + "feedback-to": { + "type": "string" + }, + "agent": { + "type": "string" + }, + "model": { + "type": "string", + "enum": [ + "sonnet", + "opus", + "haiku" + ] + } + } + } + }, + "transitions": { + "type": "sequence", + "item": { + "type": "mapping", + "required": [ + "from", + "to" + ], + "fields": { + "from": { + "type": "string" + }, + "to": { + "type": "string" + }, + "label": { + "type": "string" + } + } + } + } + } + } + } + }, + "body": { + "required_sections_per_stage": { + "heading": "### `{stage_name}`", + "accept_bare": true, + "accept_annotated": true, + "required_bullets": [ + "Outputs:" + ], + "conventional_bullets": { + "severity": "warn", + "list": [ + "Inputs:", + "Good:", + "Bad:" + ] + } + } + }, + "invariants": [ + { + "id": "initial_cardinality", + "rule": "exactly one stage with initial:true AND it is the first list entry" + }, + { + "id": "terminal_cardinality", + "rule": "exactly one stage with terminal:true AND it is the last list entry" + }, + { + "id": "stage_subsection_present", + "rule": "every stages.states[].name has a matching ### heading in body" + }, + { + "id": "feedback_target_valid", + "rule": "feedback-to value (when present) names another stage in states[]" + } + ] +} diff --git a/docs/site/advanced/external-tracker.md b/docs/site/advanced/external-tracker.md index 3c04c9a4..e7d13b50 100644 --- a/docs/site/advanced/external-tracker.md +++ b/docs/site/advanced/external-tracker.md @@ -2,7 +2,7 @@ Your backlog may already live somewhere else: Linear, GitHub Issues, another ticket ledger. The bridge is asking, not configuring: tell the first officer to intake an external item ("intake GitHub PR #134") and it files an entity carrying the reference. The external system keeps owning intake, discussion, and assignment; Spacedock stays the execution workflow. -Two flat frontmatter fields carry the reference (the [frontmatter contract](../reference/frontmatter-contract.md) explains why they stay flat): +Two flat frontmatter fields carry the reference: ```yaml issue: ENG-123 diff --git a/docs/site/reference/frontmatter-contract.md b/docs/site/reference/frontmatter-contract.md index e906b099..3884b4da 100644 --- a/docs/site/reference/frontmatter-contract.md +++ b/docs/site/reference/frontmatter-contract.md @@ -1,6 +1,6 @@ # Frontmatter contract -Every entity is a markdown file (or a folder with an `index.md`) whose YAML frontmatter carries the fields Spacedock reads to track and move it. This page is a quick lookup for the fields a development-workflow entity uses. The always-current schema is owned by the [development workflow README](https://github.com/spacedock-dev/spacedock/blob/main/docs/dev/README.md#field-reference); when this table and that README disagree, the README wins. +Every entity is a markdown file (or a folder with an `index.md`) whose YAML frontmatter carries the fields Spacedock reads to track and move it. This page is a quick lookup for the fields a development-workflow entity uses. The always-current schema is owned by the [development workflow README](https://github.com/spacedock-dev/spacedock/blob/main/docs/dev/README.md#field-reference); when this table and that README disagree, the README wins. For the machine-checkable contract across all workflows (field types and patterns, the state machine, and invariants), see the [frontmatter and state-machine contract](https://github.com/spacedock-dev/spacedock/blob/main/docs/frontmatter-contract.md). Keep fields flat and top-level; add more flat custom fields rather than nested YAML. Spacedock reads frontmatter line by line, so nested values are ignored. From ed01893e9a4001892f41684d2d4d2c6e839092d5 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 20:00:14 -0700 Subject: [PATCH 109/115] docs site: frontmatter-contract page IS the contract; schemas are SSOT MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adopt the full contract as the reference page (parser, worktree-aware reads, the state machine and its guards), tuned reader-ward since it lives in reference: lead with the dev-workflow task entity and the copy-paste starter, defer field-level detail to the two mdschemas (now the field SSOT) linked on main. Drop the redundant standalone docs/frontmatter- contract.md — the site page is the one human-readable contract. The stage diagram carries its meaning in prose on both sides so llms.txt readers lose nothing. The two concept-page links drop the stale lists- every-field promise and point at what the page now delivers. Co-Authored-By: Claude Fable 5 --- docs/frontmatter-contract.md | 111 ------------------- docs/site/concepts/stage-lifecycle.md | 2 +- docs/site/concepts/workflows-and-entities.md | 2 +- docs/site/reference/frontmatter-contract.md | 72 +++++++----- 4 files changed, 47 insertions(+), 140 deletions(-) delete mode 100644 docs/frontmatter-contract.md diff --git a/docs/frontmatter-contract.md b/docs/frontmatter-contract.md deleted file mode 100644 index 5f2762ad..00000000 --- a/docs/frontmatter-contract.md +++ /dev/null @@ -1,111 +0,0 @@ -# Spacedock frontmatter and state-machine contract (v1.0) - -The machine-checkable contract is the two schemas under [`docs/schema/`](schema/): - -- [`schema/workflow-readme.mdschema.yml`](schema/workflow-readme.mdschema.yml) — the workflow `README.md` frontmatter shape and the required per-stage body subsections. -- [`schema/entity.mdschema.yml`](schema/entity.mdschema.yml) — entity frontmatter fields, the custom-field policy, recognized body headings, and the invariants. - -Those schemas are the source of truth for field names, types, patterns, defaults, and severities. This page does not restate them; it covers the parts a field table cannot express — directory layout, the parser, worktree-aware reads, the state machine, and versioning. When this prose and a schema disagree, the schema wins. The Go reference behavior lives in `internal/status/`. - -## Workflow directory layout - -```text -{workflow_dir}/ -|-- README.md workflow definition (workflow-readme.mdschema) -|-- .md flat entity (entity.mdschema) -|-- / folder entity -| `-- index.md -|-- _archive/ archived entities -|-- _mods/ lifecycle hooks and standing teammates -`-- _debriefs/ optional session debriefs -``` - -- Flat (`.md`) and folder (`/index.md`) entities are both valid. If both forms exist for one slug, the folder form wins and validation warns that the flat file should be removed. -- `_archive/`, `_mods/`, `_debriefs/`, and `_evidence/` are reserved support directories, not discovered as entities. Hidden entries (names starting with `.`) are skipped. -- The top-level `README.md` is the workflow definition, not an entity. - -## Parser semantics - -Spacedock parses only simple top-level frontmatter fields, line by line, to keep the contract close to the line-oriented writer. - -1. Lines between the opening and closing `---` fences are scanned. -2. A non-indented line containing `:` becomes a top-level key/value pair, split on the first colon. -3. Indented lines are nested content and are ignored by the top-level parser. -4. Matching surrounding single or double quotes are stripped. -5. `key:` with no value is the empty string. -6. Parsing stops at the closing `---` fence. -7. Writes are line-oriented: values are written verbatim, not YAML-escaped. - -A new read implementation may use a full YAML library only if it produces the same top-level key set as this parser on the active corpus. The write path must preserve line-oriented update semantics until a major-version change. - -## Worktree-aware reading - -Worktree-backed stages let a worker edit an isolated copy while the workflow directory keeps minimal discoverable metadata. Readers resolve the active copy before deciding which frontmatter is current. - -1. If `worktree` is empty, the active copy is the canonical copy in the workflow directory. -2. If `worktree` is non-empty, the active copy is `//` when that file exists. -3. If the worktree mirror is missing, reads fall back to the canonical copy. -4. When both exist, active-copy frontmatter overlays the canonical copy: active values win, canonical-only values are preserved. -5. `pr` is the only field that mirrors from a worktree-backed active copy back to the canonical copy, so pull-request state stays visible from the workflow root. - -## State machine - -File location (active vs archived, with or without an active worktree) is separate from stage progress (the `status` field within the workflow's declared stages). - -- **Blocked** means `mod-block` is non-empty. -- **Terminal** means `status` equals the one stage marked `terminal: true`. -- **Archived** means the entity has moved under `_archive/`. - -The default generated workflow is linear: - -```mermaid -stateDiagram-v2 - [*] --> backlog : commission - backlog --> ideation : approval gate - ideation --> implementation : approval gate - ideation --> ideation : rejected ideation - implementation --> validation : worker complete - validation --> done : approval gate - validation --> implementation : rejected validation - done --> [*] : archive -``` - -`gate: true` makes the first officer present the transition to the captain and wait for approval before leaving the stage. `worktree: true` runs that stage's dispatched work in a worktree. `feedback-to` names the rejection target. Non-linear workflows declare explicit `stages.transitions` edges; the validator checks each endpoint names a declared stage. - -### Transition guards - -| Transition | Guard | -|------------|-------| -| Any status to terminal | `mod-block` must be empty unless forced. | -| Any status to terminal, when merge hooks are registered | Either `pr` or `mod-block` must be non-empty unless forced, catching a missed merge-hook procedure. | -| Clear `mod-block` and set terminal in one command | Refused unless forced; the audit trail must show clearing the block and terminalizing as separate writes. | -| Archive an entity | `status` must already be terminal; archive does not advance status. | -| Set `worktree=` | No data-layer guard; first-officer procedure decides when a worktree is assigned. | - -### Mutation mechanics - -- The rewriter performs one read and one write: no temp file, lock, fsync, or rollback. -- The CLI does not invoke git. The first officer commits main-branch workflow state; the worker commits worktree-branch state. -- A successful mutation prints `field: -> ` per field; archive prints `archived: `. Exit code is 0 on success, 1 on refusal or error. - -## Entity write scope - -- The first officer owns workflow frontmatter on the main branch and mutates it through `spacedock status --set` or related commands. -- For worktree-backed stages, active body and report edits live in the worktree copy. -- Worker agents edit entity body text and project files in their assigned worktree; they do not edit workflow frontmatter. -- The first officer does not edit project code, tests, mods, or scaffolding on main; those go through a dispatched worker. - -## Stage report body convention - -A worker appends a `## Stage Report: ` section at the end of the entity body on stage completion; the first officer reads the last such report when deciding the next transition. Use `DONE:` / `SKIPPED:` / `FAILED:` per checklist item, include every dispatched item, keep evidence short, and append a new `## Stage Report: (cycle N)` section for feedback cycles rather than editing an older report. Schema validation recognizes the report heading but does not validate its prose. - -## Validation - -`spacedock status --workflow-dir --validate` is the live checker. It enforces a subset of the schemas: entity-form (flat/folder) conflicts, stage-name regex, per-`id-style` id presence and uniqueness, and (when the workflow opts in) the external-proof policy. It exits 0 when valid, 1 with errors on stderr otherwise. The schemas under `docs/schema/` carry the full field-level contract (types, patterns, per-field severities, invariants) that `--validate` does not yet check end to end. - -## Versioning and backward compatibility - -- This prose declares `Version: 1.0`; the schema files carry `"version": "1.0"`. -- Workflows advertise their authoring version through `commissioned-by: spacedock@`. -- v1.x may add compatible fields, optional sections, or warn-only conventions. It must not remove canonical fields, make optional fields required, change field types, or tighten a warn-only condition into a fail. Breaking changes require a v2.0 bump. -- An implementation should accept workflows whose `commissioned-by` version is at or below its supported version and refuse a newer unsupported one. diff --git a/docs/site/concepts/stage-lifecycle.md b/docs/site/concepts/stage-lifecycle.md index e8106f96..1cb9d98b 100644 --- a/docs/site/concepts/stage-lifecycle.md +++ b/docs/site/concepts/stage-lifecycle.md @@ -36,4 +36,4 @@ When a stage declares `worktree: true`, everything from that stage onward happen - [The operating model](operating-model.md) for who does what: you, the orchestrator, the workers. - [Gates and decisions](gates-and-decisions.md) to see exactly what you decide at a stage boundary and on what evidence. -- The [frontmatter contract](../reference/frontmatter-contract.md) to look up the fields these stages write. +- The [frontmatter contract](../reference/frontmatter-contract.md) for the state these stages write and how an entity moves through them. diff --git a/docs/site/concepts/workflows-and-entities.md b/docs/site/concepts/workflows-and-entities.md index a68ae29e..b69dcdca 100644 --- a/docs/site/concepts/workflows-and-entities.md +++ b/docs/site/concepts/workflows-and-entities.md @@ -36,7 +36,7 @@ stages: ## Each work item is one file -An entity lives as a flat file `{slug}.md`, or a folder `{slug}/index.md` when reports and artifacts accumulate beside it. The body is the human-readable record: the problem, the approach, the acceptance criteria, and the stage reports. On top sits YAML frontmatter, the machine-readable state: the item's id, its current stage, its outcome. The [frontmatter contract](../reference/frontmatter-contract.md) lists every field. +An entity lives as a flat file `{slug}.md`, or a folder `{slug}/index.md` when reports and artifacts accumulate beside it. The body is the human-readable record: the problem, the approach, the acceptance criteria, and the stage reports. On top sits YAML frontmatter, the machine-readable state: the item's id, its current stage, its outcome. The [frontmatter contract](../reference/frontmatter-contract.md) covers how that state is read and how an entity moves through it. ## Keep workflow state off your code branch diff --git a/docs/site/reference/frontmatter-contract.md b/docs/site/reference/frontmatter-contract.md index 3884b4da..e3814ce8 100644 --- a/docs/site/reference/frontmatter-contract.md +++ b/docs/site/reference/frontmatter-contract.md @@ -1,31 +1,17 @@ # Frontmatter contract -Every entity is a markdown file (or a folder with an `index.md`) whose YAML frontmatter carries the fields Spacedock reads to track and move it. This page is a quick lookup for the fields a development-workflow entity uses. The always-current schema is owned by the [development workflow README](https://github.com/spacedock-dev/spacedock/blob/main/docs/dev/README.md#field-reference); when this table and that README disagree, the README wins. For the machine-checkable contract across all workflows (field types and patterns, the state machine, and invariants), see the [frontmatter and state-machine contract](https://github.com/spacedock-dev/spacedock/blob/main/docs/frontmatter-contract.md). +Every entity is a markdown file (`{slug}.md`, or a folder `{slug}/index.md` when reports and artifacts pile up beside it). Its YAML frontmatter is the machine-readable state Spacedock reads to track and move it; the body below is the human record (problem, approach, acceptance criteria, stage reports). -Keep fields flat and top-level; add more flat custom fields rather than nested YAML. Spacedock reads frontmatter line by line, so nested values are ignored. +The field-level contract (names, types, patterns, defaults, invariants) is the two machine-checkable schemas: -## Entity fields +- [`workflow-readme.mdschema.yml`](https://github.com/spacedock-dev/spacedock/blob/main/docs/schema/workflow-readme.mdschema.yml) — the workflow `README.md` frontmatter and the required per-stage body subsections. +- [`entity.mdschema.yml`](https://github.com/spacedock-dev/spacedock/blob/main/docs/schema/entity.mdschema.yml) — entity frontmatter fields, the custom-field policy, recognized body headings, and the invariants. -These are the fields the development workflow declares for a `task` entity. Other workflows may rename the entity type and adjust fields. +Those schemas are the source of truth. This page covers what a field table can't: how the frontmatter is parsed, how worktree-backed reads resolve, and how an entity moves through stages. When this page and a schema disagree, the schema wins. -| Field | Type | Description | -|-------|------|-------------| -| `id` | string | Unique 24-character Spacedock Base32 ID (this workflow uses `id-style: sd-b32`). | -| `title` | string | Human-readable entity name. | -| `status` | enum | The current stage: `backlog`, `ideation`, `implementation`, `validation`, or `done`. | -| `source` | string | Where the entity came from. Also used by the external-tracker bridge. | -| `started` | ISO 8601 | When active work began. | -| `completed` | ISO 8601 | When the entity reached terminal status. | -| `verdict` | enum | `PASSED` or `REJECTED`, set at the final stage. A terminal close requires it; see [gates and decisions](../concepts/gates-and-decisions.md#the-three-calls). | -| `score` | number | Priority score, `0.0`–`1.0` (optional). | -| `worktree` | string | Worktree path while a dispatched agent is active; empty otherwise. | -| `issue` | string | Optional external ticket reference, such as `ENG-123` or `owner/repo#42`. | +## A development-workflow entity -`status` is the execution state: `spacedock status` reports each entity's `status` against the README's stage declarations, and `--set status=` advances it. The fields the runtime writes (`started`, `completed`, `verdict`, `worktree`) should not be hand-edited while a dispatched agent is active. - -## Copy-paste starter - -The development workflow's task template ships these fields blank for a new entity: +The fields you see most often are the ones the development workflow declares for a `task`. Other workflows rename the entity type and adjust the set, but the shape is the same. A new entity ships with these blank, and the runtime fills the rest as the entity moves: ```yaml --- @@ -42,18 +28,50 @@ issue: --- ``` -Fill `title`, `status`, and `source` at creation; the runtime writes the rest as the entity moves. +You fill `title`, `status`, and `source` at creation. `status` is the execution state: it names the current stage (`backlog`, `ideation`, `implementation`, `validation`, `done` for this workflow), and the first officer advances it as work moves. The runtime owns `started`, `completed`, `verdict` (`PASSED` or `REJECTED` at the [final gate](../concepts/gates-and-decisions.md#the-three-calls)), and `worktree`; don't hand-edit those while a dispatched agent is active. -## External-tracker fields +## Keep fields flat + +Spacedock parses only simple top-level frontmatter, line by line: + +- A non-indented `key: value` line becomes a field; the value is split on the first colon and surrounding quotes are stripped. +- Indented lines are treated as nested YAML and ignored. Add more flat custom fields rather than nesting; custom keys are preserved, filterable, and shown in all-field output. +- `key:` with no value is the empty string. Parsing stops at the closing `---`. + +## Worktree-aware reading + +A worktree-backed stage edits an isolated copy while the workflow directory keeps minimal discoverable state. Readers resolve the active copy before trusting any field: -`issue` and `source` are the bridge to an external ledger (Linear, GitHub Issues). `issue` is the human-facing ticket reference; `source` records the origin. Spacedock `status` stays the execution status, and the tracker does not redefine stage semantics inside the entity. See [Bridge an external tracker](../advanced/external-tracker.md) for the full bridge model. +- Empty `worktree`: the active copy is the canonical file in the workflow directory. +- Non-empty `worktree`: the active copy is the matching file under `//` when it exists; if it's missing, reads fall back to the canonical copy. +- When both exist, active-copy fields overlay the canonical copy. `pr` is the only field mirrored back to the canonical copy, so pull-request state stays visible from the workflow root. + +## How an entity moves + +File location (active vs archived) is separate from stage progress (the `status` field). The default workflow is linear, with a gate before the terminal stage and a rejection path back from validation: + +```mermaid +stateDiagram-v2 + [*] --> backlog : commission + backlog --> ideation : approval gate + ideation --> implementation : approval gate + ideation --> ideation : rejected ideation + implementation --> validation : worker complete + validation --> done : approval gate + validation --> implementation : rejected validation + done --> [*] : archive +``` + +The first officer commissions at `backlog`, gates ask you to approve before leaving a stage, validation can bounce back to implementation on a rejection, and `done` archives. A few guards protect the terminal move: an entity with a non-empty `mod-block` (a lifecycle hook still in flight) won't terminalize without force, and clearing a block and terminalizing must be two separate writes so the audit trail stays honest. Archiving requires the entity to already be terminal. + +## External-tracker fields -## Validating an entity +`issue` and `source` bridge to an external ledger (Linear, GitHub Issues). `issue` is the human-facing ticket reference; `source` records the origin. The tracker keeps owning intake and discussion; Spacedock `status` stays the execution state. See [Bridge an external tracker](../advanced/external-tracker.md) for the model. -Check the workflow and its entities against the contract: +## Validating a workflow ```bash spacedock status --workflow-dir docs/dev --validate ``` -It exits 0 when valid, 1 with errors on stderr otherwise. Validation reads stages from the README and entities from the state checkout, so it enforces the schema the workflow declares. +It checks entities against the contract and exits 0 when valid, 1 with errors on stderr. It enforces a subset of the schemas (entity-form conflicts, stage-name rules, id uniqueness, and the opt-in external-proof policy); the schemas above carry the full field-level contract. From 3861cf7c410ac3995d5c90359c538fb78b212809 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 20:01:19 -0700 Subject: [PATCH 110/115] docs site: drop the duplicate stage diagram from the contract page The stage lifecycle already owns the entity-movement picture (the linear chain with gate borders). The contract page keeps only what it uniquely owns: the terminal guards (mod-block, the two-step audit, archive-requires- terminal), and links to stage-lifecycle for movement. Co-Authored-By: Claude Fable 5 --- docs/site/concepts/stage-lifecycle.md | 2 +- docs/site/reference/frontmatter-contract.md | 18 ++---------------- 2 files changed, 3 insertions(+), 17 deletions(-) diff --git a/docs/site/concepts/stage-lifecycle.md b/docs/site/concepts/stage-lifecycle.md index 1cb9d98b..9c71d1cd 100644 --- a/docs/site/concepts/stage-lifecycle.md +++ b/docs/site/concepts/stage-lifecycle.md @@ -36,4 +36,4 @@ When a stage declares `worktree: true`, everything from that stage onward happen - [The operating model](operating-model.md) for who does what: you, the orchestrator, the workers. - [Gates and decisions](gates-and-decisions.md) to see exactly what you decide at a stage boundary and on what evidence. -- The [frontmatter contract](../reference/frontmatter-contract.md) for the state these stages write and how an entity moves through them. +- The [frontmatter contract](../reference/frontmatter-contract.md) for the state these stages write and read. diff --git a/docs/site/reference/frontmatter-contract.md b/docs/site/reference/frontmatter-contract.md index e3814ce8..c26732ed 100644 --- a/docs/site/reference/frontmatter-contract.md +++ b/docs/site/reference/frontmatter-contract.md @@ -46,23 +46,9 @@ A worktree-backed stage edits an isolated copy while the workflow directory keep - Non-empty `worktree`: the active copy is the matching file under `//` when it exists; if it's missing, reads fall back to the canonical copy. - When both exist, active-copy fields overlay the canonical copy. `pr` is the only field mirrored back to the canonical copy, so pull-request state stays visible from the workflow root. -## How an entity moves - -File location (active vs archived) is separate from stage progress (the `status` field). The default workflow is linear, with a gate before the terminal stage and a rejection path back from validation: - -```mermaid -stateDiagram-v2 - [*] --> backlog : commission - backlog --> ideation : approval gate - ideation --> implementation : approval gate - ideation --> ideation : rejected ideation - implementation --> validation : worker complete - validation --> done : approval gate - validation --> implementation : rejected validation - done --> [*] : archive -``` +## Terminal guards -The first officer commissions at `backlog`, gates ask you to approve before leaving a stage, validation can bounce back to implementation on a rejection, and `done` archives. A few guards protect the terminal move: an entity with a non-empty `mod-block` (a lifecycle hook still in flight) won't terminalize without force, and clearing a block and terminalizing must be two separate writes so the audit trail stays honest. Archiving requires the entity to already be terminal. +File location (active vs archived) is separate from stage progress (the `status` field); [the stage lifecycle](../concepts/stage-lifecycle.md) covers how an entity moves through stages and gates. The contract adds a few guards on the terminal move: an entity with a non-empty `mod-block` (a lifecycle hook still in flight) won't terminalize without force, and clearing a block and terminalizing must be two separate writes so the audit trail stays honest. Archiving requires the entity to already be terminal. ## External-tracker fields From 90db73df5437497a091fffaffa55cb05b0e319fb Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 20:07:22 -0700 Subject: [PATCH 111/115] =?UTF-8?q?docs=20site:=20frontmatter-contract=20i?= =?UTF-8?q?s=20a=20reference=20stub=20=E2=80=94=20schemas=20+=20fields=20o?= =?UTF-8?q?nly?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A reference page optimizes for lookup. Cut the borrowed explanation that other pages or the schemas own: the entity-file definition (workflows-and- entities owns it), worktree-aware reads and terminal guards (too detailed for the user site), and the parser section (false for the Go runtime, which uses a real YAML parser — multi-line is supported, not line-by-line). What remains: the two mdschema links (field SSOT) and the dev-task field starter. Concept-page links re-pointed to what the page now is. Co-Authored-By: Claude Fable 5 --- docs/site/concepts/stage-lifecycle.md | 2 +- docs/site/concepts/workflows-and-entities.md | 2 +- docs/site/reference/frontmatter-contract.md | 42 ++------------------ 3 files changed, 5 insertions(+), 41 deletions(-) diff --git a/docs/site/concepts/stage-lifecycle.md b/docs/site/concepts/stage-lifecycle.md index 9c71d1cd..0d09d8f5 100644 --- a/docs/site/concepts/stage-lifecycle.md +++ b/docs/site/concepts/stage-lifecycle.md @@ -36,4 +36,4 @@ When a stage declares `worktree: true`, everything from that stage onward happen - [The operating model](operating-model.md) for who does what: you, the orchestrator, the workers. - [Gates and decisions](gates-and-decisions.md) to see exactly what you decide at a stage boundary and on what evidence. -- The [frontmatter contract](../reference/frontmatter-contract.md) for the state these stages write and read. +- The [frontmatter contract](../reference/frontmatter-contract.md) for the fields these stages write. diff --git a/docs/site/concepts/workflows-and-entities.md b/docs/site/concepts/workflows-and-entities.md index b69dcdca..605fa254 100644 --- a/docs/site/concepts/workflows-and-entities.md +++ b/docs/site/concepts/workflows-and-entities.md @@ -36,7 +36,7 @@ stages: ## Each work item is one file -An entity lives as a flat file `{slug}.md`, or a folder `{slug}/index.md` when reports and artifacts accumulate beside it. The body is the human-readable record: the problem, the approach, the acceptance criteria, and the stage reports. On top sits YAML frontmatter, the machine-readable state: the item's id, its current stage, its outcome. The [frontmatter contract](../reference/frontmatter-contract.md) covers how that state is read and how an entity moves through it. +An entity lives as a flat file `{slug}.md`, or a folder `{slug}/index.md` when reports and artifacts accumulate beside it. The body is the human-readable record: the problem, the approach, the acceptance criteria, and the stage reports. On top sits YAML frontmatter, the machine-readable state: the item's id, its current stage, its outcome. The [frontmatter contract](../reference/frontmatter-contract.md) has the fields and the schemas that define them. ## Keep workflow state off your code branch diff --git a/docs/site/reference/frontmatter-contract.md b/docs/site/reference/frontmatter-contract.md index c26732ed..5da4a97a 100644 --- a/docs/site/reference/frontmatter-contract.md +++ b/docs/site/reference/frontmatter-contract.md @@ -1,17 +1,13 @@ # Frontmatter contract -Every entity is a markdown file (`{slug}.md`, or a folder `{slug}/index.md` when reports and artifacts pile up beside it). Its YAML frontmatter is the machine-readable state Spacedock reads to track and move it; the body below is the human record (problem, approach, acceptance criteria, stage reports). - -The field-level contract (names, types, patterns, defaults, invariants) is the two machine-checkable schemas: +An entity's YAML frontmatter is the machine-readable state Spacedock reads to track and move it. The field-level contract (names, types, patterns, defaults, invariants) is the two machine-checkable schemas: - [`workflow-readme.mdschema.yml`](https://github.com/spacedock-dev/spacedock/blob/main/docs/schema/workflow-readme.mdschema.yml) — the workflow `README.md` frontmatter and the required per-stage body subsections. - [`entity.mdschema.yml`](https://github.com/spacedock-dev/spacedock/blob/main/docs/schema/entity.mdschema.yml) — entity frontmatter fields, the custom-field policy, recognized body headings, and the invariants. -Those schemas are the source of truth. This page covers what a field table can't: how the frontmatter is parsed, how worktree-backed reads resolve, and how an entity moves through stages. When this page and a schema disagree, the schema wins. - ## A development-workflow entity -The fields you see most often are the ones the development workflow declares for a `task`. Other workflows rename the entity type and adjust the set, but the shape is the same. A new entity ships with these blank, and the runtime fills the rest as the entity moves: +The fields you see most often are the ones the development workflow declares for a `task`. A new entity ships with these blank, and the runtime fills the rest as the entity moves: ```yaml --- @@ -28,36 +24,4 @@ issue: --- ``` -You fill `title`, `status`, and `source` at creation. `status` is the execution state: it names the current stage (`backlog`, `ideation`, `implementation`, `validation`, `done` for this workflow), and the first officer advances it as work moves. The runtime owns `started`, `completed`, `verdict` (`PASSED` or `REJECTED` at the [final gate](../concepts/gates-and-decisions.md#the-three-calls)), and `worktree`; don't hand-edit those while a dispatched agent is active. - -## Keep fields flat - -Spacedock parses only simple top-level frontmatter, line by line: - -- A non-indented `key: value` line becomes a field; the value is split on the first colon and surrounding quotes are stripped. -- Indented lines are treated as nested YAML and ignored. Add more flat custom fields rather than nesting; custom keys are preserved, filterable, and shown in all-field output. -- `key:` with no value is the empty string. Parsing stops at the closing `---`. - -## Worktree-aware reading - -A worktree-backed stage edits an isolated copy while the workflow directory keeps minimal discoverable state. Readers resolve the active copy before trusting any field: - -- Empty `worktree`: the active copy is the canonical file in the workflow directory. -- Non-empty `worktree`: the active copy is the matching file under `//` when it exists; if it's missing, reads fall back to the canonical copy. -- When both exist, active-copy fields overlay the canonical copy. `pr` is the only field mirrored back to the canonical copy, so pull-request state stays visible from the workflow root. - -## Terminal guards - -File location (active vs archived) is separate from stage progress (the `status` field); [the stage lifecycle](../concepts/stage-lifecycle.md) covers how an entity moves through stages and gates. The contract adds a few guards on the terminal move: an entity with a non-empty `mod-block` (a lifecycle hook still in flight) won't terminalize without force, and clearing a block and terminalizing must be two separate writes so the audit trail stays honest. Archiving requires the entity to already be terminal. - -## External-tracker fields - -`issue` and `source` bridge to an external ledger (Linear, GitHub Issues). `issue` is the human-facing ticket reference; `source` records the origin. The tracker keeps owning intake and discussion; Spacedock `status` stays the execution state. See [Bridge an external tracker](../advanced/external-tracker.md) for the model. - -## Validating a workflow - -```bash -spacedock status --workflow-dir docs/dev --validate -``` - -It checks entities against the contract and exits 0 when valid, 1 with errors on stderr. It enforces a subset of the schemas (entity-form conflicts, stage-name rules, id uniqueness, and the opt-in external-proof policy); the schemas above carry the full field-level contract. +You fill `title`, `status`, and `source` at creation. `status` names the current stage (`backlog`, `ideation`, `implementation`, `validation`, `done` for this workflow), and the first officer advances it as work moves. The runtime owns `started`, `completed`, `verdict` (`PASSED` or `REJECTED` at the [final gate](../concepts/gates-and-decisions.md#the-three-calls)), and `worktree`; don't hand-edit those while a dispatched agent is active. From 8924d8feef480865108b085e2baa492a8175c3ee Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 20:07:47 -0700 Subject: [PATCH 112/115] =?UTF-8?q?docs=20site:=20external-tracker=20?= =?UTF-8?q?=E2=80=94=20frontmatter=20fields,=20not=20'flat'=20(parser=20no?= =?UTF-8?q?=20longer=20line-oriented)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Fable 5 --- docs/site/advanced/external-tracker.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/site/advanced/external-tracker.md b/docs/site/advanced/external-tracker.md index e7d13b50..ff5d8b8e 100644 --- a/docs/site/advanced/external-tracker.md +++ b/docs/site/advanced/external-tracker.md @@ -2,7 +2,7 @@ Your backlog may already live somewhere else: Linear, GitHub Issues, another ticket ledger. The bridge is asking, not configuring: tell the first officer to intake an external item ("intake GitHub PR #134") and it files an entity carrying the reference. The external system keeps owning intake, discussion, and assignment; Spacedock stays the execution workflow. -Two flat frontmatter fields carry the reference: +Two frontmatter fields carry the reference: ```yaml issue: ENG-123 From 1f17ed3fe2f1a4bf97e472a520433869ae81cddb Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 20:08:45 -0700 Subject: [PATCH 113/115] =?UTF-8?q?docs=20site:=20frontmatter-contract=20?= =?UTF-8?q?=E2=80=94=20two=20subsections=20(README,=20entity),=20reader's?= =?UTF-8?q?=20seat?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The user operates through the agent, not by hand-editing frontmatter, so the copy-paste starter and the which-fields-you-fill prose were wrong-seat. Replace with two subsections, one per contract target — workflow README and entity — each naming what its schema governs and linking it. Co-Authored-By: Claude Fable 5 --- docs/site/reference/frontmatter-contract.md | 26 ++++----------------- 1 file changed, 5 insertions(+), 21 deletions(-) diff --git a/docs/site/reference/frontmatter-contract.md b/docs/site/reference/frontmatter-contract.md index 5da4a97a..d18aa1d0 100644 --- a/docs/site/reference/frontmatter-contract.md +++ b/docs/site/reference/frontmatter-contract.md @@ -1,27 +1,11 @@ # Frontmatter contract -An entity's YAML frontmatter is the machine-readable state Spacedock reads to track and move it. The field-level contract (names, types, patterns, defaults, invariants) is the two machine-checkable schemas: +Spacedock reads YAML frontmatter as the machine-readable state of a workflow and its entities. The first officer and dispatched workers write it; you operate through them, not by hand-editing. The field-level contract (names, types, patterns, defaults, invariants) is two machine-checkable schemas. -- [`workflow-readme.mdschema.yml`](https://github.com/spacedock-dev/spacedock/blob/main/docs/schema/workflow-readme.mdschema.yml) — the workflow `README.md` frontmatter and the required per-stage body subsections. -- [`entity.mdschema.yml`](https://github.com/spacedock-dev/spacedock/blob/main/docs/schema/entity.mdschema.yml) — entity frontmatter fields, the custom-field policy, recognized body headings, and the invariants. +## Workflow README -## A development-workflow entity +The workflow `README.md` frontmatter declares the entity type, the id style, and the stages with their per-stage defaults and gates. The contract is [`workflow-readme.mdschema.yml`](https://github.com/spacedock-dev/spacedock/blob/main/docs/schema/workflow-readme.mdschema.yml), which also specifies the required per-stage body subsections. -The fields you see most often are the ones the development workflow declares for a `task`. A new entity ships with these blank, and the runtime fills the rest as the entity moves: +## Entity -```yaml ---- -id: -title: Task name here -status: backlog -source: -started: -completed: -verdict: -score: -worktree: -issue: ---- -``` - -You fill `title`, `status`, and `source` at creation. `status` names the current stage (`backlog`, `ideation`, `implementation`, `validation`, `done` for this workflow), and the first officer advances it as work moves. The runtime owns `started`, `completed`, `verdict` (`PASSED` or `REJECTED` at the [final gate](../concepts/gates-and-decisions.md#the-three-calls)), and `worktree`; don't hand-edit those while a dispatched agent is active. +Each entity's frontmatter carries its id, current stage, outcome, and worktree state. The contract is [`entity.mdschema.yml`](https://github.com/spacedock-dev/spacedock/blob/main/docs/schema/entity.mdschema.yml), which defines the fields, the custom-field policy, the recognized body headings, and the invariants. From 8017d9187431d7a2505344aa38cab5aadfbbfd77 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 20:12:07 -0700 Subject: [PATCH 114/115] =?UTF-8?q?docs=20site:=20command-reference=20?= =?UTF-8?q?=E2=80=94=20split=20the=20Workflow=20group=20by=20audience?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Workflow commands aren't all the reader's: state and completion are yours (split-root checkout on a fresh clone, shell completion), while status, new, and dispatch are the first officer's against workflow state. Split the section into 'Yours to run' and 'The first officer's', which reconciles with operating.md's 'no status commands to learn'. Name new's SLUG arg and dispatch's subcommands for reference exactness; drop the brittle subcommand count and the agent-internal status resolution order. Co-Authored-By: Claude Fable 5 --- docs/site/reference/command-reference.md | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/docs/site/reference/command-reference.md b/docs/site/reference/command-reference.md index 01c28c5d..e35b3c9c 100644 --- a/docs/site/reference/command-reference.md +++ b/docs/site/reference/command-reference.md @@ -1,6 +1,6 @@ # Command reference -The `spacedock` binary has ten subcommands in three groups, plus a top-level `--version`. This page is the map: what each command is for and when you reach for it. For the exact flags of any command, run `spacedock --help`, which is the always-current source of truth. +The `spacedock` binary groups its subcommands into Launch, Setup, and Workflow, plus a top-level `--version`. This page is the map: what each command does, and which are yours to run versus the ones the first officer runs against workflow state. For the exact flags of any command, run `spacedock --help`, which is the always-current source of truth. | Command | Group | What it does | |---------|-------|--------------| @@ -10,7 +10,7 @@ The `spacedock` binary has ten subcommands in three groups, plus a top-level `-- | [`spacedock install`](#setup) | Setup | Install the per-host plugin, then run the compatibility check | | [`spacedock doctor`](#setup) | Setup | Run the compatibility check alone | | [`spacedock status`](#workflow) | Workflow | Read or mutate workflow state: the table, `--next`, `--where`, `--set` | -| [`spacedock new`](#workflow) | Workflow | Create an entity from stdin | +| [`spacedock new`](#workflow) | Workflow | Create an entity (`new [--folder] SLUG`, body on stdin) | | [`spacedock state`](#workflow) | Workflow | Manage a split-root workflow's state checkout | | [`spacedock completion`](#workflow) | Workflow | Print a bash or zsh completion script | | [`spacedock dispatch`](#workflow) | Workflow | Build the dispatch artifacts the first officer hands an ensign | @@ -34,12 +34,17 @@ The task comes first and becomes the launch prompt. Anything after `--` forwards ## Workflow -These commands read and mutate workflow state. +These commands read and mutate workflow state. Two are yours; the rest the first officer runs as it moves entities. -- **`status`** is the main one: with no flag it prints the entity table, `--next` lists what is ready to dispatch, `--where` filters, `--set` mutates frontmatter, `--validate` checks the workflow, and `--boot` prints the first-officer boot view. It resolves the workflow from `--workflow-dir`, then `PIPELINE_DIR`, then by walking up to the enclosing workflow. The day-to-day reads are covered in [Operate a workflow](../running-workflows/operating.md). -- **`new`** creates an entity from stdin. -- **`state`** initializes or creates the state checkout for a [split-root workflow](../advanced/split-root-state.md). -- **`completion`** prints a bash or zsh completion script. -- **`dispatch`** builds the worker dispatch artifacts the first officer hands an ensign. +Yours to run: + +- **`state`** initializes the state checkout for a [split-root workflow](../advanced/split-root-state.md) on a fresh clone. +- **`completion`** prints a bash or zsh completion script to install. + +The first officer's, against workflow state: + +- **`status`** reads and mutates the state: with no flag it prints the entity table, `--next` lists what is ready to dispatch, `--where` filters, `--set` mutates frontmatter, `--validate` checks the workflow, and `--boot` prints the first-officer boot view. [Operate a workflow](../running-workflows/operating.md) covers how the first officer uses it on your behalf. +- **`new`** creates an entity (`new [--folder] SLUG`) from a body on stdin. +- **`dispatch`** (`dispatch build`, `dispatch show-stage-def`) builds the worker dispatch artifacts the first officer hands an ensign. Run `spacedock status --help` (and the same for each command) for the full flag list, the mutation guards, and the exit codes. From e5cf2f9cec8a4da91240a21c543a7895a56ad912 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Fri, 12 Jun 2026 20:16:32 -0700 Subject: [PATCH 115/115] =?UTF-8?q?docs=20site:=20command-reference=20?= =?UTF-8?q?=E2=80=94=20section=20tables,=20agent-driven=20Workflow=20group?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Restructure the page: drop the monolithic top table for per-section tables (the big undifferentiated list carried no structure). Launch is prose-only (its table duplicated the prose). The Workflow group is all agent-driven — the first officer runs status/new/dispatch/state/completion against workflow state; documented for completeness and rare direct use, not split into yours-vs-theirs. Verified every command against the cobra defs in internal/cli/cli.go: new and completion are real subcommands; corrected the state row to cover both state init (resumes) and state new (births), and named new's SLUG arg and dispatch's subcommands. Co-Authored-By: Claude Fable 5 --- docs/site/reference/command-reference.md | 48 +++++++++--------------- 1 file changed, 17 insertions(+), 31 deletions(-) diff --git a/docs/site/reference/command-reference.md b/docs/site/reference/command-reference.md index e35b3c9c..dc917c84 100644 --- a/docs/site/reference/command-reference.md +++ b/docs/site/reference/command-reference.md @@ -1,26 +1,10 @@ # Command reference -The `spacedock` binary groups its subcommands into Launch, Setup, and Workflow, plus a top-level `--version`. This page is the map: what each command does, and which are yours to run versus the ones the first officer runs against workflow state. For the exact flags of any command, run `spacedock --help`, which is the always-current source of truth. - -| Command | Group | What it does | -|---------|-------|--------------| -| [`spacedock claude`](#launch) | Launch | Start Claude Code with the first officer loaded | -| [`spacedock codex`](#launch) | Launch | Start Codex (experimental) with the first officer | -| [`spacedock pi`](#launch) | Launch | Start Pi (experimental) with the first officer | -| [`spacedock install`](#setup) | Setup | Install the per-host plugin, then run the compatibility check | -| [`spacedock doctor`](#setup) | Setup | Run the compatibility check alone | -| [`spacedock status`](#workflow) | Workflow | Read or mutate workflow state: the table, `--next`, `--where`, `--set` | -| [`spacedock new`](#workflow) | Workflow | Create an entity (`new [--folder] SLUG`, body on stdin) | -| [`spacedock state`](#workflow) | Workflow | Manage a split-root workflow's state checkout | -| [`spacedock completion`](#workflow) | Workflow | Print a bash or zsh completion script | -| [`spacedock dispatch`](#workflow) | Workflow | Build the dispatch artifacts the first officer hands an ensign | -| `spacedock --version` | | Print the binary version and the contract level | - -Run `spacedock` with no arguments for the grouped help, and `spacedock --help` for a command's own flags. +The `spacedock` binary groups its subcommands into Launch, Setup, and Workflow, plus a top-level `spacedock --version` (the binary version and contract level). For the exact flags of any command, run `spacedock --help`, the always-current source of truth; `spacedock` with no arguments prints the grouped help. ## Launch -`spacedock claude`, `spacedock codex`, and `spacedock pi` start the named host with the first officer loaded. Claude Code is the primary surface; Codex and Pi are experimental. The grammar is the same for all three: +`spacedock claude`, `spacedock codex`, and `spacedock pi` start a host with the first officer loaded. Claude Code is the primary surface; Codex and Pi are experimental. The grammar is the same for all three: ```bash spacedock claude [task] [spacedock-flags] [-- host-flags] @@ -30,21 +14,23 @@ The task comes first and becomes the launch prompt. Anything after `--` forwards ## Setup -`spacedock install` installs the per-host plugin, then runs the compatibility check; `spacedock doctor` runs the check alone. Both take `--host claude|codex|pi` (default `claude`). When `doctor` reports the plugin is out of date, refresh it with `spacedock install`. See [Install Spacedock](../get-started/install.md) for the full setup path. +| Command | What it does | +|---------|--------------| +| `spacedock install` | Install the per-host plugin, then run the compatibility check | +| `spacedock doctor` | Run the compatibility check alone | -## Workflow - -These commands read and mutate workflow state. Two are yours; the rest the first officer runs as it moves entities. +Both take `--host claude|codex|pi` (default `claude`). When `doctor` reports the plugin is out of date, refresh it with `spacedock install`. See [Install Spacedock](../get-started/install.md) for the full setup path. -Yours to run: - -- **`state`** initializes the state checkout for a [split-root workflow](../advanced/split-root-state.md) on a fresh clone. -- **`completion`** prints a bash or zsh completion script to install. +## Workflow -The first officer's, against workflow state: +The first officer runs these against workflow state as it moves entities; you operate through it, not by hand. They are documented here for completeness and for the rare direct use (scripting, debugging, restoring a state checkout on a fresh clone). -- **`status`** reads and mutates the state: with no flag it prints the entity table, `--next` lists what is ready to dispatch, `--where` filters, `--set` mutates frontmatter, `--validate` checks the workflow, and `--boot` prints the first-officer boot view. [Operate a workflow](../running-workflows/operating.md) covers how the first officer uses it on your behalf. -- **`new`** creates an entity (`new [--folder] SLUG`) from a body on stdin. -- **`dispatch`** (`dispatch build`, `dispatch show-stage-def`) builds the worker dispatch artifacts the first officer hands an ensign. +| Command | What it does | +|---------|--------------| +| `spacedock status` | Read or mutate the state: the entity table, `--next`, `--where`, `--set`, `--validate`, `--boot` | +| `spacedock new` | Create an entity (`new [--folder] SLUG`) from a body on stdin | +| `spacedock dispatch` | Build the worker dispatch artifacts (`dispatch build`, `dispatch show-stage-def`) | +| `spacedock state` | Manage a [split-root workflow](../advanced/split-root-state.md)'s state checkout (`state init` resumes one on a fresh clone, `state new` births one) | +| `spacedock completion` | Print a bash or zsh completion script | -Run `spacedock status --help` (and the same for each command) for the full flag list, the mutation guards, and the exit codes. +[Operate a workflow](../running-workflows/operating.md) covers how the first officer uses `status` on your behalf. Run `spacedock status --help` (and the same for each command) for the full flag list, the mutation guards, and the exit codes.