@bastani/atomic 0.7.17-1 → 0.8.0-0

package/dist/builtin/workflows/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "@bastani/workflows",
+  "version": "0.8.0-0",
+  "private": true,
+  "description": "pi extension for multi-stage workflow authoring and execution.",
+  "contributors": [
+    "Norin Lavaee",
+    "Alex Lavaee"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./builtin": "./builtin/index.ts",
+    "./builtin/*": "./builtin/*.ts"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/flora131/atomic.git",
+    "directory": "packages/workflows"
+  },
+  "homepage": "https://github.com/flora131/atomic/tree/main/packages/workflows#readme",
+  "bugs": {
+    "url": "https://github.com/flora131/atomic/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "workflow",
+    "orchestration",
+    "ai",
+    "cli"
+  ],
+  "files": [
+    "src/**/*.ts",
+    "builtin/**/*.ts",
+    "skills/**/*",
+    "prompts/**/*",
+    "themes/*.json",
+    "assets/**/*",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "bun run test:unit",
+    "test:unit": "bun test ../../test/unit",
+    "test:integration": "bun test ../../test/integration",
+    "test:all": "bun run test:unit && bun run test:integration",
+    "typecheck": "tsc --noEmit -p ../../tsconfig.json",
+    "lint": "tsc --noEmit -p ../../tsconfig.json"
+  },
+  "pi": {
+    "extensions": [
+      "./src/extension/index.ts"
+    ],
+    "builtin": [
+      "./builtin"
+    ],
+    "skills": [
+      "./skills"
+    ],
+    "prompts": [],
+    "themes": [
+      "themes/*.json"
+    ]
+  },
+  "peerDependencies": {
+    "@bastani/atomic": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "peerDependenciesMeta": {
+    "@bastani/atomic": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    }
+  }
+}

package/dist/builtin/workflows/skills/create-spec/SKILL.md

