@laitszkin/apollo-toolkit 3.11.1 → 3.11.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (25) hide show
  1. package/CHANGELOG.md +30 -0
  2. package/analyse-app-logs/scripts/__pycache__/filter_logs_by_time.cpython-312.pyc +0 -0
  3. package/analyse-app-logs/scripts/__pycache__/log_cli_utils.cpython-312.pyc +0 -0
  4. package/analyse-app-logs/scripts/__pycache__/search_logs.cpython-312.pyc +0 -0
  5. package/docs-to-voice/scripts/__pycache__/docs_to_voice.cpython-312.pyc +0 -0
  6. package/generate-spec/SKILL.md +18 -16
  7. package/generate-spec/agents/openai.yaml +4 -1
  8. package/generate-spec/scripts/__pycache__/create-specscpython-312.pyc +0 -0
  9. package/init-project-html/SKILL.md +68 -89
  10. package/init-project-html/agents/openai.yaml +7 -18
  11. package/init-project-html/lib/atlas/assets/architecture.css +695 -107
  12. package/init-project-html/lib/atlas/assets/viewer.client.js +10 -2
  13. package/init-project-html/lib/atlas/cli.js +17 -12
  14. package/init-project-html/lib/atlas/render.js +44 -3
  15. package/init-project-html/scripts/architecture-bootstrap-render.js +16 -0
  16. package/init-project-html/scripts/architecture.js +22 -12
  17. package/katex/scripts/__pycache__/render_katex.cpython-312.pyc +0 -0
  18. package/open-github-issue/scripts/__pycache__/open_github_issue.cpython-312.pyc +0 -0
  19. package/package.json +1 -1
  20. package/read-github-issue/scripts/__pycache__/find_issues.cpython-312.pyc +0 -0
  21. package/read-github-issue/scripts/__pycache__/read_issue.cpython-312.pyc +0 -0
  22. package/resolve-review-comments/scripts/__pycache__/review_threads.cpython-312.pyc +0 -0
  23. package/spec-to-project-html/SKILL.md +38 -58
  24. package/spec-to-project-html/agents/openai.yaml +7 -14
  25. package/text-to-short-video/scripts/__pycache__/enforce_video_aspect_ratio.cpython-312.pyc +0 -0
package/CHANGELOG.md CHANGED
@@ -10,6 +10,36 @@ All notable changes to this repository are documented in this file.
10
10
 
11
11
  ### Fixed
12
12
 
13
+ ## [v3.11.3] - 2026-05-11
14
+
15
+ ### Added
16
+
17
+ - New shipped font stack for every rendered atlas page (Fraunces display serif, Geist UI sans, JetBrains Mono technical accents) loaded via Google Fonts preconnect + stylesheet in `<head>`.
18
+ - Tests: shipped CSS viewport `clamp()` + svg `height:100%`; `viewer.client.js` wheel handler always prevents default; `preserveAspectRatio` on macro SVG; Google Fonts links in rendered `<head>`; full `renderAll` orphan sweep (scoped renders do not sweep).
19
+
20
+ ### Changed
21
+
22
+ - Atlas visual system redesigned end-to-end: dark "blueprint × editorial" theme with a faint vellum grid behind every diagram, sectioned canvases with corner labels (`MACRO DIAGRAM`, `INTERNAL FLOW`), refined toolbar buttons, sharper edge color hierarchy, hover glow on sub-module nodes, and serif story / role typography. All existing class hooks (`.atlas-svg`, `.m-cluster`, `.m-node`, `.sub-dataflow__*`, etc.) are preserved so spec overlays and tests continue to work.
23
+ - Macro and sub-dataflow SVGs render with `preserveAspectRatio="xMidYMid meet"` and fill 100% of a fixed-height viewport (`clamp(480px, 68vh, 760px)` for macro; `clamp(480px, 64vh, 720px)` for sub-dataflow), so horizontally-biased atlases no longer collapse to a thin strip while leaving empty space inside the canvas block.
24
+ - Skills + OpenAI agent prompts (`init-project-html`, `spec-to-project-html`, `generate-spec`): agents **MUST** use `apltk architecture --help` as the authoritative command tree; SKILL prose carries semantic guidance and constraints only (avoids doc/CLI drift). **Subagent-only** read/declare workflow; orchestrator **MUST** wait until all feature subagents finish before cross-feature `edge` or stitching `meta`/`actor`. `generate-spec` §3.5 and frontmatter describe overlay layout, `validate --spec`, and the paginated **`apltk architecture diff`** viewer across `docs/plans/**/architecture_diff/`.
25
+
26
+ ### Fixed
27
+
28
+ - `viewer.client.js`: the wheel gesture inside any diagram viewport now unconditionally calls `preventDefault()` + `stopPropagation()`, so scrolling/zooming the atlas no longer scrolls the surrounding page. Removed the `ctrlKey`/`metaKey` gate that previously let small wheel deltas bubble up.
29
+ - `apltk architecture render` (full base mode, no `--spec`) now sweeps orphan feature directories and stale sub-module HTML files left over from previous renders, so re-running `render` is a true refresh — old pages from renamed / removed features no longer linger with the previous styling. Scoped renders (overlay mode) intentionally do **not** sweep.
30
+
31
+ ## [v3.11.2] - 2026-05-11
32
+
33
+ ### Fixed
34
+
35
+ - `apltk architecture` / `resolveProjectRoot`: auto-create `resources/project-architecture/` on every command; when no atlas marker is found walking parent directories, use the current working directory as the project root (explicit `--project` still wins). `open` renders a fresh `index.html` when the file is missing so an empty tree bootstraps in one step.
36
+ - Legacy `init-project-html/scripts/architecture.js` `open` / `diff`: same directory creation and one-shot `render` bootstrap via `architecture-bootstrap-render.js` when `index.html` is absent.
37
+
38
+ ### Added
39
+
40
+ - `init-project-html/scripts/architecture-bootstrap-render.js` helper invoked by the legacy sync `open` path.
41
+ - Tests: `test/atlas-cli.test.js` covers `--project` on a bare directory (layout + `index.html`); `test/architecture-script.test.js` expects legacy `open` to exit 0 when `index.html` is missing after bootstrap.
42
+
13
43
  ## [v3.11.1] - 2026-05-11
14
44
 
15
45
  ### Added
package/generate-spec/SKILL.md CHANGED
@@ -2,7 +2,7 @@
2
2
  name: generate-spec
3
3
  description: >-
4
4
  Author docs/plans trees: run `apltk create-specs`, hydrate `spec/tasks/checklist/contract/design` (+ `coordination.md`/`preparation.md` when parallel/prep dictates), cite official docs for external deps, plan tests via **`test-case-strategy`**, block code edits until explicit user approval.
