@hegemonart/get-design-done 1.57.3 → 1.58.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.
Files changed (19) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/.claude-plugin/plugin.json +1 -1
  3. package/CHANGELOG.md +39 -0
  4. package/hooks/gdd-intel-trigger.js +2 -2
  5. package/package.json +3 -2
  6. package/reference/DEPRECATIONS.md +18 -11
  7. package/reference/live-mode-integration.md +1 -1
  8. package/reference/registry.json +1 -1
  9. package/reference/skill-metadata.md +4 -4
  10. package/reference/skill-placeholders.md +2 -2
  11. package/scripts/lib/manifest/scaffolder.cjs +1 -1
  12. package/scripts/lib/manifest/schemas/skills.schema.json +1 -1
  13. package/scripts/lib/manifest/skills.json +1 -1
  14. package/scripts/lib/new-addendum.cjs +1 -1
  15. package/sdk/cli/commands/build.ts +2 -2
  16. package/sdk/cli/index.js +2 -2
  17. package/sdk/cli/index.ts +1 -1
  18. package/skills/README.md +55 -19
  19. package/skills/new-skill/SKILL.md +5 -5
package/.claude-plugin/marketplace.json CHANGED
@@ -5,14 +5,14 @@
5
5
  },
6
6
  "metadata": {
7
7
  "description": "Get Design Done — 5-stage agent-orchestrated design pipeline (Brief → Explore → Plan → Design → Verify) for AI coding agents. 61 agents, 94 skills, 42 connection integrations, two MCP servers, opt-in SQLite state backbone, bidirectional Figma write-back, and a reflector-driven self-improvement loop. Cross-runtime install for Claude Code, Codex, Cursor, OpenCode, Gemini, and more.",
8
- "version": "1.57.3"
8
+ "version": "1.58.0"
9
9
  },
