Local-harness SDD authoring skills → plan:provided handoff (Claude Code / Cursor / OpenCode / Hermes)

[norrietaylor]

Summary

Ship the SDD methodology as portable local agent skills (Claude Code, Cursor, OpenCode, Hermes) that author an SDD-grade plan on the developer's machine and hand off to the cloud pipeline via the existing plan:provided marker. Convergence at the spec/skill layer; cloud execution and governance unchanged.

Motivation

• No inner-loop / local / offline story today; the GitHub-primitives-only ceiling means no local dry-run or authoring.
• Cloud engine is Claude-centric. Local skills add multi-agent breadth at the authoring layer without abstracting the cloud engine, so the model-tier execution moat is preserved.
• Both gaps close cheaply because the two hard parts already exist:
  • Methodology core is already factored into shared/*.md fragments consumed via gh-aw imports:.
  • Handoff is already implemented: plan:provided → sdd-triage architecture-translation mode.

Scope (approved)

Authoring front-end → cloud. Shared core + thin per-harness adapters. Local execute/review is out of scope.

Design

1. shared/sdd-authoring.md — local authoring flow + the plan:provided output contract (plan body → R-IDs / demoable units → issue+label). Composes the agent-portable fragments: principles, rigor, sdd-gates, sdd-interaction, sdd-proof-artifacts, repo-conventions. Excludes runtime/MCP/gh-aw fragments (runtime-setup, sdd-mcp-*, *-cleanup).
2. Composition build step (analog of inlined-imports / recompile-locks) so cloud workflows and local skills stay in sync from one source; guarded by a drift snapshot test.
3. Thin per-harness adapters, all referencing the same body: Claude Code skill (SKILL.md), Cursor .cursor/rules/*.mdc, OpenCode agent config, Hermes (format TBD).
4. Installer: extend scripts/quick-setup.sh --suite or add scripts/install-local-skill.sh — same thin-wrapper install model as the cloud suite (ADR-0004).
5. Handoff contract doc cross-checked against sdd-triage.md architecture-translation-mode expectations so triage parses the emitted plan reliably.
6. Docs docs/sdd/local-authoring.md (+ mkdocs nav) and ADR decisions/0020-local-authoring-skills.md.

Acceptance

• Composed authoring body contains gate / proof-artifact / R-ID guidance and the plan:provided contract (test: scripts/test-local-authoring.py, mirroring scripts/test-requirement-ids.py).
• Drift snapshot test fails if the composed body diverges from its source fragments (mirror scripts/test-digest-snapshot.py).
• Adapter installs in a scratch repo for Claude Code + at least one other harness; idempotent re-run.
• E2E: skill authors a plan → opens a plan:provided issue → sdd-triage enters translation mode → task graph produced.
• markdownlint + mkdocs build clean; recompile-locks stays green (no cloud workflow behavior changed — only new shared fragment, docs, skill assets).

Reuse anchors (do not rebuild)

shared/*.md methodology fragments; .github/workflows/sdd-spec.md imports: composition pattern; sdd-triage.md plan:provided translation mode; scripts/quick-setup.sh thin-install; scripts/test-*.py test harness pattern; decisions/ ADR convention.

Out of scope (logged)

Full local execute/review loop; transcript/forensic provenance; post-merge circuit-breaker; release tags / E2E (#87/#89/#91) / second maintainer; cost circuit-breaker; methodology depth-vs-friction default. The authoring-body composition does seed a cheap future local replay harness for #91.

Open question

Hermes target/format.

Context

Emerged from a shootout vs glasner/aiki (inner-loop local Rust CLI). aiki's distinguishing strengths are a local/offline loop and agent-agnosticism; this captures the authoring-layer subset that maps cleanly onto spectacles without adopting Jujutsu or a local runtime. Note for prioritization: a prior claim that aiki "owns an auto-fix loop spectacles lacks" was disproved — sdd-route-execute already runs two bounded auto-revise loops (cap 3), so auto-fix is not a gap.