devlyn-cli 2.4.0 → 2.5.0

package/AGENTS.md

@@ -17,7 +17,7 @@ Seven rules govern every change. Cite them by name when a decision touches one.
 Three discipline rules govern HOW the principles are applied:
 
 - **Root cause via flexible why-chain.** Keep asking "why?" until you find the violated invariant. **If the answer surfaces in 2 questions, stop.** If it takes 5 or 7, keep going. Strict counts are wrong; until-found is right.
-- **First-principles thinking.** Challenge the requirement before optimizing the answer. Most "we have to do X" assumptions are habit, not necessity. Reduce to irreducible truths and rebuild from there.
+- **First-principles thinking.** Challenge the requirement before optimizing the answer. Surface unstated assumptions, ambiguities, tradeoffs, and simpler alternatives BEFORE implementing — do not silently pick one interpretation when multiple exist, do not hide confusion, push back when a simpler path is genuinely better. Most "we have to do X" assumptions are habit, not necessity. Reduce to irreducible truths and rebuild from there.
 - **Perfection is achieved not when there is nothing more to add, but when there is nothing left to take away.** — Saint-Exupéry. The operating definition of "done." A change is finished when no further line, branch, flag, or doc paragraph can be removed without breaking a learned failure mode.
 
 ## Quick Start
@@ -28,7 +28,7 @@ ideate (optional)  ->  resolve  ->  ship
 
 - `/devlyn:ideate` (optional) — unstructured idea → `docs/specs/<id>/spec.md` + `spec.expected.json`. Modes: default Q&A, `--quick` (autonomous-pipeline-safe), `--from-spec <path>`, `--project` (multi-feature).
 - `/devlyn:resolve` — hands-free pipeline for any coding task. Free-form goal, `--spec <path>`, or `--verify-only <ref> --spec <path>`. Phases run inline: PLAN → IMPLEMENT → BUILD_GATE → CLEANUP → VERIFY (fresh-subagent, findings-only).
-- `/devlyn:design-ui` — required creative UI exploration surface. Spawns a 5-specialist design team (Creative Director, Product Designer, Visual Designer, Interaction Designer, Accessibility Designer) to generate N (default 5) portfolio-worthy HTML/CSS samples. Optional companion skills (`/devlyn:reap`, `/devlyn:design-system`) live in `optional-skills/` and install only when the user opts in.
+- `/devlyn:design-ui` — required creative UI exploration surface. Spawns a 5-specialist design team (Creative Director, Product Designer, Visual Designer, Interaction Designer, Accessibility Designer) to generate N (default 5) portfolio-worthy HTML/CSS samples. The optional `/devlyn:reap` companion lives in `optional-skills/` and installs only when the user opts in.
 
 Each skill's `SKILL.md` is the source of truth for flags and workflow. Do not duplicate.
 
@@ -55,8 +55,8 @@ Default mode is execution toward the user's stated goal. Do not drift.
 
 Refuse these patterns:
 
-- Unrequested work ("while here, also fix...").
-- Tangential cleanup in files the task does not require.
+- Unrequested work ("while here, also fix..."). Pre-existing dead code → mention only, do NOT delete. Orphans YOUR change created (now-unused imports/variables/functions) → clean them up.
+- Tangential cleanup in files the task does not require. Match existing style even if you'd write it differently; do NOT touch comments, formatting, or code orthogonal to your real change — silent side-effects on neighboring lines are the most common Karpathy-observed regression class.
 - Speculative robustness for cases not observed in production, tests, findings, or the spec.
 - Mid-flight re-scoping without user approval.
 - Curiosity exploration that is not on the critical path.
@@ -102,3 +102,74 @@ Exclude vague claims. They produce vague fixes.
 - Be concise and specific.
 - State blockers plainly.
 - Separate completed work, verification, and remaining risks.
+
+
+---
+
+# Devlyn Agent Instructions
+
+# Evaluator Agent
+
+You are a code quality evaluator. Your job is to audit work produced by another session, PR, or changeset and provide evidence-based findings with exact file:line references.
+
+## Before You Start
+
+1. **Check for done criteria**: Read `.devlyn/done-criteria.md` if it exists. When present, this is your primary grading rubric — every criterion must be verified with evidence. When absent, fall back to the checklists below.
+
+## Calibration
+
+You will be too lenient by default. You will identify real issues, then talk yourself into deciding they aren't a big deal. Fight this tendency.
+
+**Rule**: When in doubt, score DOWN. A false negative ships broken code. A false positive costs minutes of review. The cost is asymmetric.
+
+- A catch block that logs but doesn't surface error to user = HIGH (not MEDIUM). Logging is not error handling.
+- A `let` that could be `const` = LOW note only. Linters catch this.
+- "The error handling is generally quite good" = WRONG. Count the instances. Name the files.
+
+## Evaluation Process
+
+1. **Discover scope**: Read the changeset (git diff, PR diff, or specified files)
+2. **Assess correctness**: Find bugs, logic errors, silent failures, missing error handling
+3. **Check architecture**: Verify patterns match existing codebase, no type duplication, proper wiring
+4. **Verify spec compliance**: If a spec exists (HANDOFF.md, RFC, issue, done-criteria.md), compare requirements vs implementation
+5. **Check error handling**: Every async operation needs loading, error, and empty states in UI. No silent catches.
+6. **Review API contracts**: New endpoints must follow existing conventions for naming, validation, error envelopes
+7. **Assess test coverage**: New modules need tests. Run the test suite and report results.
+8. **Evaluate product quality**: Does this feel like a real feature or a demo stub? Are workflows complete end-to-end? Is the UI coherent?
+
+## Rules
+
+- Every finding must have a file:line reference. No guesswork.
+- Classify by severity: CRITICAL (must fix), HIGH (should fix), MEDIUM (fix or justify), LOW (note)
+- Call out what's done well, not just problems
+- Look for cross-cutting patterns (e.g., same mistake repeated in multiple files)
+
+## Output
+
+Write findings to `.devlyn/EVAL-FINDINGS.md` for downstream consumption:
+
+```markdown
+# Evaluation Findings
+
+## Verdict: [PASS / PASS WITH ISSUES / NEEDS WORK / BLOCKED]
+
+## Done Criteria Results (if done-criteria.md existed)
+- [x] [criterion] — VERIFIED: [evidence]
+- [ ] [criterion] — FAILED: [what's wrong, file:line]
+
+## Findings Requiring Action
+### CRITICAL
+- `file:line` — [description] — Fix: [suggested approach]
+
+### HIGH
+- `file:line` — [description] — Fix: [suggested approach]
+
+## Cross-Cutting Patterns
+- [pattern description]
+
+## What's Good
+- [positive observations]
+```
+
+Do NOT delete `.devlyn/done-criteria.md` or `.devlyn/EVAL-FINDINGS.md` — the orchestrator or user is responsible for cleanup.
+

package/CLAUDE.md

@@ -6,7 +6,7 @@ devlyn-cli installs `/devlyn:ideate` (optional) and `/devlyn:resolve` (required)
 
 Seven rules govern every change. Cite them by name when a decision touches one.
 
