dev-flow

↑ Interactive version (dark/light, opens locally in a browser): docs/dev-flow-skill-map.html

A filesystem contract for agent-driven SDLC. One folder (.workflow/), one state file (meta.json), and 44 skills (6 core + 15 web + 2 agent + 16 mobile + 3 monorepo + 2 refactor) that read/write it. The contract is the product — the skills are durable, replaceable consumers.

v1.0.0 — install as a Claude Code plugin: /plugin marketplace add lukedj78/dev-flow then /plugin install dev-flow@dev-flow. Other runtimes (Codex · Copilot · Gemini · Cursor) use install.sh. See the CHANGELOG.

The web family now includes eve-agent — scaffold and grow an eve agent as the AI engine behind a Next.js app, opted into via stack.agent. It lives inside the app, in apps/agent, or alone at the repo root when the product has no UI at all (three topologies). See docs/example-full-walkthrough.md and the autonomous-loop runbook docs/loop-engineering.md.

Rule zero — doc-grounded, never invent. The skills are a second brain: when one says "use library X", it ships the how from X's official docs, prefers the version-matched source the tool itself ships (next dev maintains an AGENTS.md block pointing at bundled docs; eve ships node_modules/eve/docs), marks fast-moving identifiers [VERIFY], and gets re-verified on a cadence — logged in docs/vercel-changelog-watch.md. The map of every how-to is docs/knowledge-index.md.

Golden rules (enforced on every project, see the contract): ① code is written in English (identifiers, constants, comments — independent of the conversation language); ② every frontend ships i18n from day one — web via next-intl, mobile via the RN i18n stack, minimum locales English + Italian, no hardcoded user-facing copy.

                      ┌────────────────────────┐
                      │  .workflow/meta.json   │ ◄─── single source of truth
                      │  (phase + stack +      │      every skill reads
                      │   history + artifacts) │      every skill writes
                      └─────────┬──────────────┘
                                │
              ┌─────────────────┴─────────────────┐
              │                                   │
              ▼ stack.framework="next"            ▼ stack.framework="expo-rn"
              │                                   │
              │   WEB FAMILY (15 skills)           MOBILE FAMILY (16 skills)
              │                                   │
   ┌──────────┼──────────┐               ┌────────┼─────────┐
   │          │          │               │        │         │
   ▼          ▼          ▼               ▼        ▼         ▼
 prd-from-  design-md-  module-add      rn-       rn-       rn-
 idea       to-app      (auth, db,      bootstrap add-      module-add
 prd-to-    screenshot- payments,        rn-      screen    (auth, db,
 tasks      to-page     email, ci, …)   styling   rn-       storage,
 figma-to-  write-tests                  rn-      write-    realtime,
 design-md                                expo-    tests     push,
 image-to-                                router   …         payments)
 design-md              vercel-deploy                       rn-eas-deploy
              │                                   │
              └─────────────────┬─────────────────┘
                                │
                                ▼
                        Codebase at <project-root>/
                        (Next.js app or Expo app)

The skills are interchangeable consumers of the contract. Tomorrow you could rewrite any of them in TypeScript, swap one out for a Cursor-flavored variant, or extend with your own — as long as they read meta.json and respect the phase semantics, they compose.

Three stacks today, one contract. The web stack ships Next.js (or Astro/Vite) + shadcn/Base UI/MUI apps; the mobile stack ships Expo + React Native + NativeWind apps with EAS publishing to the App Store + Play Store; the monorepo stack ships both in one turborepo (with apps/web/ + apps/mobile/ + shared packages/). dev-flow (the orchestrator) reads meta.json#stack.framework and routes to the correct family — prd-from-idea and prd-to-tasks are stack-agnostic and used by all three.

---

Why a contract, not just skills

Most "AI agent toolkits" hardcode orchestration in prompts. That works until the conversation drops context — then the agent forgets which step you were on, what design tokens it picked, which modules it wired.

dev-flow fixes that the way distributed systems fix it: state lives on disk, not in the agent's head. Every skill is independently re-runnable from .workflow/meta.json. Resume a build the next morning, hand it off to a different agent, run two skills in parallel — the contract holds.

The skill count is an implementation detail. The contract is the moat.

---

What the contract gives you