5
- Architecture-touching specs declare the proposed-after atlas via `apltk architecture --spec <spec_dir> <verb> ...`; the CLI writes overlay YAML to `<spec_dir>/architecture_diff/atlas/` and re-renders only the affected proposed-after HTML pages — never hand-author files under `architecture_diff/`.
5
+ Architecture deltas use `apltk architecture --spec <spec_dir> …` (**flags: `apltk architecture --help`**) → overlay under `<spec_dir>/architecture_diff/`; **`apltk architecture diff`** pages every `docs/plans/**/architecture_diff/` vs the base atlas — never hand-edit `architecture_diff/`.
6
6
  Use when drafting/refreshing specs or restructuring batches — not when executing approved plans (use **`implement-specs*`** instead).
7
7
  Reject vague `tasks.md` missing file/mutation/verifier; SPLIT >3-module scope; never overwrite a neighbor `{change}`.
8
8
  Bad: `- [ ] Add tests`… OK: `- [ ] src/auth/scope.rs — deny unknown scopes — Verify: cargo test scope::defaults`…
@@ -27,7 +27,7 @@ description: >-
27
27
  - **`tasks.md` checklist items**: **every** `- [ ]` **MUST** specify (a) concrete file/function target, (b) specific modification and expected outcome, (c) a verification hook—**no** vague rows (`Implement integration`, `Add tests`). Forbidden vague items **MUST** be rewritten before approval.
28
28
  - **MUST** use `test-case-strategy` when planning non-trivial logic tests and checklist mapping (test IDs, drift checks). Every **non-trivial** `tasks.md` implementation item **MUST** name a focused unit drift check, another concrete verification hook, or **`N/A`** with a concrete reason.
29
29
  - **MUST NOT** modify implementation code before **explicit user approval** of the spec set. Clarifications **MUST** sync across affected files and **MUST** re-trigger approval. If scope becomes a **different issue**, **MUST** stop editing the old set and create a **new** `change_name`.
30
- - **MUST** when the proposed change touches the architecture surface (feature / sub-module add / rename / remove, edge add / remove, `sub-vars` or function I/O deltas, internal dataflow / error deltas), declare the proposed-after state through `apltk architecture --spec <spec_dir> <verb> ...`. The CLI writes overlay YAML to `<spec_dir>/architecture_diff/atlas/` and renders only the affected proposed-after HTML pages under `<spec_dir>/architecture_diff/`; `apltk architecture diff` then pairs them with the base atlas by path. **MUST NOT** hand-author files under `architecture_diff/**` — the renderer owns layout, no-overlap, DOM, CSS, ARIA, and pan/zoom. For batch specs the overlay lives in each member spec's own directory only — **MUST NOT** duplicate at batch root. See this skill's own `references/TEMPLATE_SPEC.md` for the component schema cheat sheet and a quick worked example; the binding verbs and semantic rules live in `init-project-html/SKILL.md`.
30
+ - **MUST** when the proposed change touches the architecture surface (feature / sub-module add / rename / remove, edge add / remove, variable rows, function I/O rows, internal dataflow / error deltas), declare the proposed-after state **only** through `apltk architecture --spec <spec_dir> …` using the exact verbs, subverbs, and flags from **`apltk architecture --help`** (this file must not be treated as the command list). The CLI writes overlay YAML to `<spec_dir>/architecture_diff/atlas/` and renders only the affected proposed-after HTML pages under `<spec_dir>/architecture_diff/`. **`apltk architecture diff`** then builds a paginated **before/after viewer**: it walks every `docs/plans/**/architecture_diff/` tree, pairs each overlay HTML path with the matching file under `resources/project-architecture/` when it exists, and labels pages **modified**, **added**, or **removed** (via `_removed.txt` / removal manifests) so reviewers can scroll the whole architecture delta without opening files by hand. **MUST NOT** hand-author anything under `architecture_diff/**` — the renderer owns layout, DOM, CSS, ARIA, and pan/zoom. For batch specs the overlay lives in **each member spec’s own directory** only — **MUST NOT** duplicate overlay at the batch root. Use this skill’s `references/TEMPLATE_SPEC.md` for field/enum schema; use `init-project-html/SKILL.md` for semantic rules (**subagent gate** + edge kinds + dataflow integrity). When using subagents to draft atlas overlay, the authoring agent **MUST** wait until **all** feature subagents finish before declaring cross-feature **`edge`** (or overlay **`meta`** / **`actor`** that only exists to stitch features), matching `init-project-html` / `spec-to-project-html`.
31
31
  - Write prose in the **user’s language** by default; keep requirement/task/test IDs traceable across `spec.md`, `tasks.md`, and `checklist.md`.
32
32
  - **MUST** use **kebab-case** `change_name`; **MUST NOT** use spaces or arbitrary special characters in names.
33
33
 
@@ -81,25 +81,27 @@ Always materialize: `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, `desig
81
81
  - **Pause →** Do **`design.md` / `contract.md`** stay **coarser than `tasks.md`** (no mirrored checkbox choreography / file paths)—yet still constrain ordering and forbidden hallucinations?
82
82
  - **Pause →** For parallel batches, does `design.md` **avoid** duplicating batch ownership grids already locked in **`coordination.md`**?
83
83
 
84
- ### 3.5) Architecture diff (only when the proposal touches the architecture surface)
84
+ ### 3.5) Architecture overlay + diff viewer (only when the proposal touches the architecture surface)
85
85
 
86
- When the spec changes a feature module, sub-module, edge, variable, or function I/O, declare the proposed-after state through the CLI scoped to this spec directory:
86
+ When the spec changes a feature module, sub-module, edge, variable row, function I/O row, internal dataflow, or error row:
87
87
 
88
- ```bash
89
- SPEC_DIR=docs/plans/<date>/<change_name>
90
- apltk architecture --spec "$SPEC_DIR" feature add --slug ... --title "..." --story "..." --no-render
91
- apltk architecture --spec "$SPEC_DIR" submodule add|set|remove --feature ... --slug ... --kind ... --role "..." --no-render
92
- apltk architecture --spec "$SPEC_DIR" function|variable|dataflow|error add|remove ... --no-render
93
- apltk architecture --spec "$SPEC_DIR" edge add|remove --from <feat>[/sub] --to <feat>[/sub] --kind ... --label "..." --no-render
94
- apltk architecture --spec "$SPEC_DIR" render
95
- apltk architecture --spec "$SPEC_DIR" validate
96
- ```
88
+ 1. **Discover commands:** run **`apltk architecture --help`** in the target workspace; use that output for every `add` / `set` / `remove` / `reorder` spelling and required flag. Do not copy long command tables from skills — they go stale.
89
+ 2. **Declare proposed-after state** with `apltk architecture --spec <spec_dir> …` for each mutation (pass `--no-render` while batching if you prefer a single render at the end).
90
+ 3. **`apltk architecture render --spec <spec_dir>`** — emits/updates only the HTML files touched by this overlay plus assets.
91
+ 4. **`apltk architecture validate --spec <spec_dir>`** — **MUST** return OK before the spec is approval-ready (resolve dangling edges, unknown enums, bad dataflow references).
92
+ 5. **`apltk architecture diff`** — **MUST** run before hand-off when atlas changed; confirm the paginated viewer shows sensible **modified** / **added** / **removed** counts and that each interesting path pairs correctly (base `resources/project-architecture/…` vs `<spec_dir>/architecture_diff/…`). A page appearing as **remove + add** instead of **modified** usually means a **slug rename** was split wrong — fix with intentional remove+add or a single coherent mutation sequence.
93
+
94
+ **Where files land:** overlay YAML under `<spec_dir>/architecture_diff/atlas/`; rendered proposed-after HTML under `<spec_dir>/architecture_diff/`. Cross-feature edges whose far endpoint exists only in the **base** atlas still resolve when merged — but you **must** `validate` to catch mistakes.
95
+
96
+ **Batch specs:** each `<spec_dir>` is one member directory under `docs/plans/...`; **never** duplicate overlay at the batch root.
97
+
98
+ **Subagent coordination:** if multiple features are drafted in parallel, **do not** declare cross-feature **`edge`** (or overlay **`meta` / `actor`** used only to stitch features) until **all** feature workers report done — see `init-project-html/SKILL.md` Rule 3 and `spec-to-project-html`.
97
99
 