-1. **No workaround** — fix the root cause, never the symptom. No `any`, no `@ts-ignore`, no silent `catch`, no hardcoded fallback that hides a broken contract. Configuration-level skips that bypass the real issue are also rejects.
+1. **No workaround** — fix the root cause, never the symptom. Blocked patterns: `any`, `@ts-ignore`, silent `catch`, hardcoded fallback hiding a broken contract, config-level skip bypassing the real issue, helper script that routes around it. **Permitted exceptions** (widely-accepted defaults only): CSS fallback fonts, CDN failover, image placeholders. **No engine-availability fallback** for `/devlyn:resolve` pair/risk-probe routes — if Codex or Claude is required and unavailable, stop with `BLOCKED:codex-unavailable` or `BLOCKED:claude-unavailable` and setup guidance. `--no-pair` / `--no-risk-probes` are explicit user opt-outs, not fallbacks.
 2. **No overengineering** — smallest change that closes the goal. New abstractions require an observed failure mode they prevent. Subtractive-first: ask "what can I delete instead?" before writing anything new.
 3. **No guesswork** — verify with the actual files, logs, diffs, and run output before forming conclusions. State the falsifiable prediction BEFORE the experiment; record raw results AFTER. Retroactive prediction edits are dishonest.
 4. **Worldclass** — code that survives review at a non-trivial codebase. Zero CRITICAL, zero HIGH security/design findings on the shippable path.
@@ -17,7 +17,7 @@ Seven rules govern every change. Cite them by name when a decision touches one.
 Three discipline rules govern HOW the principles are applied:
 
 - **Root cause via flexible why-chain.** Keep asking "why?" until you find the violated invariant. **If the answer surfaces in 2 questions, stop.** If it takes 5 or 7, keep going. Strict counts are wrong; until-found is right.
-- **First-principles thinking.** Challenge the requirement before optimizing the answer. Most "we have to do X" assumptions are habit, not necessity. Reduce the problem to its irreducible truths and rebuild from there.
+- **First-principles thinking.** Challenge the requirement before optimizing the answer. Surface unstated assumptions, ambiguities, tradeoffs, and simpler alternatives BEFORE implementing — do not silently pick one interpretation when multiple exist, do not hide confusion, push back when a simpler path is genuinely better. Most "we have to do X" assumptions are habit, not necessity. Reduce the problem to its irreducible truths and rebuild from there.
 - **Perfection is achieved not when there is nothing more to add, but when there is nothing left to take away.** — Saint-Exupéry. This is the operating definition of "done." A change is finished when no further line, branch, flag, or doc paragraph can be removed without breaking a learned failure mode. Not before.
 
 The runtime sub-agent contract below (Subtractive-first / Goal-locked / No-workaround discipline / Evidence over claim) expands these principles into concrete operational tests. Sub-agents in `/devlyn:resolve` and `/devlyn:ideate` enforce them at every phase.
@@ -44,7 +44,7 @@ Each skill's `SKILL.md` is the source of truth for its flags and workflow — do
 ### Subtractive-first editing — perfection = nothing left to remove
 <!-- runtime-principles:section=subtractive-first:begin -->
 
-> "Perfection is achieved not when there is nothing more to add, but when there is nothing left to take away." — Saint-Exupéry. **This is the operating definition of "done" in this repo.** A change is finished when no further line, branch, flag, or doc paragraph can be removed without breaking a learned failure mode. Not before.
+> **Operating definition of "done" in this repo** (Saint-Exupéry discipline rule above): a change is finished when no further line, branch, flag, or doc paragraph can be removed without breaking a learned failure mode. Not before.
 
 This rule overrides instinct. LLMs (including you) are trained on corpora that reward elaborate, defensive, "thorough" code — so the default impulse is to add. That impulse is wrong here. Read the rules below as hard tests, not aesthetic preferences. They are not optional, not negotiable, and not satisfiable by writing more careful additions.
 
@@ -86,15 +86,15 @@ This rule exists because LLMs (including you) are trained to be helpful, compreh
 
 **The five drift patterns you must refuse to execute on:**
 
-1. **Unrequested work.** "While I'm here, I noticed X is broken/ugly/inefficient" → **stop**. The user did not ask for X. If X is a real defect, surface it as a finding, a follow-up suggestion, or an entry in a TODO list — do NOT fix it inside the current change. Mixing unrequested work with requested work is what makes diffs unreviewable and PRs eternal.
-2. **Tangential cleanup.** "This file looks messy, let me also tidy..." → **stop**. The current task is the only task. Unrelated cleanup is a separate change requiring its own justification, scope, and pre-flight 0 check.
+1. **Unrequested work.** "While I'm here, I noticed X is broken/ugly/inefficient" → **stop**. The user did not ask for X. If X is a real defect, surface it as a finding, a follow-up suggestion, or an entry in a TODO list — do NOT fix it inside the current change. Mixing unrequested work with requested work is what makes diffs unreviewable and PRs eternal. **Pre-existing dead code → mention only, do NOT delete; orphans YOUR change created (now-unused imports, variables, functions) → clean them up.**
+2. **Tangential cleanup.** "This file looks messy, let me also tidy..." → **stop**. The current task is the only task. Unrelated cleanup is a separate change requiring its own justification, scope, and pre-flight 0 check. **Match existing style even if you'd write it differently; do NOT touch comments, formatting, or code orthogonal to your real change** — silent side-effects on neighboring lines are the most common Karpathy-observed regression class.
 3. **Speculative robustness.** "Just adding a check / fallback / handler for the case where..." → **stop**. If the case has not been observed (in production, in tests, in a finding), it does not belong in this change. Defensive code added for unobserved cases is the most common form of accretion debt — it never gets removed because nobody can prove the case never happens.
 4. **Re-scoping mid-flight.** "Actually, the better way to do this is to also restructure / rename / migrate..." → **stop**. If you discover the requested approach is wrong, surface that to the user with evidence and let them adjudicate. Do NOT silently expand scope. The user's explicit redirect is the only authorization to enlarge a task.
 5. **Curiosity detours.** "Let me also explore how Y works to understand this better..." → **stop**, unless Y is provably on the goal's critical path. Curiosity-driven exploration is creative-mode; default is execution-mode.
 
 **The single drift test before any deviation from the stated goal:** *"Did the user ask for this, OR does the user's stated goal strictly require it?"* If the answer to both is no, do not do it. Surface it as a note (commit message, end-of-turn summary, finding) and continue on the original path.
 
-**Creative-mode is the narrow exception, not the default.** Creative-mode applies only when (a) the user explicitly invoked an ideation/exploration surface (`/devlyn:ideate`, optional `/devlyn:design-system`, "let's brainstorm", "explore options for"), OR (b) the goal is genuinely under-specified and a clarifying question is impossible (extremely rare — usually you should ask). For everything else — bug fixes, feature work, refactors, doc updates, pipeline runs, code review, debugging — execution-mode is the default and drift is a defect, not a feature.
+**Creative-mode is the narrow exception, not the default.** Creative-mode applies only when (a) the user explicitly invoked an ideation/exploration surface (`/devlyn:ideate`, `/devlyn:design-ui`, "let's brainstorm", "explore options for"), OR (b) the goal is genuinely under-specified and a clarifying question is impossible (extremely rare — usually you should ask). For everything else — bug fixes, feature work, refactors, doc updates, pipeline runs, code review, debugging — execution-mode is the default and drift is a defect, not a feature.
 
 **Anti-rationalization clause** — explicitly guarding against LLM hedging:
 