• Resumability. The agent forgets, the filesystem doesn't. meta.json records where you are; any skill can pick up.
• Composability. Skills don't call each other — they read/write the same state. New skills slot in by declaring which phase they consume and produce.
• Portability. The contract is just JSON + Markdown + folders. It survives a model swap, a tooling pivot, even a rewrite of the skills in another language.
• Auditability. Every skill run appends to meta.json#history with inputs, outputs, phase delta. You always know who wrote what when.
• Idempotency. Re-running a skill is safe — it sees its own previous output and skips/updates instead of duplicating.
• Drift detection. Every contract file is content-addressed. When the user edits DESIGN.md by hand, the system knows that registry.json and /showcase (which were derived from it) are now stale — and it knows transitively, so a chain of derivations propagates.

The contract is also published as a standalone Python package, dev-flow-contract, so any future tool — a Cursor plugin, a CLI, a different LLM agent — can read/write .workflow/ without depending on Claude Code. The skills are interchangeable consumers; the package is the durable surface.

---

Quick start (5 minutes)

1. Install the skills

Two ways in, two philosophies. The plugin subscribes you to the suite as a managed bundle that updates when we ship. install.sh copies the skill files so you can fork and hack on them — and it's the route for Codex / Copilot / Gemini / Cursor. Pick one; installing both leaves you with every skill twice.

Option A — Claude Code plugin (recommended)

/plugin marketplace add lukedj78/dev-flow
/plugin install dev-flow@dev-flow

All 44 skills arrive namespaced (dev-flow:forms, dev-flow:rn-bootstrap, …), and /plugin marketplace update pulls new releases. The shipped set is generated from the canonical taxonomy, so what you install always matches skills.json and the CHANGELOG.

Option B — bundled install.sh (editable copies, all runtimes)

git clone [email protected]:lukedj78/dev-flow.git
cd dev-flow
./install.sh                          # defaults to Claude Code
./install.sh --platform codex         # or Codex CLI / Copilot / Gemini / Cursor
./install.sh --list-platforms         # see all supported runtimes

The script copies all 44 skill folders into the platform-appropriate location (e.g. ~/.claude/skills/, ~/.codex/dev-flow-skills/, ~/.gemini/skills/), drops in the right bootstrap file (AGENTS.md, GEMINI.md, .cursorrules) when needed, and backs up any pre-existing version with the same name to <skill>.bak. To uninstall + restore backups: ./uninstall.sh --platform <same>.

Portability: dev-flow's skills are designed to be runtime-portable. See Cross-platform support below.

Option C — /plugin add a single skill (local development)

If you have the repo cloned locally:

/plugin add /path/to/dev-flow/dev-flow
/plugin add /path/to/dev-flow/prd-from-idea
…

Run once per skill folder. Useful if you only want to install a subset.

Option D — gh skill install (GitHub CLI extension)

gh extension install <ext-author>/gh-skill          # one-time
gh skill install lukedj78/dev-flow                   # private repo, requires auth
# OR for a specific subset
gh skill install lukedj78/dev-flow dev-flow design-md-to-app

This works with the same gh auth you already use to clone private repos.

Option E — drag-and-drop the .skill files

The dist/ folder contains packaged .skill archives. Drag them into your Claude Code window one at a time — useful when you don't have shell access on the target machine. (dist/ is regenerated periodically; the newest skills — e.g. eve-agent — may ship source-only until repackaged, so prefer install.sh for the full set.)

Verify

ls ~/.claude/skills/ | wc -l
# Should print 44. Restart Claude Code if you don't see them in /skills.

The core happy-path skills (the web flow most projects start with):

