spiral-html

What this skill does

<h1>Spiral (HTML edition)</h1>

<p>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 <code>spiral</code>: the scaffold is identical in shape, but every ledger, rule, and contract is authored as HTML rather than Markdown.</p>

<p>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.</p>

<h2>Why HTML</h2>

<p>HTML is the new way to communicate to agents. Structured elements (<code>&lt;section&gt;</code>, <code>&lt;article&gt;</code>, <code>&lt;table&gt;</code>, <code>&lt;ol&gt;</code>, <code>&lt;dl&gt;</code>, <code>&lt;details&gt;</code>) carry semantics that Markdown discards. An agent reading <code>&lt;section data-role="rule" data-id="rule-1"&gt;</code> 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.</p>

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

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

<h2>When to invoke</h2>

<ul>
  <li><code>/spiral-html init</code>: 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.</li>
  <li><code>/spiral-html audit</code>: 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.</li>
</ul>

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

<h2>Why this exists: the three case studies</h2>

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

<ul>
  <li><strong>VibeRacer (14 days, 184 commits)</strong>: shipped a complete v1. Single-file 28-section GDD with explicit out-of-scope §18 fence. The loop terminated cleanly.</li>
  <li><strong>VibeGear2 (7 days, 298 commits)</strong>: still actively shipping P0/P1 fun work a week in. Sectioned <code>docs/gdd/</code> tree, 102 atomic coverage rows, plus <code>FUN_FACTOR_GAP_AUDIT</code> and <code>RELEASE_FUN_PLAYTEST</code> as a second qualitative gate that re-opens the loop after systems land.</li>
  <li><strong>Flatline (3 days, 94 commits)</strong>: 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 <code>implemented</code> once <em>any</em> code shipped). No qualitative gate.</li>
</ul>

<p>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.</p>

<h2>The scaffold</h2>

<p><code>/spiral-html init</code> writes these files into the target repo:</p>

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

<h2>Cross-tool compatibility</h2>

<p>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:</p>

<ul>
  <li><code>AGENTS.md</code> (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 <code>.html</code> ledgers.</li>
  <li><code>CLAUDE.md</code> (the Claude Code project-memory filename) contains one line: <code>@AGENTS.md</code>. Claude Code's import mechanism resolves