@@ -116,16 +116,6 @@ This rule exists because LLMs (including you) are trained to be helpful, compreh
 - **Fallbacks are the exception.** Only use them when it's a widely accepted best practice (CSS fallback fonts, CDN failover, image placeholders). Otherwise handle the error explicitly.
 - **Pattern**: `try { doThing() } catch (error) { showErrorUI(error) }` — NOT `try { doThing() } catch { return fallbackValue }`.
 
-### No-workaround discipline (runtime salience)
-<!-- runtime-principles:section=no-workaround:begin -->
-
-No `any`, no `@ts-ignore`, no silent `catch`, no hardcoded values, no helper scripts that bypass the root cause. Fix root causes; handle errors with user-visible state per the rule above.
-
-**Permitted exceptions** (explicitly carved out):
-- CSS fallback fonts, CDN failover, image placeholders — widely-accepted best practices.
-- No engine-availability fallback is permitted for `/devlyn:resolve` pair/risk-probe routes. If Codex or Claude is required and unavailable, the run stops with `BLOCKED:codex-unavailable` or `BLOCKED:claude-unavailable` plus setup guidance. `--no-pair` / `--no-risk-probes` are explicit user opt-outs, not fallbacks.
-<!-- runtime-principles:section=no-workaround:end -->
-
 ### Evidence over claim
 <!-- runtime-principles:section=evidence:begin -->
 
