@etus/seven-skill 0.1.0-beta.1

package/README.md

@@ -0,0 +1,118 @@
+# @etus/seven-skill
+
+Seven Design System skill, plugin, and CLI detector for AI coding agents.
+
+This package distributes the Seven Design System guard-rails as a Claude Code plugin and a deterministic CLI detector. Phase 2 expands to Cursor, Codex, Gemini, OpenCode, and other AI harnesses.
+
+## What ships
+
+- **Skill source-of-truth** under `source/`: the routing `SKILL.md` plus domain references for typography, color, motion, spatial design, voice, and the Phase 1 sub-commands (`shape`, `audit`, `polish`, `clarify`).
+- **Multi-harness build pipeline** in `build/` that emits one configured skill per target harness. Phase 1 ships Claude Code only at `.claude/skills/seven/`.
+- **Claude Code plugin** wrapper in `.claude-plugin/` with `plugin.json` and `marketplace.json` auto-synced from `package.json`.
+- **Deterministic CLI detector** in `cli/` with 35 Seven-tuned rules (`npx seven detect <path>`).
+
+## Status
+
+Phase 1 — hardened Claude Code port. Claude Code target only, 35 detector rules, four sub-commands. Distributed as a Claude Code plugin via the marketplace configuration in this package and as an npm CLI/skill package.
+
+## Install
+
+### Claude Code plugin (recommended)
+
+The plugin is configured by `.claude-plugin/marketplace.json` and `.claude-plugin/plugin.json` in this package. Inside the Seven monorepo it is available as a workspace dependency:
+
+```bash
+pnpm add -D @etus/seven-skill --workspace
+```
+
+For external projects, install the package or point the plugin manifest at the git source:
+
+```bash
+pnpm add -D @etus/seven-skill
+claude plugin install @etus/seven-skill
+
+# Git source fallback while marketplace propagation catches up:
+claude plugin install github:etusdigital/seven#path=packages/seven-skill
+```
+
+### CLI detector
+
+Inside the monorepo:
+
+```bash
+pnpm --filter @etus/seven-skill exec seven detect packages/ui/src/
+```
+
+## Commands (Phase 1)
+
+| Command          | Purpose                                                                    |
+| ---------------- | -------------------------------------------------------------------------- |
+| `/seven shape`   | Plan UX shape before writing component code                                |
+| `/seven audit`   | Five-dimension scan: a11y, performance, theming, responsive, anti-patterns |
+| `/seven polish`  | Final-pass cleanup aligned to Seven tokens and conventions                 |
+| `/seven clarify` | UX copy in pt-BR: imperative leads, sentence case, no trailing periods     |
+
+Phase 2 adds `craft`, `harden`, `layout`, `typeset`.
+
+## Detector rules
+
+The detector ships 35 rules across three engines (regex, static-html,
+browser). Each rule is `quality` (real design / a11y drift) or `slop` (an
+AI tell, Seven-flavored). The full catalog — every rule with its
+justification, a wrong/right example, and the design reference that grounds
+it — is in [`docs/detector-rules.md`](./docs/detector-rules.md).
+
+**Token-aware.** Eight rules are grounded in Seven's real design tokens: a
+build step (`build:tokens`) reads `@etus/tokens` and embeds a token-data
+snapshot, so `hardcoded-color-not-token` names the exact token a literal
+maps to, `non-inter-font` reads the font tokens, `radius-mixed-scales` reads
+the radius scale, and `bounce-easing` knows the sanctioned easing tokens.
+When `@etus/tokens` rebuilds from a Figma sync, regenerate the snapshot. The
+other 27 rules are heuristics — language facts, CSS mechanics, and a11y
+standards no token defines. Each rule's verdict is in `RULE_GROUNDING`.
+
+Quick map: nine text rules (`non-inter-font`, `hardcoded-color-not-token`,
+`raw-tailwind-palette-color`, `missing-color-type-hint`,
+`missing-length-type-hint`, `leading-none-with-length-var`,
+`fuchsia-in-ui-chrome`, `pt-pt-vocab`, `pure-black-or-white`); three
+inverted from impeccable (`side-stripe-border`, `gradient-text-decorative`,
+`shadows-not-borders`); seventeen universal design-quality / a11y rules; six
+Seven-specific element rules (`missing-tactile-press`, `pill-on-button`,
+`radius-mixed-scales`, `non-lucide-icon`, `emoji-in-chrome`,
+`forbidden-em-dash`).
+
+Exit codes follow the impeccable convention: `0` clean, `2` findings present, `1` usage error.
+
+## Architecture
+
+```
+packages/seven-skill/
+├── source/                # authoring source (not shipped to npm)
+│   ├── SKILL.md           # router + shared design laws
+│   ├── reference/         # domain + sub-command references
+│   └── scripts/           # consumer-side runtime scripts (Phase 2)
+├── build/                 # multi-harness build pipeline (not shipped)
+├── cli/                   # deterministic detector (shipped)
+├── .claude/skills/seven/  # Claude Code build output (shipped, tracked)
+├── .claude-plugin/        # Claude Code plugin wrapper (shipped)
+└── tests/                 # unit + fixture tests
+```
+
+Author in `source/`. Run `pnpm --filter @etus/seven-skill build` to regenerate the per-harness skill outputs and the plugin manifest.
+
+## Development
+
+```bash
+pnpm --filter @etus/seven-skill build       # regenerate harness output and manifests
+pnpm --filter @etus/seven-skill test        # vitest unit + fixture suite
+pnpm --filter @etus/seven-skill typecheck   # tsc strict mode
+
+# Detector usage
+pnpm --filter @etus/seven-skill exec seven detect path/to/file-or-dir
+pnpm --filter @etus/seven-skill exec seven detect packages/ui/src/ --json
+pnpm --filter @etus/seven-skill exec seven help
+```
+
+## License
+
+Apache-2.0. See `LICENSE`.