@erclx/aitk 0.17.0 → 0.19.0
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.
- package/README.md +1 -1
- package/claude/.claude-plugin/plugin.json +1 -1
- package/claude/skills/claude-design-extract/SKILL.md +49 -15
- package/claude/skills/claude-design-propose/SKILL.md +6 -66
- package/claude/skills/create-snippet/SKILL.md +5 -20
- package/claude/skills/create-standard/SKILL.md +11 -7
- package/claude/skills/{create-snippet → create-standard}/references/snippets.md +1 -1
- package/docs/ai-workflow.md +18 -18
- package/docs/target-projects.md +1 -1
- package/docs/visual-design-workflow.md +2 -2
- package/package.json +1 -1
- package/standards/bundled/snippets.md +1 -1
- package/standards/context.md +2 -0
package/README.md
CHANGED
|
@@ -48,7 +48,7 @@ Each domain has a canonical source in this repo and a thin install or sync CLI o
|
|
|
48
48
|
- [Standards](.claude/context/standards.md): shared authoring conventions, synced to projects
|
|
49
49
|
- [Snippets](.claude/context/snippets.md): reusable prompts for Claude and Gemini chat
|
|
50
50
|
- [Tooling stacks](.claude/context/tooling.md): golden configs, seeds, and references per framework
|
|
51
|
-
- [Design system](.claude/context/design.md): `DESIGN.md` token shape, extract skill, render command
|
|
51
|
+
- [Design system](.claude/context/design.md): `DESIGN.md` token shape, extract skill and its two paths, render command
|
|
52
52
|
- [Slides](.claude/context/slides.md): `SLIDES.md` source, layout catalog, render command, draft skill
|
|
53
53
|
- [Transcripts](.claude/context/transcripts.md): fetch a YouTube transcript with metadata frontmatter via `aitk transcripts`
|
|
54
54
|
- [Sandbox](.claude/context/sandbox.md): scenario-based scaffolds for verifying each domain flow
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: claude-design-extract
|
|
3
|
-
description: Drafts `.claude/DESIGN.md` from a project's existing prose and shell UI surfaces
|
|
3
|
+
description: Drafts `.claude/DESIGN.md` from a project's existing prose and shell UI surfaces, or proposes token values from `REQUIREMENTS.md` and a `## Personality` section when no UI code exists yet. Use when asked to "extract the design system", "draft DESIGN.md", "bootstrap design tokens", "capture the visual system", "propose a design system", "bootstrap DESIGN.md from scratch", "draft tokens for a greenfield project", or "replace Claude Design onboarding". Do NOT use to mutate an existing `.claude/DESIGN.md`.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Design extract
|
|
@@ -10,23 +10,39 @@ description: Drafts `.claude/DESIGN.md` from a project's existing prose and shel
|
|
|
10
10
|
- If `.claude/DESIGN.md` already exists and has content beyond the seed template, stop: `❌ .claude/DESIGN.md already populated. Edit directly or archive the existing file first.`
|
|
11
11
|
- If `aitk` is not on PATH, stop: `❌ aitk CLI not found.`
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
Step 1 carries two more stops that apply to one path only. Do not evaluate them before the path is picked.
|
|
14
14
|
|
|
15
|
-
|
|
15
|
+
## Step 1: pick the path from what the project already has
|
|
16
|
+
|
|
17
|
+
Check the project root for UI surfaces: `src/ui.ts`, `src/ui.tsx`, `src/components/**`, `scripts/lib/ui.sh`, and any `*.css`, `tailwind.config.*`, or `theme.*`.
|
|
18
|
+
|
|
19
|
+
- Any match takes the source path. Existing code defines the system, so every filled cell traces to a value already in the tree.
|
|
20
|
+
- No match takes the greenfield path. Nothing anchors a value, so every filled cell is a proposal and carries the tag that says so.
|
|
21
|
+
|
|
22
|
+
The project decides this, never a user flag or an argument. Announce which path ran in one line before Step 2, since the two produce different-looking output from the same skill.
|
|
23
|
+
|
|
24
|
+
The greenfield path needs a personality paragraph to propose against, and stops without one. The source path needs neither file and skips both stops.
|
|
25
|
+
|
|
26
|
+
- If `.claude/REQUIREMENTS.md` is missing, stop: `❌ .claude/REQUIREMENTS.md not found. Write requirements before proposing a design system.`
|
|
27
|
+
- If `.claude/REQUIREMENTS.md` has no `## Personality` section, stop: `❌ .claude/REQUIREMENTS.md missing ## Personality section. Add a paragraph describing voice and tone before running this skill.`
|
|
28
|
+
|
|
29
|
+
## Step 2: read source signals in parallel
|
|
30
|
+
|
|
31
|
+
Read these from the project root on both paths, skipping any that do not exist:
|
|
16
32
|
|
|
17
33
|
- `CLAUDE.md`: voice, personality, spelling rules
|
|
18
|
-
- `.claude/REQUIREMENTS.md`: worldview
|
|
34
|
+
- `.claude/REQUIREMENTS.md`: the `## Personality` paragraph, worldview, non-goals
|
|
19
35
|
- `.claude/standards/prose.md`: tone constraints
|
|
20
|
-
- `src/ui.ts`, `src/ui.tsx`, `src/components/**`: color codes, typography, spacing constants
|
|
21
|
-
- `scripts/lib/ui.sh`, `scripts/lib/*.sh`: ANSI color codes, frame glyphs, spacing conventions
|
|
22
|
-
- `docs/agents.md`, `docs/index.md`: any output shape or framing rules already documented
|
|
23
|
-
- Any `*.css`, `tailwind.config.*`, or `theme.*` file at the project root
|
|
24
36
|
|
|
25
37
|
Read a standard from `${CLAUDE_SKILL_DIR}/../../standards/` instead when the project does not have it.
|
|
26
38
|
|
|
39
|
+
On the source path, also read the UI surfaces matched in Step 1 plus `docs/agents.md` and `docs/index.md` for output shape or framing rules already documented.
|
|
40
|
+
|
|
41
|
+
On the greenfield path, also read `.claude/ARCHITECTURE.md` for platform, tech stack, and surface type. Do not scan `src/`, stylesheets, or UI modules. Step 1 already established they hold nothing.
|
|
42
|
+
|
|
27
43
|
Run these reads in parallel. Do not speculatively recurse into every directory.
|
|
28
44
|
|
|
29
|
-
## Step
|
|
45
|
+
## Step 3: fetch the seed template
|
|
30
46
|
|
|
31
47
|
Run this from the project root:
|
|
32
48
|
|
|
@@ -36,20 +52,38 @@ aitk claude seeds list --json | jq -r '.[] | select(.path == ".claude/DESIGN.md"
|
|
|
36
52
|
|
|
37
53
|
Use the returned content as the target shape. Keep every section heading and every table header intact. The `aitk design render` parser depends on them.
|
|
38
54
|
|
|
39
|
-
## Step
|
|
55
|
+
## Step 4: fill the template
|
|
56
|
+
|
|
57
|
+
Walk each section once. Follow `.claude/standards/prose.md` throughout: no em dashes, no semicolons, no marketing buzzwords. Use commas or separate sentences instead.
|
|
58
|
+
|
|
59
|
+
Mark any cell not traced to a source value by appending ` ? verify` inside the cell value, never as a trailing column. The cell stays inside the table shape: `| #ffffff ? verify |`. A trailing `| ? verify` after the row breaks the parser. A prose section takes its uncertainty inline instead, for example `Proposed 150ms ease-out, not yet confirmed.`, because a trailing tag on a sentence renders raw in the preview.
|
|
60
|
+
|
|
61
|
+
On the source path, the tag marks the exception. On the greenfield path it marks nearly every cell, since the values are speculative until code or a designer anchors them.
|
|
40
62
|
|
|
41
|
-
|
|
63
|
+
### Source path
|
|
42
64
|
|
|
43
|
-
- **Personality**: one paragraph. Transcribe what `CLAUDE.md` and `.claude/REQUIREMENTS.md` say about voice, tone, and visual feeling. Do not invent rules the source does not state.
|
|
65
|
+
- **Personality**: one paragraph. Transcribe what `CLAUDE.md` and `.claude/REQUIREMENTS.md` say about voice, tone, and visual feeling. Do not invent rules the source does not state. If nothing matches, write a one-sentence placeholder ending in `? verify`.
|
|
44
66
|
- **Color**: one row per role. Source hex values from the CLI UI files or stylesheets. If a role has no source signal, leave `Value` blank rather than guessing.
|
|
45
67
|
- **Typography**: one row per role. Source families and sizes from stylesheet or theme config. Leave cells blank when no signal exists.
|
|
46
68
|
- **Spacing**: fill the base unit and multipliers from stylesheet tokens or obvious repeated values in the UI code.
|
|
47
69
|
- **Borders**: one row per role. Source from stylesheet or CSS variables.
|
|
48
70
|
- **Motion** and **Iconography**: one line each. Default to `No animation.` and `No custom icons.` when no evidence exists.
|
|
49
71
|
|
|
50
|
-
|
|
72
|
+
### Greenfield path
|
|
73
|
+
|
|
74
|
+
Anchor every proposal to a signal, never to a default. "Calm and dense" pins muted grays and tight spacing. A requirements non-goal of "no motion" makes Motion read `No animation.` with no tag. A CLI-only surface leans Typography monospaced and keeps Borders minimal.
|
|
75
|
+
|
|
76
|
+
- **Personality**: transcribe the `## Personality` paragraph from `.claude/REQUIREMENTS.md` verbatim. This is the one section that is not a proposal. No tag.
|
|
77
|
+
- **Color**: one row per role. Rewrite the Intent cell in personality language, for example `warm off-white page canvas` instead of the seed default `page canvas`. Propose hex values matching the personality. Dense and calm gives low saturation and high text contrast. Playful gives saturated accents. Every Intent and Value cell gets `? verify`.
|
|
78
|
+
- **Typography**: one row per role. Propose families fitting the platform, system UI for web, monospaced for CLI tools, serif for editorial, and a harmonious scale. Every cell gets `? verify`.
|
|
79
|
+
- **Spacing**: propose a base unit matching density intent. Dense gives a 4px base, roomy gives 8px. Keep the Multiplier column as the seed ships it, no tag. Only the Value column gets `? verify`.
|
|
80
|
+
- **Borders**: propose radius and width per role. Sharp and technical gives a small radius, soft gives a larger one. Every Radius and Width cell gets `? verify`.
|
|
81
|
+
- **Motion**: one line. Write `No animation.` when the requirements forbid motion. Otherwise phrase the uncertainty inline.
|
|
82
|
+
- **Iconography**: one line. Propose style and source library matching personality, phrasing the uncertainty inline.
|
|
83
|
+
|
|
84
|
+
Do not invent non-goals. A proposed motion line is fine when neither the personality paragraph nor the requirements rule motion out.
|
|
51
85
|
|
|
52
|
-
## Step
|
|
86
|
+
## Step 5: write and render
|
|
53
87
|
|
|
54
88
|
Write the filled template to `.claude/DESIGN.md` from the project root. Then run:
|
|
55
89
|
|
|
@@ -65,5 +99,5 @@ The command writes an HTML plus CSS preview to `.claude/review/design/`. Output
|
|
|
65
99
|
📝 Wrote .claude/DESIGN.md
|
|
66
100
|
📝 Wrote .claude/review/design/index.html
|
|
67
101
|
|
|
68
|
-
N cells marked `? verify`. Open the preview and confirm before committing.
|
|
102
|
+
Ran the <source|greenfield> path. N cells marked `? verify`. Open the preview and confirm before committing.
|
|
69
103
|
```
|
|
@@ -1,75 +1,15 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: claude-design-propose
|
|
3
|
-
description:
|
|
3
|
+
description: Retired. `claude-design-extract` absorbed this skill and now takes the greenfield path itself. Invoke `aitk:claude-design-extract` instead.
|
|
4
|
+
disable-model-invocation: true
|
|
4
5
|
---
|
|
5
6
|
|
|
6
7
|
# Design propose
|
|
7
8
|
|
|
8
|
-
|
|
9
|
+
Retired. `claude-design-extract` absorbed the greenfield path, picks it from what the project has, and its description carries every trigger this skill used to route on.
|
|
9
10
|
|
|
10
|
-
-
|
|
11
|
-
- If `.claude/REQUIREMENTS.md` is missing, stop: `❌ .claude/REQUIREMENTS.md not found. Write requirements before proposing a design system.`
|
|
12
|
-
- If `.claude/REQUIREMENTS.md` has no `## Personality` section, stop: `❌ .claude/REQUIREMENTS.md missing ## Personality section. Add a paragraph describing voice and tone before running this skill.`
|
|
13
|
-
- If `aitk` is not on PATH, stop: `❌ aitk CLI not found.`
|
|
11
|
+
Invoke `aitk:claude-design-extract` instead. It reads `.claude/REQUIREMENTS.md` for the `## Personality` paragraph and `.claude/ARCHITECTURE.md` for platform signals when the project has no UI code, which is what this skill did.
|
|
14
12
|
|
|
15
|
-
|
|
13
|
+
This body exists so a project that installed the plugin before the merge keeps resolving the old name for one sync cycle. It ships in `0.18.0` and is removed in `0.19.0`.
|
|
16
14
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
- `.claude/REQUIREMENTS.md`: the `## Personality` paragraph, worldview, non-goals
|
|
20
|
-
- `.claude/ARCHITECTURE.md`: platform, tech stack, surface type (CLI, web, desktop)
|
|
21
|
-
- `CLAUDE.md`: voice rules, spelling, conventions
|
|
22
|
-
- `.claude/standards/prose.md`: tone constraints if present
|
|
23
|
-
|
|
24
|
-
Read a standard from `${CLAUDE_SKILL_DIR}/../../standards/` instead when the project does not have it.
|
|
25
|
-
|
|
26
|
-
Do not scan `src/`, stylesheets, or UI modules. This skill runs before code exists. If those files are present, the scenario is wrong and `claude-design-extract` is the correct tool.
|
|
27
|
-
|
|
28
|
-
## Step 2: fetch the seed template
|
|
29
|
-
|
|
30
|
-
Run this from the project root:
|
|
31
|
-
|
|
32
|
-
```bash
|
|
33
|
-
aitk claude seeds list --json | jq -r '.[] | select(.path == ".claude/DESIGN.md") | .content'
|
|
34
|
-
```
|
|
35
|
-
|
|
36
|
-
Use the returned content as the target shape. Keep every section heading and every table header intact. The `aitk design render` parser depends on them.
|
|
37
|
-
|
|
38
|
-
## Step 3: propose tokens from personality and requirements
|
|
39
|
-
|
|
40
|
-
Walk each section once. Follow `.claude/standards/prose.md` throughout: no em dashes, no semicolons, no marketing buzzwords. Use commas or separate sentences instead.
|
|
41
|
-
|
|
42
|
-
Every proposed table cell is speculative, so every filled table cell gets a trailing `? verify` tag inside the cell value, never as a trailing column.
|
|
43
|
-
|
|
44
|
-
Anchor proposals to signals, not defaults. If the personality says "calm and dense", that pins muted grays and tight spacing. If the requirements say "no motion", Motion writes `No animation.` with no tag. If the architecture names a CLI-only surface, Typography leans monospaced and Borders stays minimal.
|
|
45
|
-
|
|
46
|
-
- **Personality**: transcribe the `## Personality` paragraph from `.claude/REQUIREMENTS.md` verbatim. This is the one section that is not a proposal. No tag.
|
|
47
|
-
- **Color**: one row per role. Rewrite the Intent cell in personality language, for example `warm off-white page canvas` instead of the seed default `page canvas`. Propose hex values that match the personality. Dense and calm → low saturation, high text contrast. Playful → saturated accents. Every Intent and Value cell gets `? verify`.
|
|
48
|
-
- **Typography**: one row per role. Propose families that fit the platform (system UI for web, monospaced for CLI tools, serif for editorial) and a harmonious scale. Every cell gets `? verify`.
|
|
49
|
-
- **Spacing**: propose a base unit that matches density intent. Dense → 4px base. Roomy → 8px base. Keep the Multiplier column as the seed ships it, no tag. Only the Value column gets `? verify`.
|
|
50
|
-
- **Borders**: propose radius and width per role. Sharp and technical → small radius. Soft → larger radius. Every Radius and Width cell gets `? verify`.
|
|
51
|
-
- **Motion**: one line. If the requirements forbid motion, write `No animation.` If motion is allowed, phrase uncertainty inline, for example `Proposed 150ms ease-out, not yet confirmed.` Do not append a trailing `? verify` tag to a prose sentence. It renders raw in the preview.
|
|
52
|
-
- **Iconography**: one line. Propose style and source library matching personality. Phrase uncertainty inline, for example `Proposed outline style, source library not yet chosen.` Do not append a trailing `? verify` tag.
|
|
53
|
-
|
|
54
|
-
Do not invent non-goals. If the personality paragraph does not mention motion and the requirements do not forbid it, a proposed motion line is acceptable.
|
|
55
|
-
|
|
56
|
-
A cell marked `? verify` must stay inside the table shape: `| #ffffff ? verify |`. A trailing `| ? verify` column breaks the parser.
|
|
57
|
-
|
|
58
|
-
## Step 4: write and render
|
|
59
|
-
|
|
60
|
-
Write the filled template to `.claude/DESIGN.md` from the project root. Then run:
|
|
61
|
-
|
|
62
|
-
```bash
|
|
63
|
-
aitk design render
|
|
64
|
-
```
|
|
65
|
-
|
|
66
|
-
The command writes an HTML plus CSS preview to `.claude/review/design/`. Output the path in chat so the user can open it.
|
|
67
|
-
|
|
68
|
-
## Response format
|
|
69
|
-
|
|
70
|
-
```plaintext
|
|
71
|
-
📝 Wrote .claude/DESIGN.md
|
|
72
|
-
📝 Wrote .claude/review/design/index.html
|
|
73
|
-
|
|
74
|
-
N cells marked `? verify`. Open the preview, confirm the personality read as intended, then edit DESIGN.md directly to lock values.
|
|
75
|
-
```
|
|
15
|
+
`scripts/sandbox/claude/design-propose.sh` goes at the same time, but its fixture does not. That scenario is the only greenfield coverage the survivor has, so `0.19.0` folds it into `scripts/sandbox/claude/design-extract.sh` as a second arm rather than deleting it. Removing the file outright drops the greenfield path from the catalog.
|
|
@@ -1,28 +1,13 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: create-snippet
|
|
3
|
-
description:
|
|
3
|
+
description: Retired. `create-standard` absorbed this skill and writes snippets as well as standards. Invoke `aitk:create-standard` instead.
|
|
4
|
+
disable-model-invocation: true
|
|
4
5
|
---
|
|
5
6
|
|
|
6
7
|
# Create snippet
|
|
7
8
|
|
|
8
|
-
|
|
9
|
+
Retired. `create-standard` absorbed the snippet surface, resolves `snippets/` or `.claude/snippets/` the same way it resolves the standards folders, and its description carries every trigger this skill used to route on.
|
|
9
10
|
|
|
10
|
-
-
|
|
11
|
-
- `.claude/standards/prose.md` from the project root: prose conventions for all generated text
|
|
11
|
+
Invoke `aitk:create-standard` instead and ask for a snippet. The name understates what the skill covers, which is why its description names both surfaces.
|
|
12
12
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
## Guards
|
|
16
|
-
|
|
17
|
-
- If neither `snippets/` nor `.claude/snippets/` exists, stop: `❌ No snippets/ or .claude/snippets/ directory found.`
|
|
18
|
-
|
|
19
|
-
## Steps
|
|
20
|
-
|
|
21
|
-
1. Resolve the write surface: `snippets/` at the project root if present, the toolkit's own authoring source. Otherwise `.claude/snippets/`, a target project's installed copy.
|
|
22
|
-
2. Confirm the slug and full content with the user before writing
|
|
23
|
-
3. Write the file to `<surface>/<slug>.md`
|
|
24
|
-
|
|
25
|
-
## After writing
|
|
26
|
-
|
|
27
|
-
- Root surface (`snippets/`): this is the toolkit's authoring source. Remind the user `bun run check` regenerates the consumed copy under `.claude/snippets/`.
|
|
28
|
-
- `.claude/snippets/` surface: the file is project-local. `aitk snippets sync` leaves it alone, since sync only updates filenames it recognizes from the toolkit. Remind the user to copy it to the toolkit repo, under `snippets/<category>/<name>.md`, if it should ship to every project.
|
|
13
|
+
This body exists so a project that installed the plugin before the merge keeps resolving the old name for one sync cycle. It ships in `0.18.0` and is removed in `0.19.0`.
|
|
@@ -1,25 +1,29 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: create-standard
|
|
3
|
-
description: Creates a new standard file in `standards/`
|
|
3
|
+
description: Creates a new standard file in `standards/` or `.claude/standards/`, or a new snippet file in `snippets/` or `.claude/snippets/`. Use when asked to create a standard, add a standard, write a new authoring convention, create a snippet, add a snippet, or make a new snippet. Do NOT use to edit an existing standard or snippet.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Create standard
|
|
7
7
|
|
|
8
|
+
Creates one authoring file on either surface. Read the user's request for which artifact they asked for, standard or snippet, and carry that choice through every step below. Ask only when the request names neither.
|
|
9
|
+
|
|
8
10
|
Read these files in parallel:
|
|
9
11
|
|
|
10
|
-
- `.claude/standards/standard.md` from the project root: the meta-standard for a standard's shape, frontmatter, and structure
|
|
11
12
|
- `.claude/standards/prose.md` from the project root: prose conventions for all generated text
|
|
13
|
+
- `.claude/standards/standard.md` from the project root, for a standard: the meta-standard for shape, frontmatter, and structure
|
|
14
|
+
- `${CLAUDE_SKILL_DIR}/references/snippets.md`, for a snippet: authoring conventions, invocation channels, use patterns
|
|
12
15
|
|
|
13
16
|
Read a standard from `${CLAUDE_SKILL_DIR}/../../standards/` instead when the project does not have it.
|
|
14
17
|
|
|
15
18
|
## Guards
|
|
16
19
|
|
|
17
|
-
-
|
|
20
|
+
- For a standard, if neither `standards/` nor `.claude/standards/` exists, stop: `❌ No standards/ or .claude/standards/ directory found.`
|
|
21
|
+
- For a snippet, if neither `snippets/` nor `.claude/snippets/` exists, stop: `❌ No snippets/ or .claude/snippets/ directory found.`
|
|
18
22
|
|
|
19
23
|
## Steps
|
|
20
24
|
|
|
21
|
-
1. Resolve the write surface: `standards/`
|
|
22
|
-
2. Draft the
|
|
25
|
+
1. Resolve the write surface for the chosen artifact: the root folder (`standards/` or `snippets/`) if present, the toolkit's own authoring source. Otherwise the `.claude/` folder, a target project's installed copy.
|
|
26
|
+
2. Draft the content from the user's description. A standard follows `standard.md` for frontmatter, headings, and structure.
|
|
23
27
|
3. Confirm the slug and full content with the user before writing
|
|
24
28
|
4. Write the file to `<surface>/<slug>.md`
|
|
25
29
|
|
|
@@ -27,5 +31,5 @@ Read a standard from `${CLAUDE_SKILL_DIR}/../../standards/` instead when the pro
|
|
|
27
31
|
|
|
28
32
|
Emit the full path on its own line.
|
|
29
33
|
|
|
30
|
-
- Root surface
|
|
31
|
-
- `.claude
|
|
34
|
+
- Root surface: this is the toolkit's authoring source. Remind the user to run `bun run check` to regenerate the consumed copy under `.claude/`. For a standard, that pass also regenerates the `standards/index.md` entry, and the user adds a row to the standards table in `.claude/context/standards.md`.
|
|
35
|
+
- `.claude/` surface: the file is project-local. `aitk standards sync` and `aitk snippets sync` leave it alone, since sync only updates filenames it recognizes from the toolkit. Remind the user to copy it to the toolkit repo, under `standards/<slug>.md` or `snippets/<category>/<name>.md`, if it should ship to every project.
|
package/docs/ai-workflow.md
CHANGED
|
@@ -126,24 +126,24 @@ Before the first feature session on a UI-heavy project, pick a design tier. The
|
|
|
126
126
|
|
|
127
127
|
## Skills
|
|
128
128
|
|
|
129
|
-
| Skill | When to use
|
|
130
|
-
| ---------------------------- |
|
|
131
|
-
| `aitk:claude-groundwork` | Before a plan is warranted, measure an unknown in a scratch folder under `.claude/.tmp/groundwork/`
|
|
132
|
-
| `aitk:claude-feature` | Before implementation, scan for conflicts and ambiguities
|
|
133
|
-
| `aitk:claude-roadmap` | Sequence MVP scope into ordered versions in `.claude/ROADMAP.md`
|
|
134
|
-
| `aitk:claude-orchestrate` | Assert the orchestrator role, refill the ready queue, and dispatch the roadmap, feature, and review skills
|
|
135
|
-
| `aitk:claude-diagram` | Draft per-kind mermaid entries under `.claude/diagrams/` from architecture and code, then verify each rendered image
|
|
136
|
-
| `aitk:claude-design-
|
|
137
|
-
| `aitk:claude-review` | In a fresh session, review all changes since main
|
|
138
|
-
| `aitk:claude-pr-review` | Review an open PR from an independent session, then close the review out against the commits added since
|
|
139
|
-
| `aitk:claude-address-review` | Address PR findings and CI status, refresh stale docs, then push a follow-up
|
|
140
|
-
| `aitk:claude-tasks` | Add a task to `.claude/tasks/` or archive a shipped one out of the folder
|
|
141
|
-
| `aitk:claude-docs` | When decisions diverged from plan, update `.claude/` docs
|
|
142
|
-
| `aitk:claude-ui-test` | After UI changes, generate and run e2e tests + visual checklist
|
|
143
|
-
| `aitk:claude-ux-audit` | Audit existing UI surfaces for missing states, edge cases, inconsistencies
|
|
144
|
-
| `aitk:claude-autoship` | After plan approval, chain implement → verify → review → draft PR
|
|
145
|
-
| `aitk:systematic-debugging` | When a test fails or bug surfaces, enforce root-cause investigation before fixes
|
|
146
|
-
| `aitk:git-ship` | Post-feature: sync docs, commit, rename branch, open PR
|
|
129
|
+
| Skill | When to use |
|
|
130
|
+
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------- |
|
|
131
|
+
| `aitk:claude-groundwork` | Before a plan is warranted, measure an unknown in a scratch folder under `.claude/.tmp/groundwork/` |
|
|
132
|
+
| `aitk:claude-feature` | Before implementation, scan for conflicts and ambiguities |
|
|
133
|
+
| `aitk:claude-roadmap` | Sequence MVP scope into ordered versions in `.claude/ROADMAP.md` |
|
|
134
|
+
| `aitk:claude-orchestrate` | Assert the orchestrator role, refill the ready queue, and dispatch the roadmap, feature, and review skills |
|
|
135
|
+
| `aitk:claude-diagram` | Draft per-kind mermaid entries under `.claude/diagrams/` from architecture and code, then verify each rendered image |
|
|
136
|
+
| `aitk:claude-design-extract` | Draft `.claude/DESIGN.md`, sourcing tokens from existing UI code or proposing them from requirements on day one |
|
|
137
|
+
| `aitk:claude-review` | In a fresh session, review all changes since main |
|
|
138
|
+
| `aitk:claude-pr-review` | Review an open PR from an independent session, then close the review out against the commits added since |
|
|
139
|
+
| `aitk:claude-address-review` | Address PR findings and CI status, refresh stale docs, then push a follow-up |
|
|
140
|
+
| `aitk:claude-tasks` | Add a task to `.claude/tasks/` or archive a shipped one out of the folder |
|
|
141
|
+
| `aitk:claude-docs` | When decisions diverged from plan, update `.claude/` docs |
|
|
142
|
+
| `aitk:claude-ui-test` | After UI changes, generate and run e2e tests + visual checklist |
|
|
143
|
+
| `aitk:claude-ux-audit` | Audit existing UI surfaces for missing states, edge cases, inconsistencies |
|
|
144
|
+
| `aitk:claude-autoship` | After plan approval, chain implement → verify → review → draft PR |
|
|
145
|
+
| `aitk:systematic-debugging` | When a test fails or bug surfaces, enforce root-cause investigation before fixes |
|
|
146
|
+
| `aitk:git-ship` | Post-feature: sync docs, commit, rename branch, open PR |
|
|
147
147
|
|
|
148
148
|
## Feedback routing
|
|
149
149
|
|
package/docs/target-projects.md
CHANGED
|
@@ -56,7 +56,7 @@ Keep the `## Scripts` table in `.claude/context/development.md` current as scrip
|
|
|
56
56
|
Scaffold installs tooling and seeds. It does not fill the planning docs or the design system. Complete those before the first feature session:
|
|
57
57
|
|
|
58
58
|
1. Fill `.claude/REQUIREMENTS.md` and `.claude/ARCHITECTURE.md`. The seed provides the files, the scope and decisions are yours to write.
|
|
59
|
-
2. For a UI project, invoke `aitk:claude-design-
|
|
59
|
+
2. For a UI project, invoke `aitk:claude-design-extract` to draft `.claude/DESIGN.md`. With no UI code yet it takes the greenfield path and proposes tokens from the requirements and a `## Personality` section. Skip for non-UI projects.
|
|
60
60
|
3. Optionally invoke `aitk:claude-diagram` to draft entries under `.claude/diagrams/` from the architecture and the requirements. One file per diagram kind, so a later refresh of one kind leaves the others untouched. It renders each diagram it writes to verify the layout, which downloads the Mermaid CLI on first use and takes about 15 seconds. A machine without a renderer still gets the diagrams and is told which check was skipped. Each entry records the commit and date it was last verified against, and `aitk:claude-docs` maintains that record on every ship: it annotates an entry whose cited code path left the tree and stubs a kind whose source signal arrived uncovered. The sweep writes frontmatter only, so a diagram's picture and prose change when you redraw them and at no other time.
|
|
61
61
|
4. Start the feature loop. See [AI workflow](ai-workflow.md) for the per-feature sequence.
|
|
62
62
|
|
|
@@ -18,7 +18,7 @@ The default. `.claude/DESIGN.md` holds visual intent as prose plus token tables
|
|
|
18
18
|
|
|
19
19
|
### Seed shape
|
|
20
20
|
|
|
21
|
-
The toolkit seed in `tooling/claude/seeds/.claude/DESIGN.md` ships a token-table template. The `aitk:claude-design-extract` skill drafts the file from a project's existing prose and CLI UI surfaces. `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`.
|
|
21
|
+
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`.
|
|
22
22
|
|
|
23
23
|
### Tools
|
|
24
24
|
|
|
@@ -27,7 +27,7 @@ The toolkit seed in `tooling/claude/seeds/.claude/DESIGN.md` ships a token-table
|
|
|
27
27
|
|
|
28
28
|
### Skills
|
|
29
29
|
|
|
30
|
-
- `aitk:claude-design-extract` to draft `.claude/DESIGN.md
|
|
30
|
+
- `aitk:claude-design-extract` to draft `.claude/DESIGN.md`, from existing project signals or from requirements alone on day one
|
|
31
31
|
- `aitk:claude-ui-test` for e2e test generation after UI changes
|
|
32
32
|
- `aitk:claude-ux-audit` for UX gap detection on existing surfaces
|
|
33
33
|
- Anthropic's `frontend-design` plugin optional for light visual steering
|
package/package.json
CHANGED
package/standards/context.md
CHANGED
|
@@ -88,6 +88,8 @@ Only the `development` entry carries this section. It is not a general-purpose h
|
|
|
88
88
|
|
|
89
89
|
- Aim for one entry per domain. There is no hard cap. Length is a symptom, not the defect.
|
|
90
90
|
- Past roughly 150 lines, check two things before adding more: whether the entry still covers a single domain, and whether it has filled with content `ls` or `--help` reproduces. Fix whichever is true rather than trimming to hit a number.
|
|
91
|
+
- Past roughly 40 lines with no heading of any level breaking them, add a subheading at the seam. Measure the longest such run rather than everything under one `##`, and exclude fenced code blocks. The number is a checkpoint like the 150 above, not a cap.
|
|
92
|
+
- Exempt a block whose lines are all list items at one level. A long list of peers is already navigable, and a subheading dropped into it splits a set that belongs together. Mixing prose with the list, or nesting levels inside it, ends the exemption.
|
|
91
93
|
- Never cut a `## Decisions` or `## Gotchas` entry to shorten a file. Cut a `## Layout` or `## CLI` section instead.
|
|
92
94
|
- Split into a folder (`.claude/context/<domain>/<sub-area>.md`) when a domain has three or more sub-areas that do not fit cleanly in one file. That split is the natural ceiling.
|
|
93
95
|
- Keep a split domain's `index.md` generated. The catalog body is rewritten on every regen, so the domain's own overview and layout belong in a sibling file rather than in it, and the `subtitle` is what names the file to start with.
|