mirror of
https://github.com/pbakaus/impeccable.git
synced 2026-09-14 07:06:45 +03:00
Trim SKILL.md plumbing; extract context + pin protocols to references
Before: 422 lines. After: 386 lines. The cut is conservative because evals/AGENT.md revealed that most of what looked like bloat is actually load-bearing: the font_selection_procedure with its 23-font ban list (lesson 6), the theme_selection with audience examples (lesson 9), and the absolute_bans with literal CSS patterns (lesson 7) all drive measurable eval improvements and must stay inline. What moved out of SKILL.md: - Context Gathering Protocol (52 → ~18 lines). The full protocol — cache semantics, dispatch tree, teach/document/live exceptions, why-it-matters — moved to reference/context.md. SKILL.md keeps only the compact hook: load command, "never infer from codebase" warning, and pointer. - Pin/Unpin (14 → 6 lines). Details moved to reference/pin.md. - Spatial principles: dropped 4pt-vs-8pt rationale, gap-vs-margins CSS technicality, and container-queries-vs-viewport explanation (not load-bearing in the main skill). Kept all load-bearing rules including the 80-char body-text line (detector-backed). What did NOT move (load-bearing per evals): - <font_selection_procedure> with the 23-font ban list - <theme_selection> with the 8 audience examples - <absolute_bans> with literal CSS patterns - All XML tag structure (lesson 8: XML works better than markdown for reasoning models, especially OpenAI) Also added: - reference/context.md (new) — full context protocol - reference/pin.md (new) — full pin/unpin docs - "Never infer brand, audience, or tone from the codebase" warning restored to SKILL.md (was dropped in an earlier refactor) Fixed: - reference/colorize.md had "Accent borders: Add colored left/top borders to cards or sections" which directly contradicted SKILL.md's absolute_ban on border-left/right > 1px. Rewrote the accent-border advice to use hairline borders, surface tints, or leading glyphs instead, with an explicit reference to the ban. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Paul Bakaus
co-authored by
Claude Opus 4.6
Claude Opus 4.6
parent
268a5e15cc
commit
473dbd52ef
@@ -28,55 +28,28 @@ After running the script, delete this entire section (from `<post-update-cleanup
|
||||
|
||||
## Context Gathering Protocol
|
||||
|
||||
Design skills produce generic output without project context. This protocol runs ONCE at the start of a session, before any design work.
|
||||
Before any design work, ensure project context is loaded. Two files at the project root (case-insensitive):
|
||||
|
||||
### The two context files
|
||||
- **PRODUCT.md** — required. Users, brand, tone, anti-references, strategic principles.
|
||||
- **DESIGN.md** — optional but strongly recommended. Colors, typography, elevation, components.
|
||||
|
||||
- **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".
|
||||
**Never infer brand, audience, or tone from the codebase.** Code shows WHAT was built, not WHO it's for or HOW it should feel. Output is generic without PRODUCT.md.
|
||||
|
||||
Filename matching is case-insensitive for both. Legacy `.impeccable.md` auto-migrates to `PRODUCT.md` on first load. **DESIGN.md wins on visual decisions; PRODUCT.md wins on strategic/voice decisions.**
|
||||
|
||||
### 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`.** The same applies to DESIGN.md if you loaded it earlier. 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 — load the fresh version).
|
||||
- You just ran `/impeccable document` (DESIGN.md was written or updated — load the fresh version).
|
||||
- The user says they've manually edited PRODUCT.md or DESIGN.md.
|
||||
|
||||
### First-time load
|
||||
|
||||
When the protocol fires (no prior load in this session, no exception above), run the shared loader:
|
||||
Load both in one call:
|
||||
|
||||
```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.
|
||||
Consume the full JSON output. Never pipe through `head`, `tail`, `grep`, or `jq`.
|
||||
|
||||
### Dispatch on result
|
||||
**If the content is already in this session's conversation history, do NOT re-run.** Re-fetching wastes thousands of tokens. Exceptions: you just ran `/impeccable teach` or `/impeccable document`, or the user manually edited a file.
|
||||
|
||||
- **`hasProduct: true` AND the content is substantive** (>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
|
||||
<spatial_principles>
|
||||
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.
|
||||
</spatial_principles>
|
||||
|
||||
<spatial_rules>
|
||||
@@ -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 <command>` or `unpin <command>`:
|
||||
|
||||
**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 <command>` or `unpin <command>`, run:
|
||||
```bash
|
||||
node {{scripts_path}}/pin.mjs <pin|unpin> <command>
|
||||
```
|
||||
|
||||
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).
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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.
|
||||
@@ -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}}<command>` invokes `{{command_prefix}}impeccable <command>` 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 <command>
|
||||
node {{scripts_path}}/pin.mjs unpin <command>
|
||||
```
|
||||
|
||||
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.
|
||||
Reference in New Issue
Block a user