@erclx/aitk 0.49.0 → 0.51.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aitk",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "0.49.0",
+  "version": "0.51.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/claude-orchestrate/REQUIREMENT.md

@@ -15,6 +15,8 @@ The session also writes surfaces it is told only how to read. Refilling the queu
 
 Output drifts everywhere the contract stops. The specified shape covers invocation alone, so a sweep report, a board report, and an analysis each end in a decision the human owns and each buries it under the evidence they would have skipped. A compaction is the same failure one step earlier, since the file that survives it has a stated reader and no stated writer, and the session improvises what to save and loses the reasoning the board never held.
 
+The runbooks the session cannot run from memory fail on a third axis, which is where they are kept. A runbook reached by an installed path is a dependency on a channel this skill does not travel on, so a project holding the plugin and running no install follows the citation to nothing, and nothing reports the break because a missing file produces no error until someone opens the path. The three that cover the moments the loop cannot detect therefore have to ship inside the skill.
+
 ## Must
 
 - Read the priority file for execution order, since the index sorts by filename and states no order
@@ -28,7 +30,9 @@ Output drifts everywhere the contract stops. The specified shape covers invocati
 - Carry a plan pointer in the Plan column and a file set in the Touches column, so a row's readiness and disjointness claims stay checkable
 - Re-resolve the board's plan pointers after any archive, since the archiving skill rewrites the task file and knows nothing about the board
 - Lead a sweep report, a board report, and an analysis with the state, the open decisions, and the next action, keeping the evidence below them
-- Write the pre-compact handoff with what no other file carries, and name the snippet that reads it back
+- Write the pre-compact handoff with what no other file carries, and name the runbook that reads it back
+- Carry the handoff, resume, and sweep runbooks inside the skill, so every citation resolves for a project holding the plugin and nothing else
+- Read the handoff or the resume runbook when the human asks for that side of a compaction, since the request is the only signal available for a moment the loop cannot detect
 
 ## Must not
 
@@ -47,6 +51,7 @@ Output drifts everywhere the contract stops. The specified shape covers invocati
 - Priority file absent: report the queue and say the order is unrecorded rather than inferring it from the index
 - Roadmap absent: omit the roadmap line rather than asserting a version the file does not state
 - Roadmap present but never committed: report the date as uncommitted, since a blank reads as a formatting slip
+- This body dropped from a long session approaching a compaction: name the re-invocation and the runbook paths, since the routing lives in the body and a user-invoked skill routes nothing once it is gone
 
 ## Out of scope
 

package/claude/skills/claude-orchestrate/SKILL.md

@@ -35,9 +35,9 @@ Then output the state of play so the human knows what to launch, review, and mer
 
 The roadmap is optional and this skill does not require it. It carries why a sequence is what it is, changes only when strategy changes, and is absent in a project whose scope has already shipped. Report what it says and name it as the source. Never assert an active version the file does not state, and say nothing about one when the file is missing.
 
-A compaction is a moment this skill cannot detect, so both sides of it are snippets the human fires. Before one, `@.claude/snippets/claude/orchestrator-handoff.md` writes `.claude/tasks/session.md` with the state of play, the decisions taken under delegated authority, the mistakes worth not repeating, and the standing cautions. After one, `@.claude/snippets/claude/orchestrator-resume.md` reads that file back with the board and the groundwork behind the live work. Write nothing to the handoff that the board, a task file, or a groundwork folder already carries.
+A compaction is a moment this skill cannot detect, so the human asks for each side of it and this skill reads the matching runbook when they do. On a request to write the handoff or save the session, read `${CLAUDE_SKILL_DIR}/references/orchestrator-handoff.md` and follow it. It writes `.claude/tasks/session.md` with the state of play, the decisions taken under delegated authority, the mistakes worth not repeating, and the standing cautions. On a request to resume after a compaction, read `${CLAUDE_SKILL_DIR}/references/orchestrator-resume.md`, which reads that file back with the board and the groundwork behind the live work. Write nothing to the handoff that the board, a task file, or a groundwork folder already carries.
 
-Name `${CLAUDE_SKILL_DIR}/../../snippets/claude/<name>.md` as the fallback for any orchestrator snippet the project copy lacks. Snippets install by named bundle rather than wholesale, so a project that installed one bundle has the `.claude/snippets/` directory and none of these files, and the plugin ships the whole snippets folder beside `skills/`.
+That routing lives in this body and this skill is user-invoked, so a session that has dropped the body routes nothing and the request lands as ordinary conversation. Approaching a compaction is when a long session is likeliest to have dropped it, which is the same moment the handoff exists for. Re-invoke `/aitk:claude-orchestrate` first whenever the session has run long or the ask goes unanswered. The two runbooks sit at `references/orchestrator-handoff.md` and `references/orchestrator-resume.md` inside this skill's own folder, so a person who knows their plugin root opens either one directly and follows it without this skill loaded at all.
 
 ## Output
 
