🤔 What Is DevFlow?
DevFlow is a Claude Code skill plugin that fuses three battle-tested frameworks into one cohesive development pipeline. Each framework is powerful alone, but they don't automatically connect — DevFlow bridges them.
| Framework | Stars | Role in DevFlow |
|---|
| obra/superpowers | 240K+ | Execution Discipline — TDD, subagent-driven dev, systematic debugging, git worktrees |
| mattpocock/skills | 151K+ | Design Sharpening — relentless grill interview, domain modeling, ADRs, glossary |
| Fission-AI/OpenSpec | 58K+ | Spec Management — proposal → delta specs → archive |
The Problem
These frameworks are powerful but don't automatically connect. Brainstorming output doesn't feed into specs. Specs don't feed into task plans. TDD doesn't know about requirements. Knowledge gets lost between stages.
DevFlow's Solution
A single pipeline where every stage reads from and writes to a unified devwork/ directory. No more broken handoffs.
💡 Idea → 🔍 Grill → 📋 Spec → 📐 Plan → 🔨 Apply → ✅ Review → 📦 Archive
🚀 Quick Install
# Clone to your Claude Code skills directory
git clone https://github.com/AppleCG/devflow.git ~/.claude/skills/devflow
That's it. DevFlow auto-activates on your next session. No configuration required.
Requirements: Claude Code with skills support. Git for worktree isolation (Build mode).
🎯 Three Modes
DevFlow analyzes your intent and routes to the right mode automatically:
| Mode | Trigger | Pipeline | Output |
|---|
| 🎨 Design | "How should I...", architecture discussions | Quick-Grill (5 Qs) → Spec-lite | proposal.md + CONTEXT.md + optional ADR |
| 🏗️ Build | "Build...", "Implement...", feature requests | Full 8-stage pipeline | Working code + tests + specs + docs |
| 🔧 Fix | "X is broken", "Bug: ...", error reports | Diagnose → TDD fix → Verify → Archive | Root cause analysis + regression test + fix |
🎨 Design Mode — Quick-Grill Example
You: "I want to add a notification system. How should I design it?"
DevFlow: [Design Mode]
Q1: "What types of notifications? Who receives them?
→ Recommended: Email + in-app for order updates, in-app only for marketing."
Q2: "How does this relate to existing concepts?
→ [Explores codebase] Your User model already has email + preferences fields..."
Q3: "If we 10x to 1M notifications/day — which assumption breaks first?
→ Recommended: Async queue from day one, not a synchronous send."
Q4: "Any irreversible decisions?
→ Yes — provider choice. ADR recommended: AWS SES vs SendGrid vs Resend."
Q5: "Alternatives considered?
→ AWS SES wins on cost at current scale. Can migrate to SendGrid if needed."
→ proposal.md written to devwork/changes/notification-system/
→ CONTEXT.md updated: +Notification, +NotificationChannel
→ ADR-0004: "Use AWS SES for transactional email"
Each question comes with a recommended answer. The model explores your codebase before asking. Terms are captured in CONTEXT.md as they crystallize. ADRs are created only when the triple-filter triggers (hard to reverse + surprising + real trade-off).
🔄 Build Mode — Full 8-Stage Pipeline
| # | Stage | Source | What It Does | Hard Gate |
|---|
| ① | Grill | Matt Pocock | Relentless design interview. One question at a time. Sharpens fuzzy language. Builds CONTEXT.md. | Design approved by user |
| ② | Spec | OpenSpec | Generates proposal.md + WHEN/THEN specs + design.md + tasks.md (initial). | Proposal confirmed |
| ③ | Plan | superpowers | Enhances tasks.md: exact file paths, verification commands, TDD flags, dependency graph. Auto-detects parallel groups. | Every task has file path + verify cmd |
| ④ | Isolate | superpowers | Creates git worktree on new branch. Native tools preferred, git fallback. | Worktree ready, baseline green |
| ⑤ | Apply | All three | TDD (RED→GREEN→REFACTOR) + auto-parallel subagents + checkpoints + 3-failure rollback. | All tasks [x], all tests pass |
| ⑥ | Review | superpowers + Matt | Dual-axis: Spec compliance (WHEN/THEN match code?) + Code quality (10 smell baseline). | Both axes pass |
| ⑦ | Finish | superpowers | Structured menu: merge locally / create PR / keep / discard. | User confirms merge method |
| ⑧ | Archive | OpenSpec + Matt | Sync delta specs → source of truth. Archive change. Capture knowledge. | User confirms archive |
⚡ Stage ⑤ — Enhanced Apply (The Core)
Task N from tasks.md
│
├─ git commit checkpoint
├─ 🔴 RED: Write failing test → Verify it FAILS correctly
├─ 🟢 GREEN: Minimal implementation → Verify it PASSES
├─ 🔵 REFACTOR: Clean up → Verify still green
├─ ✅ Task complete, mark [x]
│
└─ Failure? → git reset --hard checkpoint → retry
└─ 3 failures? → Systematic debugging → Question architecture
TDD Iron Law: No production code without a failing test first. Write code before the test? Delete it. Start over. No exceptions.
Auto-Parallel: Model analyzes the dependency graph. Tasks operating on different files with no dependencies → dispatched as concurrent subagents. Each gets isolated context and precise instructions.
Checkpoint + Rollback: git commit before each task. On failure, git reset --hard to checkpoint. After 3 failures on the same task → upgrade to systematic debugging → question whether the architecture is fundamentally wrong.
Model Selection: Mechanical tasks (1-2 files, clear specs) → fast/cheap model. Integration tasks → standard model. Architecture/review → most capable model.
📁 File Structure
Skill Package (this repo)
skills/devflow/
├── SKILL.md # Entry: mode detection + routing
├── modes/ # Three mode orchestrators
│ ├── design.md # Design mode (Quick-Grill → Spec-lite)
│ ├── build.md # Build mode (Full 8-stage pipeline)
│ └── fix.md # Fix mode (Diagnose → TDD fix → Verify)
├── stages/ # Reusable stage skills
│ ├── grill.md # Full design interview (Matt Pocock style)
│ ├── quick-grill.md # Compressed 5-question interview
│ ├── spec.md # OpenSpec artifact generation
│ ├── plan.md # Task enhancement + dependency analysis
│ ├── isolate.md # Git worktree isolation
│ ├── enhanced-apply.md # TDD + subagent + parallel + rollback (225 lines)
│ ├── review.md # Dual-axis review (spec + quality)
│ ├── diagnose.md # Systematic root cause investigation
│ ├── finish.md # Branch completion (merge/PR/keep/discard)
│ └── archive.md # Knowledge capture + spec sync
└── templates/ # Reference files with annotations
├── CONTEXT.md # Glossary template
├── adr.md # Architecture Decision Record template
├── proposal.md # Change proposal template
├── design.md # Technical design template
├── tasks.md # Task list with dependency graph
├── spec.md # WHEN/THEN behavior spec template
└── summary.md # Change summary template
Project Output (devwork/)
devwork/
├── specs/ # System specs — source of truth (long-lived)
│ └── <domain>/spec.md
├── changes/ # Active changes (short-lived)
│ └── <id>/
│ ├── proposal.md
│ ├── design.md
│ ├── tasks.md # Enhanced by PLAN stage
│ ├── delta/<domain>/ # Delta specs (ADDED/MODIFIED/REMOVED)
│ └── logs/ # Full audit trail
├── knowledge/ # Cross-change knowledge (long-lived)
│ ├── CONTEXT.md # Project glossary
│ └── adr/ # Architecture Decision Records
└── archive/ # Completed changes
🧠 Philosophy
Actions, Not Phases
Traditional workflows lock you into phases. DevFlow follows OpenSpec's philosophy: actions are things you can do, not stages you're stuck in. Update the design during implementation? Go ahead. Discover a new requirement mid-build? The pipeline adapts.
Hard Gates, Not Suggestions
Every stage has a non-negotiable condition that must be met before proceeding. Inspired by superpowers' Iron Law pattern:
- 🚫 No production code without a failing test first
- 🚫 No fixes without root cause investigation first
- 🚫 No completion claims without fresh verification evidence
- 🚫 No CONTEXT.md updates without user confirmation
Process Over Prompt
Methodology is embedded in structured Markdown files with DOT diagrams, checklists, and Red Flags tables — not vague system prompts. Each skill file is self-contained and platform-agnostic.
Knowledge Lives in the Project
All artifacts live in devwork/ in your project root — not in .claude/, not in chat history. Change tools, change AI models, change teammates — the knowledge persists.
📊 Comparison
| Capability | DevFlow | superpowers alone | grill-with-docs alone | OpenSpec alone |
|---|
| Design sharpening | ✅ Grill interview | ⚠️ Brainstorming (no glossary/ADR) | ✅ (no execution pipeline) | ❌ |
| Spec management | ✅ Delta specs + sync | ❌ | ⚠️ ADRs only | ✅ (no execution discipline) |
| TDD enforcement | ✅ Iron Law | ✅ | ⚠️ Optional | ❌ |
| Auto-parallel | ✅ Dependency analysis | ✅ | ❌ | ❌ |
| Checkpoint rollback | ✅ git-based | ❌ | ❌ | ❌ |
| Dual-axis review | ✅ Spec + Quality | ✅ | ⚠️ Quality only | ✅ Verify |
| Knowledge capture | ✅ CONTEXT + ADR + summary | ❌ | ✅ | ❌ |
| Unified output dir | ✅ devwork/ | ❌ (scattered) | ⚠️ docs/ | ✅ openspec/ |
👏 Credits
DevFlow fuses and adapts concepts from three incredible open-source projects:
| Project | Author | What We Adapted |
|---|
| superpowers | Jesse Vincent (obra) | TDD Iron Law, subagent-driven-development, systematic-debugging 4-phase model, writing-plans task right-sizing, git worktree isolation, verification-before-completion, hard gates + Red Flags pattern, DOT diagram process flows |
| skills | Matt Pocock | Grill-with-docs relentless interview, domain-modeling glossary/ADR discipline, diagnosing-bugs feedback loop construction, code-review 10-smell baseline, TDD seams concept |
| OpenSpec | Fission-AI | Spec-driven development, delta specs (ADDED/MODIFIED/REMOVED), artifact dependency graph, explore→propose→apply→archive workflow, actions-not-phases philosophy |
📄 License
MIT © 2026 AppleCG
