feat: unified /plan command with gap analysis, design review, and plan-aware /implement

.claude-plugin/marketplace.json

@@ -7,21 +7,21 @@
   },
   "plugins": [
     {
-      "name": "devflow-specify",
-      "source": "./plugins/devflow-specify",
-      "description": "Interactive feature specification - creates well-defined GitHub issues",
+      "name": "devflow-plan",
+      "source": "./plugins/devflow-plan",
+      "description": "Unified design planning with gap analysis and design review",
       "version": "1.8.3",
       "keywords": [
-        "specification",
-        "requirements",
         "planning",
-        "issues"
+        "design",
+        "gap-analysis",
+        "architecture"
       ]
     },
     {
       "name": "devflow-implement",
       "source": "./plugins/devflow-implement",
-      "description": "Complete task implementation workflow with exploration, planning, and coding",
+      "description": "Complete task implementation workflow - accepts plan documents, issues, or task descriptions",
       "version": "1.8.3",
       "keywords": [
         "implementation",

.gitignore

@@ -24,6 +24,7 @@ plugins/*/agents/evaluator.md
 plugins/*/agents/tester.md
 plugins/*/agents/scrutinizer.md
 plugins/*/agents/validator.md
+plugins/*/agents/designer.md
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*

CLAUDE.md

@@ -16,8 +16,8 @@ Plugin marketplace with 17 plugins (8 core + 9 optional language/ecosystem), eac
 
 | Plugin | Purpose | Teams Variant |
 |--------|---------|---------------|
-| `devflow-specify` | Feature specification workflow | Optional |
 | `devflow-implement` | Complete task implementation lifecycle | Optional |
+| `devflow-plan` | Unified design planning with gap analysis | Optional |
 | `devflow-code-review` | Comprehensive code review | Optional |
 | `devflow-resolve` | Review issue resolution | Optional |
 | `devflow-debug` | Competing hypothesis debugging | Optional |
@@ -52,8 +52,8 @@ Commands with Teams Variant ship as `{name}.md` (parallel subagents) and `{name}
 
 ```
 devflow/
-├── shared/skills/          # 39 skills (single source of truth)
-├── shared/agents/          # 11 shared agents (single source of truth)
+├── shared/skills/          # 41 skills (single source of truth)
+├── shared/agents/          # 12 shared agents (single source of truth)
 ├── plugins/devflow-*/      # 17 plugins (8 core + 9 optional language/ecosystem)
 ├── docs/reference/         # Detailed reference documentation
 ├── scripts/                # Helper scripts (statusline, docs-helpers)
@@ -98,7 +98,7 @@ All generated docs live under `.docs/` in the project root:
 │       ├── {focus}.md                 # Reviewer reports (security.md, etc.)
 │       ├── review-summary.md          # Synthesizer output
 │       └── resolution-summary.md      # Written by /resolve
-└── design/                            # Implementation plans
+└── design/                            # Design artifacts from /plan
 ```
 
 Working memory files live in a dedicated `.memory/` directory:
@@ -132,26 +132,26 @@ Working memory files live in a dedicated `.memory/` directory:
 
 **Universal Skill Installation**: All skills from all plugins are always installed, regardless of plugin selection. Skills are tiny markdown files installed as `~/.claude/skills/devflow:{name}/` (namespaced to avoid collisions with other plugin ecosystems). Source directories in `shared/skills/` stay unprefixed — the `devflow:` prefix is applied at install-time only. Shadow overrides live at `~/.devflow/skills/{name}/` (unprefixed); when shadowed, the installer copies the user's version to the prefixed install target. Only commands and agents remain plugin-specific.
 
-**Model Strategy**: Explicit model assignments in agent frontmatter override the user's session model. Opus for analysis agents (reviewer, scrutinizer, evaluator), Sonnet for execution agents (coder, simplifier, resolver, skimmer, tester), Haiku for I/O agents (git, synthesizer, validator).
+**Model Strategy**: Explicit model assignments in agent frontmatter override the user's session model. Opus for analysis agents (reviewer, scrutinizer, evaluator, designer), Sonnet for execution agents (coder, simplifier, resolver, skimmer, tester), Haiku for I/O agents (git, synthesizer, validator).
 
 ## Agent & Command Roster
 
 **Orchestration commands** (spawn agents, never do agent work in main session):
-- `/specify` — Skimmer + Explore + Synthesizer + Plan + Synthesizer → GitHub issue
-- `/implement` — Git + Skimmer + Explore + Synthesizer + Plan + Synthesizer + Coder + Simplifier + Scrutinizer + Evaluator + Tester → PR
+- `/plan` — Skimmer + Explore + Designer + Synthesizer + Plan + Designer → design artifact
+- `/implement` — Git + Coder + Validator + Simplifier + Scrutinizer + Evaluator + Tester → PR (accepts plan documents, issues, or task descriptions)
 - `/code-review` — 7-11 Reviewer agents + Git + Synthesizer
 - `/resolve` — N Resolver agents + Git
 - `/debug` — Agent Teams competing hypotheses
 - `/self-review` — Simplifier then Scrutinizer (sequential)
 - `/audit-claude` — CLAUDE.md audit (optional plugin)
 
-**Shared agents** (11): git, synthesizer, skimmer, simplifier, coder, reviewer, resolver, evaluator, tester, scrutinizer, validator
+**Shared agents** (12): git, synthesizer, skimmer, simplifier, coder, reviewer, resolver, evaluator, tester, scrutinizer, validator, designer
 
 **Plugin-specific agents** (1): claude-md-auditor
 
 **Orchestration skills** (7): implement:orch, explore:orch, debug:orch, plan:orch, review:orch, resolve:orch, pipeline:orch. These enable the same agent pipelines as slash commands but triggered via ambient intent classification.
 
-**Agent Teams**: 5 commands use Agent Teams (`/code-review`, `/implement`, `/debug`, `/specify`, `/resolve`). One-team-per-session constraint — must TeamDelete before creating next team.
+**Agent Teams**: 5 commands use Agent Teams (`/code-review`, `/implement`, `/plan`, `/debug`, `/resolve`). One-team-per-session constraint — must TeamDelete before creating next team.
 
 ## Key Conventions
 

CONTRIBUTING.md

@@ -24,8 +24,8 @@ After setup, Devflow commands (`/code-review`, `/implement`, etc.) are available
 
 ```
 devflow/
-├── shared/skills/       # 39 skills (single source of truth)
-├── shared/agents/       # 11 shared agents (single source of truth)
+├── shared/skills/       # 41 skills (single source of truth)
+├── shared/agents/       # 12 shared agents (single source of truth)
 ├── plugins/devflow-*/   # 17 plugins (8 core + 9 optional)
 ├── scripts/hooks/       # Working Memory hooks
 ├── src/cli/             # TypeScript CLI (init, list, uninstall)

README.md

@@ -48,11 +48,11 @@ Devflow: IMPLEMENT/ORCHESTRATED
 
 **18 parallel code reviewers.** Security, architecture, performance, complexity, consistency, regression, testing, and more. Each produces findings with severity, confidence scoring, and concrete fixes. Conditional reviewers activate when relevant (TypeScript for `.ts` files, database for schema changes). Every finding gets validated and resolved automatically.
 
-**39 skills grounded in expert material.** Every skill is backed by peer-reviewed papers, canonical books, and industry standards — security (OWASP, Shostack), architecture (Parnas, Evans, Fowler), performance (Brendan Gregg), testing (Beck, Meszaros), design (Wlaschin, Hickey). 200+ sources total.
+**41 skills grounded in expert material.** Every skill is backed by peer-reviewed papers, canonical books, and industry standards — security (OWASP, Shostack), architecture (Parnas, Evans, Fowler), performance (Brendan Gregg), testing (Beck, Meszaros), design (Wlaschin, Hickey). 200+ sources total.
 
 **Skill shadowing.** Override any built-in skill with your own version. Drop a file into `~/.devflow/skills/{name}/` and the installer uses yours instead of the default — same activation, your rules.
 
-**Full lifecycle.** `/implement` takes a task from exploration through planning, coding, validation, and refinement. `/specify` defines features with clarification gates. `/debug` investigates bugs with competing hypotheses in parallel. `/self-review` runs Simplifier + Scrutinizer quality passes.
+**Full lifecycle.** `/plan` takes a feature idea through codebase exploration, gap analysis, design review, and outputs a plan document ready for `/implement`. `/implement` accepts that plan document (or an issue or task description directly) and drives it through coding, validation, and refinement to a PR. `/debug` investigates bugs with competing hypotheses in parallel. `/self-review` runs Simplifier + Scrutinizer quality passes.
 
 **Everything is composable.** 17 plugins (8 core + 9 language/ecosystem). Install only what you need. Six commands cover the entire development lifecycle.
 
@@ -61,7 +61,7 @@ Devflow: IMPLEMENT/ORCHESTRATED
 ```
 devflow · feat/auth-middleware* · 3↑ · v1.8.3 +5 · 12 files · +234 -56
 Current Session ████░░░░ 42% · Session 5h ██░░░░░░ 18% · 7d █░░░░░░░ 8%
-Opus 4.6 [1m] · 23m · $1.24 · 2 CLAUDE.md · 4 MCPs · 8 hooks · 39 skills
+Opus 4.6 [1m] · 23m · $1.24 · 2 CLAUDE.md · 4 MCPs · 8 hooks · 41 skills
 ```
 
 **Security.** Deny lists block dangerous tool patterns out of the box — configurable during init.
@@ -78,8 +78,8 @@ That's it. The interactive wizard handles plugin selection, feature configuratio
 
 | Command | What it does |
 |---------|-------------|
-| `/specify` | Define a feature with clarification gates → GitHub issue |
-| `/implement` | Full lifecycle: explore → plan → code → validate → refine → PR |
+| `/plan` | Full design pipeline: explore → gap analysis → design → PR-ready plan document |
+| `/implement` | Execute plan: accepts plan documents from `/plan`, issues, or task descriptions → PR |
 | `/code-review` | Multi-perspective parallel code review |
 | `/resolve` | Validate and fix all review issues |
 | `/debug` | Competing hypothesis investigation |

docs/cli-reference.md

@@ -43,7 +43,7 @@ npx devflow-kit init --plugin=implement,code-review  # Install multiple
 
 | Plugin | Type | Description |
 |--------|------|-------------|
-| `devflow-specify` | Core | Feature specification workflow |
+| `devflow-plan` | Core | Unified design planning with gap analysis |
 | `devflow-implement` | Core | Complete task implementation lifecycle |
 | `devflow-code-review` | Core | Comprehensive code review |
 | `devflow-resolve` | Core | Review issue resolution |

docs/commands.md

@@ -2,38 +2,43 @@
 
 Devflow provides six commands that orchestrate specialized agents. Commands spawn agents — they never do the work themselves.
 
-## /specify
+## /plan
 
-Interactive feature specification with three mandatory gates:
+Unified design planning from requirements discovery through implementation design:
 
-1. **Understanding Gate** — Confirm the feature idea is understood
-2. **Scope Gate** — Validate priorities and boundaries
-3. **Acceptance Gate** — Confirm success criteria
+1. **Gate 0** — Confirm understanding of the requirement
+2. **Requirements Discovery** — Parallel exploration agents analyze codebase
+3. **Gap Analysis** — Identify missing pieces, risks, and dependencies
+4. **Gate 1** — Validate scope and gaps with user
+5. **Implementation Design** — Parallel planning agents design the approach
+6. **Design Review + Gate 2** — Review the design artifact, user approves the final plan
 
-Creates a well-defined GitHub issue ready for `/implement`.
+Produces a machine-readable design artifact in `.docs/design/` consumed by `/implement`.
 
 ```
-/specify              # Start interactive specification
+/plan add JWT auth           # From description
+/plan #42                    # From GitHub issue
+/plan #12 #15 #18           # Multi-issue
+/plan                        # From conversation context
 ```
 
 ## /implement
 
-Executes a single task through the complete development lifecycle:
+Executes a single task through the complete development lifecycle. Accepts plan documents, GitHub issues, or task descriptions.
 
-1. **Setup** — Auto-create feature branch (detects repo naming conventions)
-2. **Exploration** — Analyze codebase for relevant patterns and dependencies
-3. **Planning** — Design the implementation approach
-4. **Implementation** — Write code on the feature branch
-5. **Validation** — Build, typecheck, lint, and test
-6. **Refinement** — Simplifier (code clarity) + Scrutinizer (9-pillar quality)
-7. **Alignment** — Evaluator verifies implementation matches the original request
-8. **QA Testing** — Tester executes scenario-based acceptance tests
+1. **Setup** — Auto-create feature branch, parse plan document or fetch issue
+2. **Implementation** — Write code on the feature branch
+3. **Validation** — Build, typecheck, lint, and test
+4. **Refinement** — Simplifier (code clarity) + Scrutinizer (9-pillar quality)
+5. **Alignment** — Evaluator verifies implementation matches the original request
+6. **QA Testing** — Tester executes scenario-based acceptance tests
 
 Creates a PR when complete.
 
 ```
-/implement add JWT auth      # From description
+/implement .docs/design/42-jwt-auth.2026-04-07_1430.md  # From plan document
 /implement #42               # From GitHub issue
+/implement add JWT auth      # From description
 /implement                   # From conversation context
 ```
 

docs/reference/agent-design.md

@@ -49,7 +49,7 @@ When an agent only needs a subset of tools, prefer platform-enforced restriction
 | Agent Type | Target Lines | Examples |
 |------------|-------------|----------|
 | Utility | 50-80 | Skimmer, Simplifier, Validator |
-| Worker | 80-120 | Coder, Reviewer, Git |
+| Worker | 80-120 | Coder, Reviewer, Git, Designer |
 | Orchestration | 100-150 | (Commands handle orchestration, not agents) |
 
 ## What Belongs Where
@@ -106,4 +106,4 @@ Before committing a new or modified agent:
 3. Test with explicit invocation
 4. Document in plugin README.md
 
-**Note:** Shared agents live in `shared/agents/` and are distributed at build time. Only create plugin-specific agents when tightly coupled to a single workflow (e.g., `claude-md-auditor.md`).
+**Note:** Shared agents live in `shared/agents/` and are distributed at build time (e.g., `git.md`, `coder.md`, `designer.md`). Only create plugin-specific agents when tightly coupled to a single workflow (e.g., `claude-md-auditor.md`).

docs/reference/file-organization.md

@@ -9,19 +9,19 @@ devflow/
 ├── .claude-plugin/                   # Marketplace registry (repo root)
 │   └── marketplace.json
 ├── shared/
-│   ├── skills/                       # SINGLE SOURCE OF TRUTH (39 skills)
+│   ├── skills/                       # SINGLE SOURCE OF TRUTH (41 skills)
 │   │   ├── git/
 │   │   │   ├── SKILL.md
 │   │   │   └── references/
 │   │   ├── software-design/
 │   │   └── ...
-│   └── agents/                       # SINGLE SOURCE OF TRUTH (11 shared agents)
+│   └── agents/                       # SINGLE SOURCE OF TRUTH (12 shared agents)
 │       ├── git.md
 │       ├── synthesizer.md
 │       ├── coder.md
 │       └── ...
 ├── plugins/                          # Plugin collection (17 plugins)
-│   ├── devflow-specify/
+│   ├── devflow-plan/
 │   │   ├── .claude-plugin/
 │   │   │   └── plugin.json
 │   │   ├── commands/
@@ -135,7 +135,7 @@ Skills and agents are **not duplicated** in git. Instead:
 
 ### Shared vs Plugin-Specific Agents
 
-- **Shared** (11): `git`, `synthesizer`, `skimmer`, `simplifier`, `coder`, `reviewer`, `resolver`, `evaluator`, `tester`, `scrutinizer`, `validator`
+- **Shared** (12): `git`, `synthesizer`, `skimmer`, `simplifier`, `coder`, `reviewer`, `resolver`, `evaluator`, `tester`, `scrutinizer`, `validator`, `designer`
 - **Plugin-specific** (1): `claude-md-auditor` — committed directly in its plugin
 
 ## Settings Override

docs/reference/skills-architecture.md

@@ -18,9 +18,9 @@ Shared patterns used by multiple agents.
 | `docs-framework` | Documentation conventions (.docs/ structure, naming, templates) | Synthesizer |
 | `git` | Git safety, atomic commits, PR descriptions, GitHub API patterns | Coder, Git, Resolver |
 | `patterns` | CRUD, API endpoints, events, config, logging | Coder, Resolver |
-| `agent-teams` | Agent Teams patterns for peer-to-peer collaboration, debate, consensus | /code-review, /implement, /debug |
+| `agent-teams` | Agent Teams patterns for peer-to-peer collaboration, debate, consensus | /code-review, /implement, /debug, /plan |
 | `router` | Intent classification and proportional skill loading for Devflow mode (unrestricted tools — orchestrator) | Ambient UserPromptSubmit hook |
-| `knowledge-persistence` | Record/load architectural decisions and pitfalls to `.memory/knowledge/` | /implement, /code-review, /resolve, /debug, /specify, /self-review |
+| `knowledge-persistence` | Record/load architectural decisions and pitfalls to `.memory/knowledge/` | /implement, /code-review, /resolve, /debug, /plan, /self-review |
 | `qa` | Scenario-based acceptance testing methodology, evidence collection | Tester |
 
 ### Tier 1b: Pattern Skills
@@ -47,6 +47,8 @@ Listed in Claude Code's skill catalog. May auto-invoke based on description matc
 | Skill | Purpose | Agent Refs |
 |-------|---------|------------|
 | `boundary-validation` | Boundary validation enforcement | Coder |
+| `gap-analysis` | Gap analysis for design plans — missing flows, edge cases, failure modes | Designer |
+| `design-review` | Design review patterns — architectural feasibility, tradeoffs, alternatives | Designer |
 | `research` | Research-before-building enforcement for utility code | Coder |
 | `test-driven-development` | RED-GREEN-REFACTOR cycle enforcement | Coder |
 
@@ -263,12 +265,3 @@ For language/framework patterns:
 4. Add to relevant plugin manifests
 5. Run `npm run build` to distribute
 
-## Clarification Gates
-
-The `/specify` command uses **mandatory clarification gates**:
-
-1. **Gate 0 (Before Exploration)**: Confirm understanding of feature idea
-2. **Gate 1 (After Exploration)**: Validate scope and priorities
-3. **Gate 2 (Before Issue Creation)**: Confirm acceptance criteria
-
-No gate may be skipped. If user says "whatever you think", state recommendation and get explicit approval.

plugins/devflow-ambient/.claude-plugin/plugin.json

@@ -26,7 +26,8 @@
     "reviewer",
     "git",
     "synthesizer",
-    "resolver"
+    "resolver",
+    "designer"
   ],
   "skills": [
     "router",
@@ -51,6 +52,8 @@
     "patterns",
     "knowledge-persistence",
     "qa",
-    "worktree-support"
+    "worktree-support",
+    "gap-analysis",
+    "design-review"
   ]
 }

plugins/devflow-implement/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "devflow-implement",
-  "description": "Complete task implementation workflow - orchestrates exploration, planning, coding, validation, and PR creation",
+  "description": "Complete task implementation workflow - accepts plan documents, issues, or task descriptions",
   "author": {
     "name": "Dean0x"
   },
@@ -18,8 +18,6 @@
   ],
   "agents": [
     "git",
-    "skimmer",
-    "synthesizer",
     "coder",
     "simplifier",
     "scrutinizer",