@@ -110,7 +110,7 @@ Write no shape for a correction. A correction is a sentence, and a format for ad
 
 ## Refilling the ready queue
 
-Keep enough planned, non-conflicting tasks available that a free worker never waits, and place the findings the last merge produced before promoting anything new. Run this after every merge and whenever the ready list thins. `@.claude/snippets/claude/orchestrator-sweep.md` fires this procedure after a batch of merges and adds the plan re-verification that a merge invalidates.
+Keep enough planned, non-conflicting tasks available that a free worker never waits, and place the findings the last merge produced before promoting anything new. Run this after every merge and whenever the ready list thins. `${CLAUDE_SKILL_DIR}/references/orchestrator-sweep.md` wraps this procedure for a batch of merges and adds the plan re-verification that a merge invalidates.
 
 Open the sweep by invoking `aitk:claude-memory-capture`. Both other callers are ship-chain skills and this session never ships, so without this the session that receives every operator correction is the one session that records none. The sweep is the closest bounded moment this session has to a ship, and it already runs once per batch of merges, which beats an end-of-session moment a compaction can cut short.
 

package/{snippets/claude → claude/skills/claude-orchestrate/references}/orchestrator-handoff.md

@@ -1,3 +1,8 @@
+---
+title: Orchestrator handoff runbook
+description: What to write to .claude/tasks/session.md before a compaction, and what to leave to the board
+---
+
 Write the pre-compact handoff as orchestrator. Do this before a compaction, because a compaction keeps conclusions and drops the reasoning that produced them, and no other file in the repository carries that reasoning.
 
 1. Resolve the main worktree root with `git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`, falling back to `pwd`. Write `.claude/tasks/session.md` under it.

package/{snippets/claude → claude/skills/claude-orchestrate/references}/orchestrator-resume.md

@@ -1,3 +1,8 @@
+---
+title: Orchestrator resume runbook
+description: What to read back after a compaction, and how to treat a groundwork folder's three shelf lives
+---
+
 Resume as orchestrator after a compaction. Read the board and the groundwork behind the live work before answering anything, because a compaction summary keeps conclusions and drops the reasoning that produced them.
 
 1. Resolve the main worktree root with `git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`, falling back to `pwd`. Every path below resolves against it.

package/{snippets/claude → claude/skills/claude-orchestrate/references}/orchestrator-sweep.md

@@ -1,3 +1,8 @@
+---
+title: Orchestrator sweep runbook
+description: The once-per-batch board sweep, plan re-verification, and where each merged finding goes
+---
+
 Sweep the board as orchestrator after merging. Run this once per batch of merges, before answering what to do next, because the surfaces that record what shipped are the ones nothing updates on its own.
 
 1. Pull into the main worktree rather than fetching. A fetch leaves the local branch behind, so `git log` reports a state that has not arrived. A repository that adds a post-merge hook to name archive candidates gets it on a pull and never on a fetch.

package/docs/visual-design-workflow.md

@@ -18,7 +18,7 @@ The default. `.claude/DESIGN.md` holds visual intent as prose plus token tables
 
 ### Seed shape
 
-The toolkit seed in `tooling/claude/seeds/.claude/DESIGN.md` ships a token-table template. The `aitk:claude-design-extract` skill drafts the file, sourcing tokens from a project's existing prose and CLI UI surfaces, or proposing them from `.claude/REQUIREMENTS.md` and a `## Personality` paragraph when no UI code exists yet. `aitk design render` writes an HTML plus CSS preview to `.claude/review/design/` for eyeballing the current system without leaving Claude Code. See `.claude/context/design.md`.
+The toolkit seed in `tooling/claude/seeds/.claude/DESIGN.md` ships a token-table template with a starting set of roles, and `.claude/standards/design.md` carries the same tables under `## Template` with placeholder rows. The column headers are what the renderer parses, so they stay verbatim in either, while the rows and values are the project's own. The `aitk:claude-design-extract` skill drafts the file, sourcing tokens from a project's existing prose and CLI UI surfaces, or proposing them from `.claude/REQUIREMENTS.md` and a `## Personality` paragraph when no UI code exists yet. `aitk design render` writes an HTML plus CSS preview to `.claude/review/design/` for eyeballing the current system without leaving Claude Code. See `.claude/context/design.md`.
 
 ### Tools
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "0.49.0",
+  "version": "0.51.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/snippets/snippets.toml

