spiral-html

name

spiral-html

description

HTML-first bootstrap and audit of the structural-discipline scaffold (GDD tree, coverage ledger, progress log, open questions, followups, playtest gate) that takes a vision into a delivered system through small iterations whose state lives in git, not the agent's head. Same methodology as spiral; ledgers, rules, and contracts are written in HTML rather than Markdown. Slash commands /spiral-html-init and /spiral-html-audit live under commands/.

Spiral (HTML edition)

The methodology for sustaining a multi-week autonomous PR loop without the agent losing context, running out of work prematurely, or accumulating debt. This is the HTML-first variant of spiral: the scaffold is identical in shape, but every ledger, rule, and contract is authored as HTML rather than Markdown.

The agent does not remember the project. The project remembers itself. Every kind of state lives in git-tracked ledger files with rigid templates. The agent's job collapses to: read ledgers, pick the next slice, run the loop, update ledgers. Every iteration returns to the same artifacts and finds them advanced. The shape is not a loop, it is a spiral: forward-while-circling.

Why HTML

HTML is the new way to communicate to agents. Structured elements (<section>, <article>, <table>, <ol>, <dl>, <details>) carry semantics that Markdown discards. An agent reading <section data-role="rule" data-id="rule-1"> can locate, cite, and update content without parsing prose. The audit script in this skill exploits that: it grep-checks for HTML attributes rather than heading prefixes.

Two files must stay Markdown: AGENTS.md and CLAUDE.md. Codex's native root-down walk only picks up AGENTS.md, and Claude Code's project-memory import only resolves CLAUDE.md. The contract therefore lives in AGENTS.md as Markdown; CLAUDE.md is a one-liner (@AGENTS.md) so Claude Code imports the same rules. Everything else under docs/ is HTML.

Path-scoped Rules under .claude/rules/ retain YAML frontmatter (Claude Code requires it for path globbing); only the body becomes HTML.

When to invoke

• /spiral-html init: at the start of a fresh project. Writes the canonical HTML scaffold (rules, plan, agreement, GDD tree, coverage ledger, progress log, open questions, followups, playtest, fun-factor audit) into the current repo.
• /spiral-html audit: on an existing project. Diffs the repo against the canonical HTML structure and prints a remediation checklist. Catches the three known failure modes (monolith GDD, chapter-granular coverage, missing qualitative gate) plus generic drift.

Per-slice execution (read context, branch, implement, PR, merge, repeat) is the job of randroid:loop. Per-task tracking is the job of task-tracking-dots-html (the HTML-backed dot-html fork, NOT the Markdown task-tracking-dots). This skill is the substrate those two run against.

Why this exists: the three case studies

Three multi-week autonomous-loop projects produced three outcomes. The pattern is in docs/case-studies.html. The short version:

• VibeRacer (14 days, 184 commits): shipped a complete v1. Single-file 28-section GDD with explicit out-of-scope §18 fence. The loop terminated cleanly.
• VibeGear2 (7 days, 298 commits): still actively shipping P0/P1 fun work a week in. Sectioned docs/gdd/ tree, 102 atomic coverage rows, plus FUN_FACTOR_GAP_AUDIT and RELEASE_FUN_PLAYTEST as a second qualitative gate that re-opens the loop after systems land.
• Flatline (3 days, 94 commits): self-terminated with 0 open dots, 0 open questions, 1 deferred doc cleanup. The product was not fun. Coverage rows were chapter-granular (11 rows, all implemented once any code shipped). No qualitative gate.

Flatline is the failure case this skill explicitly prevents. The audit script flags both the chapter-granular coverage anti-pattern and the missing qualitative gate.

The scaffold

/spiral-html init writes these files into the target repo:

