devflow

Quick Install · Three Modes · Pipeline · Philosophy · Credits

---

🤔 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

---