@erclx/aitk 0.49.0 → 0.50.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.50.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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.50.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

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>
+````