devflow

name	devflow
description	Full-lifecycle AI development workflow — auto-detects whether you need design, build, or fix mode, then enforces the right pipeline with hard gates at every stage. Fuses grill-with-docs, OpenSpec, and superpowers methodology.

DevFlow — Disciplined AI Development Pipeline

Announce at start: "I'm using DevFlow to guide this work. Detecting the right mode..."

Mode Detection

Before ANY action, analyze the user's intent. You MUST classify into one of three modes:

graph TD
    START["User message received"] --> Q1{"Discussing design,<br/>architecture, or<br/>'how should I...'?"}
    Q1 -->|yes| DESIGN["→ Design Mode<br/>quick-grill → spec-lite"]
    Q1 -->|no| Q2{"Building a feature,<br/>implementing a change,<br/>or writing code?"}
    Q2 -->|yes| BUILD["→ Build Mode<br/>full 8-stage pipeline"]
    Q2 -->|no| Q3{"Reporting a bug,<br/>unexpected behavior,<br/>or 'X is broken'?"}
    Q3 -->|yes| FIX["→ Fix Mode<br/>diagnose → apply → verify → archive"]
    Q3 -->|no| ASK["Ask user to clarify intent"]

Decision heuristics:

Signal	Mode
"design", "architecture", "how should I", "what's the best way", "should we use X or Y", "plan for", "think about"	Design
"build", "implement", "add feature", "create", "develop", "code", /opsx:propose, /opsx:apply	Build
"fix", "bug", "broken", "error", "crash", "doesn't work", "unexpected", "failing test"	Fix
Single word, vague, ambiguous across modes	Ask

Hard Gate

DO NOT take any action until mode is determined and announced.
DO NOT write code, scaffold, or implement anything in Design mode.
DO NOT skip Fix mode's diagnosis phase before proposing fixes.

Mode Routing

Once mode is determined, invoke the corresponding mode skill:

• Design mode → invoke devflow/modes/design
• Build mode → invoke devflow/modes/build
• Fix mode → invoke devflow/modes/fix

Directory Structure

All artifacts go to devwork/ in the project root:

devwork/
├── specs/           # System specs (source of truth)
├── changes/         # Active changes
│   └── <id>/
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       ├── delta/   # Delta specs
│       └── logs/    # Execution trace
├── knowledge/       # Long-lived knowledge
│   ├── CONTEXT.md   # Project glossary
│   └── adr/         # Architecture Decision Records
└── archive/         # Completed changes

Red Flags — STOP and Re-route

If you catch yourself...	Action
Writing code during a design discussion	STOP. Switch to Design mode.
Skipping diagnosis and jumping to a fix	STOP. Switch to Fix mode.
Implementing without a spec or plan	STOP. Go through Build mode from the start.
"This is too simple to need the full pipeline"	Every change goes through the right mode. Simplicity determines depth, not whether to use the mode.
Mixing design discussion with implementation	STOP. Finish design first, then transition to Build.

Common Rationalizations

Excuse	Reality
"This is just a quick question"	Quick questions hide unexamined assumptions. Design mode catches them.
"I know what to do, skip the process"	Process IS the value. The pipeline catches what you miss.
"This bug is obvious"	Obvious bugs have root causes. Fix mode diagnoses before fixing.
"I'll document later"	grill-with-docs captures knowledge inline. Later = never.