devlyn-cli 1.5.4 → 1.7.0

package/README.md

@@ -6,295 +6,207 @@
   <img alt="DEVLYN" src="assets/logo.svg" width="540" />
 </picture>
 
-### Context Engineering & Harness Engineering Toolkit for Claude Code
+### The AI Development Toolkit for Claude Code
 
-**Structured prompts, agent orchestration, and automated pipelines — debugging, code review, UI design, product specs, and more.**
+**Ideate. Resolve. Ship. — All from your terminal.**
 
 [![npm version](https://img.shields.io/npm/v/devlyn-cli.svg)](https://www.npmjs.com/package/devlyn-cli)
+[![npm downloads](https://img.shields.io/npm/dw/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)
+If devlyn-cli saved you time, [give it a star](https://github.com/fysoul17/devlyn-cli) — it helps others find it too.
 
 </div>
 
 ---
 
-## Why devlyn-cli?
-
-[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 solves this with two complementary engineering approaches:
-
-### Context Engineering
-
-Structured prompts and role-based instructions that shape _what the AI knows and how it thinks_ for each task.
-
-- **16 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 with role-specific expertise
-- **Product & feature spec templates** for structured planning
-
-### Harness Engineering
-
-Pipeline orchestration that controls _how agents execute_ — permissions, state management, multi-phase workflows, and cross-model evaluation.
-
-- **`/devlyn:auto-resolve`** — 9-phase automated pipeline (build → browser validate → evaluate → fix loop → simplify → review → security → clean → docs)
-- **`/devlyn:browser-validate`** — feature verification in a real browser with tiered fallback (Chrome MCP → Playwright → curl)
-- **`bypassPermissions` mode** for autonomous subagent execution
-- **File-based state machine** — agents communicate via `.devlyn/done-criteria.md`, `EVAL-FINDINGS.md`, and `BROWSER-RESULTS.md`
-- **Git checkpoints** at each phase for rollback safety
-- **Cross-model evaluation** via `--with-codex` flag (OpenAI Codex as independent evaluator)
-
-**Zero dependencies. One command. Works with any project.**
-
-## Get Started
+## Install
 
 ```bash
 npx devlyn-cli
 ```
 
-The interactive installer walks you through setup — select optional skills, choose community packs, done.
-
-```bash
-# Non-interactive install (CI/CD friendly)
-npx devlyn-cli -y
+That's it. The interactive installer handles everything. Run it again anytime to update.
 
-# Update to the latest version
-npx devlyn-cli@latest
+---
 
-# See everything that's included
-npx devlyn-cli list
-```
+## How It Works — Two Commands, Full Cycle
 
-### What Gets Installed
+devlyn-cli turns Claude Code into an autonomous development pipeline. The core loop is simple:
 
 ```
-your-project/
-├── .claude/
-│   ├── commands/              # 16 slash commands
-│   ├── 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
+ideate  →  auto-resolve  →  ship  →  repeat
 ```
 
-## Commands
+### Step 1 — Plan with `/devlyn:ideate`
 
-Slash commands are invoked directly in Claude Code conversations (e.g., type `/devlyn:resolve`).
-
-### Debugging & Resolution
+Turn a raw idea into structured, implementation-ready specs.
 
-| Command | Description |
-|---|---|
-| `/devlyn:resolve` | Systematic bug fixing with root-cause analysis and test-driven validation |
-| `/devlyn:team-resolve` | Spawns a full agent team — root cause analyst, test engineer, security auditor — to investigate complex issues |
-| `/devlyn:auto-resolve` | Fully automated pipeline for any task — bugs, features, refactors, chores. Build → browser validate → evaluate → fix loop → simplify → review → clean → docs. One command, zero human intervention. Supports `--with-codex` for cross-model evaluation via OpenAI Codex |
-| `/devlyn:browser-validate` | Verify implemented features work in a real browser — starts dev server, tests the feature end-to-end (clicks, forms, verification), with tiered fallback (Chrome MCP → Playwright → curl) |
+```
+/devlyn:ideate "I want to build a habit tracking app with AI nudges"
+```
 
-### Code Review & Quality
+This produces three documents through interactive brainstorming:
 
-| Command | Description |
+| Document | What It Contains |
 |---|---|
-| `/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:evaluate` | Independent quality evaluation — assembles evaluator team to grade work against done criteria with calibrated, skeptical grading |
-| `/devlyn:clean` | Detect and remove dead code, unused dependencies, complexity hotspots, and tech debt |
+| `docs/VISION.md` | North star, principles, anti-goals |
+| `docs/ROADMAP.md` | Phased roadmap with links to each spec |
+| `docs/roadmap/phase-N/*.md` | Self-contained spec per feature — ready for auto-resolve |
 
-### UI Design & Implementation
+Need to add features later? Run ideate again — it expands the existing roadmap.
 
-| 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 |
+### Step 2 — Build with `/devlyn:auto-resolve`
 
-### Product & Planning
+Point it at a spec (or just describe what you want) and walk away.
 
-| Command | Description |
-|---|---|
-| `/devlyn:product-spec` | Generate or incrementally update product spec documents |
-| `/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:auto-resolve "Implement per spec at docs/roadmap/phase-1/1.1-user-auth.md"
+```
 
-### Documentation
+It runs a **9-phase pipeline** autonomously:
 
-| Command | Description |
-|---|---|
-| `/devlyn:update-docs` | Sync all project docs with current codebase — cleans stale content, preserves roadmaps, generates missing docs |
+```
+Build → Browser Test → Evaluate → Fix Loop → Simplify → Review → Security → Clean → Docs
+```
 
-## Skills
+- Each phase runs as a separate agent with fresh context
+- Git checkpoints at every phase for safe rollback
+- Browser validation tests your feature end-to-end (clicks, forms, verification)
+- Evaluation grades against done-criteria — if it fails, auto-fix and re-evaluate
 
-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.
+Skip phases you don't need: `--skip-browser`, `--skip-review`, `--skip-clean`, `--skip-docs`, `--max-rounds 6`
 
-| 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 |
+### Bonus — Dual-Model Mode with Codex
 
-## Workflows
+Install the Codex MCP server during setup, then:
 
-Commands are designed to compose. Pick the right tool based on scope, then chain them together.
+```
+/devlyn:auto-resolve "fix the auth bug" --with-codex
+```
 
-### Automated Pipeline (Recommended)
+Claude builds, **OpenAI Codex evaluates independently** — two models collaborating, catching what a single model misses.
 
-One command runs the full cycle — no human intervention needed:
+> `--with-codex evaluate` (default) · `--with-codex review` · `--with-codex both`
 
-```bash
-/devlyn:auto-resolve fix the auth bug where users see blank screen on 401
-```
-
-| Phase | What Happens |
-|---|---|
-| **Build** | `team-resolve` investigates and implements, writes testable done criteria |
-| **Browser Validate** | For web projects: starts dev server, tests the implemented feature end-to-end in a real browser, fixes issues found |
-| **Evaluate** | Independent evaluator grades against done criteria with calibrated skepticism |
-| **Fix Loop** | If evaluation fails, fixes findings and re-evaluates (up to N rounds) |
-| **Simplify** | Quick cleanup pass for reuse and efficiency |
-| **Review** | Multi-perspective team review |
-| **Security** | Dedicated OWASP-focused audit (auto-detects when changes touch auth, secrets, APIs) |
-| **Clean** | Remove dead code and unused dependencies |
-| **Docs** | Sync documentation with changes |
+---
 
-Each phase runs as a separate subagent (fresh context), communicates via files, and commits a git checkpoint for rollback safety. Skip phases with flags: `--skip-browser`, `--skip-review`, `--skip-clean`, `--skip-docs`, `--max-rounds 3`, `--with-codex` (cross-model evaluation via OpenAI Codex).
+## Manual Commands
 
-### Manual Workflow
+When you want step-by-step control instead of the full pipeline.
 
-For step-by-step control between phases:
+### Debugging & Resolution
 
-| 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. **Evaluate** | `/devlyn:evaluate` | Independent quality evaluation — grades against done criteria written in step 1 |
-| | | *If the evaluation finds issues: `/devlyn:team-resolve "Fix issues in .devlyn/EVAL-FINDINGS.md"`* |
-| 3. **Simplify** | `/simplify` | Quick cleanup pass for reuse, quality, and efficiency *(built-in Claude Code command)* |
-| 4. **Review** | `/devlyn:review` or `/devlyn:team-review` | Audit the changes — solo for small PRs (< 10 files), team for large PRs (10+ files) |
-| 5. **Clean** | `/devlyn:clean` | Remove dead code, unused dependencies, and complexity hotspots |
-| 6. **Document** | `/devlyn:update-docs` | Sync project documentation with the current codebase |
+| Command | Use When |
+|---|---|
+| `/devlyn:resolve` | Simple bugs (1-2 files) |
+| `/devlyn:team-resolve` | Complex issues — spawns root-cause analyst, test engineer, security auditor |
+| `/devlyn:browser-validate` | Test a web feature in a real browser (Chrome MCP → Playwright → curl fallback) |
 
-Steps 5-6 are optional — run them periodically rather than on every PR.
+### Code Review & Quality
 
-> **Scope matching matters.** For a simple one-file bug, `/devlyn:resolve` + `/devlyn:review` (solo) is fast. For a multi-module feature, `/devlyn:auto-resolve` handles everything. Don't over-tool simple changes.
+| Command | Use When |
+|---|---|
+| `/devlyn:review` | Solo review — security, quality, best practices checklist |
+| `/devlyn:team-review` | Multi-reviewer team — security, testing, performance, product perspectives |
+| `/devlyn:evaluate` | Grade work against done-criteria with calibrated skepticism |
+| `/devlyn:clean` | Remove dead code, unused deps, complexity hotspots |
 
 ### 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.
+| 1 | `/devlyn:design-ui` | Generate 5 distinct style explorations |
+| 2 | `/devlyn:design-system` | Extract design tokens from chosen style |
+| 3 | `/devlyn:implement-ui` | Team builds it — component architect, UX, accessibility, responsive, visual QA |
 
-After building, follow the [recommended workflow](#recommended-workflow) starting from step 2 (simplify) to review and polish the implementation.
+> Use `/devlyn:team-design-ui` for step 1 with a full creative team.
 
-### Standalone Tools
-
-These commands work independently, outside of the main workflow:
+### Planning & Docs
 
 | Command | What It Does |
 |---|---|
-| `/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:product-spec` | Generate or update product specs |
+| `/devlyn:feature-spec` | Turn product spec → implementable feature spec |
+| `/devlyn:discover-product` | Scan codebase → auto-generate product docs |
 | `/devlyn:recommend-features` | Prioritize top 5 features to build next |
+| `/devlyn:update-docs` | Sync all docs with current codebase |
+
+---
 
-## Optional Skills & Packs
+## Auto-Activated Skills
 
-During installation, the interactive selector lets you add optional skills and community packs.
+These activate automatically — no commands needed. They shape how Claude thinks during relevant tasks.
 
-### Skills
+| Skill | Activates During |
+|---|---|
+| `root-cause-analysis` | Debugging — enforces 5 Whys, evidence standards |
+| `code-review-standards` | Reviews — severity framework, approval criteria |
+| `ui-implementation-standards` | UI work — design fidelity, accessibility, responsiveness |
+| `code-health-standards` | Maintenance — dead code prevention, complexity thresholds |
+| `workflow-routing` | Any task — guides you to the right command |
+
+---
+
+## Optional Add-ons
 
-Copied directly into your `.claude/skills/` directory.
+Selected during install. Run `npx devlyn-cli` again to add more.
+
+<details>
+<summary><strong>Skills</strong> — copied to <code>.claude/skills/</code></summary>
 
 | 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 |
-| `dokkit` | Document template filling for DOCX/HWPX — ingest, fill, review, export |
-| `devlyn:pencil-pull` | Pull Pencil designs into code with exact visual fidelity |
-| `devlyn:pencil-push` | Push codebase UI to Pencil canvas for design sync |
+| `cloudflare-nextjs-setup` | Cloudflare Workers + Next.js with OpenNext |
+| `generate-skill` | Create Claude Code skills following Anthropic best practices |
+| `prompt-engineering` | Claude 4 prompt optimization |
+| `better-auth-setup` | Better Auth + Hono + Drizzle + PostgreSQL |
+| `pyx-scan` | Check if an AI agent skill is safe before installing |
+| `dokkit` | Document template filling for DOCX/HWPX |
+| `devlyn:pencil-pull` | Pull Pencil designs into code |
+| `devlyn:pencil-push` | Push codebase UI to Pencil canvas |
 
-### Community Packs
+</details>
 
-Installed via the [skills CLI](https://github.com/anthropics/skills) (`npx skills add`). These are maintained by their respective communities.
+<details>
+<summary><strong>Community Packs</strong> — installed via <a href="https://github.com/anthropics/skills">skills CLI</a></summary>
 
 | 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 |
-| `Leonxlnx/taste-skill` | Premium frontend design skills — modern layouts, animations, and visual refinement |
+| `anthropics/skills` | Official Anthropic skill-creator with eval framework |
+| `Leonxlnx/taste-skill` | Premium frontend design skills |
 
-### MCP Servers
+</details>
 
-Installed via `claude mcp add` during setup.
+<details>
+<summary><strong>MCP Servers</strong> — installed via <code>claude mcp add</code></summary>
 
 | Server | Description |
 |---|---|
-| `codex-cli` | Codex MCP server for cross-model evaluation via OpenAI Codex |
-| `playwright` | Playwright MCP for browser testing — powers `devlyn:browser-validate` Tier 2 |
-
-> **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 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
+| `codex-cli` | Codex MCP server — enables `--with-codex` dual-model mode |
+| `playwright` | Playwright MCP — powers browser-validate Tier 2 |
 
-The installation is **idempotent** — run it again anytime to update to the latest config.
+</details>
 
-## Creating Your Own Skills
+> **Want to add a pack?** Open a PR adding it to the `OPTIONAL_ADDONS` array in [`bin/devlyn.js`](bin/devlyn.js).
 
-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 installed and configured
+- **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** installed and configured
 
 ## Contributing
 
-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`)
-3. Commit your changes following the included [commit conventions](config/commit-conventions.md)
-4. Push to the branch (`git push origin feat/my-feature`)
-5. Open a Pull Request
+- **Add a command** — `.md` file in `config/commands/`
+- **Add a skill** — directory in `config/skills/` with `SKILL.md`
+- **Add optional skill** — add to `optional-skills/` and `OPTIONAL_ADDONS`
+- **Suggest a pack** — PR to the pack list
 
 ## Star History
 

package/bin/devlyn.js

@@ -594,15 +594,9 @@ async function init(skipPrompts = false) {
 
   // Skip prompts if -y flag or non-interactive
   if (skipPrompts || !process.stdin.isTTY) {
-    log('\n💡 Add optional addons later:', 'dim');
-    OPTIONAL_ADDONS.forEach((addon) => {
-      if (addon.type === 'local') {
-        log(`   npx devlyn-cli  (select "${addon.name}" during install)`, 'dim');
-      } else {
-        log(`   npx skills add ${addon.name}`, 'dim');
-      }
-    });
-    log('');
+    log('\n💡 Add optional addons later: run `npx devlyn-cli` without -y', 'dim');
+    log(`\n${COLORS.dim}   Enjoying devlyn? Star it on GitHub — it helps others find it:${COLORS.reset}`);
+    log(`   ${COLORS.purple}→ https://github.com/fysoul17/devlyn-cli${COLORS.reset}\n`);
     return;
   }
 
@@ -621,7 +615,9 @@ async function init(skipPrompts = false) {
   }
 
   log('\n✨ All done!', 'green');
-  log('   Run `npx devlyn-cli` again to update\n', 'dim');
+  log('   Run `npx devlyn-cli` again to update', 'dim');
+  log(`\n${COLORS.dim}   Enjoying devlyn? Star it on GitHub — it helps others find it:${COLORS.reset}`);
+  log(`   ${COLORS.purple}→ https://github.com/fysoul17/devlyn-cli${COLORS.reset}\n`);
 }
 
 function showHelp() {

package/config/skills/devlyn:ideate/SKILL.md

@@ -0,0 +1,344 @@
+---
+name: devlyn:ideate
+description: Transform unstructured ideas into implementation-ready planning documents through structured brainstorming, research, and multi-perspective synthesis. Produces a three-layer document architecture (Vision, Roadmap index, auto-resolve-ready specs) that eliminates context pollution in the implementation pipeline. Use when the user wants to brainstorm, plan a new project or feature set, explore possibilities, create a vision and roadmap, or structure scattered ideas into an actionable plan. Triggers on "let's brainstorm", "let's plan", "ideate", "I have an idea for", "help me think through", "let's explore", new project planning, feature discovery, roadmap creation, or when the user is throwing ideas that need structuring. Also triggers when the user shares links or resources for a new initiative and needs them synthesized into a plan, or wants to update an existing roadmap with new ideas.
+---
+
+# Ideation to Implementation Bridge
+
+Turn unstructured thinking into auto-resolve-ready documents. The output is a precision-engineered context pipeline — each document layer serves a specific role so that implementation agents receive exactly the context they need, nothing more.
+
+<why_this_matters>
+When ideas flow directly from conversation to `/devlyn:auto-resolve`, context degrades at each handoff:
+- Abstract vision statements cause over-engineering (the agent optimizes for principles instead of deliverables)
+- Full roadmaps create attention noise (49 irrelevant items dilute focus on item #3)
+- Done criteria generated from vague prompts miss the user's actual intent
+
+This skill solves the context engineering problem by producing **self-contained specs** — each carries just enough context for auto-resolve to work autonomously.
+</why_this_matters>
+
+## Output Architecture
+
+The skill produces a three-layer progressive disclosure structure:
+
+```
+docs/
+├── VISION.md              # Layer 1: Strategic WHY (~50-100 lines)
+│                          # Orientation only. auto-resolve never reads this.
+│
+├── ROADMAP.md             # Layer 2: Tactical index (what, in what order)
+│                          # Thin table linking to detail specs. auto-resolve never reads this.
+│
+└── roadmap/               # Layer 3: Auto-resolve-ready specs
+    ├── phase-1/
+    │   ├── _overview.md   # Phase-level context and goals
+    │   ├── 1.1-xxx.md     # Self-contained spec → direct auto-resolve input
+    │   └── 1.2-yyy.md
+    ├── phase-2/
+    │   └── ...
+    ├── decisions/         # Architecture decision records (why we chose X over Y)
+    │   └── 001-xxx.md
+    └── backlog/           # Ideas acknowledged but not yet phased
+        └── ...
+```
+
+**Core principle**: auto-resolve reads ONE spec file. That file is self-contained. Vision and Roadmap exist for humans and for this ideation skill — not for the implementation pipeline.
+
+Read `references/templates/` for the exact format of each document type when generating output.
+
+## Conversation Protocol
+
+Ideation is a dialogue, not a monologue. The user will come in with scattered ideas, incomplete thoughts, and implicit assumptions. Your job is to draw out accurate, complete information through back-and-forth conversation — not to fill gaps with guesses.
+
+<conversation_rhythm>
+**Ask, don't assume.** When information is missing or ambiguous, ask targeted questions. Generating a spec with wrong assumptions is worse than asking one more question. The user wants accuracy (documents they can trust and hand to auto-resolve), not speed.
+
+**2-3 questions at a time, max.** Don't dump a 10-item questionnaire. Ask the most important unknowns, get answers, then ask the next batch based on what you learned. Each exchange should build on the last.
+
+**Summarize after each exchange.** After the user shares information, reflect it back concisely: "So what I'm hearing is [X]. Is that right, or am I missing something?" This catches misunderstandings early — much cheaper than rewriting specs later.
+
+**Confirm before phase transitions.** Before moving from FRAME → EXPLORE, or EXPLORE → CONVERGE, summarize the current state and ask if the user is ready to move on. Never silently transition.
+
+**Capture energy, then clarify.** When the user is excited and throwing out rapid-fire ideas, don't interrupt the flow with structural questions. Let them finish, capture everything, then come back with targeted clarifications: "Love these ideas. A few things I want to make sure I get right: [questions]."
+
+**Track what's confirmed vs. assumed.** Mentally separate facts the user stated from inferences you made. When generating documents, only write confirmed facts. Flag assumptions explicitly: "I'm assuming [X] based on [Y] — correct?"
+</conversation_rhythm>
+
+## Detecting the Mode
+
+Before starting, identify what the user needs:
+
+| Signal | Mode | Approach |
+|--------|------|----------|
+| No existing docs, new project or idea | **Greenfield** | Full flow: Frame → Explore → Converge → Document |
+| Existing docs, user adds new ideas | **Expand** | Lighter Frame, focused Explore on new area, merge into existing phases |
+| One specific feature needs deep thought | **Deep-dive** | Intensive Explore on one topic, output 1-3 specs |
+| User shares links/resources to process | **Research-first** | Lead with Explore (research synthesis), then standard flow |
+| Existing roadmap, user wants to reprioritize | **Replan** | Read existing docs, focus on Converge, update documents |
+
+Announce the detected mode and confirm before proceeding.
+
+### Expand Mode Detail
+
+Expand is the most common mode after initial setup — the user already has Vision + Roadmap and wants to add new capabilities. This mode requires careful integration with existing documents.
+
+**On entry:**
+1. Read `docs/VISION.md`, `docs/ROADMAP.md`, and existing phase `_overview.md` files to understand the established context
+2. Scan existing item specs to understand what's built and what's planned
+3. Summarize your understanding: "Here's what exists: [phases, item count, current status]. You want to add [new area]. Does this expand an existing phase or warrant a new one?"
+
+**During ideation:**
+- FRAME is lighter — the vision already exists, focus on framing the NEW area only
+- EXPLORE focuses specifically on the new capability and how it integrates with existing features
+- CONVERGE must consider dependencies on existing items, not just new ones
+
+**During document generation:**
+- Don't overwrite existing VISION.md unless the user explicitly wants to update it
+- Continue numbering from existing IDs (if Phase 2 exists with 2.1-2.4, new items start at 2.5 or create Phase 3)
+- Add new rows to ROADMAP.md, don't regenerate the whole table
+- New item specs can reference existing items in their Dependencies section
+- If new items change the meaning of existing items, flag this: "Adding [X] may affect the scope of existing item [Y]. Should we update [Y]'s spec?"
+
+In Replan mode, also read existing docs first, then focus on the Converge phase to reprioritize.
+
+### Context Archiving
+
+As projects progress, completed work accumulates and dilutes the active roadmap. Archive stale context at these trigger points:
+
+**When an entire phase is complete:**
+1. Move the phase's table from the active section to a `## Completed` section at the bottom of ROADMAP.md
+2. Keep it collapsed — just phase name, completion date, and item count
+3. Item spec files stay in place (they're self-contained and may be referenced by dependencies)
+
+```markdown
+## Completed
+<details>
+<summary>Phase 1: Foundation (completed 2026-04-15, 4 items)</summary>
+
+| # | Feature | Completed |
+|---|---------|-----------|
+| 1.1 | Auth & Onboarding | 2026-02-10 |
+| 1.2 | Order Management | 2026-03-05 |
+| 1.3 | Inventory Tracking | 2026-03-28 |
+| 1.4 | Customer Directory | 2026-04-15 |
+</details>
+```
+
+**When entering Expand or Replan mode:**
+1. Scan ROADMAP.md for items marked Done — if all items in a phase are Done, archive that phase
+2. Check Backlog for items whose "Revisit" date has passed — surface them as candidates for the new phase
+3. Review decisions — flag any marked `accepted` that may need revisiting given new context
+
+**When a decision becomes outdated:**
+- Don't delete it — mark status as `superseded` and add a note pointing to the replacement decision
+- This preserves the reasoning history for future reference
+
+The goal: ROADMAP.md's active section should only show work that's planned, in-progress, or blocked. Everything else moves to Completed or gets re-evaluated.
+
+## Phase 1: FRAME
+
+<phase_goal>Establish problem space boundaries before exploring solutions.</phase_goal>
+
+The biggest risk in ideation is premature convergence — jumping to solutions before understanding the problem. This phase prevents that.
+
+Establish through conversation:
+1. **Problem statement**: What problem or opportunity? For whom? Why now?
+2. **Constraints**: What can't change? (tech stack, timeline, existing commitments)
+3. **Success criteria**: How will we know this worked? (outcomes, not outputs)
+4. **Anti-goals**: What are we explicitly NOT trying to do?
+
+Adapt to what the user has already shared — if they came in with a clear vision, this might be a quick confirmation. If the idea is fuzzy, spend more time here. Ask conversationally, not as a rigid questionnaire.
+
+Don't write documents yet. The output of this phase is a shared mental model between you and the user.
+
+## Phase 2: EXPLORE
+
+<phase_goal>Systematically expand the possibility space before narrowing it.</phase_goal>
+
+This is the creative core — the phase that should take the most conversational turns. The user chose to ideate with AI because they want perspectives, research, and creative expansion they wouldn't get alone.
+
+<research_protocol>
+When relevant, actively research before and during brainstorming:
+- **Existing solutions**: What's already out there? (web search, documentation)
+- **Technical feasibility**: Can this be built within the constraints? Where are the hard parts?
+- **Patterns and prior art**: How have similar problems been solved?
+- **Market/user context**: Who else needs this? What do they currently use?
+
+Not every ideation needs all of these — a personal side project doesn't need market research. Judge what's relevant and use subagents for parallel research when multiple topics need investigation.
+</research_protocol>
+
+<multi_perspective>
+For each major idea, consider it from at least three angles:
+- **User**: Is this actually useful? Does it solve a real pain?
+- **Technical**: Is this buildable? Where are the complexity hotspots?
+- **Strategic**: Does this align with the vision? Does it create leverage for future work?
+
+Add perspectives as relevant:
+- **Risk**: What could go wrong? What are the dependencies?
+- **Business**: Does this create value? Is the effort justified?
+- **Accessibility**: Is this inclusive? Who gets left out?
+</multi_perspective>
+
+<creative_expansion>
+When the conversation needs energy or the user feels stuck:
+- **"What if..."** — Remove a constraint and see what emerges
+- **Analogy transfer** — "How does [adjacent domain] solve this?"
+- **Inversion** — "What's the worst version? Now invert it."
+- **10x thinking** — "If this needed 10x users, what changes?"
+- **Minimum viable magic** — "What's the smallest thing that would feel magical?"
+
+Use these naturally in conversation, not as a mechanical checklist.
+</creative_expansion>
+
+As ideas accumulate, periodically synthesize:
+```
+Here's where we are:
+- Core ideas: [list]
+- Open questions: [list]
+- Tensions to resolve: [list]
+- Research still needed: [list]
+```
+
+This prevents circular conversations and gives the user a clear sense of progress.
+
+## Phase 3: CONVERGE
+
+<phase_goal>Transform exploration into decisions.</phase_goal>
+
+When the user signals readiness or exploration winds down naturally, shift to convergence.
+
+### Theme Clustering
+Group related ideas into coherent themes:
+```
+Theme A: [name]
+- Ideas: 1, 3, 7
+- Value: [why this matters]
+- Risk: [what could go wrong]
+```
+
+### Prioritization
+Use value x feasibility as the primary framework:
+- **High value + High feasibility** → Phase 1 (build first)
+- **High value + Low feasibility** → Phase 2+ (build after foundation exists)
+- **Low value + High feasibility** → Backlog (if time permits)
+- **Low value + Low feasibility** → Cut
+
+Present as a recommendation — the user makes the final call on ordering.
+
+### Sequencing
+Within each phase:
+- **Dependencies**: What must exist before what?
+- **Risk ordering**: Build uncertain things first (fail fast)
+- **Value delivery**: Each phase should deliver usable value, not just infrastructure
+
+### Architecture Decisions
+Surface decisions that affect multiple items — technology choices, data model, integration approaches, UX patterns. For each: **What** was decided, **Why** (tradeoffs), and **What alternatives** were considered. These become decision records.
+
+### Confirmation
+Before generating documents, present a final summary:
+```
+Vision: [one sentence]
+Phases: [N] phases, [M] total items
+Phase 1 ([theme]): [items with brief descriptions]
+Phase 2 ([theme]): [items]
+Key decisions: [list]
+Deferred: [items with reasons]
+```
+
+Get explicit confirmation before proceeding to document generation.
+
+## Phase 4: DOCUMENT
+
+<phase_goal>Generate the three-layer document set.</phase_goal>
+
+Read the templates before generating:
+- `references/templates/vision.md` — VISION.md format
+- `references/templates/roadmap.md` — ROADMAP.md index format
+- `references/templates/item-spec.md` — Auto-resolve-ready spec format
+- `references/templates/decision.md` — Architecture decision record format
+
+### Generation Order
+1. `docs/VISION.md` — from Phase 1 framing + Phase 3 decisions
+2. `docs/roadmap/decisions/` — one file per architecture decision
+3. `docs/roadmap/phase-N/_overview.md` — phase-level context
+4. `docs/roadmap/phase-N/{id}-{name}.md` — one per roadmap item
+5. `docs/ROADMAP.md` — index linking to everything above
+
+### Item Spec Quality
+
+Each Layer 3 spec is the direct input to auto-resolve. Its quality determines implementation quality.
+
+<spec_quality_criteria>
+**Requirements section** — becomes auto-resolve's done-criteria:
+- Testable: a test can assert it OR a human can verify in under 30 seconds
+- Specific: not "handles errors well" but "returns 400 with `{error: 'missing_field', field: 'email'}`"
+- Scoped: tied to this item only, not aspirational
+
+**Context section** — 2-3 sentences maximum. Just enough for auto-resolve to understand WHY without loading the full vision.
+
+**Out of Scope** — explicitly states what this item does NOT do. This is what prevents auto-resolve from over-building, which is one of its most common failure modes.
+
+**Constraints** — technical constraints with reasoning. Auto-resolve respects constraints significantly better when it understands the motivation behind them.
+</spec_quality_criteria>
+
+If an item is too vague to write specific requirements, it needs more exploration (revisit Phase 2 for that item) or should be split into smaller items.
+
+### Handling Existing Documents
+In **Expand** and **Replan** modes:
+- Read existing documents first
+- Merge new items into the existing phase structure
+- Preserve existing items (don't overwrite or reorder without confirmation)
+- Update ROADMAP.md index to include new entries
+
+### Output Summary
+After generating all documents:
+```
+Documents created:
+- docs/VISION.md
+- docs/ROADMAP.md
+- docs/roadmap/phase-1/_overview.md
+- docs/roadmap/phase-1/1.1-xxx.md
+- docs/roadmap/phase-1/1.2-yyy.md
+- docs/roadmap/decisions/001-xxx.md
+[total: N files]
+```
+
+## Phase 5: BRIDGE
+
+<phase_goal>Connect documents to the implementation pipeline.</phase_goal>
+
+After document generation, output the implementation guide:
+
+```
+## Implementation
+
+To implement each item:
+/devlyn:auto-resolve "Implement per spec at docs/roadmap/phase-1/1.1-xxx.md — read the spec file for requirements, constraints, and scope boundaries"
+
+Recommended order (respecting dependencies):
+1. 1.1 [name] — no dependencies
+2. 1.2 [name] — depends on 1.1
+3. 1.3 [name] — depends on 1.1
+...
+
+After completing each item:
+1. Update status in the item spec frontmatter (status: done)
+2. Update ROADMAP.md status column
+```
+
+The auto-resolve prompt explicitly tells the build agent to read the spec file — this ensures done-criteria are adopted from the spec rather than generated from scratch, preserving the ideation context through to implementation.
+
+## Quality Checklist
+
+Before finalizing, verify:
+- [ ] Every roadmap item has a linked spec file
+- [ ] Every spec has testable requirements (not vague statements)
+- [ ] Every spec has an Out of Scope section
+- [ ] Every spec's Context section is 3 sentences or fewer
+- [ ] ROADMAP.md is an index only — no inline specifications
+- [ ] No spec requires reading VISION.md to be understood (self-contained)
+- [ ] Dependencies between items are documented in both specs
+- [ ] Architecture decisions include reasoning and alternatives considered
+
+## Language
+
+Generate all documents in the language the user communicates in. If the user mixes languages, match their primary language for prose and keep technical terms in English.

package/config/skills/devlyn:ideate/references/templates/decision.md

@@ -0,0 +1,48 @@
+# Decision Record Template
+
+Generate decision records at `docs/roadmap/decisions/{NNN}-{title}.md`. These capture WHY a decision was made, preventing future agents and collaborators from re-debating settled questions.
+
+---
+
+```markdown
+---
+id: [NNN]
+title: "[Decision Title]"
+date: [YYYY-MM-DD]
+status: accepted
+---
+
+# [NNN] [Decision Title]
+
+## Context
+<!-- What situation or question prompted this decision? -->
+
+## Decision
+<!-- What was decided. Be specific and concrete. -->
+
+## Alternatives Considered
+
+### [Alternative 1]
+- Pros: [advantages]
+- Cons: [disadvantages]
+- Why rejected: [the deciding factor]
+
+### [Alternative 2]
+- Pros: [advantages]
+- Cons: [disadvantages]
+- Why rejected: [the deciding factor]
+
+## Consequences
+<!-- What changes as a result. Include both positive tradeoffs and costs accepted. -->
+- [Positive consequence]
+- [Cost or constraint accepted]
+```
+
+## Guidelines
+
+- Status values: `proposed` | `accepted` | `superseded`
+- Number decisions sequentially: 001, 002, 003...
+- Focus on the "why rejected" for alternatives — this is what prevents re-debating
+- Keep decisions atomic: one decision per record
+- If a decision is later reversed, mark the original as `superseded` and create a new record referencing it
+- Only create decision records for choices that affect multiple roadmap items or have non-obvious reasoning. Don't document every small implementation choice.

package/config/skills/devlyn:ideate/references/templates/item-spec.md

@@ -0,0 +1,86 @@
+# Item Spec Template (Auto-Resolve-Ready)
+
+Generate one file per roadmap item at `docs/roadmap/phase-N/{id}-{name}.md`. This is the most critical template — each spec becomes the direct input to `/devlyn:auto-resolve`.
+
+---
+
+```markdown
+---
+id: "[phase.item]"
+title: "[Feature Name]"
+phase: [N]
+status: planned
+priority: [high | medium | low]
+complexity: [low | medium | high]
+depends-on: []
+---
+
+# [id] [Feature Name]
+
+## Context
+<!-- 2-3 sentences MAX. Just enough for auto-resolve to understand WHY this exists. -->
+<!-- Extract only the relevant context from the vision — don't make the implementation agent read the full vision document. -->
+[Project] does [what]. This feature [enables/improves/fixes] [specific user capability].
+
+## Objective
+<!-- One sentence: what the user can do after this is implemented. -->
+
+## Requirements
+<!-- These become auto-resolve's done-criteria. Quality of these requirements directly determines implementation quality. -->
+- [ ] [Specific, testable requirement]
+- [ ] [Specific, testable requirement]
+- [ ] [Specific, testable requirement]
+- [ ] ...
+
+## Constraints
+<!-- Technical constraints WITH reasoning. Implementation agents respect constraints significantly better when they understand the motivation. -->
+- [Constraint] — Why: [reason]
+- ...
+
+## Out of Scope
+<!-- What this item explicitly does NOT include. This prevents auto-resolve from over-building. -->
+- [Feature/behavior] ([where/when it will be addressed, e.g., "Phase 2, item 2.3"])
+- ...
+
+## Architecture Notes
+<!-- Technical context that helps implementation. Reference decision records when applicable. -->
+<!-- Remove this section if the implementation is straightforward. -->
+
+## Dependencies
+- **Internal**: [Other roadmap items that must exist first, e.g., "1.1 User Auth"]
+- **External**: [APIs, services, credentials, third-party setup needed]
+
+## Verification
+<!-- How to confirm this works. Overlaps with Requirements but focuses on observable user-facing behavior. -->
+- [ ] [Observable verification step]
+- [ ] ...
+```
+
+## Quality Criteria
+
+Before writing a spec, verify each requirement against these criteria:
+
+**Testable**: Can a test assert this, or can a human verify it in under 30 seconds?
+- Bad: "The dashboard loads quickly"
+- Good: "Dashboard initial render completes within 2 seconds on 3G throttled connection"
+
+**Specific**: Is there exactly one interpretation of what "done" means?
+- Bad: "Handles errors gracefully"
+- Good: "Failed API calls display an error banner with the message and a retry button"
+
+**Scoped**: Does this belong to THIS item only?
+- Bad: "The app supports multiple languages" (cross-cutting concern, not a single item)
+- Good: "The settings page displays a language selector with EN and KO options"
+
+**Self-contained**: Can auto-resolve implement this without reading VISION.md or ROADMAP.md?
+- If the Context section references principles without explaining them, it's not self-contained
+- The spec should carry its own context, not point to other documents
+
+## When a Spec Isn't Ready
+
+If you can't write specific requirements for an item, it needs one of:
+1. **More exploration** — go back to Phase 2 for this item
+2. **Splitting** — the item is too large; break it into smaller, specifiable pieces
+3. **A spike** — mark it as a research task whose output is a proper spec
+
+Never generate a spec with vague requirements just to fill the roadmap. A backlog item with "needs exploration" is more honest and more useful than a spec with untestable requirements.

package/config/skills/devlyn:ideate/references/templates/roadmap.md

@@ -0,0 +1,50 @@
+# ROADMAP.md Template
+
+Generate `docs/ROADMAP.md` using this structure. This is an **index** — brief descriptions and links to detail specs. No inline specifications.
+
+---
+
+```markdown
+# [Project Name] Roadmap
+
+> **North Star**: [One sentence from VISION.md]
+
+## Phase 1: [Theme Name] (Target: [date or timeframe])
+<!-- 1-2 sentences: what this phase delivers and why it comes first -->
+
+| # | Feature | Status | Priority | Complexity | Spec |
+|---|---------|--------|----------|-----------|------|
+| 1.1 | [Feature Name] | Planned | High | Medium | [spec](roadmap/phase-1/1.1-feature-name.md) |
+| 1.2 | [Feature Name] | Planned | High | High | [spec](roadmap/phase-1/1.2-feature-name.md) |
+| 1.3 | [Feature Name] | Planned | Medium | Low | [spec](roadmap/phase-1/1.3-feature-name.md) |
+
+## Phase 2: [Theme Name] (Target: [date or timeframe])
+<!-- 1-2 sentences -->
+
+| # | Feature | Status | Priority | Complexity | Spec |
+|---|---------|--------|----------|-----------|------|
+| 2.1 | [Feature Name] | Planned | High | Medium | [spec](roadmap/phase-2/2.1-feature-name.md) |
+
+## Backlog
+<!-- Ideas acknowledged but not yet phased -->
+| Feature | Reason Deferred | Revisit |
+|---------|----------------|---------|
+| [Name] | [Why not now] | [When to reconsider] |
+
+## Decisions
+| # | Decision | Date | Record |
+|---|----------|------|--------|
+| 1 | [Decision Title] | [YYYY-MM-DD] | [record](roadmap/decisions/001-decision-title.md) |
+```
+
+## Guidelines
+
+- Status values: `Planned` | `In Progress` | `Done` | `Blocked`
+- Priority: `High` | `Medium` | `Low`
+- Complexity: `Low` | `Medium` | `High`
+- Feature names should be user-facing descriptions, not technical jargon
+- Each phase should deliver usable value — no "infrastructure only" phases
+- The spec column links to the detail spec in `roadmap/phase-N/`
+- Numbering: `{phase}.{item}` (e.g., 1.1, 1.2, 2.1)
+- Slug format for filenames: `{id}-{kebab-case-name}.md` (e.g., `1.1-user-auth.md`)
+- Keep this file under 150 lines — it's an index, not a specification

package/config/skills/devlyn:ideate/references/templates/vision.md

@@ -0,0 +1,44 @@
+# VISION.md Template
+
+Generate `docs/VISION.md` using this structure. Keep it under 100 lines — this is a strategic orientation document, not a detailed specification.
+
+---
+
+```markdown
+# [Project Name] Vision
+
+## North Star
+<!-- One sentence. Every decision should move toward this. -->
+
+## Principles
+<!-- 3-5 guiding principles. Each includes what it means AND the tradeoff it implies. -->
+1. **[Principle Name]** — [What this means in practice]. Tradeoff: [what we accept giving up].
+2. ...
+
+## Target Users
+### Primary
+<!-- Be specific: role, context, pain, what they need -->
+**[Who]** — [Their situation]. Pain: [what frustrates them]. Need: [what they want].
+
+### Not For
+<!-- Explicitly state who this isn't for, so the team doesn't try to serve everyone -->
+- [Audience] — Why: [reason this isn't our focus]
+
+## Anti-Goals
+<!-- Things we deliberately choose NOT to do, even if they seem like good ideas -->
+- **[Anti-goal]** — Why: [the reasoning behind this constraint]
+- ...
+
+## Success Metrics
+<!-- How we know this is working. Outcomes, not outputs. -->
+- [Metric]: [target] (e.g., "Time to first value: under 5 minutes")
+- ...
+```
+
+## Guidelines
+
+- North Star should be ambitious but specific — "make X better" is too vague
+- Principles without tradeoffs are platitudes — if a principle has no cost, it's not a real principle
+- Anti-goals prevent scope creep downstream — be generous with these
+- Success metrics should be measurable, even if the measurement is qualitative
+- Write in the user's primary language, technical terms in English

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "devlyn-cli",
-  "version": "1.5.4",
-  "description": "Claude Code configuration toolkit for teams",
+  "version": "1.7.0",
+  "description": "AI development toolkit for Claude Code — ideate, auto-resolve, and ship with context engineering and agent orchestration",
+  "homepage": "https://github.com/fysoul17/devlyn-cli#readme",
   "bin": {
     "devlyn": "bin/devlyn.js"
   },
@@ -16,8 +17,17 @@
     "claude",
     "claude-code",
     "ai",
-    "config",
-    "devlyn"
+    "ai-agent",
+    "ai-tools",
+    "context-engineering",
+    "harness-engineering",
+    "agent-orchestration",
+    "prompt-engineering",
+    "code-review",
+    "devlyn",
+    "developer-tools",
+    "automation",
+    "cli"
   ],
   "author": "",
   "license": "MIT",