docs: add MkDocs Material documentation site with GitHub Pages deploy

48 documentation pages covering getting started, workflow phases,
all 16 commands, 10 agents, reference guides, and advanced features.
GitHub Action deploys to Pages on push to main.

Author: Habib0x0

.github/workflows/docs.yml

@@ -0,0 +1,46 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - run: pip install mkdocs-material
+
+      - run: mkdocs build --strict
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -5,3 +5,4 @@
 .claude/*.local.md
 .claude/*.local.json
 .claude/specs/.worktrees/
+site/

docs/advanced/ci-cd.md

@@ -0,0 +1,96 @@
+# CI/CD integration
+
+The post-implementation scripts are designed to work in CI pipelines. They use exit codes and promise markers to communicate status to the calling process.
+
+## Exit codes
+
+| Script | Exit 0 | Exit 1 |
+|--------|--------|--------|
+| `spec-verify.sh` | All smoke tests pass (PASS) | One or more checks failed (FAIL) |
+| `spec-loop.sh` | Completed normally (all tasks done or max iterations reached) | Unexpected error |
+| `spec-accept.sh` | Script completed (check promise marker for ACCEPTED/REJECTED) | Script error |
+
+## Promise markers
+
+Scripts that produce structured outcomes write promise markers in their output:
+
+| Script | Markers |
+|--------|---------|
+| `spec-loop.sh` | `<promise>COMPLETE</promise>` |
+| `spec-accept.sh` | `<promise>ACCEPTED</promise>` or `<promise>REJECTED</promise>` |
+| `spec-retro.sh` | `<promise>RETRO_COMPLETE</promise>` |
+
+These markers let the calling script detect outcomes reliably without parsing human-readable prose.
+
+## Example CI stages
+
+### Post-deployment smoke test
+
+Use `spec-verify.sh` as a deployment gate. The script exits 1 if any smoke test fails, which fails the CI step:
+
+```bash
+spec-verify.sh --spec-name user-authentication \
+  --url "$STAGING_URL" \
+  --scope quick || exit 1
+```
+
+For a full smoke test on staging before promoting to production:
+
+```bash
+spec-verify.sh --spec-name user-authentication \
+  --url "$STAGING_URL"
+```
+
+### Acceptance gate before release
+
+Check the promise marker from `spec-accept.sh` to gate the release stage:
+
+```bash
+output=$(spec-accept.sh --spec-name user-authentication)
+if echo "$output" | grep -q '<promise>ACCEPTED</promise>'; then
+  echo "Acceptance passed, proceeding to release"
+else
+  echo "Acceptance failed, aborting release"
+  exit 1
+fi
+```
+
+### Automated implementation loop in CI
+
+Run the implementation loop in CI with a bounded iteration count. The loop exits 0 when complete or when max iterations is reached:
+
+```bash
+spec-loop.sh \
+  --spec-name user-authentication \
+  --max-iterations 30 \
+  --no-worktree
+```
+
+!!!warning
+    Running `spec-loop.sh` in CI requires `claude --dangerously-skip-permissions`, which the script uses internally. Only do this in isolated CI environments where you control what code Claude can access and execute.
+
+## Suggested pipeline order
+
+For a full automated pipeline after implementation:
+
+```bash
+# 1. Run acceptance testing
+spec-accept.sh --spec-name "$SPEC"
+
+# 2. Deploy to staging (your deploy step here)
+
+# 3. Smoke test on staging
+spec-verify.sh --spec-name "$SPEC" --url "$STAGING_URL" || exit 1
+
+# 4. Generate release artifacts
+spec-release.sh --spec-name "$SPEC" --version-bump minor --release
+
+# 5. Deploy to production (your deploy step here)
+
+# 6. Verify production
+spec-verify.sh --spec-name "$SPEC" --url "$PROD_URL" --scope quick || exit 1
+```
+
+## Scope flag for spec-verify.sh
+
+`--scope quick` runs a lightweight health check — useful for production verification where you want fast feedback without running the full test suite. The default (no `--scope` flag) runs the full smoke test battery.

docs/advanced/crash-recovery.md

@@ -0,0 +1,49 @@
+# Crash recovery
+
+`spec-loop.sh` and `spec-team.sh` implement crash recovery via checkpoint commits. If Claude exits with a non-zero exit code during an iteration, the branch is automatically rolled back to the state before that iteration started.
+
+## How checkpoints work
+
+At the start of each iteration, before Claude is invoked, the script calls `create_checkpoint()` from `scripts/lib/checkpoint.sh`:
+
+1. Check for uncommitted changes (staged or unstaged) in the working directory
+2. If changes exist, stage everything and create a commit: `checkpoint: pre-iteration N`
+3. Record the commit hash as `CHECKPOINT_SHA`
+
+If there are no uncommitted changes (the previous iteration committed cleanly), no checkpoint commit is created and `CHECKPOINT_SHA` is empty.
+
+## Rollback behavior
+
+After Claude exits, the script checks the exit code:
+
+- **Exit code 0** — success, no rollback needed
+- **Non-zero exit code with a checkpoint** — call `git reset --hard <CHECKPOINT_SHA>` to discard the failed iteration's partial work and return to the pre-iteration state
+- **Non-zero exit code without a checkpoint** — nothing to roll back, continue
+
+If `git reset --hard` itself fails (rare), the script prints a critical warning and the path to the worktree so you can inspect manually.
+
+## What triggers a non-zero exit
+
+Claude exits non-zero when it encounters an unrecoverable error: tool failures, network issues, hitting context limits, or explicit errors. Rollback ensures these situations leave the codebase in a clean state rather than with half-written code.
+
+## Checkpoint commits in git history
+
+Checkpoint commits appear in git history with the message `checkpoint: pre-iteration N`. They are real commits on the spec branch. When you open a PR, you may want to squash or rebase these out:
+
+```bash
+git rebase -i main
+```
+
+## Manual recovery
+
+If you need to recover manually, checkpoint commits are labeled and easy to find:
+
+```bash
+git log --oneline | grep checkpoint
+```
+
+Roll back to a specific checkpoint:
+
+```bash
+git reset --hard <checkpoint-sha>
+```

docs/advanced/cross-spec-deps.md

@@ -0,0 +1,80 @@
+# Cross-spec dependencies
+
+Specs can declare dependencies on other specs. Execution scripts check that all declared dependencies are fully complete before starting any implementation work.
+
+## Declaring dependencies
+
+Add a `## Depends On` section to the spec's `requirements.md`:
+
+```markdown
+## Depends On
+
+- auth-system
+- database-migrations
+```
+
+List one dependency per line as a bullet. Each entry is the name of another spec in `.claude/specs/`.
+
+Remove the section entirely if the spec has no dependencies.
+
+## What "complete" means
+
+A dependency is considered complete when every task in its `tasks.md` satisfies all three conditions:
+
+- `Status: completed`
+- `Wired: yes` or `Wired: n/a`
+- `Verified: yes`
+
+A dependency with any task that does not meet all three conditions is considered incomplete, and the dependent spec's execution scripts will refuse to start.
+
+## Dependency check behavior
+
+When you run `spec-loop.sh`, `spec-exec.sh`, or `spec-team.sh`, the script calls `check_dependencies()` before creating any worktree or running any iteration.
+
+If a dependency is not found:
+
+```
+Error: Dependency spec not found: auth-system
+```
+
+If a dependency has no `tasks.md`:
+
+```
+Error: Dependency auth-system has no tasks.md
+```
+
+If a dependency is incomplete:
+
+```
+Error: Dependency incomplete: auth-system (4/7 tasks verified)
+```
+
+The script exits with code 1. Fix or complete the dependency before running the dependent spec.
+
+## Circular dependency detection
+
+The scripts detect circular dependencies using a depth-first search before checking completion status. If a cycle is found, the script exits immediately with an error:
+
+```
+Error: Circular dependency detected: spec-a -> spec-b -> spec-a
+```
+
+Circular dependencies cannot be resolved automatically — you need to restructure your specs to break the cycle.
+
+## Viewing dependency status
+
+Use `/spec-status` to see the dependency status for the current spec:
+
+```
+Dependencies:
+  auth-system: complete (7/7 tasks verified)
+  database-migrations: incomplete (3/5 tasks verified)
+```
+
+This output comes from `get_dependency_status()` in `scripts/lib/deps.sh`, which reads the `## Depends On` section and checks each referenced spec.
+
+## Multiple specs in parallel
+
+Specs without dependencies on each other can run in parallel on separate worktrees. Because each spec gets its own branch (`spec/<name>`), parallel execution does not cause conflicts.
+
+Specs with a dependency chain must run in order: complete the dependency first, then start the dependent spec.