@@ -152,9 +142,9 @@ When `/devlyn:resolve` or `/devlyn:ideate` route a phase to Codex (`--engine cod
 
 ## Skill Boundary Policy
 
-Post iter-0034 Phase 4 cutover (2026-05-04) the runtime pipeline surface is two skills — `/devlyn:resolve` and `/devlyn:ideate` — plus the required creative UI exploration surface `/devlyn:design-ui`. `/devlyn:resolve` runs PLAN → IMPLEMENT → BUILD_GATE → CLEANUP → VERIFY inline; verification, cleanup, and security review (delegated to the native `security-review` Claude Code skill from BUILD_GATE) all live inside the pipeline. There are no standalone `/devlyn:review`, `/devlyn:evaluate`, `/devlyn:team-resolve`, etc. surfaces to delegate to — those skills were folded into resolve's phases or removed in iter-0034. `/devlyn:design-ui` is the unified creative UI exploration surface — it spawns a 5-specialist design team (Creative Director, Product Designer, Visual Designer, Interaction Designer, Accessibility Designer) by default for any N. The legacy `/devlyn:team-design-ui` was merged into it on 2026-05-14 and the optional-skills directory deleted. Optional creative power-user skills (`/devlyn:reap`, `/devlyn:design-system`) live in `optional-skills/` and are user-invoked only; resolve never delegates to them.
+The runtime pipeline surface is two skills — `/devlyn:resolve` and `/devlyn:ideate` — plus `/devlyn:design-ui` for creative UI exploration. `/devlyn:resolve` runs PLAN → IMPLEMENT → BUILD_GATE → CLEANUP → VERIFY inline; verification, cleanup, and security review (delegated to the native `security-review` Claude Code skill from BUILD_GATE) all live inside the pipeline. There are no standalone `/devlyn:review`, `/devlyn:evaluate`, or `/devlyn:team-resolve` surfaces. `/devlyn:design-ui` spawns a 5-specialist design team (Creative Director, Product Designer, Visual Designer, Interaction Designer, Accessibility Designer). `/devlyn:reap` is an optional user-invoked skill in `optional-skills/`; resolve never delegates to it.
 
-Browser validation routes through `_shared/browser-runner.sh` (Chrome MCP → Playwright → curl tier) directly from BUILD_GATE — there is no separate `/devlyn:browser-validate` skill at HEAD.
+Browser validation runs directly from BUILD_GATE using whichever toolchain is available (Chrome MCP, Playwright, or curl-tier fallback) — there is no separate `/devlyn:browser-validate` skill.
 
 ## Communication Style
 

package/README.md

@@ -177,15 +177,16 @@ fixture count, and the replay command without running arms or judges. Dry-runs
 and lint prove wiring only; real score claims must cite the run id and fixture
 ids.
 
-## Optional Power-User Skills
+### Migration from earlier versions
 
-One creative companion skill lives in `optional-skills/` — install it via the interactive installer when you need it.
+Earlier versions of devlyn-cli shipped 16+ slash commands. The iter-0034 Phase 4 cutover (2026-05-04) and the 2026-05-14 follow-up consolidated them down to the three current commands. Upgrades automatically purge the legacy skill directories from `~/.claude/skills/`.
 
-| Command | Use When |
+| Old command | Now use |
 |---|---|
-| `/devlyn:design-system` | Extract exact design tokens (colors, type scale, spacing) from a chosen UI style |
-
-> Earlier versions of devlyn-cli shipped 16+ skills (auto-resolve / preflight / evaluate / review / team-review / clean / update-docs / browser-validate / product-spec / feature-spec / recommend-features / discover-product / design-ui / implement-ui). Most were consolidated into `/devlyn:resolve` (which folds verification, review, and cleanup into its phases) plus `/devlyn:ideate` (which absorbs the planning surfaces) in the iter-0034 Phase 4 cutover (2026-05-04). `/devlyn:design-ui` is the required creative UI surface — on 2026-05-14 the optional `/devlyn:team-design-ui` was merged into it, so `/devlyn:design-ui` now always spawns a 5-specialist design team (Creative Director, Product Designer, Visual Designer, Interaction Designer, Accessibility Designer). Upgrades automatically remove the legacy skill directories from `~/.claude/skills/`.
+| `/devlyn:auto-resolve`, `/devlyn:preflight`, `/devlyn:evaluate`, `/devlyn:review`, `/devlyn:team-resolve`, `/devlyn:team-review`, `/devlyn:clean`, `/devlyn:update-docs`, `/devlyn:browser-validate`, `/devlyn:implement-ui` | `/devlyn:resolve` (folds them into PLAN → IMPLEMENT → BUILD_GATE → CLEANUP → VERIFY) |
+| `/devlyn:product-spec`, `/devlyn:feature-spec`, `/devlyn:recommend-features`, `/devlyn:discover-product` | `/devlyn:ideate` |
+| `/devlyn:team-design-ui` | `/devlyn:design-ui` (now always spawns the 5-specialist team — Creative Director, Product Designer, Visual Designer, Interaction Designer, Accessibility Designer) |
+| `/devlyn:design-system` | Removed 2026-05-14 — no replacement |
 
 ---
 
@@ -221,7 +222,6 @@ Selected during install. Run `npx devlyn-cli` again to add more.
 | `devlyn:pencil-pull` | Pull Pencil designs into code |
 | `devlyn:pencil-push` | Push codebase UI to Pencil canvas |
 | `devlyn:reap` | Safely reap orphaned MCP / codex / Superset child processes |
-| `devlyn:design-system` | Extract design tokens from a chosen UI style for exact reproduction |
 
 </details>
 

package/agents-config/evaluator.md

@@ -4,7 +4,7 @@ You are a code quality evaluator. Your job is to audit work produced by another
 
 ## Before You Start
 
-1. **Check for done criteria**: Read `.devlyn/done-criteria.md` if it exists. When present, this is your primary grading rubric — every criterion must be verified with evidence. When absent, fall back to the checklists below.
+1. **Check for done criteria**: Read `.devlyn/runs/<run_id>/spec/expected.json` if a structured done-criteria source exists for the current run. When present, this is your primary grading rubric — every criterion must be verified with evidence. When absent, fall back to the checklists below.
 
 ## Calibration
 
@@ -36,14 +36,14 @@ You will be too lenient by default. You will identify real issues, then talk you
 
 ## Output
 
-Write findings to `.devlyn/EVAL-FINDINGS.md` for downstream consumption:
+Write findings to `.devlyn/runs/<run_id>/eval-findings.md` for downstream consumption:
 
 ```markdown
 # Evaluation Findings
 
 ## Verdict: [PASS / PASS WITH ISSUES / NEEDS WORK / BLOCKED]
 
-## Done Criteria Results (if done-criteria.md existed)
+## Done Criteria Results (if a done-criteria source existed)
 - [x] [criterion] — VERIFIED: [evidence]
 - [ ] [criterion] — FAILED: [what's wrong, file:line]
 
@@ -61,4 +61,4 @@ Write findings to `.devlyn/EVAL-FINDINGS.md` for downstream consumption:
 - [positive observations]
 ```
 
-Do NOT delete `.devlyn/done-criteria.md` or `.devlyn/EVAL-FINDINGS.md` — the orchestrator or user is responsible for cleanup.
+Do NOT delete the run-directory artifacts (`spec/expected.json`, `eval-findings.md`) — the orchestrator or user is responsible for cleanup.

package/bin/devlyn.js

@@ -118,11 +118,11 @@ const DEPRECATED_DIRS = [
   // upgrade so users only have them if they opt in via the interactive
   // installer (matches the pencil-pull / pencil-push pattern).
   'skills/devlyn:reap',
-  'skills/devlyn:design-system',
-  // Merged into devlyn:design-ui on 2026-05-14. Source dir deleted entirely;
-  // entry kept here so users who opted into the team variant get their stale
-  // copy purged on upgrade.
+  // Deleted entirely on 2026-05-14 (devlyn:team-design-ui merged into
+  // devlyn:design-ui; devlyn:design-system removed outright). Entries kept
+  // so users who previously opted in get their stale copies purged on upgrade.
   'skills/devlyn:team-design-ui',
+  'skills/devlyn:design-system',
 ];
 
 function getTargetDir() {
@@ -185,7 +185,6 @@ const OPTIONAL_ADDONS = [
   { name: 'devlyn:pencil-pull', desc: 'Pull Pencil designs into code with exact visual fidelity', type: 'local' },
   { name: 'devlyn:pencil-push', desc: 'Push codebase UI to Pencil canvas for design sync', type: 'local' },
   { name: 'devlyn:reap', desc: 'Safely reap orphaned MCP / codex / Superset child processes left behind by long Claude sessions', type: 'local' },
-  { name: 'devlyn:design-system', desc: 'Extract design tokens from a chosen UI style for exact reproduction (creative power-user)', type: 'local' },
   // External skill packs (installed via npx skills add)
   { name: 'vercel-labs/agent-skills', desc: 'React, Next.js, React Native best practices', type: 'external' },
   { name: 'supabase/agent-skills', desc: 'Supabase integration patterns', type: 'external' },
@@ -559,64 +558,66 @@ function installSkillsForCLI(cliKey) {
 function installAgentsForCLI(cliKey) {
   const cli = CLI_TARGETS[cliKey];
   if (!cli) return false;
-  if (!fs.existsSync(AGENTS_SOURCE)) return false;
 
-  const agents = fs.readdirSync(AGENTS_SOURCE).filter((f) => f.endsWith('.md'));
-  if (agents.length === 0) return false;
+  const agents = fs.existsSync(AGENTS_SOURCE)
+    ? fs.readdirSync(AGENTS_SOURCE).filter((f) => f.endsWith('.md'))
+    : [];
 
-  log(`\n🤖 Installing agents for ${cli.name}...`, 'cyan');
+  if (agents.length > 0) {
+    log(`\n🤖 Installing agents for ${cli.name}...`, 'cyan');
 
-  if (cli.configDir) {
-    // CLI supports an agents directory — copy agent files there
-    const destDir = path.join(process.cwd(), cli.configDir);
-    if (!fs.existsSync(destDir)) {
-      fs.mkdirSync(destDir, { recursive: true });
-    }
-    for (const file of agents) {
-      const src = path.join(AGENTS_SOURCE, file);
-      const dest = path.join(destDir, file);
-      fs.copyFileSync(src, dest);
-      log(`  → ${cli.configDir}/${file}`, 'dim');
-    }
-  } else {
-    // CLI uses a single instructions file — append agent content
-    const destFile = path.join(process.cwd(), cli.instructionsFile);
-    const separator = '\n\n---\n\n# Devlyn Agent Instructions\n\n';
-    const agentContent = agents.map((file) => {
-      return fs.readFileSync(path.join(AGENTS_SOURCE, file), 'utf8');
-    }).join('\n\n---\n\n');
-
-    let existing = '';
-    if (fs.existsSync(destFile)) {
-      existing = fs.readFileSync(destFile, 'utf8');
-      // Remove previous devlyn agent section if present
-      const devlynMarker = '# Devlyn Agent Instructions';
-      const markerIdx = existing.indexOf(devlynMarker);
-      if (markerIdx > 0) {
-        // Find the separator before the marker (---\n\n)
-        const sepIdx = existing.lastIndexOf('---', markerIdx);
-        existing = existing.slice(0, sepIdx > 0 ? sepIdx : markerIdx).trimEnd();
+    if (cli.configDir) {
+      // CLI supports an agents directory — copy agent files there
+      const destDir = path.join(process.cwd(), cli.configDir);
+      if (!fs.existsSync(destDir)) {
+        fs.mkdirSync(destDir, { recursive: true });
       }
-    } else if (cli.baseInstructionsFile) {
-      const baseInstructionsSrc = path.join(__dirname, '..', cli.baseInstructionsFile);
-      if (fs.existsSync(baseInstructionsSrc)) {
-        existing = fs.readFileSync(baseInstructionsSrc, 'utf8').trimEnd();
+      for (const file of agents) {
+        const src = path.join(AGENTS_SOURCE, file);
+        const dest = path.join(destDir, file);
+        fs.copyFileSync(src, dest);
+        log(`  → ${cli.configDir}/${file}`, 'dim');
+      }
+    } else {
+      // CLI uses a single instructions file — append agent content
+      const destFile = path.join(process.cwd(), cli.instructionsFile);
+      const separator = '\n\n---\n\n# Devlyn Agent Instructions\n\n';
+      const agentContent = agents.map((file) => {
+        return fs.readFileSync(path.join(AGENTS_SOURCE, file), 'utf8');
+      }).join('\n\n---\n\n');
+
+      let existing = '';
+      if (fs.existsSync(destFile)) {
+        existing = fs.readFileSync(destFile, 'utf8');
+        // Remove previous devlyn agent section if present
+        const devlynMarker = '# Devlyn Agent Instructions';
+        const markerIdx = existing.indexOf(devlynMarker);
+        if (markerIdx > 0) {
+          // Find the separator before the marker (---\n\n)
+          const sepIdx = existing.lastIndexOf('---', markerIdx);
+          existing = existing.slice(0, sepIdx > 0 ? sepIdx : markerIdx).trimEnd();
+        }
+      } else if (cli.baseInstructionsFile) {
+        const baseInstructionsSrc = path.join(__dirname, '..', cli.baseInstructionsFile);
+        if (fs.existsSync(baseInstructionsSrc)) {
+          existing = fs.readFileSync(baseInstructionsSrc, 'utf8').trimEnd();
+        }
       }
-    }
 
-    fs.writeFileSync(destFile, existing + separator + agentContent + '\n');
-    log(`  → ${cli.instructionsFile} (agent instructions appended)`, 'dim');
+      fs.writeFileSync(destFile, existing + separator + agentContent + '\n');
+      log(`  → ${cli.instructionsFile} (agent instructions appended)`, 'dim');
+    }
   }
 
-  // If this CLI also supports a global skill-loader (currently Codex), install
-  // devlyn:resolve + devlyn:ideate + devlyn:design-ui + _shared. Codex invokes
-  // these as skills (for example `$devlyn:resolve`), not Claude slash commands.
+  // Always install global skills (Codex-style skill loader) regardless of
+  // whether agent files were present. Agent install and skill install are
+  // independent capabilities.
   const skillsCopied = installSkillsForCLI(cliKey);
   if (skillsCopied > 0) {
     log(`  → ${skillsCopied} skill${skillsCopied > 1 ? 's' : ''} installed (devlyn:resolve / devlyn:ideate / devlyn:design-ui / _shared)`, 'dim');
   }
 
-  return true;
+  return agents.length > 0 || skillsCopied > 0;
 }
 
 function installAgentsForAllDetected() {

package/config/skills/_shared/runtime-principles.md

@@ -2,13 +2,13 @@
 
 The runtime contract every sub-agent inside `/devlyn:resolve` (PLAN / IMPLEMENT / BUILD_GATE / CLEANUP / VERIFY) and `/devlyn:ideate` must satisfy. Source of truth for sub-agent behavior on user tasks. NOT for autoresearch-loop / harness-developer concerns (see `autoresearch/PRINCIPLES.md`).
 
-The four sections below mirror the corresponding CLAUDE.md sections (Subtractive-first editing, Goal-locked execution, No-workaround discipline, Evidence over claim). Each section is wrapped in `<!-- runtime-principles:section=NAME:begin -->` / `:end -->` markers in BOTH this file and CLAUDE.md; lint Check 12 (added in iter-0019.A Step 5) extracts each named block from both files and diffs to detect drift.
+The three sections below mirror the corresponding CLAUDE.md sections (Subtractive-first editing, Goal-locked execution, Evidence over claim). No-workaround discipline lives in CLAUDE.md Core Principle #1 only — it does not have a runtime-mirror block. Each mirrored section is wrapped in `<!-- runtime-principles:section=NAME:begin -->` / `:end -->` markers in BOTH this file and CLAUDE.md; lint Check 12 extracts each named block from both files and diffs to detect drift.
 
 <!-- runtime-principles:contract:begin -->
 ## Subtractive-first editing — perfection = nothing left to remove
 <!-- runtime-principles:section=subtractive-first:begin -->
 
-> "Perfection is achieved not when there is nothing more to add, but when there is nothing left to take away." — Saint-Exupéry. **This is the operating definition of "done" in this repo.** A change is finished when no further line, branch, flag, or doc paragraph can be removed without breaking a learned failure mode. Not before.
+> **Operating definition of "done" in this repo** (Saint-Exupéry discipline rule above): a change is finished when no further line, branch, flag, or doc paragraph can be removed without breaking a learned failure mode. Not before.
 
 This rule overrides instinct. LLMs (including you) are trained on corpora that reward elaborate, defensive, "thorough" code — so the default impulse is to add. That impulse is wrong here. Read the rules below as hard tests, not aesthetic preferences. They are not optional, not negotiable, and not satisfiable by writing more careful additions.
 
@@ -50,15 +50,15 @@ This rule exists because LLMs (including you) are trained to be helpful, compreh
 
 **The five drift patterns you must refuse to execute on:**
 
-1. **Unrequested work.** "While I'm here, I noticed X is broken/ugly/inefficient" → **stop**. The user did not ask for X. If X is a real defect, surface it as a finding, a follow-up suggestion, or an entry in a TODO list — do NOT fix it inside the current change. Mixing unrequested work with requested work is what makes diffs unreviewable and PRs eternal.
-2. **Tangential cleanup.** "This file looks messy, let me also tidy..." → **stop**. The current task is the only task. Unrelated cleanup is a separate change requiring its own justification, scope, and pre-flight 0 check.
+1. **Unrequested work.** "While I'm here, I noticed X is broken/ugly/inefficient" → **stop**. The user did not ask for X. If X is a real defect, surface it as a finding, a follow-up suggestion, or an entry in a TODO list — do NOT fix it inside the current change. Mixing unrequested work with requested work is what makes diffs unreviewable and PRs eternal. **Pre-existing dead code → mention only, do NOT delete; orphans YOUR change created (now-unused imports, variables, functions) → clean them up.**
+2. **Tangential cleanup.** "This file looks messy, let me also tidy..." → **stop**. The current task is the only task. Unrelated cleanup is a separate change requiring its own justification, scope, and pre-flight 0 check. **Match existing style even if you'd write it differently; do NOT touch comments, formatting, or code orthogonal to your real change** — silent side-effects on neighboring lines are the most common Karpathy-observed regression class.
 3. **Speculative robustness.** "Just adding a check / fallback / handler for the case where..." → **stop**. If the case has not been observed (in production, in tests, in a finding), it does not belong in this change. Defensive code added for unobserved cases is the most common form of accretion debt — it never gets removed because nobody can prove the case never happens.
 4. **Re-scoping mid-flight.** "Actually, the better way to do this is to also restructure / rename / migrate..." → **stop**. If you discover the requested approach is wrong, surface that to the user with evidence and let them adjudicate. Do NOT silently expand scope. The user's explicit redirect is the only authorization to enlarge a task.
 5. **Curiosity detours.** "Let me also explore how Y works to understand this better..." → **stop**, unless Y is provably on the goal's critical path. Curiosity-driven exploration is creative-mode; default is execution-mode.
 
 **The single drift test before any deviation from the stated goal:** *"Did the user ask for this, OR does the user's stated goal strictly require it?"* If the answer to both is no, do not do it. Surface it as a note (commit message, end-of-turn summary, finding) and continue on the original path.
 
-**Creative-mode is the narrow exception, not the default.** Creative-mode applies only when (a) the user explicitly invoked an ideation/exploration surface (`/devlyn:ideate`, optional `/devlyn:design-system`, "let's brainstorm", "explore options for"), OR (b) the goal is genuinely under-specified and a clarifying question is impossible (extremely rare — usually you should ask). For everything else — bug fixes, feature work, refactors, doc updates, pipeline runs, code review, debugging — execution-mode is the default and drift is a defect, not a feature.
+**Creative-mode is the narrow exception, not the default.** Creative-mode applies only when (a) the user explicitly invoked an ideation/exploration surface (`/devlyn:ideate`, `/devlyn:design-ui`, "let's brainstorm", "explore options for"), OR (b) the goal is genuinely under-specified and a clarifying question is impossible (extremely rare — usually you should ask). For everything else — bug fixes, feature work, refactors, doc updates, pipeline runs, code review, debugging — execution-mode is the default and drift is a defect, not a feature.
 
 **Anti-rationalization clause** — explicitly guarding against LLM hedging:
 
@@ -72,16 +72,6 @@ This rule exists because LLMs (including you) are trained to be helpful, compreh
 **Stopping rule.** A task is done when the user's stated goal is closed AND no off-path work was added. If you find yourself hesitating because "I should also do Z" — Z is drift. Note it for follow-up, do not execute.
 <!-- runtime-principles:section=goal-locked:end -->
 
-## No-workaround discipline
-<!-- runtime-principles:section=no-workaround:begin -->
-
-No `any`, no `@ts-ignore`, no silent `catch`, no hardcoded values, no helper scripts that bypass the root cause. Fix root causes; handle errors with user-visible state per the rule above.
-
-**Permitted exceptions** (explicitly carved out):
-- CSS fallback fonts, CDN failover, image placeholders — widely-accepted best practices.
-- No engine-availability fallback is permitted for `/devlyn:resolve` pair/risk-probe routes. If Codex or Claude is required and unavailable, the run stops with `BLOCKED:codex-unavailable` or `BLOCKED:claude-unavailable` plus setup guidance. `--no-pair` / `--no-risk-probes` are explicit user opt-outs, not fallbacks.
-<!-- runtime-principles:section=no-workaround:end -->
-
 ## Evidence over claim
 <!-- runtime-principles:section=evidence:begin -->
 

package/config/skills/devlyn:design-ui/SKILL.md

@@ -648,8 +648,3 @@ After `TeamCreate` succeeds, treat Phases 2-6 as `try/finally`: run cleanup even
 </output_format>
 
 Make bold choices. Each design should be portfolio-worthy — something you'd proudly present.
-
-<next_step>
-After the user picks a style, suggest:
-→ Run `/devlyn:design-system [style-number]` to extract design tokens from the chosen style into a reusable design system reference.
-</next_step>

package/config/skills/root-cause-analysis/SKILL.md

@@ -8,7 +8,7 @@ Standard methodology for investigating bugs, issues, and unexpected behavior. Ap
 - Error logs or stack traces need diagnosis
 - "Why does X happen?" or "What's causing X?" questions
 - Debugging sessions
-- Any use of `/devlyn:resolve` or `/devlyn:team-resolve`
+- Any use of `/devlyn:resolve`
 
 ## 5 Whys Protocol
 
@@ -62,5 +62,4 @@ If the real fix requires significant refactoring, present the scope to the user
 
 ## Routing
 
-- **Simple issue** (single file, obvious cause): Use `/devlyn:resolve`
-- **Complex issue** (multi-module, unclear cause, security implications): Use `/devlyn:team-resolve` for multi-perspective investigation
+- Use `/devlyn:resolve` — handles both simple and multi-module investigations; VERIFY pair-judge fires conditionally on high-risk / complex specs.

package/config/skills/ui-implementation-standards/SKILL.md

@@ -7,7 +7,7 @@ Quality framework for building and improving UI from design systems. Apply these
 - Building UI components or pages
 - Implementing designs from a design system
 - Improving or refactoring existing UI
-- Any use of `/devlyn:implement-ui`, `/devlyn:design-ui`, or `/devlyn:design-system`
+- Any use of `/devlyn:design-ui`
 - Frontend development tasks involving visual design
 
 ## Design System Fidelity
@@ -70,5 +70,5 @@ Every interactive component or data-dependent view needs all states:
 ## Routing
 
 - **Build new UI or improve existing**: Use `/devlyn:implement-ui` for a full team approach
-- **Add features to existing UI**: Use `/devlyn:team-resolve` with the feature description
+- **Add features to existing UI**: Use `/devlyn:resolve` with the feature description
 - **Review UI code quality**: Use `/devlyn:team-review` for multi-perspective code review

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devlyn-cli",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "AI development toolkit for Claude Code — ideate, resolve, and ship with context engineering and agent orchestration",
   "homepage": "https://github.com/fysoul17/devlyn-cli#readme",
   "bin": {

package/scripts/lint-skills.sh

@@ -3773,14 +3773,16 @@ fi
 # must mirror the corresponding CLAUDE.md sections. Drift in one source-of-truth without
 # the other produces silent behavioral divergence between session-level and sub-agent
 # enforcement. Per-section markers `<!-- runtime-principles:section=NAME:begin/end -->`
-# wrap each of the 4 sections (subtractive-first, goal-locked, no-workaround, evidence)
-# in BOTH files. Check 12 extracts each named block from both files and diffs.
+# wrap each of the 3 mirrored sections (subtractive-first, goal-locked, evidence)
+# in BOTH files. No-workaround discipline lives in CLAUDE.md Core Principle #1
+# only and is not mirrored to runtime-principles.md.
+# Check 12 extracts each named block from both files and diffs.
 # ---------------------------------------------------------------------------
 section "Check 12: CLAUDE.md ↔ runtime-principles.md per-section excerpt parity"
 rp_src="config/skills/_shared/runtime-principles.md"
 claude_src="CLAUDE.md"
 rp_drift=0
-expected_sections="subtractive-first goal-locked no-workaround evidence"
+expected_sections="subtractive-first goal-locked evidence"
 
 if [ ! -f "$rp_src" ]; then
   bad "$rp_src — missing"
@@ -3859,7 +3861,7 @@ else
   fi
 
   if [ $rp_drift -eq 0 ]; then
-    ok "all 4 contract sections in parity (subtractive-first / goal-locked / no-workaround / evidence) — markers, topology, content"
+    ok "all 3 mirrored contract sections in parity (subtractive-first / goal-locked / evidence) — markers, topology, content"
   fi
 fi
 

package/optional-skills/devlyn:design-system/SKILL.md

@@ -1,503 +0,0 @@
----
-name: devlyn:design-system
-description: Extract all design values from selected style for exact reproduction
-argument-hint: <style-number> [platform] (e.g., "3", "3 flutter", "style 2 web")
-allowed-tools: Bash(ls:*), Bash(cat:*), Bash(grep:*), View, Edit, Write
----
-
-Extract design values from a style preview HTML to generate a framework-agnostic design reference.
-
-<context>
-User input: $ARGUMENTS
-Available styles: !`ls -1 docs/design/style_*.html 2>/dev/null || echo "No styles found"`
-</context>
-
-<input_parsing>
-
-Parse two values from input:
-
-1. **Style number** (required): "3", "style 3", or "style_3_concept_name" all resolve to style 3
-
-2. **Platform** (optional, defaults to "web"):
-   - `web` — HTML/CSS, React, Vue, Svelte, Next.js
-   - `flutter` — Dart/Flutter
-   - `native` — iOS (SwiftUI) / Android (Compose)
-   - `desktop` — Electron, Tauri, PyQt
-   - `terminal` — CLI apps with color support
-
-</input_parsing>
-
-<goal>
-
-Create a design reference document that enables any AI agent to:
-
-1. Apply correct visual styling (colors, typography, spacing, shadows, motion)
-2. Build components that match the design language (patterns, behaviors, icon approach)
-
-This document contains **values and patterns**—no framework-specific implementation code. The implementing agent determines the correct syntax based on the actual project setup.
-
-**Important distinction**:
-
-- This document defines HOW things should look (reusable across any page structure)
-- Feature specs define WHAT to build (page structure, sections, content)
-- An agent uses both: feature spec for structure + this document for styling
-
-</goal>
-
-<extraction_requirements>
-
-Extract all concrete values that define the design's appearance and reusable component patterns.
-
-<colors>
-Extract every color used:
-- Background, surface, text primary, text secondary
-- Accent colors (primary, secondary if present)
-- Borders, dividers, hover states
-- Any gradients (with exact color stops and direction)
-
-Format: hex values (e.g., #F4F7FA)
-</colors>
-
-<typography>
-Extract the exact font configuration:
-- Font family name (exact Google Fonts spelling)
-- All font weights used (e.g., 300, 400, 600, 700)
-
-For each text level (H1, H2, H3, Body, Body Large, Small/Caption, Label):
-
-- Size in pixels
-- Weight
-- Letter-spacing (em or px)
-- Line-height (unitless ratio)
-  </typography>
-
-<spacing>
-Extract actual pixel values used, not abstract scales:
-- Section/page padding
-- Hero section padding (if different)
-- Component/card padding (large and small variants)
-- Element gap (between buttons, cards)
-- Tight gap (icon + text, inline elements)
-- Navigation gaps
-- Section header margin-bottom
-</spacing>
-
-<shape>
-Extract border-radius values:
-- Cards and containers
-- Feature icons
-- Small icons
-- Buttons and pills (often "full" or 100px)
-- CTA sections (if different)
-</shape>
-
-<shadows>
-Extract complete box-shadow CSS values:
-- Default/subtle shadow
-- Navigation/badge shadow
-- Floating card shadow
-- Hover state shadow
-- Button hover shadow
-
-Include the full value: offset, blur, spread, color with alpha.
-</shadows>
-
-<motion>
-Extract animation timing:
-- Easing function (exact cubic-bezier or keyword)
-- Base transition duration
-- Enter/appear animation duration
-- Scroll-triggered transition duration
-- Stagger delay between items
-- Any cyclic animation durations (float, drift effects)
-</motion>
-
-<effects>
-Only if present in the design:
-- Background effects (orbs, gradients, patterns)
-- Glassmorphism (backdrop-filter blur value, background opacity)
-- Gradient text treatment
-- Any texture overlays
-</effects>
-
-<components>
-Extract reusable component patterns found in the design. For each distinct component type:
-
-1. **Navigation** (if present):
-
-   - Layout type (fixed, sticky, static)
-   - Visual treatment (solid, glassmorphism, transparent)
-   - Elements included (logo style, link style, CTA style)
-
-2. **Cards** (identify all card variants):
-
-   - Name/purpose (feature card, stat card, testimonial card, etc.)
-   - Icon approach: emoji, SVG, or icon font
-   - If emoji: note this explicitly
-   - Icon container style (size, background, radius)
-   - Content structure (what elements: icon, title, description, stat, etc.)
-   - Hover behavior (transform, shadow change, with duration)
-
-3. **Buttons** (identify all variants):
-
-   - Primary, secondary, ghost styles
-   - Hover transforms and shadow changes
-
-4. **Badges/Labels**:
-
-   - Visual style (pill, tag, etc.)
-   - Any animated elements (pulse dots, etc.)
-
-5. **Section Headers**:
-
-   - Label + title + description pattern
-   - Alignment (centered, left)
-
-6. **Special Elements**:
-   - Any unique patterns (floating cards, step indicators, etc.)
-   - Animation behaviors
-
-For each component, describe it as a reusable pattern that can be applied regardless of how many times it appears or what content it contains.
-</components>
-
-<interactive_states>
-Document hover/active/focus states for interactive elements:
-
-- What property changes (transform, shadow, background, scale, opacity)
-- From value → To value
-- Duration and easing
-
-Format as a reference table.
-</interactive_states>
-
-<character>
-Summarize the design's personality:
-- Theme: Light or Dark
-- Shape language: Angular, Curved, or Mixed
-- Density: Spacious or Dense
-- Energy: Calm, Dynamic, or Playful
-</character>
-
-</extraction_requirements>
-
-<output_format>
-
-Generate `docs/design-system.md` with this structure:
-
-```markdown
-# Design Style: {Concept Name}
-
-> {One sentence capturing the design's mood and intent}
-
-**Platform**: {platform}
-**Source**: `{source filename}`
-
----
-
-## Implementation Note
-
-This document defines the visual design language—HOW things should look.
-
-When implementing:
-
-1. Use your **feature spec** for page structure (WHAT sections/components to build)
-2. Use **this document** for styling those components (HOW they should look)
-3. Apply values using syntax appropriate for your framework
-
----
-
-## Colors
-
-| Role                  | Value     |
-| --------------------- | --------- |
-| Background            | `#______` |
-| Surface               | `#______` |
-| Text                  | `#______` |
-| Text Muted            | `#______` |
-| Accent                | `#______` |
-| {additional roles...} | `#______` |
-
-**Gradients** (if present):
-
-- {Name}: `{direction}deg, {color1} {stop1}%, {color2} {stop2}%`
-
-## Typography
-
-**Font Family**: {exact name} (with {fallback} for {language} if applicable)
-**Weights**: {comma-separated list}
-
-| Element       | Size  | Weight | Letter-spacing | Line-height |
-| ------------- | ----- | ------ | -------------- | ----------- |
-| H1            | {n}px | {n}    | {n}em          | {n}         |
-| H2            | {n}px | {n}    | {n}em          | {n}         |
-| H3            | {n}px | {n}    | {n}em          | {n}         |
-| Body          | {n}px | {n}    | —              | {n}         |
-| Body Large    | {n}px | {n}    | —              | {n}         |
-| Small/Caption | {n}px | {n}    | —              | {n}         |
-| Label         | {n}px | {n}    | —              | {n}         |
-
-## Spacing
-
-| Context                      | Value                            |
-| ---------------------------- | -------------------------------- |
-| Section padding              | {n}px vertical, {n}px horizontal |
-| Hero padding                 | {top}px top, {bottom}px bottom   |
-| Card padding (large)         | {n}px                            |
-| Card padding (small)         | {n}px                            |
-| Element gap                  | {n}px                            |
-| Tight gap                    | {n}px                            |
-| Section header margin-bottom | {n}px                            |
-
-## Shape
-
-| Context          | Radius       |
-| ---------------- | ------------ |
-| Cards/Containers | {n}px        |
-| Icons (large)    | {n}px        |
-| Icons (small)    | {n}px        |
-| Buttons/Pills    | {n}px (full) |
-
-## Shadows
-
-| Name         | Value                 |
-| ------------ | --------------------- |
-| Subtle       | `{full shadow value}` |
-| Card         | `{full shadow value}` |
-| Card Hover   | `{full shadow value}` |
-| Float        | `{full shadow value}` |
-| Button Hover | `{full shadow value}` |
-
-## Motion
-
-| Property            | Value                              |
-| ------------------- | ---------------------------------- |
-| Easing (soft)       | `cubic-bezier({a}, {b}, {c}, {d})` |
-| Easing (bounce)     | `cubic-bezier({a}, {b}, {c}, {d})` |
-| Base duration       | {n}s                               |
-| Hover duration      | {n}s                               |
-| Enter duration      | {n}s                               |
-| Stagger             | {n}s                               |
-| {Cyclic animations} | {n}s                               |
-
-## Effects
-
-{Only include sections that exist in the source design}
-
-**Background Elements** (if present):
-
-- {Description with sizes, colors, blur, positions, animations}
-
-**Glassmorphism** (if present):
-
-- Background: `rgba({r}, {g}, {b}, {a})`
-- Backdrop blur: {n}px
-
-**Gradient Text** (if present):
-
-- Applied to: {list elements}
-- CSS: background-clip text with transparent fill
-
----
-
-## Component Patterns
-
-Reusable patterns that define how components should look, regardless of page structure.
-
-### Icon Approach
-
-- **Type**: {emoji | SVG | icon font}
-- **Container**: {size}px, {background}, {radius}px radius
-  {If emoji, note: "Use emoji characters directly, not icon libraries"}
-
-### Navigation
-
-- **Position**: {fixed center | sticky top | etc.}
-- **Style**: {glassmorphism | solid | transparent}
-- **Elements**: Logo ({style}), Links ({style}), CTA button ({style})
-
-### Card: Feature
-
-- **Use for**: Feature highlights, service descriptions
-- **Structure**: Icon container → Title → Description
-- **Icon**: {size}px container, {background style}
-- **Hover**: {transform}, {shadow change}, {duration}
-
-### Card: Stat
-
-- **Use for**: Metrics, numbers, KPIs
-- **Structure**: Large value (gradient text) → Label
-- **Hover**: {transform}, {duration}
-
-### Card: {Other variants found...}
-
-{Document each distinct card pattern}
-
-### Button: Primary
-
-- **Style**: {gradient/solid} background, {text color}
-- **Hover**: {transform}, {shadow}
-
-### Button: Secondary
-
-- **Style**: {background}, {border if any}
-- **Hover**: {changes}
-
-### Badge/Label
-
-- **Style**: Pill shape, {background}, {text style}
-- **Animation**: {if any, e.g., pulse dot}
-
-### Section Header
-
-- **Pattern**: Label badge (optional) → H2 title → Description (optional)
-- **Alignment**: {centered | left}
-- **Spacing**: {margin-bottom}px below
-
-### {Special Patterns}
-
-{Document any unique patterns like floating cards, step indicators, etc.}
-
----
-
-## Interactive States
-
-| Component                                  | Trigger | Property  | From   | To               | Duration |
-| ------------------------------------------ | ------- | --------- | ------ | ---------------- | -------- |
-| Feature Card                               | hover   | transform | none   | translateY(-8px) | {n}s     |
-| Feature Card                               | hover   | shadow    | subtle | card-hover       | {n}s     |
-| Button Primary                             | hover   | transform | none   | translateY(-3px) | {n}s     |
-| Button Primary                             | hover   | shadow    | none   | button-hover     | {n}s     |
-| {continue for all interactive elements...} |         |           |        |                  |          |
-
----
-
-## Character
-
-- **Theme**: {Light | Dark}
-- **Shape**: {Angular | Curved | Mixed}
-- **Density**: {Spacious | Dense}
-- **Energy**: {Calm | Dynamic | Playful}
-
----
-
-## Token Reference
-
-Quick reference for implementation.
-
-### Colors
-```
-
-color-bg: #**\_\_**
-color-surface: #**\_\_**
-color-text: #**\_\_**
-color-text-muted: #**\_\_**
-color-accent: #**\_\_**
-gradient-primary: {direction}, {stops}
-
-```
-
-### Typography
-```
-
-font-family: {name}, {fallback}
-font-weight-regular: {n}
-font-weight-semibold: {n}
-font-weight-bold: {n}
-
-```
-
-### Spacing
-```
-
-space-section: {n}px
-space-component: {n}px
-space-element: {n}px
-space-tight: {n}px
-
-```
-
-### Shape
-```
-
-radius-card: {n}px
-radius-icon: {n}px
-radius-button: full
-
-```
-
-### Motion
-```
-
-ease-soft: cubic-bezier({values})
-ease-bounce: cubic-bezier({values})
-duration-base: {n}s
-duration-hover: {n}s
-
-```
-
----
-
-_Generated from: `{source filename}`_
-```
-
-</output_format>
-
-<platform_adaptations>
-
-Adjust the Token Reference section based on platform:
-
-**flutter**: Include Dart-style comments showing Color() and Duration() syntax as reference
-**native**: Note that colors should be added to asset catalogs
-**terminal**: Include ANSI color code mappings
-
-Keep these as **reference comments**, not copy-paste code.
-
-</platform_adaptations>
-
-<quality_verification>
-
-Before saving, verify completeness:
-
-**Values extraction**:
-
-- [ ] All colors extracted with valid hex values
-- [ ] Font name matches exact Google Fonts spelling
-- [ ] Typography table complete for all text levels
-- [ ] Spacing values are concrete pixels
-- [ ] Border radius values for all contexts
-- [ ] Shadow values are complete CSS
-- [ ] Easing is exact cubic-bezier
-- [ ] Animation durations in seconds
-
-**Component patterns**:
-
-- [ ] Icon approach clearly stated (emoji vs SVG vs font)
-- [ ] All card variants documented with hover behavior
-- [ ] Button variants documented
-- [ ] Navigation pattern documented
-- [ ] Section header pattern documented
-- [ ] Special/unique patterns documented
-
-**Interactive states**:
-
-- [ ] All hover transforms documented
-- [ ] All shadow transitions documented
-- [ ] Durations specified for each
-
-**Reproduction test**: Could another agent read this document and build components that look identical, regardless of what page structure they're implementing?
-
-</quality_verification>
-
-<execution>
-
-1. Parse style number and platform from $ARGUMENTS
-2. Read the matching `docs/design/style_{n}_*.html` file
-3. Extract all values following the extraction requirements
-4. Extract all component patterns
-5. Document all interactive states
-6. Generate `docs/design-system.md` following the output format
-7. Confirm what was created and note the source file
-
-If the style file doesn't exist, list the available options.
-
-</execution>