98
- The CLI writes overlay YAML under `$SPEC_DIR/architecture_diff/atlas/` and re-renders only the affected HTML pages under `$SPEC_DIR/architecture_diff/`. Cross-feature edges into features that are not declared in the overlay still resolve against the base atlas. For batch specs, scope each member spec's overlay to its own directory — never duplicate at the batch root. **Do not hand-edit** any file under `architecture_diff/`.
100
+ **Do not hand-edit** any file under `architecture_diff/`.
99
101
 
100
102
  - **Pause →** Did I touch any file under `architecture_diff/` by hand? Revert and re-run the CLI verb instead.
101
- - **Pause →** Does `apltk architecture --spec "$SPEC_DIR" validate` return OK? Resolve dangling edges and unknown enums before approval.
102
- - **Pause →** Does `apltk architecture diff` pair the spec's pages correctly (modified / added / removed)? A page that shows as remove + add means a slug was renamed inadvertently.
103
+ - **Pause →** Does `apltk architecture validate --spec <spec_dir>` return OK?
104
+ - **Pause →** Does `apltk architecture diff` pair the spec’s pages correctly?
103
105
 
104
106
  ### 4) Clarifications and approval
105
107
 
package/generate-spec/agents/openai.yaml CHANGED
@@ -4,4 +4,7 @@ interface:
4
4
  default_prompt: >-