@@ -3,10 +3,3 @@ names = [
     "align",
     "decision-help",
 ]
-
-[orchestrator]
-names = [
-    "claude/orchestrator-handoff",
-    "claude/orchestrator-resume",
-    "claude/orchestrator-sweep",
-]

package/standards/design.md

@@ -37,3 +37,47 @@ Does not govern:
 ## Sections
 
 Use `## Personality`, `## Color`, `## Typography`, `## Spacing`, `## Borders`, `## Motion`, and `## Iconography`. The token tables carry fixed headers the renderer reads.
+
+## Template
+
+The column headers are the strings the renderer parses, read by exact key, so they stay verbatim. Row names are not. Each is slugged into the variable name it emits, which leaves a project free to rename a row, add one, or drop one it has no use for.
+
+```markdown
+# Design
+
+## Personality
+
+<one paragraph on voice, tone, and the feeling a user should have>
+
+## Color
+
+| Role   | Intent           | Value   |
+| ------ | ---------------- | ------- |
+| <role> | <what it is for> | <value> |
+
+## Typography
+
+| Role   | Family   | Weight   | Size   | Line height |
+| ------ | -------- | -------- | ------ | ----------- |
+| <role> | <family> | <weight> | <size> | <height>    |
+
+## Spacing
+
+| Step   | Multiplier   | Value   |
+| ------ | ------------ | ------- |
+| <step> | <multiplier> | <value> |
+
+## Borders
+
+| Role   | Radius   | Width   | When used   |
+| ------ | -------- | ------- | ----------- |
+| <role> | <radius> | <width> | <when used> |
+
+## Motion
+
+<whether motion is used at all, and if so the default duration and easing>
+
+## Iconography
+
+<style, source library, and whether custom icons are allowed>
+```

package/standards/diagrams.md

@@ -122,3 +122,31 @@ Reference the context entry by path when a reader needs the mechanism. The diagr
 - That watch samples thinly. It sees the one or two paths an entry happened to cite and nothing else, so a change elsewhere leaves the entry looking current. `verified` is what covers the gap, and an entry whose date sits far behind the branch is due a read whether or not anything flagged it.
 - The explanation paragraphs around a Mermaid block are prose and follow `prose.md`. The fenced block itself is not, which is why a check scoped to prose is the wrong thing to rely on for what sits inside it.
 - The punctuation bans still apply to node and subgraph labels, and nothing checks them there. An em dash in a label passes every gate the repository has, so read the labels before shipping the entry.
+
+## Template
+
+The filename and the `category` value both come from Entry kinds and are fixed per kind. A stub nobody has drawn yet carries `TODO: never verified` in place of the SHA and date. The node names and labels inside the fence are placeholders, written bare because Mermaid reads an angle bracket as markup.
+
+````markdown
+---
+title: <what the entry answers>
+description: <which question it settles and which source signal drives it>
+category: <the kind, verbatim from Entry kinds>
+verified: <short-sha> <YYYY-MM-DD>
+---
+
+# <what the entry answers>
+
+```mermaid
+flowchart TB
+    accTitle: what the diagram answers
+    accDescr: the structure in one sentence for a reader who cannot see the render
+
+    a[first part] --> b[second part]
+    b --> c[third part]
+```
+
+<One paragraph leading with what the diagram shows.>
+
+<One paragraph on why this shape was chosen and what was rejected, where the choice was non-obvious. Name one or two code paths the reader can open.>
+````

package/standards/publish.md

@@ -7,7 +7,7 @@ description: Scan run against finished text leaving through a channel no automat
 
 ## Scope
 
-Governs the scan an author runs against finished text on its way out, and the responses available when a source it reaches for cannot be read. It is an attribute standard rather than a document-type one, so it applies to any text leaving through a channel no automated check covers.
+Governs the scan an author runs against finished text on its way out, and the responses available when a source it reaches for cannot be read. It is an attribute standard rather than a document-type one, so it applies to any text leaving through a channel no automated check covers, and it carries no template because a scan has no document to shape.
 
 Does not govern:
 

package/standards/slug.md

@@ -7,7 +7,7 @@ description: Transform from a git branch name to a slug, and the three responses
 
 ## Scope
 
-Governs the transform from a git branch name to the slug a surface carries in a derived name, and the responses available when the transform returns empty. It is an attribute standard rather than a document-type one, so it applies wherever a branch-derived name is produced.
+Governs the transform from a git branch name to the slug a surface carries in a derived name, and the responses available when the transform returns empty. It is an attribute standard rather than a document-type one, so it applies wherever a branch-derived name is produced, and it carries no template because a string has no document to shape.
 
 Does not govern:
 