10
10
  "plugins": [
11
11
  {
12
12
  "name": "get-design-done",
13
13
  "source": "./",
14
14
  "description": "Agent-orchestrated 5-stage design pipeline (Brief → Explore → Plan → Design → Verify) for AI coding agents. 61 specialized agents, 94 skills, 42 connection integrations (Figma, Refero, Preview, Storybook, Chromatic, Graphify, Linear, Jira, Notion, …), bidirectional Figma write-back, queryable intel store, opt-in SQLite state backbone, and a reflector-driven self-improvement loop. Two MCP servers (gdd-state for typed STATE mutators, gdd-mcp for 13 read-only project-priming tools), tier-aware routing with cost telemetry, and defense-in-depth hooks (protected paths, MCP circuit breaker, injection scanner, budget enforcer). Cross-runtime install for Claude Code, Codex, Cursor, OpenCode, Gemini, Copilot, and more.",
15
- "version": "1.57.3",
15
+ "version": "1.58.0",
16
16
  "author": {
17
17
  "name": "hegemonart"
18
18
  },
package/.claude-plugin/plugin.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "get-design-done",
3
3
  "short_name": "gdd",
4
- "version": "1.57.3",
4
+ "version": "1.58.0",
5
5
  "description": "Agent-orchestrated 5-stage design pipeline (Brief → Explore → Plan → Design → Verify) for AI coding agents. 61 specialized agents, 94 skills, 42 connection integrations (Figma, Refero, Preview, Storybook, Chromatic, Graphify, Linear, Jira, Notion, …), bidirectional Figma write-back, queryable intel store for O(1) design-surface lookups, opt-in SQLite state backbone, and a reflector-driven self-improvement loop. Two MCP servers (`gdd-state` for typed STATE mutators, `gdd-mcp` for 13 read-only project-priming tools), tier-aware agent routing with cost telemetry, defense-in-depth hooks (protected paths, MCP circuit breaker, injection scanner, budget enforcer), and a cross-runtime install layer for Claude Code, Codex, Cursor, OpenCode, Gemini, Copilot, and more.",
6
6
  "author": {
7
7
  "name": "hegemonart",
package/CHANGELOG.md CHANGED
@@ -4,6 +4,45 @@ All notable changes to get-design-done are documented here. Versions follow [sem
4
4
 
5
5
  ---
6
6
 
7
+ ## [1.58.0] - 2026-06-04
8
+
9
+ ### Architectural cleanup - kill the skills/ <-> source/skills/ duplication
10
+
11
+ Previous layout (Phase 42) committed BOTH the editable templates (`source/skills/`) AND the rendered Claude Code surface (`skills/`) - 232 tracked files for 116 distinct skills, identical content modulo a single `{{command_prefix}}` placeholder substitution. Pure git churn.
12
+
13
+ v1.58.0 makes `skill-templates/` (renamed from `source/skills/`; the gratuitous `source/` wrapper held only `skills/` and is gone) the single source of truth. `skills/` is gitignored and regenerated on demand. **End-user install experience is unchanged** - the npm tarball still ships `skills/` pre-built at the root; no build step runs on consumer machines.
14
+
15
+ 5,007/5,007 tests pass.
16
+
17
+ ### Breaking changes
18
+
19
+ - **For contributors only:** the editable skill source path moved from `source/skills/<slug>/SKILL.md` to `skill-templates/<slug>/SKILL.md`. Forks with in-flight edits under `source/skills/` should `git mv` their changes to `skill-templates/`. No runtime contract changes; no API changes; end users installing from npm see no behavior difference.
20
+
21
+ ### Changed
22
+
23
+ - **`source/skills/` -> `skill-templates/`** (renamed). The `source/` wrapper held only `skills/` inside and added nothing semantically. The new name is self-documenting.
24
+ - **`skills/` is now gitignored.** Regenerated automatically by two npm lifecycle hooks:
25
+ - `prepare` (runs on `npm install` from a fresh git clone, and again on `npm publish`) -> dev clones work immediately, no extra steps.
26
+ - `prepack` (chains `build:sdk` -> `build:skills`) -> the published tarball always contains a freshly-built `skills/`.
27
+ - **`build:skills:check` semantics flip** from "committed `skills/` matches source compile" to "compile is deterministic + on-disk `skills/` matches `skill-templates/`". Still catches manual edits to the build dir; no longer gates against a committed copy that doesn't need to exist.
28
+ - **`scripts/build-skills.cjs` writes progress to stderr** (was stdout). Required for `npm pack --json` to produce parseable JSON when `prepack` runs first.
29
+
30
+ ### Migration for contributors
31
+
32
+ Anyone editing skill content must now point at `skill-templates/<slug>/SKILL.md` instead of `source/skills/<slug>/SKILL.md`. After edits, `npm run build:skills` regenerates the local `skills/` (or just run `npm install`, which fires `prepare`). The CI `build:skills:check` gate catches any regression. End users running `npm install @hegemonart/get-design-done` see no change - the tarball contents are byte-identical to v1.57.3 for the same skill bodies.
33
+
34
+ ### Internal refactor scope
35
+
36
+ - ~40 test + script + reference files updated: `source/skills/` -> `skill-templates/`.
37
+ - `package.json#scripts` added `"prepare": "node scripts/build-skills.cjs"` + chained `prepack`.
38
+ - `.gitignore` adds `skills/`.
39
+ - `internal-refs.json` rebaselined (1749 -> 1682 hits; cleaner after removing duplicate path entries).
40
+ - `STYLE.md` regenerated.
41
+ - `reference/DEPRECATIONS.md` documents both the Phase 42 migration (`skills/` -> `source/skills/`) and the v1.58.0 follow-up (`source/skills/` -> `skill-templates/` + ungitignore).
42
+ - `skill-templates/README.md` rewritten as the single canonical source-of-truth doc.
43
+
44
+ ---
45
+
7
46
  ## [1.57.3] - 2026-06-04
8
47
 
9
48
  ### Polish residuals - closes remaining POLISH-PLAN items + dist/ deduplication
package/hooks/gdd-intel-trigger.js CHANGED
@@ -4,7 +4,7 @@
4
4
  * hooks/gdd-intel-trigger.js — D5 (PostToolUse on Edit|Write)
5
5
  *
6
6
  * On every Edit/Write that touches a design-authoritative surface
7
- * (skills/**, agents/**, reference/**, source/skills/**), spawn a
7
+ * (skills/**, agents/**, reference/**, skill-templates/**), spawn a
8
8
  * background, detached refresh of the .design/intel/ store so downstream
9
9
  * consumers (router, planner, audits) see the latest extracts without the
10
10
  * user paying for a full rebuild on the next /gdd run.
@@ -14,7 +14,7 @@
14
14
  * camelCase field names (tool_name/toolName, tool_input/toolInput,
15
15
  * file_path/filePath/path).
16
16
  * 2. If the edited path matches
17
- * ^(skills|agents|reference|source/skills)/.*\.(md|json)$
17
+ * ^(skills|agents|reference|skill-templates)/.*\.(md|json)$
18
18
  * (path-separator-agnostic), schedule a background refresh.
19
19
  * 3. Otherwise no-op — write {continue:true} and exit 0.
20
20
  * 4. Always exit 0. Never block. Never surface errors. Errors only ever
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hegemonart/get-design-done",
3
- "version": "1.57.3",
3
+ "version": "1.58.0",
4
4
  "description": "A design-quality pipeline for AI coding agents: brief, explore, plan, design, and verify UI work against your design system.",
5
5
  "author": "Hegemon",
6
6
  "homepage": "https://github.com/hegemonart/get-design-done",
@@ -55,7 +55,8 @@
55
55
  "generate:skill-frontmatter": "node scripts/generate-skill-frontmatter.cjs",
56
56
  "generate:skill-frontmatter:check": "node scripts/generate-skill-frontmatter.cjs --check",
57
57
  "build:sdk": "node scripts/build-sdk-bins.cjs",
58
- "prepack": "npm run build:sdk",
58
+ "prepare": "node scripts/build-skills.cjs",
59
+ "prepack": "npm run build:sdk && npm run build:skills",
59
60
  "postpack": "node scripts/build-sdk-bins.cjs --clean",
60
61
  "test": "node --test --experimental-strip-types \"test/suite/**/*.test.cjs\" \"test/suite/**/*.test.ts\"",
61
62
  "test:behavior": "node scripts/run-behavior-tests.cjs",
package/reference/DEPRECATIONS.md CHANGED
@@ -30,17 +30,24 @@ the scanner pattern list in lockstep.
30
30
 
31
31
  ## Authoring surfaces
32
32
 
33
- - **`skills/` as the authoring source** → **`source/skills/`** - deprecated in Phase 42 (multi-harness
34
- source compilation). Skills are now authored once in `source/skills/` with placeholders
35
- (`{{command_prefix}}` et al.; see `reference/skill-placeholders.md`) and compiled per-harness by
36
- `scripts/build-skills.cjs`. The committed `skills/` tree is now a **generated artifact** (the Claude-Code
37
- compile target) - CI's `npm run build:skills:check` drift-gates `committed === generated`.
38
-
39
- Migration for contributors: **edit `source/skills/`, never `skills/` directly**, then run
40
- `npm run build:skills` (or `gdd-sdk build skills`) and commit the regenerated `skills/` +
41
- `dist/claude-code/`. `.claude-plugin/plugin.json`'s `"skills": ["./skills/"]` is unchanged - the plugin
42
- still loads `skills/`, now produced from `source/skills/`. This is a path/authoring move only; no
43
- stale-ref token is emitted (both paths are live), so the `detect-stale-refs.cjs` list is not extended.
33
+ - **`skills/` as the authoring source** → **`source/skills/`** (Phase 42, deprecated)
34
+ → **`skill-templates/`** (v1.58.0, current). Two-step migration:
35
+
36
+ - **Phase 42** introduced multi-harness compilation. Skills moved to `source/skills/` with
37
+ placeholders (`{{command_prefix}}` et al.; see `reference/skill-placeholders.md`) and the
38
+ rendered `skills/` was kept committed as a "generated-but-tracked artifact". A drift gate
39
+ (`npm run build:skills:check`) verified `committed === generated`.
40
+ - **v1.58.0** removed the committed render. `source/skills/` was renamed to `skill-templates/`
41
+ (the `source/` wrapper held only `skills/` and added nothing), and `skills/` is now
42
+ gitignored - regenerated by the `prepare` lifecycle on `npm install` and packed into the
43
+ tarball via `prepack`. Net: 232 tracked files dropped to 116, with no change to end-user
44
+ install experience (the tarball still ships `skills/` pre-built).
45
+
46
+ Migration for contributors: **edit `skill-templates/`, never `skills/` directly**. After edits,
47
+ `npm run build:skills` regenerates `skills/` locally (or `npm install` does it automatically).
48
+ `.claude-plugin/plugin.json`'s `"skills": ["./skills/"]` is unchanged - the plugin still loads
49
+ `skills/`, now produced from `skill-templates/`. The `detect-stale-refs.cjs` list is extended to
50
+ emit warnings on lingering `source/skills/` path references.
44
51
 
45
52
  ## Scanner scope
46
53
 
package/reference/live-mode-integration.md CHANGED
@@ -9,7 +9,7 @@ last_updated: 2026-06-03
9
9
 
10
10
  # Live Mode Integration
11
11
 
12
- This file is the meta-rules companion to the `gdd-live` skill (`source/skills/live/SKILL.md`). It describes how `/gdd:live` turns a running dev server into a live design surface: the user picks a DOM element, the agent generates N variants in one batch, the variants hot-swap in place, the user accepts or discards, and the whole session persists. For the SKILL.md structural contract (line cap, description budget, frontmatter), see `./skill-authoring-contract.md`. The variants themselves are grounded in the Phase 45 domain indexes (`./spatial.md`, `./interaction.md`, `./color.md`, `./typography.md`, `./motion.md`).
12
+ This file is the meta-rules companion to the `gdd-live` skill (`skill-templates/live/SKILL.md`). It describes how `/gdd:live` turns a running dev server into a live design surface: the user picks a DOM element, the agent generates N variants in one batch, the variants hot-swap in place, the user accepts or discards, and the whole session persists. For the SKILL.md structural contract (line cap, description budget, frontmatter), see `./skill-authoring-contract.md`. The variants themselves are grounded in the Phase 45 domain indexes (`./spatial.md`, `./interaction.md`, `./color.md`, `./typography.md`, `./motion.md`).
13
13
 
14
14
  There is NO bundled browser automation. The skill drives the Claude Preview MCP at runtime; the modules under `scripts/lib/live/` are pure and dependency-free.
15
15
 
package/reference/registry.json CHANGED
@@ -1071,7 +1071,7 @@
1071
1071
  "path": "reference/skill-placeholders.md",
1072
1072
  "type": "meta-rules",
1073
1073
  "phase": 42,
1074
- "description": "Multi-harness skill-placeholder catalogue: the four placeholders ({{command_prefix}}/{{model}}/{{config_file}}/{{ask_instruction}}) + per-harness substitution table + the \\{{...}} escape + the <!-- harness-only: a,b --> block rule. Skills authored once in source/skills/, compiled per-harness by scripts/build-skills.cjs via scripts/lib/build/factory.cjs reading scripts/lib/manifest/harnesses.json."
1074
+ "description": "Multi-harness skill-placeholder catalogue: the four placeholders ({{command_prefix}}/{{model}}/{{config_file}}/{{ask_instruction}}) + per-harness substitution table + the \\{{...}} escape + the <!-- harness-only: a,b --> block rule. Skills authored once in skill-templates/, compiled per-harness by scripts/build-skills.cjs via scripts/lib/build/factory.cjs reading scripts/lib/manifest/harnesses.json."
1075
1075
  },
1076
1076
  {
1077
1077
  "name": "color",
package/reference/skill-metadata.md CHANGED
@@ -10,7 +10,7 @@ last_updated: 2026-06-02
10
10
  # Skill Metadata Single Source of Truth
11
11
 
12
12
  `scripts/lib/manifest/skills.json` is the one place skill frontmatter is authored. A
13
- generator projects it onto every `source/skills/<id>/SKILL.md`, the build step compiles
13
+ generator projects it onto every `skill-templates/<id>/SKILL.md`, the build step compiles
14
14
  those into the shipped trees, and CI gates keep the three copies identical. This doc
15
15
  explains the file, the generator, and the description budget. For the structural rules a
16
16
  SKILL.md body must follow (line cap, progressive disclosure, frontmatter required fields),
@@ -20,7 +20,7 @@ see `./skill-authoring-contract.md`.
20
20
 
21
21
  The file is a JSON object: a `schema_version` integer and a `skills` array. Each array
22
22
  element is one skill record. Only `name` is required (it must equal the
23
- `source/skills/<id>/` directory name); every other field is optional and omitted when it
23
+ `skill-templates/<id>/` directory name); every other field is optional and omitted when it
24
24
  has no value.
25
25
 
26
26
  ```json
@@ -50,7 +50,7 @@ Metadata flows in one direction, and a `*:check` gate guards each hop:
50
50
  ```text
51
51
  skills.json
52
52
  -> generate-skill-frontmatter (npm run generate:skill-frontmatter)
53
- -> source/skills/<id>/SKILL.md
53
+ -> skill-templates/<id>/SKILL.md
54
54
  -> build:skills (npm run build:skills)
55
55
  -> skills/ + dist/claude-code/
56
56
  ```
@@ -64,7 +64,7 @@ skills.json
64
64
  - `--check`: the CI drift gate. It writes nothing and exits non-zero when any committed
65
65
  frontmatter differs from what the manifest would generate.
66
66
 
67
- `scripts/build-skills.cjs` then propagates `source/skills/` into the committed `skills/`
67
+ `scripts/build-skills.cjs` then propagates `skill-templates/` into the committed `skills/`
68
68
  tree and `dist/claude-code/`; its own check mode asserts that the built output equals the
69
69
  committed output. So the contract is: edit `skills.json`, regenerate, build. Never
70
70
  hand-edit a managed frontmatter line in `SKILL.md`, because the drift gate will fail.
package/reference/skill-placeholders.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Skill Placeholders - Multi-Harness Source Compilation
2
2
 
3
- > Phase 42. Skills are authored once in `source/skills/` with placeholders and compiled per-harness into
3
+ > Phase 42. Skills are authored once in `skill-templates/` with placeholders and compiled per-harness into
4
4
  > `dist/<bundle>/<config-dir>/skills/...` by `scripts/build-skills.cjs` (the pure transform lives in
5
5
  > `scripts/lib/build/factory.cjs`; the per-harness values in `scripts/lib/build/harness-configs.cjs`,
6
6
  > which reads the Phase 41.5 manifest root `scripts/lib/manifest/harnesses.json`). The Claude-Code
@@ -68,4 +68,4 @@ scope (a maintenance trap) - see the Phase 42 CONTEXT.
68
68
  ## Validation
69
69
 
70
70
  `test/suite/phase-42-placeholders.test.cjs` asserts that every placeholder actually used across
71
- `source/skills/` is documented in this file, and that `source/skills/` mirrors the `skills/` skill count.
71
+ `skill-templates/` is documented in this file, and that `skill-templates/` mirrors the `skills/` skill count.
package/scripts/lib/manifest/scaffolder.cjs CHANGED
@@ -3,7 +3,7 @@
3
3
  * scripts/lib/manifest/scaffolder.cjs — Phase 50 (Authoring Contract v3).
4
4
  *
5
5
  * Pure, dependency-free generator behind the `/gdd:new-skill` scaffolder skill.
6
- * The SKILL.md (source/skills/new-skill/SKILL.md) drives the interactive
6
+ * The SKILL.md (skill-templates/new-skill/SKILL.md) drives the interactive
7
7
  * prompts; this module is the deterministic core it (and the test suite) call.
8
8
  *
9
9
  * Exports:
package/scripts/lib/manifest/schemas/skills.schema.json CHANGED
@@ -25,7 +25,7 @@
25
25
  "name": {
26
26
  "type": "string",
27
27
  "minLength": 1,
28
- "description": "Skill id = source/skills/<name>/ directory name."
28
+ "description": "Skill id = skill-templates/<name>/ directory name."
29
29
  },
30
30
  "frontmatter_name": {
31
31
  "type": "string",
package/scripts/lib/manifest/skills.json CHANGED
@@ -312,7 +312,7 @@
312
312
  },
313
313
  {
314
314
  "name": "new-skill",
315
- "description": "Scaffolds a new Phase-28.5 + Phase-50-compliant skill: gathers a name, a multi-paragraph v3 description, a lifecycle stage, an allowed-tools list, and optional composes_with neighbours, then writes source/skills/<name>/SKILL.md from the pure generator. Use when adding a brand-new gdd skill and you want the frontmatter, length cap, and v3 description form correct from the first commit. Activates for requests involving authoring a skill, scaffolding a command, creating a new SKILL.md, or adding a slash command.",
315
+ "description": "Scaffolds a new Phase-28.5 + Phase-50-compliant skill: gathers a name, a multi-paragraph v3 description, a lifecycle stage, an allowed-tools list, and optional composes_with neighbours, then writes skill-templates/<name>/SKILL.md from the pure generator. Use when adding a brand-new gdd skill and you want the frontmatter, length cap, and v3 description form correct from the first commit. Activates for requests involving authoring a skill, scaffolding a command, creating a new SKILL.md, or adding a slash command.",
316
316
  "argument_hint": "<skill-name>",
317
317
  "tools": "Read, Write, Bash, AskUserQuestion",
318
318
  "user_invocable": true,
package/scripts/lib/new-addendum.cjs CHANGED
@@ -3,7 +3,7 @@
3
3
  * scripts/lib/new-addendum.cjs — Phase 54 (Composable Reference Addendums), REG-01.
4
4
  *
5
5
  * Pure, dependency-free generator behind the `/gdd:new-addendum <kind> <name>`
6
- * scaffolder skill (source/skills/new-addendum/SKILL.md). The SKILL.md drives
6
+ * scaffolder skill (skill-templates/new-addendum/SKILL.md). The SKILL.md drives
7
7
  * the prompts; this module is the deterministic core it (and the test suite)
8
8
  * call. Mirrors scripts/lib/manifest/scaffolder.cjs (the Phase 50 skill
9
9
  * scaffolder): same ReDoS-safe NAME_RE, same throw-on-invalid contract, same
package/sdk/cli/commands/build.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  // sdk/cli/commands/build.ts — Phase 42 (COMPILE-06).
2
2
  //
3
3
  // `gdd-sdk build skills [--harness <id>] [--zip] [--check]` — compile the per-harness skill bundles
4
- // from source/skills/ via the orchestrator scripts/build-skills.cjs. The orchestrator is a separate
4
+ // from skill-templates/ via the orchestrator scripts/build-skills.cjs. The orchestrator is a separate
5
5
  // dep-free CJS process (no bundling entanglement with the SDK); we resolve it relative to the package
6
6
  // root and spawn it, forwarding stdout/stderr.
7
7
  //
@@ -30,7 +30,7 @@ const BUILD_FLAGS: readonly FlagSpec[] = [
30
30
 
31
31
  export const BUILD_USAGE = `gdd-sdk build skills [flags]
32
32
 
33
- Compile per-harness skill bundles from source/skills/ into dist/<bundle>/ (and regenerate the
33
+ Compile per-harness skill bundles from skill-templates/ into dist/<bundle>/ (and regenerate the
34
34
  committed Claude-Code surface skills/). One source, N provider bundles.
35
35
 
36
36
  Flags:
package/sdk/cli/index.js CHANGED
@@ -9634,7 +9634,7 @@ var BUILD_FLAGS = [
9634
9634
  ];
9635
9635
  var BUILD_USAGE = `gdd-sdk build skills [flags]
9636
9636
 
9637
- Compile per-harness skill bundles from source/skills/ into dist/<bundle>/ (and regenerate the
9637
+ Compile per-harness skill bundles from skill-templates/ into dist/<bundle>/ (and regenerate the
9638
9638
  committed Claude-Code surface skills/). One source, N provider bundles.
9639
9639
 
9640
9640
  Flags:
@@ -9954,7 +9954,7 @@ Commands:
9954
9954
  query <op> Typed STATE.md read operations.
9955
9955
  audit Probe connections + dry-run verify.
9956
9956
  init Bootstrap a new project.
9957
- build skills Compile per-harness skill bundles from source/skills/.
9957
+ build skills Compile per-harness skill bundles from skill-templates/.
9958
9958
  dashboard Open the GDD dashboard (TUI; --web for the browser graph).
9959
9959
 
9960
9960
  Use 'gdd-sdk <command> -h' for command-specific flags.
package/sdk/cli/index.ts CHANGED
@@ -36,7 +36,7 @@ Commands:
36
36
  query <op> Typed STATE.md read operations.
37
37
  audit Probe connections + dry-run verify.
38
38
  init Bootstrap a new project.
39
- build skills Compile per-harness skill bundles from source/skills/.
39
+ build skills Compile per-harness skill bundles from skill-templates/.
40
40
  dashboard Open the GDD dashboard (TUI; --web for the browser graph).
41
41
 
42
42
  Use 'gdd-sdk <command> -h' for command-specific flags.
package/skills/README.md CHANGED
@@ -1,41 +1,76 @@
1
- # `source/skills/` - Canonical Skill BODY Source
1
+ # `skill-templates/` - Editable Skill Source (Single Source of Truth)
2
2
 
3
- This directory is the **canonical home for skill body content**. Every `SKILL.md` under
4
- `source/skills/<slug>/` is the editable truth: the per-skill prose, examples, procedure files,
5
- and any sibling docs (`*-procedure.md`, `*-rules.md`, emitters, etc.) live here.
3
+ This directory is the **only** place to edit skill content. Every `SKILL.md` and sibling
4
+ doc here is the editable truth - the per-skill prose, examples, procedure files
5
+ (`*-procedure.md`, `*-rules.md`, emitters, etc.) all live here.
6
6
 
7
- `skills/` (the sibling at the repo root) is a **built artifact**, regenerated from this directory
8
- by `npm run build:skills`. Do not hand-edit `skills/<slug>/SKILL.md` - your edit will be wiped on
9
- the next build and the CI drift gate (`build:skills:check`) will fail.
7
+ The user-facing `skills/` directory at the repo root is a **build artifact**, not source.
8
+ It's gitignored and regenerated automatically:
9
+
10
+ - on `npm install` (via the `prepare` lifecycle script) - so developer clones work immediately
11
+ - on `npm pack` / `npm publish` (via `prepack`) - so the published tarball ships pre-built skills
12
+
13
+ End users installing `@hegemonart/get-design-done` from the npm registry receive a tarball
14
+ with `skills/` already built; no build step runs on their machine.
15
+
16
+ ## Why two directories, not one
17
+
18
+ Claude Code reads `./skills/<slug>/SKILL.md` raw. If we kept `/gdd:` placeholders
19
+ in the file Claude reads, the literal text `/gdd:` would show up in the prompt.
20
+ So the editable templates need to live separately from the rendered output.
21
+
22
+ The previous layout (Phase 42) put templates under `source/skills/` AND committed the
23
+ rendered `skills/` alongside. That meant 232 tracked files for 116 distinct skills with
24
+ identical content modulo a single placeholder substitution. Pure git churn.
25
+
26
+ v1.58.0 fixes this: templates are tracked once at `skill-templates/`, the rendered output
27
+ is generated on demand.
10
28
 
11
29
  ## Source-of-truth split (what lives where)
12
30
 
13
31
  | Concern | Source of truth | How it reaches `skills/` |
14
32
  |---|---|---|
15
- | **Body content** (everything below the frontmatter) | `source/skills/<slug>/SKILL.md` | `scripts/build-skills.cjs` walks `source/skills/`, applies per-harness placeholder substitution, writes to `skills/` |
16
- | **Universal frontmatter** (`name`, `description`, `argument-hint`, `tools`, `user-invocable`, `disable-model-invocation`) | `scripts/lib/manifest/skills.json` | `scripts/generate-skill-frontmatter.cjs` writes the managed block into `source/skills/<slug>/SKILL.md`, then `build:skills` copies it onward |
17
- | **Non-managed frontmatter** (e.g. `color`, `model`, custom keys) | `source/skills/<slug>/SKILL.md` itself (preserved verbatim) | carried through both generators unchanged |
33
+ | **Body content** (everything below the frontmatter) | `skill-templates/<slug>/SKILL.md` | `scripts/build-skills.cjs` walks `skill-templates/`, applies per-harness placeholder substitution, writes to `skills/` |
34
+ | **Universal frontmatter** (`name`, `description`, `argument-hint`, `tools`, `user-invocable`, `disable-model-invocation`) | `scripts/lib/manifest/skills.json` | `scripts/generate-skill-frontmatter.cjs` writes the managed block into `skill-templates/<slug>/SKILL.md`, then `build:skills` copies it onward |
35
+ | **Non-managed frontmatter** (e.g. `color`, `model`, custom keys) | `skill-templates/<slug>/SKILL.md` itself (preserved verbatim) | carried through both generators unchanged |
18
36
 
19
- The forward direction is **`skills.json` -> `source/skills/` -> `skills/`**.
37
+ The forward direction is **`skills.json` -> `skill-templates/` -> `skills/`**.
20
38
  Treat that direction as canonical; the `--extract` mode of `generate-skill-frontmatter.cjs` exists
21
39
  only to seed the manifest from current sources when reconciling drift.
22
40
 
23
41
  ## Editing protocol
24
42
 
25
- 1. **Edit body** -> modify `source/skills/<slug>/SKILL.md` (anything below the frontmatter delimiter).
43
+ 1. **Edit body** -> modify `skill-templates/<slug>/SKILL.md` (anything below the frontmatter delimiter).
26
44
  2. **Edit universal frontmatter** -> modify `scripts/lib/manifest/skills.json`, then run
27
45
  `npm run generate:skill-frontmatter`.
28
- 3. **Edit non-managed frontmatter** -> modify `source/skills/<slug>/SKILL.md` directly; the generator
46
+ 3. **Edit non-managed frontmatter** -> modify `skill-templates/<slug>/SKILL.md` directly; the generator
29
47
  preserves it.
30
- 4. **Regenerate the built surface** -> `npm run build:skills`. This rewrites `skills/<slug>/SKILL.md`
31
- byte-for-byte.
32
- 5. **Verify no drift** -> `npm run build:skills:check` (CI gate) and `npm run generate:skill-frontmatter:check`.
48
+ 4. **Regenerate the built surface** -> `npm run build:skills`. This rewrites the gitignored
49
+ `skills/<slug>/SKILL.md` byte-for-byte from the templates.
50
+ 5. **Verify the build** -> `npm run build:skills:check` (CI gate) confirms compile determinism
51
+ and that the on-disk `skills/` matches what `skill-templates/` would generate.
52
+
53
+ ## Placeholders
54
+
55
+ Four substitution slots are supported by `scripts/lib/build/factory.cjs`:
56
+
57
+ - `/gdd:` - slash-command prefix (`/gdd:` for Claude, `/gdd-` for Codex, etc.)
58
+ - `your configured Claude model` - human-readable model phrase ("your configured Claude model", etc.)
59
+ - `.claude/settings.json` - per-harness config path (`.claude/settings.json`, `.codex/config.toml`, ...)
60
+ - `ask Claude Code` - "ask Claude Code", "ask Codex", etc.
61
+
62
+ Plus conditional blocks: `BODY` keeps
63
+ `BODY` only when the active harness id is in the listed set.
64
+
65
+ Escape with `{{ ... }}` to emit a literal `{{...}}` in the output (never substituted).
66
+
67
+ Full grammar + the per-harness substitution table: `reference/skill-placeholders.md`.
33
68
 
34
69
  ## What npm ships
35
70
 
36
- `package.json` `files` lists `skills/` (the built surface); `source/skills/` is repo-only and is
37
- **not** distributed via npm. Users running `npm install @hegemonart/get-design-done` get the
38
- compiled skills; only contributors editing this repo touch `source/skills/`.
71
+ `package.json` `files` lists `skills/` (the built surface); `skill-templates/` is repo-only and
72
+ is **not** distributed via npm. The `prepack` lifecycle runs `npm run build:skills` so the tarball
73
+ always contains a freshly-built `skills/`.
39
74
 
40
75
  ## Cross-references
41
76
 
@@ -44,3 +79,4 @@ compiled skills; only contributors editing this repo touch `source/skills/`.
44
79
  - `scripts/lib/manifest/README.md` - explains why `skills.json` is the universal-frontmatter SoT.
45
80
  - `scripts/generate-skill-frontmatter.cjs` - manifest -> source-frontmatter generator (with
46
81
  `--check` drift gate and `--extract` reverse mode).
82
+ - `reference/skill-placeholders.md` - placeholder grammar + per-harness substitution table.
package/skills/new-skill/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: gdd-new-skill
3
- description: "Scaffolds a new Phase-28.5 + Phase-50-compliant skill: gathers a name, a multi-paragraph v3 description, a lifecycle stage, an allowed-tools list, and optional composes_with neighbours, then writes source/skills/<name>/SKILL.md from the pure generator. Use when adding a brand-new gdd skill and you want the frontmatter, length cap, and v3 description form correct from the first commit. Activates for requests involving authoring a skill, scaffolding a command, creating a new SKILL.md, or adding a slash command."
3
+ description: "Scaffolds a new Phase-28.5 + Phase-50-compliant skill: gathers a name, a multi-paragraph v3 description, a lifecycle stage, an allowed-tools list, and optional composes_with neighbours, then writes skill-templates/<name>/SKILL.md from the pure generator. Use when adding a brand-new gdd skill and you want the frontmatter, length cap, and v3 description form correct from the first commit. Activates for requests involving authoring a skill, scaffolding a command, creating a new SKILL.md, or adding a slash command."
4
4
  argument-hint: "<skill-name>"
5
5
  tools: Read, Write, Bash, AskUserQuestion
6
6
  user-invocable: true
@@ -8,7 +8,7 @@ user-invocable: true
8
8
 
9
9
  # /gdd:new-skill
10
10
 
11
- **Role:** Interactively scaffold a contract-compliant skill. Gather the fields, then write `source/skills/<name>/SKILL.md` from the pure generator at `scripts/lib/manifest/scaffolder.cjs`. This skill writes ONE source file. It does NOT touch `scripts/lib/manifest/skills.json` and does NOT run the build; it prints the exact follow-up commands instead.
11
+ **Role:** Interactively scaffold a contract-compliant skill. Gather the fields, then write `skill-templates/<name>/SKILL.md` from the pure generator at `scripts/lib/manifest/scaffolder.cjs`. This skill writes ONE source file. It does NOT touch `scripts/lib/manifest/skills.json` and does NOT run the build; it prints the exact follow-up commands instead.
12
12
 
13
13
  Read `reference/skill-authoring-contract.md` first for the length cap, the frontmatter required fields, and the v3 description form.
14
14
 
@@ -27,7 +27,7 @@ Either way the answers feed the same record builder. Never block waiting on a TT
27
27
 
28
28
  ## Step 1 - Gather the fields
29
29
 
30
- 1. **name**: the slug from `$ARGUMENTS` if present, else ask. Must match `^[a-z0-9][a-z0-9-._]*$`. Reject `source/skills/<name>/` collisions.
30
+ 1. **name**: the slug from `$ARGUMENTS` if present, else ask. Must match `^[a-z0-9][a-z0-9-._]*$`. Reject `skill-templates/<name>/` collisions.
31
31
  2. **description**: a multi-paragraph v3 form. Sentence one is what the skill does. Sentence two is `Use when <triggers>`. Sentence three is `Activates for requests involving <kw1>, <kw2>, <kw3>.` Keep it 20 to 1024 chars.
32
32
  3. **lifecycle stage**: pick one of brief / explore / plan / verify / ship / figma / token / report (free text allowed). This seeds the composition suggestions.
33
33
  4. **tools**: a comma list (for example `Read, Write, Bash`). Empty means inherit-all.
@@ -45,7 +45,7 @@ Present the suggestions; let the user accept, edit, or clear them.
45
45
 
46
46
  ## Step 2 - Length pre-check
47
47
 
48
- Before writing, estimate the body length. If the planned body would exceed about 100 lines, warn the user (the authoring contract warns at 100 and blocks at 250) and suggest extracting domain content into a co-located `source/skills/<name>/<topic>.md` reference. The generated skeleton is small; the warning is for the prose the user will add next.
48
+ Before writing, estimate the body length. If the planned body would exceed about 100 lines, warn the user (the authoring contract warns at 100 and blocks at 250) and suggest extracting domain content into a co-located `skill-templates/<name>/<topic>.md` reference. The generated skeleton is small; the warning is for the prose the user will add next.
49
49
 
50
50
  ## Step 3 - Write the file
51
51
 
@@ -66,7 +66,7 @@ process.stdout.write(s.renderSkillMd(rec));
66
66
  "
67
67
  ```
68
68
 
69
- `buildSkillRecord` throws on an invalid name, an out-of-budget description, or a malformed tools list. Surface the thrown message to the user and re-prompt the offending field. Capture stdout and write it verbatim to `source/skills/<name>/SKILL.md` via the Write tool.
69
+ `buildSkillRecord` throws on an invalid name, an out-of-budget description, or a malformed tools list. Surface the thrown message to the user and re-prompt the offending field. Capture stdout and write it verbatim to `skill-templates/<name>/SKILL.md` via the Write tool.
70
70
 
71
71
  ## Step 4 - Tell the user the follow-up
72
72