Path	Role
AGENTS.md	Rules-as-contract in Markdown (stays Markdown so Codex's root-down walk works): em-dash ban, pre-slice reading list, stack constraints, commit style, autonomous PR loop reference, secrets policy, testing expectations, pre-commit checklist. The pre-slice reading list points at the .html ledgers.
CLAUDE.md	One line: @AGENTS.md. Claude Code's project-memory import only resolves CLAUDE.md, so the file exists to forward the same rules.
docs/IMPLEMENTATION_PLAN.html	The 18-step loop contract. Slice selection priority. Definition of done.
docs/WORKING_AGREEMENT.html	Process: branches, commits, PR template, bot-review settled-wait gate, verification minimums, merge-and-deploy expectations, risk gates.
docs/gdd/index.html	GDD tree index. Each requirement is its own file. Build logs grow per-section as work ships.
docs/GDD_COVERAGE.json	Atomic-row spec to code traceability. One row per requirement, not per chapter. Stays JSON (data, not prose).
docs/PROGRESS_LOG.html	Append-only slice receipts as <article data-slice="..."> elements (Branch / Changed / Verification / Assumptions / GDD coverage / Followups). Newest on top.
docs/OPEN_QUESTIONS.html	<section data-q="Q-NNN"> entries with options, recommended default, status, resolution. Defaults let the loop ship without blocking.
docs/FOLLOWUPS.html	<section data-f="F-NNN"> entries with priority (blocks-release, nice-to-have, polish), blocker condition, unblock condition.
docs/DEPENDENCY_LEDGER.html	Watched dependencies with currently-pinned version + per-dep upgrade procedure. The Dependency Upgrade Gate fires every loop iteration that touches main.
docs/PLAYTEST.html	Qualitative second-gate checklist. The loop is not done until this resolves.
docs/FUN_FACTOR_AUDIT.html	Qualitative gap-finder. Run when coverage is ≥80% done. Source of P0/P1 polish work.
.claude/rules/slice-discipline.md	Path-scoped Rule. YAML frontmatter for path globbing; HTML body. Loads when editing source. Enforces "no drive-by refactors, no speculative abstractions, refactor-in-slice".
.claude/rules/ledger-append-only.md	Path-scoped Rule. YAML frontmatter for path globbing; HTML body. Loads when editing the four ledger files. Enforces append-only, never-rewrite-past-entries.
.claude/rules/gdd-build-log.md	Path-scoped Rule. YAML frontmatter for path globbing; HTML body. Loads when editing GDD section files. Enforces build-log-on-every-shipped-feature.

Cross-tool compatibility

The HTML-first scaffold cannot rely on every discovery contract the Markdown version uses. Two files stay Markdown so the canonical discovery paths keep working:

• AGENTS.md (the Codex-required filename) carries the full contract as Markdown. Codex's root-down walk finds and reads it directly. The reading list inside points at the .html ledgers.
• CLAUDE.md (the Claude Code project-memory filename) contains one line: @AGENTS.md. Claude Code's import mechanism resolves the pointer and loads the same contract.
• .claude/rules/*.md keep YAML frontmatter and the .md filename because Claude Code's path-scoped Rules system parses the frontmatter to decide when to load. The body inside each rule is HTML.
• The Codex per-directory AGENTS.md symlinks point at the rules files (still .md); Codex reads the YAML frontmatter and HTML body uniformly.

The seven parts of the spiral

1. Vision: the canonical spec (GDD tree, atomic requirements) as HTML section files.
2. Contract: the three docs that govern every iteration (rules in AGENTS.md, plan, agreement).
3. Slice: the bounded unit of work (one PR, one log entry, small enough that a botched slice is reverted in one click).
4. Ledgers: externalized memory (progress log, open questions, followups, coverage) as append-only HTML elements with data-* ids.
5. Gates: what blocks merge AND what triggers a slice. Mechanical (CI green, type-check, tests, no em-dash, bot-review settled). Qualitative (playtest, fun-factor audit). Dependency Upgrade Gate (see docs/DEPENDENCY_LEDGER.html): a watched-dep release is the same kind of fresh state as a new commit on main; the agent observes and acts at every loop boundary that touches main. The qualitative gate is the second gate that prevents Flatline-style early termination.
6. Selection rule: what to work on next: red CI > pending dep upgrade > P0/P1 dot > answered open question > high-priority followup > coverage gap > partial GDD section > cleanup.
7. Loop: the continuous operation. Read context, pick slice, branch, implement, test, update ledgers, PR, handle review, wait for bot + CI, merge, pull main, smoke prod, close item, start next. Never voluntarily idles. Executed by randroid:loop.

How init works

Invocation: /spiral-html init from inside a target git repo, or bash ${CLAUDE_PLUGIN_ROOT}/scripts/init.sh "<ProjectName>" "<one-line-pitch>" "<stack>".

The script:

1. Refuses to run if AGENTS.md already exists at the repo root. Use audit instead.
2. Prompts for project name, one-line pitch, and stack if not passed as args.
3. Copies every template file into the target repo, substituting {{PROJECT_NAME}}, {{PITCH}}, {{STACK}}, {{TODAY}}.
4. Creates docs/gdd/ for the GDD tree and .claude/rules/ for the path-scoped Rules.
5. Writes AGENTS.md (the full Markdown contract) and CLAUDE.md (one-line @AGENTS.md import).
6. Verifies em-dash cleanliness on every written file.
7. Prints a next-steps note: draft the first GDD section under docs/gdd/, then run /randroid:loop implement to start the spiral.

How audit works

Invocation: /spiral-html audit from inside any git repo, or bash ${CLAUDE_PLUGIN_ROOT}/scripts/audit.sh.

The script runs nine checks and prints a remediation checklist:

1. Missing canonical files. Verifies the scaffold is present: the Markdown contract pair (AGENTS.md, CLAUDE.md), the docs HTML ledger set including DEPENDENCY_LEDGER.html, and the three .claude/rules files.
2. Monolith GDD. Warns if docs/GDD.html exists alone without a docs/gdd/ directory.
3. Chapter-granular coverage. Counts rows in docs/GDD_COVERAGE.json. Warns if row count is implausibly low for project age (heuristic: fewer than 14 rows per project-week).
4. Missing qualitative gate. Warns if docs/PLAYTEST.html or docs/FUN_FACTOR_AUDIT.html is missing.
5. Stale progress log. Reads the newest <article data-date="YYYY-MM-DD"> in docs/PROGRESS_LOG.html. Warns if older than 7 days.
6. Open questions without defaults. Warns on any <section data-q="..."> missing a <dt>Recommended default</dt> entry.
7. Followups without priority. Warns on any <section data-f="..."> missing a data-priority attribute.
8. Em-dash drift. Greps the canonical files for U+2014 / U+2013. Warns on hits.
9. Dependency ledger present. Warns if docs/DEPENDENCY_LEDGER.html is missing or empty (no <section id="watch-list"> recorded).

The output is a checklist, not a generated remediation file. One canonical place per kind of state.

Composition

• randroid:loop reads the ledgers this skill writes. The loop's research and implement modes both name OPEN_QUESTIONS and FOLLOWUPS as required reads. With this skill, those references resolve to the .html files.
• task-tracking-dots-html (the dot-html CLI, HTML dots under .dots/) is the work-item tracker, NOT the Markdown task-tracking-dots. Q-NNN entries that resolve into work become Dots. F-NNN entries with data-priority="blocks-release" become Dots.
• This skill is stateless. All state lives in the target repo's ledger files.

Architecture

spiral-html/
├── SKILL.md                    # This file (YAML frontmatter + HTML body)
├── README.md                   # Human-facing one-pager (HTML body)
├── .claude-plugin/
│   └── plugin.json             # Plugin metadata
├── commands/
│   ├── spiral-html-init.md     # /spiral-html init slash command
│   └── spiral-html-audit.md    # /spiral-html audit slash command
├── templates/
│   ├── AGENTS.md               # The contract, in Markdown (Codex root-down walk)
│   ├── CLAUDE.md               # One-line @AGENTS.md import (Claude Code project memory)
│   ├── IMPLEMENTATION_PLAN.html
│   ├── WORKING_AGREEMENT.html
│   ├── docs-gdd-index.html
│   ├── GDD_COVERAGE.json
│   ├── PROGRESS_LOG.html
│   ├── OPEN_QUESTIONS.html
│   ├── FOLLOWUPS.html
│   ├── DEPENDENCY_LEDGER.html
│   ├── PLAYTEST.html
│   ├── FUN_FACTOR_AUDIT.html
│   ├── dot-claude-rules-slice-discipline.md
│   ├── dot-claude-rules-ledger-append-only.md
│   └── dot-claude-rules-gdd-build-log.md
├── scripts/
│   ├── init.sh                 # Bootstrap into a target repo
│   └── audit.sh                # Diff target repo against canon
└── docs/
    ├── methodology.html        # The meta-pattern essay
    └── case-studies.html       # VibeRacer / VibeGear2 / Flatline