Skill	What it does
dev-flow	The orchestrator — reads .workflow/meta.json and proposes what to do next
prd-from-idea	Idea paragraph → PROJECT.md + PRD.md
prd-to-tasks	PRD.md → tasks.md (importable into beads / Linear / GitHub Issues)
linear-scrum	Take a project into Linear and run it with agile scrum — cycles, estimates, sprint planning, velocity reports; Linear as source of truth
compliance-audit	GDPR + EU AI Act audit of an existing project (10-point risk register) + safe auto-remediation; flags legal decisions. Horizontal; proposed as a pre-deploy gate
spec-review	Review a diff on two axes — does it match PRD.md/tasks.md, and does it obey the contract it was built under? Parallel sub-agents, reported side by side, never merged
figma-to-design-md	Figma URL → DESIGN.md (Google design.md spec) + screenshots
image-to-design-md	1+ raster images → DESIGN.md + screenshots
design-md-to-app	DESIGN.md → scaffolded Next.js + shadcn app with theme + showcase + folder convention
coss-ui	Coss/UI (Cal.com design system on Base UI) via the shadcn @coss/* registry — Init/Add modes, DESIGN.md token reconciliation; requires Tailwind v4, mixed MIT/AGPLv3 license
screenshot-to-page	One screenshot → one route, with pixel-perfect verification loop
module-add	Wire auth / db / payments / email / test / ci / motion / voice / realtime / storage / deploy modules
write-tests	One source file (server action / page / component / query) → its Vitest or Playwright test, following the project's existing patterns
vercel-deploy	Ship the web app: preview → smoke → staged production → promote → domains + DNS, with a rollback runbook. The only skill that sets phase = "deployed" for web

install.sh installs all 44 skills, not just these. Beyond the core flow above: the compliance-audit capability, the web discipline skills (forms, data-fetching, state-discipline, transitions), the web add-ons (heroicons-animated animated icons, vercel-doctor cost/perf and shadscan UI-quality pre-deploy gates, vercel-deploy the ship step), the agent engine (eve-agent, eve-registry-porting), the 2 refactor skills (promote-component, composition-patterns-guide), the 16 mobile rn-* skills, and the 3 monorepo skills. Full breakdown in The 44 skills, in detail.

2. Create a project

mkdir -p ~/projects/my-app && cd ~/projects/my-app

3. Open Claude Code in that directory and say:

"I want to build a CRM for veterinary clinics. Customer records, vaccination history, appointment scheduling, document archive."

The orchestrator (dev-flow) will:

1. Create .workflow/meta.json.
2. Invoke prd-from-idea → PROJECT.md + PRD.md.
3. Ask if you have a Figma / images / want to write the DESIGN.md by hand.
4. Invoke the right design-extraction skill → .workflow/DESIGN.md.
5. Ask for stack choice (Next + shadcn is the default).
6. Invoke design-md-to-app → fully scaffolded codebase + showcase.
7. Optionally invoke screenshot-to-page for routes from your screenshots.
8. Optionally invoke module-add for db / auth / etc.

By the end you have a runnable Next.js app at the project root, with a .workflow/ folder that documents every decision.

---

Use cases

Seven concrete recipes — what to type, what to expect. Pick the one that matches your situation and start there. The sections below assume you've installed the skills (see Quick start).

1. Greenfield project — idea to running app

Situation: empty directory, you have an idea, no design assets yet.

mkdir -p ~/projects/vet-crm && cd ~/projects/vet-crm

In Claude Code, say:

"I want to build a CRM for veterinary clinics. Customer records, vaccination history, appointment scheduling."

The orchestrator routes through phases:

1. dev-flow            → init_workflow .  (creates .workflow/meta.json, phase=empty)
2. prd-from-idea       → PROJECT.md + PRD.md  (phase=prd_drafted)
3. prd-to-tasks        → tasks.md  (phase=tasks_split)
4. image-to-design-md  → DESIGN.md  (asks for reference screenshots)
   OR figma-to-design-md if you have a Figma URL
5. design-md-to-app    → full scaffold + /showcase  (phase=scaffolded)
6. screenshot-to-page  → /clients, /appointments, …  (phase=page_generated)
7. module-add db       → Drizzle + Neon
8. module-add auth     → better-auth

Check progress at any time:

$ python3 ~/.claude/skills/dev-flow/scripts/show_state.py .
Project:  'Vet CRM'  ('vet-crm')
Phase:    scaffolded
Stack:    framework=next, ui=shadcn
Skill runs: 4
  - prd-from-idea         → phase=prd_drafted
  - image-to-design-md    → phase=design_extracted
  - design-md-to-app      → phase=scaffolded
Next step proposal: screenshot-to-page  OR  module-add

End-to-end time: ~25 minutes if Neon credentials are ready, ~10 minutes with placeholder env values.

---

2. You already have a DESIGN.md — skip straight to scaffold

Situation: you wrote a DESIGN.md by hand (or copied from another project) and want to scaffold immediately.

mkdir my-app && cd my-app
mkdir .workflow
cat > .workflow/DESIGN.md << 'EOF'
# My App Design System
## Color Palette
- primary: #0066cc
- background: #ffffff
- on-surface: #111827
## Typography
- display: Inter, 48px, 600
- body: Inter, 16px, 400
...
EOF

In Claude Code:

"Use this DESIGN.md to scaffold the app. Next + shadcn."

design-md-to-app starts directly from phase=design_extracted, skips PRD/tasks (the DESIGN is already there), and produces:

• package.json, app/, components/site/, lib/server/, lib/queries/
• registry.json (token-first shadcn install)
• app/showcase/page.tsx with 9 sections
• app/error.tsx, app/loading.tsx, lib/env.ts (Zod-validated), next.config.ts (security headers)
• Theme provider + mode-toggle (D-key shortcut, with rich-editor exclusion)
• Folder skeleton ready for screenshot-to-page and module-add

---

3. Figma → DESIGN.md (3 access paths, picked automatically)

Situation: you have a Figma URL and want to extract the design system.

mkdir ~/projects/aether && cd ~/projects/aether

In Claude Code:

"Extract the design system from this Figma file: https://www.figma.com/design/<file-key>/Aetherfield"

figma-to-design-md picks the first available access path:

Path	When it fires	Quality
A — Figma Dev Mode MCP	A mcp__figma* tool is exposed in this session	High — uses real variables + styles
B — Figma REST API	FIGMA_ACCESS_TOKEN is set, OR you provide a personal access token when asked	Medium-high — variables + styles via /v1/files/<key>
C-bis — Playwright-assisted	Browser MCP available but no Figma access — opens the file in a headless browser, screenshots key frames, runs k-means on the pixels	Medium — palette inferred, typography from rendered text
C — Manual export	Nothing else available — guides you to export PNGs + (optional) Tokens Studio JSON	Lower, but always works

The skill tells you explicitly which path it's using:

$ "Using Path A — Figma MCP, found mcp__figma__get_file"
$ "Using Path B — REST API with token from env"
$ "No Figma access. Falling back to Path C-bis with Playwright."

Path B example (most common — you have a token but no MCP):

export FIGMA_ACCESS_TOKEN=figd_xxx

"Extract design from https://www.figma.com/design/<file-key>/MyProject"

The extraction produces:

• .workflow/DESIGN.md (Google design.md spec)
• .workflow/screenshots/<frame-name>.png (2–3 reference frames)
• .workflow/_design-md-mapping.json recording which path was used + any fallbacks

If Path A/B couldn't read typography (rare), the skill stops and asks instead of inventing weights — typography is non-negotiable.

---

4. Screenshot → page (two-mode pixel verification)

Situation: you have a screenshot of a UI and want it as a real route.

Drop the screenshot in .workflow/screenshots/dashboard.png, then:

"Turn dashboard.png into /dashboard."

screenshot-to-page picks the verification mode based on the kind of route:

Route shape	Mode	Target	Iter cap
/dashboard, /settings, /clients/<id>, anything CRUD	structure-first (default)	≤ 8% delta, token-correct	3
/, /pricing, /about, /sign-up, marketing/landing	pixel-tight (opt-in)	≤ 2% delta	8

Why two modes: pixel-tight on dashboards produces rigid HTML that imitates pixels instead of respecting tokens. The next developer can't tell which spacing was a design choice and which was an LLM matching one pixel. For brand-critical surfaces (heros, pricing), the inverse is true — fidelity IS the value.

The skill states the chosen mode in its hand-off:

"Iterated in structure-first mode (3 passes, final delta 6.4%) — token-correct, semantically clean. Switch to pixel-tight if you want closer fidelity for production."

---

5. Retroactive edit to DESIGN.md (drift detection)

Situation: you edited .workflow/DESIGN.md by hand (changed primary from blue to purple) after the app was already scaffolded.

$ python3 ~/.claude/skills/dev-flow/scripts/check_drift.py . --plan
  ✗ .workflow/DESIGN.md    image-to-design-md  self-drift
  ⚠ registry.json          design-md-to-app    upstream-stale
  ⚠ app/showcase/page.tsx  design-md-to-app    upstream-stale  (transitively via registry.json)

Migration plan (re-run these skills, in order):
  image-to-design-md:
    ✗ .workflow/DESIGN.md  (self-drift)
  design-md-to-app:
    ⚠ registry.json
    ⚠ app/showcase/page.tsx

Run the skills in the order shown — each one's outputs will refresh
the artifacts and clear the drift downstream.

You know exactly what to re-run and in what order. Drift propagates transitively through derived_from chains.

This is the use case the linear phase enum could not handle — the system now models the actual iterative workflow of product development.

---

6. Add a module to an existing scaffold

Situation: scaffold is running. You want a database, then auth, then payments.

"Add a database."

module-add checks prerequisites, picks the default (Drizzle + Neon), installs:

• drizzle-orm, @neondatabase/serverless, drizzle-kit
• lib/db/schema.ts with tenant-scoped indexes, uniqueIndex, soft-delete archivedAt convention, RLS docs
• drizzle.config.ts, lib/db/index.ts
• pnpm db:push / db:migrate / db:studio scripts in package.json
• DATABASE_URL in .env.local.example

"Add auth."

Detects stack.db = neon-drizzle, picks better-auth as the default:

• lib/auth.ts, lib/auth-client.ts, app/api/auth/[...all]/route.ts
• lib/auth-server.ts with getCurrentUserId() / getCurrentTenantId() helpers — replaces the stubs in lib/server/<domain>.ts
• Auth tables appended to lib/db/schema.ts
• BETTER_AUTH_SECRET, BETTER_AUTH_URL env vars

"Add payments."

Stripe with subscriptions + one-time:

• lib/stripe.ts (server SDK with pinned apiVersion), lib/stripe-client.ts (memoized loader)
• app/api/stripe/webhook/route.ts (signed receiver, idempotent handler) + /portal redirect
• app/billing/page.tsx reference UI
• subscriptions table in Drizzle schema
• Instructions for stripe listen --forward-to localhost:3000/api/stripe/webhook during dev

Same shape for module-add email (Resend + React Email), module-add test (Vitest + Playwright), module-add ci (husky + GH Actions). Re-running is idempotent — the skill detects existing installs and skips.

---

7. Use the contract outside Claude Code

Situation: you want to build your own tool — a CLI, a Cursor extension, a different LLM agent — that reads/writes .workflow/.

pip install -e ./contract-package    # while not on PyPI yet

from pathlib import Path
from dev_flow_contract import (
    init_workflow, record_artifact, set_phase, append_history,
    check_drift, Phase
)

root = Path("./my-project")
init_workflow(root, name="My Project")

# After your tool writes a file:
(root / ".workflow" / "DESIGN.md").write_text("# Design")
record_artifact(root, ".workflow/DESIGN.md", produced_by="my-extractor")

# Bump the phase + record the run:
set_phase(root, Phase.DESIGN_EXTRACTED)
append_history(
    root,
    skill="my-extractor",
    inputs={"source_url": "https://..."},
    outputs=["DESIGN.md"],
    phase_after=Phase.DESIGN_EXTRACTED,
)

# Later, check what's stale:
report = check_drift(root)
if report.has_drift:
    for row in report.rows:
        if row.status != "fresh":
            print(f"{row.path}: {row.status}")

The dev-flow Claude Code skills are interchangeable consumers of this package. Tomorrow you can rewrite any of them in TypeScript, swap one for a Cursor variant, or extend with your own — as long as your tool reads/writes the contract correctly, it composes.

---

Cross-platform support

dev-flow is designed to be runtime-portable. The contract (.workflow/) is just JSON + Markdown + folders, the helper scripts are pure Python, and the skill bodies are tool-name-agnostic prose. The only Claude Code-specific bit is the discovery mechanism — and that's solved per-runtime by a small bootstrap file.

Support matrix

Runtime	Install path	Bootstrap	Status
Claude Code	~/.claude/skills/	none — auto-discovered	✅ fully tested
Codex CLI (OpenAI)	~/.codex/dev-flow-skills/	AGENTS.md (auto-copied)	🧪 scaffolded, not yet validated end-to-end
Copilot CLI (GitHub)	~/.config/gh-copilot/skills/	none — skill tool auto-discovers	🧪 scaffolded
Gemini CLI (Google)	~/.gemini/skills/	GEMINI.md (auto-copied)	🧪 scaffolded
Cursor	~/.dev-flow-skills/	.cursorrules (auto-copied)	🧪 scaffolded
Generic (any LLM agent)	~/.dev-flow-skills/	system-prompt.md (manual integration)	🧪 scaffolded

🧪 scaffolded means: the install path + bootstrap file are wired and tested for shape (./install.sh --platform codex produces the right tree), but full end-to-end runs against the real runtime haven't been validated yet. If you try one and hit issues, please file an issue — happy to iterate.

What makes it portable

1. Tool-name mapping — the skill bodies use Claude Code names (Bash, Read, Edit, Glob, Grep). The bootstrap/tool-mappings.md reference (installed alongside the skills) is the canonical Claude → Codex → Copilot → Gemini → Cursor equivalence table. The LLM reads it once at session start and translates as it goes.

2. Bootstrap files for runtimes that don't auto-discover skills:

   • bootstrap/templates/AGENTS.md — Codex CLI entry point
   • bootstrap/templates/GEMINI.md — Gemini CLI entry point
   • bootstrap/templates/.cursorrules — Cursor entry point
   • bootstrap/templates/system-prompt.md — generic system-prompt fallback for custom agents

3. dev-flow-contract Python package — the runtime-independent core. Any Python-capable agent can read/write .workflow/ correctly without depending on any specific runtime:

   from dev_flow_contract import init_workflow, record_artifact, check_drift
   

4. Agent-agnostic helper scripts — init_workflow.py, update_meta.py, check_drift.py. They're invoked by shell, so every runtime can use them via whatever shell tool it has.

Per-runtime usage guide

Six recipes — install once, then per-project. Same skill content, same .workflow/ contract, different loading mechanism.

Claude Code (native)

Install once:

git clone https://github.com/lukedj78/dev-flow.git
cd dev-flow
./install.sh

Use it on any project:

mkdir ~/projects/my-app && cd ~/projects/my-app
claude            # open Claude Code here

Then say:

"I want to build a CRM for veterinary clinics."

Auto-discovery picks the skills from ~/.claude/skills/, dev-flow orchestrator routes. Nothing to configure per project.

Codex CLI (OpenAI)

Install once:

./install.sh --platform codex
# → ~/.codex/dev-flow-skills/ + ~/.codex/dev-flow-skills/AGENTS.md

Per project:

mkdir ~/projects/my-app && cd ~/projects/my-app
cp ~/.codex/dev-flow-skills/AGENTS.md .
codex

Codex reads AGENTS.md at session start. The template tells it where the skills live, how to translate Claude tool names to Codex equivalents (Bash → shell, Edit → apply_patch), and how to update meta.json after each step.

"I want to build a CRM for veterinary clinics."

Minimal variant (if you don't want to copy AGENTS.md to every project):

echo "Load instructions from ~/.codex/dev-flow-skills/AGENTS.md" > AGENTS.md

Copilot CLI (GitHub)

Install once:

./install.sh --platform copilot
# → ~/.config/gh-copilot/skills/

No per-project bootstrap — Copilot CLI auto-discovers skills like Claude Code.

cd ~/projects/my-app
gh copilot suggest "I want to build a CRM for veterinary clinics"

Verify the install:

gh copilot skills list | grep dev-flow

Gemini CLI (Google)

Install once:

./install.sh --platform gemini
# → ~/.gemini/skills/ + ~/.gemini/skills/GEMINI.md

Per project:

mkdir ~/projects/my-app && cd ~/projects/my-app
cp ~/.gemini/skills/GEMINI.md .
gemini

Gemini reads GEMINI.md at session start. Skills are activated via activate_skill when a trigger pattern matches.

"I want to build a CRM for veterinary clinics."

Cursor

Install once:

./install.sh --platform cursor
# → ~/.dev-flow-skills/ + ~/.dev-flow-skills/.cursorrules

Per project:

mkdir ~/projects/my-app && cd ~/projects/my-app
cp ~/.dev-flow-skills/.cursorrules .
cursor .

Open Cursor's chat (Cmd+L) and say:

"I want to build a CRM for veterinary clinics."

Honesty caveat: Cursor doesn't have a native skills system. The skills become prompt augmentation loaded via .cursorrules — not auto-routing. Quality depends on how well Cursor follows the rules; on long sessions it can drop references. Works better if you guide explicitly: "Use the prd-from-idea skill to draft a PRD."

Custom agent (LangChain, OpenAI Assistants, raw API)

Install once:

./install.sh --platform generic
# → ~/.dev-flow-skills/ + ~/.dev-flow-skills/system-prompt.md

Prepend system-prompt.md to your agent's system prompt. Examples:

LangChain

from langchain.prompts import SystemMessagePromptTemplate

with open("/Users/you/.dev-flow-skills/system-prompt.md") as f:
    dev_flow_prompt = f.read()

system_msg = SystemMessagePromptTemplate.from_template(
    dev_flow_prompt + "\n\nYou are a coding assistant…"
)

OpenAI Assistants API

from openai import OpenAI
client = OpenAI()

assistant = client.beta.assistants.create(
    name="My Dev Agent",
    instructions=open("/Users/you/.dev-flow-skills/system-prompt.md").read(),
    tools=[{"type": "code_interpreter"}],
    model="gpt-4o",
)

The agent must have:

• Filesystem read/write to ~/.dev-flow-skills/ (so it can read SKILL.md files).
• Shell execution (so it can call the Python helpers: init_workflow.py, update_meta.py, check_drift.py).

Without both, the contract operations don't work.

Universal commands (any runtime)

These are runtime-agnostic — every platform calls them via shell:

# Show project state
python3 ~/.<platform>/<skills-dir>/dev-flow/scripts/show_state.py .

# Detect drift after manual edits to contract files
python3 ~/.<platform>/<skills-dir>/dev-flow/scripts/check_drift.py . --plan

Or, from any Python runtime that installed the contract package:

pip install -e ~/dev-flow/contract-package

from dev_flow_contract import init_workflow, check_drift, record_artifact

Picking the right runtime

If…	Use	Why
You want zero-config + best auto-routing	Claude Code	The skills were designed for it; matching is unambiguous
You're already on the OpenAI CLI / prefer OpenAI models	Codex CLI	Solid AGENTS.md support, but you'll need to validate (not e2e tested)
You work in GitHub repos and want everything via gh	Copilot CLI	Auto-discovery + natural fit with git/PR workflows
You want Google models / huge context windows	Gemini CLI	1M+ token context useful on big projects
Your IDE is Cursor and you don't want to switch tools	Cursor	No tool-switch, but routing is weaker — you'll be more explicit
You're building a custom agent	Generic	system-prompt.md is the smallest possible starting point

Honest disclaimer: today only Claude Code has been tested end-to-end. The other 5 are scaffolded — install paths and bootstraps are wired, but full project runs haven't been validated. If you try one and it works, open an issue so the support matrix can be updated; if it doesn't work, also open one — fixes come from feedback.

Porting to a runtime not listed

If your agent runtime isn't in the matrix:

1. Create a bootstrap file mirroring the structure of bootstrap/templates/system-prompt.md.
2. Add your runtime's tool names to bootstrap/tool-mappings.md (PRs welcome).
3. Add a case to install.sh's platform switch.

The skill bodies and the contract don't need to change — only the bootstrap layer.

---

Documentation

• 📐 Architecture — the .workflow/ contract, the meta.json schema, the phase enum, file conventions.
• 🛠 Conventions — folder layout (components/site/ vs app/<route>/_components/), server actions in lib/server/<domain>, theme system with keyboard shortcut, showcase template.
• 📚 Case studies — three projects built with the suite (Aetherfield editorial, Notarius CRM, Wisely fintech). Each shows which skills were used and what was generated.
• 🤖 Full walkthrough — one product ("Helmsman" AI support desk) exercising all 44 skills, phase by phase: core → design → monorepo → web → mobile → agent (eve) → voice/realtime → deploy.
• 🔁 Loop engineering — runbook for an autonomous Linear → Claude Code → PR loop on a Hetzner server (the harness that repeats one dev-flow iteration). Project-agnostic; eve is one optional payload.
• 📇 Knowledge index — the map of every doc-grounded how-to: which domain, which reference, which upstream to re-verify. Start here when wiring a library or running a knowledge refresh.
• 🧠 Obsidian — this repo is also an Obsidian vault (config committed): graph view over skills → references, backlinks, full-text search across all 44 skills.
• 🔤 CONTEXT.md — the ubiquitous language: what skill, family, phase, reference, gate, module mean here, and the words to avoid (three different things are called "registry" — always qualify it).
• 📋 CHANGELOG.md — semver on the suite as a whole; what a major/minor/patch bump means for the contract.
• 🚫 .out-of-scope/ — decisions not to build, each with what would change our mind. Read before proposing something that was already evaluated.

---

Repository layout

<skill-name>/                44 skill folders, FLAT at the root
├── SKILL.md                 the skill (frontmatter: name + description)
├── references/*.md          its doc-grounded how-tos, recipes, vendored contract
└── scripts/*                its executable helpers + tests
docs/                        cross-cutting docs, knowledge index, assets
scripts/                     repo tooling (registry + manifest + bundle builders, linter)
dist/                        generated <skill>.skill bundles (one per skill)
.claude-plugin/              plugin.json (generated) + marketplace.json — plugin distribution
.out-of-scope/               decisions not to build, with what would change our mind
.obsidian/                   committed vault config (see docs/OBSIDIAN.md)
bootstrap/ contract-package/ evals/   templates, the contract as a package, eval fixtures
README.md · CONTEXT.md (glossary) · CHANGELOG.md · install.sh · uninstall.sh · skills.json

Why the skill folders are flat, not nested by family. The root mirrors the install target (~/.claude/skills/<name>/) one-to-one, keeps ~385 cross-skill reference paths valid, and matches what Claude Code / Codex / Gemini expect. The six-family grouping is logical, not physical: it lives in the TAXONOMY map in scripts/build_skills_registry.py and is published in skills.json. That map is the single source of truth for family + role — a skill missing from it is a build error, never a silent default, so the counts here and in install.sh can't drift out of sync again.

---

The 44 skills, in detail

6 skills are stack-agnostic core: dev-flow, prd-from-idea, prd-to-tasks, linear-scrum, compliance-audit, and spec-review — all three stacks use them. The 15 web-stack skills assume meta.json#stack.framework="next" (and stack.nextjs_version="16" — Pages Router and pre-16 are refused); the 2 agent-engine skills (eve-agent, eve-registry-porting) assume stack.agent="eve"; the 16 mobile-stack skills assume "expo-rn"; the 3 monorepo-stack skills assume "monorepo". The 2 refactor skills (promote-component, composition-patterns-guide) are stack-agnostic and work across all three. dev-flow reads that key and routes.

Web stack (Next.js + shadcn/ui)

dev-flow — the orchestrator

When to use it: when you want to not think about which skill comes next. Paste an idea / a Figma URL / images, and dev-flow figures out the right specialist to invoke based on phase in meta.json.

phase=empty            → prd-from-idea
phase=idea_captured    → prd-from-idea (expand)
phase=prd_drafted      → branches by stack.framework:
                         "next"    → prd-to-tasks  OR  figma-to-design-md  OR
                                     image-to-design-md  OR  design-md-to-app
                         "expo-rn" → rn-bootstrap (mobile scaffold)
phase=tasks_split      → figma-to-design-md  OR  image-to-design-md  OR  design-md-to-app
phase=design_extracted → "next"    → design-md-to-app
                         "expo-rn" → rn-bootstrap
phase=scaffolded       → "next"    → screenshot-to-page  OR  module-add
                         "expo-rn" → rn-add-screen  OR  rn-module-add  OR  rn-write-tests
phase=page_generated   → module-add (next)  OR  rn-module-add (expo-rn)  OR  more screen-gen
phase=module-added     → write-tests / rn-write-tests  OR  iterate
                         → eventually the stack's deploy skill, once feature-complete
phase=feature_complete → gates (any stack): compliance-audit  +  vercel-doctor (web on Vercel)
                         "next"    → vercel-deploy
                         "expo-rn" → rn-eas-deploy
                         eve agent → eve deploy
phase=deployed         → "next"    → maintenance loop: screenshot-to-page / module-add,
                                     re-run the gates after material changes
                         "expo-rn" → maintenance loop: rn-add-screen for new features,
                                     rn-eas-build-submit-update for OTA hotfixes

dev-flow does not do specialist work itself — it only routes and updates state. If you find it doing PRD drafting or scaffolding directly, that's a bug.

Bundled scripts:

• scripts/init_workflow.py <project-root> [--name "Project Name"] — creates .workflow/ with a fresh meta.json.
• scripts/show_state.py <project-root> — prints current phase, files present, proposed next step.

prd-from-idea — paragraph → PRD

Input: a paragraph or two describing what you want to build. Output:

• .workflow/PROJECT.md — strategic brief (audience, problem, value prop, success criteria).
• .workflow/PRD.md — product requirements (user stories, acceptance criteria, non-goals, open questions).

How it works: the skill asks you 5–8 high-leverage questions, parses your answer, fills the templates. It refuses to invent: if you can't answer "who is this for", it writes <TBD — needs user input> rather than guess.

prd-to-tasks — PRD → executable checklist

Input: .workflow/PRD.md (and .workflow/PROJECT.md for context). Output: .workflow/tasks.md with 1 task per - [ ] checkbox. Compatible with beads, GitHub Issues import, Linear CSV, ralph-tui.

Sizing: each task ≈ 2–8 hours of focused work. If a task is bigger, the skill splits it. If smaller, it