5
5
  Use $generate-spec to create or update single-spec plans under docs/plans/<date>/<change_name>/ or parallel batches under docs/plans/<date>/<batch_name>/<change_name>/ with shared coordination.md and, only when specs cannot be parallel-safe without prior shared work, minimal non-business preparation.md; treat references/templates/*.md as binding format; member specs assume preparation finished—do not duplicate preparation tasks; surface collisions early and resolve ownership via coordination.md; fill BDD in spec.md; integrate $test-case-strategy into tasks/checklists.
6
6
  **Critical layering:** design.md + contract.md are higher-level guiding context only (architecture + cite-backed external truth; coarse INT-### / EXT-### anchors). tasks.md MUST be the ONLY enumerated runnable queue with path-level edits and verification hooks—derive tasks FROM spec + design + contract WITHOUT mirroring checklist rows into design/contract; optionally cite INT/EXT on task lines for traceability—never duplicate task choreography inside design.md or contract.md.
7
- **Architecture diff:** When the spec touches the architecture surface (feature/sub-module add/rename/remove, edge changes, sub-vars / sub-io / dataflow / error deltas), declare the proposed-after state through `apltk architecture --spec <spec_dir> <verb> ...`. The CLI writes overlay YAML under `<spec_dir>/architecture_diff/atlas/` and renders only the affected HTML pages under `<spec_dir>/architecture_diff/`; `apltk architecture diff` then pairs them with the base atlas by path. NEVER hand-author files under `architecture_diff/**` — the renderer owns layout, no-overlap, DOM, CSS, ARIA, and pan/zoom. Use $init-project-html `SKILL.md` and `references/TEMPLATE_SPEC.md` for the verb cheat sheet (`feature`, `submodule`, `function`, `variable`, `dataflow`, `error`, `edge` add/remove/set + `meta set`, `actor add`, plus `render`, `validate`, `undo`). For batch specs scope each member's overlay to that member's directory only — never duplicate at the batch root. Always run `apltk architecture --spec <spec_dir> validate` after the final mutation and ensure `apltk architecture diff` pairs every changed page (modified / added / removed) correctly.
7
+ **Architecture overlay + diff:** When the spec touches atlas surface (feature/sub-module, edges, function/variable rows, dataflow, errors), declare proposed-after state ONLY via `apltk architecture --spec <spec_dir> …`. **Exact verbs/flags: ALWAYS `apltk architecture --help`.** CLI writes `<spec_dir>/architecture_diff/atlas/` + renders affected HTML under `<spec_dir>/architecture_diff/`. NEVER hand-author `architecture_diff/**`.
8
+ After mutations: `render --spec`, `validate --spec` (must be OK pre-approval). **`apltk architecture diff`** opens the paginated before/after viewer over all `docs/plans/**/architecture_diff/` vs base `resources/project-architecture/` — run it when atlas changed; verify modified/added/removed pairing.
9
+ Batch specs: one overlay per member directory—never at batch root. If subagents draft multiple features: **wait until ALL finish** before cross-feature `edge` / stitching `meta` / `actor` (same gate as $init-project-html / $spec-to-project-html).
10
+ Field/enums: this skill's references/TEMPLATE_SPEC.md. Semantics: $init-project-html SKILL.md.
package/init-project-html/SKILL.md CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: init-project-html
3
3
  description: >-
4
- Declare the project HTML architecture atlas through `apltk architecture` CLI verbs instead of hand-writing SVG/HTML. Two acceptance criteria gate completion: (1) the macro diagram clearly shows feature × sub-module relationships — data flow, call/return interaction logic, error handling, rollback — all expressed as `--kind call|return|data-row|failure` edges; (2) each sub-module's internal diagram clearly shows function-level interactions inside it — function-to-function flow via `dataflow add --fn <declared-fn>`, variable state transitions via `--reads`/`--writes` referencing declared variables, and the resulting local data flow. The tool owns layout, CSS, and pan/zoom for both diagrams; `validate` rejects any step that references an undeclared function or variable. With subagents, each owns one feature and declares every intra-feature interaction itself; the main agent only declares cross-feature edges. Anchor every declaration to repo evidence.
4
+ Declare the project HTML architecture atlas through `apltk architecture` instead of hand-writing SVG/HTML. Two acceptance criteria gate completion: (1) the macro diagram clearly shows feature × sub-module relationships — data flow, call/return interaction logic, error handling, rollback — all expressed as cross-sub-module edges with kinds `call`, `return`, `data-row`, and `failure`; (2) each sub-module’s internal diagram shows function-level flow (`dataflow` steps may reference a declared function plus `reads`/`writes` of declared variables). The tool owns layout, CSS, pan/zoom, and validation. **Subagents only:** one write-capable subagent per feature declares every intra-feature change; the main agent **waits until all subagents finish**, then wires **only** cross-feature seams. **Exact CLI spelling:** always `apltk architecture --help` — never treat prose in this file as the command list. Anchor every declaration to repo evidence.
5
5
  ---
6
6
 
7
7
  # Init Project HTML
@@ -11,54 +11,56 @@ description: >-
11
11
  - Required: none (the CLI ships its own layout engine, CSS, and pan/zoom client; `apltk architecture` is installed with this toolkit).
12
12
  - Conditional: `spec-to-project-html` when the same atlas needs spec-driven refresh — that skill uses the same CLI with `--spec`.
13
13
  - Optional: `align-project-documents` when `docs/features` already names the user-visible capabilities.
14
- - Fallback: codebase too large for one pass → use the subagent strategy below, document scanned roots and explicit omissions in `meta.summary`. **MUST NOT** declare components for code paths that were never read.
14
+ - Fallback: codebase too large for one pass → use the **subagent** strategy below; document scanned roots and explicit omissions in `meta.summary`. **MUST NOT** declare components for code paths that were never read.
15
15
 
16
16
  ## Non-negotiables
17
17
 
18
18
  ### Rule 1 — Use the CLI; never hand-author atlas HTML
19
19
 
20
- The atlas state lives in `resources/project-architecture/atlas/` (`atlas.index.yaml` + per-feature YAMLs). Every change goes through `apltk architecture <verb> ...`. After any mutation, the CLI re-renders `resources/project-architecture/**/*.html` with the correct layout, CSS, pan/zoom, and ARIA — agents **MUST NOT** edit those HTML files by hand or invent additional ones.
20
+ The atlas state lives in `resources/project-architecture/atlas/` (`atlas.index.yaml` + per-feature YAMLs). Every change goes through the CLI (exact verbs/flags: **`apltk architecture --help`**). After any mutation, the CLI re-renders `resources/project-architecture/**/*.html` with the correct layout, CSS, pan/zoom, and ARIA — agents **MUST NOT** edit those HTML files by hand or invent additional ones.
21
21
 
22
22
  ### Rule 2 — Sub-module pages describe only themselves; the internal-dataflow diagram is zoomable and structurally typed
23
23
 
24
- What the CLI emits on each sub-module page is fixed:
24
+ What the CLI emits on each sub-module page is fixed in *role* (not in exact flag names — those live in `--help`):
25
25
 
26
- - function I/O table (`function add --feature X --submodule Y --name fn --in ... --out ... --side ... --purpose ...`),
27
- - variables-with-business-purpose table (`variable add --name v --type T --scope call|tx|persist|instance|loop --purpose ...`),
28
- - internal dataflow diagram — ordered steps the renderer lays out as a numbered top-to-bottom flow inside a pan/zoom viewport with +/−/Fit controls, exactly like the macro SVG. Each step is `dataflow add --step "..." [--fn <declared-fn>] [--reads "v1,v2"] [--writes "v3,v4"]`. The renderer surfaces `--fn` as a pill at the top of the step box, `--reads` as a green chip on the bottom-left, and `--writes` as an orange chip on the bottom-right — so a single SVG simultaneously shows the function-to-function flow inside the sub-module AND the variable state transitions across the run,
29
- - local errors (`error add --name ErrX --when ... --means ...`).
26
+ - **Function I/O table** — one row per declared function/side-effect entry point.
27
+ - **Variables table** — business-purpose identifiers (`scope` enum and `purpose` text).
28
+ - **Internal dataflow** — ordered steps inside a pan/zoom viewport (+/−/Fit), same interaction model as the macro SVG. Steps may attach a declared function name and comma-separated read/write variable names; the renderer shows them as a function pill and read/write chips so **function-to-function flow** and **variable state** are visible in one diagram.
29
+ - **Local errors** — symbolic error rows (`when` / `means`).
30
30
 
31
- Schema rules the CLI enforces on every `dataflow add` (so the diagram never lies):
31
+ **Structural constraints** (enforced by `validate`):
32
32
 
33
- - `--fn <name>` must match a function declared **in the same sub-module** via `function add`. If it does not, `validate` fails — declare the function first.
34
- - Every name in `--reads` / `--writes` must match a variable declared **in the same sub-module** via `variable add`. If it does not, `validate` fails — declare the variable first.
35
- - `--fn` / `--reads` / `--writes` are optional but additive: omitting them is allowed for purely descriptive steps, but for any non-trivial sub-module the function-and-variable structure **MUST** be filled in so the diagram conveys the function-to-function flow and the variable state transitions.
33
+ - Any function name referenced from a dataflow step must already exist on **that** sub-module (`function` row).
34
+ - Any variable name in reads/writes must already exist on **that** sub-module (`variable` row).
35
+ - Purely descriptive steps without fn/reads/writes are allowed, but non-trivial sub-modules **MUST** fill the structure so the diagram is not hollow.
36
36
 
37
- Cross-boundary narratives ("I call X", "Y calls me") **MUST** be expressed as edges (`edge add --from X/sub --to Y/sub --kind call|return|data-row|failure --label ...`), never as sub-module page prose. The CLI enforces this by design — there is no verb to add cross-boundary text to a sub-module page.
37
+ Cross-boundary narratives (“I call X”, “Y calls me”) **MUST** be **edges** between `feature/submodule` endpoints with a `kind` of `call`, `return`, `data-row`, or `failure` — never as extra prose on a sub-module page. There is no CLI path to smuggle cross-boundary text onto sub-module pages.
38
38
 
39
- ### Rule 3 — Read order: never let the codebase wipe the context window; subagents own their own feature
39
+ ### Rule 3 — Read order: subagents only; wait for all workers before cross-feature wiring
40
40
 
41
- Real production codebases dwarf the main agent's context. Reading the whole repo before declaring pushes early details out by the end, making macro edges and sub-module declarations contradict each other. The split below also draws a hard responsibility line between the worker and the orchestrator. **MUST** follow one of:
41
+ Real production codebases dwarf the main agent’s context. **MUST** use this pattern only:
42
42
 
43
- - **With subagents (preferred):** first enumerate the **feature-module list** (slug + entry + boundary resources only). Then dispatch **one (write-capable) subagent per feature**. Each subagent:
44
- - deep-reads its own feature,
45
- - declares **everything intra-feature** itself via `apltk architecture ... --feature <slug>` (sub-modules; per sub-module functions / variables / internal dataflow / errors; **every intra-feature edge** — function calls between sub-modules, error edges, rollback / compensation edges; variable state transitions are captured as ordered `dataflow add` steps on each sub-module),
46
- - returns ONLY a structured summary of (i) the sub-module list and (ii) the **outbound boundaries** the main agent needs to wire (calls / data-rows / failure edges to other features' sub-modules, including direction and the consuming/producing endpoints).
43
+ 1. Enumerate the **feature-module list** (slug + entry + boundary resources only) — **no** function-body deep reads at this stage.
44
+ 2. Dispatch **one write-capable subagent per feature** (every feature in scope that needs atlas work). Each subagent:
45
+ - deep-reads **only** its feature;
46
+ - declares **everything intra-feature** via `apltk architecture` scoped with `--feature <slug>` where the CLI allows (exact scoping flags: **`--help`**): sub-modules, per-sub-module functions / variables / ordered dataflow / errors, and **every intra-feature edge** (calls, returns, data-rows, failures, rollback/compensation **between sub-modules of the same feature**);
47
+ - returns **ONLY** a structured summary of (i) sub-module list (slug + kind + one-line role) and (ii) **outbound boundaries** the orchestrator must wire later (calls / data-rows / failures **to other features’** sub-modules — direction, endpoints, suggested kind/label).
47
48
 
48
- The main agent never re-reads source for that feature. It collects every subagent's outbound-boundary summary and declares **only the cross-feature edges** (and any cross-feature actors / meta) itself, then runs `apltk architecture validate`.
49
- - **Without subagents:** process features **one at a time** — read feature A end-to-end, declare its sub-modules, functions, variables, internal dataflow, errors, and intra-feature edges via the CLI, then move on. For cross-feature edges that point at not-yet-declared features, declare the placeholder feature with `feature add --slug <future> --title <future>` first, then add the edge; subsequent passes set the real title/story. Drop A's function-level details from working memory before reading feature B.
49
+ 3. **Gate — all subagents complete:** The main agent **MUST NOT** declare any **cross-feature** `edge`, shared `meta` that encodes multi-feature narrative, nor any `actor` that exists only to stitch features together, **until every dispatched subagent has finished** (success **or** an explicit failure report). Partial summaries are for note-taking only — **not** for mutating cross-feature atlas state.
50
50
 
51
- Both paths share one invariant: at any moment the agent doing the deep read only holds *that feature's details + cross-feature boundary notes*. The main agent's working set, in subagent mode, is **boundaries only**. Run `apltk architecture validate` after the last feature to catch dangling edges, unknown endpoints, or missing required fields.
51
+ 4. After the gate: the main agent aggregates outbound boundary notes, declares **only** cross-feature edges (and optional shared `meta` / `actor` if needed), then runs **`apltk architecture render`** (if batched with `--no-render`) and **`apltk architecture validate`**.
52
+
53
+ The main agent **MUST NOT** re-read source for a delegated feature and **MUST NOT** re-declare intra-feature components a subagent already owns.
52
54
 
53
55
  ### Rule 4 — Evidence over invention
54
56
 
55
- - **MUST** anchor every declared feature, sub-module, function, variable, dataflow step, and edge to a concrete path / symbol / SQL / config; record scanned roots and any deliberate omissions in `meta.summary` via `apltk architecture meta set --summary "..."`.
56
- - **MUST NOT** invent modules, integrations, or sub-modules just because the diagram "looks balanced". Empty rows are valid; lies are not.
57
+ - **MUST** anchor every declared feature, sub-module, function, variable, dataflow step, and edge to a concrete path / symbol / SQL / config; record scanned roots and any deliberate omissions in `meta.summary` via the CLI (`meta` verbs — flags: **`--help`**).
58
+ - **MUST NOT** invent modules, integrations, or sub-modules just because the diagram “looks balanced”. Empty rows are valid; lies are not.
57
59
 
58
60
  ## Standards (summary)
59
61
 
60
62
  - **Evidence**: every CLI declaration traces to a path/symbol/SQL/config; uncertain areas surface as `TBD` strings or are omitted with a recorded reason.
61
- - **Execution**: feature-module list (shallow) → branch by environment (subagent fan-out or sequential read-declare) → `apltk architecture validate` → handover report.
63
+ - **Execution**: shallow feature-module list → subagent fan-out per feature → **wait for all** → cross-feature edges / meta → `validate` → handover.
62
64
  - **Quality**: macro SVG carries every cross-feature data-row edge that exists in the system; sub-module declarations are self-only; pan/zoom + Fit work in the rendered HTML; `apltk architecture validate` returns OK.
63
65
  - **Output**: `resources/project-architecture/atlas/` (YAML state) + `resources/project-architecture/**/*.html` (renderer output) — both managed by the CLI.
64
66
 
@@ -67,40 +69,34 @@ Both paths share one invariant: at any moment the agent doing the deep read only
67
69
  The atlas is only complete when both of the following are demonstrably true on the rendered HTML (open `resources/project-architecture/index.html` and one representative sub-module page to verify):
68
70
 
69
71
  1. **Macro diagram clearly shows the relationships between features and sub-modules**, including:
70
- - **Data flow** — every cross-feature DB row, queue topic, or cache key hand-off is a `--kind data-row` edge between the producing and consuming sub-modules (not free-form prose).
71
- - **Interaction logic** — synchronous request/response paths are paired `--kind call` (outbound) and `--kind return` (response) edges with a label that names the call site or response shape.
72
- - **Error handling and rollback** — every failure / compensation / retry path that crosses a sub-module boundary is a `--kind failure` edge with a label that names what is being rolled back or compensated.
73
- - No interaction is captured *only* in sub-module page prose — if it crosses a sub-module boundary it MUST appear as an edge so the macro SVG carries it.
74
- 2. **Each sub-module's internal diagram clearly shows the function-level interactions inside the sub-module**, including:
75
- - **Function-to-function flow** — every step that does non-trivial work carries `--fn <declared-fn>`. The sequence of pills along the steps reveals which function is active at each point in the flow.
76
- - **Variable state transitions during the run** — every variable that is read or mutated by a step is declared via `variable add`, and that step lists it in `--reads` (the value flows in) or `--writes` (the value is created/updated). Reading the steps top-to-bottom traces each variable's life cycle.
77
- - **Local data flow** — the ordered step boxes (with reads/writes chips) read as a directed flowchart, ending at the sub-module boundary (returning a value, persisting a row, emitting an event).
72
+ - **Data flow** — every cross-feature DB row, queue topic, or cache key hand-off is a `data-row` **edge** between producing and consuming sub-modules (not free-form prose).
73
+ - **Interaction logic** — synchronous request/response paths use paired **`call`** (outbound) and **`return`** edges with a label that names the call site or response shape.
74
+ - **Error handling and rollback** — every failure / compensation / retry path that crosses a sub-module boundary is a **`failure`** edge with a label that names what is rolled back or compensated.
75
+ - No cross-boundary interaction exists **only** in sub-module page prose — it **MUST** appear as an edge on the macro SVG.
76
+ 2. **Each sub-module’s internal diagram clearly shows the function-level interactions inside the sub-module**, including:
77
+ - **Function-to-function flow** — non-trivial steps reference a declared function on that sub-module.
78
+ - **Variable state transitions** — variables read or written by a step are declared first, then referenced on the step; reading top-to-bottom traces lifecycle.
79
+ - **Local data flow** — ordered steps read as a directed flowchart to the sub-module boundary.
78
80
 
79
- `apltk architecture validate` MUST return OK before reporting completion — it enforces both criteria's structural pieces (unknown sub-modules on edges, unknown functions/variables referenced by dataflow steps).
81
+ `apltk architecture validate` **MUST** return OK before reporting completion.
80
82
 
81
83
  ## How to use `apltk architecture`
82
84
 
83
- Each verb is a single mutation; the CLI auto-renders after every change. Pass `--no-render` when batching mutations. Global flags: `--project <root>`, `--spec <spec_dir>` (writes to overlay; see `spec-to-project-html`), `--no-render`, `--no-open`.
84
-
85
- | Verb | Use it to… |
86
- | --- | --- |
87
- | `apltk architecture meta set --title ... --summary ...` | Set the macro title + atlas summary (read order, scanned roots, deliberate omissions). |
88
- | `apltk architecture actor add --id end-user --label "End user"` | Add a top-level actor (optional; appears in macro context). |
89
- | `apltk architecture feature add --slug <kebab> --title "..." --story "..." [--depends-on a,b]` | Declare a feature module (user-visible capability). |
90
- | `apltk architecture submodule add --feature <slug> --slug <kebab> --kind ui\|api\|service\|db\|pure-fn\|queue\|external --role "..."` | Declare a sub-module under a feature. |
91
- | `apltk architecture function add --feature X --submodule Y --name fn --in "T1, T2" --out "R \| ErrX" --side pure\|io\|write\|tx\|lock\|network --purpose "..."` | Add a function I/O row. |
92
- | `apltk architecture variable add --feature X --submodule Y --name v --type T --scope call\|tx\|persist\|instance\|loop --purpose "..."` | Add a variable-with-business-purpose row. |
93
- | `apltk architecture dataflow add --feature X --submodule Y --step "..." [--fn <declared-fn>] [--reads "v1,v2"] [--writes "v3,v4"] [--at N]` | Append (or insert at index `N`) an internal dataflow step. `--fn` must match a previously declared `function`; every name in `--reads` / `--writes` must match a previously declared `variable` in the same sub-module — the renderer surfaces them as a function pill + reads/writes chips so the diagram shows function-to-function flow and variable state transitions. |
94
- | `apltk architecture dataflow reorder --feature X --submodule Y --from i --to j` | Move a step within the same sub-module. |
95
- | `apltk architecture error add --feature X --submodule Y --name ErrCode --when "..." --means "..."` | Add a local error row. |
96
- | `apltk architecture edge add --from <feature>[/sub] --to <feature>[/sub] --kind call\|return\|data-row\|failure --label "..." [--id <stable>]` | Add an edge. Intra-feature edges (both endpoints in the same feature with sub-modules) land in the feature YAML; cross-feature edges land in `atlas.index.yaml`. |
97
- | `apltk architecture feature\|submodule\|function\|variable\|error\|edge remove ...` | Remove a previously declared component. Removing a feature drops every sub-module and edge that referenced it. |
98
- | `apltk architecture feature\|submodule set ...` | Update fields (e.g. retitle a feature, change a sub-module's role) without re-adding. |
99
- | `apltk architecture render` | Force-regenerate HTML from current YAML state (useful after editing YAML directly, though hand-editing is discouraged). |
100
- | `apltk architecture validate` | Schema + referential integrity check; fails on dangling edges, unknown enums, duplicate slugs. |
101
- | `apltk architecture undo` | Revert the most recent mutation (single-level snapshot). |
102
- | `apltk architecture open` | Open the rendered macro `index.html` in a browser. |
103
- | `apltk architecture diff` | Render the paginated before/after viewer for every active spec under `docs/plans/**/architecture_diff/`. |
85
+ **Authoritative command tree:** run **`apltk architecture --help`** (same output as `apltk architecture help`). **MUST** use that output for every verb, subverb (`add` / `set` / `remove` / `reorder`), and required flag. This skill describes **semantics and constraints** only so documentation does not drift when the CLI adds flags or synonyms.
86
+
87
+ **Typical global flags** (confirm in `--help`): `--project <root>`, `--spec <spec_dir>` (overlay under `<spec_dir>/architecture_diff/` — see `spec-to-project-html`), `--no-render`, `--no-open`, `--out` (for `diff`). Pass `--no-render` while batching mutations, then **`render`** once before `validate` if you batched.
88
+
89
+ **Groupings — what each family is for:**
90
+
91
+ | Family | Purpose | Key constraints |
92
+ | --- | --- | --- |
93
+ | **`open` / `diff` / `render` / `validate` / `undo` / `help`** | View, regenerate, check, revert, discover verbs | **`validate`** before “done”. **`diff`** after spec overlays to compare base vs proposed-after under `docs/plans/**/architecture_diff/`. |
94
+ | **`meta` / `actor`** | Macro title, summary, optional top-level actors | Summary is the right place for scanned roots and omissions. |
95
+ | **`feature` / `submodule`** | Feature modules and their sub-modules | **Remove** cascades references; in spec overlay mode, rename is usually **remove + add** so `diff` classifies correctly. |
96
+ | **`function` / `variable` / `dataflow` / `error`** | Tables + ordered internal flow + local errors | Declare symbols **before** referencing them from `dataflow`. Use **`remove`** (see `--help`) to delete mistaken rows or steps. |
97
+ | **`edge`** | Cross- **or** intra-feature seams | **`kind`** ∈ `call` \| `return` \| `data-row` \| `failure`. Intra-feature endpoints land in the feature file; cross-feature endpoints land in the index. Prefer stable **`--id`** on edges you may remove later in spec mode. |
98
+
99
+ **Cross-feature work timing:** only after **all** feature subagents have returned (Rule 3).
104
100
 
105
101
  ## Workflow
106
102
 
@@ -111,21 +107,19 @@ Scan the shipped source for **user-visible capabilities** (each one = one featur
111
107
  - **Pause →** Is the list actually complete? Note skipped roots with reason; no silent skips.
112
108
  - **Pause →** Did I dive into function bodies here? Roll back — keep only structural notes.
113
109
 
114
- ### 2) Branch the deep-read by environment (Rule 3)
115
-
116
- #### 2A) With subagents (preferred) — workers own their feature; main agent owns the macro seams
110
+ ### 2) Subagent fan-out — workers own features; orchestrator owns cross-feature seams **after** all workers finish
117
111
 
118
- Dispatch one **write-capable** subagent per feature, plus the main agent for the macro layer. Hand each subagent: its feature slug, the feature-module list from step 1 (so it knows other features' slugs for outbound edges), and access to `apltk architecture`. Each subagent **declares its own feature end-to-end** and only reports outbound boundaries upward:
112
+ Dispatch one **write-capable** subagent per feature. Hand each subagent: its feature slug, the feature-module list from step 1 (so it knows other features’ slugs for outbound edges), and **`apltk architecture --help`** as the flag reference.
119
113
 
120
114
  > **Feature `<slug>` subagent contract**
121
115
  > - Read every sub-module of this feature.
122
- > - Run `feature add --slug <slug> --title "..." --story "..." --no-render` (or `feature set` if a placeholder already exists).
123
- > - For every sub-module: `submodule add` with the right `--kind`, then add its `function`, `variable`, `dataflow` (ordered — these steps carry the variable state transitions through the flow), and `error` rows.
124
- > - For every intra-feature interaction between sub-modules — function calls, returns, error propagation, rollback / compensation — emit `edge add --from <slug>/<a> --to <slug>/<b> --kind call|return|data-row|failure --label "..."`. Failure / rollback flows belong here: model them as additional `--kind failure` edges or as ordered `dataflow add` steps on the affected sub-modules, whichever maps to the real code path.
125
- > - Run `apltk architecture validate` (scoped to this feature) before returning.
126
- > - **Return ONLY**: (i) sub-module list (slug + kind + one-line role), (ii) outbound boundaries to *other* features' sub-modules (direction + edge kind + suggested label). No source excerpts, no function bodies.
116
+ > - Declare the feature and its sub-modules (`feature` / `submodule` — exact flags: **`--help`**).
117
+ > - For every sub-module: add **function**, **variable**, ordered **dataflow**, and **error** rows as needed.
118
+ > - For every intra-feature interaction between sub-modules, add an **edge** whose endpoints stay **inside** this feature.
119
+ > - Run **`apltk architecture validate`** before returning (same project root; use **`--help`** for project/spec flags).
120
+ > - **Return ONLY**: (i) sub-module list (slug + kind + one-line role), (ii) outbound boundaries to *other* features’ sub-modules (direction + edge kind + suggested label). No source dumps.
127
121
 
128
- Main agent — after every subagent returns — declares **only** macro-level state from the aggregated outbound boundaries:
122
+ **Orchestrator — after every subagent has completed:**
129
123
 
130
124
  ```bash
