Spiral HTML
Bootstrap or audit an HTML-first structural-discipline scaffold for long-running product work, with semantic ledgers for GDD coverage, progress, questions, follow-ups, dependencies, and playtest gates. Use when a project wants Spiral's durable agent state in HTML rather than Markdown.
randroids-dojo
Updated Spiral HTML by randroids-dojo · 5c94881
npx skillmds@latest add randroids-dojo/spiral-html File contents
---name: spiral-htmldescription: Bootstrap or audit an HTML-first structural-discipline scaffold for long-running product work, with semantic ledgers for GDD coverage, progress, questions, follow-ups, dependencies, and playtest gates. Use when a project wants Spiral's durable agent state in HTML rather than Markdown.---<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><section></code>, <code><article></code>, <code><table></code>, <code><ol></code>, <code><dl></code>, <code><details></code>) carry semantics that Markdown discards. An agent reading <code><section data-role="rule" data-id="rule-1"></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><strong>Initialize:</strong> at the start of a fresh project, write the canonical HTML scaffold into the current repository.</li> <li><strong>Audit:</strong> on an existing project, diff the repository against the canonical HTML structure and print a remediation checklist.</li></ul><p>Per-slice execution 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><article data-slice="..."></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><section data-q="Q-NNN"></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><section data-f="F-NNN"></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 the pointer and loads the same contract.</li> <li><code>.claude/rules/*.md</code> keep YAML frontmatter and the <code>.md</code> filename because Claude Code's path-scoped Rules system parses the frontmatter to decide when to load. The body inside each rule is HTML.</li> <li>The Codex per-directory <code>AGENTS.md</code> symlinks point at the rules files (still <code>.md</code>); Codex reads the YAML frontmatter and HTML body uniformly.</li></ul><h2>The seven parts of the spiral</h2><ol> <li><strong>Vision</strong>: the canonical spec (GDD tree, atomic requirements) as HTML section files.</li> <li><strong>Contract</strong>: the three docs that govern every iteration (rules in <code>AGENTS.md</code>, plan, agreement).</li> <li><strong>Slice</strong>: the bounded unit of work (one PR, one log entry, small enough that a botched slice is reverted in one click).</li> <li><strong>Ledgers</strong>: externalized memory (progress log, open questions, followups, coverage) as append-only HTML elements with <code>data-*</code> ids.</li> <li><strong>Gates</strong>: 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 <code>docs/DEPENDENCY_LEDGER.html</code>): a watched-dep release is the same kind of fresh state as a new commit on <code>main</code>; the agent observes and acts at every loop boundary that touches <code>main</code>. The qualitative gate is the second gate that prevents Flatline-style early termination.</li> <li><strong>Selection rule</strong>: 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.</li> <li><strong>Loop</strong>: 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 <code>randroid-loop</code>.</li></ol><h2>How <code>init</code> works</h2><p>Resolve <code>scripts/init.sh</code> relative to this skill directory and run it from inside the target repository with <code>"<ProjectName>" "<one-line-pitch>" "<stack>"</code>.</p><p>The script:</p><ol> <li>Refuses to run if <code>AGENTS.md</code> already exists at the repo root. Use <code>audit</code> instead.</li> <li>Prompts for project name, one-line pitch, and stack if not passed as args.</li> <li>Copies every template file into the target repo, substituting <code>{{PROJECT_NAME}}</code>, <code>{{PITCH}}</code>, <code>{{STACK}}</code>, <code>{{TODAY}}</code>.</li> <li>Creates <code>docs/gdd/</code> for the GDD tree and <code>.claude/rules/</code> for the path-scoped Rules.</li> <li>Writes <code>AGENTS.md</code> (the full Markdown contract) and <code>CLAUDE.md</code> (one-line <code>@AGENTS.md</code> import).</li> <li>Verifies em-dash cleanliness on every written file.</li> <li>Prints a next-steps note: draft the first GDD section under <code>docs/gdd/</code>, then use <code>randroid-loop</code> in implementation mode to start the spiral.</li></ol><h2>How <code>audit</code> works</h2><p>Resolve <code>scripts/audit.sh</code> relative to this skill directory and run it from inside the repository to audit.</p><p>The script runs nine checks and prints a remediation checklist:</p><ol> <li><strong>Missing canonical files.</strong> Verifies the scaffold is present: the Markdown contract pair (<code>AGENTS.md</code>, <code>CLAUDE.md</code>), the docs HTML ledger set including <code>DEPENDENCY_LEDGER.html</code>, and the three <code>.claude/rules</code> files.</li> <li><strong>Monolith GDD.</strong> Warns if <code>docs/GDD.html</code> exists alone without a <code>docs/gdd/</code> directory.</li> <li><strong>Chapter-granular coverage.</strong> Counts rows in <code>docs/GDD_COVERAGE.json</code>. Warns if row count is implausibly low for project age (heuristic: fewer than 14 rows per project-week).</li> <li><strong>Missing qualitative gate.</strong> Warns if <code>docs/PLAYTEST.html</code> or <code>docs/FUN_FACTOR_AUDIT.html</code> is missing.</li> <li><strong>Stale progress log.</strong> Reads the newest <code><article data-date="YYYY-MM-DD"></code> in <code>docs/PROGRESS_LOG.html</code>. Warns if older than 7 days.</li> <li><strong>Open questions without defaults.</strong> Warns on any <code><section data-q="..."></code> missing a <code><dt>Recommended default</dt></code> entry.</li> <li><strong>Followups without priority.</strong> Warns on any <code><section data-f="..."></code> missing a <code>data-priority</code> attribute.</li> <li><strong>Em-dash drift.</strong> Greps the canonical files for U+2014 / U+2013. Warns on hits.</li> <li><strong>Dependency ledger present.</strong> Warns if <code>docs/DEPENDENCY_LEDGER.html</code> is missing or empty (no <code><section id="watch-list"></code> recorded).</li></ol><p>The output is a checklist, not a generated remediation file. One canonical place per kind of state.</p><h2>Composition</h2><ul> <li><code>randroid-loop</code> reads the ledgers this skill writes. The loop's research and implement modes both name <code>OPEN_QUESTIONS</code> and <code>FOLLOWUPS</code> as required reads. With this skill, those references resolve to the <code>.html</code> files.</li> <li><code>task-tracking-dots-html</code> (the <code>dot-html</code> CLI, HTML dots under <code>.dots/</code>) is the work-item tracker, NOT the Markdown <code>task-tracking-dots</code>. <code>Q-NNN</code> entries that resolve into work become Dots. <code>F-NNN</code> entries with <code>data-priority="blocks-release"</code> become Dots.</li> <li>This skill is stateless. All state lives in the target repo's ledger files.</li></ul><h2>Architecture</h2><pre><code>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</code></pre>
randroids-dojo/skills/tree/main/plugins/spiral-html commit 5c94881073
Frequently asked questions
Run npx skillmds@latest add randroids-dojo/spiral-html in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
Bootstrap or audit an HTML-first structural-discipline scaffold for long-running product work, with semantic ledgers for GDD coverage, progress, questions, follow-ups, dependencies, and playtest gates. Use when a project wants Spiral's durable agent state in HTML rather than Markdown. It is listed under Web & Frontend on SkillMD.
This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.
randroids-dojo (@randroids-dojo) published this skill. Their other Agent Skills are listed on their SkillMD profile.