@laitszkin/apollo-toolkit 3.9.7 → 3.10.0

package/spec-to-project-html/agents/openai.yaml

@@ -0,0 +1,12 @@
+interface:
+  display_name: "spec-to-project-html"
+  short_description: "Sync HTML architecture pages with active planning specs"
+  default_prompt: >-
+    Use $spec-to-project-html to read docs/plans (spec.md → design.md → contract.md), diff against `resources/project-architecture/` produced by $init-project-html, and patch HTML per `init-project-html/SKILL.md` Rules 1–7 (the authoritative rulebook). Local vocabulary + class-hook + DOM cheat sheet lives in this skill's own `references/TEMPLATE_SPEC.md`. Preserve the two-layer rule throughout.
+    The macro `index.html` stays ONE SVG with feature-module clusters AND every sub-module node drawn together, including many-to-many edges, producer/consumer loops, and cross-feature `m-edge--cross` data-row edges; the macro `flow-edge-manifest--macro` mirrors every SVG edge.
+    Read strategy (mirrors $init-project-html Rule 3 to avoid context loss). STEP 1: list AFFECTED feature modules from the spec/design diff, plus any feature owning a cross-feature edge into an affected one — without diving into function bodies.
+    STEP 2: branch by environment.
+    (4A, preferred) with subagents, dispatch ONE read-only subagent per affected feature; each returns a structured CHANGE summary (added/renamed/retired sub-modules, function I/O deltas, variables-with-business-purpose deltas, error deltas, outbound edge changes, `planned` / `gap` markers). The main agent collects every summary first, then patches the macro and pages in one pass.
+    (4B, no subagents) handle affected features ONE AT A TIME — deep-read feature A, IMMEDIATELY patch `features/A/index.html` + affected sub-module pages, incrementally patch the macro for A's cluster / nodes / edges (mark edges pointing at unread affected features with `data-edge-target-pending="<future-slug>"`), drop A's function-level details from memory, then move on. After every affected feature is patched, resolve every pending placeholder in a final macro pass. NEVER load every affected feature's source into the main agent context at once.
+    Each `features/<slug>/<sub-module>.html` stays self-only: update `sub-io` function table + `sub-vars` variables-with-business-purpose table (sync every renamed / added / removed parameter, local state, struct field, DB column, config knob, counter, or time anchor that influences a business branch, using scope chips `sub-vars__scope--call|tx|persist|instance|loop`) + `sub-dataflow` internal value flow + `sub-errors`. FORBIDDEN on sub-module pages: cross-submodule narrative, `flow-return-row`, or cross-boundary `flow-edge-manifest`.
+    Feature `index.html` stays lightweight (story + submodule-nav). Migrate legacy `arch-diagram` or feature-level cross-submodule flowcharts onto the macro when you touch them; keep CSS paths (`assets/` for root, `../../assets/` under features); scaffold via $init-project-html if files are missing. Report which read strategy (4A or 4B) was actually used.

package/spec-to-project-html/references/TEMPLATE_SPEC.md

@@ -0,0 +1,98 @@
+# HTML architecture atlas — reference cheat sheet (spec-to-project-html copy)
+
+> Reference material only. The **binding rules** (page contracts, naming, assets, accessibility, forbidden shortcuts) live in `init-project-html/SKILL.md` (the atlas authority). `spec-to-project-html/SKILL.md` follows those same Rules 1–7 when patching pages to match active specs. This file is a local glossary + class-hook table + DOM snippets so this skill can stay self-contained when installed alone.
+
+## Vocabulary
+
+- **Feature module** — one **user-visible end-to-end capability** (e.g. "invite-code registration", "get-invite-codes"). One directory `features/<feature-slug>/`. It is **not** a single web layer or a single database.
+- **Sub-module** — an implementation boundary inside that capability (front-end page, public API, domain service, PostgreSQL, pure helpers, message queues…). One HTML page per sub-module, sibling to the feature's `index.html`.
+
+## Directory layout (target output)
+
+```text
+resources/project-architecture/
+  index.html                           # macro: feature × sub-module in one SVG with multi-edge + data-row flow
+  assets/
+    architecture.css
+  features/
+    <feature-slug>/                    # one feature module = one directory
+      index.html                       # lightweight overview (story + submodule nav)
+      <sub-module-slug>.html           # one HTML per sub-module (own I/O + internal flow)
+```
+
+## Macro SVG — CSS class hooks
+
+| Element | class |
+|---|---|
+| Actor block | `m-actor` |
+| Feature cluster frame | `m-cluster` / `m-cluster__rect` / `m-cluster__title` |
+| Sub-module node | `m-sub` (add `m-sub--db` for databases) |
+| Edge | `m-edge` + modifier `m-edge--call` / `m-edge--return` / `m-edge--cross` |
+| Edge label | `m-edge__label` (cross-feature labels add `m-edge__label--cross`) |
+
+## DOM snippets
+
+### `sub-io` function I/O table
+
+```html
+<section class="sub-io">
+  <h2>Function I/O</h2>
+  <table>
+    <thead><tr><th>Function</th><th>Signature</th><th>Side effects</th><th>Purpose</th></tr></thead>
+    <tbody>
+      <tr>
+        <td><code>FunctionName</code></td>
+        <td class="sub-io__signature">
+          <strong>in:</strong> <code>T1</code>, <code>T2</code><br>
+          <strong>out:</strong> <code>R</code> | <code>ErrX</code>
+        </td>
+        <td><span class="sub-io__side sub-io__side--pure">pure</span></td>
+        <td>One-line purpose.</td>
+      </tr>
+    </tbody>
+  </table>
+</section>
+```
+
+### `sub-vars` variables-with-business-purpose table
+
+```html
+<section class="sub-vars">
+  <h2>Variables &amp; business purpose</h2>
+  <p class="sub-vars__intro">Identifiers this sub-module holds or threads through. Types align readers; business purpose comes first.</p>
+  <table>
+    <thead>
+      <tr><th>Variable</th><th>Type</th><th>Scope</th><th>Business purpose</th></tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td class="sub-vars__name">someVar</td>
+        <td class="sub-vars__type">SomeType</td>
+        <td><span class="sub-vars__scope sub-vars__scope--call">call</span></td>
+        <td>One line: this value decides branch X; without it Y breaks.</td>
+      </tr>
+    </tbody>
+  </table>
+</section>
+```
+
+Scope chip vocabulary: `sub-vars__scope--call` (single call), `--tx` (transaction-bound), `--persist` (persisted), `--instance` (fixed at construction; lifetime-shared), `--loop` (retry/loop).
+
+### `sub-dataflow` small SVG sizing
+
+- Node class: `d-node`; edge class: `d-edge` (side-effect edges use `d-edge--side`).
+- Recommended viewBox: height ≤ 240, width ≤ 720.
+- Nodes are this sub-module's internal variables/functions only.
+
+## Edge-kind vocabulary (for macro `flow-edge-manifest`)
+
+| `data-edge-kind` | meaning | typical visual |
+|---|---|---|
+| `call` | function call / HTTP request | solid arrow |
+| `return` | return value / response | thin dashed arrow |
+| `data-row` | cross-feature hand-off via data rows (not a function call) | warm-tone heavy dashed |
+| `failure` | failure branch | red solid arrow with `failure` chip in the manifest row |
+
+## Typography hint
+
+Pair a recognisable display face (e.g. `Fraunces`) with `Plus Jakarta Sans`. Avoid the "AI-default purple gradient" and Inter look-alike. Detailed rules live in `init-project-html/SKILL.md` § Rule 6.