diff --git a/.agents/skills/impeccable/SKILL.md b/.agents/skills/impeccable/SKILL.md index 970bc2e1c..16173c6c2 100644 --- a/.agents/skills/impeccable/SKILL.md +++ b/.agents/skills/impeccable/SKILL.md @@ -23,55 +23,28 @@ After running the script, delete this entire section (from `200 chars, no `[TODO]` placeholders): - - If `hasDesign: true`: proceed. You have full context. - - If `hasDesign: false`: do a one-line nudge to the user (say it once per session): *"Note: no DESIGN.md found. I'll use impeccable's built-in design principles. For more on-brand output, run `$impeccable document` to generate a DESIGN.md from your existing code."* Then proceed. -- **`hasProduct: false`** OR the file exists but is empty / full of `[TODO]` placeholders: - 1. Tell the user: *"I need PRODUCT.md before I can do this well. Running `$impeccable teach` now — I'll resume `[original task]` after."* - 2. Run `$impeccable teach`. - 3. When teach completes, re-run `load-context.mjs` and resume the **original** task the user asked for. Do not silently abandon intent. +**If PRODUCT.md is missing or empty:** run `$impeccable teach`, then resume the user's original task with the fresh context. -### Exceptions (commands that skip or reshape the protocol) +**If DESIGN.md is missing:** nudge once per session (*"Run `$impeccable document` for more on-brand output"*), then proceed. -- **`$impeccable teach`**: skips this protocol entirely — teach is how PRODUCT.md (and optionally DESIGN.md) get CREATED. Don't try to load before you create. -- **`$impeccable document`**: load PRODUCT.md (voice input) but do NOT block on missing DESIGN.md — document is how DESIGN.md gets created. -- **`$impeccable live`**: `live.mjs` already invokes the loader internally and returns both files in its startup JSON. When you've run `live.mjs`, the context is warmed. Do NOT additionally run `load-context.mjs` in the same session. - -### Why this matters - -- **Generic output is the #1 failure mode** of impeccable without PRODUCT.md. The user asked for polish and got a stock-looking polish because Claude had no tone to polish toward. -- **Warmed live sessions feel instant** because when the user finally clicks Generate in the browser, Claude already has PRODUCT + DESIGN in context and proceeds straight to variant generation. -- **Token-efficient sessions** let the user run `$impeccable polish`, then `$impeccable audit`, then `$impeccable layout` without re-reading context files three times. +Full protocol (session cache rules, exceptions for teach/document/live, dispatch tree, migration): [reference/context.md](reference/context.md). --- @@ -210,11 +183,9 @@ Create visual rhythm through varied spacing, not the same padding everywhere. Em Always apply these — do not consult a reference, just do them: -- Use a 4pt spacing scale with semantic token names (`--space-sm`, `--space-md`), not pixel-named (`--spacing-8`). Scale: 4, 8, 12, 16, 24, 32, 48, 64, 96. 8pt is too coarse — you'll often want 12px between two values. -- Use `gap` instead of margins for sibling spacing. It eliminates margin collapse and the cleanup hacks that come with it. -- Vary spacing for hierarchy. A heading with extra space above it reads as more important — make use of that. Don't apply the same padding everywhere. +- Vary spacing for hierarchy. A heading with extra space above it reads as more important. Don't apply the same padding everywhere. +- Use a semantic spacing scale (`--space-sm`, `--space-md`), not pixel-named (`--spacing-8`). - Self-adjusting grid pattern: `grid-template-columns: repeat(auto-fit, minmax(280px, 1fr))` is the breakpoint-free responsive grid for card-style content. -- Container queries are for components, viewport queries are for page layout. A card in a sidebar should adapt to the sidebar's width, not the viewport's. @@ -403,15 +374,8 @@ When a sub-command is matched, load the linked reference and follow its instruct ## Pin / Unpin -If this skill is invoked with `pin ` or `unpin `: - -**pin** creates a lightweight standalone skill so you can invoke the command directly (e.g., `$audit` instead of `$impeccable audit`). - -**unpin** removes a previously pinned shortcut. - -Run: +For `pin ` or `unpin `, run: ```bash node .agents/skills/impeccable/scripts/pin.mjs ``` - -Report what the script did. If it succeeded, confirm the new shortcut is available (for pin) or removed (for unpin). \ No newline at end of file +Full details (what pin/unpin does, valid commands, cross-harness behavior): [reference/pin.md](reference/pin.md). \ No newline at end of file diff --git a/.agents/skills/impeccable/reference/colorize.md b/.agents/skills/impeccable/reference/colorize.md index a4ce5072e..bb94be480 100644 --- a/.agents/skills/impeccable/reference/colorize.md +++ b/.agents/skills/impeccable/reference/colorize.md @@ -74,10 +74,13 @@ Add color systematically across these dimensions: - **Comparison**: Color coding for different datasets or timeframes ### Borders & Accents -- **Accent borders**: Add colored left/top borders to cards or sections +- **Hairline borders**: 1px colored borders on full perimeter (not side-stripes — see the absolute ban on `border-left/right > 1px`) - **Underlines**: Color underlines for emphasis or active states - **Dividers**: Subtle colored dividers instead of gray lines - **Focus rings**: Colored focus indicators matching brand +- **Surface tints**: A 4-8% background wash of the accent color instead of a stripe + +**NEVER**: `border-left` or `border-right` greater than 1px as a colored accent stripe. This is one of the three absolute bans in the parent skill. If you want to mark a card as "active" or "warning", use a full hairline border, a background tint, a leading glyph, or a numbered prefix — not a side stripe. ### Typography Color - **Colored headings**: Use brand colors for section headings (maintain contrast) diff --git a/.agents/skills/impeccable/reference/context.md b/.agents/skills/impeccable/reference/context.md new file mode 100644 index 000000000..f1b6489e5 --- /dev/null +++ b/.agents/skills/impeccable/reference/context.md @@ -0,0 +1,52 @@ +# Context Gathering Protocol + +The full protocol that backs the brief rule in SKILL.md. Load this when you need the complete dispatch logic, exceptions, or cache semantics. + +## The two context files + +- **PRODUCT.md** (strategic, **required**): target users, product purpose, brand personality, anti-references, strategic design principles. Answers *who/what/why*. +- **DESIGN.md** (visual, **optional but strongly recommended**): follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/). Colors, typography, elevation, components, do's-and-don'ts. Answers *how it looks*. + +Filename matching is case-insensitive. Legacy `.impeccable.md` auto-migrates to `PRODUCT.md` on first load. **DESIGN.md wins on visual decisions; PRODUCT.md wins on strategic/voice decisions.** + +## The load command + +```bash +node {{scripts_path}}/load-context.mjs +``` + +Returns JSON with `hasProduct`, `product` (full contents), `hasDesign`, `design` (full contents), `migrated`. **Consume the full output. Never pipe through `head`, `tail`, `grep`, or `jq` with field filters** — you need the complete file contents to do your job. Token cost of the full load is ~2-20KB, far less than redoing work with missing context. + +## Session cache (critical for token economy) + +If PRODUCT.md content is already in your conversation history from an earlier tool call in this session, you already have it loaded. **Do NOT re-run `load-context.mjs`.** Same for DESIGN.md. Re-fetching wastes thousands of tokens across a multi-command session. + +Exceptions where you MUST re-load: +- You just ran `$impeccable teach` — PRODUCT.md was written or updated. +- You just ran `$impeccable document` — DESIGN.md was written or updated. +- The user says they've manually edited PRODUCT.md or DESIGN.md. + +## Dispatch on result + +**`hasProduct: true` AND content is substantive** (>200 chars, no `[TODO]` placeholders): +- If `hasDesign: true`: proceed. You have full context. +- If `hasDesign: false`: do a one-line nudge (say it once per session): + > *"Note: no DESIGN.md found. I'll use impeccable's built-in design principles. For more on-brand output, run `$impeccable document` to generate a DESIGN.md from your existing code."* + Then proceed. + +**`hasProduct: false`** OR file exists but is empty / full of `[TODO]` placeholders: +1. Tell the user: *"I need PRODUCT.md before I can do this well. Running `$impeccable teach` now — I'll resume `[original task]` after."* +2. Run `$impeccable teach`. +3. When teach completes, re-run `load-context.mjs` and resume the **original** task the user asked for. Do not silently abandon intent. + +## Exceptions (commands that skip or reshape the protocol) + +- **`$impeccable teach`**: skips this protocol entirely — teach is how PRODUCT.md (and optionally DESIGN.md) get CREATED. Don't try to load before you create. +- **`$impeccable document`**: load PRODUCT.md (voice input) but do NOT block on missing DESIGN.md — document is how DESIGN.md gets created. +- **`$impeccable live`**: `live.mjs` already invokes the loader internally and returns both files in its startup JSON. When you've run `live.mjs`, the context is warmed. Do NOT additionally run `load-context.mjs` in the same session. + +## Why this matters + +- **Generic output is the #1 failure mode** of impeccable without PRODUCT.md. The user asks for polish and gets a stock-looking polish because the agent has no tone to polish toward. +- **Warmed live sessions feel instant** because when the user finally clicks Generate in the browser, the agent already has PRODUCT + DESIGN in context and proceeds straight to variant generation. +- **Token-efficient sessions** let the user run `$impeccable polish`, then `$impeccable audit`, then `$impeccable layout` without re-reading context files three times. diff --git a/.agents/skills/impeccable/reference/pin.md b/.agents/skills/impeccable/reference/pin.md new file mode 100644 index 000000000..d3828748e --- /dev/null +++ b/.agents/skills/impeccable/reference/pin.md @@ -0,0 +1,31 @@ +# Pin / Unpin + +Commands that create or remove standalone slash-command shortcuts for frequently-used sub-commands. + +## What it does + +**Pin** creates a lightweight standalone skill so `$` invokes `$impeccable ` directly. Example: `$impeccable pin audit` creates `$audit` as a shortcut for `$impeccable audit`. + +**Unpin** removes a previously pinned shortcut. + +The pinned skill is a thin redirect — it doesn't duplicate the sub-command reference, it just forwards to the impeccable router. + +## Usage + +```bash +node {{scripts_path}}/pin.mjs pin +node {{scripts_path}}/pin.mjs unpin +``` + +The script writes to every harness directory present in the project (`.claude/`, `.cursor/`, `.codex/`, `.agents/`, `.gemini/`, etc.) so pinned shortcuts work across every AI coding tool the user has installed. + +## Valid commands + +Any impeccable sub-command name is a valid pin target: `craft`, `shape`, `teach`, `document`, `extract`, `critique`, `audit`, `polish`, `bolder`, `quieter`, `distill`, `harden`, `onboard`, `animate`, `colorize`, `typeset`, `layout`, `delight`, `overdrive`, `clarify`, `adapt`, `optimize`, `live`. + +## Reporting back + +After running the script, report what happened: +- **Pin success**: confirm the new shortcut (e.g. *"Pinned. You can now use `$audit` as a shortcut for `$impeccable audit`."*). +- **Unpin success**: confirm removal. +- **Errors**: relay the script's stderr verbatim — usually the command name was invalid or the pin already/doesn't exist. diff --git a/.claude/skills/impeccable/SKILL.md b/.claude/skills/impeccable/SKILL.md index 7bf4675b9..e105a905f 100644 --- a/.claude/skills/impeccable/SKILL.md +++ b/.claude/skills/impeccable/SKILL.md @@ -29,55 +29,28 @@ After running the script, delete this entire section (from `200 chars, no `[TODO]` placeholders): - - If `hasDesign: true`: proceed. You have full context. - - If `hasDesign: false`: do a one-line nudge to the user (say it once per session): *"Note: no DESIGN.md found. I'll use impeccable's built-in design principles. For more on-brand output, run `/impeccable document` to generate a DESIGN.md from your existing code."* Then proceed. -- **`hasProduct: false`** OR the file exists but is empty / full of `[TODO]` placeholders: - 1. Tell the user: *"I need PRODUCT.md before I can do this well. Running `/impeccable teach` now — I'll resume `[original task]` after."* - 2. Run `/impeccable teach`. - 3. When teach completes, re-run `load-context.mjs` and resume the **original** task the user asked for. Do not silently abandon intent. +**If PRODUCT.md is missing or empty:** run `/impeccable teach`, then resume the user's original task with the fresh context. -### Exceptions (commands that skip or reshape the protocol) +**If DESIGN.md is missing:** nudge once per session (*"Run `/impeccable document` for more on-brand output"*), then proceed. -- **`/impeccable teach`**: skips this protocol entirely — teach is how PRODUCT.md (and optionally DESIGN.md) get CREATED. Don't try to load before you create. -- **`/impeccable document`**: load PRODUCT.md (voice input) but do NOT block on missing DESIGN.md — document is how DESIGN.md gets created. -- **`/impeccable live`**: `live.mjs` already invokes the loader internally and returns both files in its startup JSON. When you've run `live.mjs`, the context is warmed. Do NOT additionally run `load-context.mjs` in the same session. - -### Why this matters - -- **Generic output is the #1 failure mode** of impeccable without PRODUCT.md. The user asked for polish and got a stock-looking polish because Claude had no tone to polish toward. -- **Warmed live sessions feel instant** because when the user finally clicks Generate in the browser, Claude already has PRODUCT + DESIGN in context and proceeds straight to variant generation. -- **Token-efficient sessions** let the user run `/impeccable polish`, then `/impeccable audit`, then `/impeccable layout` without re-reading context files three times. +Full protocol (session cache rules, exceptions for teach/document/live, dispatch tree, migration): [reference/context.md](reference/context.md). --- @@ -216,11 +189,9 @@ Create visual rhythm through varied spacing, not the same padding everywhere. Em Always apply these — do not consult a reference, just do them: -- Use a 4pt spacing scale with semantic token names (`--space-sm`, `--space-md`), not pixel-named (`--spacing-8`). Scale: 4, 8, 12, 16, 24, 32, 48, 64, 96. 8pt is too coarse — you'll often want 12px between two values. -- Use `gap` instead of margins for sibling spacing. It eliminates margin collapse and the cleanup hacks that come with it. -- Vary spacing for hierarchy. A heading with extra space above it reads as more important — make use of that. Don't apply the same padding everywhere. +- Vary spacing for hierarchy. A heading with extra space above it reads as more important. Don't apply the same padding everywhere. +- Use a semantic spacing scale (`--space-sm`, `--space-md`), not pixel-named (`--spacing-8`). - Self-adjusting grid pattern: `grid-template-columns: repeat(auto-fit, minmax(280px, 1fr))` is the breakpoint-free responsive grid for card-style content. -- Container queries are for components, viewport queries are for page layout. A card in a sidebar should adapt to the sidebar's width, not the viewport's. @@ -409,15 +380,8 @@ When a sub-command is matched, load the linked reference and follow its instruct ## Pin / Unpin -If this skill is invoked with `pin ` or `unpin `: - -**pin** creates a lightweight standalone skill so you can invoke the command directly (e.g., `/audit` instead of `/impeccable audit`). - -**unpin** removes a previously pinned shortcut. - -Run: +For `pin ` or `unpin `, run: ```bash node .claude/skills/impeccable/scripts/pin.mjs ``` - -Report what the script did. If it succeeded, confirm the new shortcut is available (for pin) or removed (for unpin). \ No newline at end of file +Full details (what pin/unpin does, valid commands, cross-harness behavior): [reference/pin.md](reference/pin.md). \ No newline at end of file diff --git a/.claude/skills/impeccable/reference/colorize.md b/.claude/skills/impeccable/reference/colorize.md index 5cd4db209..1b6796b04 100644 --- a/.claude/skills/impeccable/reference/colorize.md +++ b/.claude/skills/impeccable/reference/colorize.md @@ -74,10 +74,13 @@ Add color systematically across these dimensions: - **Comparison**: Color coding for different datasets or timeframes ### Borders & Accents -- **Accent borders**: Add colored left/top borders to cards or sections +- **Hairline borders**: 1px colored borders on full perimeter (not side-stripes — see the absolute ban on `border-left/right > 1px`) - **Underlines**: Color underlines for emphasis or active states - **Dividers**: Subtle colored dividers instead of gray lines - **Focus rings**: Colored focus indicators matching brand +- **Surface tints**: A 4-8% background wash of the accent color instead of a stripe + +**NEVER**: `border-left` or `border-right` greater than 1px as a colored accent stripe. This is one of the three absolute bans in the parent skill. If you want to mark a card as "active" or "warning", use a full hairline border, a background tint, a leading glyph, or a numbered prefix — not a side stripe. ### Typography Color - **Colored headings**: Use brand colors for section headings (maintain contrast) diff --git a/.claude/skills/impeccable/reference/context.md b/.claude/skills/impeccable/reference/context.md new file mode 100644 index 000000000..6dbe33f59 --- /dev/null +++ b/.claude/skills/impeccable/reference/context.md @@ -0,0 +1,52 @@ +# Context Gathering Protocol + +The full protocol that backs the brief rule in SKILL.md. Load this when you need the complete dispatch logic, exceptions, or cache semantics. + +## The two context files + +- **PRODUCT.md** (strategic, **required**): target users, product purpose, brand personality, anti-references, strategic design principles. Answers *who/what/why*. +- **DESIGN.md** (visual, **optional but strongly recommended**): follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/). Colors, typography, elevation, components, do's-and-don'ts. Answers *how it looks*. + +Filename matching is case-insensitive. Legacy `.impeccable.md` auto-migrates to `PRODUCT.md` on first load. **DESIGN.md wins on visual decisions; PRODUCT.md wins on strategic/voice decisions.** + +## The load command + +```bash +node {{scripts_path}}/load-context.mjs +``` + +Returns JSON with `hasProduct`, `product` (full contents), `hasDesign`, `design` (full contents), `migrated`. **Consume the full output. Never pipe through `head`, `tail`, `grep`, or `jq` with field filters** — you need the complete file contents to do your job. Token cost of the full load is ~2-20KB, far less than redoing work with missing context. + +## Session cache (critical for token economy) + +If PRODUCT.md content is already in your conversation history from an earlier tool call in this session, you already have it loaded. **Do NOT re-run `load-context.mjs`.** Same for DESIGN.md. Re-fetching wastes thousands of tokens across a multi-command session. + +Exceptions where you MUST re-load: +- You just ran `/impeccable teach` — PRODUCT.md was written or updated. +- You just ran `/impeccable document` — DESIGN.md was written or updated. +- The user says they've manually edited PRODUCT.md or DESIGN.md. + +## Dispatch on result + +**`hasProduct: true` AND content is substantive** (>200 chars, no `[TODO]` placeholders): +- If `hasDesign: true`: proceed. You have full context. +- If `hasDesign: false`: do a one-line nudge (say it once per session): + > *"Note: no DESIGN.md found. I'll use impeccable's built-in design principles. For more on-brand output, run `/impeccable document` to generate a DESIGN.md from your existing code."* + Then proceed. + +**`hasProduct: false`** OR file exists but is empty / full of `[TODO]` placeholders: +1. Tell the user: *"I need PRODUCT.md before I can do this well. Running `/impeccable teach` now — I'll resume `[original task]` after."* +2. Run `/impeccable teach`. +3. When teach completes, re-run `load-context.mjs` and resume the **original** task the user asked for. Do not silently abandon intent. + +## Exceptions (commands that skip or reshape the protocol) + +- **`/impeccable teach`**: skips this protocol entirely — teach is how PRODUCT.md (and optionally DESIGN.md) get CREATED. Don't try to load before you create. +- **`/impeccable document`**: load PRODUCT.md (voice input) but do NOT block on missing DESIGN.md — document is how DESIGN.md gets created. +- **`/impeccable live`**: `live.mjs` already invokes the loader internally and returns both files in its startup JSON. When you've run `live.mjs`, the context is warmed. Do NOT additionally run `load-context.mjs` in the same session. + +## Why this matters + +- **Generic output is the #1 failure mode** of impeccable without PRODUCT.md. The user asks for polish and gets a stock-looking polish because the agent has no tone to polish toward. +- **Warmed live sessions feel instant** because when the user finally clicks Generate in the browser, the agent already has PRODUCT + DESIGN in context and proceeds straight to variant generation. +- **Token-efficient sessions** let the user run `/impeccable polish`, then `/impeccable audit`, then `/impeccable layout` without re-reading context files three times. diff --git a/.claude/skills/impeccable/reference/pin.md b/.claude/skills/impeccable/reference/pin.md new file mode 100644 index 000000000..81565d5fc --- /dev/null +++ b/.claude/skills/impeccable/reference/pin.md @@ -0,0 +1,31 @@ +# Pin / Unpin + +Commands that create or remove standalone slash-command shortcuts for frequently-used sub-commands. + +## What it does + +**Pin** creates a lightweight standalone skill so `/` invokes `/impeccable ` directly. Example: `/impeccable pin audit` creates `/audit` as a shortcut for `/impeccable audit`. + +**Unpin** removes a previously pinned shortcut. + +The pinned skill is a thin redirect — it doesn't duplicate the sub-command reference, it just forwards to the impeccable router. + +## Usage + +```bash +node {{scripts_path}}/pin.mjs pin +node {{scripts_path}}/pin.mjs unpin +``` + +The script writes to every harness directory present in the project (`.claude/`, `.cursor/`, `.codex/`, `.agents/`, `.gemini/`, etc.) so pinned shortcuts work across every AI coding tool the user has installed. + +## Valid commands + +Any impeccable sub-command name is a valid pin target: `craft`, `shape`, `teach`, `document`, `extract`, `critique`, `audit`, `polish`, `bolder`, `quieter`, `distill`, `harden`, `onboard`, `animate`, `colorize`, `typeset`, `layout`, `delight`, `overdrive`, `clarify`, `adapt`, `optimize`, `live`. + +## Reporting back + +After running the script, report what happened: +- **Pin success**: confirm the new shortcut (e.g. *"Pinned. You can now use `/audit` as a shortcut for `/impeccable audit`."*). +- **Unpin success**: confirm removal. +- **Errors**: relay the script's stderr verbatim — usually the command name was invalid or the pin already/doesn't exist. diff --git a/.cursor/skills/impeccable/SKILL.md b/.cursor/skills/impeccable/SKILL.md index 346d044c9..1f72fcd70 100644 --- a/.cursor/skills/impeccable/SKILL.md +++ b/.cursor/skills/impeccable/SKILL.md @@ -25,55 +25,28 @@ After running the script, delete this entire section (from `200 chars, no `[TODO]` placeholders): - - If `hasDesign: true`: proceed. You have full context. - - If `hasDesign: false`: do a one-line nudge to the user (say it once per session): *"Note: no DESIGN.md found. I'll use impeccable's built-in design principles. For more on-brand output, run `/impeccable document` to generate a DESIGN.md from your existing code."* Then proceed. -- **`hasProduct: false`** OR the file exists but is empty / full of `[TODO]` placeholders: - 1. Tell the user: *"I need PRODUCT.md before I can do this well. Running `/impeccable teach` now — I'll resume `[original task]` after."* - 2. Run `/impeccable teach`. - 3. When teach completes, re-run `load-context.mjs` and resume the **original** task the user asked for. Do not silently abandon intent. +**If PRODUCT.md is missing or empty:** run `/impeccable teach`, then resume the user's original task with the fresh context. -### Exceptions (commands that skip or reshape the protocol) +**If DESIGN.md is missing:** nudge once per session (*"Run `/impeccable document` for more on-brand output"*), then proceed. -- **`/impeccable teach`**: skips this protocol entirely — teach is how PRODUCT.md (and optionally DESIGN.md) get CREATED. Don't try to load before you create. -- **`/impeccable document`**: load PRODUCT.md (voice input) but do NOT block on missing DESIGN.md — document is how DESIGN.md gets created. -- **`/impeccable live`**: `live.mjs` already invokes the loader internally and returns both files in its startup JSON. When you've run `live.mjs`, the context is warmed. Do NOT additionally run `load-context.mjs` in the same session. - -### Why this matters - -- **Generic output is the #1 failure mode** of impeccable without PRODUCT.md. The user asked for polish and got a stock-looking polish because Claude had no tone to polish toward. -- **Warmed live sessions feel instant** because when the user finally clicks Generate in the browser, Claude already has PRODUCT + DESIGN in context and proceeds straight to variant generation. -- **Token-efficient sessions** let the user run `/impeccable polish`, then `/impeccable audit`, then `/impeccable layout` without re-reading context files three times. +Full protocol (session cache rules, exceptions for teach/document/live, dispatch tree, migration): [reference/context.md](reference/context.md). --- @@ -212,11 +185,9 @@ Create visual rhythm through varied spacing, not the same padding everywhere. Em Always apply these — do not consult a reference, just do them: -- Use a 4pt spacing scale with semantic token names (`--space-sm`, `--space-md`), not pixel-named (`--spacing-8`). Scale: 4, 8, 12, 16, 24, 32, 48, 64, 96. 8pt is too coarse — you'll often want 12px between two values. -- Use `gap` instead of margins for sibling spacing. It eliminates margin collapse and the cleanup hacks that come with it. -- Vary spacing for hierarchy. A heading with extra space above it reads as more important — make use of that. Don't apply the same padding everywhere. +- Vary spacing for hierarchy. A heading with extra space above it reads as more important. Don't apply the same padding everywhere. +- Use a semantic spacing scale (`--space-sm`, `--space-md`), not pixel-named (`--spacing-8`). - Self-adjusting grid pattern: `grid-template-columns: repeat(auto-fit, minmax(280px, 1fr))` is the breakpoint-free responsive grid for card-style content. -- Container queries are for components, viewport queries are for page layout. A card in a sidebar should adapt to the sidebar's width, not the viewport's. @@ -405,15 +376,8 @@ When a sub-command is matched, load the linked reference and follow its instruct ## Pin / Unpin -If this skill is invoked with `pin ` or `unpin `: - -**pin** creates a lightweight standalone skill so you can invoke the command directly (e.g., `/audit` instead of `/impeccable audit`). - -**unpin** removes a previously pinned shortcut. - -Run: +For `pin ` or `unpin `, run: ```bash node .cursor/skills/impeccable/scripts/pin.mjs ``` - -Report what the script did. If it succeeded, confirm the new shortcut is available (for pin) or removed (for unpin). \ No newline at end of file +Full details (what pin/unpin does, valid commands, cross-harness behavior): [reference/pin.md](reference/pin.md). \ No newline at end of file diff --git a/.cursor/skills/impeccable/reference/colorize.md b/.cursor/skills/impeccable/reference/colorize.md index a4ce5072e..bb94be480 100644 --- a/.cursor/skills/impeccable/reference/colorize.md +++ b/.cursor/skills/impeccable/reference/colorize.md @@ -74,10 +74,13 @@ Add color systematically across these dimensions: - **Comparison**: Color coding for different datasets or timeframes ### Borders & Accents -- **Accent borders**: Add colored left/top borders to cards or sections +- **Hairline borders**: 1px colored borders on full perimeter (not side-stripes — see the absolute ban on `border-left/right > 1px`) - **Underlines**: Color underlines for emphasis or active states - **Dividers**: Subtle colored dividers instead of gray lines - **Focus rings**: Colored focus indicators matching brand +- **Surface tints**: A 4-8% background wash of the accent color instead of a stripe + +**NEVER**: `border-left` or `border-right` greater than 1px as a colored accent stripe. This is one of the three absolute bans in the parent skill. If you want to mark a card as "active" or "warning", use a full hairline border, a background tint, a leading glyph, or a numbered prefix — not a side stripe. ### Typography Color - **Colored headings**: Use brand colors for section headings (maintain contrast) diff --git a/.cursor/skills/impeccable/reference/context.md b/.cursor/skills/impeccable/reference/context.md new file mode 100644 index 000000000..6dbe33f59 --- /dev/null +++ b/.cursor/skills/impeccable/reference/context.md @@ -0,0 +1,52 @@ +# Context Gathering Protocol + +The full protocol that backs the brief rule in SKILL.md. Load this when you need the complete dispatch logic, exceptions, or cache semantics. + +## The two context files + +- **PRODUCT.md** (strategic, **required**): target users, product purpose, brand personality, anti-references, strategic design principles. Answers *who/what/why*. +- **DESIGN.md** (visual, **optional but strongly recommended**): follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/). Colors, typography, elevation, components, do's-and-don'ts. Answers *how it looks*. + +Filename matching is case-insensitive. Legacy `.impeccable.md` auto-migrates to `PRODUCT.md` on first load. **DESIGN.md wins on visual decisions; PRODUCT.md wins on strategic/voice decisions.** + +## The load command + +```bash +node {{scripts_path}}/load-context.mjs +``` + +Returns JSON with `hasProduct`, `product` (full contents), `hasDesign`, `design` (full contents), `migrated`. **Consume the full output. Never pipe through `head`, `tail`, `grep`, or `jq` with field filters** — you need the complete file contents to do your job. Token cost of the full load is ~2-20KB, far less than redoing work with missing context. + +## Session cache (critical for token economy) + +If PRODUCT.md content is already in your conversation history from an earlier tool call in this session, you already have it loaded. **Do NOT re-run `load-context.mjs`.** Same for DESIGN.md. Re-fetching wastes thousands of tokens across a multi-command session. + +Exceptions where you MUST re-load: +- You just ran `/impeccable teach` — PRODUCT.md was written or updated. +- You just ran `/impeccable document` — DESIGN.md was written or updated. +- The user says they've manually edited PRODUCT.md or DESIGN.md. + +## Dispatch on result + +**`hasProduct: true` AND content is substantive** (>200 chars, no `[TODO]` placeholders): +- If `hasDesign: true`: proceed. You have full context. +- If `hasDesign: false`: do a one-line nudge (say it once per session): + > *"Note: no DESIGN.md found. I'll use impeccable's built-in design principles. For more on-brand output, run `/impeccable document` to generate a DESIGN.md from your existing code."* + Then proceed. + +**`hasProduct: false`** OR file exists but is empty / full of `[TODO]` placeholders: +1. Tell the user: *"I need PRODUCT.md before I can do this well. Running `/impeccable teach` now — I'll resume `[original task]` after."* +2. Run `/impeccable teach`. +3. When teach completes, re-run `load-context.mjs` and resume the **original** task the user asked for. Do not silently abandon intent. + +## Exceptions (commands that skip or reshape the protocol) + +- **`/impeccable teach`**: skips this protocol entirely — teach is how PRODUCT.md (and optionally DESIGN.md) get CREATED. Don't try to load before you create. +- **`/impeccable document`**: load PRODUCT.md (voice input) but do NOT block on missing DESIGN.md — document is how DESIGN.md gets created. +- **`/impeccable live`**: `live.mjs` already invokes the loader internally and returns both files in its startup JSON. When you've run `live.mjs`, the context is warmed. Do NOT additionally run `load-context.mjs` in the same session. + +## Why this matters + +- **Generic output is the #1 failure mode** of impeccable without PRODUCT.md. The user asks for polish and gets a stock-looking polish because the agent has no tone to polish toward. +- **Warmed live sessions feel instant** because when the user finally clicks Generate in the browser, the agent already has PRODUCT + DESIGN in context and proceeds straight to variant generation. +- **Token-efficient sessions** let the user run `/impeccable polish`, then `/impeccable audit`, then `/impeccable layout` without re-reading context files three times. diff --git a/.cursor/skills/impeccable/reference/pin.md b/.cursor/skills/impeccable/reference/pin.md new file mode 100644 index 000000000..81565d5fc --- /dev/null +++ b/.cursor/skills/impeccable/reference/pin.md @@ -0,0 +1,31 @@ +# Pin / Unpin + +Commands that create or remove standalone slash-command shortcuts for frequently-used sub-commands. + +## What it does + +**Pin** creates a lightweight standalone skill so `/` invokes `/impeccable ` directly. Example: `/impeccable pin audit` creates `/audit` as a shortcut for `/impeccable audit`. + +**Unpin** removes a previously pinned shortcut. + +The pinned skill is a thin redirect — it doesn't duplicate the sub-command reference, it just forwards to the impeccable router. + +## Usage + +```bash +node {{scripts_path}}/pin.mjs pin +node {{scripts_path}}/pin.mjs unpin +``` + +The script writes to every harness directory present in the project (`.claude/`, `.cursor/`, `.codex/`, `.agents/`, `.gemini/`, etc.) so pinned shortcuts work across every AI coding tool the user has installed. + +## Valid commands + +Any impeccable sub-command name is a valid pin target: `craft`, `shape`, `teach`, `document`, `extract`, `critique`, `audit`, `polish`, `bolder`, `quieter`, `distill`, `harden`, `onboard`, `animate`, `colorize`, `typeset`, `layout`, `delight`, `overdrive`, `clarify`, `adapt`, `optimize`, `live`. + +## Reporting back + +After running the script, report what happened: +- **Pin success**: confirm the new shortcut (e.g. *"Pinned. You can now use `/audit` as a shortcut for `/impeccable audit`."*). +- **Unpin success**: confirm removal. +- **Errors**: relay the script's stderr verbatim — usually the command name was invalid or the pin already/doesn't exist. diff --git a/.gemini/skills/impeccable/SKILL.md b/.gemini/skills/impeccable/SKILL.md index c4395133d..e7a196306 100644 --- a/.gemini/skills/impeccable/SKILL.md +++ b/.gemini/skills/impeccable/SKILL.md @@ -24,55 +24,28 @@ After running the script, delete this entire section (from `200 chars, no `[TODO]` placeholders): - - If `hasDesign: true`: proceed. You have full context. - - If `hasDesign: false`: do a one-line nudge to the user (say it once per session): *"Note: no DESIGN.md found. I'll use impeccable's built-in design principles. For more on-brand output, run `/impeccable document` to generate a DESIGN.md from your existing code."* Then proceed. -- **`hasProduct: false`** OR the file exists but is empty / full of `[TODO]` placeholders: - 1. Tell the user: *"I need PRODUCT.md before I can do this well. Running `/impeccable teach` now — I'll resume `[original task]` after."* - 2. Run `/impeccable teach`. - 3. When teach completes, re-run `load-context.mjs` and resume the **original** task the user asked for. Do not silently abandon intent. +**If PRODUCT.md is missing or empty:** run `/impeccable teach`, then resume the user's original task with the fresh context. -### Exceptions (commands that skip or reshape the protocol) +**If DESIGN.md is missing:** nudge once per session (*"Run `/impeccable document` for more on-brand output"*), then proceed. -- **`/impeccable teach`**: skips this protocol entirely — teach is how PRODUCT.md (and optionally DESIGN.md) get CREATED. Don't try to load before you create. -- **`/impeccable document`**: load PRODUCT.md (voice input) but do NOT block on missing DESIGN.md — document is how DESIGN.md gets created. -- **`/impeccable live`**: `live.mjs` already invokes the loader internally and returns both files in its startup JSON. When you've run `live.mjs`, the context is warmed. Do NOT additionally run `load-context.mjs` in the same session. - -### Why this matters - -- **Generic output is the #1 failure mode** of impeccable without PRODUCT.md. The user asked for polish and got a stock-looking polish because Claude had no tone to polish toward. -- **Warmed live sessions feel instant** because when the user finally clicks Generate in the browser, Claude already has PRODUCT + DESIGN in context and proceeds straight to variant generation. -- **Token-efficient sessions** let the user run `/impeccable polish`, then `/impeccable audit`, then `/impeccable layout` without re-reading context files three times. +Full protocol (session cache rules, exceptions for teach/document/live, dispatch tree, migration): [reference/context.md](reference/context.md). --- @@ -211,11 +184,9 @@ Create visual rhythm through varied spacing, not the same padding everywhere. Em Always apply these — do not consult a reference, just do them: -- Use a 4pt spacing scale with semantic token names (`--space-sm`, `--space-md`), not pixel-named (`--spacing-8`). Scale: 4, 8, 12, 16, 24, 32, 48, 64, 96. 8pt is too coarse — you'll often want 12px between two values. -- Use `gap` instead of margins for sibling spacing. It eliminates margin collapse and the cleanup hacks that come with it. -- Vary spacing for hierarchy. A heading with extra space above it reads as more important — make use of that. Don't apply the same padding everywhere. +- Vary spacing for hierarchy. A heading with extra space above it reads as more important. Don't apply the same padding everywhere. +- Use a semantic spacing scale (`--space-sm`, `--space-md`), not pixel-named (`--spacing-8`). - Self-adjusting grid pattern: `grid-template-columns: repeat(auto-fit, minmax(280px, 1fr))` is the breakpoint-free responsive grid for card-style content. -- Container queries are for components, viewport queries are for page layout. A card in a sidebar should adapt to the sidebar's width, not the viewport's. @@ -404,15 +375,8 @@ When a sub-command is matched, load the linked reference and follow its instruct ## Pin / Unpin -If this skill is invoked with `pin ` or `unpin `: - -**pin** creates a lightweight standalone skill so you can invoke the command directly (e.g., `/audit` instead of `/impeccable audit`). - -**unpin** removes a previously pinned shortcut. - -Run: +For `pin ` or `unpin `, run: ```bash node .gemini/skills/impeccable/scripts/pin.mjs ``` - -Report what the script did. If it succeeded, confirm the new shortcut is available (for pin) or removed (for unpin). \ No newline at end of file +Full details (what pin/unpin does, valid commands, cross-harness behavior): [reference/pin.md](reference/pin.md). \ No newline at end of file diff --git a/.gemini/skills/impeccable/reference/colorize.md b/.gemini/skills/impeccable/reference/colorize.md index a4ce5072e..bb94be480 100644 --- a/.gemini/skills/impeccable/reference/colorize.md +++ b/.gemini/skills/impeccable/reference/colorize.md @@ -74,10 +74,13 @@ Add color systematically across these dimensions: - **Comparison**: Color coding for different datasets or timeframes ### Borders & Accents -- **Accent borders**: Add colored left/top borders to cards or sections +- **Hairline borders**: 1px colored borders on full perimeter (not side-stripes — see the absolute ban on `border-left/right > 1px`) - **Underlines**: Color underlines for emphasis or active states - **Dividers**: Subtle colored dividers instead of gray lines - **Focus rings**: Colored focus indicators matching brand +- **Surface tints**: A 4-8% background wash of the accent color instead of a stripe + +**NEVER**: `border-left` or `border-right` greater than 1px as a colored accent stripe. This is one of the three absolute bans in the parent skill. If you want to mark a card as "active" or "warning", use a full hairline border, a background tint, a leading glyph, or a numbered prefix — not a side stripe. ### Typography Color - **Colored headings**: Use brand colors for section headings (maintain contrast) diff --git a/.gemini/skills/impeccable/reference/context.md b/.gemini/skills/impeccable/reference/context.md new file mode 100644 index 000000000..6dbe33f59 --- /dev/null +++ b/.gemini/skills/impeccable/reference/context.md @@ -0,0 +1,52 @@ +# Context Gathering Protocol + +The full protocol that backs the brief rule in SKILL.md. Load this when you need the complete dispatch logic, exceptions, or cache semantics. + +## The two context files + +- **PRODUCT.md** (strategic, **required**): target users, product purpose, brand personality, anti-references, strategic design principles. Answers *who/what/why*. +- **DESIGN.md** (visual, **optional but strongly recommended**): follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/). Colors, typography, elevation, components, do's-and-don'ts. Answers *how it looks*. + +Filename matching is case-insensitive. Legacy `.impeccable.md` auto-migrates to `PRODUCT.md` on first load. **DESIGN.md wins on visual decisions; PRODUCT.md wins on strategic/voice decisions.** + +## The load command + +```bash +node {{scripts_path}}/load-context.mjs +``` + +Returns JSON with `hasProduct`, `product` (full contents), `hasDesign`, `design` (full contents), `migrated`. **Consume the full output. Never pipe through `head`, `tail`, `grep`, or `jq` with field filters** — you need the complete file contents to do your job. Token cost of the full load is ~2-20KB, far less than redoing work with missing context. + +## Session cache (critical for token economy) + +If PRODUCT.md content is already in your conversation history from an earlier tool call in this session, you already have it loaded. **Do NOT re-run `load-context.mjs`.** Same for DESIGN.md. Re-fetching wastes thousands of tokens across a multi-command session. + +Exceptions where you MUST re-load: +- You just ran `/impeccable teach` — PRODUCT.md was written or updated. +- You just ran `/impeccable document` — DESIGN.md was written or updated. +- The user says they've manually edited PRODUCT.md or DESIGN.md. + +## Dispatch on result + +**`hasProduct: true` AND content is substantive** (>200 chars, no `[TODO]` placeholders): +- If `hasDesign: true`: proceed. You have full context. +- If `hasDesign: false`: do a one-line nudge (say it once per session): + > *"Note: no DESIGN.md found. I'll use impeccable's built-in design principles. For more on-brand output, run `/impeccable document` to generate a DESIGN.md from your existing code."* + Then proceed. + +**`hasProduct: false`** OR file exists but is empty / full of `[TODO]` placeholders: +1. Tell the user: *"I need PRODUCT.md before I can do this well. Running `/impeccable teach` now — I'll resume `[original task]` after."* +2. Run `/impeccable teach`. +3. When teach completes, re-run `load-context.mjs` and resume the **original** task the user asked for. Do not silently abandon intent. + +## Exceptions (commands that skip or reshape the protocol) + +- **`/impeccable teach`**: skips this protocol entirely — teach is how PRODUCT.md (and optionally DESIGN.md) get CREATED. Don't try to load before you create. +- **`/impeccable document`**: load PRODUCT.md (voice input) but do NOT block on missing DESIGN.md — document is how DESIGN.md gets created. +- **`/impeccable live`**: `live.mjs` already invokes the loader internally and returns both files in its startup JSON. When you've run `live.mjs`, the context is warmed. Do NOT additionally run `load-context.mjs` in the same session. + +## Why this matters + +- **Generic output is the #1 failure mode** of impeccable without PRODUCT.md. The user asks for polish and gets a stock-looking polish because the agent has no tone to polish toward. +- **Warmed live sessions feel instant** because when the user finally clicks Generate in the browser, the agent already has PRODUCT + DESIGN in context and proceeds straight to variant generation. +- **Token-efficient sessions** let the user run `/impeccable polish`, then `/impeccable audit`, then `/impeccable layout` without re-reading context files three times. diff --git a/.gemini/skills/impeccable/reference/pin.md b/.gemini/skills/impeccable/reference/pin.md new file mode 100644 index 000000000..81565d5fc --- /dev/null +++ b/.gemini/skills/impeccable/reference/pin.md @@ -0,0 +1,31 @@ +# Pin / Unpin + +Commands that create or remove standalone slash-command shortcuts for frequently-used sub-commands. + +## What it does + +**Pin** creates a lightweight standalone skill so `/` invokes `/impeccable ` directly. Example: `/impeccable pin audit` creates `/audit` as a shortcut for `/impeccable audit`. + +**Unpin** removes a previously pinned shortcut. + +The pinned skill is a thin redirect — it doesn't duplicate the sub-command reference, it just forwards to the impeccable router. + +## Usage + +```bash +node {{scripts_path}}/pin.mjs pin +node {{scripts_path}}/pin.mjs unpin +``` + +The script writes to every harness directory present in the project (`.claude/`, `.cursor/`, `.codex/`, `.agents/`, `.gemini/`, etc.) so pinned shortcuts work across every AI coding tool the user has installed. + +## Valid commands + +Any impeccable sub-command name is a valid pin target: `craft`, `shape`, `teach`, `document`, `extract`, `critique`, `audit`, `polish`, `bolder`, `quieter`, `distill`, `harden`, `onboard`, `animate`, `colorize`, `typeset`, `layout`, `delight`, `overdrive`, `clarify`, `adapt`, `optimize`, `live`. + +## Reporting back + +After running the script, report what happened: +- **Pin success**: confirm the new shortcut (e.g. *"Pinned. You can now use `/audit` as a shortcut for `/impeccable audit`."*). +- **Unpin success**: confirm removal. +- **Errors**: relay the script's stderr verbatim — usually the command name was invalid or the pin already/doesn't exist. diff --git a/.github/skills/impeccable/SKILL.md b/.github/skills/impeccable/SKILL.md index 37c9f2946..e61278608 100644 --- a/.github/skills/impeccable/SKILL.md +++ b/.github/skills/impeccable/SKILL.md @@ -27,55 +27,28 @@ After running the script, delete this entire section (from `200 chars, no `[TODO]` placeholders): - - If `hasDesign: true`: proceed. You have full context. - - If `hasDesign: false`: do a one-line nudge to the user (say it once per session): *"Note: no DESIGN.md found. I'll use impeccable's built-in design principles. For more on-brand output, run `/impeccable document` to generate a DESIGN.md from your existing code."* Then proceed. -- **`hasProduct: false`** OR the file exists but is empty / full of `[TODO]` placeholders: - 1. Tell the user: *"I need PRODUCT.md before I can do this well. Running `/impeccable teach` now — I'll resume `[original task]` after."* - 2. Run `/impeccable teach`. - 3. When teach completes, re-run `load-context.mjs` and resume the **original** task the user asked for. Do not silently abandon intent. +**If PRODUCT.md is missing or empty:** run `/impeccable teach`, then resume the user's original task with the fresh context. -### Exceptions (commands that skip or reshape the protocol) +**If DESIGN.md is missing:** nudge once per session (*"Run `/impeccable document` for more on-brand output"*), then proceed. -- **`/impeccable teach`**: skips this protocol entirely — teach is how PRODUCT.md (and optionally DESIGN.md) get CREATED. Don't try to load before you create. -- **`/impeccable document`**: load PRODUCT.md (voice input) but do NOT block on missing DESIGN.md — document is how DESIGN.md gets created. -- **`/impeccable live`**: `live.mjs` already invokes the loader internally and returns both files in its startup JSON. When you've run `live.mjs`, the context is warmed. Do NOT additionally run `load-context.mjs` in the same session. - -### Why this matters - -- **Generic output is the #1 failure mode** of impeccable without PRODUCT.md. The user asked for polish and got a stock-looking polish because Claude had no tone to polish toward. -- **Warmed live sessions feel instant** because when the user finally clicks Generate in the browser, Claude already has PRODUCT + DESIGN in context and proceeds straight to variant generation. -- **Token-efficient sessions** let the user run `/impeccable polish`, then `/impeccable audit`, then `/impeccable layout` without re-reading context files three times. +Full protocol (session cache rules, exceptions for teach/document/live, dispatch tree, migration): [reference/context.md](reference/context.md). --- @@ -214,11 +187,9 @@ Create visual rhythm through varied spacing, not the same padding everywhere. Em Always apply these — do not consult a reference, just do them: -- Use a 4pt spacing scale with semantic token names (`--space-sm`, `--space-md`), not pixel-named (`--spacing-8`). Scale: 4, 8, 12, 16, 24, 32, 48, 64, 96. 8pt is too coarse — you'll often want 12px between two values. -- Use `gap` instead of margins for sibling spacing. It eliminates margin collapse and the cleanup hacks that come with it. -- Vary spacing for hierarchy. A heading with extra space above it reads as more important — make use of that. Don't apply the same padding everywhere. +- Vary spacing for hierarchy. A heading with extra space above it reads as more important. Don't apply the same padding everywhere. +- Use a semantic spacing scale (`--space-sm`, `--space-md`), not pixel-named (`--spacing-8`). - Self-adjusting grid pattern: `grid-template-columns: repeat(auto-fit, minmax(280px, 1fr))` is the breakpoint-free responsive grid for card-style content. -- Container queries are for components, viewport queries are for page layout. A card in a sidebar should adapt to the sidebar's width, not the viewport's. @@ -407,15 +378,8 @@ When a sub-command is matched, load the linked reference and follow its instruct ## Pin / Unpin -If this skill is invoked with `pin ` or `unpin `: - -**pin** creates a lightweight standalone skill so you can invoke the command directly (e.g., `/audit` instead of `/impeccable audit`). - -**unpin** removes a previously pinned shortcut. - -Run: +For `pin ` or `unpin `, run: ```bash node .github/skills/impeccable/scripts/pin.mjs ``` - -Report what the script did. If it succeeded, confirm the new shortcut is available (for pin) or removed (for unpin). \ No newline at end of file +Full details (what pin/unpin does, valid commands, cross-harness behavior): [reference/pin.md](reference/pin.md). \ No newline at end of file diff --git a/.github/skills/impeccable/reference/colorize.md b/.github/skills/impeccable/reference/colorize.md index a4ce5072e..bb94be480 100644 --- a/.github/skills/impeccable/reference/colorize.md +++ b/.github/skills/impeccable/reference/colorize.md @@ -74,10 +74,13 @@ Add color systematically across these dimensions: - **Comparison**: Color coding for different datasets or timeframes ### Borders & Accents -- **Accent borders**: Add colored left/top borders to cards or sections +- **Hairline borders**: 1px colored borders on full perimeter (not side-stripes — see the absolute ban on `border-left/right > 1px`) - **Underlines**: Color underlines for emphasis or active states - **Dividers**: Subtle colored dividers instead of gray lines - **Focus rings**: Colored focus indicators matching brand +- **Surface tints**: A 4-8% background wash of the accent color instead of a stripe + +**NEVER**: `border-left` or `border-right` greater than 1px as a colored accent stripe. This is one of the three absolute bans in the parent skill. If you want to mark a card as "active" or "warning", use a full hairline border, a background tint, a leading glyph, or a numbered prefix — not a side stripe. ### Typography Color - **Colored headings**: Use brand colors for section headings (maintain contrast) diff --git a/.github/skills/impeccable/reference/context.md b/.github/skills/impeccable/reference/context.md new file mode 100644 index 000000000..6dbe33f59 --- /dev/null +++ b/.github/skills/impeccable/reference/context.md @@ -0,0 +1,52 @@ +# Context Gathering Protocol + +The full protocol that backs the brief rule in SKILL.md. Load this when you need the complete dispatch logic, exceptions, or cache semantics. + +## The two context files + +- **PRODUCT.md** (strategic, **required**): target users, product purpose, brand personality, anti-references, strategic design principles. Answers *who/what/why*. +- **DESIGN.md** (visual, **optional but strongly recommended**): follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/). Colors, typography, elevation, components, do's-and-don'ts. Answers *how it looks*. + +Filename matching is case-insensitive. Legacy `.impeccable.md` auto-migrates to `PRODUCT.md` on first load. **DESIGN.md wins on visual decisions; PRODUCT.md wins on strategic/voice decisions.** + +## The load command + +```bash +node {{scripts_path}}/load-context.mjs +``` + +Returns JSON with `hasProduct`, `product` (full contents), `hasDesign`, `design` (full contents), `migrated`. **Consume the full output. Never pipe through `head`, `tail`, `grep`, or `jq` with field filters** — you need the complete file contents to do your job. Token cost of the full load is ~2-20KB, far less than redoing work with missing context. + +## Session cache (critical for token economy) + +If PRODUCT.md content is already in your conversation history from an earlier tool call in this session, you already have it loaded. **Do NOT re-run `load-context.mjs`.** Same for DESIGN.md. Re-fetching wastes thousands of tokens across a multi-command session. + +Exceptions where you MUST re-load: +- You just ran `/impeccable teach` — PRODUCT.md was written or updated. +- You just ran `/impeccable document` — DESIGN.md was written or updated. +- The user says they've manually edited PRODUCT.md or DESIGN.md. + +## Dispatch on result + +**`hasProduct: true` AND content is substantive** (>200 chars, no `[TODO]` placeholders): +- If `hasDesign: true`: proceed. You have full context. +- If `hasDesign: false`: do a one-line nudge (say it once per session): + > *"Note: no DESIGN.md found. I'll use impeccable's built-in design principles. For more on-brand output, run `/impeccable document` to generate a DESIGN.md from your existing code."* + Then proceed. + +**`hasProduct: false`** OR file exists but is empty / full of `[TODO]` placeholders: +1. Tell the user: *"I need PRODUCT.md before I can do this well. Running `/impeccable teach` now — I'll resume `[original task]` after."* +2. Run `/impeccable teach`. +3. When teach completes, re-run `load-context.mjs` and resume the **original** task the user asked for. Do not silently abandon intent. + +## Exceptions (commands that skip or reshape the protocol) + +- **`/impeccable teach`**: skips this protocol entirely — teach is how PRODUCT.md (and optionally DESIGN.md) get CREATED. Don't try to load before you create. +- **`/impeccable document`**: load PRODUCT.md (voice input) but do NOT block on missing DESIGN.md — document is how DESIGN.md gets created. +- **`/impeccable live`**: `live.mjs` already invokes the loader internally and returns both files in its startup JSON. When you've run `live.mjs`, the context is warmed. Do NOT additionally run `load-context.mjs` in the same session. + +## Why this matters + +- **Generic output is the #1 failure mode** of impeccable without PRODUCT.md. The user asks for polish and gets a stock-looking polish because the agent has no tone to polish toward. +- **Warmed live sessions feel instant** because when the user finally clicks Generate in the browser, the agent already has PRODUCT + DESIGN in context and proceeds straight to variant generation. +- **Token-efficient sessions** let the user run `/impeccable polish`, then `/impeccable audit`, then `/impeccable layout` without re-reading context files three times. diff --git a/.github/skills/impeccable/reference/pin.md b/.github/skills/impeccable/reference/pin.md new file mode 100644 index 000000000..81565d5fc --- /dev/null +++ b/.github/skills/impeccable/reference/pin.md @@ -0,0 +1,31 @@ +# Pin / Unpin + +Commands that create or remove standalone slash-command shortcuts for frequently-used sub-commands. + +## What it does + +**Pin** creates a lightweight standalone skill so `/` invokes `/impeccable ` directly. Example: `/impeccable pin audit` creates `/audit` as a shortcut for `/impeccable audit`. + +**Unpin** removes a previously pinned shortcut. + +The pinned skill is a thin redirect — it doesn't duplicate the sub-command reference, it just forwards to the impeccable router. + +## Usage + +```bash +node {{scripts_path}}/pin.mjs pin +node {{scripts_path}}/pin.mjs unpin +``` + +The script writes to every harness directory present in the project (`.claude/`, `.cursor/`, `.codex/`, `.agents/`, `.gemini/`, etc.) so pinned shortcuts work across every AI coding tool the user has installed. + +## Valid commands + +Any impeccable sub-command name is a valid pin target: `craft`, `shape`, `teach`, `document`, `extract`, `critique`, `audit`, `polish`, `bolder`, `quieter`, `distill`, `harden`, `onboard`, `animate`, `colorize`, `typeset`, `layout`, `delight`, `overdrive`, `clarify`, `adapt`, `optimize`, `live`. + +## Reporting back + +After running the script, report what happened: +- **Pin success**: confirm the new shortcut (e.g. *"Pinned. You can now use `/audit` as a shortcut for `/impeccable audit`."*). +- **Unpin success**: confirm removal. +- **Errors**: relay the script's stderr verbatim — usually the command name was invalid or the pin already/doesn't exist. diff --git a/.kiro/skills/impeccable/SKILL.md b/.kiro/skills/impeccable/SKILL.md index acfc8fa00..9d49d7365 100644 --- a/.kiro/skills/impeccable/SKILL.md +++ b/.kiro/skills/impeccable/SKILL.md @@ -25,55 +25,28 @@ After running the script, delete this entire section (from `200 chars, no `[TODO]` placeholders): - - If `hasDesign: true`: proceed. You have full context. - - If `hasDesign: false`: do a one-line nudge to the user (say it once per session): *"Note: no DESIGN.md found. I'll use impeccable's built-in design principles. For more on-brand output, run `/impeccable document` to generate a DESIGN.md from your existing code."* Then proceed. -- **`hasProduct: false`** OR the file exists but is empty / full of `[TODO]` placeholders: - 1. Tell the user: *"I need PRODUCT.md before I can do this well. Running `/impeccable teach` now — I'll resume `[original task]` after."* - 2. Run `/impeccable teach`. - 3. When teach completes, re-run `load-context.mjs` and resume the **original** task the user asked for. Do not silently abandon intent. +**If PRODUCT.md is missing or empty:** run `/impeccable teach`, then resume the user's original task with the fresh context. -### Exceptions (commands that skip or reshape the protocol) +**If DESIGN.md is missing:** nudge once per session (*"Run `/impeccable document` for more on-brand output"*), then proceed. -- **`/impeccable teach`**: skips this protocol entirely — teach is how PRODUCT.md (and optionally DESIGN.md) get CREATED. Don't try to load before you create. -- **`/impeccable document`**: load PRODUCT.md (voice input) but do NOT block on missing DESIGN.md — document is how DESIGN.md gets created. -- **`/impeccable live`**: `live.mjs` already invokes the loader internally and returns both files in its startup JSON. When you've run `live.mjs`, the context is warmed. Do NOT additionally run `load-context.mjs` in the same session. - -### Why this matters - -- **Generic output is the #1 failure mode** of impeccable without PRODUCT.md. The user asked for polish and got a stock-looking polish because Claude had no tone to polish toward. -- **Warmed live sessions feel instant** because when the user finally clicks Generate in the browser, Claude already has PRODUCT + DESIGN in context and proceeds straight to variant generation. -- **Token-efficient sessions** let the user run `/impeccable polish`, then `/impeccable audit`, then `/impeccable layout` without re-reading context files three times. +Full protocol (session cache rules, exceptions for teach/document/live, dispatch tree, migration): [reference/context.md](reference/context.md). --- @@ -212,11 +185,9 @@ Create visual rhythm through varied spacing, not the same padding everywhere. Em Always apply these — do not consult a reference, just do them: -- Use a 4pt spacing scale with semantic token names (`--space-sm`, `--space-md`), not pixel-named (`--spacing-8`). Scale: 4, 8, 12, 16, 24, 32, 48, 64, 96. 8pt is too coarse — you'll often want 12px between two values. -- Use `gap` instead of margins for sibling spacing. It eliminates margin collapse and the cleanup hacks that come with it. -- Vary spacing for hierarchy. A heading with extra space above it reads as more important — make use of that. Don't apply the same padding everywhere. +- Vary spacing for hierarchy. A heading with extra space above it reads as more important. Don't apply the same padding everywhere. +- Use a semantic spacing scale (`--space-sm`, `--space-md`), not pixel-named (`--spacing-8`). - Self-adjusting grid pattern: `grid-template-columns: repeat(auto-fit, minmax(280px, 1fr))` is the breakpoint-free responsive grid for card-style content. -- Container queries are for components, viewport queries are for page layout. A card in a sidebar should adapt to the sidebar's width, not the viewport's. @@ -405,15 +376,8 @@ When a sub-command is matched, load the linked reference and follow its instruct ## Pin / Unpin -If this skill is invoked with `pin ` or `unpin `: - -**pin** creates a lightweight standalone skill so you can invoke the command directly (e.g., `/audit` instead of `/impeccable audit`). - -**unpin** removes a previously pinned shortcut. - -Run: +For `pin ` or `unpin `, run: ```bash node .kiro/skills/impeccable/scripts/pin.mjs ``` - -Report what the script did. If it succeeded, confirm the new shortcut is available (for pin) or removed (for unpin). \ No newline at end of file +Full details (what pin/unpin does, valid commands, cross-harness behavior): [reference/pin.md](reference/pin.md). \ No newline at end of file diff --git a/.kiro/skills/impeccable/reference/colorize.md b/.kiro/skills/impeccable/reference/colorize.md index a4ce5072e..bb94be480 100644 --- a/.kiro/skills/impeccable/reference/colorize.md +++ b/.kiro/skills/impeccable/reference/colorize.md @@ -74,10 +74,13 @@ Add color systematically across these dimensions: - **Comparison**: Color coding for different datasets or timeframes ### Borders & Accents -- **Accent borders**: Add colored left/top borders to cards or sections +- **Hairline borders**: 1px colored borders on full perimeter (not side-stripes — see the absolute ban on `border-left/right > 1px`) - **Underlines**: Color underlines for emphasis or active states - **Dividers**: Subtle colored dividers instead of gray lines - **Focus rings**: Colored focus indicators matching brand +- **Surface tints**: A 4-8% background wash of the accent color instead of a stripe + +**NEVER**: `border-left` or `border-right` greater than 1px as a colored accent stripe. This is one of the three absolute bans in the parent skill. If you want to mark a card as "active" or "warning", use a full hairline border, a background tint, a leading glyph, or a numbered prefix — not a side stripe. ### Typography Color - **Colored headings**: Use brand colors for section headings (maintain contrast) diff --git a/.kiro/skills/impeccable/reference/context.md b/.kiro/skills/impeccable/reference/context.md new file mode 100644 index 000000000..6dbe33f59 --- /dev/null +++ b/.kiro/skills/impeccable/reference/context.md @@ -0,0 +1,52 @@ +# Context Gathering Protocol + +The full protocol that backs the brief rule in SKILL.md. Load this when you need the complete dispatch logic, exceptions, or cache semantics. + +## The two context files + +- **PRODUCT.md** (strategic, **required**): target users, product purpose, brand personality, anti-references, strategic design principles. Answers *who/what/why*. +- **DESIGN.md** (visual, **optional but strongly recommended**): follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/). Colors, typography, elevation, components, do's-and-don'ts. Answers *how it looks*. + +Filename matching is case-insensitive. Legacy `.impeccable.md` auto-migrates to `PRODUCT.md` on first load. **DESIGN.md wins on visual decisions; PRODUCT.md wins on strategic/voice decisions.** + +## The load command + +```bash +node {{scripts_path}}/load-context.mjs +``` + +Returns JSON with `hasProduct`, `product` (full contents), `hasDesign`, `design` (full contents), `migrated`. **Consume the full output. Never pipe through `head`, `tail`, `grep`, or `jq` with field filters** — you need the complete file contents to do your job. Token cost of the full load is ~2-20KB, far less than redoing work with missing context. + +## Session cache (critical for token economy) + +If PRODUCT.md content is already in your conversation history from an earlier tool call in this session, you already have it loaded. **Do NOT re-run `load-context.mjs`.** Same for DESIGN.md. Re-fetching wastes thousands of tokens across a multi-command session. + +Exceptions where you MUST re-load: +- You just ran `/impeccable teach` — PRODUCT.md was written or updated. +- You just ran `/impeccable document` — DESIGN.md was written or updated. +- The user says they've manually edited PRODUCT.md or DESIGN.md. + +## Dispatch on result + +**`hasProduct: true` AND content is substantive** (>200 chars, no `[TODO]` placeholders): +- If `hasDesign: true`: proceed. You have full context. +- If `hasDesign: false`: do a one-line nudge (say it once per session): + > *"Note: no DESIGN.md found. I'll use impeccable's built-in design principles. For more on-brand output, run `/impeccable document` to generate a DESIGN.md from your existing code."* + Then proceed. + +**`hasProduct: false`** OR file exists but is empty / full of `[TODO]` placeholders: +1. Tell the user: *"I need PRODUCT.md before I can do this well. Running `/impeccable teach` now — I'll resume `[original task]` after."* +2. Run `/impeccable teach`. +3. When teach completes, re-run `load-context.mjs` and resume the **original** task the user asked for. Do not silently abandon intent. + +## Exceptions (commands that skip or reshape the protocol) + +- **`/impeccable teach`**: skips this protocol entirely — teach is how PRODUCT.md (and optionally DESIGN.md) get CREATED. Don't try to load before you create. +- **`/impeccable document`**: load PRODUCT.md (voice input) but do NOT block on missing DESIGN.md — document is how DESIGN.md gets created. +- **`/impeccable live`**: `live.mjs` already invokes the loader internally and returns both files in its startup JSON. When you've run `live.mjs`, the context is warmed. Do NOT additionally run `load-context.mjs` in the same session. + +## Why this matters + +- **Generic output is the #1 failure mode** of impeccable without PRODUCT.md. The user asks for polish and gets a stock-looking polish because the agent has no tone to polish toward. +- **Warmed live sessions feel instant** because when the user finally clicks Generate in the browser, the agent already has PRODUCT + DESIGN in context and proceeds straight to variant generation. +- **Token-efficient sessions** let the user run `/impeccable polish`, then `/impeccable audit`, then `/impeccable layout` without re-reading context files three times. diff --git a/.kiro/skills/impeccable/reference/pin.md b/.kiro/skills/impeccable/reference/pin.md new file mode 100644 index 000000000..81565d5fc --- /dev/null +++ b/.kiro/skills/impeccable/reference/pin.md @@ -0,0 +1,31 @@ +# Pin / Unpin + +Commands that create or remove standalone slash-command shortcuts for frequently-used sub-commands. + +## What it does + +**Pin** creates a lightweight standalone skill so `/` invokes `/impeccable ` directly. Example: `/impeccable pin audit` creates `/audit` as a shortcut for `/impeccable audit`. + +**Unpin** removes a previously pinned shortcut. + +The pinned skill is a thin redirect — it doesn't duplicate the sub-command reference, it just forwards to the impeccable router. + +## Usage + +```bash +node {{scripts_path}}/pin.mjs pin +node {{scripts_path}}/pin.mjs unpin +``` + +The script writes to every harness directory present in the project (`.claude/`, `.cursor/`, `.codex/`, `.agents/`, `.gemini/`, etc.) so pinned shortcuts work across every AI coding tool the user has installed. + +## Valid commands + +Any impeccable sub-command name is a valid pin target: `craft`, `shape`, `teach`, `document`, `extract`, `critique`, `audit`, `polish`, `bolder`, `quieter`, `distill`, `harden`, `onboard`, `animate`, `colorize`, `typeset`, `layout`, `delight`, `overdrive`, `clarify`, `adapt`, `optimize`, `live`. + +## Reporting back + +After running the script, report what happened: +- **Pin success**: confirm the new shortcut (e.g. *"Pinned. You can now use `/audit` as a shortcut for `/impeccable audit`."*). +- **Unpin success**: confirm removal. +- **Errors**: relay the script's stderr verbatim — usually the command name was invalid or the pin already/doesn't exist. diff --git a/.opencode/skills/impeccable/SKILL.md b/.opencode/skills/impeccable/SKILL.md index 3c6c0f860..7912a048c 100644 --- a/.opencode/skills/impeccable/SKILL.md +++ b/.opencode/skills/impeccable/SKILL.md @@ -29,55 +29,28 @@ After running the script, delete this entire section (from `200 chars, no `[TODO]` placeholders): - - If `hasDesign: true`: proceed. You have full context. - - If `hasDesign: false`: do a one-line nudge to the user (say it once per session): *"Note: no DESIGN.md found. I'll use impeccable's built-in design principles. For more on-brand output, run `/impeccable document` to generate a DESIGN.md from your existing code."* Then proceed. -- **`hasProduct: false`** OR the file exists but is empty / full of `[TODO]` placeholders: - 1. Tell the user: *"I need PRODUCT.md before I can do this well. Running `/impeccable teach` now — I'll resume `[original task]` after."* - 2. Run `/impeccable teach`. - 3. When teach completes, re-run `load-context.mjs` and resume the **original** task the user asked for. Do not silently abandon intent. +**If PRODUCT.md is missing or empty:** run `/impeccable teach`, then resume the user's original task with the fresh context. -### Exceptions (commands that skip or reshape the protocol) +**If DESIGN.md is missing:** nudge once per session (*"Run `/impeccable document` for more on-brand output"*), then proceed. -- **`/impeccable teach`**: skips this protocol entirely — teach is how PRODUCT.md (and optionally DESIGN.md) get CREATED. Don't try to load before you create. -- **`/impeccable document`**: load PRODUCT.md (voice input) but do NOT block on missing DESIGN.md — document is how DESIGN.md gets created. -- **`/impeccable live`**: `live.mjs` already invokes the loader internally and returns both files in its startup JSON. When you've run `live.mjs`, the context is warmed. Do NOT additionally run `load-context.mjs` in the same session. - -### Why this matters - -- **Generic output is the #1 failure mode** of impeccable without PRODUCT.md. The user asked for polish and got a stock-looking polish because Claude had no tone to polish toward. -- **Warmed live sessions feel instant** because when the user finally clicks Generate in the browser, Claude already has PRODUCT + DESIGN in context and proceeds straight to variant generation. -- **Token-efficient sessions** let the user run `/impeccable polish`, then `/impeccable audit`, then `/impeccable layout` without re-reading context files three times. +Full protocol (session cache rules, exceptions for teach/document/live, dispatch tree, migration): [reference/context.md](reference/context.md). --- @@ -216,11 +189,9 @@ Create visual rhythm through varied spacing, not the same padding everywhere. Em Always apply these — do not consult a reference, just do them: -- Use a 4pt spacing scale with semantic token names (`--space-sm`, `--space-md`), not pixel-named (`--spacing-8`). Scale: 4, 8, 12, 16, 24, 32, 48, 64, 96. 8pt is too coarse — you'll often want 12px between two values. -- Use `gap` instead of margins for sibling spacing. It eliminates margin collapse and the cleanup hacks that come with it. -- Vary spacing for hierarchy. A heading with extra space above it reads as more important — make use of that. Don't apply the same padding everywhere. +- Vary spacing for hierarchy. A heading with extra space above it reads as more important. Don't apply the same padding everywhere. +- Use a semantic spacing scale (`--space-sm`, `--space-md`), not pixel-named (`--spacing-8`). - Self-adjusting grid pattern: `grid-template-columns: repeat(auto-fit, minmax(280px, 1fr))` is the breakpoint-free responsive grid for card-style content. -- Container queries are for components, viewport queries are for page layout. A card in a sidebar should adapt to the sidebar's width, not the viewport's. @@ -409,15 +380,8 @@ When a sub-command is matched, load the linked reference and follow its instruct ## Pin / Unpin -If this skill is invoked with `pin ` or `unpin `: - -**pin** creates a lightweight standalone skill so you can invoke the command directly (e.g., `/audit` instead of `/impeccable audit`). - -**unpin** removes a previously pinned shortcut. - -Run: +For `pin ` or `unpin `, run: ```bash node .opencode/skills/impeccable/scripts/pin.mjs ``` - -Report what the script did. If it succeeded, confirm the new shortcut is available (for pin) or removed (for unpin). \ No newline at end of file +Full details (what pin/unpin does, valid commands, cross-harness behavior): [reference/pin.md](reference/pin.md). \ No newline at end of file diff --git a/.opencode/skills/impeccable/reference/colorize.md b/.opencode/skills/impeccable/reference/colorize.md index 1a2ae7439..f05f4d7cb 100644 --- a/.opencode/skills/impeccable/reference/colorize.md +++ b/.opencode/skills/impeccable/reference/colorize.md @@ -74,10 +74,13 @@ Add color systematically across these dimensions: - **Comparison**: Color coding for different datasets or timeframes ### Borders & Accents -- **Accent borders**: Add colored left/top borders to cards or sections +- **Hairline borders**: 1px colored borders on full perimeter (not side-stripes — see the absolute ban on `border-left/right > 1px`) - **Underlines**: Color underlines for emphasis or active states - **Dividers**: Subtle colored dividers instead of gray lines - **Focus rings**: Colored focus indicators matching brand +- **Surface tints**: A 4-8% background wash of the accent color instead of a stripe + +**NEVER**: `border-left` or `border-right` greater than 1px as a colored accent stripe. This is one of the three absolute bans in the parent skill. If you want to mark a card as "active" or "warning", use a full hairline border, a background tint, a leading glyph, or a numbered prefix — not a side stripe. ### Typography Color - **Colored headings**: Use brand colors for section headings (maintain contrast) diff --git a/.opencode/skills/impeccable/reference/context.md b/.opencode/skills/impeccable/reference/context.md new file mode 100644 index 000000000..6dbe33f59 --- /dev/null +++ b/.opencode/skills/impeccable/reference/context.md @@ -0,0 +1,52 @@ +# Context Gathering Protocol + +The full protocol that backs the brief rule in SKILL.md. Load this when you need the complete dispatch logic, exceptions, or cache semantics. + +## The two context files + +- **PRODUCT.md** (strategic, **required**): target users, product purpose, brand personality, anti-references, strategic design principles. Answers *who/what/why*. +- **DESIGN.md** (visual, **optional but strongly recommended**): follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/). Colors, typography, elevation, components, do's-and-don'ts. Answers *how it looks*. + +Filename matching is case-insensitive. Legacy `.impeccable.md` auto-migrates to `PRODUCT.md` on first load. **DESIGN.md wins on visual decisions; PRODUCT.md wins on strategic/voice decisions.** + +## The load command + +```bash +node {{scripts_path}}/load-context.mjs +``` + +Returns JSON with `hasProduct`, `product` (full contents), `hasDesign`, `design` (full contents), `migrated`. **Consume the full output. Never pipe through `head`, `tail`, `grep`, or `jq` with field filters** — you need the complete file contents to do your job. Token cost of the full load is ~2-20KB, far less than redoing work with missing context. + +## Session cache (critical for token economy) + +If PRODUCT.md content is already in your conversation history from an earlier tool call in this session, you already have it loaded. **Do NOT re-run `load-context.mjs`.** Same for DESIGN.md. Re-fetching wastes thousands of tokens across a multi-command session. + +Exceptions where you MUST re-load: +- You just ran `/impeccable teach` — PRODUCT.md was written or updated. +- You just ran `/impeccable document` — DESIGN.md was written or updated. +- The user says they've manually edited PRODUCT.md or DESIGN.md. + +## Dispatch on result + +**`hasProduct: true` AND content is substantive** (>200 chars, no `[TODO]` placeholders): +- If `hasDesign: true`: proceed. You have full context. +- If `hasDesign: false`: do a one-line nudge (say it once per session): + > *"Note: no DESIGN.md found. I'll use impeccable's built-in design principles. For more on-brand output, run `/impeccable document` to generate a DESIGN.md from your existing code."* + Then proceed. + +**`hasProduct: false`** OR file exists but is empty / full of `[TODO]` placeholders: +1. Tell the user: *"I need PRODUCT.md before I can do this well. Running `/impeccable teach` now — I'll resume `[original task]` after."* +2. Run `/impeccable teach`. +3. When teach completes, re-run `load-context.mjs` and resume the **original** task the user asked for. Do not silently abandon intent. + +## Exceptions (commands that skip or reshape the protocol) + +- **`/impeccable teach`**: skips this protocol entirely — teach is how PRODUCT.md (and optionally DESIGN.md) get CREATED. Don't try to load before you create. +- **`/impeccable document`**: load PRODUCT.md (voice input) but do NOT block on missing DESIGN.md — document is how DESIGN.md gets created. +- **`/impeccable live`**: `live.mjs` already invokes the loader internally and returns both files in its startup JSON. When you've run `live.mjs`, the context is warmed. Do NOT additionally run `load-context.mjs` in the same session. + +## Why this matters + +- **Generic output is the #1 failure mode** of impeccable without PRODUCT.md. The user asks for polish and gets a stock-looking polish because the agent has no tone to polish toward. +- **Warmed live sessions feel instant** because when the user finally clicks Generate in the browser, the agent already has PRODUCT + DESIGN in context and proceeds straight to variant generation. +- **Token-efficient sessions** let the user run `/impeccable polish`, then `/impeccable audit`, then `/impeccable layout` without re-reading context files three times. diff --git a/.opencode/skills/impeccable/reference/pin.md b/.opencode/skills/impeccable/reference/pin.md new file mode 100644 index 000000000..81565d5fc --- /dev/null +++ b/.opencode/skills/impeccable/reference/pin.md @@ -0,0 +1,31 @@ +# Pin / Unpin + +Commands that create or remove standalone slash-command shortcuts for frequently-used sub-commands. + +## What it does + +**Pin** creates a lightweight standalone skill so `/` invokes `/impeccable ` directly. Example: `/impeccable pin audit` creates `/audit` as a shortcut for `/impeccable audit`. + +**Unpin** removes a previously pinned shortcut. + +The pinned skill is a thin redirect — it doesn't duplicate the sub-command reference, it just forwards to the impeccable router. + +## Usage + +```bash +node {{scripts_path}}/pin.mjs pin +node {{scripts_path}}/pin.mjs unpin +``` + +The script writes to every harness directory present in the project (`.claude/`, `.cursor/`, `.codex/`, `.agents/`, `.gemini/`, etc.) so pinned shortcuts work across every AI coding tool the user has installed. + +## Valid commands + +Any impeccable sub-command name is a valid pin target: `craft`, `shape`, `teach`, `document`, `extract`, `critique`, `audit`, `polish`, `bolder`, `quieter`, `distill`, `harden`, `onboard`, `animate`, `colorize`, `typeset`, `layout`, `delight`, `overdrive`, `clarify`, `adapt`, `optimize`, `live`. + +## Reporting back + +After running the script, report what happened: +- **Pin success**: confirm the new shortcut (e.g. *"Pinned. You can now use `/audit` as a shortcut for `/impeccable audit`."*). +- **Unpin success**: confirm removal. +- **Errors**: relay the script's stderr verbatim — usually the command name was invalid or the pin already/doesn't exist. diff --git a/.pi/skills/impeccable/SKILL.md b/.pi/skills/impeccable/SKILL.md index 15977d930..194403828 100644 --- a/.pi/skills/impeccable/SKILL.md +++ b/.pi/skills/impeccable/SKILL.md @@ -27,55 +27,28 @@ After running the script, delete this entire section (from `200 chars, no `[TODO]` placeholders): - - If `hasDesign: true`: proceed. You have full context. - - If `hasDesign: false`: do a one-line nudge to the user (say it once per session): *"Note: no DESIGN.md found. I'll use impeccable's built-in design principles. For more on-brand output, run `/impeccable document` to generate a DESIGN.md from your existing code."* Then proceed. -- **`hasProduct: false`** OR the file exists but is empty / full of `[TODO]` placeholders: - 1. Tell the user: *"I need PRODUCT.md before I can do this well. Running `/impeccable teach` now — I'll resume `[original task]` after."* - 2. Run `/impeccable teach`. - 3. When teach completes, re-run `load-context.mjs` and resume the **original** task the user asked for. Do not silently abandon intent. +**If PRODUCT.md is missing or empty:** run `/impeccable teach`, then resume the user's original task with the fresh context. -### Exceptions (commands that skip or reshape the protocol) +**If DESIGN.md is missing:** nudge once per session (*"Run `/impeccable document` for more on-brand output"*), then proceed. -- **`/impeccable teach`**: skips this protocol entirely — teach is how PRODUCT.md (and optionally DESIGN.md) get CREATED. Don't try to load before you create. -- **`/impeccable document`**: load PRODUCT.md (voice input) but do NOT block on missing DESIGN.md — document is how DESIGN.md gets created. -- **`/impeccable live`**: `live.mjs` already invokes the loader internally and returns both files in its startup JSON. When you've run `live.mjs`, the context is warmed. Do NOT additionally run `load-context.mjs` in the same session. - -### Why this matters - -- **Generic output is the #1 failure mode** of impeccable without PRODUCT.md. The user asked for polish and got a stock-looking polish because Claude had no tone to polish toward. -- **Warmed live sessions feel instant** because when the user finally clicks Generate in the browser, Claude already has PRODUCT + DESIGN in context and proceeds straight to variant generation. -- **Token-efficient sessions** let the user run `/impeccable polish`, then `/impeccable audit`, then `/impeccable layout` without re-reading context files three times. +Full protocol (session cache rules, exceptions for teach/document/live, dispatch tree, migration): [reference/context.md](reference/context.md). --- @@ -214,11 +187,9 @@ Create visual rhythm through varied spacing, not the same padding everywhere. Em Always apply these — do not consult a reference, just do them: -- Use a 4pt spacing scale with semantic token names (`--space-sm`, `--space-md`), not pixel-named (`--spacing-8`). Scale: 4, 8, 12, 16, 24, 32, 48, 64, 96. 8pt is too coarse — you'll often want 12px between two values. -- Use `gap` instead of margins for sibling spacing. It eliminates margin collapse and the cleanup hacks that come with it. -- Vary spacing for hierarchy. A heading with extra space above it reads as more important — make use of that. Don't apply the same padding everywhere. +- Vary spacing for hierarchy. A heading with extra space above it reads as more important. Don't apply the same padding everywhere. +- Use a semantic spacing scale (`--space-sm`, `--space-md`), not pixel-named (`--spacing-8`). - Self-adjusting grid pattern: `grid-template-columns: repeat(auto-fit, minmax(280px, 1fr))` is the breakpoint-free responsive grid for card-style content. -- Container queries are for components, viewport queries are for page layout. A card in a sidebar should adapt to the sidebar's width, not the viewport's. @@ -407,15 +378,8 @@ When a sub-command is matched, load the linked reference and follow its instruct ## Pin / Unpin -If this skill is invoked with `pin ` or `unpin `: - -**pin** creates a lightweight standalone skill so you can invoke the command directly (e.g., `/audit` instead of `/impeccable audit`). - -**unpin** removes a previously pinned shortcut. - -Run: +For `pin ` or `unpin `, run: ```bash node .pi/skills/impeccable/scripts/pin.mjs ``` - -Report what the script did. If it succeeded, confirm the new shortcut is available (for pin) or removed (for unpin). \ No newline at end of file +Full details (what pin/unpin does, valid commands, cross-harness behavior): [reference/pin.md](reference/pin.md). \ No newline at end of file diff --git a/.pi/skills/impeccable/reference/colorize.md b/.pi/skills/impeccable/reference/colorize.md index a4ce5072e..bb94be480 100644 --- a/.pi/skills/impeccable/reference/colorize.md +++ b/.pi/skills/impeccable/reference/colorize.md @@ -74,10 +74,13 @@ Add color systematically across these dimensions: - **Comparison**: Color coding for different datasets or timeframes ### Borders & Accents -- **Accent borders**: Add colored left/top borders to cards or sections +- **Hairline borders**: 1px colored borders on full perimeter (not side-stripes — see the absolute ban on `border-left/right > 1px`) - **Underlines**: Color underlines for emphasis or active states - **Dividers**: Subtle colored dividers instead of gray lines - **Focus rings**: Colored focus indicators matching brand +- **Surface tints**: A 4-8% background wash of the accent color instead of a stripe + +**NEVER**: `border-left` or `border-right` greater than 1px as a colored accent stripe. This is one of the three absolute bans in the parent skill. If you want to mark a card as "active" or "warning", use a full hairline border, a background tint, a leading glyph, or a numbered prefix — not a side stripe. ### Typography Color - **Colored headings**: Use brand colors for section headings (maintain contrast) diff --git a/.pi/skills/impeccable/reference/context.md b/.pi/skills/impeccable/reference/context.md new file mode 100644 index 000000000..6dbe33f59 --- /dev/null +++ b/.pi/skills/impeccable/reference/context.md @@ -0,0 +1,52 @@ +# Context Gathering Protocol + +The full protocol that backs the brief rule in SKILL.md. Load this when you need the complete dispatch logic, exceptions, or cache semantics. + +## The two context files + +- **PRODUCT.md** (strategic, **required**): target users, product purpose, brand personality, anti-references, strategic design principles. Answers *who/what/why*. +- **DESIGN.md** (visual, **optional but strongly recommended**): follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/). Colors, typography, elevation, components, do's-and-don'ts. Answers *how it looks*. + +Filename matching is case-insensitive. Legacy `.impeccable.md` auto-migrates to `PRODUCT.md` on first load. **DESIGN.md wins on visual decisions; PRODUCT.md wins on strategic/voice decisions.** + +## The load command + +```bash +node {{scripts_path}}/load-context.mjs +``` + +Returns JSON with `hasProduct`, `product` (full contents), `hasDesign`, `design` (full contents), `migrated`. **Consume the full output. Never pipe through `head`, `tail`, `grep`, or `jq` with field filters** — you need the complete file contents to do your job. Token cost of the full load is ~2-20KB, far less than redoing work with missing context. + +## Session cache (critical for token economy) + +If PRODUCT.md content is already in your conversation history from an earlier tool call in this session, you already have it loaded. **Do NOT re-run `load-context.mjs`.** Same for DESIGN.md. Re-fetching wastes thousands of tokens across a multi-command session. + +Exceptions where you MUST re-load: +- You just ran `/impeccable teach` — PRODUCT.md was written or updated. +- You just ran `/impeccable document` — DESIGN.md was written or updated. +- The user says they've manually edited PRODUCT.md or DESIGN.md. + +## Dispatch on result + +**`hasProduct: true` AND content is substantive** (>200 chars, no `[TODO]` placeholders): +- If `hasDesign: true`: proceed. You have full context. +- If `hasDesign: false`: do a one-line nudge (say it once per session): + > *"Note: no DESIGN.md found. I'll use impeccable's built-in design principles. For more on-brand output, run `/impeccable document` to generate a DESIGN.md from your existing code."* + Then proceed. + +**`hasProduct: false`** OR file exists but is empty / full of `[TODO]` placeholders: +1. Tell the user: *"I need PRODUCT.md before I can do this well. Running `/impeccable teach` now — I'll resume `[original task]` after."* +2. Run `/impeccable teach`. +3. When teach completes, re-run `load-context.mjs` and resume the **original** task the user asked for. Do not silently abandon intent. + +## Exceptions (commands that skip or reshape the protocol) + +- **`/impeccable teach`**: skips this protocol entirely — teach is how PRODUCT.md (and optionally DESIGN.md) get CREATED. Don't try to load before you create. +- **`/impeccable document`**: load PRODUCT.md (voice input) but do NOT block on missing DESIGN.md — document is how DESIGN.md gets created. +- **`/impeccable live`**: `live.mjs` already invokes the loader internally and returns both files in its startup JSON. When you've run `live.mjs`, the context is warmed. Do NOT additionally run `load-context.mjs` in the same session. + +## Why this matters + +- **Generic output is the #1 failure mode** of impeccable without PRODUCT.md. The user asks for polish and gets a stock-looking polish because the agent has no tone to polish toward. +- **Warmed live sessions feel instant** because when the user finally clicks Generate in the browser, the agent already has PRODUCT + DESIGN in context and proceeds straight to variant generation. +- **Token-efficient sessions** let the user run `/impeccable polish`, then `/impeccable audit`, then `/impeccable layout` without re-reading context files three times. diff --git a/.pi/skills/impeccable/reference/pin.md b/.pi/skills/impeccable/reference/pin.md new file mode 100644 index 000000000..81565d5fc --- /dev/null +++ b/.pi/skills/impeccable/reference/pin.md @@ -0,0 +1,31 @@ +# Pin / Unpin + +Commands that create or remove standalone slash-command shortcuts for frequently-used sub-commands. + +## What it does + +**Pin** creates a lightweight standalone skill so `/` invokes `/impeccable ` directly. Example: `/impeccable pin audit` creates `/audit` as a shortcut for `/impeccable audit`. + +**Unpin** removes a previously pinned shortcut. + +The pinned skill is a thin redirect — it doesn't duplicate the sub-command reference, it just forwards to the impeccable router. + +## Usage + +```bash +node {{scripts_path}}/pin.mjs pin +node {{scripts_path}}/pin.mjs unpin +``` + +The script writes to every harness directory present in the project (`.claude/`, `.cursor/`, `.codex/`, `.agents/`, `.gemini/`, etc.) so pinned shortcuts work across every AI coding tool the user has installed. + +## Valid commands + +Any impeccable sub-command name is a valid pin target: `craft`, `shape`, `teach`, `document`, `extract`, `critique`, `audit`, `polish`, `bolder`, `quieter`, `distill`, `harden`, `onboard`, `animate`, `colorize`, `typeset`, `layout`, `delight`, `overdrive`, `clarify`, `adapt`, `optimize`, `live`. + +## Reporting back + +After running the script, report what happened: +- **Pin success**: confirm the new shortcut (e.g. *"Pinned. You can now use `/audit` as a shortcut for `/impeccable audit`."*). +- **Unpin success**: confirm removal. +- **Errors**: relay the script's stderr verbatim — usually the command name was invalid or the pin already/doesn't exist. diff --git a/.rovodev/skills/impeccable/SKILL.md b/.rovodev/skills/impeccable/SKILL.md index 7be43ef7b..0b6740732 100644 --- a/.rovodev/skills/impeccable/SKILL.md +++ b/.rovodev/skills/impeccable/SKILL.md @@ -29,55 +29,28 @@ After running the script, delete this entire section (from `200 chars, no `[TODO]` placeholders): - - If `hasDesign: true`: proceed. You have full context. - - If `hasDesign: false`: do a one-line nudge to the user (say it once per session): *"Note: no DESIGN.md found. I'll use impeccable's built-in design principles. For more on-brand output, run `/impeccable document` to generate a DESIGN.md from your existing code."* Then proceed. -- **`hasProduct: false`** OR the file exists but is empty / full of `[TODO]` placeholders: - 1. Tell the user: *"I need PRODUCT.md before I can do this well. Running `/impeccable teach` now — I'll resume `[original task]` after."* - 2. Run `/impeccable teach`. - 3. When teach completes, re-run `load-context.mjs` and resume the **original** task the user asked for. Do not silently abandon intent. +**If PRODUCT.md is missing or empty:** run `/impeccable teach`, then resume the user's original task with the fresh context. -### Exceptions (commands that skip or reshape the protocol) +**If DESIGN.md is missing:** nudge once per session (*"Run `/impeccable document` for more on-brand output"*), then proceed. -- **`/impeccable teach`**: skips this protocol entirely — teach is how PRODUCT.md (and optionally DESIGN.md) get CREATED. Don't try to load before you create. -- **`/impeccable document`**: load PRODUCT.md (voice input) but do NOT block on missing DESIGN.md — document is how DESIGN.md gets created. -- **`/impeccable live`**: `live.mjs` already invokes the loader internally and returns both files in its startup JSON. When you've run `live.mjs`, the context is warmed. Do NOT additionally run `load-context.mjs` in the same session. - -### Why this matters - -- **Generic output is the #1 failure mode** of impeccable without PRODUCT.md. The user asked for polish and got a stock-looking polish because Claude had no tone to polish toward. -- **Warmed live sessions feel instant** because when the user finally clicks Generate in the browser, Claude already has PRODUCT + DESIGN in context and proceeds straight to variant generation. -- **Token-efficient sessions** let the user run `/impeccable polish`, then `/impeccable audit`, then `/impeccable layout` without re-reading context files three times. +Full protocol (session cache rules, exceptions for teach/document/live, dispatch tree, migration): [reference/context.md](reference/context.md). --- @@ -216,11 +189,9 @@ Create visual rhythm through varied spacing, not the same padding everywhere. Em Always apply these — do not consult a reference, just do them: -- Use a 4pt spacing scale with semantic token names (`--space-sm`, `--space-md`), not pixel-named (`--spacing-8`). Scale: 4, 8, 12, 16, 24, 32, 48, 64, 96. 8pt is too coarse — you'll often want 12px between two values. -- Use `gap` instead of margins for sibling spacing. It eliminates margin collapse and the cleanup hacks that come with it. -- Vary spacing for hierarchy. A heading with extra space above it reads as more important — make use of that. Don't apply the same padding everywhere. +- Vary spacing for hierarchy. A heading with extra space above it reads as more important. Don't apply the same padding everywhere. +- Use a semantic spacing scale (`--space-sm`, `--space-md`), not pixel-named (`--spacing-8`). - Self-adjusting grid pattern: `grid-template-columns: repeat(auto-fit, minmax(280px, 1fr))` is the breakpoint-free responsive grid for card-style content. -- Container queries are for components, viewport queries are for page layout. A card in a sidebar should adapt to the sidebar's width, not the viewport's. @@ -409,15 +380,8 @@ When a sub-command is matched, load the linked reference and follow its instruct ## Pin / Unpin -If this skill is invoked with `pin ` or `unpin `: - -**pin** creates a lightweight standalone skill so you can invoke the command directly (e.g., `/audit` instead of `/impeccable audit`). - -**unpin** removes a previously pinned shortcut. - -Run: +For `pin ` or `unpin `, run: ```bash node .rovodev/skills/impeccable/scripts/pin.mjs ``` - -Report what the script did. If it succeeded, confirm the new shortcut is available (for pin) or removed (for unpin). \ No newline at end of file +Full details (what pin/unpin does, valid commands, cross-harness behavior): [reference/pin.md](reference/pin.md). \ No newline at end of file diff --git a/.rovodev/skills/impeccable/reference/colorize.md b/.rovodev/skills/impeccable/reference/colorize.md index a4ce5072e..bb94be480 100644 --- a/.rovodev/skills/impeccable/reference/colorize.md +++ b/.rovodev/skills/impeccable/reference/colorize.md @@ -74,10 +74,13 @@ Add color systematically across these dimensions: - **Comparison**: Color coding for different datasets or timeframes ### Borders & Accents -- **Accent borders**: Add colored left/top borders to cards or sections +- **Hairline borders**: 1px colored borders on full perimeter (not side-stripes — see the absolute ban on `border-left/right > 1px`) - **Underlines**: Color underlines for emphasis or active states - **Dividers**: Subtle colored dividers instead of gray lines - **Focus rings**: Colored focus indicators matching brand +- **Surface tints**: A 4-8% background wash of the accent color instead of a stripe + +**NEVER**: `border-left` or `border-right` greater than 1px as a colored accent stripe. This is one of the three absolute bans in the parent skill. If you want to mark a card as "active" or "warning", use a full hairline border, a background tint, a leading glyph, or a numbered prefix — not a side stripe. ### Typography Color - **Colored headings**: Use brand colors for section headings (maintain contrast) diff --git a/.rovodev/skills/impeccable/reference/context.md b/.rovodev/skills/impeccable/reference/context.md new file mode 100644 index 000000000..6dbe33f59 --- /dev/null +++ b/.rovodev/skills/impeccable/reference/context.md @@ -0,0 +1,52 @@ +# Context Gathering Protocol + +The full protocol that backs the brief rule in SKILL.md. Load this when you need the complete dispatch logic, exceptions, or cache semantics. + +## The two context files + +- **PRODUCT.md** (strategic, **required**): target users, product purpose, brand personality, anti-references, strategic design principles. Answers *who/what/why*. +- **DESIGN.md** (visual, **optional but strongly recommended**): follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/). Colors, typography, elevation, components, do's-and-don'ts. Answers *how it looks*. + +Filename matching is case-insensitive. Legacy `.impeccable.md` auto-migrates to `PRODUCT.md` on first load. **DESIGN.md wins on visual decisions; PRODUCT.md wins on strategic/voice decisions.** + +## The load command + +```bash +node {{scripts_path}}/load-context.mjs +``` + +Returns JSON with `hasProduct`, `product` (full contents), `hasDesign`, `design` (full contents), `migrated`. **Consume the full output. Never pipe through `head`, `tail`, `grep`, or `jq` with field filters** — you need the complete file contents to do your job. Token cost of the full load is ~2-20KB, far less than redoing work with missing context. + +## Session cache (critical for token economy) + +If PRODUCT.md content is already in your conversation history from an earlier tool call in this session, you already have it loaded. **Do NOT re-run `load-context.mjs`.** Same for DESIGN.md. Re-fetching wastes thousands of tokens across a multi-command session. + +Exceptions where you MUST re-load: +- You just ran `/impeccable teach` — PRODUCT.md was written or updated. +- You just ran `/impeccable document` — DESIGN.md was written or updated. +- The user says they've manually edited PRODUCT.md or DESIGN.md. + +## Dispatch on result + +**`hasProduct: true` AND content is substantive** (>200 chars, no `[TODO]` placeholders): +- If `hasDesign: true`: proceed. You have full context. +- If `hasDesign: false`: do a one-line nudge (say it once per session): + > *"Note: no DESIGN.md found. I'll use impeccable's built-in design principles. For more on-brand output, run `/impeccable document` to generate a DESIGN.md from your existing code."* + Then proceed. + +**`hasProduct: false`** OR file exists but is empty / full of `[TODO]` placeholders: +1. Tell the user: *"I need PRODUCT.md before I can do this well. Running `/impeccable teach` now — I'll resume `[original task]` after."* +2. Run `/impeccable teach`. +3. When teach completes, re-run `load-context.mjs` and resume the **original** task the user asked for. Do not silently abandon intent. + +## Exceptions (commands that skip or reshape the protocol) + +- **`/impeccable teach`**: skips this protocol entirely — teach is how PRODUCT.md (and optionally DESIGN.md) get CREATED. Don't try to load before you create. +- **`/impeccable document`**: load PRODUCT.md (voice input) but do NOT block on missing DESIGN.md — document is how DESIGN.md gets created. +- **`/impeccable live`**: `live.mjs` already invokes the loader internally and returns both files in its startup JSON. When you've run `live.mjs`, the context is warmed. Do NOT additionally run `load-context.mjs` in the same session. + +## Why this matters + +- **Generic output is the #1 failure mode** of impeccable without PRODUCT.md. The user asks for polish and gets a stock-looking polish because the agent has no tone to polish toward. +- **Warmed live sessions feel instant** because when the user finally clicks Generate in the browser, the agent already has PRODUCT + DESIGN in context and proceeds straight to variant generation. +- **Token-efficient sessions** let the user run `/impeccable polish`, then `/impeccable audit`, then `/impeccable layout` without re-reading context files three times. diff --git a/.rovodev/skills/impeccable/reference/pin.md b/.rovodev/skills/impeccable/reference/pin.md new file mode 100644 index 000000000..81565d5fc --- /dev/null +++ b/.rovodev/skills/impeccable/reference/pin.md @@ -0,0 +1,31 @@ +# Pin / Unpin + +Commands that create or remove standalone slash-command shortcuts for frequently-used sub-commands. + +## What it does + +**Pin** creates a lightweight standalone skill so `/` invokes `/impeccable ` directly. Example: `/impeccable pin audit` creates `/audit` as a shortcut for `/impeccable audit`. + +**Unpin** removes a previously pinned shortcut. + +The pinned skill is a thin redirect — it doesn't duplicate the sub-command reference, it just forwards to the impeccable router. + +## Usage + +```bash +node {{scripts_path}}/pin.mjs pin +node {{scripts_path}}/pin.mjs unpin +``` + +The script writes to every harness directory present in the project (`.claude/`, `.cursor/`, `.codex/`, `.agents/`, `.gemini/`, etc.) so pinned shortcuts work across every AI coding tool the user has installed. + +## Valid commands + +Any impeccable sub-command name is a valid pin target: `craft`, `shape`, `teach`, `document`, `extract`, `critique`, `audit`, `polish`, `bolder`, `quieter`, `distill`, `harden`, `onboard`, `animate`, `colorize`, `typeset`, `layout`, `delight`, `overdrive`, `clarify`, `adapt`, `optimize`, `live`. + +## Reporting back + +After running the script, report what happened: +- **Pin success**: confirm the new shortcut (e.g. *"Pinned. You can now use `/audit` as a shortcut for `/impeccable audit`."*). +- **Unpin success**: confirm removal. +- **Errors**: relay the script's stderr verbatim — usually the command name was invalid or the pin already/doesn't exist. diff --git a/.trae-cn/skills/impeccable/SKILL.md b/.trae-cn/skills/impeccable/SKILL.md index 28ca342b9..7896604fc 100644 --- a/.trae-cn/skills/impeccable/SKILL.md +++ b/.trae-cn/skills/impeccable/SKILL.md @@ -27,55 +27,28 @@ After running the script, delete this entire section (from `200 chars, no `[TODO]` placeholders): - - If `hasDesign: true`: proceed. You have full context. - - If `hasDesign: false`: do a one-line nudge to the user (say it once per session): *"Note: no DESIGN.md found. I'll use impeccable's built-in design principles. For more on-brand output, run `/impeccable document` to generate a DESIGN.md from your existing code."* Then proceed. -- **`hasProduct: false`** OR the file exists but is empty / full of `[TODO]` placeholders: - 1. Tell the user: *"I need PRODUCT.md before I can do this well. Running `/impeccable teach` now — I'll resume `[original task]` after."* - 2. Run `/impeccable teach`. - 3. When teach completes, re-run `load-context.mjs` and resume the **original** task the user asked for. Do not silently abandon intent. +**If PRODUCT.md is missing or empty:** run `/impeccable teach`, then resume the user's original task with the fresh context. -### Exceptions (commands that skip or reshape the protocol) +**If DESIGN.md is missing:** nudge once per session (*"Run `/impeccable document` for more on-brand output"*), then proceed. -- **`/impeccable teach`**: skips this protocol entirely — teach is how PRODUCT.md (and optionally DESIGN.md) get CREATED. Don't try to load before you create. -- **`/impeccable document`**: load PRODUCT.md (voice input) but do NOT block on missing DESIGN.md — document is how DESIGN.md gets created. -- **`/impeccable live`**: `live.mjs` already invokes the loader internally and returns both files in its startup JSON. When you've run `live.mjs`, the context is warmed. Do NOT additionally run `load-context.mjs` in the same session. - -### Why this matters - -- **Generic output is the #1 failure mode** of impeccable without PRODUCT.md. The user asked for polish and got a stock-looking polish because Claude had no tone to polish toward. -- **Warmed live sessions feel instant** because when the user finally clicks Generate in the browser, Claude already has PRODUCT + DESIGN in context and proceeds straight to variant generation. -- **Token-efficient sessions** let the user run `/impeccable polish`, then `/impeccable audit`, then `/impeccable layout` without re-reading context files three times. +Full protocol (session cache rules, exceptions for teach/document/live, dispatch tree, migration): [reference/context.md](reference/context.md). --- @@ -214,11 +187,9 @@ Create visual rhythm through varied spacing, not the same padding everywhere. Em Always apply these — do not consult a reference, just do them: -- Use a 4pt spacing scale with semantic token names (`--space-sm`, `--space-md`), not pixel-named (`--spacing-8`). Scale: 4, 8, 12, 16, 24, 32, 48, 64, 96. 8pt is too coarse — you'll often want 12px between two values. -- Use `gap` instead of margins for sibling spacing. It eliminates margin collapse and the cleanup hacks that come with it. -- Vary spacing for hierarchy. A heading with extra space above it reads as more important — make use of that. Don't apply the same padding everywhere. +- Vary spacing for hierarchy. A heading with extra space above it reads as more important. Don't apply the same padding everywhere. +- Use a semantic spacing scale (`--space-sm`, `--space-md`), not pixel-named (`--spacing-8`). - Self-adjusting grid pattern: `grid-template-columns: repeat(auto-fit, minmax(280px, 1fr))` is the breakpoint-free responsive grid for card-style content. -- Container queries are for components, viewport queries are for page layout. A card in a sidebar should adapt to the sidebar's width, not the viewport's. @@ -407,15 +378,8 @@ When a sub-command is matched, load the linked reference and follow its instruct ## Pin / Unpin -If this skill is invoked with `pin ` or `unpin `: - -**pin** creates a lightweight standalone skill so you can invoke the command directly (e.g., `/audit` instead of `/impeccable audit`). - -**unpin** removes a previously pinned shortcut. - -Run: +For `pin ` or `unpin `, run: ```bash node .trae-cn/skills/impeccable/scripts/pin.mjs ``` - -Report what the script did. If it succeeded, confirm the new shortcut is available (for pin) or removed (for unpin). \ No newline at end of file +Full details (what pin/unpin does, valid commands, cross-harness behavior): [reference/pin.md](reference/pin.md). \ No newline at end of file diff --git a/.trae-cn/skills/impeccable/reference/colorize.md b/.trae-cn/skills/impeccable/reference/colorize.md index a4ce5072e..bb94be480 100644 --- a/.trae-cn/skills/impeccable/reference/colorize.md +++ b/.trae-cn/skills/impeccable/reference/colorize.md @@ -74,10 +74,13 @@ Add color systematically across these dimensions: - **Comparison**: Color coding for different datasets or timeframes ### Borders & Accents -- **Accent borders**: Add colored left/top borders to cards or sections +- **Hairline borders**: 1px colored borders on full perimeter (not side-stripes — see the absolute ban on `border-left/right > 1px`) - **Underlines**: Color underlines for emphasis or active states - **Dividers**: Subtle colored dividers instead of gray lines - **Focus rings**: Colored focus indicators matching brand +- **Surface tints**: A 4-8% background wash of the accent color instead of a stripe + +**NEVER**: `border-left` or `border-right` greater than 1px as a colored accent stripe. This is one of the three absolute bans in the parent skill. If you want to mark a card as "active" or "warning", use a full hairline border, a background tint, a leading glyph, or a numbered prefix — not a side stripe. ### Typography Color - **Colored headings**: Use brand colors for section headings (maintain contrast) diff --git a/.trae-cn/skills/impeccable/reference/context.md b/.trae-cn/skills/impeccable/reference/context.md new file mode 100644 index 000000000..6dbe33f59 --- /dev/null +++ b/.trae-cn/skills/impeccable/reference/context.md @@ -0,0 +1,52 @@ +# Context Gathering Protocol + +The full protocol that backs the brief rule in SKILL.md. Load this when you need the complete dispatch logic, exceptions, or cache semantics. + +## The two context files + +- **PRODUCT.md** (strategic, **required**): target users, product purpose, brand personality, anti-references, strategic design principles. Answers *who/what/why*. +- **DESIGN.md** (visual, **optional but strongly recommended**): follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/). Colors, typography, elevation, components, do's-and-don'ts. Answers *how it looks*. + +Filename matching is case-insensitive. Legacy `.impeccable.md` auto-migrates to `PRODUCT.md` on first load. **DESIGN.md wins on visual decisions; PRODUCT.md wins on strategic/voice decisions.** + +## The load command + +```bash +node {{scripts_path}}/load-context.mjs +``` + +Returns JSON with `hasProduct`, `product` (full contents), `hasDesign`, `design` (full contents), `migrated`. **Consume the full output. Never pipe through `head`, `tail`, `grep`, or `jq` with field filters** — you need the complete file contents to do your job. Token cost of the full load is ~2-20KB, far less than redoing work with missing context. + +## Session cache (critical for token economy) + +If PRODUCT.md content is already in your conversation history from an earlier tool call in this session, you already have it loaded. **Do NOT re-run `load-context.mjs`.** Same for DESIGN.md. Re-fetching wastes thousands of tokens across a multi-command session. + +Exceptions where you MUST re-load: +- You just ran `/impeccable teach` — PRODUCT.md was written or updated. +- You just ran `/impeccable document` — DESIGN.md was written or updated. +- The user says they've manually edited PRODUCT.md or DESIGN.md. + +## Dispatch on result + +**`hasProduct: true` AND content is substantive** (>200 chars, no `[TODO]` placeholders): +- If `hasDesign: true`: proceed. You have full context. +- If `hasDesign: false`: do a one-line nudge (say it once per session): + > *"Note: no DESIGN.md found. I'll use impeccable's built-in design principles. For more on-brand output, run `/impeccable document` to generate a DESIGN.md from your existing code."* + Then proceed. + +**`hasProduct: false`** OR file exists but is empty / full of `[TODO]` placeholders: +1. Tell the user: *"I need PRODUCT.md before I can do this well. Running `/impeccable teach` now — I'll resume `[original task]` after."* +2. Run `/impeccable teach`. +3. When teach completes, re-run `load-context.mjs` and resume the **original** task the user asked for. Do not silently abandon intent. + +## Exceptions (commands that skip or reshape the protocol) + +- **`/impeccable teach`**: skips this protocol entirely — teach is how PRODUCT.md (and optionally DESIGN.md) get CREATED. Don't try to load before you create. +- **`/impeccable document`**: load PRODUCT.md (voice input) but do NOT block on missing DESIGN.md — document is how DESIGN.md gets created. +- **`/impeccable live`**: `live.mjs` already invokes the loader internally and returns both files in its startup JSON. When you've run `live.mjs`, the context is warmed. Do NOT additionally run `load-context.mjs` in the same session. + +## Why this matters + +- **Generic output is the #1 failure mode** of impeccable without PRODUCT.md. The user asks for polish and gets a stock-looking polish because the agent has no tone to polish toward. +- **Warmed live sessions feel instant** because when the user finally clicks Generate in the browser, the agent already has PRODUCT + DESIGN in context and proceeds straight to variant generation. +- **Token-efficient sessions** let the user run `/impeccable polish`, then `/impeccable audit`, then `/impeccable layout` without re-reading context files three times. diff --git a/.trae-cn/skills/impeccable/reference/pin.md b/.trae-cn/skills/impeccable/reference/pin.md new file mode 100644 index 000000000..81565d5fc --- /dev/null +++ b/.trae-cn/skills/impeccable/reference/pin.md @@ -0,0 +1,31 @@ +# Pin / Unpin + +Commands that create or remove standalone slash-command shortcuts for frequently-used sub-commands. + +## What it does + +**Pin** creates a lightweight standalone skill so `/` invokes `/impeccable ` directly. Example: `/impeccable pin audit` creates `/audit` as a shortcut for `/impeccable audit`. + +**Unpin** removes a previously pinned shortcut. + +The pinned skill is a thin redirect — it doesn't duplicate the sub-command reference, it just forwards to the impeccable router. + +## Usage + +```bash +node {{scripts_path}}/pin.mjs pin +node {{scripts_path}}/pin.mjs unpin +``` + +The script writes to every harness directory present in the project (`.claude/`, `.cursor/`, `.codex/`, `.agents/`, `.gemini/`, etc.) so pinned shortcuts work across every AI coding tool the user has installed. + +## Valid commands + +Any impeccable sub-command name is a valid pin target: `craft`, `shape`, `teach`, `document`, `extract`, `critique`, `audit`, `polish`, `bolder`, `quieter`, `distill`, `harden`, `onboard`, `animate`, `colorize`, `typeset`, `layout`, `delight`, `overdrive`, `clarify`, `adapt`, `optimize`, `live`. + +## Reporting back + +After running the script, report what happened: +- **Pin success**: confirm the new shortcut (e.g. *"Pinned. You can now use `/audit` as a shortcut for `/impeccable audit`."*). +- **Unpin success**: confirm removal. +- **Errors**: relay the script's stderr verbatim — usually the command name was invalid or the pin already/doesn't exist. diff --git a/.trae/skills/impeccable/SKILL.md b/.trae/skills/impeccable/SKILL.md index 39e59a3c5..6f3c4a42e 100644 --- a/.trae/skills/impeccable/SKILL.md +++ b/.trae/skills/impeccable/SKILL.md @@ -27,55 +27,28 @@ After running the script, delete this entire section (from `200 chars, no `[TODO]` placeholders): - - If `hasDesign: true`: proceed. You have full context. - - If `hasDesign: false`: do a one-line nudge to the user (say it once per session): *"Note: no DESIGN.md found. I'll use impeccable's built-in design principles. For more on-brand output, run `/impeccable document` to generate a DESIGN.md from your existing code."* Then proceed. -- **`hasProduct: false`** OR the file exists but is empty / full of `[TODO]` placeholders: - 1. Tell the user: *"I need PRODUCT.md before I can do this well. Running `/impeccable teach` now — I'll resume `[original task]` after."* - 2. Run `/impeccable teach`. - 3. When teach completes, re-run `load-context.mjs` and resume the **original** task the user asked for. Do not silently abandon intent. +**If PRODUCT.md is missing or empty:** run `/impeccable teach`, then resume the user's original task with the fresh context. -### Exceptions (commands that skip or reshape the protocol) +**If DESIGN.md is missing:** nudge once per session (*"Run `/impeccable document` for more on-brand output"*), then proceed. -- **`/impeccable teach`**: skips this protocol entirely — teach is how PRODUCT.md (and optionally DESIGN.md) get CREATED. Don't try to load before you create. -- **`/impeccable document`**: load PRODUCT.md (voice input) but do NOT block on missing DESIGN.md — document is how DESIGN.md gets created. -- **`/impeccable live`**: `live.mjs` already invokes the loader internally and returns both files in its startup JSON. When you've run `live.mjs`, the context is warmed. Do NOT additionally run `load-context.mjs` in the same session. - -### Why this matters - -- **Generic output is the #1 failure mode** of impeccable without PRODUCT.md. The user asked for polish and got a stock-looking polish because Claude had no tone to polish toward. -- **Warmed live sessions feel instant** because when the user finally clicks Generate in the browser, Claude already has PRODUCT + DESIGN in context and proceeds straight to variant generation. -- **Token-efficient sessions** let the user run `/impeccable polish`, then `/impeccable audit`, then `/impeccable layout` without re-reading context files three times. +Full protocol (session cache rules, exceptions for teach/document/live, dispatch tree, migration): [reference/context.md](reference/context.md). --- @@ -214,11 +187,9 @@ Create visual rhythm through varied spacing, not the same padding everywhere. Em Always apply these — do not consult a reference, just do them: -- Use a 4pt spacing scale with semantic token names (`--space-sm`, `--space-md`), not pixel-named (`--spacing-8`). Scale: 4, 8, 12, 16, 24, 32, 48, 64, 96. 8pt is too coarse — you'll often want 12px between two values. -- Use `gap` instead of margins for sibling spacing. It eliminates margin collapse and the cleanup hacks that come with it. -- Vary spacing for hierarchy. A heading with extra space above it reads as more important — make use of that. Don't apply the same padding everywhere. +- Vary spacing for hierarchy. A heading with extra space above it reads as more important. Don't apply the same padding everywhere. +- Use a semantic spacing scale (`--space-sm`, `--space-md`), not pixel-named (`--spacing-8`). - Self-adjusting grid pattern: `grid-template-columns: repeat(auto-fit, minmax(280px, 1fr))` is the breakpoint-free responsive grid for card-style content. -- Container queries are for components, viewport queries are for page layout. A card in a sidebar should adapt to the sidebar's width, not the viewport's. @@ -407,15 +378,8 @@ When a sub-command is matched, load the linked reference and follow its instruct ## Pin / Unpin -If this skill is invoked with `pin ` or `unpin `: - -**pin** creates a lightweight standalone skill so you can invoke the command directly (e.g., `/audit` instead of `/impeccable audit`). - -**unpin** removes a previously pinned shortcut. - -Run: +For `pin ` or `unpin `, run: ```bash node .trae/skills/impeccable/scripts/pin.mjs ``` - -Report what the script did. If it succeeded, confirm the new shortcut is available (for pin) or removed (for unpin). \ No newline at end of file +Full details (what pin/unpin does, valid commands, cross-harness behavior): [reference/pin.md](reference/pin.md). \ No newline at end of file diff --git a/.trae/skills/impeccable/reference/colorize.md b/.trae/skills/impeccable/reference/colorize.md index a4ce5072e..bb94be480 100644 --- a/.trae/skills/impeccable/reference/colorize.md +++ b/.trae/skills/impeccable/reference/colorize.md @@ -74,10 +74,13 @@ Add color systematically across these dimensions: - **Comparison**: Color coding for different datasets or timeframes ### Borders & Accents -- **Accent borders**: Add colored left/top borders to cards or sections +- **Hairline borders**: 1px colored borders on full perimeter (not side-stripes — see the absolute ban on `border-left/right > 1px`) - **Underlines**: Color underlines for emphasis or active states - **Dividers**: Subtle colored dividers instead of gray lines - **Focus rings**: Colored focus indicators matching brand +- **Surface tints**: A 4-8% background wash of the accent color instead of a stripe + +**NEVER**: `border-left` or `border-right` greater than 1px as a colored accent stripe. This is one of the three absolute bans in the parent skill. If you want to mark a card as "active" or "warning", use a full hairline border, a background tint, a leading glyph, or a numbered prefix — not a side stripe. ### Typography Color - **Colored headings**: Use brand colors for section headings (maintain contrast) diff --git a/.trae/skills/impeccable/reference/context.md b/.trae/skills/impeccable/reference/context.md new file mode 100644 index 000000000..6dbe33f59 --- /dev/null +++ b/.trae/skills/impeccable/reference/context.md @@ -0,0 +1,52 @@ +# Context Gathering Protocol + +The full protocol that backs the brief rule in SKILL.md. Load this when you need the complete dispatch logic, exceptions, or cache semantics. + +## The two context files + +- **PRODUCT.md** (strategic, **required**): target users, product purpose, brand personality, anti-references, strategic design principles. Answers *who/what/why*. +- **DESIGN.md** (visual, **optional but strongly recommended**): follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/). Colors, typography, elevation, components, do's-and-don'ts. Answers *how it looks*. + +Filename matching is case-insensitive. Legacy `.impeccable.md` auto-migrates to `PRODUCT.md` on first load. **DESIGN.md wins on visual decisions; PRODUCT.md wins on strategic/voice decisions.** + +## The load command + +```bash +node {{scripts_path}}/load-context.mjs +``` + +Returns JSON with `hasProduct`, `product` (full contents), `hasDesign`, `design` (full contents), `migrated`. **Consume the full output. Never pipe through `head`, `tail`, `grep`, or `jq` with field filters** — you need the complete file contents to do your job. Token cost of the full load is ~2-20KB, far less than redoing work with missing context. + +## Session cache (critical for token economy) + +If PRODUCT.md content is already in your conversation history from an earlier tool call in this session, you already have it loaded. **Do NOT re-run `load-context.mjs`.** Same for DESIGN.md. Re-fetching wastes thousands of tokens across a multi-command session. + +Exceptions where you MUST re-load: +- You just ran `/impeccable teach` — PRODUCT.md was written or updated. +- You just ran `/impeccable document` — DESIGN.md was written or updated. +- The user says they've manually edited PRODUCT.md or DESIGN.md. + +## Dispatch on result + +**`hasProduct: true` AND content is substantive** (>200 chars, no `[TODO]` placeholders): +- If `hasDesign: true`: proceed. You have full context. +- If `hasDesign: false`: do a one-line nudge (say it once per session): + > *"Note: no DESIGN.md found. I'll use impeccable's built-in design principles. For more on-brand output, run `/impeccable document` to generate a DESIGN.md from your existing code."* + Then proceed. + +**`hasProduct: false`** OR file exists but is empty / full of `[TODO]` placeholders: +1. Tell the user: *"I need PRODUCT.md before I can do this well. Running `/impeccable teach` now — I'll resume `[original task]` after."* +2. Run `/impeccable teach`. +3. When teach completes, re-run `load-context.mjs` and resume the **original** task the user asked for. Do not silently abandon intent. + +## Exceptions (commands that skip or reshape the protocol) + +- **`/impeccable teach`**: skips this protocol entirely — teach is how PRODUCT.md (and optionally DESIGN.md) get CREATED. Don't try to load before you create. +- **`/impeccable document`**: load PRODUCT.md (voice input) but do NOT block on missing DESIGN.md — document is how DESIGN.md gets created. +- **`/impeccable live`**: `live.mjs` already invokes the loader internally and returns both files in its startup JSON. When you've run `live.mjs`, the context is warmed. Do NOT additionally run `load-context.mjs` in the same session. + +## Why this matters + +- **Generic output is the #1 failure mode** of impeccable without PRODUCT.md. The user asks for polish and gets a stock-looking polish because the agent has no tone to polish toward. +- **Warmed live sessions feel instant** because when the user finally clicks Generate in the browser, the agent already has PRODUCT + DESIGN in context and proceeds straight to variant generation. +- **Token-efficient sessions** let the user run `/impeccable polish`, then `/impeccable audit`, then `/impeccable layout` without re-reading context files three times. diff --git a/.trae/skills/impeccable/reference/pin.md b/.trae/skills/impeccable/reference/pin.md new file mode 100644 index 000000000..81565d5fc --- /dev/null +++ b/.trae/skills/impeccable/reference/pin.md @@ -0,0 +1,31 @@ +# Pin / Unpin + +Commands that create or remove standalone slash-command shortcuts for frequently-used sub-commands. + +## What it does + +**Pin** creates a lightweight standalone skill so `/` invokes `/impeccable ` directly. Example: `/impeccable pin audit` creates `/audit` as a shortcut for `/impeccable audit`. + +**Unpin** removes a previously pinned shortcut. + +The pinned skill is a thin redirect — it doesn't duplicate the sub-command reference, it just forwards to the impeccable router. + +## Usage + +```bash +node {{scripts_path}}/pin.mjs pin +node {{scripts_path}}/pin.mjs unpin +``` + +The script writes to every harness directory present in the project (`.claude/`, `.cursor/`, `.codex/`, `.agents/`, `.gemini/`, etc.) so pinned shortcuts work across every AI coding tool the user has installed. + +## Valid commands + +Any impeccable sub-command name is a valid pin target: `craft`, `shape`, `teach`, `document`, `extract`, `critique`, `audit`, `polish`, `bolder`, `quieter`, `distill`, `harden`, `onboard`, `animate`, `colorize`, `typeset`, `layout`, `delight`, `overdrive`, `clarify`, `adapt`, `optimize`, `live`. + +## Reporting back + +After running the script, report what happened: +- **Pin success**: confirm the new shortcut (e.g. *"Pinned. You can now use `/audit` as a shortcut for `/impeccable audit`."*). +- **Unpin success**: confirm removal. +- **Errors**: relay the script's stderr verbatim — usually the command name was invalid or the pin already/doesn't exist. diff --git a/source/skills/impeccable/SKILL.md b/source/skills/impeccable/SKILL.md index 85267b36d..63a34eb39 100644 --- a/source/skills/impeccable/SKILL.md +++ b/source/skills/impeccable/SKILL.md @@ -28,55 +28,28 @@ After running the script, delete this entire section (from `200 chars, no `[TODO]` placeholders): - - If `hasDesign: true`: proceed. You have full context. - - If `hasDesign: false`: do a one-line nudge to the user (say it once per session): *"Note: no DESIGN.md found. I'll use impeccable's built-in design principles. For more on-brand output, run `/impeccable document` to generate a DESIGN.md from your existing code."* Then proceed. -- **`hasProduct: false`** OR the file exists but is empty / full of `[TODO]` placeholders: - 1. Tell the user: *"I need PRODUCT.md before I can do this well. Running `/impeccable teach` now — I'll resume `[original task]` after."* - 2. Run `/impeccable teach`. - 3. When teach completes, re-run `load-context.mjs` and resume the **original** task the user asked for. Do not silently abandon intent. +**If PRODUCT.md is missing or empty:** run `/impeccable teach`, then resume the user's original task with the fresh context. -### Exceptions (commands that skip or reshape the protocol) +**If DESIGN.md is missing:** nudge once per session (*"Run `/impeccable document` for more on-brand output"*), then proceed. -- **`/impeccable teach`**: skips this protocol entirely — teach is how PRODUCT.md (and optionally DESIGN.md) get CREATED. Don't try to load before you create. -- **`/impeccable document`**: load PRODUCT.md (voice input) but do NOT block on missing DESIGN.md — document is how DESIGN.md gets created. -- **`/impeccable live`**: `live.mjs` already invokes the loader internally and returns both files in its startup JSON. When you've run `live.mjs`, the context is warmed. Do NOT additionally run `load-context.mjs` in the same session. - -### Why this matters - -- **Generic output is the #1 failure mode** of impeccable without PRODUCT.md. The user asked for polish and got a stock-looking polish because Claude had no tone to polish toward. -- **Warmed live sessions feel instant** because when the user finally clicks Generate in the browser, Claude already has PRODUCT + DESIGN in context and proceeds straight to variant generation. -- **Token-efficient sessions** let the user run `/impeccable polish`, then `/impeccable audit`, then `/impeccable layout` without re-reading context files three times. +Full protocol (session cache rules, exceptions for teach/document/live, dispatch tree, migration): [reference/context.md](reference/context.md). --- @@ -215,11 +188,9 @@ Create visual rhythm through varied spacing, not the same padding everywhere. Em Always apply these — do not consult a reference, just do them: -- Use a 4pt spacing scale with semantic token names (`--space-sm`, `--space-md`), not pixel-named (`--spacing-8`). Scale: 4, 8, 12, 16, 24, 32, 48, 64, 96. 8pt is too coarse — you'll often want 12px between two values. -- Use `gap` instead of margins for sibling spacing. It eliminates margin collapse and the cleanup hacks that come with it. -- Vary spacing for hierarchy. A heading with extra space above it reads as more important — make use of that. Don't apply the same padding everywhere. +- Vary spacing for hierarchy. A heading with extra space above it reads as more important. Don't apply the same padding everywhere. +- Use a semantic spacing scale (`--space-sm`, `--space-md`), not pixel-named (`--spacing-8`). - Self-adjusting grid pattern: `grid-template-columns: repeat(auto-fit, minmax(280px, 1fr))` is the breakpoint-free responsive grid for card-style content. -- Container queries are for components, viewport queries are for page layout. A card in a sidebar should adapt to the sidebar's width, not the viewport's. @@ -408,15 +379,8 @@ When a sub-command is matched, load the linked reference and follow its instruct ## Pin / Unpin -If this skill is invoked with `pin ` or `unpin `: - -**pin** creates a lightweight standalone skill so you can invoke the command directly (e.g., `{{command_prefix}}audit` instead of `{{command_prefix}}impeccable audit`). - -**unpin** removes a previously pinned shortcut. - -Run: +For `pin ` or `unpin `, run: ```bash node {{scripts_path}}/pin.mjs ``` - -Report what the script did. If it succeeded, confirm the new shortcut is available (for pin) or removed (for unpin). +Full details (what pin/unpin does, valid commands, cross-harness behavior): [reference/pin.md](reference/pin.md). diff --git a/source/skills/impeccable/reference/colorize.md b/source/skills/impeccable/reference/colorize.md index 363d2aae2..d3156f914 100644 --- a/source/skills/impeccable/reference/colorize.md +++ b/source/skills/impeccable/reference/colorize.md @@ -74,10 +74,13 @@ Add color systematically across these dimensions: - **Comparison**: Color coding for different datasets or timeframes ### Borders & Accents -- **Accent borders**: Add colored left/top borders to cards or sections +- **Hairline borders**: 1px colored borders on full perimeter (not side-stripes — see the absolute ban on `border-left/right > 1px`) - **Underlines**: Color underlines for emphasis or active states - **Dividers**: Subtle colored dividers instead of gray lines - **Focus rings**: Colored focus indicators matching brand +- **Surface tints**: A 4-8% background wash of the accent color instead of a stripe + +**NEVER**: `border-left` or `border-right` greater than 1px as a colored accent stripe. This is one of the three absolute bans in the parent skill. If you want to mark a card as "active" or "warning", use a full hairline border, a background tint, a leading glyph, or a numbered prefix — not a side stripe. ### Typography Color - **Colored headings**: Use brand colors for section headings (maintain contrast) diff --git a/source/skills/impeccable/reference/context.md b/source/skills/impeccable/reference/context.md new file mode 100644 index 000000000..6dbe33f59 --- /dev/null +++ b/source/skills/impeccable/reference/context.md @@ -0,0 +1,52 @@ +# Context Gathering Protocol + +The full protocol that backs the brief rule in SKILL.md. Load this when you need the complete dispatch logic, exceptions, or cache semantics. + +## The two context files + +- **PRODUCT.md** (strategic, **required**): target users, product purpose, brand personality, anti-references, strategic design principles. Answers *who/what/why*. +- **DESIGN.md** (visual, **optional but strongly recommended**): follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/). Colors, typography, elevation, components, do's-and-don'ts. Answers *how it looks*. + +Filename matching is case-insensitive. Legacy `.impeccable.md` auto-migrates to `PRODUCT.md` on first load. **DESIGN.md wins on visual decisions; PRODUCT.md wins on strategic/voice decisions.** + +## The load command + +```bash +node {{scripts_path}}/load-context.mjs +``` + +Returns JSON with `hasProduct`, `product` (full contents), `hasDesign`, `design` (full contents), `migrated`. **Consume the full output. Never pipe through `head`, `tail`, `grep`, or `jq` with field filters** — you need the complete file contents to do your job. Token cost of the full load is ~2-20KB, far less than redoing work with missing context. + +## Session cache (critical for token economy) + +If PRODUCT.md content is already in your conversation history from an earlier tool call in this session, you already have it loaded. **Do NOT re-run `load-context.mjs`.** Same for DESIGN.md. Re-fetching wastes thousands of tokens across a multi-command session. + +Exceptions where you MUST re-load: +- You just ran `/impeccable teach` — PRODUCT.md was written or updated. +- You just ran `/impeccable document` — DESIGN.md was written or updated. +- The user says they've manually edited PRODUCT.md or DESIGN.md. + +## Dispatch on result + +**`hasProduct: true` AND content is substantive** (>200 chars, no `[TODO]` placeholders): +- If `hasDesign: true`: proceed. You have full context. +- If `hasDesign: false`: do a one-line nudge (say it once per session): + > *"Note: no DESIGN.md found. I'll use impeccable's built-in design principles. For more on-brand output, run `/impeccable document` to generate a DESIGN.md from your existing code."* + Then proceed. + +**`hasProduct: false`** OR file exists but is empty / full of `[TODO]` placeholders: +1. Tell the user: *"I need PRODUCT.md before I can do this well. Running `/impeccable teach` now — I'll resume `[original task]` after."* +2. Run `/impeccable teach`. +3. When teach completes, re-run `load-context.mjs` and resume the **original** task the user asked for. Do not silently abandon intent. + +## Exceptions (commands that skip or reshape the protocol) + +- **`/impeccable teach`**: skips this protocol entirely — teach is how PRODUCT.md (and optionally DESIGN.md) get CREATED. Don't try to load before you create. +- **`/impeccable document`**: load PRODUCT.md (voice input) but do NOT block on missing DESIGN.md — document is how DESIGN.md gets created. +- **`/impeccable live`**: `live.mjs` already invokes the loader internally and returns both files in its startup JSON. When you've run `live.mjs`, the context is warmed. Do NOT additionally run `load-context.mjs` in the same session. + +## Why this matters + +- **Generic output is the #1 failure mode** of impeccable without PRODUCT.md. The user asks for polish and gets a stock-looking polish because the agent has no tone to polish toward. +- **Warmed live sessions feel instant** because when the user finally clicks Generate in the browser, the agent already has PRODUCT + DESIGN in context and proceeds straight to variant generation. +- **Token-efficient sessions** let the user run `/impeccable polish`, then `/impeccable audit`, then `/impeccable layout` without re-reading context files three times. diff --git a/source/skills/impeccable/reference/pin.md b/source/skills/impeccable/reference/pin.md new file mode 100644 index 000000000..4d4defbe3 --- /dev/null +++ b/source/skills/impeccable/reference/pin.md @@ -0,0 +1,31 @@ +# Pin / Unpin + +Commands that create or remove standalone slash-command shortcuts for frequently-used sub-commands. + +## What it does + +**Pin** creates a lightweight standalone skill so `{{command_prefix}}` invokes `{{command_prefix}}impeccable ` directly. Example: `{{command_prefix}}impeccable pin audit` creates `{{command_prefix}}audit` as a shortcut for `{{command_prefix}}impeccable audit`. + +**Unpin** removes a previously pinned shortcut. + +The pinned skill is a thin redirect — it doesn't duplicate the sub-command reference, it just forwards to the impeccable router. + +## Usage + +```bash +node {{scripts_path}}/pin.mjs pin +node {{scripts_path}}/pin.mjs unpin +``` + +The script writes to every harness directory present in the project (`.claude/`, `.cursor/`, `.codex/`, `.agents/`, `.gemini/`, etc.) so pinned shortcuts work across every AI coding tool the user has installed. + +## Valid commands + +Any impeccable sub-command name is a valid pin target: `craft`, `shape`, `teach`, `document`, `extract`, `critique`, `audit`, `polish`, `bolder`, `quieter`, `distill`, `harden`, `onboard`, `animate`, `colorize`, `typeset`, `layout`, `delight`, `overdrive`, `clarify`, `adapt`, `optimize`, `live`. + +## Reporting back + +After running the script, report what happened: +- **Pin success**: confirm the new shortcut (e.g. *"Pinned. You can now use `{{command_prefix}}audit` as a shortcut for `{{command_prefix}}impeccable audit`."*). +- **Unpin success**: confirm removal. +- **Errors**: relay the script's stderr verbatim — usually the command name was invalid or the pin already/doesn't exist.