Kjell Tore Guttormsen
7d604309ae
Docs pass for Wave 2. README now documents nine phases rather than eight,
carries a Phase 9 row in the phase table and a Phase 9 paragraph in the
slides walkthrough, lists 05-critique-iterate.md among the foundation
references (6, not 5; 14 reference files, not 13), and uses the namespaced
design:critique / design:accessibility / design:handoff tokens the live
plugin actually exposes.
Two stale claims corrected, both measured 2026-08-18:
- Assertion (i) was described as a recursive grep that excludes the local
files by name. Since 3696b8e it is a per-file grep over a git-derived
shipped set (git check-ignore), so no name list exists to maintain.
- Marketplace context claimed this plugin has no separate git repository and
no separate remote. git rev-parse --show-toplevel resolves to the plugin
directory, origin is open/claude-design.git, and the sibling catalog/ is a
separate repository. The docs-triple rule is narrowed accordingly: the
catalog README is updated in the catalog repository at release time, never
from here.
Also fixes a mis-numbered layer list in the README walkthrough, which named
start-simple as Layer 2 and the AI-slop avoid-list as Layer 4. The real
numbering in 01-prompt-fundamentals.md is Layer 1, 1.5, 2a, 2b, 3, 4, 5.
No version bump, no tag, no CHANGELOG entry — Step 9 owns those.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NaybqQwqirrNmikJsUrbDg
88 lines
8.6 KiB
Markdown
88 lines
8.6 KiB
Markdown
# claude-design
|
||
|
||
## Context
|
||
|
||
This plugin is an expert on **Claude Design** (`claude.ai/design`) — Anthropic's Labs research preview for generating interactive design artifacts from a prompt. It walks the operator through the full lifecycle: idea → intent-preset selection → audience and destination → DESIGN.md anchor → five-layer prompt drafting → copy-paste delivery → iteration coaching → ship-readiness handoff. It does not generate artifact code itself and it does not drive the browser; it produces the prompt that the operator pastes into Claude Design.
|
||
|
||
## Status
|
||
|
||
`v0.1.0`. Surface:
|
||
|
||
- One skill: `claude-design-facilitator` (auto-fire + explicit `/claude-design-facilitator` slash command)
|
||
- Six foundation references under `skills/claude-design-facilitator/references/`
|
||
- Eight per-preset references under `skills/claude-design-facilitator/references/presets/`
|
||
- Five test scripts under `tests/` plus a `verify.sh` roll-up
|
||
- A `.coverage.md` preset manifest at the plugin root (canonical input for SC2 and the SC3 Authoritative-claims registry)
|
||
- `LICENSE` (MIT), `GOVERNANCE.md` (marketplace fork-and-own blurb), `README.md`, `CHANGELOG.md`
|
||
|
||
No commands, no agents, no hooks, no MCP servers at v0.1. The single skill is the entire user-facing surface.
|
||
|
||
## Marketplace context
|
||
|
||
This plugin sits under the `ktg-plugin-marketplace` directory but is **its own git repository** with its own Forgejo remote at `ssh://git@git.fromaitochitta.com/open/claude-design.git` (measured 2026-08-18: `git rev-parse --show-toplevel` resolves to the plugin directory). The marketplace is a polyrepo — the sibling `catalog/` directory is a separate repository that pins each plugin to a release tag. All commits for this plugin go to this repository's `origin/main`, never to a marketplace-wide repository.
|
||
|
||
Marketplace conventions inherited from the root `CLAUDE.md`:
|
||
|
||
- Conventional Commits — `type(scope): description`; scope is `claude-design`
|
||
- Hooks in Node.js (`.mjs`), never bash (this plugin ships no hooks at v0.1)
|
||
- Zero npm dependencies in hooks and scripts
|
||
- Docs updated in the same commit on every feature change: plugin `README.md` + plugin `CLAUDE.md`. The catalog `README.md` is the third leg of the marketplace docs-triple, but it lives in the separate `catalog/` repository and is updated there at release time — see Workflow below.
|
||
|
||
## Architecture (v0.1)
|
||
|
||
- **`skills/claude-design-facilitator/SKILL.md`** is the auto-fire entry point AND the explicit `/claude-design-facilitator` invocation surface. The skill body documents the nine-phase facilitation flow. Phase 9 (critique-iterate) is optional and opt-out; the other eight run in order.
|
||
- **`skills/claude-design-facilitator/.triggers.txt`** lists the natural-language phrases the skill auto-fires on. `tests/test-skill-triggers.sh` validates every phrase appears in the SKILL.md description.
|
||
- **`skills/claude-design-facilitator/references/`** is the knowledge base. Six foundation references (00–05) plus eight per-preset references under `references/presets/`. Each per-preset file also carries a thin `Critique-iterate hint` block naming which `design-critique` sections dominate for that artifact type and which real prompt layer in `01-prompt-fundamentals.md` those findings route to; the shared Phase 9 mechanics live once in `05-critique-iterate.md`. The heading letter of that block is per-file, not uniform — four presets end at `## (e)` and four at `## (f)` — so the canonical machine-checkable anchor is the letter-free substring `Critique-iterate hint`, never the letter. Every authoritative claim cites an Anthropic primary source inline.
|
||
- **`.coverage.md`** at the plugin root is the SC2 manifest (preset enumeration with evidence-grade labels) and the SC3 Authoritative-claims registry (bullet list of files that must carry Anthropic-domain citations).
|
||
- **`tests/`** + **`verify.sh`** enforce the brief Success Criteria: SC1 dogfood-log format, SC2 per-preset coverage, SC3 citation discipline, plus skill description quality and plugin structural integrity.
|
||
|
||
The skill body never offers to generate artifact code, automate the browser, or store artifact history (per [Non-Goals in README](README.md)). It produces prompts.
|
||
|
||
## Scope fence
|
||
|
||
This plugin covers **pre-design and during-design** for `claude.ai/design`: idea → prompt → preview → iterate → ship-readiness.
|
||
|
||
**Post-design** — critique, accessibility audit, UX copy review, research synthesis, design-system audit, engineering handoff — is out of scope and lives in Anthropic's official `knowledge-work-plugins/design` (`https://claude.com/plugins/design`). This plugin must never duplicate the commands `/critique`, `/accessibility`, `/ux-copy`, `/research-synthesis`, `/design-system`, `/handoff` — with or without a `claude-design:` namespace prefix. `tests/validate-plugin.sh` assertion (h) enforces this scope fence mechanically.
|
||
|
||
The lifecycle-stage coverage map and the operational handoff between the two plugins are documented in `skills/claude-design-facilitator/references/04-handoff-and-scope.md`.
|
||
|
||
## Authoring rules
|
||
|
||
Every contribution to this plugin must respect these rules:
|
||
|
||
- **Language: English everywhere.** Plugin file content — `README.md`, `CLAUDE.md` (this file), `CHANGELOG.md`, `SKILL.md`, all `references/*.md`, all `tests/*.sh` output messages, every code comment — is English. This is the operator override of the marketplace's default Norwegian-dialogue policy; documented in the v0.1 brief. The `tests/validate-plugin.sh` assertion (j) emits a WARN on Norwegian diacritics in shipped content; review case-by-case (citation slugs occasionally legitimately carry diacritics, but the default is zero hits).
|
||
- **No operator-private context in shipped content.** No personal-name or organization-affiliation tokens, no copy-paste from local session-state and handoff files. `tests/validate-plugin.sh` assertion (i) enforces this with a per-file grep over a git-derived shipped set: a file counts as shipped unless `git check-ignore` says it is ignored. Gitignored files are by definition not shipped, whatever they are named, so no name list has to be maintained.
|
||
- **Evidence-grade label discipline.** Every per-preset reference file carries an inline `Evidence grade:` label on line 4. The three grades are `Anthropic-documented + community-validated`, `Community-only`, and `Experimental`. `.coverage.md` is the canonical registry. SC2 and SC3 read from `.coverage.md` directly — keep it in sync.
|
||
- **URL canonicalisation.** All `support.claude.com` references use the form `https://support.claude.com/en/articles/<numeric-id>-<slug>`. Numeric IDs are stable across slug rewrites; slug-only URLs are not. `https://anthropic.com/news/...` and `https://claude.com/blog/...` follow whatever slug Anthropic publishes.
|
||
- **No NIH of Anthropic surfaces.** The plugin recommends Anthropic's `knowledge-work-plugins/design` as the downstream tool; it does not duplicate that plugin's functionality.
|
||
|
||
## Workflow
|
||
|
||
The Voyage pipeline produces v0.1 and every subsequent feature change:
|
||
|
||
1. **Brief** closes scope and scope boundaries
|
||
2. **Research** gathers external sources — Anthropic primary material (news posts, support articles, blog posts, open-source skills, tutorials, plugins), plus community practitioners with attribution
|
||
3. **Plan** specifies file-by-file what gets built
|
||
4. **Execute** delivers the code and content
|
||
5. **Review** is the release gate (`/trekreview`)
|
||
|
||
Voyage policy: Opus across all sub-agents and orchestrator phases (per `feedback_voyage_opus_always`).
|
||
|
||
For incremental content updates that do not warrant a full Voyage iteration (e.g., refreshing a single per-preset reference when Anthropic publishes new guidance), the docs rule still applies: plugin `README.md` + plugin `CLAUDE.md` (this file) updated in the same commit as the content change. The third leg of the marketplace docs-triple — the catalog `README.md` — lives in the separate `catalog/` repository and is updated there at release time, when the catalog `ref` is bumped to the new tag. It is never edited from this repository.
|
||
|
||
## Communication patterns
|
||
|
||
### Linking to local files
|
||
|
||
When pointing to local files in responses, always use markdown link syntax with a descriptive name:
|
||
|
||
- Use `[Human-friendly name](file:///absolute/path)` — never bare `file:///...` URLs or autolinks `<file://...>`.
|
||
- Always use absolute paths. Never `~/` or relative paths.
|
||
- For multiple files, render as a bullet list of named markdown links.
|
||
|
||
Why: bare `file://` URLs only render the first as clickable across multiple lines. Named markdown links make each entry independently clickable and look cleaner.
|
||
|
||
Example:
|
||
|
||
- [Brief](file:///Users/ktg/.../brief.html)
|
||
- [Research summary](file:///Users/ktg/.../research/summary.md)
|