{"id":51248839,"url":"https://github.com/oraphadev/ai-workflow","last_synced_at":"2026-06-29T06:02:37.546Z","repository":{"id":366930724,"uuid":"1278519610","full_name":"oraphadev/ai-workflow","owner":"oraphadev","description":"Take a project from an empty directory to a deployed MVP through an 8-stage, gate-driven AI pipeline. Install: npx skills add oraphadev/ai-workflow --agent claude-code","archived":false,"fork":false,"pushed_at":"2026-06-23T23:26:31.000Z","size":150,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-24T00:21:06.998Z","etag":null,"topics":["agent-skill","ai-workflow","claude-code","skills-cli","vibe-coding"],"latest_commit_sha":null,"homepage":null,"language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oraphadev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-23T21:51:29.000Z","updated_at":"2026-06-23T23:26:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/oraphadev/ai-workflow","commit_stats":null,"previous_names":["oraphadev/ai-workflow"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/oraphadev/ai-workflow","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oraphadev%2Fai-workflow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oraphadev%2Fai-workflow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oraphadev%2Fai-workflow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oraphadev%2Fai-workflow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oraphadev","download_url":"https://codeload.github.com/oraphadev/ai-workflow/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oraphadev%2Fai-workflow/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34915002,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-29T02:00:05.398Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skill","ai-workflow","claude-code","skills-cli","vibe-coding"],"created_at":"2026-06-29T06:02:36.980Z","updated_at":"2026-06-29T06:02:37.537Z","avatar_url":"https://github.com/oraphadev.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AI Workflow — idea to deployed MVP, gate by gate\n\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Skills CLI](https://img.shields.io/badge/skills.sh-oraphadev%2Fai--workflow-black)](https://skills.sh/oraphadev/ai-workflow)\n[![Made for Claude Code](https://img.shields.io/badge/made%20for-Claude%20Code-d97757)](https://claude.com/claude-code)\n\nAn agent skill that takes a project from an **empty directory to a deployed MVP** through one disciplined, resumable pipeline — research the market, specify the product, design the brand, choose the stack, provision the services, build the agent harness, and only then write code.\n\n```bash\nnpx skills add oraphadev/ai-workflow --agent claude-code\n```\n\n\u003csub\u003eDiagram source: [`assets/ai-workflow.excalidraw`](assets/ai-workflow.excalidraw) · interactive: [`assets/ai-workflow.html`](assets/ai-workflow.html)\u003c/sub\u003e\n\n```\n1 Discovery → 2 Scope → 3 Brand → 4 Prototyping → 5 Stack → 6 Instrumentation → 7 Harness → 8 Vibe Coding\n└──────────────────── planning (1–6) ────────────────────┘   └─ harness (7) ─┘  └─ build (8) ─┘\n```\n\n## Why\n\nVibe coding from zero fails for two reasons: the model invents what nobody specified, and it builds before there's a machine that keeps the build consistent. AI Workflow answers both with a **fixed, ordered pipeline**. Each of the 8 stages consumes the versioned artifacts of the ones before it, so nothing downstream rests on a decision that was never made. The planning stages (1–6) write durable artifacts into the repo; stage 7 turns those artifacts into a living Claude Code harness; stage 8 builds the product inside that harness, deploy-first.\n\nThe skill is an **orchestrator**, not a code generator. It plans, delegates to specialized subagents, verifies, and — critically — **stops at human gates**. It never barrels through eight stages in one shot, and it never lets you parachute into a late stage while earlier ones are undone.\n\n## Two laws\n\n1. **State machine with human gates.** Almost every stage ends where a human must decide — the competitor list, the MVP cut, a brand direction, the stack, the providers. The skill *proposes, then stops and waits.* Each stage's Definition of Done is the gate to the next. Approvals are recorded in `docs/GATES.md`; an unrecorded gate is an unpassed gate.\n\n2. **Complete and continuous, no skipping.** The pipeline runs in order, fully. After a gate is approved it flows straight into the next stage — no re-summoning stage by stage. And if you ask it to jump ahead (e.g. *\"just scaffold the harness\"*) while earlier stages are missing, it names the gaps and steers you back to the earliest one instead of building on an empty base.\n\n## How it works\n\n| # | Stage | Produces | What happens |\n|---|-------|----------|--------------|\n| 1 | **Discovery** | `docs/discovery/` | Each competitor is its own **deep-research workflow** that fans out into many subagents — a 360° business panorama (9 dimensions) + a route-by-route map of the product. Consolidated into a `SUMMARY.md` of patterns, a competitor×feature matrix, and actionable opportunities. |\n| 2 | **Scope** | `docs/product/` | Agent-led brainstorming converges the product: value prop, JTBD personas, the MVP cut by Impact×Effort, success metrics, and a `PRD.md` of user stories + acceptance criteria. |\n| 3 | **Brand** | `docs/brand/` | Naming, voice \u0026 tone, a complete visual identity spec, and **W3C design tokens** (`design-tokens.json`) — stack-agnostic, ready to consume. Direction, not a generated logo. |\n| 4 | **Prototyping** | `docs/prototype/` | All MVP screens materialized in the best-fit tool (Figma, code, …), every relevant state covered, validated against the PRD. |\n| 5 | **Stack** | `docs/stack/` | Frontend, backend, data, auth, infra chosen per layer with justified trade-offs, plus the architecture: diagram + data model + folder structure + data flow. |\n| 6 | **Instrumentation** | `docs/instrumentation/` + `.env` | Every external service derived from features + stack, providers recommended with cost, provisioned via CLI or per-service runbooks, ending in a complete, working `.env` (gitignored) + documented `.env.example`. |\n| 7 | **Harness** | repo root + `.claude/` | The execution machine for *this* project: a lean `CLAUDE.md`, a 15-role agent team, slash commands, a versioned knowledge base, a code graph, tests + CI, and quality gates — green on a hello-world before it's done. |\n| 8 | **Vibe Coding** | the product | The Orchestrator distributes work to the team; each feature flows `spec → plan → build → verify` with gates; deploy-first, vertical slices, validated against success metrics. |\n\n### Core ideas\n\n- **Artifacts are contracts.** Every deliverable is the literal input to a later stage. All progress lives under `docs/`; `docs/STATE.md` is the heartbeat and `docs/GATES.md` is the approval ledger. Any new session reads them and knows exactly where the project is — close the terminal whenever you want.\n- **Orchestrator-first.** The lead never codes monolithically. It decomposes, delegates to subagents, verifies, integrates — from Discovery's nested fan-out to Vibe Coding's per-slice team.\n- **Lean context, rich knowledge.** The root context (`CLAUDE.md`) stays minimal; depth is pushed into the knowledge base, skills, and subagent prompts — the spine here, the depth in per-stage references.\n- **Triglot.** It converses in your language but writes every artifact in English, so the knowledge base stays portable.\n\n## Installation\n\n```bash\nnpx skills add oraphadev/ai-workflow --agent claude-code\n```\n\nWorks with any agent supported by the [Skills CLI](https://skills.sh/) — swap the `--agent` flag accordingly.\n\n## Usage\n\nStart a session in an empty project directory and say something like:\n\n```text\nTenho uma ideia: um app de gestão financeira pra MEIs no Brasil. Quero começar\ndo zero seguindo o workflow completo, do mercado ao MVP. Bora.\n```\n\nYou don't need to name the skill — *\"I have an idea for a Calendly competitor for barbershops, help me take it from market research to an MVP\"* triggers it too. You can also enter at a single stage (*\"just do a deep competitor research first\"*) — Discovery is the front door — and continue from there.\n\nThe skill then:\n\n1. **Locates the project.** Reads `docs/STATE.md` if it exists (and resumes), or scaffolds the planning tree + heartbeat for a zero project.\n2. **Runs one stage at a time**, delegating fan-out work to subagents and writing each deliverable into `docs/\u003cstage\u003e/`.\n3. **Stops at each gate**, presents the decision with a recommendation, records your approval, and flows into the next stage.\n\n### What it does — and deliberately doesn't — create\n\nThe zero-project bootstrap scaffolds **only** the planning structure: `docs/\u003cstage\u003e/` folders plus `docs/STATE.md` and `docs/GATES.md`. It does **not** generate the `.claude/` harness up front — that is stage 7's job, designed against the chosen stack and brand, not guessed. Empty templates would be false state; an artifact exists only once its stage produced it.\n\n## Recommended setup\n\nWorks with whatever the session provides, but shines with:\n\n- **Web access** (search/fetch or browser tooling) — Discovery refuses to research from model memory.\n- **Subagent / workflow support** — Discovery and the build run as parallel, sometimes nested, subagent fan-outs.\n- **Figma MCP** — for the Prototyping stage (and materializing the visual identity).\n- **A skill-discovery skill** (e.g. [find-skills](https://skills.sh/)) — each stage routes to specialized skills instead of hand-rolling.\n\n## Repository layout\n\n```\n.\n├── README.md                          ← you are here\n├── LICENSE                            ← MIT\n├── assets/\n│   ├── ai-workflow.excalidraw         ← editable diagram source\n│   └── ai-workflow.html               ← interactive, clickable pipeline\n└── skills/\n    └── ai-workflow/\n        ├── SKILL.md                   ← the conductor: state machine, gates, conventions, routing\n        ├── references/                ← 8 per-stage playbooks (read on entering each stage)\n        ├── assets/templates/          ← deliverable templates, the 15-role harness team, state files\n        └── scripts/                   ← scaffold_workflow.py (zero → docs/ + heartbeat)\n```\n\n## License\n\nMIT.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foraphadev%2Fai-workflow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foraphadev%2Fai-workflow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foraphadev%2Fai-workflow/lists"}