devlyn-cli 0.4.0 → 0.5.0

package/README.md

@@ -1,11 +1,20 @@
 <div align="center">
 
-# devlyn-cli
+<br />
 
-**A shared configuration toolkit for Claude Code — standardize AI-powered workflows across your team and projects.**
+<picture>
+  <img alt="DEVLYN" src="assets/logo.svg" width="540" />
+</picture>
+
+### The Skills & Commands Toolkit for Claude Code
+
+**Ship better code with battle-tested AI workflows — debugging, code review, UI design, product specs, and more.**
 
 [![npm version](https://img.shields.io/npm/v/devlyn-cli.svg)](https://www.npmjs.com/package/devlyn-cli)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Claude Code](https://img.shields.io/badge/Claude_Code-compatible-blueviolet)](https://docs.anthropic.com/en/docs/claude-code)
+
+[Get Started](#get-started) · [Commands](#commands) · [Skills](#skills) · [Workflows](#workflows) · [Optional Packs](#optional-skills--packs) · [Contributing](#contributing)
 
 </div>
 
@@ -13,122 +22,222 @@
 
 ## Why devlyn-cli?
 
-[Claude Code](https://docs.anthropic.com/en/docs/claude-code) is powerful out of the box, but teams need **consistent workflows** — shared commands, proven prompts, commit conventions, and reusable skills.
+[Claude Code](https://docs.anthropic.com/en/docs/claude-code) is powerful out of the box — but teams need **consistent, repeatable workflows**. Without shared conventions, every developer prompts differently, reviews differently, and debugs differently.
 
-devlyn-cli installs a curated `.claude/` configuration into any project, giving your team:
+devlyn-cli solves this by installing a curated `.claude/` configuration into any project:
 
-- Battle-tested slash commands for debugging, code review, UI design, and more
-- Reusable AI agent skills for debugging, code review, and UI implementation
-- Product and feature spec templates
-- Commit message conventions
+- **14 slash commands** for debugging, code review, UI design, documentation, and more
+- **5 core skills** that activate automatically based on conversation context
+- **Agent team workflows** that spawn specialized AI teammates for complex tasks
+- **Product & feature spec templates** for structured planning
+- **Commit conventions** for consistent git history
 
-Zero dependencies. One command. Works with any project.
+**Zero dependencies. One command. Works with any project.**
 
-## Quick Start
+## Get Started
 
 ```bash
 npx devlyn-cli
 ```
 
-That's it. The interactive installer walks you through the setup.
+The interactive installer walks you through setup — select optional skills, choose community packs, done.
 
 ```bash
-# Non-interactive mode (for CI/CD)
+# Non-interactive install (CI/CD friendly)
 npx devlyn-cli -y
 
-# Update to the latest config
+# Update to the latest version
 npx devlyn-cli@latest
 
-# List all available commands and templates
+# See everything that's included
 npx devlyn-cli list
 ```
 
-## What Gets Installed
+### What Gets Installed
 
 ```
 your-project/
 ├── .claude/
 │   ├── commands/              # 14 slash commands
-│   ├── skills/                # 5 core skills + optional addons
-│   ├── templates/             # Document templates
-│   └── commit-conventions.md  # Commit message standards
-└── CLAUDE.md                  # Project-level instructions
+│   ├── skills/                # 5 core skills + any optional addons
+│   ├── templates/             # Product spec, feature spec, prompt templates
+│   ├── commit-conventions.md  # Commit message standards
+│   └── settings.json          # Agent teams enabled
+└── CLAUDE.md                  # Project-level AI instructions
 ```
 
 ## Commands
 
-Slash commands are invoked directly in Claude Code conversations (e.g., `/devlyn.resolve`).
+Slash commands are invoked directly in Claude Code conversations (e.g., type `/devlyn.resolve`).
+
+### Debugging & Resolution
 
 | Command | Description |
 |---|---|
 | `/devlyn.resolve` | Systematic bug fixing with root-cause analysis and test-driven validation |
-| `/devlyn.team-resolve` | Team-based issue resolution — spawns specialized agent teammates (root cause analyst, test engineer, security auditor, etc.) |
-| `/devlyn.review` | Post-implementation code review — security, quality, best practices |
-| `/devlyn.team-review` | Team-based multi-perspective code review — spawns specialized reviewers (security, quality, testing, product, performance) |
-| `/devlyn.design-ui` | Generate 5 distinct UI style explorations from a spec or reference image |
-| `/devlyn.implement-ui` | Team-based UI implementation/improvement — spawns component architect, UX engineer, accessibility engineer, responsive engineer, visual QA |
-| `/devlyn.feature-spec` | Transform product specs into implementable feature specifications |
+| `/devlyn.team-resolve` | Spawns a full agent team — root cause analyst, test engineer, security auditor — to investigate complex issues |
+
+### Code Review & Quality
+
+| Command | Description |
+|---|---|
+| `/devlyn.review` | Post-implementation review — security, quality, best practices checklist |
+| `/devlyn.team-review` | Multi-perspective team review with specialized reviewers (security, quality, testing, performance, product) |
+| `/devlyn.clean` | Detect and remove dead code, unused dependencies, complexity hotspots, and tech debt |
+
+### UI Design & Implementation
+
+| Command | Description |
+|---|---|
+| `/devlyn.design-ui` | Generate 5 radically distinct UI style explorations from a spec or reference image |
+| `/devlyn.team-design-ui` | Spawns a design team — creative director, product designer, visual designer, interaction designer, accessibility designer |
+| `/devlyn.design-system` | Extract design system tokens from a chosen style for exact reproduction |
+| `/devlyn.implement-ui` | Team-based UI build — component architect, UX engineer, accessibility engineer, responsive engineer, visual QA |
+
+### Product & Planning
+
+| Command | Description |
+|---|---|
 | `/devlyn.product-spec` | Generate or incrementally update product spec documents |
-| `/devlyn.discover-product` | Scan a codebase to generate feature-oriented product documentation |
+| `/devlyn.feature-spec` | Transform product specs into implementable feature specifications |
+| `/devlyn.discover-product` | Scan codebase to generate feature-oriented product documentation |
 | `/devlyn.recommend-features` | Prioritize top 5 features to build next based on value and readiness |
-| `/devlyn.team-design-ui` | Team-based design exploration — spawns creative director, product designer, visual designer, interaction designer, accessibility designer |
-| `/devlyn.design-system` | Design system reference and guidance |
+
+### Documentation
+
+| Command | Description |
+|---|---|
 | `/devlyn.update-docs` | Sync all project docs with current codebase — cleans stale content, preserves roadmaps, generates missing docs |
-| `/devlyn.clean` | Detect and remove dead code, unused dependencies, complexity hotspots, and tech debt |
 
 ## Skills
 
-Skills are triggered automatically based on conversation context.
+Skills are **not invoked manually** — they activate automatically when Claude Code detects a relevant conversation context. Think of them as always-on expertise that shapes how the AI approaches specific types of work.
 
-| Skill | Description |
-|---|---|
-| `root-cause-analysis` | 5 Whys methodology, evidence standards, and no-workaround rules for debugging |
-| `code-review-standards` | Severity framework, quality bar, and approval criteria for code reviews |
-| `ui-implementation-standards` | Design system fidelity, accessibility, animation quality, and responsive standards for UI work |
-| `code-health-standards` | Dead code prevention, dependency discipline, complexity thresholds, and production hygiene |
-| `workflow-routing` | SDLC phase map — guides you to the right command for your current task |
+| Skill | When It Activates | What It Does |
+|---|---|---|
+| `root-cause-analysis` | Debugging conversations | Enforces 5 Whys methodology, evidence standards, and no-workaround rules |
+| `code-review-standards` | Code review tasks | Applies severity framework, quality bar, and approval criteria |
+| `ui-implementation-standards` | UI/frontend work | Ensures design fidelity, accessibility, animation quality, and responsive standards |
+| `code-health-standards` | Code maintenance | Enforces dead code prevention, dependency discipline, and complexity thresholds |
+| `workflow-routing` | Any task | SDLC phase map — guides you to the right command for your current task |
+
+## Workflows
 
-## Templates
+Commands are designed to compose. Pick the right tool based on scope, then chain them together.
 
-| Template | Description |
+### Recommended Workflow
+
+The full fix → polish → review → maintain cycle:
+
+| Step | Command | What It Does |
+|---|---|---|
+| 1. **Resolve** | `/devlyn.resolve` or `/devlyn.team-resolve` | Fix the issue — solo for focused bugs (1-2 modules), team for complex issues (3+ modules) |
+| 2. **Simplify** | `/simplify` | Quick cleanup pass for reuse, quality, and efficiency *(built-in Claude Code command)* |
+| 3. **Review** | `/devlyn.review` or `/devlyn.team-review` | Audit the changes — solo for small PRs (< 10 files), team for large PRs (10+ files) |
+| | | *If the review finds issues, loop back to step 1* |
+| 4. **Clean** | `/devlyn.clean` | Remove dead code, unused dependencies, and complexity hotspots |
+| 5. **Document** | `/devlyn.update-docs` | Sync project documentation with the current codebase |
+
+Steps 4-5 are optional — run them periodically rather than on every PR. Steps 1-3 are the core loop.
+
+> **Tip:** Consider running `/devlyn.review` once more after steps 4-5. `/devlyn.clean` removes code and `/devlyn.update-docs` changes docs — a final review pass catches accidental regressions from cleanup.
+
+> **Scope matching matters.** For a simple one-file bug, `/devlyn.resolve` + `/devlyn.review` (solo) is fast. For a multi-module feature, `/devlyn.team-resolve` + `/devlyn.team-review` (team) gives you parallel specialist perspectives. Don't over-tool simple changes.
+
+### UI Design Pipeline
+
+A full explore → extract → build pipeline:
+
+| Step | Command | What It Does |
+|---|---|---|
+| 1. **Explore** | `/devlyn.design-ui` | Generates 5 radically distinct style options from a spec or reference image |
+| 2. **Extract** | `/devlyn.design-system` | Pulls exact design tokens (colors, spacing, typography) from your chosen style |
+| 3. **Build** | `/devlyn.implement-ui` | Spawns a build team (component architect, UX engineer, accessibility engineer, responsive engineer, visual QA) |
+
+> For design exploration with a full creative team, use `/devlyn.team-design-ui` instead of step 1.
+
+After building, follow the [recommended workflow](#recommended-workflow) starting from step 2 (simplify) to review and polish the implementation.
+
+### Standalone Tools
+
+These commands work independently, outside of the main workflow:
+
+| Command | What It Does |
 |---|---|
-| `template-product-spec.md` | Comprehensive product specification template |
-| `template-feature.spec.md` | Feature specification template |
-| `prompt-templates.md` | Reusable prompt snippets for common tasks |
+| `/devlyn.clean [focus]` | Focused cleanup — e.g., `/devlyn.clean dependencies` or `/devlyn.clean dead-code` |
+| `/devlyn.update-docs [area]` | Focused doc sync — e.g., `/devlyn.update-docs API reference` |
+| `/devlyn.product-spec` | Generate or update a product specification |
+| `/devlyn.feature-spec` | Transform a product spec into an implementable feature spec |
+| `/devlyn.discover-product` | Scan codebase to auto-generate product documentation |
+| `/devlyn.recommend-features` | Prioritize top 5 features to build next |
 
 ## Optional Skills & Packs
 
-During installation, you can choose to add optional skills and third-party skill packs:
+During installation, the interactive selector lets you add optional skills and community packs.
 
-| Addon | Type | Description |
-|---|---|---|
-| `cloudflare-nextjs-setup` | skill | Cloudflare Workers + Next.js deployment with OpenNext |
-| `generate-skill` | skill | Create well-structured Claude Code skills following Anthropic best practices |
-| `prompt-engineering` | skill | Claude 4 prompt optimization using Anthropic best practices |
-| `better-auth-setup` | skill | Production-ready Better Auth + Hono + Drizzle + PostgreSQL auth setup |
-| `pyx-scan` | skill | Check whether an AI agent skill is safe before installing |
-| `vercel-labs/agent-skills` | pack | React, Next.js, React Native best practices |
-| `supabase/agent-skills` | pack | Supabase integration patterns |
-| `coreyhaines31/marketingskills` | pack | Marketing automation and content skills |
-| `anthropics/skills` | pack | Official Anthropic skill-creator with eval framework and description optimizer |
+### Skills
+
+Copied directly into your `.claude/skills/` directory.
+
+| Skill | Description |
+|---|---|
+| `cloudflare-nextjs-setup` | Cloudflare Workers + Next.js deployment with OpenNext |
+| `generate-skill` | Create well-structured Claude Code skills following Anthropic best practices |
+| `prompt-engineering` | Claude 4 prompt optimization using official Anthropic best practices |
+| `better-auth-setup` | Production-ready Better Auth + Hono + Drizzle + PostgreSQL auth setup |
+| `pyx-scan` | Check whether an AI agent skill is safe before installing |
+
+### Community Packs
+
+Installed via the [skills CLI](https://github.com/anthropics/skills) (`npx skills add`). These are maintained by their respective communities.
+
+| Pack | Description |
+|---|---|
+| `vercel-labs/agent-skills` | React, Next.js, React Native best practices |
+| `supabase/agent-skills` | Supabase integration patterns |
+| `coreyhaines31/marketingskills` | Marketing automation and content skills |
+| `anthropics/skills` | Official Anthropic skill-creator with eval framework and description optimizer |
+
+> **Want to add a pack?** Open a PR adding your pack to the `OPTIONAL_ADDONS` array in [`bin/devlyn.js`](bin/devlyn.js).
 
 ## How It Works
 
-1. Run `npx devlyn-cli` in your project
-2. The CLI copies the config files into `.claude/`
-3. Claude Code automatically reads `.claude/commands` and `.claude/skills`
-4. Invoke commands like `/devlyn.resolve` in your Claude Code session
+1. **Run `npx devlyn-cli`** in your project root
+2. The CLI copies config files into `.claude/` and `CLAUDE.md` to the project root
+3. Claude Code automatically reads `.claude/commands/` and `.claude/skills/` on startup
+4. Invoke commands like `/devlyn.resolve` in your Claude Code session — skills activate on their own
+
+The installation is **idempotent** — run it again anytime to update to the latest config.
 
-The installation is **idempotent** — run it again at any time to update to the latest config.
+## Creating Your Own Skills
+
+Want to author custom skills for your team or the community?
+
+1. **During install**, select the `generate-skill` optional skill — or —
+2. **Install the official Anthropic skill-creator** pack:
+   ```bash
+   npx skills add anthropics/skills
+   ```
+
+Both provide structured templates, best practices, and eval frameworks for writing high-quality Claude Code skills.
+
+See the [Claude Code skills documentation](https://docs.anthropic.com/en/docs/claude-code/skills) for the full specification.
 
 ## Requirements
 
-- Node.js 18+
-- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI
+- **Node.js 18+**
+- **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** CLI installed and configured
 
 ## Contributing
 
-Contributions are welcome! Feel free to open an issue or submit a pull request.
+Contributions are welcome! Here are some ways to get involved:
+
+- **Add a command** — Create a new `.md` file in `config/commands/`
+- **Add a skill** — Create a new directory in `config/skills/` with a `SKILL.md`
+- **Add an optional skill** — Add to `optional-skills/` and the `OPTIONAL_ADDONS` array
+- **Suggest a community pack** — Open a PR to add it to the pack list
+
+### Development
 
 1. Fork the repository
 2. Create your branch (`git checkout -b feat/my-feature`)
@@ -143,4 +252,3 @@ Contributions are welcome! Feel free to open an issue or submit a pull request.
 ## License
 
 [MIT](LICENSE) — Donut Studio
-

package/bin/devlyn.js

@@ -7,6 +7,7 @@ const { execSync } = require('child_process');
 
 const CONFIG_SOURCE = path.join(__dirname, '..', 'config');
 const OPTIONAL_SKILLS_SOURCE = path.join(__dirname, '..', 'optional-skills');
+const OPTIONAL_COMMANDS_SOURCE = path.join(__dirname, '..', 'optional-commands');
 const PKG = require('../package.json');
 
 // Files removed in previous versions that should be cleaned up on upgrade
@@ -69,6 +70,8 @@ const OPTIONAL_ADDONS = [
   { name: 'prompt-engineering', desc: 'Claude 4 prompt optimization using Anthropic best practices', type: 'local' },
   { name: 'better-auth-setup', desc: 'Production-ready Better Auth + Hono + Drizzle + PostgreSQL auth setup', type: 'local' },
   { name: 'pyx-scan', desc: 'Check whether an AI agent skill is safe before installing', type: 'local' },
+  // Local optional commands (copied to .claude/commands/)
+  { name: 'pencil-sync', desc: 'Sync designs between codebase and Pencil (.pen files) via MCP', type: 'command' },
   // 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' },
@@ -170,7 +173,9 @@ function listContents() {
   // List optional addons
   log('\n📦 Optional Addons:', 'blue');
   OPTIONAL_ADDONS.forEach((addon) => {
-    const tag = addon.type === 'local' ? `${COLORS.magenta}skill${COLORS.reset}` : `${COLORS.cyan}pack${COLORS.reset}`;
+    const tagLabel = addon.type === 'command' ? 'cmd' : addon.type === 'local' ? 'skill' : 'pack';
+    const tagColor = addon.type === 'command' ? COLORS.green : addon.type === 'local' ? COLORS.magenta : COLORS.cyan;
+    const tag = `${tagColor}${tagLabel}${COLORS.reset}`;
     log(`  ${COLORS.green}${addon.name}${COLORS.reset} ${COLORS.dim}[${tag}${COLORS.dim}]${COLORS.reset}`);
     log(`     ${COLORS.dim}${addon.desc}${COLORS.reset}`);
   });
@@ -232,7 +237,9 @@ function multiSelect(items) {
         const checkbox = selected.has(i) ? `${COLORS.green}◉${COLORS.reset}` : `${COLORS.dim}○${COLORS.reset}`;
         const pointer = i === cursor ? `${COLORS.cyan}❯${COLORS.reset}` : ' ';
         const name = i === cursor ? `${COLORS.cyan}${item.name}${COLORS.reset}` : item.name;
-        const tag = item.type === 'local' ? `${COLORS.magenta}skill${COLORS.reset}` : `${COLORS.cyan}pack${COLORS.reset}`;
+        const tagLabel = item.type === 'command' ? 'cmd' : item.type === 'local' ? 'skill' : 'pack';
+        const tagColor = item.type === 'command' ? COLORS.green : item.type === 'local' ? COLORS.magenta : COLORS.cyan;
+        const tag = `${tagColor}${tagLabel}${COLORS.reset}`;
         console.log(`${pointer} ${checkbox} ${name} ${COLORS.dim}[${tag}${COLORS.dim}]${COLORS.reset}`);
         console.log(`    ${COLORS.dim}${item.desc}${COLORS.reset}`);
       });
@@ -318,6 +325,30 @@ function installLocalSkill(skillName) {
   return true;
 }
 
+function installLocalCommand(commandName) {
+  const src = path.join(OPTIONAL_COMMANDS_SOURCE, commandName);
+  const targetDir = getTargetDir();
+  const destDir = path.join(targetDir, 'commands');
+
+  if (!fs.existsSync(src)) {
+    log(`   ⚠️  Command pack "${commandName}" not found`, 'yellow');
+    return false;
+  }
+
+  log(`\n📋 Installing ${commandName} commands...`, 'cyan');
+
+  if (!fs.existsSync(destDir)) {
+    fs.mkdirSync(destDir, { recursive: true });
+  }
+
+  const files = fs.readdirSync(src).filter((f) => f.endsWith('.md'));
+  for (const file of files) {
+    fs.copyFileSync(path.join(src, file), path.join(destDir, file));
+    log(`  → commands/${file}`, 'dim');
+  }
+  return true;
+}
+
 function installSkillPack(packName) {
   try {
     log(`\n📦 Installing ${packName}...`, 'cyan');
@@ -333,6 +364,9 @@ function installAddon(addon) {
   if (addon.type === 'local') {
     return installLocalSkill(addon.name);
   }
+  if (addon.type === 'command') {
+    return installLocalCommand(addon.name);
+  }
   return installSkillPack(addon.name);
 }
 
@@ -385,9 +419,9 @@ async function init(skipPrompts = false) {
 
   // Skip prompts if -y flag or non-interactive
   if (skipPrompts || !process.stdin.isTTY) {
-    log('\n💡 Add optional skills & packs later:', 'dim');
+    log('\n💡 Add optional addons later:', 'dim');
     OPTIONAL_ADDONS.forEach((addon) => {
-      if (addon.type === 'local') {
+      if (addon.type === 'local' || addon.type === 'command') {
         log(`   npx devlyn-cli  (select "${addon.name}" during install)`, 'dim');
       } else {
         log(`   npx skills add ${addon.name}`, 'dim');

package/optional-commands/pencil-sync/devlyn.pencil-pull.md

@@ -0,0 +1,123 @@
+# Pull Pencil Design into Code
+
+Implement the selected Pencil design in code with exact visual fidelity. Work through one component at a time, verifying each against the design before moving on.
+
+<project_context>
+- Next.js 16 + React 19, Server Components by default
+- Custom CSS with CSS variables (no Tailwind) — tokens live in `src/app/globals.css`
+- Three visual zones, each with its own CSS file and class prefix:
+  - Marketing (`marketing.css`) — cinematic, descriptive class names
+  - Auth (`auth.css`) — minimal, `auth-` prefix
+  - Dashboard (`dashboard.css`) — functional, `dash-` prefix
+- Design system reference: `docs/design-system.md`
+</project_context>
+
+<goal>
+The coded implementation should be visually indistinguishable from the Pencil design. Small discrepancies — a few pixels of padding, a slightly different font weight, a missing border-radius — compound across components and produce a result that "looks off" even if no single difference is dramatic. Treat the Pencil design as the pixel-level specification and match it exactly.
+
+The only areas where interpretation is needed:
+- Interactive states (hover, focus, active) — Pencil can't represent these, so follow existing patterns in the codebase
+- Responsive behavior — implement following existing responsive patterns
+- Dynamic content — use the design's placeholder text for empty states
+</goal>
+
+## How to approach this
+
+<setup>
+Before writing any code, gather context:
+1. Call `get_editor_state(include_schema: true)` to see the active .pen file and current selection. If the user has selected a frame, that's your target. If not, ask which frame/screen to implement.
+2. Call `get_guidelines(topic: "code")` for Pencil's code generation rules. These supplement the project-specific conventions below.
+3. Call `get_variables` to extract design tokens. Map each Pencil variable to its CSS custom property in `globals.css`. If new variables exist in Pencil that aren't in the CSS yet, add them to `globals.css` following the existing naming convention.
+
+Design tokens flow: `Pencil variables → globals.css custom properties → Component CSS`. This chain keeps design and code in sync, so use CSS variables rather than hardcoding values.
+</setup>
+
+<implementation>
+Work through components one at a time rather than attempting the full screen at once. This matters because verifying a single component is quick and reliable, while trying to verify an entire screen introduces too many variables — you can't tell which component introduced a discrepancy.
+
+For each component:
+
+**1. Read the design thoroughly**
+Use `batch_get` with the component's node ID (`readDepth: 10`, `resolveVariables: true`) to get the complete tree. For components with SVGs, also set `includePathGeometry: true`. If it's a reusable component, read its instances too — they often override text, colors, or child visibility.
+
+**2. Screenshot as ground truth**
+Call `get_screenshot` on the component. Study the screenshot carefully — this is your specification. Note exact spacing, font sizes, colors, borders, shadows, border-radius, alignment, and text content.
+
+**3. Check for existing code**
+Search `src/components/` and `src/app/` for matching component names or CSS classes. If the component already exists, update it. Creating a duplicate leads to divergence over time.
+
+**4. Implement**
+Match every visual property from the design:
+- Layout: flex direction, gap, padding, margin, alignment
+- Sizing: exact width/height, `fill_container` → `width: 100%` or `flex: 1`, `fit_content` → `width: fit-content`
+- Colors: map to CSS custom properties (`var(--bg-deep)`, `var(--accent)`, etc.)
+- Typography: font-family, font-size, font-weight, line-height, letter-spacing, color
+- Borders: width, color, radius (map to `var(--radius-*)`)
+- Effects: box-shadow, opacity, backdrop-filter
+- Text content: copy exactly, character for character
+- Icons: match the icon, size, and color
+
+When updating existing components, preserve all event handlers, state management, and data flow. Only change visual/layout properties.
+
+**5. Verify**
+Take another `get_screenshot` and compare. Check: are colors identical (not close)? Are font sizes and weights exact? Is spacing pixel-accurate? Are border-radius values correct? Is text character-for-character? Are all child elements present (count them)?
+
+Fix any difference before moving to the next component.
+
+**6. Report**
+State what file was created/modified, list any new CSS variables added, and note any design decisions that required interpretation.
+</implementation>
+
+<integration_check>
+After all components are implemented, verify the page-level layout:
+- Use `batch_get` to read the complete target frame with full depth
+- Check component ordering, spacing between components, and overall structure
+- Use `snapshot_layout` to compare Pencil's computed layout rectangles against the CSS layout
+</integration_check>
+
+<examples>
+
+**Example: Pulling a dashboard card component**
+
+The Pencil design shows a card with `cornerRadius: 16` (maps to `var(--radius-md)`), `fill: $bg-deep`, `padding: 24`, and a title text in Space Grotesk at 14px/600. The `batch_get` output shows:
+```
+{type: "frame", cornerRadius: 16, fill: "$bg-deep", padding: 24, layout: "vertical", gap: 12,
+ children: [{type: "text", content: "Active Projects", fontFamily: "Space Grotesk", fontSize: 14, fontWeight: 600}]}
+```
+Search code → find `.dash-card` in `dashboard.css`. Update it:
+```css
+.dash-card {
+  background: var(--bg-deep);
+  border-radius: var(--radius-md);
+  padding: 24px;
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+.dash-card h3 {
+  font-family: var(--space);
+  font-size: 14px;
+  font-weight: 600;
+}
+```
+
+**Example: Pulling a component with instance overrides**
+
+A button component is reusable in Pencil. The base definition has `content: "Button"` and `fill: "$accent"`. But the instance in this frame overrides `content: "Deploy Now"` and adds a `descendants` override hiding an icon child. You need to:
+1. Read both the base component and this specific instance
+2. Implement the component with the overridden text "Deploy Now"
+3. Respect the hidden icon — don't render it in this usage
+4. Screenshot-verify the result matches the instance, not the base
+
+</examples>
+
+## Pencil MCP tools you'll use
+
+| Task | Tool | Key Params |
+|------|------|-----------|
+| Check what's open | `get_editor_state` | `include_schema: true` |
+| Read design nodes | `batch_get` | `readDepth`, `resolveVariables`, `includePathGeometry` |
+| Take screenshot | `get_screenshot` | `nodeId` |
+| Check layout | `snapshot_layout` | `maxDepth` |
+| Get design tokens | `get_variables` | — |
+| Get code guidelines | `get_guidelines` | `topic: "code"` |

package/optional-commands/pencil-sync/devlyn.pencil-push.md

@@ -0,0 +1,70 @@
+# Push Codebase Design to Pencil
+
+Read the current UI implementation and recreate it as a matching design in Pencil, so the .pen canvas accurately reflects what's live in code.
+
+<project_context>
+- Next.js 16 + React 19, Server Components by default
+- Custom CSS with CSS variables (no Tailwind) — tokens live in `src/app/globals.css`
+- Three visual zones, each with its own CSS file and class prefix:
+  - Marketing (`marketing.css`) — cinematic, descriptive class names
+  - Auth (`auth.css`) — minimal, `auth-` prefix
+  - Dashboard (`dashboard.css`) — functional, `dash-` prefix
+- Design system reference: `docs/design-system.md`
+</project_context>
+
+<goal>
+The Pencil file should be a faithful mirror of the coded UI. When someone opens the .pen file, they should see exactly what the live site looks like — same colors, spacing, typography, radii, and component structure. This matters because the .pen file becomes the source of truth for future design iterations: if it drifts from code, every subsequent design change will introduce unintended differences.
+</goal>
+
+## How to approach this
+
+<setup>
+Start by understanding the current state:
+1. Call `get_editor_state(include_schema: true)` to see if a .pen file is already open. If not, either create one with `open_document("new")` or ask which .pen file to target.
+2. Read the codebase's design tokens from `src/app/globals.css` and `docs/design-system.md`. Also read the zone-specific CSS file for whichever zone the user wants to push.
+3. Sync tokens into Pencil: use `get_variables` to check what exists, then `set_variables` to create/update variables matching the CSS custom properties (colors, radii, fonts). Use Pencil variables throughout — this keeps themes connected between code and Pencil.
+</setup>
+
+<implementation>
+Work through each component or section one at a time rather than trying to build the entire page in one pass. Building incrementally lets you verify each piece against the code before moving on, which prevents small errors from compounding into large drift.
+
+For each component:
+1. Read the `.tsx` file and its CSS to understand layout, children, and styles
+2. Build the matching frame structure in Pencil using `batch_design` (max 25 operations per call)
+3. Apply styles using Pencil variables — match exact pixel values from CSS for spacing, font sizes, border-radius, etc.
+4. Take a `get_screenshot` and compare against the coded version
+5. Fix any discrepancies before moving on
+
+Name Pencil frames and nodes to match CSS class names or React component names. This makes it easy to trace between code and design later.
+</implementation>
+
+<examples>
+
+**Example: Pushing a dashboard sidebar**
+
+The sidebar component lives at `src/components/dashboard/Sidebar.tsx` with styles in `dashboard.css` using `.dash-sidebar`. You would:
+1. Read both files to extract: width (280px via `--sidebar-width`), background color (`var(--bg-deep)`), flex layout (vertical, gap), and all child nav items
+2. Create a frame in Pencil with `width: 280`, `fill: $bg-deep`, `layout: vertical`, matching gap/padding
+3. Add child text nodes and icon frames matching each nav link
+4. Screenshot and verify dimensions, colors, and text content match
+
+**Example: Pushing a glass panel component**
+
+The `.glass-panel` class in `globals.css` has `border-radius: var(--radius-3xl)` (44px), `backdrop-filter: blur(20px)`, and a liquid highlight. You would:
+1. Create a frame with `cornerRadius: 44`, matching the backdrop-filter effect as closely as Pencil supports
+2. Use the `$glass-bg` variable for background
+3. Verify the panel looks visually consistent with the coded version
+
+</examples>
+
+## Pencil MCP tools you'll use
+
+| Task | Tool | Key Params |
+|------|------|-----------|
+| Check what's open | `get_editor_state` | `include_schema: true` |
+| Open/create .pen file | `open_document` | `"new"` or file path |
+| Read design nodes | `batch_get` | `readDepth`, `searchDepth` |
+| Take screenshot | `get_screenshot` | `nodeId` |
+| Check layout | `snapshot_layout` | `maxDepth` |
+| Get/set design tokens | `get_variables` / `set_variables` | — |
+| Build design | `batch_design` | operations string (max 25 ops) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devlyn-cli",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Claude Code configuration toolkit for teams",
   "bin": {
     "devlyn": "bin/devlyn.js"
@@ -8,6 +8,7 @@
   "files": [
     "bin",
     "config",
+    "optional-commands",
     "optional-skills",
     "CLAUDE.md"
   ],