From cb1e040861b34e2b35761335032b94c3458c33f6 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Mon, 8 Jun 2026 20:55:08 -0700 Subject: [PATCH 1/5] docs site: stand up MkDocs Material site + GitHub Pages publish MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Build the public docs site to the approved 7-section IA (Home · Get started · Concepts · Running workflows · Advanced topics · Reference · Contributing), green under `mkdocs build --strict`. - docs/site/ single content root: install-journey MOVED to get-started/install.md; functional files (docs/dev/README.md, AGENTS.md, docs/releasing.md, docs/specs/state-behavior-extension, docs/runtime-support.md) SYMLINKED in, canonical path unchanged. - mkdocs.yml: Material theme, light/dark palette toggle, content.code.copy + search.suggest/highlight + navigation.sections/instant + content.tabs.link; explicit nav mirroring the IA; mkdocs-llmstxt -> site/llms.txt. - "For agents" banner link (theme override) to llms.txt + the AGENTS.md page. - docs/requirements.txt pins mkdocs + mkdocs-material + mkdocs-llmstxt. - .github/workflows/docs.yml: strict build as a PR check; deploy to Pages on push to main (the stable branch per docs/releasing.md). - Net-new pages authored to a first-version bar (Concepts/Running/Advanced syntheses, Voice & tone lifted from the ideation draft, e6 example stub, Reference -> Frontmatter contract surfacing the dev README schema table). Move-induced fixes: README install link, install.sh source-build hint, and internal/release/install_doc_test.go path now point at the relocated install.md. go test ./... green (1247 passed). Co-Authored-By: Claude Opus 4.8 (1M context) --- .github/workflows/docs.yml | 62 +++++++++++ .gitignore | 4 + README.md | 2 +- docs/overrides/main.html | 11 ++ docs/requirements.txt | 5 + docs/site/advanced/external-tracker.md | 1 + .../advanced/mods-and-standing-teammates.md | 17 +++ docs/site/advanced/split-root-state.md | 28 +++++ docs/site/advanced/sprints-and-roadmap.md | 37 ++++++ docs/site/agents/index.md | 1 + docs/site/concepts/gates-and-decisions.md | 25 +++++ docs/site/concepts/operating-model.md | 26 +++++ docs/site/concepts/stage-lifecycle.md | 25 +++++ docs/site/concepts/workflows-and-entities.md | 35 ++++++ docs/site/contributing/adding-a-runtime.md | 21 ++++ docs/site/contributing/architecture-notes.md | 28 +++++ .../site/contributing/development-workflow.md | 1 + docs/site/contributing/proof-policy.md | 23 ++++ docs/site/contributing/releasing.md | 1 + docs/site/contributing/voice-and-tone.md | 51 +++++++++ docs/site/get-started/first-launch.md | 41 +++++++ docs/site/get-started/first-workflow.md | 36 ++++++ .../get-started/install.md} | 0 docs/site/index.md | 36 ++++++ docs/site/reference/command-reference.md | 49 ++++++++ docs/site/reference/frontmatter-contract.md | 29 +++++ docs/site/reference/multi-host.md | 1 + docs/site/running-workflows/commission.md | 31 ++++++ .../running-workflows/debrief-and-refit.md | 23 ++++ docs/site/running-workflows/example.md | 5 + docs/site/running-workflows/operating.md | 39 +++++++ docs/site/running-workflows/survey.md | 19 ++++ install.sh | 2 +- internal/release/install_doc_test.go | 4 +- mkdocs.yml | 105 ++++++++++++++++++ 35 files changed, 820 insertions(+), 4 deletions(-) create mode 100644 .github/workflows/docs.yml create mode 100644 docs/overrides/main.html create mode 100644 docs/requirements.txt create mode 120000 docs/site/advanced/external-tracker.md create mode 100644 docs/site/advanced/mods-and-standing-teammates.md create mode 100644 docs/site/advanced/split-root-state.md create mode 100644 docs/site/advanced/sprints-and-roadmap.md create mode 120000 docs/site/agents/index.md create mode 100644 docs/site/concepts/gates-and-decisions.md create mode 100644 docs/site/concepts/operating-model.md create mode 100644 docs/site/concepts/stage-lifecycle.md create mode 100644 docs/site/concepts/workflows-and-entities.md create mode 100644 docs/site/contributing/adding-a-runtime.md create mode 100644 docs/site/contributing/architecture-notes.md create mode 120000 docs/site/contributing/development-workflow.md create mode 100644 docs/site/contributing/proof-policy.md create mode 120000 docs/site/contributing/releasing.md create mode 100644 docs/site/contributing/voice-and-tone.md create mode 100644 docs/site/get-started/first-launch.md create mode 100644 docs/site/get-started/first-workflow.md rename docs/{install-journey.md => site/get-started/install.md} (100%) create mode 100644 docs/site/index.md create mode 100644 docs/site/reference/command-reference.md create mode 100644 docs/site/reference/frontmatter-contract.md create mode 120000 docs/site/reference/multi-host.md create mode 100644 docs/site/running-workflows/commission.md create mode 100644 docs/site/running-workflows/debrief-and-refit.md create mode 100644 docs/site/running-workflows/example.md create mode 100644 docs/site/running-workflows/operating.md create mode 100644 docs/site/running-workflows/survey.md create mode 100644 mkdocs.yml diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..0b0e6ca9 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,62 @@ +# Builds the MkDocs Material docs site with `--strict` and publishes it to GitHub +# Pages. The strict build runs on every PR as a check so a broken nav entry or +# internal link fails before merge; on push to the stable branch (main) the built +# site deploys to Pages. +name: docs + +on: + push: + branches: + - main + pull_request: + branches: + - main + +# Allow only one concurrent deployment; do not cancel an in-progress run so a +# deploy completes before the next starts. +concurrency: + group: pages + cancel-in-progress: false + +jobs: + # Strict build. Runs on PRs and pushes alike, so the same gate that protects + # merges also produces the artifact the deploy job publishes. + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.12" + + - name: Install docs dependencies + run: pip install -r docs/requirements.txt + + - name: Build the site (strict) + run: mkdocs build --strict + + - name: Upload Pages artifact + if: github.ref == 'refs/heads/main' + uses: actions/upload-pages-artifact@v3 + with: + path: site + + # Deploy only on push to the stable branch. PRs run the build gate above but + # never deploy. + deploy: + if: github.ref == 'refs/heads/main' + needs: build + runs-on: ubuntu-latest + permissions: + pages: write + id-token: write + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.gitignore b/.gitignore index 07902168..6224dcbe 100644 --- a/.gitignore +++ b/.gitignore @@ -6,6 +6,10 @@ __pycache__/ # goreleaser build output (binaries, tarballs, checksums, generated cask). dist/ +# MkDocs build output. The docs Pages workflow rebuilds `site/` from `docs/site/` +# + mkdocs.yml on every run; it is a generated artifact, never committed. +/site/ + # Split-root state checkouts are linked worktrees on an orphan state branch, never # committed to the code branch (zero code-branch churn). A fresh clone re-creates # the checkout with `spacedock state init`. diff --git a/README.md b/README.md index d8bc6881..df009dc0 100644 --- a/README.md +++ b/README.md @@ -74,7 +74,7 @@ spacedock claude "/spacedock:survey" Using Codex or Pi instead? Swap the subcommand: `spacedock codex "/spacedock:survey"` or `spacedock pi "/spacedock:survey"`. -See [`docs/install-journey.md`](docs/install-journey.md) for the full first-run +See [`docs/site/get-started/install.md`](docs/site/get-started/install.md) for the full first-run walkthrough, the Codex and Pi paths, and a from-source build for development. ## Quick start diff --git a/docs/overrides/main.html b/docs/overrides/main.html new file mode 100644 index 00000000..8e34c256 --- /dev/null +++ b/docs/overrides/main.html @@ -0,0 +1,11 @@ +{% extends "base.html" %} + + +{% block announce %} + For agents: + llms.txt + · + AGENTS.md +{% endblock %} diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..77a9dbbc --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,5 @@ +# Pinned build dependencies for the Spacedock docs site. +# Installed by the Pages workflow and locally for `mkdocs build --strict`. +mkdocs==1.6.1 +mkdocs-material==9.6.21 +mkdocs-llmstxt==0.3.0 diff --git a/docs/site/advanced/external-tracker.md b/docs/site/advanced/external-tracker.md new file mode 120000 index 00000000..1ded4065 --- /dev/null +++ b/docs/site/advanced/external-tracker.md @@ -0,0 +1 @@ +../../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 new file mode 100644 index 00000000..73b1200a --- /dev/null +++ b/docs/site/advanced/mods-and-standing-teammates.md @@ -0,0 +1,17 @@ +# Mods & standing teammates + +Mods extend a workflow with lifecycle hooks and standing agents — behavior layered on top of the base stage primitives, without changing the workflow's stage definitions. + +## Lifecycle hooks + +A mod registers behavior at a point in the workflow lifecycle — startup, idle, or merge. The first officer runs registered hooks at the matching lifecycle event. For example, a startup hook can spawn a standing teammate before the normal event loop begins; a merge hook can guard terminalization so an entity cannot be closed while a merge is pending. + +Mods live under the workflow's `_mods/` directory. They are convention-driven prose the first officer reads and acts on, not a separate binary. + +## Standing teammates + +A standing teammate is an agent kept alive for the session, available on demand rather than dispatched per stage. The **comm-officer** is the canonical example: a prose-polishing teammate spawned by a startup hook and kept resident for the captain session. + +The comm-officer polishes drafts about to be presented to the captain — PR bodies, gate review summaries, entity narrative sections — and the entity body prose before it's committed. It does not polish live chat replies, short operational statuses, or commit messages. Polish is best-effort and non-blocking: callers proceed with un-polished text if no reply arrives within two minutes. + +The comm-officer is light-touch by default and defers to a project voice guide when one applies. For Spacedock's docs, that guide is the [Voice & tone](../contributing/voice-and-tone.md) page. diff --git a/docs/site/advanced/split-root-state.md b/docs/site/advanced/split-root-state.md new file mode 100644 index 00000000..85a1c770 --- /dev/null +++ b/docs/site/advanced/split-root-state.md @@ -0,0 +1,28 @@ +# Multi-workflow & split-root state + +Split-root state separates a workflow's *definition* from its *runtime state*. The README stays in the main repo; the mutable entities live in a per-workflow state checkout. This keeps noisy state transitions out of the code branch. + +## Two roots + +A split-root workflow composes two directories: + +- `definition_dir` — the directory containing `README.md` (the workflow definition: stages, schema, gates). It stays in the main repo. +- `state_dir` — `definition_dir/`, declared by the README's `state:` field (commonly `.spacedock-state`). It holds the active entities, archived entities under `_archive`, and stage reports under folder-form entities. + +The launcher reads workflow identity and stage declarations from the definition README, and active entities from the state checkout. It writes frontmatter updates and archive moves to the state checkout — never to the code branch. + +## Declaring split-root + +The README opts in with one top-level frontmatter field: + +```yaml +state: .spacedock-state +``` + +The path resolves relative to the README's directory. If `state` is absent, the workflow uses the same-directory layout (entities live beside the README). + +## Concurrency-safe state commits + +The state checkout is a single shared git index. When multiple agents write entities concurrently, a bare `git add -A` would sweep up a sibling writer's staged entity. State commits are therefore path-scoped — each writer adds and commits only its own entity path — and pushed with a rebase-on-rejection retry so disjoint single-file commits replay cleanly atop one another. + +For the full storage-behavior contract, see the [external-tracker bridge](external-tracker.md) and the development workflow's state model. diff --git a/docs/site/advanced/sprints-and-roadmap.md b/docs/site/advanced/sprints-and-roadmap.md new file mode 100644 index 00000000..9b6d7eb9 --- /dev/null +++ b/docs/site/advanced/sprints-and-roadmap.md @@ -0,0 +1,37 @@ +# Sprints & roadmap + +The roadmap is the strategy layer above the per-entity workflow. It owns outcome, scope, sequencing, and definition-of-done. It does not track task state — that lives in the workflow's state checkout and is queried with `spacedock status`. + +## The two roles + +- **The shaping first officer** owns strategy and shape: the roadmap, sprint definition (deliverable plus definition-of-done), the gating ideation of each sprint's entities, the cross-entity coherence check, the staff readiness review, and packaging each sprint as a dispatch. It stays high-level and does not hand-drive stage execution. +- **The Commander** takes one packaged sprint and drives it to its deliverable: dispatches each stage, approves execution gates and merges with judgment, runs the sprint-wide integration test, and produces the report. It boots the first-officer skill and creates its own team. It escalates only on a third feedback cycle, a budget blowout, an irrecoverable block, or a genuine scope fork. + +The handoff between them is the **dispatch package** — a self-contained sprint package the Commander runs from a cold boot, not a context transfer. + +## The sprint lifecycle + +A sprint runs in three phases: + +- **Shape** (shaping first officer) — scope-lock with the captain, carve the members, ideate each gated member with the riskiest mechanism exercised first, run an independent preflight staff review, present the ideation gates, and package the dispatch. +- **Drive** (Commander, a separate cold-booted session) — implementation → validation → done per member, with a detached adversarial audit at validation for every high-stakes surface; merge each member; run an independent pre-cut antipattern audit before the release tag fires; then cut the release. +- **Close** (shaping first officer) — fold the audit's deferred findings into the next sprint's backlog and run a light post-cut verification. + +The two independent reviews — preflight and pre-cut — are never self-reviews. Their value is refuting the first officer's own assumptions, so a fresh reviewer runs them. + +## Roadmap as a strategy layer + +The roadmap holds the value-ordered sprint sequence: each sprint and the deliverable it unlocks. It is the durable strategy document, distinct from the executable work it sequences. + +## A convention, not new code + +Today this is a **convention-only dry run** of the sprint/roadmap construct: prose plus frontmatter plus the native `status --where` query, with no new binary code. A sprint *groups* entities by a frontmatter query rather than a hard-coded list: + +```bash +# every member of a sprint +spacedock status --workflow-dir docs/dev --where sprint=019x-pre-flip-cleanups +# the drivable set (excludes deferred members) +spacedock status --workflow-dir docs/dev --where sprint=019x-pre-flip-cleanups --where 'sprint-readiness != defer' +``` + +Members carry `sprint`, `group`, and `sprint-readiness` frontmatter. There is no contract bump and no dedicated `--sprint` gate — the rollup is the native `--where` query. Whether this construct graduates into binary support depends on whether the dry run proves it. diff --git a/docs/site/agents/index.md b/docs/site/agents/index.md new file mode 120000 index 00000000..fd3cf9a9 --- /dev/null +++ b/docs/site/agents/index.md @@ -0,0 +1 @@ +../../../AGENTS.md \ No newline at end of file diff --git a/docs/site/concepts/gates-and-decisions.md b/docs/site/concepts/gates-and-decisions.md new file mode 100644 index 00000000..0f5bac1f --- /dev/null +++ b/docs/site/concepts/gates-and-decisions.md @@ -0,0 +1,25 @@ +# Gates & decisions + +A gate is the decision point at the end of a stage. Nothing advances past a gated stage without a decision — yours, or one you've delegated to an agent review. + +## What a gate carries + +Each gate carries a stage report: findings, verdicts, artifacts, and anomalies. You decide on the evidence, not the transcript. The record outlives the reviewer, so a bad result can be traced back to the call that caused it. + +At a gate, the first officer pauses and presents the stage report. You make one of three calls: + +- **Approve** — the work meets the bar; the entity advances. +- **Redo with feedback** — the work needs revision; it bounces back to an earlier stage with your concrete feedback. +- **Reject** — the work does not meet the bar. + +Some gates wait on you. Others resolve through a delegated agent review, when you've handed the call to an agent. + +## Feedback cycles and the loop cap + +Rejected work bounces back to an earlier stage for revision. To prevent loops, a hard cap limits how many times an entity can bounce. On the third consecutive rejection, the first officer escalates to you instead of auto-bouncing a fourth time — the loop never runs unbounded. + +## The detached adversarial audit + +For high-stakes surfaces — the front-door launcher, the state-mutation guards, the shipped scaffolding, and the CI/release machinery — a passing validation is necessary but not sufficient. Before merging such a change, a read-only adversarial audit runs on a separate throwaway checkout. The auditor tries to *refute* the validation: it constructs an edit that breaks the claim and confirms the deliverable's own tests catch it. A test that stays green under an edit that breaks the claim is a hole. + +This catches the class of bug where a test passes but would also pass on a broken future edit — which validation, trusting its own green suite, cannot see. "Refuted nothing material" is itself a valid, recorded outcome. diff --git a/docs/site/concepts/operating-model.md b/docs/site/concepts/operating-model.md new file mode 100644 index 00000000..4f017029 --- /dev/null +++ b/docs/site/concepts/operating-model.md @@ -0,0 +1,26 @@ +# The operating model + +Spacedock runs work through three roles. You set the mission and make the calls; agents do the work and bring decisions back to you. + +## Three roles + +| Role | Who | +|------|-----| +| **Captain** | You. You define the mission and make the calls at approval gates unless delegated. | +| **First Officer** | The orchestrator agent that runs the workflow and reports to you at gates. | +| **Ensign** | The worker agent that moves one item forward through one stage. | + +The first officer reads the workflow README, checks which items are ready to advance, and dispatches ensigns. Stages that need isolation run in their own git worktree; lightweight stages run inline. At a gate, the first officer pauses and presents the stage report for a decision: approve, redo with feedback, or reject. Some gates wait on you; others resolve through a delegated agent review. + +## The shaping/driving split + +At larger scale the orchestration splits into two operating roles: + +- **The shaping first officer** owns strategy and shape — the roadmap, sprint definition (deliverable plus definition-of-done), the gating ideation of each sprint's entities, the staff readiness review, and packaging each sprint as a dispatch. It stays high-level and does not hand-drive stage execution. +- **The Commander** takes one packaged sprint and drives it to its deliverable: dispatches each stage, approves execution gates and merges with judgment, runs the sprint-wide integration test, and produces the report. It escalates only on a third feedback cycle, a budget blowout, an irrecoverable block, or a genuine scope fork. + +See [Sprints & roadmap](../advanced/sprints-and-roadmap.md) for the strategy layer this split serves. + +## How the model serves you + +The point of the model is that decisions are batched and evidenced, not scattered. You queue work; agents advance each item through its stages; you handle gates as they surface, not one session at a time. Each decision leaves a trail — a stage report with findings, verdicts, artifacts, and anomalies — so you decide on evidence, not the transcript. diff --git a/docs/site/concepts/stage-lifecycle.md b/docs/site/concepts/stage-lifecycle.md new file mode 100644 index 00000000..a848805f --- /dev/null +++ b/docs/site/concepts/stage-lifecycle.md @@ -0,0 +1,25 @@ +# The stage lifecycle + +Work moves through stages. Each stage declares what good looks like, produces a deliverable, and routes the entity to the next stage. The development workflow's lifecycle is the canonical example: backlog → ideation → implementation → validation → done. + +## The stages + +- **backlog** — a work item enters here when it's first proposed. It has a seed description but no design work yet. +- **ideation** — a pilot fleshes out the idea: clarify the problem, explore approaches, and produce a concrete definition of done with acceptance criteria and a test plan. +- **implementation** — produce the deliverable. Write the code, generate the fixtures, make the changes the work item describes. Implementation is complete when the deliverable exists and is ready for independent verification. +- **validation** — a *fresh* agent verifies the deliverable against the acceptance criteria. The validator checks what was produced; it does not produce the deliverable itself. +- **done** — validation is complete and the captain approves. The entity closes with a verdict of PASSED or REJECTED. + +## Fresh context at validation + +Validation runs with fresh context — a separate agent that has no access to the maker's reasoning. The agent doesn't get to judge its own work. This is what makes review push back on thin evidence instead of rubber-stamping the implementation it just wrote. + +## Worktree vs. inline + +Stages that touch shared state run in their own git worktree, so concurrent work doesn't collide. Lighter stages run inline, in the repo root. The workflow README declares which stages need a worktree. + +## What a stage declares + +Each stage in the README names its inputs, its outputs, and — most importantly — what *good* and *bad* look like for that stage. The agent works to that line on its own. When a standard turns out fuzzy in practice, the agent proposes an edit to the stage's written criteria for your approval, so the bar sharpens as you use it. + +For how the transition between stages is decided, see [Gates & decisions](gates-and-decisions.md). diff --git a/docs/site/concepts/workflows-and-entities.md b/docs/site/concepts/workflows-and-entities.md new file mode 100644 index 00000000..6d0e4701 --- /dev/null +++ b/docs/site/concepts/workflows-and-entities.md @@ -0,0 +1,35 @@ +# Workflows & entities + +A workflow is a directory of plain-text work items plus a README that defines the stages, the schema, and the gates. Everything about a work item lives in the file itself. + +## A workflow is a directory plus a README + +The README declares the workflow: its stages, its frontmatter schema, and which stages are gated. The work items live alongside it. The README is the single definition the first officer reads to know how to drive the workflow. + +## An entity is one work item + +An **entity** (also called a *work item*) is one markdown file — or a folder, when reports and artifacts accumulate beside it. Each entity is named `{slug}` or `{slug}.md` (lowercase, hyphens, no spaces). Use folder-form entities when reports may pile up; for example `native-go-status/index.md`. + +Everything about the work item lives in the file: the problem, the design notes, the bar for done, and the stage reports. State survives a session; the next one picks up where you left off. + +## Entity frontmatter + +Every entity carries YAML frontmatter. The field set is declared by the workflow README. The development workflow's schema is the canonical example: + +| Field | Type | Description | +|-------|------|-------------| +| `id` | string | Unique entity identifier | +| `title` | string | Human-readable name | +| `status` | enum | The current stage | +| `source` | string | Where the work item came from | +| `started` | ISO 8601 | When active work began | +| `completed` | ISO 8601 | When the entity reached its terminal stage | +| `verdict` | enum | PASSED or REJECTED — set at the final stage | +| `worktree` | string | Worktree path while a dispatched agent is active, empty otherwise | +| `issue` | string | Optional external ticket reference (e.g. `ENG-123`, `owner/repo#42`) | + +The full field reference for the development workflow lives on the [Frontmatter contract](../reference/frontmatter-contract.md) page. + +## The state checkout + +Some workflows separate the workflow *definition* from the workflow *runtime state*. With the `state-branch` profile, the README stays in the main repo while the mutable entities live in a per-workflow `.spacedock-state` checkout. This keeps state transitions out of the code branch. See [Multi-workflow & split-root state](../advanced/split-root-state.md) for how the two roots compose. diff --git a/docs/site/contributing/adding-a-runtime.md b/docs/site/contributing/adding-a-runtime.md new file mode 100644 index 00000000..eb4969d3 --- /dev/null +++ b/docs/site/contributing/adding-a-runtime.md @@ -0,0 +1,21 @@ +# Adding a runtime + +A host is *supported* when a live or fixture-backed run launches it as a first officer, dispatches an ensign through its native mechanism, and verifies the resulting workflow state. A host is not supported just because its instructions mention Spacedock. + +## Add support in layers + +Each layer has its own proof: + +1. **Skill adapters** — add a first-officer and an ensign runtime adapter for the host, wired from the corresponding skill. The adapter must name the host's native dispatch mechanism, not emulate Claude's tools. +2. **Dispatch host mode** — teach `spacedock dispatch build` the host's assignment shape, keeping entity and worktree paths explicit. Test both the positive shape and the banned-tool negative case. +3. **Runtime contracts and registries** — define the minimum worker record if the host has long-lived workers, and reject stale completion evidence so a previous completion never satisfies a later assignment. +4. **Launch/install UX** — add `spacedock `, `install --host `, and `doctor --host ` only after the underlying mechanism is proven. +5. **Live runner** — prove the host with a live-gated test that asserts process exit, entity content, git log, and clean state — never transcript phrasing. + +## Manifesting from void + +When a runtime seems unsupported on first contact, don't treat setup friction as proof the path is impossible. A missing auth file, an undiscovered extension, or a different subagent tool schema is harness work, not a product blocker. Use the deliberate "assume it works" operating prompt to force the implementation loop to iron out auth, package paths, and tool-shape mismatches before declaring a blocker. + +## The full guide + +The complete runtime contract — the layer-by-layer acceptance checklist, the "manifesting from void" prompt, and the Pi live-smoke mechanism — is on the [Multi-host support](../reference/multi-host.md) page. diff --git a/docs/site/contributing/architecture-notes.md b/docs/site/contributing/architecture-notes.md new file mode 100644 index 00000000..88ca0370 --- /dev/null +++ b/docs/site/contributing/architecture-notes.md @@ -0,0 +1,28 @@ +# Architecture notes + +Notes on how the Spacedock codebase and its design contracts are organized, for contributors orienting in the repo. + +## Project shape + +The repo builds the Go-based `spacedock` launcher and the project-side skill integration: + +- `cmd/spacedock/` — the process entry point only. +- `internal/cli/` — command routing, usage text, exit-code behavior. +- `internal/status/` — status implementation and the compatibility runner. +- `docs/specs/` — design contracts. +- `docs/dev/README.md` — the development workflow definition. +- `docs/dev/.spacedock-state/` — the development workflow's entities, in a separate state checkout. +- `skills/` — the skill-facing command integration. + +The baseline gate for every change is `go test ./...`. Prefer small Go packages with clear boundaries; use the standard library unless a dependency removes real complexity; keep command output stable and test it with fixtures. + +## Design contracts + +Two specs under `docs/specs/` carry the load-bearing design semantics: + +- **State behavior extension** — the split-root storage profile (definition vs. runtime state) and the external-tracker bridge principles. See [External-tracker bridge](../advanced/external-tracker.md) and [Multi-workflow & split-root state](../advanced/split-root-state.md). +- **Scenario-testing principles** — the semantic model for scenario-based testing: what a scenario is, what an executor is (codified vs. LLM), and the variant axes a scenario runs under. It dissolves the offline/live split by treating both as two executors of one named scenario. + +## Runtime live CI + +The live lanes prove runtime behavior, not text shape. One host-neutral scenario table, per-host runner adapters implementing the same scenario IDs, and a parity guard that fails if a scenario exists for one host only. Static grep over workflow YAML or skill prose is never a substitute for launching the real host front door, observing its output, and checking the resulting workflow state. For the full discipline, see [Proof policy](proof-policy.md). diff --git a/docs/site/contributing/development-workflow.md b/docs/site/contributing/development-workflow.md new file mode 120000 index 00000000..faadd5dc --- /dev/null +++ b/docs/site/contributing/development-workflow.md @@ -0,0 +1 @@ +../../dev/README.md \ No newline at end of file diff --git a/docs/site/contributing/proof-policy.md b/docs/site/contributing/proof-policy.md new file mode 100644 index 00000000..57fd29ea --- /dev/null +++ b/docs/site/contributing/proof-policy.md @@ -0,0 +1,23 @@ +# Proof policy + +A change is proven by exercising its behavior and observing the outcome — not by asserting that a file contains the right words. This is the discipline the development workflow's ideation and validation stages enforce, and it is the bar any contribution must clear. + +## Behavior is proven by exercising it + +Prove a claim by running the behavior and checking the result: output bytes, exit code, resulting on-disk state, or a test feeding many inputs and asserting uniform handling. Go unit tests for parser and command behavior, golden fixtures for stable command output, behavior fixtures that drive the binary for command-level claims, and live workflow smoke tests when runtime behavior is the claim. + +## No prose-grep acceptance criteria + +A string, substring, or regex match over an instruction file the model reads — the first-officer or ensign contract, a workflow README, a skill — never satisfies a behavioral acceptance criterion. The matched string was written by the same implementer the check is supposed to police, so a passing check only asserts "the file contains the text we put in the file." It has no independent source of truth: a valid paraphrase fails it, and an inverted clause passes it. + +The one test that settles it: **does the expected value come from somewhere other than the file under test?** If no — the clause is its own expectation — the check is a tautology and proves nothing. If yes — the file is bound to an independent source that can diverge from it — it may be a legitimate invariant. The legitimate case parses real artifacts in code and tests a relationship between independent values; for example, that the plugin manifest's contract range brackets the binary's contract version. + +## Acceptance criteria are end-state properties + +Acceptance criteria describe properties of the finished entity, not stage actions. Each criterion's "Verified by" must name something outside the entity body that can fail: a test, a command's output or exit code, a file the change produces, or the resulting on-disk state. An acceptance criterion whose only proof is reviewing the entity's own prose can never fail, so it is not an acceptance criterion. + +## The detached adversarial audit + +For high-stakes surfaces — the front-door launcher, the state-mutation guards, the shipped scaffolding, and the CI/release machinery — a passing validation is necessary but not sufficient. A read-only adversarial audit on a throwaway checkout tries to refute the validation: construct an edit that breaks the claim and confirm the deliverable's own tests catch it. A test that stays green under an edit that breaks the claim is a hole. See [Gates & decisions](../concepts/gates-and-decisions.md) for how findings route back. + +The authoritative statement of this policy lives in the development workflow's stage definitions — see [The development workflow](development-workflow.md). diff --git a/docs/site/contributing/releasing.md b/docs/site/contributing/releasing.md new file mode 120000 index 00000000..43d5a123 --- /dev/null +++ b/docs/site/contributing/releasing.md @@ -0,0 +1 @@ +../../releasing.md \ No newline at end of file diff --git a/docs/site/contributing/voice-and-tone.md b/docs/site/contributing/voice-and-tone.md new file mode 100644 index 00000000..2694356c --- /dev/null +++ b/docs/site/contributing/voice-and-tone.md @@ -0,0 +1,51 @@ +# 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). + +## 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/first-launch.md b/docs/site/get-started/first-launch.md new file mode 100644 index 00000000..91cf80f7 --- /dev/null +++ b/docs/site/get-started/first-launch.md @@ -0,0 +1,41 @@ +# Your first launch + +Once the `spacedock` launcher and the host plugin are installed (see [Install](install.md)), a single command starts a session. Spacedock launches your first officer — the orchestrator agent — inside your coding harness. + +## Launch the first officer + +Point Spacedock at a project you already have and let it survey: + +```bash +spacedock claude "/spacedock:survey" +``` + +This starts the first officer in Claude Code and runs the survey skill. Using Codex or Pi instead? Swap the subcommand: + +```bash +spacedock codex "/spacedock:survey" # or: spacedock pi "/spacedock:survey" +``` + +The first launch sets up the plugin for you, so this single line is enough. When a `.safehouse` profile is present in the working directory, the launch runs sandboxed. + +## What the front door does + +The launch command is the front door. Its grammar is: + +```bash +spacedock claude "task" [--safehouse…] [-- host-flags…] +``` + +- 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`) — `--model`, `--resume`, `--plugin-dir`, and the like. +- `--safehouse` forces the launch through the sandbox; a `.safehouse` profile in the working directory does the same automatically. + +## Survey what you already built + +`/spacedock:survey` reads your project's existing agent history and reports three things: + +- the workflow you've been running without naming it, +- how you've been calling work done, +- the decisions still open and waiting on you. + +It then offers to commission a Spacedock workflow from what it found — which takes you to [your first workflow](first-workflow.md). diff --git a/docs/site/get-started/first-workflow.md b/docs/site/get-started/first-workflow.md new file mode 100644 index 00000000..7c882207 --- /dev/null +++ b/docs/site/get-started/first-workflow.md @@ -0,0 +1,36 @@ +# Your first workflow + +A workflow is a directory of plain-text work item files plus a README that defines the stages, the schema, and the gates. You commission one by describing what you want — Spacedock generates the scaffolding and starts driving it. + +## Commission a workflow + +Describe the workflow you want: + +```bash +spacedock claude "/spacedock:commission Dev task workflow: design -> plan -> +implement -> review, with the design and implementation plan inlined in each work +item, implementation on isolated worktrees with strict TDD, design and review +gated for approval." +``` + +The first officer commissions the workflow and opens a worktree for the implementation stage. It pauses at the design and review gates for your call. + +The same shape drives non-dev work. This example triages a Gmail inbox (it requires a Gmail integration set up before you run it): + +```bash +spacedock claude "/spacedock:commission Email triage: fetch, categorize, and act +on my Gmail inbox. Entity: a batch of up to 50 emails. Stages: intake (triage +in:inbox, categorize, propose an action per email as a table) -> approval +(Captain reviews the proposal) -> execute (carry out approved actions). Walk me +through Gmail setup if needed." +``` + +## What happens next + +The first officer reads the workflow README, checks which items are ready to advance, and dispatches ensigns. Stages that need isolation run in their own git worktree; lightweight stages run inline. At a gate, the first officer pauses and presents the stage report for a decision: approve, redo with feedback, or reject. Some gates wait on you; others resolve through a delegated agent review. Rejected work bounces back to an earlier stage for revision, and a hard cap prevents loops. + +## Keep going + +- To understand the roles and the lifecycle behind this, read [Concepts](../concepts/operating-model.md). +- To drive a workflow day to day — dispatch, gates, status queries — see [Running workflows](../running-workflows/operating.md). +- When you end a session, `/spacedock:debrief` captures what happened so the next session picks up where you left off. diff --git a/docs/install-journey.md b/docs/site/get-started/install.md similarity index 100% rename from docs/install-journey.md rename to docs/site/get-started/install.md diff --git a/docs/site/index.md b/docs/site/index.md new file mode 100644 index 00000000..821196a9 --- /dev/null +++ b/docs/site/index.md @@ -0,0 +1,36 @@ +# Spacedock + +**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 you delegate the call to an agent. Either way, the decision is recorded with its evidence and reason. + +## Why + +- 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 around. You stopped deciding the work and started just answering the agent. +- You're the agent, and you stall every few steps waiting on a human who isn't watching, with no clear scope and no clear bar for done, so you ask and then you wait. +- Generation got cheap. Your attention and judgment are now the bottleneck. Every task still ends in a decision, and no one owns it, so it falls on whoever's around. + +## What's different + +- **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 — the decision point at the end of a stage — carries a stage report: findings, verdicts, artifacts, anomalies. You decide on evidence, not the transcript. The record outlives the reviewer, so you can trace a bad result back to the call that caused it. +- **The bar sharpens as you use it.** Each stage declares what good means, and the agent works to that line on its own. When a standard turns out fuzzy in practice, the agent proposes an edit to the stage's written criteria for your approval. +- **Batch the work; decide as it flows back.** Queue many items at once. Agents advance each through its stages. You handle gates as they surface, not one session at a time. +- **Isolation when it matters.** Stages that touch shared state run in their own git worktree. Lighter stages run inline. + +## Start with what you already built + +Point Spacedock at a project you vibe-coded into spaghetti and run `/spacedock:survey`. It reads your own agent history and shows you three things: the workflow you've been running without naming it, how you've been calling work done, and the decisions still open and waiting on you. + +## Where to go next + +- New to Spacedock? Start with [Get started](get-started/install.md) — install, your first launch, and your first workflow. +- Want the mental model? Read [Concepts](concepts/operating-model.md) — the operating model, the stage lifecycle, and how gates work. +- Operating a workflow? See [Running workflows](running-workflows/commission.md). +- Contributing? Read [the development workflow](contributing/development-workflow.md) and the [voice & tone guide](contributing/voice-and-tone.md). + +## For agents + +Spacedock's docs are read by agents too — a user's first officer parsing these docs is itself an agent. The build emits an agent-readable surface: an `llms.txt` index of the docs (linked from the "For agents" banner at the top of every page) and the repo's [agent instructions](agents/index.md). + +## License + +Spacedock is released under the Apache License 2.0. diff --git a/docs/site/reference/command-reference.md b/docs/site/reference/command-reference.md new file mode 100644 index 00000000..0e3ad78b --- /dev/null +++ b/docs/site/reference/command-reference.md @@ -0,0 +1,49 @@ +# Command reference + +The `spacedock` launcher groups its commands into Launch, Setup, and Workflow. Run `spacedock --help` for the per-command detail. + +## Launch + +Start a coding host as your Spacedock first officer. + +| Command | Description | +|---------|-------------| +| `spacedock claude [task] [-- claude-flags]` | Start Claude Code as your Spacedock first officer | +| `spacedock codex [task] [-- codex-flags]` | Start Codex as your Spacedock first officer | +| `spacedock pi [task] [-- pi-flags]` | Start Pi as your Spacedock first officer | + +The optional `task` is the launch prompt. Everything after `--` forwards verbatim to the host. A `--plugin-dir` launch loads a local plugin checkout and relaxes the contract gate, so it does not require a prior `spacedock install`. + +## Setup + +| Command | Description | +|---------|-------------| +| `spacedock install [--host claude\|codex\|pi]` | Install the Spacedock plugin for a host, then check it | +| `spacedock doctor [--host claude\|codex\|pi]` | Check the installed plugin and this binary are compatible | + +## Workflow + +| Command | Description | +|---------|-------------| +| `spacedock status [args]` | Show or update workflow state | +| `spacedock new [--folder] SLUG` | Create an entity from a stdin body (auto-discovers the workflow) | +| `spacedock state init` | Initialize a cloned split-root workflow's state checkout | +| `spacedock completion bash\|zsh` | Print a bash or zsh completion script | +| `spacedock dispatch build \| show-stage-def` | Build worker dispatch artifacts | + +## Other + +| Command | Description | +|---------|-------------| +| `spacedock --version` | Print the installed version | + +## Status queries + +`spacedock status` reads workflow state. Common forms: + +```bash +spacedock status --workflow-dir docs/dev # the status table +spacedock status --workflow-dir docs/dev --next # entities ready to dispatch +spacedock status --workflow-dir docs/dev --where sprint=0200-flip # filter by frontmatter +spacedock status --workflow-dir docs/dev --validate # entity-contract validation +``` diff --git a/docs/site/reference/frontmatter-contract.md b/docs/site/reference/frontmatter-contract.md new file mode 100644 index 00000000..01fdc433 --- /dev/null +++ b/docs/site/reference/frontmatter-contract.md @@ -0,0 +1,29 @@ +# Frontmatter contract + +Every entity carries YAML frontmatter. The field set a workflow uses is declared in its README. This page surfaces the development workflow's schema as the canonical reference; a standalone, workflow-neutral contract spec under `docs/specs/` is a planned follow-up. + +## Field reference (development workflow) + +| Field | Type | Description | +|-------|------|-------------| +| `id` | string | Unique 24-character Spacedock Base32 ID (this workflow uses `sd-b32`) | +| `title` | string | Human-readable task name | +| `status` | enum | One of: backlog, ideation, implementation, validation, done | +| `source` | string | Where this task came from | +| `started` | ISO 8601 | When active work began | +| `completed` | ISO 8601 | When the task reached terminal status | +| `verdict` | enum | PASSED or REJECTED — set at the final stage | +| `score` | number | Priority score, 0.0–1.0 (optional). Workflows can upgrade to a multi-dimension rubric in their README. | +| `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` | + +The authoritative, always-current copy of this schema is the development workflow's README — see [The development workflow](../contributing/development-workflow.md), under "Schema / Field Reference". + +## External tracker fields + +When an entity originates from an external ticket system, two flat fields bridge it: + +- `issue` — the human-facing external reference. +- `source` — where the entity came from (e.g. `linear`, `kata`). + +Spacedock status remains the execution status unless a future bridge explicitly declares bidirectional ownership. For the full bridge contract, see [External-tracker bridge](../advanced/external-tracker.md). diff --git a/docs/site/reference/multi-host.md b/docs/site/reference/multi-host.md new file mode 120000 index 00000000..a7ccb9a2 --- /dev/null +++ b/docs/site/reference/multi-host.md @@ -0,0 +1 @@ +../../runtime-support.md \ No newline at end of file diff --git a/docs/site/running-workflows/commission.md b/docs/site/running-workflows/commission.md new file mode 100644 index 00000000..d1cca6c5 --- /dev/null +++ b/docs/site/running-workflows/commission.md @@ -0,0 +1,31 @@ +# Commission a workflow + +Commissioning generates a new workflow from a description. You say what stages you want, what an entity is, and which stages are gated; Spacedock writes the scaffolding and the first officer starts driving it. + +## Run the commission skill + +```bash +spacedock claude "/spacedock:commission " +``` + +A useful description names four things: + +- **The stages** and their order (e.g. `design -> plan -> implement -> review`). +- **The entity** — what one work item is (a task, a batch of emails, a document). +- **Which stages are gated** — where you want to approve before the work advances. +- **Any per-stage rules** — isolated worktrees, strict TDD, inlined design notes. + +## Example + +```bash +spacedock claude "/spacedock:commission Dev task workflow: design -> plan -> +implement -> review, with the design and implementation plan inlined in each work +item, implementation on isolated worktrees with strict TDD, design and review +gated for approval." +``` + +The first officer commissions the workflow and opens a worktree for the implementation stage, pausing at the design and review gates for your call. + +## After commissioning + +Once the workflow exists, you drive it: add entities, dispatch stages, and handle gates. See [Operating a workflow](operating.md) for the day-to-day loop. If you're starting from an existing project rather than a blank slate, [survey it first](survey.md). diff --git a/docs/site/running-workflows/debrief-and-refit.md b/docs/site/running-workflows/debrief-and-refit.md new file mode 100644 index 00000000..2b406ac6 --- /dev/null +++ b/docs/site/running-workflows/debrief-and-refit.md @@ -0,0 +1,23 @@ +# Debrief & refit + +Two skills keep a workflow durable across sessions and across Spacedock releases: `debrief` captures what a session did so the next one resumes from it, and `refit` upgrades your workflow scaffolding when a new Spacedock release lands. + +## Debrief: capture a session + +When you end a session, run: + +```bash +spacedock claude "/spacedock:debrief" +``` + +It captures what happened — commits, state changes, decisions, and open issues — into a record the next session picks up. Because the record lives with the workflow, the next session starts from where you left off instead of from a cold transcript. + +## Refit: upgrade your scaffolding + +When a new Spacedock release is out, run: + +```bash +spacedock claude "/spacedock:refit" +``` + +It upgrades your workflow's scaffolding files to the current version while keeping your local modifications. Use it to bring an existing workflow's structure up to date without losing the project-specific edits you've made. diff --git a/docs/site/running-workflows/example.md b/docs/site/running-workflows/example.md new file mode 100644 index 00000000..508b4e28 --- /dev/null +++ b/docs/site/running-workflows/example.md @@ -0,0 +1,5 @@ +# Example: a real workflow + +A walkthrough of one concrete, in-repo Spacedock workflow — from commission to a delivered entity — is coming. It will trace a single real work item through the stages so you can see the loop end to end with real artifacts. + +Until then, see [Commission a workflow](commission.md) and [Operating a workflow](operating.md) for the steps, and [The stage lifecycle](../concepts/stage-lifecycle.md) for the model the example will illustrate. diff --git a/docs/site/running-workflows/operating.md b/docs/site/running-workflows/operating.md new file mode 100644 index 00000000..d97e86d2 --- /dev/null +++ b/docs/site/running-workflows/operating.md @@ -0,0 +1,39 @@ +# Operating a workflow + +Driving a workflow is a loop: see what's ready, dispatch it, handle the gates that surface. The first officer runs the loop; you make the calls. + +## The loop + +The first officer reads the workflow README, checks which entities are ready to advance, and dispatches ensigns. Stages that need isolation run in their own git worktree; lightweight stages run inline. As work flows back, the first officer presents each gate for your decision — approve, redo with feedback, or reject. + +## Check workflow state + +Read the current state of a workflow with the launcher: + +```bash +spacedock status --workflow-dir docs/dev +``` + +To list the entities ready for dispatch — the query the first officer runs each loop: + +```bash +spacedock status --workflow-dir docs/dev --next +``` + +To filter entities by a frontmatter field, use `--where`: + +```bash +spacedock status --workflow-dir docs/dev --where sprint=0200-flip +``` + +See the [Command reference](../reference/command-reference.md) for the full `status` surface. + +## Handling gates + +When the first officer pauses at a gate, it presents the stage report. Decide on the evidence in the report, not the transcript: + +- **Approve** to advance the entity. +- **Redo with feedback** to bounce it back to an earlier stage with concrete direction. +- **Reject** when it does not meet the bar. + +For the mechanics of gates, feedback cycles, and the loop cap, see [Gates & decisions](../concepts/gates-and-decisions.md). diff --git a/docs/site/running-workflows/survey.md b/docs/site/running-workflows/survey.md new file mode 100644 index 00000000..7b58362c --- /dev/null +++ b/docs/site/running-workflows/survey.md @@ -0,0 +1,19 @@ +# Survey an existing project + +Survey reads a brownfield project's own agent history and reports the implicit workflow you've been running — before you commit to any structure. Use it when you arrive at a project with prior agent work and want the lay of the land. + +## Run the survey skill + +```bash +spacedock claude "/spacedock:survey" +``` + +Point it at a project you already have. It reads your own agent session history (read-only) and reports three things: + +- the workflow you've been running without naming it, +- how you've been calling work done, +- the decisions still open and waiting on you. + +## From survey to a workflow + +The survey is read-only — it changes nothing. After reporting, it offers to commission a Spacedock workflow from what it found, so the implicit structure becomes an explicit one you can drive. From there, see [Commission a workflow](commission.md) and [Operating a workflow](operating.md). diff --git a/install.sh b/install.sh index c3c82372..f2b6e333 100755 --- a/install.sh +++ b/install.sh @@ -41,7 +41,7 @@ detect_os() { case "$(uname -s)" in Darwin) echo darwin ;; Linux) echo linux ;; - *) die "unsupported OS $(uname -s); see docs/install-journey.md for source build" ;; + *) die "unsupported OS $(uname -s); see docs/site/get-started/install.md for source build" ;; esac } diff --git a/internal/release/install_doc_test.go b/internal/release/install_doc_test.go index 0f2eb977..b1b6652d 100644 --- a/internal/release/install_doc_test.go +++ b/internal/release/install_doc_test.go @@ -27,7 +27,7 @@ func TestInstallJourneyDocumentsLinuxPath(t *testing.T) { } } if !found { - t.Errorf("docs/install-journey.md has no runnable `curl … install.sh | sh` Linux install line") + t.Errorf("docs/site/get-started/install.md has no runnable `curl … install.sh | sh` Linux install line") } } @@ -64,7 +64,7 @@ func TestInstallJourneyDoesNotOverclaimLinuxSandbox(t *testing.T) { func readInstallJourney(t *testing.T) string { t.Helper() - data, err := os.ReadFile(filepath.Join("..", "..", "docs", "install-journey.md")) + data, err := os.ReadFile(filepath.Join("..", "..", "docs", "site", "get-started", "install.md")) if err != nil { t.Fatal(err) } diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000..16654b7d --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,105 @@ +site_name: Spacedock +site_description: A multi-agent orchestrator where nothing ships without a decision. +site_url: https://spacedock-dev.github.io/spacedock/ +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 + +theme: + name: material + custom_dir: docs/overrides + palette: + - media: "(prefers-color-scheme: light)" + scheme: default + toggle: + icon: material/brightness-7 + name: Switch to dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + toggle: + icon: material/brightness-4 + name: Switch to light mode + features: + - content.code.copy + - content.tabs.link + - search.suggest + - search.highlight + - navigation.sections + - navigation.instant + +plugins: + - search + - llmstxt: + 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. + sections: + Get started: + - index.md + - get-started/*.md + Concepts: + - concepts/*.md + Running workflows: + - running-workflows/*.md + Advanced topics: + - advanced/*.md + Reference: + - reference/*.md + Contributing: + - contributing/*.md + For agents: + - agents/*.md + +extra: + agents_url: llms.txt + agents_md_url: agents/ + +nav: + - Home: index.md + - Get started: + - Install: get-started/install.md + - Your first launch: get-started/first-launch.md + - Your first workflow: get-started/first-workflow.md + - Concepts: + - The operating model: concepts/operating-model.md + - Workflows & entities: concepts/workflows-and-entities.md + - The stage lifecycle: concepts/stage-lifecycle.md + - Gates & decisions: concepts/gates-and-decisions.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 + - "Example: a real workflow": running-workflows/example.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 + - 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 + - For agents: agents/index.md + +markdown_extensions: + - admonition + - pymdownx.highlight: + anchor_linenums: true + - pymdownx.details + - pymdownx.superfences + - pymdownx.tabbed: + alternate_style: true + - toc: + permalink: true From a36c52b77dd41593e802aa5b3823dfe91dc0d864 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Mon, 8 Jun 2026 21:18:58 -0700 Subject: [PATCH 2/5] docs site: swap For-agents banner for machine-discoverable head tags Captain refinement at the validation gate: a banner is human chrome for a machine resource, so agents should discover the for-agents surface from the document head, not a visible banner. - docs/overrides/main.html: drop the visible "For agents" announce banner; add two tags (llms.txt, AGENTS.md) to the extrahead block. rel="alternate" type="text/markdown" is the standards-safe form (no registered rel for llms.txt yet). - /llms.txt stays at the build-output root (the convention a14y scores) and the AGENTS.md page stays reachable; only the human-facing surface changed. - Removed the now-unused extra.agents_url / agents_md_url keys; updated the Home page prose to point at the head links instead of the banner. mkdocs build --strict green; the two tags render in every page's (verified in site/index.html and nested pages). Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/overrides/main.html | 17 +++++++++-------- docs/site/index.md | 2 +- mkdocs.yml | 4 ---- 3 files changed, 10 insertions(+), 13 deletions(-) diff --git a/docs/overrides/main.html b/docs/overrides/main.html index 8e34c256..678bce90 100644 --- a/docs/overrides/main.html +++ b/docs/overrides/main.html @@ -1,11 +1,12 @@ {% extends "base.html" %} - -{% block announce %} - For agents: - llms.txt - · - AGENTS.md + +{% block extrahead %} + {{ super() }} + + {% endblock %} diff --git a/docs/site/index.md b/docs/site/index.md index 821196a9..2fa9d105 100644 --- a/docs/site/index.md +++ b/docs/site/index.md @@ -29,7 +29,7 @@ Point Spacedock at a project you vibe-coded into spaghetti and run `/spacedock:s ## For agents -Spacedock's docs are read by agents too — a user's first officer parsing these docs is itself an agent. The build emits an agent-readable surface: an `llms.txt` index of the docs (linked from the "For agents" banner at the top of every page) and the repo's [agent instructions](agents/index.md). +Spacedock's docs are read by agents too — a user's first officer parsing these docs is itself an agent. The build emits an agent-readable surface: an `llms.txt` index of the docs at the site root (discoverable from each page's `` via ``) and the repo's [agent instructions](agents/index.md). ## License diff --git a/mkdocs.yml b/mkdocs.yml index 16654b7d..be3683a1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -54,10 +54,6 @@ plugins: For agents: - agents/*.md -extra: - agents_url: llms.txt - agents_md_url: agents/ - nav: - Home: index.md - Get started: From 096e2b234aab8f0a495aa30d51b1a5a6ababa53b Mon Sep 17 00:00:00 2001 From: CL Kao Date: Mon, 8 Jun 2026 21:22:54 -0700 Subject: [PATCH 3/5] =?UTF-8?q?docs=20site:=20tab=20nav,=20example?= =?UTF-8?q?=E2=86=92Concepts,=20[TODO]-stub=20synthesized=20pages?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Captain refinements for a releasable shell now, prose filled incrementally. 1. Declutter nav: swap navigation.sections for navigation.tabs + navigation.tabs.sticky (top-level sections become top tabs; the sidebar shows only the active section's pages, sub-sections collapsed by default). 2. Move the worked-example (e6 slot) from Running workflows → Concepts (Concepts → A worked example); nav + file relocated, stays the e6 stub. 3. [TODO]-stub every synthesized/thin page (Home synthesis, Get-started first-launch/first-workflow, all Concepts intros, all Running-workflows pages, the synthesized Advanced pages, the worked-example, the synthesized Reference + Contributing pages) with an honest one-line "[TODO] — ". KEPT REAL and unchanged: the moved install page, the 5 symlinked docs (dev/README, releasing, AGENTS, runtime-support, specs), the drafted Voice & tone page, and /llms.txt. Bar met: nav complete, every page resolves, mkdocs build --strict green — a releasable shell with honest [TODO]s, not fake depth. Co-Authored-By: Claude Opus 4.8 (1M context) --- .../advanced/mods-and-standing-teammates.md | 16 +------ docs/site/advanced/split-root-state.md | 27 +---------- docs/site/advanced/sprints-and-roadmap.md | 36 +------------- docs/site/concepts/gates-and-decisions.md | 24 +--------- docs/site/concepts/operating-model.md | 25 +--------- docs/site/concepts/stage-lifecycle.md | 24 +--------- docs/site/concepts/worked-example.md | 3 ++ docs/site/concepts/workflows-and-entities.md | 34 +------------ docs/site/contributing/adding-a-runtime.md | 20 +------- docs/site/contributing/architecture-notes.md | 27 +---------- docs/site/contributing/proof-policy.md | 22 +-------- docs/site/get-started/first-launch.md | 40 +--------------- docs/site/get-started/first-workflow.md | 35 +------------- docs/site/index.md | 31 +----------- docs/site/reference/command-reference.md | 48 +------------------ docs/site/reference/frontmatter-contract.md | 28 +---------- docs/site/running-workflows/commission.md | 30 +----------- .../running-workflows/debrief-and-refit.md | 22 +-------- docs/site/running-workflows/example.md | 5 -- docs/site/running-workflows/operating.md | 38 +-------------- docs/site/running-workflows/survey.md | 18 +------ mkdocs.yml | 5 +- 22 files changed, 26 insertions(+), 532 deletions(-) create mode 100644 docs/site/concepts/worked-example.md delete mode 100644 docs/site/running-workflows/example.md diff --git a/docs/site/advanced/mods-and-standing-teammates.md b/docs/site/advanced/mods-and-standing-teammates.md index 73b1200a..09572392 100644 --- a/docs/site/advanced/mods-and-standing-teammates.md +++ b/docs/site/advanced/mods-and-standing-teammates.md @@ -1,17 +1,3 @@ # Mods & standing teammates -Mods extend a workflow with lifecycle hooks and standing agents — behavior layered on top of the base stage primitives, without changing the workflow's stage definitions. - -## Lifecycle hooks - -A mod registers behavior at a point in the workflow lifecycle — startup, idle, or merge. The first officer runs registered hooks at the matching lifecycle event. For example, a startup hook can spawn a standing teammate before the normal event loop begins; a merge hook can guard terminalization so an entity cannot be closed while a merge is pending. - -Mods live under the workflow's `_mods/` directory. They are convention-driven prose the first officer reads and acts on, not a separate binary. - -## Standing teammates - -A standing teammate is an agent kept alive for the session, available on demand rather than dispatched per stage. The **comm-officer** is the canonical example: a prose-polishing teammate spawned by a startup hook and kept resident for the captain session. - -The comm-officer polishes drafts about to be presented to the captain — PR bodies, gate review summaries, entity narrative sections — and the entity body prose before it's committed. It does not polish live chat replies, short operational statuses, or commit messages. Polish is best-effort and non-blocking: callers proceed with un-polished text if no reply arrives within two minutes. - -The comm-officer is light-touch by default and defers to a project voice guide when one applies. For Spacedock's docs, that guide is the [Voice & tone](../contributing/voice-and-tone.md) page. +[TODO] — lifecycle hooks (startup/idle/merge) under `_mods/`, and standing teammates like the comm-officer prose-polisher (which defers to the [Voice & tone](../contributing/voice-and-tone.md) guide). diff --git a/docs/site/advanced/split-root-state.md b/docs/site/advanced/split-root-state.md index 85a1c770..9c82fa46 100644 --- a/docs/site/advanced/split-root-state.md +++ b/docs/site/advanced/split-root-state.md @@ -1,28 +1,3 @@ # Multi-workflow & split-root state -Split-root state separates a workflow's *definition* from its *runtime state*. The README stays in the main repo; the mutable entities live in a per-workflow state checkout. This keeps noisy state transitions out of the code branch. - -## Two roots - -A split-root workflow composes two directories: - -- `definition_dir` — the directory containing `README.md` (the workflow definition: stages, schema, gates). It stays in the main repo. -- `state_dir` — `definition_dir/`, declared by the README's `state:` field (commonly `.spacedock-state`). It holds the active entities, archived entities under `_archive`, and stage reports under folder-form entities. - -The launcher reads workflow identity and stage declarations from the definition README, and active entities from the state checkout. It writes frontmatter updates and archive moves to the state checkout — never to the code branch. - -## Declaring split-root - -The README opts in with one top-level frontmatter field: - -```yaml -state: .spacedock-state -``` - -The path resolves relative to the README's directory. If `state` is absent, the workflow uses the same-directory layout (entities live beside the README). - -## Concurrency-safe state commits - -The state checkout is a single shared git index. When multiple agents write entities concurrently, a bare `git add -A` would sweep up a sibling writer's staged entity. State commits are therefore path-scoped — each writer adds and commits only its own entity path — and pushed with a rebase-on-rejection retry so disjoint single-file commits replay cleanly atop one another. - -For the full storage-behavior contract, see the [external-tracker bridge](external-tracker.md) and the development workflow's state model. +[TODO] — separating workflow definition from runtime state: the two roots (`definition_dir` / `state_dir`), declaring `state:` in the README, and concurrency-safe path-scoped state commits. See the [external-tracker bridge](external-tracker.md). diff --git a/docs/site/advanced/sprints-and-roadmap.md b/docs/site/advanced/sprints-and-roadmap.md index 9b6d7eb9..d28e509a 100644 --- a/docs/site/advanced/sprints-and-roadmap.md +++ b/docs/site/advanced/sprints-and-roadmap.md @@ -1,37 +1,3 @@ # Sprints & roadmap -The roadmap is the strategy layer above the per-entity workflow. It owns outcome, scope, sequencing, and definition-of-done. It does not track task state — that lives in the workflow's state checkout and is queried with `spacedock status`. - -## The two roles - -- **The shaping first officer** owns strategy and shape: the roadmap, sprint definition (deliverable plus definition-of-done), the gating ideation of each sprint's entities, the cross-entity coherence check, the staff readiness review, and packaging each sprint as a dispatch. It stays high-level and does not hand-drive stage execution. -- **The Commander** takes one packaged sprint and drives it to its deliverable: dispatches each stage, approves execution gates and merges with judgment, runs the sprint-wide integration test, and produces the report. It boots the first-officer skill and creates its own team. It escalates only on a third feedback cycle, a budget blowout, an irrecoverable block, or a genuine scope fork. - -The handoff between them is the **dispatch package** — a self-contained sprint package the Commander runs from a cold boot, not a context transfer. - -## The sprint lifecycle - -A sprint runs in three phases: - -- **Shape** (shaping first officer) — scope-lock with the captain, carve the members, ideate each gated member with the riskiest mechanism exercised first, run an independent preflight staff review, present the ideation gates, and package the dispatch. -- **Drive** (Commander, a separate cold-booted session) — implementation → validation → done per member, with a detached adversarial audit at validation for every high-stakes surface; merge each member; run an independent pre-cut antipattern audit before the release tag fires; then cut the release. -- **Close** (shaping first officer) — fold the audit's deferred findings into the next sprint's backlog and run a light post-cut verification. - -The two independent reviews — preflight and pre-cut — are never self-reviews. Their value is refuting the first officer's own assumptions, so a fresh reviewer runs them. - -## Roadmap as a strategy layer - -The roadmap holds the value-ordered sprint sequence: each sprint and the deliverable it unlocks. It is the durable strategy document, distinct from the executable work it sequences. - -## A convention, not new code - -Today this is a **convention-only dry run** of the sprint/roadmap construct: prose plus frontmatter plus the native `status --where` query, with no new binary code. A sprint *groups* entities by a frontmatter query rather than a hard-coded list: - -```bash -# every member of a sprint -spacedock status --workflow-dir docs/dev --where sprint=019x-pre-flip-cleanups -# the drivable set (excludes deferred members) -spacedock status --workflow-dir docs/dev --where sprint=019x-pre-flip-cleanups --where 'sprint-readiness != defer' -``` - -Members carry `sprint`, `group`, and `sprint-readiness` frontmatter. There is no contract bump and no dedicated `--sprint` gate — the rollup is the native `--where` query. Whether this construct graduates into binary support depends on whether the dry run proves it. +[TODO] — the roadmap as the strategy layer above the workflow, the shaping-FO/Commander split, the sprint lifecycle (shape → drive → close), and the convention-only `status --where` sprint grouping. diff --git a/docs/site/concepts/gates-and-decisions.md b/docs/site/concepts/gates-and-decisions.md index 0f5bac1f..d4f45610 100644 --- a/docs/site/concepts/gates-and-decisions.md +++ b/docs/site/concepts/gates-and-decisions.md @@ -1,25 +1,3 @@ # Gates & decisions -A gate is the decision point at the end of a stage. Nothing advances past a gated stage without a decision — yours, or one you've delegated to an agent review. - -## What a gate carries - -Each gate carries a stage report: findings, verdicts, artifacts, and anomalies. You decide on the evidence, not the transcript. The record outlives the reviewer, so a bad result can be traced back to the call that caused it. - -At a gate, the first officer pauses and presents the stage report. You make one of three calls: - -- **Approve** — the work meets the bar; the entity advances. -- **Redo with feedback** — the work needs revision; it bounces back to an earlier stage with your concrete feedback. -- **Reject** — the work does not meet the bar. - -Some gates wait on you. Others resolve through a delegated agent review, when you've handed the call to an agent. - -## Feedback cycles and the loop cap - -Rejected work bounces back to an earlier stage for revision. To prevent loops, a hard cap limits how many times an entity can bounce. On the third consecutive rejection, the first officer escalates to you instead of auto-bouncing a fourth time — the loop never runs unbounded. - -## The detached adversarial audit - -For high-stakes surfaces — the front-door launcher, the state-mutation guards, the shipped scaffolding, and the CI/release machinery — a passing validation is necessary but not sufficient. Before merging such a change, a read-only adversarial audit runs on a separate throwaway checkout. The auditor tries to *refute* the validation: it constructs an edit that breaks the claim and confirms the deliverable's own tests catch it. A test that stays green under an edit that breaks the claim is a hole. - -This catches the class of bug where a test passes but would also pass on a broken future edit — which validation, trusting its own green suite, cannot see. "Refuted nothing material" is itself a valid, recorded outcome. +[TODO] — what a gate carries, the three calls (approve / redo with feedback / reject), feedback cycles and the loop cap, and the detached adversarial audit. diff --git a/docs/site/concepts/operating-model.md b/docs/site/concepts/operating-model.md index 4f017029..d9d4b9b3 100644 --- a/docs/site/concepts/operating-model.md +++ b/docs/site/concepts/operating-model.md @@ -1,26 +1,3 @@ # The operating model -Spacedock runs work through three roles. You set the mission and make the calls; agents do the work and bring decisions back to you. - -## Three roles - -| Role | Who | -|------|-----| -| **Captain** | You. You define the mission and make the calls at approval gates unless delegated. | -| **First Officer** | The orchestrator agent that runs the workflow and reports to you at gates. | -| **Ensign** | The worker agent that moves one item forward through one stage. | - -The first officer reads the workflow README, checks which items are ready to advance, and dispatches ensigns. Stages that need isolation run in their own git worktree; lightweight stages run inline. At a gate, the first officer pauses and presents the stage report for a decision: approve, redo with feedback, or reject. Some gates wait on you; others resolve through a delegated agent review. - -## The shaping/driving split - -At larger scale the orchestration splits into two operating roles: - -- **The shaping first officer** owns strategy and shape — the roadmap, sprint definition (deliverable plus definition-of-done), the gating ideation of each sprint's entities, the staff readiness review, and packaging each sprint as a dispatch. It stays high-level and does not hand-drive stage execution. -- **The Commander** takes one packaged sprint and drives it to its deliverable: dispatches each stage, approves execution gates and merges with judgment, runs the sprint-wide integration test, and produces the report. It escalates only on a third feedback cycle, a budget blowout, an irrecoverable block, or a genuine scope fork. - -See [Sprints & roadmap](../advanced/sprints-and-roadmap.md) for the strategy layer this split serves. - -## How the model serves you - -The point of the model is that decisions are batched and evidenced, not scattered. You queue work; agents advance each item through its stages; you handle gates as they surface, not one session at a time. Each decision leaves a trail — a stage report with findings, verdicts, artifacts, and anomalies — so you decide on evidence, not the transcript. +[TODO] — the three roles (Captain, First Officer, Ensign), the shaping/driving split, and how batched, evidenced decisions serve the captain. diff --git a/docs/site/concepts/stage-lifecycle.md b/docs/site/concepts/stage-lifecycle.md index a848805f..c3ef0d28 100644 --- a/docs/site/concepts/stage-lifecycle.md +++ b/docs/site/concepts/stage-lifecycle.md @@ -1,25 +1,3 @@ # The stage lifecycle -Work moves through stages. Each stage declares what good looks like, produces a deliverable, and routes the entity to the next stage. The development workflow's lifecycle is the canonical example: backlog → ideation → implementation → validation → done. - -## The stages - -- **backlog** — a work item enters here when it's first proposed. It has a seed description but no design work yet. -- **ideation** — a pilot fleshes out the idea: clarify the problem, explore approaches, and produce a concrete definition of done with acceptance criteria and a test plan. -- **implementation** — produce the deliverable. Write the code, generate the fixtures, make the changes the work item describes. Implementation is complete when the deliverable exists and is ready for independent verification. -- **validation** — a *fresh* agent verifies the deliverable against the acceptance criteria. The validator checks what was produced; it does not produce the deliverable itself. -- **done** — validation is complete and the captain approves. The entity closes with a verdict of PASSED or REJECTED. - -## Fresh context at validation - -Validation runs with fresh context — a separate agent that has no access to the maker's reasoning. The agent doesn't get to judge its own work. This is what makes review push back on thin evidence instead of rubber-stamping the implementation it just wrote. - -## Worktree vs. inline - -Stages that touch shared state run in their own git worktree, so concurrent work doesn't collide. Lighter stages run inline, in the repo root. The workflow README declares which stages need a worktree. - -## What a stage declares - -Each stage in the README names its inputs, its outputs, and — most importantly — what *good* and *bad* look like for that stage. The agent works to that line on its own. When a standard turns out fuzzy in practice, the agent proposes an edit to the stage's written criteria for your approval, so the bar sharpens as you use it. - -For how the transition between stages is decided, see [Gates & decisions](gates-and-decisions.md). +[TODO] — the stages (backlog → ideation → implementation → validation → done), fresh context at validation, worktree vs. inline, and what each stage declares. diff --git a/docs/site/concepts/worked-example.md b/docs/site/concepts/worked-example.md new file mode 100644 index 00000000..111b3021 --- /dev/null +++ b/docs/site/concepts/worked-example.md @@ -0,0 +1,3 @@ +# A worked example + +[TODO] — a walkthrough of one concrete, in-repo Spacedock workflow from commission to a delivered entity, tracing a single work item through the stages with real artifacts. This is the slot the `readme-real-workflow-example-link` task (e6) fills. diff --git a/docs/site/concepts/workflows-and-entities.md b/docs/site/concepts/workflows-and-entities.md index 6d0e4701..01401bbe 100644 --- a/docs/site/concepts/workflows-and-entities.md +++ b/docs/site/concepts/workflows-and-entities.md @@ -1,35 +1,3 @@ # Workflows & entities -A workflow is a directory of plain-text work items plus a README that defines the stages, the schema, and the gates. Everything about a work item lives in the file itself. - -## A workflow is a directory plus a README - -The README declares the workflow: its stages, its frontmatter schema, and which stages are gated. The work items live alongside it. The README is the single definition the first officer reads to know how to drive the workflow. - -## An entity is one work item - -An **entity** (also called a *work item*) is one markdown file — or a folder, when reports and artifacts accumulate beside it. Each entity is named `{slug}` or `{slug}.md` (lowercase, hyphens, no spaces). Use folder-form entities when reports may pile up; for example `native-go-status/index.md`. - -Everything about the work item lives in the file: the problem, the design notes, the bar for done, and the stage reports. State survives a session; the next one picks up where you left off. - -## Entity frontmatter - -Every entity carries YAML frontmatter. The field set is declared by the workflow README. The development workflow's schema is the canonical example: - -| Field | Type | Description | -|-------|------|-------------| -| `id` | string | Unique entity identifier | -| `title` | string | Human-readable name | -| `status` | enum | The current stage | -| `source` | string | Where the work item came from | -| `started` | ISO 8601 | When active work began | -| `completed` | ISO 8601 | When the entity reached its terminal stage | -| `verdict` | enum | PASSED or REJECTED — set at the final stage | -| `worktree` | string | Worktree path while a dispatched agent is active, empty otherwise | -| `issue` | string | Optional external ticket reference (e.g. `ENG-123`, `owner/repo#42`) | - -The full field reference for the development workflow lives on the [Frontmatter contract](../reference/frontmatter-contract.md) page. - -## The state checkout - -Some workflows separate the workflow *definition* from the workflow *runtime state*. With the `state-branch` profile, the README stays in the main repo while the mutable entities live in a per-workflow `.spacedock-state` checkout. This keeps state transitions out of the code branch. See [Multi-workflow & split-root state](../advanced/split-root-state.md) for how the two roots compose. +[TODO] — what a workflow is (a directory plus a README), what an entity/work item is, entity frontmatter, and the state checkout. See the [Frontmatter contract](../reference/frontmatter-contract.md) for the field reference. diff --git a/docs/site/contributing/adding-a-runtime.md b/docs/site/contributing/adding-a-runtime.md index eb4969d3..58211580 100644 --- a/docs/site/contributing/adding-a-runtime.md +++ b/docs/site/contributing/adding-a-runtime.md @@ -1,21 +1,3 @@ # Adding a runtime -A host is *supported* when a live or fixture-backed run launches it as a first officer, dispatches an ensign through its native mechanism, and verifies the resulting workflow state. A host is not supported just because its instructions mention Spacedock. - -## Add support in layers - -Each layer has its own proof: - -1. **Skill adapters** — add a first-officer and an ensign runtime adapter for the host, wired from the corresponding skill. The adapter must name the host's native dispatch mechanism, not emulate Claude's tools. -2. **Dispatch host mode** — teach `spacedock dispatch build` the host's assignment shape, keeping entity and worktree paths explicit. Test both the positive shape and the banned-tool negative case. -3. **Runtime contracts and registries** — define the minimum worker record if the host has long-lived workers, and reject stale completion evidence so a previous completion never satisfies a later assignment. -4. **Launch/install UX** — add `spacedock `, `install --host `, and `doctor --host ` only after the underlying mechanism is proven. -5. **Live runner** — prove the host with a live-gated test that asserts process exit, entity content, git log, and clean state — never transcript phrasing. - -## Manifesting from void - -When a runtime seems unsupported on first contact, don't treat setup friction as proof the path is impossible. A missing auth file, an undiscovered extension, or a different subagent tool schema is harness work, not a product blocker. Use the deliberate "assume it works" operating prompt to force the implementation loop to iron out auth, package paths, and tool-shape mismatches before declaring a blocker. - -## The full guide - -The complete runtime contract — the layer-by-layer acceptance checklist, the "manifesting from void" prompt, and the Pi live-smoke mechanism — is on the [Multi-host support](../reference/multi-host.md) page. +[TODO] — what "supported" means, adding support in layers (skill adapters → dispatch mode → registries → launch/install UX → live runner), and the "manifesting from void" operating prompt. The full guide is [Multi-host support](../reference/multi-host.md). diff --git a/docs/site/contributing/architecture-notes.md b/docs/site/contributing/architecture-notes.md index 88ca0370..9a5bf3eb 100644 --- a/docs/site/contributing/architecture-notes.md +++ b/docs/site/contributing/architecture-notes.md @@ -1,28 +1,3 @@ # Architecture notes -Notes on how the Spacedock codebase and its design contracts are organized, for contributors orienting in the repo. - -## Project shape - -The repo builds the Go-based `spacedock` launcher and the project-side skill integration: - -- `cmd/spacedock/` — the process entry point only. -- `internal/cli/` — command routing, usage text, exit-code behavior. -- `internal/status/` — status implementation and the compatibility runner. -- `docs/specs/` — design contracts. -- `docs/dev/README.md` — the development workflow definition. -- `docs/dev/.spacedock-state/` — the development workflow's entities, in a separate state checkout. -- `skills/` — the skill-facing command integration. - -The baseline gate for every change is `go test ./...`. Prefer small Go packages with clear boundaries; use the standard library unless a dependency removes real complexity; keep command output stable and test it with fixtures. - -## Design contracts - -Two specs under `docs/specs/` carry the load-bearing design semantics: - -- **State behavior extension** — the split-root storage profile (definition vs. runtime state) and the external-tracker bridge principles. See [External-tracker bridge](../advanced/external-tracker.md) and [Multi-workflow & split-root state](../advanced/split-root-state.md). -- **Scenario-testing principles** — the semantic model for scenario-based testing: what a scenario is, what an executor is (codified vs. LLM), and the variant axes a scenario runs under. It dissolves the offline/live split by treating both as two executors of one named scenario. - -## Runtime live CI - -The live lanes prove runtime behavior, not text shape. One host-neutral scenario table, per-host runner adapters implementing the same scenario IDs, and a parity guard that fails if a scenario exists for one host only. Static grep over workflow YAML or skill prose is never a substitute for launching the real host front door, observing its output, and checking the resulting workflow state. For the full discipline, see [Proof policy](proof-policy.md). +[TODO] — the project shape (`cmd/`, `internal/cli`, `internal/status`, `docs/specs`, `skills/`), the design contracts under `docs/specs/`, and the runtime live CI model. See [Proof policy](proof-policy.md). diff --git a/docs/site/contributing/proof-policy.md b/docs/site/contributing/proof-policy.md index 57fd29ea..075a2bbc 100644 --- a/docs/site/contributing/proof-policy.md +++ b/docs/site/contributing/proof-policy.md @@ -1,23 +1,3 @@ # Proof policy -A change is proven by exercising its behavior and observing the outcome — not by asserting that a file contains the right words. This is the discipline the development workflow's ideation and validation stages enforce, and it is the bar any contribution must clear. - -## Behavior is proven by exercising it - -Prove a claim by running the behavior and checking the result: output bytes, exit code, resulting on-disk state, or a test feeding many inputs and asserting uniform handling. Go unit tests for parser and command behavior, golden fixtures for stable command output, behavior fixtures that drive the binary for command-level claims, and live workflow smoke tests when runtime behavior is the claim. - -## No prose-grep acceptance criteria - -A string, substring, or regex match over an instruction file the model reads — the first-officer or ensign contract, a workflow README, a skill — never satisfies a behavioral acceptance criterion. The matched string was written by the same implementer the check is supposed to police, so a passing check only asserts "the file contains the text we put in the file." It has no independent source of truth: a valid paraphrase fails it, and an inverted clause passes it. - -The one test that settles it: **does the expected value come from somewhere other than the file under test?** If no — the clause is its own expectation — the check is a tautology and proves nothing. If yes — the file is bound to an independent source that can diverge from it — it may be a legitimate invariant. The legitimate case parses real artifacts in code and tests a relationship between independent values; for example, that the plugin manifest's contract range brackets the binary's contract version. - -## Acceptance criteria are end-state properties - -Acceptance criteria describe properties of the finished entity, not stage actions. Each criterion's "Verified by" must name something outside the entity body that can fail: a test, a command's output or exit code, a file the change produces, or the resulting on-disk state. An acceptance criterion whose only proof is reviewing the entity's own prose can never fail, so it is not an acceptance criterion. - -## The detached adversarial audit - -For high-stakes surfaces — the front-door launcher, the state-mutation guards, the shipped scaffolding, and the CI/release machinery — a passing validation is necessary but not sufficient. A read-only adversarial audit on a throwaway checkout tries to refute the validation: construct an edit that breaks the claim and confirm the deliverable's own tests catch it. A test that stays green under an edit that breaks the claim is a hole. See [Gates & decisions](../concepts/gates-and-decisions.md) for how findings route back. - -The authoritative statement of this policy lives in the development workflow's stage definitions — see [The development workflow](development-workflow.md). +[TODO] — behavior is proven by exercising it (not prose-grep), acceptance criteria as end-state properties with an independent source of truth, and the detached adversarial audit. The authoritative statement lives in [The development workflow](development-workflow.md). diff --git a/docs/site/get-started/first-launch.md b/docs/site/get-started/first-launch.md index 91cf80f7..2dc5c381 100644 --- a/docs/site/get-started/first-launch.md +++ b/docs/site/get-started/first-launch.md @@ -1,41 +1,3 @@ # Your first launch -Once the `spacedock` launcher and the host plugin are installed (see [Install](install.md)), a single command starts a session. Spacedock launches your first officer — the orchestrator agent — inside your coding harness. - -## Launch the first officer - -Point Spacedock at a project you already have and let it survey: - -```bash -spacedock claude "/spacedock:survey" -``` - -This starts the first officer in Claude Code and runs the survey skill. Using Codex or Pi instead? Swap the subcommand: - -```bash -spacedock codex "/spacedock:survey" # or: spacedock pi "/spacedock:survey" -``` - -The first launch sets up the plugin for you, so this single line is enough. When a `.safehouse` profile is present in the working directory, the launch runs sandboxed. - -## What the front door does - -The launch command is the front door. Its grammar is: - -```bash -spacedock claude "task" [--safehouse…] [-- host-flags…] -``` - -- 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`) — `--model`, `--resume`, `--plugin-dir`, and the like. -- `--safehouse` forces the launch through the sandbox; a `.safehouse` profile in the working directory does the same automatically. - -## Survey what you already built - -`/spacedock:survey` reads your project's existing agent history and reports three things: - -- the workflow you've been running without naming it, -- how you've been calling work done, -- the decisions still open and waiting on you. - -It then offers to commission a Spacedock workflow from what it found — which takes you to [your first workflow](first-workflow.md). +[TODO] — launching the first officer with `spacedock claude "/spacedock:survey"`, the front-door command grammar, and what survey reports. diff --git a/docs/site/get-started/first-workflow.md b/docs/site/get-started/first-workflow.md index 7c882207..9253e286 100644 --- a/docs/site/get-started/first-workflow.md +++ b/docs/site/get-started/first-workflow.md @@ -1,36 +1,3 @@ # Your first workflow -A workflow is a directory of plain-text work item files plus a README that defines the stages, the schema, and the gates. You commission one by describing what you want — Spacedock generates the scaffolding and starts driving it. - -## Commission a workflow - -Describe the workflow you want: - -```bash -spacedock claude "/spacedock:commission Dev task workflow: design -> plan -> -implement -> review, with the design and implementation plan inlined in each work -item, implementation on isolated worktrees with strict TDD, design and review -gated for approval." -``` - -The first officer commissions the workflow and opens a worktree for the implementation stage. It pauses at the design and review gates for your call. - -The same shape drives non-dev work. This example triages a Gmail inbox (it requires a Gmail integration set up before you run it): - -```bash -spacedock claude "/spacedock:commission Email triage: fetch, categorize, and act -on my Gmail inbox. Entity: a batch of up to 50 emails. Stages: intake (triage -in:inbox, categorize, propose an action per email as a table) -> approval -(Captain reviews the proposal) -> execute (carry out approved actions). Walk me -through Gmail setup if needed." -``` - -## What happens next - -The first officer reads the workflow README, checks which items are ready to advance, and dispatches ensigns. Stages that need isolation run in their own git worktree; lightweight stages run inline. At a gate, the first officer pauses and presents the stage report for a decision: approve, redo with feedback, or reject. Some gates wait on you; others resolve through a delegated agent review. Rejected work bounces back to an earlier stage for revision, and a hard cap prevents loops. - -## Keep going - -- To understand the roles and the lifecycle behind this, read [Concepts](../concepts/operating-model.md). -- To drive a workflow day to day — dispatch, gates, status queries — see [Running workflows](../running-workflows/operating.md). -- When you end a session, `/spacedock:debrief` captures what happened so the next session picks up where you left off. +[TODO] — commissioning your first workflow with `/spacedock:commission`, the design and review gates, and what happens after. diff --git a/docs/site/index.md b/docs/site/index.md index 2fa9d105..f9ed4a13 100644 --- a/docs/site/index.md +++ b/docs/site/index.md @@ -1,36 +1,9 @@ # Spacedock -**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 you 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. -## Why - -- 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 around. You stopped deciding the work and started just answering the agent. -- You're the agent, and you stall every few steps waiting on a human who isn't watching, with no clear scope and no clear bar for done, so you ask and then you wait. -- Generation got cheap. Your attention and judgment are now the bottleneck. Every task still ends in a decision, and no one owns it, so it falls on whoever's around. - -## What's different - -- **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 — the decision point at the end of a stage — carries a stage report: findings, verdicts, artifacts, anomalies. You decide on evidence, not the transcript. The record outlives the reviewer, so you can trace a bad result back to the call that caused it. -- **The bar sharpens as you use it.** Each stage declares what good means, and the agent works to that line on its own. When a standard turns out fuzzy in practice, the agent proposes an edit to the stage's written criteria for your approval. -- **Batch the work; decide as it flows back.** Queue many items at once. Agents advance each through its stages. You handle gates as they surface, not one session at a time. -- **Isolation when it matters.** Stages that touch shared state run in their own git worktree. Lighter stages run inline. - -## Start with what you already built - -Point Spacedock at a project you vibe-coded into spaghetti and run `/spacedock:survey`. It reads your own agent history and shows you three things: the workflow you've been running without naming it, how you've been calling work done, and the decisions still open and waiting on you. - -## Where to go next - -- New to Spacedock? Start with [Get started](get-started/install.md) — install, your first launch, and your first workflow. -- Want the mental model? Read [Concepts](concepts/operating-model.md) — the operating model, the stage lifecycle, and how gates work. -- Operating a workflow? See [Running workflows](running-workflows/commission.md). -- Contributing? Read [the development workflow](contributing/development-workflow.md) and the [voice & tone guide](contributing/voice-and-tone.md). +[TODO] — the Home page: the pitch, what's different, and where to go next (Get started, Concepts, Running workflows, Contributing). ## For agents Spacedock's docs are read by agents too — a user's first officer parsing these docs is itself an agent. The build emits an agent-readable surface: an `llms.txt` index of the docs at the site root (discoverable from each page's `` via ``) and the repo's [agent instructions](agents/index.md). - -## License - -Spacedock is released under the Apache License 2.0. diff --git a/docs/site/reference/command-reference.md b/docs/site/reference/command-reference.md index 0e3ad78b..765f46aa 100644 --- a/docs/site/reference/command-reference.md +++ b/docs/site/reference/command-reference.md @@ -1,49 +1,3 @@ # Command reference -The `spacedock` launcher groups its commands into Launch, Setup, and Workflow. Run `spacedock --help` for the per-command detail. - -## Launch - -Start a coding host as your Spacedock first officer. - -| Command | Description | -|---------|-------------| -| `spacedock claude [task] [-- claude-flags]` | Start Claude Code as your Spacedock first officer | -| `spacedock codex [task] [-- codex-flags]` | Start Codex as your Spacedock first officer | -| `spacedock pi [task] [-- pi-flags]` | Start Pi as your Spacedock first officer | - -The optional `task` is the launch prompt. Everything after `--` forwards verbatim to the host. A `--plugin-dir` launch loads a local plugin checkout and relaxes the contract gate, so it does not require a prior `spacedock install`. - -## Setup - -| Command | Description | -|---------|-------------| -| `spacedock install [--host claude\|codex\|pi]` | Install the Spacedock plugin for a host, then check it | -| `spacedock doctor [--host claude\|codex\|pi]` | Check the installed plugin and this binary are compatible | - -## Workflow - -| Command | Description | -|---------|-------------| -| `spacedock status [args]` | Show or update workflow state | -| `spacedock new [--folder] SLUG` | Create an entity from a stdin body (auto-discovers the workflow) | -| `spacedock state init` | Initialize a cloned split-root workflow's state checkout | -| `spacedock completion bash\|zsh` | Print a bash or zsh completion script | -| `spacedock dispatch build \| show-stage-def` | Build worker dispatch artifacts | - -## Other - -| Command | Description | -|---------|-------------| -| `spacedock --version` | Print the installed version | - -## Status queries - -`spacedock status` reads workflow state. Common forms: - -```bash -spacedock status --workflow-dir docs/dev # the status table -spacedock status --workflow-dir docs/dev --next # entities ready to dispatch -spacedock status --workflow-dir docs/dev --where sprint=0200-flip # filter by frontmatter -spacedock status --workflow-dir docs/dev --validate # entity-contract validation -``` +[TODO] — the `spacedock` command surface grouped into Launch (`claude`/`codex`/`pi`), Setup (`install`/`doctor`), and Workflow (`status`/`new`/`state`/`completion`/`dispatch`), plus `--version` and the `status` query forms. diff --git a/docs/site/reference/frontmatter-contract.md b/docs/site/reference/frontmatter-contract.md index 01fdc433..b416c3ee 100644 --- a/docs/site/reference/frontmatter-contract.md +++ b/docs/site/reference/frontmatter-contract.md @@ -1,29 +1,3 @@ # Frontmatter contract -Every entity carries YAML frontmatter. The field set a workflow uses is declared in its README. This page surfaces the development workflow's schema as the canonical reference; a standalone, workflow-neutral contract spec under `docs/specs/` is a planned follow-up. - -## Field reference (development workflow) - -| Field | Type | Description | -|-------|------|-------------| -| `id` | string | Unique 24-character Spacedock Base32 ID (this workflow uses `sd-b32`) | -| `title` | string | Human-readable task name | -| `status` | enum | One of: backlog, ideation, implementation, validation, done | -| `source` | string | Where this task came from | -| `started` | ISO 8601 | When active work began | -| `completed` | ISO 8601 | When the task reached terminal status | -| `verdict` | enum | PASSED or REJECTED — set at the final stage | -| `score` | number | Priority score, 0.0–1.0 (optional). Workflows can upgrade to a multi-dimension rubric in their README. | -| `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` | - -The authoritative, always-current copy of this schema is the development workflow's README — see [The development workflow](../contributing/development-workflow.md), under "Schema / Field Reference". - -## External tracker fields - -When an entity originates from an external ticket system, two flat fields bridge it: - -- `issue` — the human-facing external reference. -- `source` — where the entity came from (e.g. `linear`, `kata`). - -Spacedock status remains the execution status unless a future bridge explicitly declares bidirectional ownership. For the full bridge contract, see [External-tracker bridge](../advanced/external-tracker.md). +[TODO] — the entity frontmatter field reference (surfacing the development workflow's "Schema / Field Reference" table) plus the external-tracker `issue`/`source` fields. The always-current schema is in [The development workflow](../contributing/development-workflow.md); a standalone `docs/specs/frontmatter-contract.md` is a planned follow-up. diff --git a/docs/site/running-workflows/commission.md b/docs/site/running-workflows/commission.md index d1cca6c5..9a7b44ed 100644 --- a/docs/site/running-workflows/commission.md +++ b/docs/site/running-workflows/commission.md @@ -1,31 +1,3 @@ # Commission a workflow -Commissioning generates a new workflow from a description. You say what stages you want, what an entity is, and which stages are gated; Spacedock writes the scaffolding and the first officer starts driving it. - -## Run the commission skill - -```bash -spacedock claude "/spacedock:commission " -``` - -A useful description names four things: - -- **The stages** and their order (e.g. `design -> plan -> implement -> review`). -- **The entity** — what one work item is (a task, a batch of emails, a document). -- **Which stages are gated** — where you want to approve before the work advances. -- **Any per-stage rules** — isolated worktrees, strict TDD, inlined design notes. - -## Example - -```bash -spacedock claude "/spacedock:commission Dev task workflow: design -> plan -> -implement -> review, with the design and implementation plan inlined in each work -item, implementation on isolated worktrees with strict TDD, design and review -gated for approval." -``` - -The first officer commissions the workflow and opens a worktree for the implementation stage, pausing at the design and review gates for your call. - -## After commissioning - -Once the workflow exists, you drive it: add entities, dispatch stages, and handle gates. See [Operating a workflow](operating.md) for the day-to-day loop. If you're starting from an existing project rather than a blank slate, [survey it first](survey.md). +[TODO] — generating a workflow from a description with `/spacedock:commission`: the four things to name (stages, entity, gated stages, per-stage rules) and what the first officer does next. diff --git a/docs/site/running-workflows/debrief-and-refit.md b/docs/site/running-workflows/debrief-and-refit.md index 2b406ac6..fa6e6b17 100644 --- a/docs/site/running-workflows/debrief-and-refit.md +++ b/docs/site/running-workflows/debrief-and-refit.md @@ -1,23 +1,3 @@ # Debrief & refit -Two skills keep a workflow durable across sessions and across Spacedock releases: `debrief` captures what a session did so the next one resumes from it, and `refit` upgrades your workflow scaffolding when a new Spacedock release lands. - -## Debrief: capture a session - -When you end a session, run: - -```bash -spacedock claude "/spacedock:debrief" -``` - -It captures what happened — commits, state changes, decisions, and open issues — into a record the next session picks up. Because the record lives with the workflow, the next session starts from where you left off instead of from a cold transcript. - -## Refit: upgrade your scaffolding - -When a new Spacedock release is out, run: - -```bash -spacedock claude "/spacedock:refit" -``` - -It upgrades your workflow's scaffolding files to the current version while keeping your local modifications. Use it to bring an existing workflow's structure up to date without losing the project-specific edits you've made. +[TODO] — `/spacedock:debrief` (capture a session into a record the next one resumes from) and `/spacedock:refit` (upgrade workflow scaffolding to the current release while keeping local edits). diff --git a/docs/site/running-workflows/example.md b/docs/site/running-workflows/example.md deleted file mode 100644 index 508b4e28..00000000 --- a/docs/site/running-workflows/example.md +++ /dev/null @@ -1,5 +0,0 @@ -# Example: a real workflow - -A walkthrough of one concrete, in-repo Spacedock workflow — from commission to a delivered entity — is coming. It will trace a single real work item through the stages so you can see the loop end to end with real artifacts. - -Until then, see [Commission a workflow](commission.md) and [Operating a workflow](operating.md) for the steps, and [The stage lifecycle](../concepts/stage-lifecycle.md) for the model the example will illustrate. diff --git a/docs/site/running-workflows/operating.md b/docs/site/running-workflows/operating.md index d97e86d2..6b4aaa27 100644 --- a/docs/site/running-workflows/operating.md +++ b/docs/site/running-workflows/operating.md @@ -1,39 +1,3 @@ # Operating a workflow -Driving a workflow is a loop: see what's ready, dispatch it, handle the gates that surface. The first officer runs the loop; you make the calls. - -## The loop - -The first officer reads the workflow README, checks which entities are ready to advance, and dispatches ensigns. Stages that need isolation run in their own git worktree; lightweight stages run inline. As work flows back, the first officer presents each gate for your decision — approve, redo with feedback, or reject. - -## Check workflow state - -Read the current state of a workflow with the launcher: - -```bash -spacedock status --workflow-dir docs/dev -``` - -To list the entities ready for dispatch — the query the first officer runs each loop: - -```bash -spacedock status --workflow-dir docs/dev --next -``` - -To filter entities by a frontmatter field, use `--where`: - -```bash -spacedock status --workflow-dir docs/dev --where sprint=0200-flip -``` - -See the [Command reference](../reference/command-reference.md) for the full `status` surface. - -## Handling gates - -When the first officer pauses at a gate, it presents the stage report. Decide on the evidence in the report, not the transcript: - -- **Approve** to advance the entity. -- **Redo with feedback** to bounce it back to an earlier stage with concrete direction. -- **Reject** when it does not meet the bar. - -For the mechanics of gates, feedback cycles, and the loop cap, see [Gates & decisions](../concepts/gates-and-decisions.md). +[TODO] — the day-to-day loop (see what's ready, dispatch, handle gates), the `spacedock status` queries (`--next`, `--where`), and handling gate decisions. See the [Command reference](../reference/command-reference.md). diff --git a/docs/site/running-workflows/survey.md b/docs/site/running-workflows/survey.md index 7b58362c..b5ff6ce2 100644 --- a/docs/site/running-workflows/survey.md +++ b/docs/site/running-workflows/survey.md @@ -1,19 +1,3 @@ # Survey an existing project -Survey reads a brownfield project's own agent history and reports the implicit workflow you've been running — before you commit to any structure. Use it when you arrive at a project with prior agent work and want the lay of the land. - -## Run the survey skill - -```bash -spacedock claude "/spacedock:survey" -``` - -Point it at a project you already have. It reads your own agent session history (read-only) and reports three things: - -- the workflow you've been running without naming it, -- how you've been calling work done, -- the decisions still open and waiting on you. - -## From survey to a workflow - -The survey is read-only — it changes nothing. After reporting, it offers to commission a Spacedock workflow from what it found, so the implicit structure becomes an explicit one you can drive. From there, see [Commission a workflow](commission.md) and [Operating a workflow](operating.md). +[TODO] — reading a brownfield project's agent history with `/spacedock:survey` (read-only), what it reports, and how it offers to commission a workflow from what it found. diff --git a/mkdocs.yml b/mkdocs.yml index be3683a1..d42c3881 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -26,7 +26,8 @@ theme: - content.tabs.link - search.suggest - search.highlight - - navigation.sections + - navigation.tabs + - navigation.tabs.sticky - navigation.instant plugins: @@ -65,12 +66,12 @@ 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 - Survey an existing project: running-workflows/survey.md - Operating a workflow: running-workflows/operating.md - Debrief & refit: running-workflows/debrief-and-refit.md - - "Example: a real workflow": running-workflows/example.md - Advanced topics: - Sprints & roadmap: advanced/sprints-and-roadmap.md - Mods & standing teammates: advanced/mods-and-standing-teammates.md From b1213bc3ffd47e2ad46615e19553d69e22a4d4d8 Mon Sep 17 00:00:00 2001 From: CL Kao Date: Mon, 8 Jun 2026 21:26:20 -0700 Subject: [PATCH 4/5] docs site: make for-agents head links subpath-safe (base-aware, no leading slash) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Change the head hrefs from root-absolute `{{ '/llms.txt' | url }}` to base-aware `{{ 'llms.txt' | url }}` (no leading slash) for both llms.txt and agents/, so they resolve to the site-root files whether the site deploys at the domain root OR under a /spacedock/ project-Pages subpath. Rendered: href="llms.txt" / "agents/" on the root page; href="../../llms.txt" / "../../agents/" on nested pages — each resolving to the real site-root file. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/overrides/main.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/overrides/main.html b/docs/overrides/main.html index 678bce90..6d4c5a90 100644 --- a/docs/overrides/main.html +++ b/docs/overrides/main.html @@ -7,6 +7,6 @@ the standards-safe form. --> {% block extrahead %} {{ super() }} - - + + {% endblock %} From b62597ae57f2005e09ab6ac41d27eca0287a4ace Mon Sep 17 00:00:00 2001 From: CL Kao Date: Mon, 8 Jun 2026 21:37:00 -0700 Subject: [PATCH 5/5] docs site: cut the for-agents head-link surface; re-home AGENTS.md to Contributing MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Captain correction: the "For agents" surface conflated two different agents. AGENTS.md is repo-DEVELOPMENT guidance (an agent working ON Spacedock), not product-using-agent guidance — that's what /llms.txt already covers. - Remove the head block; remove docs/overrides/main.html entirely (it had no other purpose) and the theme.custom_dir reference. - Keep /llms.txt at the build root as the product-using-agent surface (mkdocs-llmstxt output, a14y-scored), discoverable via the canonical path — no head link needed. Drop the "For agents" llmstxt section. - Re-home AGENTS.md as contributor content: move the symlink docs/site/agents/index.md -> docs/site/contributing/agent-development.md and give it a Contributing nav entry "Agent development" (replacing the top-level "For agents" nav entry), so the page stays in-nav and --strict stays green. - Reframe the Home agent note: /llms.txt for product-using agents; repo-dev guidance points to Contributing -> Agent development. mkdocs build --strict green; 0 head-link tags; /llms.txt at root; AGENTS.md renders at contributing/agent-development/. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/overrides/main.html | 12 ------------ .../index.md => contributing/agent-development.md} | 0 docs/site/index.md | 4 ++-- mkdocs.yml | 5 +---- 4 files changed, 3 insertions(+), 18 deletions(-) delete mode 100644 docs/overrides/main.html rename docs/site/{agents/index.md => contributing/agent-development.md} (100%) diff --git a/docs/overrides/main.html b/docs/overrides/main.html deleted file mode 100644 index 6d4c5a90..00000000 --- a/docs/overrides/main.html +++ /dev/null @@ -1,12 +0,0 @@ -{% extends "base.html" %} - - -{% block extrahead %} - {{ super() }} - - -{% endblock %} diff --git a/docs/site/agents/index.md b/docs/site/contributing/agent-development.md similarity index 100% rename from docs/site/agents/index.md rename to docs/site/contributing/agent-development.md diff --git a/docs/site/index.md b/docs/site/index.md index f9ed4a13..8cd4c729 100644 --- a/docs/site/index.md +++ b/docs/site/index.md @@ -4,6 +4,6 @@ [TODO] — the Home page: the pitch, what's different, and where to go next (Get started, Concepts, Running workflows, Contributing). -## For agents +## 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 an agent-readable surface: an `llms.txt` index of the docs at the site root (discoverable from each page's `` via ``) and the repo's [agent instructions](agents/index.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. (Repo-development guidance for an agent working ON Spacedock lives under Contributing → [Agent development](contributing/agent-development.md).) diff --git a/mkdocs.yml b/mkdocs.yml index d42c3881..9bf93bc5 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -9,7 +9,6 @@ docs_dir: docs/site theme: name: material - custom_dir: docs/overrides palette: - media: "(prefers-color-scheme: light)" scheme: default @@ -52,8 +51,6 @@ plugins: - reference/*.md Contributing: - contributing/*.md - For agents: - - agents/*.md nav: - Home: index.md @@ -83,12 +80,12 @@ nav: - Multi-host support: reference/multi-host.md - Contributing: - The development workflow: contributing/development-workflow.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 - - For agents: agents/index.md markdown_extensions: - admonition