@@ -0,0 +1,247 @@
+---
+name: create-spec
+description: Create a detailed execution plan/spec/prd for implementing features or refactors in a codebase by leveraging existing research in the codebase.
+---
+
+You are tasked with creating a spec for implementing a new feature or system change in the codebase by leveraging existing research in the **$ARGUMENTS** path. If no research path is specified, use the entire `research/` directory. IMPORTANT: Research documents are located in the `research/` directory — do NOT look in the `specs/` directory for research. Follow the template below to produce a comprehensive specification as output in the `specs/` folder using the findings from RELEVANT research documents found in `research/`. The spec file MUST be named using the format `YYYY-MM-DD-topic.md` (e.g., `specs/2026-03-26-my-feature.md`), where the date is the current date and the topic is a kebab-case summary. Tip: It's good practice to use the `codebase-research-locator` and `codebase-research-analyzer` agents to help you find and analyze the research documents in the `research/` directory. It is also HIGHLY recommended to cite relevant research throughout the spec for additional context.
+
+<EXTREMELY_IMPORTANT>
+
+- Please use your AskUserQuestion tool to provide a rich interface to ask the user for their input on a question.
+- Please DO NOT implement anything in this stage, just create the comprehensive spec as described below.
+- When writing the spec, DO NOT include information about concrete dates/timelines (e.g. # minutes, hours, days, weeks, etc.) and favor explicit phases (e.g. Phase 1, Phase 2, etc.).
+- Once the spec is generated ask questions one at a time OR in logical groups:
+  - Refer to section "## 9. Open Questions / Unresolved Issues", go through each question one by one, and use **contrastive clarification** (presenting 2-3 specific options with concrete tradeoffs) rather than open-ended questions. This means presenting interpretations like "(A) Option X — tradeoff Y" and "(B) Option Z — tradeoff W" instead of asking "what do you think about X?". Update the spec with the user's answers as you walk through the questions.
+  - Interview the user relentlessly about every aspect of this plan/spec until you reach a shared understanding with them. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer (i.e., **contrastive clarification**).
+  - If a question can be answered by exploring the codebase, explore the codebase instead and confirm with the user that this is their inferred intent.
+- Finally, once the spec is generated and after open questions are answered, provide an executive summary of the spec to the user including the path to the generated spec document in the `specs/` directory.
+    - Encourage the user to review the spec for best results and provide feedback or ask any follow-up questions they may have.
+
+</EXTREMELY_IMPORTANT>
+
+# [Project Name] Technical Design Document / RFC
+
+| Document Metadata      | Details                                                                        |
+| ---------------------- | ------------------------------------------------------------------------------ |
+| Author(s)              | !`git config user.name`                                                        |
+| Status                 | Draft (WIP) / In Review (RFC) / Approved / Implemented / Deprecated / Rejected |
+| Team / Owner           |                                                                                |
+| Created / Last Updated |                                                                                |
+
+## 1. Executive Summary
+
+_Instruction: A "TL;DR" of the document. Assume the reader is a VP or an engineer from another team who has 2 minutes. Summarize the Context (Problem), the Solution (Proposal), and the Impact (Value). Keep it under 200 words._
+
+> **Example:** This RFC proposes replacing our current nightly batch billing system with an event-driven architecture using Kafka and AWS Lambda. Currently, billing delays cause a 5% increase in customer support tickets. The proposed solution will enable real-time invoicing, reducing billing latency from 24 hours to <5 minutes.
+
+## 2. Context and Motivation
+
+_Instruction: Why are we doing this? Why now? Link to the Product Requirement Document (PRD)._
+
+### 2.1 Current State
+
+_Instruction: Describe the existing architecture. Use a "Context Diagram" if possible. Be honest about the flaws._
+
+- **Architecture:** Currently, Service A communicates with Service B via a shared SQL database.
+- **Limitations:** This creates a tight coupling; when Service A locks the table, Service B times out.
+
+### 2.2 The Problem
+
+_Instruction: What is the specific pain point?_
+
+- **User Impact:** Customers cannot download receipts during the nightly batch window.
+- **Business Impact:** We are losing $X/month in churn due to billing errors.
+- **Technical Debt:** The current codebase is untestable and has 0% unit test coverage.
+
+## 3. Goals and Non-Goals
+
+_Instruction: This is the contract Definition of Success. Be precise._
+
+### 3.1 Functional Goals
+
+- [ ] Users must be able to export data in CSV format.
+- [ ] System must support multi-tenant data isolation.
+
+### 3.2 Non-Goals (Out of Scope)
+
+_Instruction: Explicitly state what you are NOT doing. This prevents scope creep._
+
+- [ ] We will NOT support PDF export in this version (CSV only).
+- [ ] We will NOT migrate data older than 3 years.
+- [ ] We will NOT build a custom UI (API only).
+
+## 4. Proposed Solution (High-Level Design)
+
+_Instruction: The "Big Picture." Diagrams are mandatory here._
+
+### 4.1 System Architecture Diagram
+
+_Instruction: Insert a C4 System Context or Container diagram. Show the "Black Boxes."_
+
+- (Place Diagram Here - e.g., Mermaid diagram)
+
+For example,
+
+```mermaid
+%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#f8f9fa','primaryTextColor':'#2c3e50','primaryBorderColor':'#4a5568','lineColor':'#4a90e2','secondaryColor':'#ffffff','tertiaryColor':'#e9ecef','background':'#f5f7fa','mainBkg':'#f8f9fa','nodeBorder':'#4a5568','clusterBkg':'#ffffff','clusterBorder':'#cbd5e0','edgeLabelBackground':'#ffffff'}}}%%
+
+flowchart TB
+    %% ---------------------------------------------------------
+    %% CLEAN ENTERPRISE DESIGN
+    %% Professional • Trustworthy • Corporate Standards
+    %% ---------------------------------------------------------
+
+    %% STYLE DEFINITIONS
+    classDef person fill:#5a67d8,stroke:#4c51bf,stroke-width:3px,color:#ffffff,font-weight:600,font-size:14px
+
+    classDef systemCore fill:#4a90e2,stroke:#357abd,stroke-width:2.5px,color:#ffffff,font-weight:600,font-size:14px
+
+    classDef systemSupport fill:#667eea,stroke:#5a67d8,stroke-width:2.5px,color:#ffffff,font-weight:600,font-size:13px
+
+    classDef database fill:#48bb78,stroke:#38a169,stroke-width:2.5px,color:#ffffff,font-weight:600,font-size:13px
+
+    classDef external fill:#718096,stroke:#4a5568,stroke-width:2.5px,color:#ffffff,font-weight:600,font-size:13px,stroke-dasharray:6 3
+
+    %% NODES - CLEAN ENTERPRISE HIERARCHY
+
+    User(("◉<br><b>User</b><br>")):::person
+
+    subgraph SystemBoundary["◆ Primary System Boundary"]
+        direction TB
+
+        LoadBalancer{{"<b>Load Balancer</b><br>NGINX<br><i>Layer 7 Proxy</i>"}}:::systemCore
+
+        API["<b>API Application</b><br>Go • Gin Framework<br><i>REST Endpoints</i>"]:::systemCore
+
+        Worker(["<b>Background Worker</b><br>Go Runtime<br><i>Async Processing</i>"]):::systemSupport
+
+        Cache[("◆<br><b>Cache Layer</b><br>Redis<br><i>In-Memory</i>")]:::database
+
+        PrimaryDB[("●<br><b>Primary Database</b><br>PostgreSQL<br><i>Persistent Storage</i>")]:::database
+    end
+
+    ExternalAPI{{"<b>External API</b><br>Third Party<br><i>HTTP/REST</i>"}}:::external
+
+    %% RELATIONSHIPS - CLEAN FLOW
+
+    User -->|"1. HTTPS Request<br>TLS 1.3"| LoadBalancer
+    LoadBalancer -->|"2. Proxy Pass<br>Round Robin"| API
+
+    API <-->|"3. Cache<br>Read/Write"| Cache
+    API -->|"4. Persist Data<br>Transactional"| PrimaryDB
+    API -.->|"5. Enqueue Event<br>Async"| Worker
+
+    Worker -->|"6. Process Job<br>Execution"| PrimaryDB
+    Worker -.->|"7. HTTP Call<br>Webhooks"| ExternalAPI
+
+    %% STYLE BOUNDARY
+    style SystemBoundary fill:#ffffff,stroke:#cbd5e0,stroke-width:2px,color:#2d3748,stroke-dasharray:8 4,font-weight:600,font-size:12px
+```
+
+### 4.2 Architectural Pattern
+
+_Instruction: Name the pattern (e.g., "Event Sourcing", "BFF - Backend for Frontend")._
+
+- We are adopting a Publisher-Subscriber pattern where the Order Service publishes `OrderCreated` events, and the Billing Service consumes them asynchronously.
+
+### 4.3 Key Components
+
+| Component         | Responsibility              | Technology Stack  | Justification                                |
+| ----------------- | --------------------------- | ----------------- | -------------------------------------------- |
+| Ingestion Service | Validates incoming webhooks | Go, Gin Framework | High concurrency performance needed.         |
+| Event Bus         | Decouples services          | Kafka             | Durable log, replay capability.              |
+| Projections DB    | Read-optimized views        | MongoDB           | Flexible schema for diverse receipt formats. |
+
+## 5. Detailed Design
+
+_Instruction: The "Meat" of the document. Sufficient detail for an engineer to start coding._
+
+### 5.1 API Interfaces
+
+_Instruction: Define the contract. Use OpenAPI/Swagger snippets or Protocol Buffer definitions._
+
+**Endpoint:** `POST /api/v1/invoices`
+
+- **Auth:** Bearer Token (Scope: `invoice:write`)
+- **Idempotency:** Required header `X-Idempotency-Key`
+- **Request Body:**
+
+```json
+{ "user_id": "uuid", "amount": 100.0, "currency": "USD" }
+```
+
+### 5.2 Data Model / Schema
+
+_Instruction: Provide ERDs (Entity Relationship Diagrams) or JSON schemas. Discuss normalization vs. denormalization._
+
+**Table:** `invoices` (PostgreSQL)
+
+| Column    | Type | Constraints       | Description           |
+| --------- | ---- | ----------------- | --------------------- |
+| `id`      | UUID | PK                |                       |
+| `user_id` | UUID | FK -> Users       | Partition Key         |
+| `status`  | ENUM | 'PENDING', 'PAID' | Indexed for filtering |
+
+### 5.3 Algorithms and State Management
+
+_Instruction: Describe complex logic, state machines, or consistency models._
+
+- **State Machine:** An invoice moves from `DRAFT` -> `LOCKED` -> `PROCESSING` -> `PAID`.
+- **Concurrency:** We use Optimistic Locking on the `version` column to prevent double-payments.
+
+## 6. Alternatives Considered
+
+_Instruction: Prove you thought about trade-offs. Why is your solution better than the others?_
+
+| Option                           | Pros                               | Cons                                      | Reason for Rejection                                                          |
+| -------------------------------- | ---------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------- |
+| Option A: Synchronous HTTP Calls | Simple to implement, Easy to debug | Tight coupling, cascading failures        | Latency requirements (200ms) make blocking calls risky.                       |
+| Option B: RabbitMQ               | Lightweight, Built-in routing      | Less durable than Kafka, harder to replay | We need message replay for auditing (Compliance requirement).                 |
+| Option C: Kafka (Selected)       | High throughput, Replayability     | Operational complexity                    | **Selected:** The need for auditability/replay outweighs the complexity cost. |
+
+## 7. Cross-Cutting Concerns
+
+### 7.1 Security and Privacy
+
+- **Authentication:** Services authenticate via mTLS.
+- **Authorization:** Policy enforcement point at the API Gateway (OPA - Open Policy Agent).
+- **Data Protection:** PII (Names, Emails) is encrypted at rest using AES-256.
+- **Threat Model:** Primary threat is compromised API Key; remediation is rapid rotation and rate limiting.
+
+### 7.2 Observability Strategy
+
+- **Metrics:** We will track `invoice_creation_latency` (Histogram) and `payment_failure_count` (Counter).
+- **Tracing:** All services propagate `X-Trace-ID` headers (OpenTelemetry).
+- **Alerting:** PagerDuty triggers if `5xx` error rate > 1% for 5 minutes.
+
+### 7.3 Scalability and Capacity Planning
+
+- **Traffic Estimates:** 1M transactions/day = ~12 TPS avg / 100 TPS peak.
+- **Storage Growth:** 1KB per record \* 1M = 1GB/day.
+- **Bottleneck:** The PostgreSQL Write node is the bottleneck. We will implement Read Replicas to offload traffic.
+
+## 8. Migration, Rollout, and Testing
+
+### 8.1 Deployment Strategy
+
+- [ ] Phase 1: Deploy services in "Shadow Mode" (process traffic but do not email users).
+- [ ] Phase 2: Enable Feature Flag `new-billing-engine` for 1% of internal users.
+- [ ] Phase 3: Ramp to 100%.
+
+### 8.2 Data Migration Plan
+
+- **Backfill:** We will run a script to migrate the last 90 days of invoices from the legacy SQL server.
+- **Verification:** A "Reconciliation Job" will run nightly to compare Legacy vs. New totals.
+
+### 8.3 Test Plan
+
+- **Unit Tests:**
+- **Integration Tests:**
+- **End-to-End Tests:**
+
+## 9. Open Questions / Unresolved Issues
+
+_Instruction: List known unknowns. These must be resolved before the doc is marked "Approved"._
+
+- [ ] Will the Legal team approve the 3rd party library for PDF generation?
+- [ ] Does the current VPC peering allow connection to the legacy mainframe?

package/dist/builtin/workflows/skills/impeccable/SKILL.md

@@ -0,0 +1,173 @@
+---
+allowed-tools:
+    - Bash(npx impeccable *)
+argument-hint: '[craft|shape · audit|critique · animate|bolder|colorize|delight|layout|overdrive|quieter|typeset · adapt|clarify|distill · harden|onboard|optimize|polish · teach|document|extract|live] [target]'
+description: Use when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, or otherwise improve a frontend interface. Covers websites, landing pages, dashboards, product UI, app shells, components, forms, settings, onboarding, and empty states. Handles UX review, visual hierarchy, information architecture, cognitive load, accessibility, performance, responsive behavior, theming, anti-patterns, typography, fonts, spacing, layout, alignment, color, motion, micro-interactions, UX copy, error states, edge cases, i18n, and reusable design systems or tokens. Also use for bland designs that need to become bolder or more delightful, loud designs that should become quieter, live browser iteration on UI elements, or ambitious visual effects that should feel technically extraordinary. Not for backend-only or non-UI tasks.
+license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution.
+metadata:
+    github-path: plugin/skills/impeccable
+    github-ref: refs/tags/skill-v3.1.0
+    github-repo: https://github.com/pbakaus/impeccable
+    github-tree-sha: 9848f143e82822ddd265d9ff5c6e17403d024cee
+name: impeccable
+user-invocable: true
+version: 3.1.0
+---
+Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft.
+
+## Setup
+
+Before any design work or file edits:
+
+1. Load context (PRODUCT.md / DESIGN.md) via the loader script.
+2. Identify the register and load the matching register reference (brand.md or product.md).
+3. **If the user invoked a sub-command (e.g. `craft`, `shape`, `audit`), load its reference file too.** This is non-negotiable: `craft` without `craft.md` loaded means you'll skip the shape-and-confirm step the user expects.
+
+Skipping these produces generic output that ignores the project.
+
+### 1. Context gathering
+
+Two files, case-insensitive. The loader looks at the project root by default and falls back to `.agents/context/` and `docs/` if the root is clean. Override with `IMPECCABLE_CONTEXT_DIR=path/to/dir` (absolute or relative to cwd).
+
+- **PRODUCT.md**: required. Users, brand, tone, anti-references, strategic principles.
+- **DESIGN.md**: optional, strongly recommended. Colors, typography, elevation, components.
+
+Load both in one call:
+
+```bash
+node .claude/skills/impeccable/scripts/load-context.mjs
+```
+
+Consume the full JSON output. Never pipe through `head`, `tail`, `grep`, or `jq`. The output's `contextDir` field tells you where the files were resolved from.
+
+If the output is already in this session's conversation history, don't re-run. Exceptions requiring a fresh load: you just ran `/impeccable teach` or `/impeccable document` (they rewrite the files), or the user manually edited one.
+
+`/impeccable live` already warms context via `live.mjs`. If you've run `live.mjs`, don't also run `load-context.mjs` this session.
+
+If PRODUCT.md is missing, empty, or placeholder (`[TODO]` markers, <200 chars): run `/impeccable teach`, then resume the user's original task with the fresh context. If the original task was `/impeccable craft`, resume into `/impeccable shape` before any implementation work.
+
+If DESIGN.md is missing: nudge once per session (*"Run `/impeccable document` for more on-brand output"*), then proceed.
+
+### 2. Register
+
+Every design task is **brand** (marketing, landing, campaign, long-form content, portfolio: design IS the product) or **product** (app UI, admin, dashboard, tool: design SERVES the product).
+
+Identify before designing. Priority: (1) cue in the task itself ("landing page" vs "dashboard"); (2) the surface in focus (the page, file, or route being worked on); (3) `register` field in PRODUCT.md. First match wins.
+
+If PRODUCT.md lacks the `register` field (legacy), infer it once from its "Users" and "Product Purpose" sections, then cache the inferred value for the session. Suggest the user run `/impeccable teach` to add the field explicitly.
+
+Load the matching reference: [reference/brand.md](reference/brand.md) or [reference/product.md](reference/product.md). The shared design laws below apply to both.
+
+## Shared design laws
+
+Apply to every design, both registers. Match implementation complexity to the aesthetic vision: maximalism needs elaborate code, minimalism needs precision. Interpret creatively. Vary across projects; never converge on the same choices. Claude is capable of extraordinary work. Don't hold back.
+
+### Color
+
+- Use OKLCH. Reduce chroma as lightness approaches 0 or 100; high chroma at extremes looks garish.
+- Never use `#000` or `#fff`. Tint every neutral toward the brand hue (chroma 0.005–0.01 is enough).
+- Pick a **color strategy** before picking colors. Four steps on the commitment axis:
+  - **Restrained**: tinted neutrals + one accent ≤10%. Product default; brand minimalism.
+  - **Committed**: one saturated color carries 30–60% of the surface. Brand default for identity-driven pages.
+  - **Full palette**: 3–4 named roles, each used deliberately. Brand campaigns; product data viz.
+  - **Drenched**: the surface IS the color. Brand heroes, campaign pages.
+- The "one accent ≤10%" rule is Restrained only. Committed / Full palette / Drenched exceed it on purpose. Don't collapse every design to Restrained by reflex.
+
+### Theme
+
+Dark vs. light is never a default. Not dark "because tools look cool dark." Not light "to be safe."
+
+Before choosing, write one sentence of physical scene: who uses this, where, under what ambient light, in what mood. If the sentence doesn't force the answer, it's not concrete enough. Add detail until it does.
+
+"Observability dashboard" does not force an answer. "SRE glancing at incident severity on a 27-inch monitor at 2am in a dim room" does. Run the sentence, not the category.
+
+### Typography
+
+- Cap body line length at 65–75ch.
+- Hierarchy through scale + weight contrast (≥1.25 ratio between steps). Avoid flat scales.
+
+### Layout
+
+- Vary spacing for rhythm. Same padding everywhere is monotony.
+- Cards are the lazy answer. Use them only when they're truly the best affordance. Nested cards are always wrong.
+- Don't wrap everything in a container. Most things don't need one.
+
+### Motion
+
+- Don't animate CSS layout properties.
+- Ease out with exponential curves (ease-out-quart / quint / expo). No bounce, no elastic.
+
+### Absolute bans
+
+Match-and-refuse. If you're about to write any of these, rewrite the element with different structure.
+
+- **Side-stripe borders.** `border-left` or `border-right` greater than 1px as a colored accent on cards, list items, callouts, or alerts. Never intentional. Rewrite with full borders, background tints, leading numbers/icons, or nothing.
+- **Gradient text.** `background-clip: text` combined with a gradient background. Decorative, never meaningful. Use a single solid color. Emphasis via weight or size.
+- **Glassmorphism as default.** Blurs and glass cards used decoratively. Rare and purposeful, or nothing.
+- **The hero-metric template.** Big number, small label, supporting stats, gradient accent. SaaS cliché.
+- **Identical card grids.** Same-sized cards with icon + heading + text, repeated endlessly.
+- **Modal as first thought.** Modals are usually laziness. Exhaust inline / progressive alternatives first.
+
+### Copy
+
+- Every word earns its place. No restated headings, no intros that repeat the title.
+- **No em dashes.** Use commas, colons, semicolons, periods, or parentheses. Also not `--`.
+
+### The AI slop test
+
+If someone could look at this interface and say "AI made that" without doubt, it's failed. Cross-register failures are the absolute bans above. Register-specific failures live in each reference.
+
+**Category-reflex check.** Run at two altitudes; the second one catches what the first one misses.
+
+- **First-order:** if someone could guess the theme + palette from the category alone ("observability → dark blue", "healthcare → white + teal", "finance → navy + gold", "crypto → neon on black"), it's the first training-data reflex. Rework the scene sentence and color strategy until the answer isn't obvious from the domain.
+- **Second-order:** if someone could guess the aesthetic family from category-plus-anti-references ("AI workflow tool that's not SaaS-cream → editorial-typographic", "fintech that's not navy-and-gold → terminal-native dark mode"), it's the trap one tier deeper. The first reflex was avoided; the second wasn't. Rework until both answers are not obvious. The brand register's [reflex-reject aesthetic lanes](reference/brand.md) list catches the currently-saturated families.
+
+## Commands
+
+| Command | Category | Description | Reference |
+|---|---|---|---|
+| `craft [feature]` | Build | Shape, then build a feature end-to-end | [reference/craft.md](reference/craft.md) |
+| `shape [feature]` | Build | Plan UX/UI before writing code | [reference/shape.md](reference/shape.md) |
+| `teach` | Build | Set up PRODUCT.md and DESIGN.md context | [reference/teach.md](reference/teach.md) |
+| `document` | Build | Generate DESIGN.md from existing project code | [reference/document.md](reference/document.md) |
+| `extract [target]` | Build | Pull reusable tokens and components into design system | [reference/extract.md](reference/extract.md) |
+| `critique [target]` | Evaluate | UX design review with heuristic scoring | [reference/critique.md](reference/critique.md) |
+| `audit [target]` | Evaluate | Technical quality checks (a11y, perf, responsive) | [reference/audit.md](reference/audit.md) |
+| `polish [target]` | Refine | Final quality pass before shipping | [reference/polish.md](reference/polish.md) |
+| `bolder [target]` | Refine | Amplify safe or bland designs | [reference/bolder.md](reference/bolder.md) |
+| `quieter [target]` | Refine | Tone down aggressive or overstimulating designs | [reference/quieter.md](reference/quieter.md) |
+| `distill [target]` | Refine | Strip to essence, remove complexity | [reference/distill.md](reference/distill.md) |
+| `harden [target]` | Refine | Production-ready: errors, i18n, edge cases | [reference/harden.md](reference/harden.md) |
+| `onboard [target]` | Refine | Design first-run flows, empty states, activation | [reference/onboard.md](reference/onboard.md) |
+| `animate [target]` | Enhance | Add purposeful animations and motion | [reference/animate.md](reference/animate.md) |
+| `colorize [target]` | Enhance | Add strategic color to monochromatic UIs | [reference/colorize.md](reference/colorize.md) |
+| `typeset [target]` | Enhance | Improve typography hierarchy and fonts | [reference/typeset.md](reference/typeset.md) |
+| `layout [target]` | Enhance | Fix spacing, rhythm, and visual hierarchy | [reference/layout.md](reference/layout.md) |
+| `delight [target]` | Enhance | Add personality and memorable touches | [reference/delight.md](reference/delight.md) |
+| `overdrive [target]` | Enhance | Push past conventional limits | [reference/overdrive.md](reference/overdrive.md) |
+| `clarify [target]` | Fix | Improve UX copy, labels, and error messages | [reference/clarify.md](reference/clarify.md) |
+| `adapt [target]` | Fix | Adapt for different devices and screen sizes | [reference/adapt.md](reference/adapt.md) |
+| `optimize [target]` | Fix | Diagnose and fix UI performance | [reference/optimize.md](reference/optimize.md) |
+| `live` | Iterate | Visual variant mode: pick elements in the browser, generate alternatives | [reference/live.md](reference/live.md) |
+
+Plus two management commands: `pin <command>` and `unpin <command>`, detailed below.
+
+### Routing rules
+
+1. **No argument**: render the table above as the user-facing command menu, grouped by category. Ask what they'd like to do.
+2. **First word matches a command**: load its reference file and follow its instructions. Everything after the command name is the target.
+3. **First word doesn't match**: general design invocation. Apply the setup steps, shared design laws, and the loaded register reference, using the full argument as context.
+
+Setup (context gathering, register) is already loaded by then; sub-commands don't re-invoke `/impeccable`.
+
+If the first word is `craft`, setup still runs first, but [reference/craft.md](reference/craft.md) owns the rest of the flow. If setup invokes `teach` as a blocker, finish teach, refresh context, then resume the original command and target.
+
+## Pin / Unpin
+
+**Pin** creates a standalone shortcut so `/<command>` invokes `/impeccable <command>` directly. **Unpin** removes it. The script writes to every harness directory present in the project.
+
+```bash
+node .claude/skills/impeccable/scripts/pin.mjs <pin|unpin> <command>
+```
+
+Valid `<command>` is any command from the table above. Report the script's result concisely. Confirm the new shortcut on success, relay stderr verbatim on error.