# devflow

**Repository Path**: lzugis15/devflow

## Basic Information

- **Project Name**: devflow
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-09
- **Last Updated**: 2026-07-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<h1 align="center">DevFlow</h1>

<p align="center">
  <img src="https://img.shields.io/badge/version-1.0.0-blue?style=flat-square" alt="Version">
  <img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="License">
  <img src="https://img.shields.io/badge/platform-Claude%20Code-orange?style=flat-square" alt="Platform">
  <img src="https://img.shields.io/badge/skills-10%20stages-purple?style=flat-square" alt="Skills">
</p>

<p align="center"><strong>Full-Lifecycle AI Development Pipeline</strong></p>

<p align="center">Design → Build → Fix — one disciplined pipeline that auto-detects what you need<br>and enforces engineering best practices at every stage.</p>

<p align="center">
  <a href="#-quick-install">Quick Install</a> ·
  <a href="#-three-modes">Three Modes</a> ·
  <a href="#-pipeline">Pipeline</a> ·
  <a href="#-philosophy">Philosophy</a> ·
  <a href="#-credits">Credits</a>
</p>

---

## 🤔 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](https://github.com/obra/superpowers) | 240K+ | **Execution Discipline** — TDD, subagent-driven dev, systematic debugging, git worktrees |
| [mattpocock/skills](https://github.com/mattpocock/skills) | 151K+ | **Design Sharpening** — relentless grill interview, domain modeling, ADRs, glossary |
| [Fission-AI/OpenSpec](https://github.com/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

```bash
# 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](https://github.com/obra/superpowers) | [Jesse Vincent (obra)](https://github.com/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](https://github.com/mattpocock/skills) | [Matt Pocock](https://github.com/mattpocock) | Grill-with-docs relentless interview, domain-modeling glossary/ADR discipline, diagnosing-bugs feedback loop construction, code-review 10-smell baseline, TDD seams concept |
| [OpenSpec](https://github.com/Fission-AI/OpenSpec) | [Fission-AI](https://github.com/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](https://github.com/AppleCG)

---

<p align="center">
  <sub>Built by fusing the best of superpowers + grill-with-docs + OpenSpec into one pipeline</sub>
</p>