131
125
  apltk architecture meta set --title "..." --summary "..." --no-render
@@ -137,37 +131,22 @@ apltk architecture render
137
131
  apltk architecture validate
138
132
  ```
139
133
 
140
- The main agent **MUST NOT** re-declare a subagent's intra-feature components, and **MUST NOT** open source files for any feature it delegated.
141
-
142
- #### 2B) Without subagents — feature-by-feature read-declare loop
143
-
144
- Process the list from step 1 one feature at a time (topological hint: read-from data sources and pure helpers first, user-facing entries last). Per feature:
145
-
146
- 1. **Deep-read** every sub-module of this feature.
147
- 2. **Declare immediately** via the CLI (`feature add`, then `submodule add` × N, then `function`/`variable`/`dataflow`/`error` rows, then intra-feature `edge add`).
148
- 3. **Cross-feature edges**: if the target feature has not been declared yet, declare a placeholder with `feature add --slug <future> --title <future>`, add the edge, then refine the placeholder on a later pass.
149
- 4. **Drop function-level details from working memory** before moving to the next feature.
150
-
151
- After the last feature:
152
-
153
- - Refine any placeholder features that were used to carry cross-feature edges.
154
- - Run `apltk architecture validate` — must return OK.
134
+ The main agent **MUST NOT** re-declare a subagent’s intra-feature components, and **MUST NOT** open source files for any feature it delegated.
155
135
 
156
136
  ### 3) Handover report
157
137
 
158
- Report: feature count, sub-module count, macro edge counts (call / return / data-row / failure), uncovered paths + reasons, the read strategy actually used (2A or 2B), and the location of the rendered atlas (`resources/project-architecture/index.html`).
138
+ Report: feature count, sub-module count, macro edge counts (call / return / data-row / failure), uncovered paths + reasons, confirmation that **all subagents completed before cross-feature wiring**, and the location of the rendered atlas (`resources/project-architecture/index.html`).
159
139
 
160
140
  ## Sample hints
161
141
 
162
- - Multiple SQL paths on `service ↔ db` → call `edge add` once per SQL path so the macro shows them as separate edges.
163
- - Retry loops between `service ↔ generator(pure)` → call/return pair in the macro plus a `dataflow add` step in the service with `--fn issueCode --writes "code"` describing the retry budget; a follow-up step `--fn issueCode --reads "code" --writes "row"` then captures the persistence attempt.
164
- - Variable state transitions inside one function (e.g. `code` is computed, persisted, then returned) → emit one `dataflow add` per logical mutation, with `--fn` constant and `--reads` / `--writes` listing every variable that changes shape at that point. The sub-module page chips trace each variable's life cycle top-to-bottom.
165
- - Cross-feature DB hand-off (A writes, B reads) → declare both sides' `INSERT_*` / `SELECT_*` functions on the `db` sub-module, then `edge add --kind data-row` from producer feature/submodule to consumer feature/submodule.
166
- - Rollback / compensation across sub-modules → `edge add --kind failure --label "rollback on dup"`; rollback *within* a single sub-module belongs in `dataflow add` (with `--fn` set to whichever function owns the cleanup).
167
- - Third-party systems → declare as `--kind external` sub-modules; the trust boundary becomes visible because the renderer styles them differently.
142
+ - Multiple SQL paths on `service ↔ db` → one **`edge`** per SQL path so the macro shows distinct strokes.
143
+ - Retry loops between `service ↔ generator(pure)` → **`call` / `return`** pair on the macro plus ordered **`dataflow`** steps on the service that show retry budget and persistence.
144
+ - Cross-feature DB hand-off (A writes, B reads) → both sides declare DB-oriented functions, then a **`data-row`** edge from producer to consumer.
145
+ - Rollback / compensation across sub-modules → **`failure`** edge with an explicit label; cleanup *inside* a single sub-module belongs in ordered **`dataflow`** steps.
146
+ - Third-party systems → **`external`** kind sub-modules so the trust boundary is visible in styling.
168
147
 
169
148
  ## References
170
149
 
171
- - `lib/atlas/schema.js` — single source of truth for component fields, enums, and validation. `references/TEMPLATE_SPEC.md` mirrors that schema as a quick-reference cheat sheet.
172
- - `lib/atlas/cli.js` — full verb dispatch (run `apltk architecture --help` for the live usage).
150
+ - `lib/atlas/schema.js` — fields, enums, validation. `references/TEMPLATE_SPEC.md` mirrors the schema as a cheat sheet (not a substitute for **`apltk architecture --help`**).
151
+ - `lib/atlas/cli.js` — implementation of dispatch (`apltk architecture --help` prints usage).
173
152
  - `init-project-html/sample-demo/` — end-to-end YAML + rendered HTML for two features.
package/init-project-html/agents/openai.yaml CHANGED
@@ -2,21 +2,10 @@ interface:
2
2
  display_name: "init-project-html"
3
3
  short_description: "Declare the project HTML architecture atlas through `apltk architecture` CLI verbs"
4
4
  default_prompt: >-
5
- Use $init-project-html. Its `SKILL.md` is the authoritative rulebook; `references/TEMPLATE_SPEC.md` is a component-schema cheat sheet.
6
- NEVER hand-author files under `resources/project-architecture/**/*.html`. The atlas state lives in YAML under `resources/project-architecture/atlas/` and every mutation goes through `apltk architecture <verb> ...`; the CLI owns layout, no-overlap, DOM, CSS, ARIA, and pan/zoom — both the macro SVG and each sub-module's internal-dataflow diagram are zoomable.
7
- Read strategy to avoid context loss AND to enforce a hard responsibility split. STEP 1: enumerate the feature-module list (slug + entry + boundary resources) WITHOUT diving into function bodies.
8
- STEP 2: branch by environment.
9
- (2A, preferred) if subagents are available, dispatch ONE write-capable subagent per feature. Each subagent deep-reads ITS OWN feature and declares EVERY intra-feature interaction itself via `apltk architecture ... --feature <slug>`: `submodule add` (with the right `--kind`), `function add` / `variable add` / `dataflow add` (ordered — these steps carry the variable state transitions through the flow) / `error add` rows on every sub-module, and **every intra-feature edge** between its sub-modules (function calls, returns, error propagation, rollback / compensation — model failure / rollback paths as `--kind failure` edges and/or as ordered `dataflow add` steps). The subagent returns ONLY (i) sub-module list (slug + kind + one-line role) and (ii) outbound boundaries to other features' sub-modules (direction + edge kind + suggested label). The main agent never re-reads source for a delegated feature and never re-declares its components — it batches ONLY cross-feature `edge add` (and any shared `actor` / `meta`) from the aggregated outbound summaries, then runs `apltk architecture render` and `apltk architecture validate`.
10
- (2B, no subagents) process features ONE AT A TIME — deep-read feature A, IMMEDIATELY drive the CLI (`feature add`, `submodule add` x N, `function add` / `variable add` / `dataflow add` / `error add` rows, intra-feature `edge add` including failure / rollback edges), drop A's function-level details from working memory, then move to feature B. For cross-feature edges pointing at a not-yet-declared feature, declare a placeholder with `feature add --slug <future> --title <future>` first and refine its title/story on a later pass.
11
- CLI verbs to declare components (always kebab-case slugs; pass `--no-render` to batch then call `apltk architecture render` once at the end):
12
- `apltk architecture meta set --title "..." --summary "..."`,
13
- `apltk architecture actor add --id <kebab> --label "..."`,
14
- `apltk architecture feature add --slug <kebab> --title "..." --story "..." [--depends-on a,b]`,
15
- `apltk architecture submodule add --feature X --slug Y --kind ui|api|service|db|pure-fn|queue|external --role "..."`,
16
- `apltk architecture function add --feature X --submodule Y --name fn --in "T1, T2" --out "R | ErrX" --side pure|io|write|tx|lock|network --purpose "..."`,
17
- `apltk architecture variable add --feature X --submodule Y --name v --type T --scope call|tx|persist|instance|loop --purpose "..."`,
18
- `apltk architecture dataflow add --feature X --submodule Y --step "..." [--fn <declared-fn>] [--reads "v1,v2"] [--writes "v3,v4"] [--at N]` (use `--fn` to surface function-to-function flow inside the sub-module; use `--reads` / `--writes` to surface variable state transitions — every name MUST match a `function`/`variable` already declared in the SAME sub-module or `validate` fails),
19
- `apltk architecture error add --feature X --submodule Y --name ErrCode --when "..." --means "..."`,
20
- `apltk architecture edge add --from <feature>[/sub] --to <feature>[/sub] --kind call|return|data-row|failure --label "..." [--id <stable>]`.
21
- Intra-feature edges (both endpoints in the same feature with sub-modules) land in the feature YAML; cross-feature edges land in `atlas.index.yaml`. After the last mutation run `apltk architecture validate` — must return OK; resolve every reported error before reporting completion.
22
- Each sub-module page describes ONLY itself (`sub-io` function I/O + `sub-vars` variables-with-business-purpose + `sub-dataflow` zoomable internal flow with fn pill + reads/writes chips + `sub-errors` local errors) — express any cross-boundary interaction as an edge, never as sub-module page prose. Two acceptance criteria gate completion: (1) the macro diagram clearly shows feature×sub-module relationships — data flow, call/return interaction logic, error handling, rollback — all as `--kind call|return|data-row|failure` edges (no cross-boundary path expressed only as prose); (2) every non-trivial sub-module's internal diagram clearly shows function-level interactions — `dataflow add --fn <declared-fn>` for function-to-function flow + `--reads` / `--writes` for variable state transitions through the run. Anchor every declaration to a concrete path / symbol / SQL / config; mark TBD when evidence is missing; record scanned roots and deliberate omissions in `meta.summary`. Report which read strategy (2A or 2B) was actually used and the location of the rendered atlas (`resources/project-architecture/index.html`).
5
+ Use $init-project-html. Semantic rules + acceptance criteria live in its SKILL.md; field/enum cheat sheet in references/TEMPLATE_SPEC.md; **exact verb/subverb/flag spelling MUST come from `apltk architecture --help`** — never memorize commands from prose.
6
+ NEVER hand-edit `resources/project-architecture/**/*.html`. State is YAML under `resources/project-architecture/atlas/`; every mutation goes through the CLI; renderer owns layout, CSS, ARIA, pan/zoom on macro + sub-module dataflow SVGs.
7
+ **Subagents only:** STEP 1 — shallow feature-module list (slug, entry, boundaries), no function-body reads. STEP 2 — dispatch ONE write-capable subagent per feature; each declares ALL intra-feature state (sub-modules, function/variable/dataflow/error rows, intra-feature edges) via `apltk architecture` (flags: `--help`). Each returns ONLY (i) sub-module list and (ii) outbound boundary notes for OTHER features.
8
+ **HARD GATE:** the main agent MUST wait until EVERY dispatched subagent has finished (success or explicit failure report) before declaring ANY cross-feature `edge`, shared `meta` that stitches multiple features, or `actor` that exists only for cross-feature context.
9
+ After the gate: batch cross-feature `edge` (+ optional `meta`/`actor`), then `apltk architecture render` (if you used `--no-render`) and `apltk architecture validate`. The orchestrator MUST NOT re-read delegated features or re-declare intra-feature components.
10
+ Sub-module pages are self-only — cross-boundary behavior is ALWAYS `edge` with kind call|return|data-row|failure. Internal `dataflow` steps may reference a declared function plus reads/writes of declared variables in the SAME sub-module or validate fails.
11
+ Anchor every declaration to repo evidence; use `meta.summary` for scanned roots/omissions. Report completion only after validate is OK; point reviewers to `resources/project-architecture/index.html`.