Full-Lifecycle AI Development Pipeline
Design → Build → Fix — one disciplined pipeline that auto-detects what you need
and enforces engineering best practices at every stage.
Quick Install · Three Modes · Pipeline · Philosophy · Credits
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 |
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.
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
# Clone to your Claude Code skills directory
git clone https://github.com/AppleCG/devflow.git ~/.claude/skills/devflowThat's it. DevFlow auto-activates on your next session. No configuration required.
Requirements: Claude Code with skills support. Git for worktree isolation (Build mode).
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 |
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).
| # | 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 |
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.
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
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
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.
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
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.
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.
| Capability | DevFlow | superpowers alone | grill-with-docs alone | OpenSpec alone |
|---|---|---|---|---|
| Design sharpening | ✅ Grill interview | ✅ (no execution pipeline) | ❌ | |
| Spec management | ✅ Delta specs + sync | ❌ | ✅ (no execution discipline) | |
| TDD enforcement | ✅ Iron Law | ✅ | ❌ | |
| Auto-parallel | ✅ Dependency analysis | ✅ | ❌ | ❌ |
| Checkpoint rollback | ✅ git-based | ❌ | ❌ | ❌ |
| Dual-axis review | ✅ Spec + Quality | ✅ | ✅ Verify | |
| Knowledge capture | ✅ CONTEXT + ADR + summary | ❌ | ✅ | ❌ |
| Unified output dir | ✅ devwork/ | ❌ (scattered) | ✅ openspec/ |
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 |
MIT © 2026 AppleCG
Built by fusing the best of superpowers + grill-with-docs + OpenSpec into one pipeline