package/standards/standard.md

@@ -91,3 +91,60 @@ A standard failing these questions is non-conforming even when it satisfies ever
 - When shown, label them `### Correct` and `### Incorrect` with an inline `# reason` on each entry
 - Keep to two or three entries. Show the pattern, not a catalog.
 - Keep each entry a short one-liner or command. Do not write multi-line correct and incorrect function blocks.
+
+## Template
+
+- Carry one fenced template of the document the standard governs, so an author copies a shape instead of reconstructing it from prose.
+- Bind this to a standard governing a document type. An attribute standard governs a scan, a string, or a label rather than a file, so it has no document to template and carries none.
+- State that exemption in the sentence declaring the standard an attribute standard. An exemption left to inference reads as an omission, and the next author writes a template that teaches nothing.
+- Place the template below the rules it satisfies, under a `## Template` heading or inside the section holding those rules. A reader arrives at it having already read what each part means.
+- Show the skeleton alone: every required section, one placeholder line for what each holds. A full worked document is a second document to maintain.
+- Write placeholders in angle brackets rather than copying a real document. A copied file goes stale, and its backticked filenames read as citations to anything parsing the standard.
+- Switch to a bare word where the fenced language reads `<` as syntax of its own, as Mermaid and HTML do, and say in the line above the fence that the names are placeholders. A template that does not parse in its own language teaches a shape the author cannot run.
+- Carry any header, key, or label a consuming tool parses verbatim. The template is the only place an author learns which strings are load-bearing, since prose calling them fixed does not say what they are.
+- Treat the template as authoritative where it and the prose disagree. An author copies the block, so a contradiction ships as the block, and naming the winner turns a drift into a visible defect rather than a silent one.
+
+````markdown
+---
+title: <Document type> reference
+description: <one line naming what this standard covers>
+---
+
+# <Document type> reference
+
+Applies to `<path/to/document>`. <One line on what the document is for and when it changes.>
+
+## Scope
+
+Governs `<path/to/document>`: <the aspects this standard sets>.
+
+Does not govern:
+
+- <excluded concern>: `<sibling>.md`
+- <excluded concern>: <the surface that owns it>
+
+## What a working <document type> looks like
+
+A <document type> works when <the task a reader completes from it alone>:
+
+- <question the document must answer>
+- <question the document must answer>
+
+A <document type> failing these is non-conforming even when it satisfies every shape rule below.
+
+## Frontmatter
+
+- `title` (required): <casing, and what it names>
+- `description` (required): <what the one line covers>
+
+## <Shape rule group>
+
+- <imperative rule, one concern per bullet>
+- <imperative rule, one concern per bullet>
+
+## Template
+
+```markdown
+<the skeleton of the governed document, placeholders throughout>
+```
+````

package/standards/versioning.md

@@ -9,7 +9,7 @@ Two namespaces, kept separate.
 
 ## Scope
 
-Governs the two version namespaces, phase labels and semver tags, and which surfaces each may appear on. It is an attribute standard rather than a document-type one, so it applies wherever either namespace is written.
+Governs the two version namespaces, phase labels and semver tags, and which surfaces each may appear on. It is an attribute standard rather than a document-type one, so it applies wherever either namespace is written, and it carries no template because a label has no document to shape.
 
 Does not govern:
 

package/standards/wireframes.md

@@ -75,3 +75,38 @@ Reference the context entry from the wireframe by path when a reader needs the m
 
 - When a surface's layout or interaction changes, update its wireframe file in the same PR. A wireframe showing a defunct layout is worse than none.
 - The Behavior and Copy prose around an ASCII block is prose and follows `prose.md`. The fenced block itself is not, so a check scoped to prose is the wrong thing to rely on for what sits inside it.
+
+## Template
+
+One H2 per layout variant, each holding its own fence. A surface with a single layout carries one.
+
+````markdown
+---
+title: <Surface name>
+description: <when and where the surface appears>
+---
+
+# <Surface name>
+
+## <what triggers this variant>
+
+```plaintext
++------------------------------------------+
+| <region>                    ← <its role> |
++------------------------------------------+
+|                                          |
+| <region>                    ← <its role> |
+|                                          |
++------------------------------------------+
+```
+
+## Copy
+
+- <on-screen text, word for word>
+- <text the surface templates>: <marked so a reader does not read it as final>
+
+## Behavior
+
+- <what the visitor does, and what changes on screen>
+- <what each reachable state looks like>
+````