{"slug": "an-opinionated-ai-engineering-workflow-for-bmad", "title": "An opinionated AI engineering workflow for BMAD", "summary": "Hedgehog, a new AI engineering workflow from developer skyf0xx, enforces test-driven development and opinionated architecture to keep AI-generated codebases structured as they grow. The tool, installed via `npx @skyf0xx/hedgehog init`, supports Claude Code, Cursor, Gemini CLI, and other coding agents, encoding build order into the project so AI follows a proven path through layers like schema, contract, repository, service, controller, and UI. Hedgehog aims to prevent architecture drift by using small, verifiable steps and mechanical enforcement instead of relying on the model's memory.", "body_md": "AI can write code in seconds.\n\nBut as projects grow, context fills up, **architecture drifts**, and every new feature becomes harder to change safely.\n\nHedgehog gives AI a **disciplined way to build software**: TDD. Opinionated architecture. Small, verifiable steps.\n\nInstead of asking AI to remember your entire project, Hedgehog encodes the plan into the architecture and build process.\n\nThe codebase carries the context, not the model.\n\nHedgehog combines:\n\n**BMAD for planning**— turn an idea into a clear brief, requirements, and architecture** An opinionated stack**— remove unnecessary technical decisions, and settle the necessary ones once** TDD and progressive layering**— build one tested layer at a time** Mechanical enforcement**— use tooling and phase gates instead of trusting the AI to follow instructions** Small context loops**— keep every change focused, verifiable, and easy to review\n\nSoftware that stays structured as it grows.\n\n```\nPlan\n  ↓\nBootstrap\n  ↓\nBuild one small, tested layer\n  ↓\nVerify\n  ↓\nRepeat\n```\n\nThe build order is encoded into the project. The AI does not have to remember what comes next. It does not negotiate the architecture. It follows a proven path through the codebase.\n\nA fixed TypeScript stack with a backend-first, test-driven build order:\n\n```\nSchema\n  ↓\nContract\n  ↓\nRepository\n  ↓\nService\n  ↓\nController\n  ↓\nUI\n```\n\nEvery layer is verified before the next begins.\n\nA structured pipeline for producing distinctive, production-quality landing pages:\n\n```\nBrief\n  ↓\nFeeling\n  ↓\nDesign tokens\n  ↓\nSequence\n  ↓\nArtifact\n```\n\nA CLI, a library, a browser extension, a data pipeline, etc. fitting neither shape gets its own build order, designed at intake rather than chosen from a menu — starting from a [battle-tested blueprint](/skyf0xx/hedgehog/blob/master/src/skills/hedgehog-core-design/blueprints) for the system's shape where one exists.\n\nRun `init`\n\nwith no core flag: planning intake names the system shape, picks\nthe stack, derives the layers, and locks them to `.hedgehog/core.yaml`\n\n,\nthen generates that workspace and builds it one verified layer at a time.\n\nThe enforcement remains the same: ordered steps, scoped file access and a verification command per layer.\n\nFrom an empty project folder, run:\n\n```\n# Full-stack app\nnpx @skyf0xx/hedgehog init --ts-full-stack-app\n\n# Landing page\nnpx @skyf0xx/hedgehog init --landing-page\n\n# Anything else (CLI, library, browser extension, data pipeline, etc.)\nnpx @skyf0xx/hedgehog init\n```\n\nThen open your coding agent and describe what you want to build.\n\nHedgehog installs for **Claude Code** by default. Add a host flag to\ninstall for another one, or several at once:\n\n```\nnpx @skyf0xx/hedgehog init --cursor              # Cursor\nnpx @skyf0xx/hedgehog init --gemini              # Gemini CLI\nnpx @skyf0xx/hedgehog init --host=claude,cursor  # both\nnpx @skyf0xx/hedgehog init --all-hosts           # every supported agent\n```\n\nEach one gets the discipline in its own native shape — agents and skills\nin the directory it reads, and the instructions file it loads at session\nstart (`CLAUDE.md`\n\n, `HEDGEHOG.md`\n\n, or `GEMINI.md`\n\n).\n\nEvery install also writes ** AGENTS.md** at the repo root: an index of\nevery agent and skill, when each applies, and the build loop. Coding\nagents that read\n\n`AGENTS.md`\n\n— Codex, Copilot CLI, OpenCode, and others —\nwork from that index, following the same ordered steps and the same\n`hedgehog verify`\n\ngate.Plain `init`\n\n(no core flag) installs the agents, skills, and build graph\nthat every core shares. Planning intake designs an opinionated build\norder and stack for what you actually describe, then bootstrap generates\nthat workspace. Don't pick `--ts-full-stack-app`\n\nor `--landing-page`\n\nby\nelimination when neither actually fits.\n\nTo update:\n\n```\nnpx @skyf0xx/hedgehog update\n```\n\nThis refreshes the installed agents and skills — for every coding agent\nthe project was set up for — along with the `AGENTS.md`\n\nindex derived\nfrom them. It never touches the instructions file, the build graph, the\ncore workspace, or `skills/BMAD`\n\n, since those carry project-specific or\nwrite-once content.\n\nTo see the build graph:\n\n```\nnpx @skyf0xx/hedgehog graph\n```\n\nStarts a small local server and opens a live, read-only diagram of every task, status and its dependencies.\n\nMost AI coding tools improve prompting.\n\nHedgehog improves the **system AI builds inside**.\n\n| Raw AI | BMAD | Hedgehog | |\n|---|---|---|---|\nPlanning |\nConversation | Multi-agent workflow | BMAD |\nArchitecture |\nAI decides, drifts | Documented | Decided once, then enforced |\nBuild order |\nImprovised | Guided by docs | Mechanically enforced |\nContext |\nHeld in the prompt | Large planning documents | Encoded in the codebase |\nVerification |\nOptional | Process-dependent | Tests and phase gates |\nResult |\nFast code | Better plans | Reliable software |\n\nHedgehog uses a fixed stack and build order for each core. The tooling enforces architectural boundaries so correctness does not depend on the AI remembering instructions.\n\nSee [ARCHITECTURE.md](/skyf0xx/hedgehog/blob/master/ARCHITECTURE.md) for the full design.\n\nHedgehog uses [BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD)\n(`bmad-code-org/BMAD-METHOD`\n\n) for planning, MIT-licensed.\n\nThe `nx-generate`\n\n, `nx-run-tasks`\n\n, `nx-workspace`\n\n, and\n`link-workspace-packages`\n\nskills are adapted from\n[nx-ai-agents-config](https://github.com/nrwl/nx-ai-agents-config)\n(`nrwl/nx-ai-agents-config`\n\n) MIT-licensed, pinned to commit `9609810`\n\n(2026-07-23) and rewritten for Hedgehog's pnpm-only workspace convention.\n\n`front-end-eng`\n\n's animation skills (`skills/GSAP/`\n\n) are vendored from\n[gsap-skills](https://github.com/greensock/gsap-skills)\n(`greensock/gsap-skills`\n\n) MIT-licensed, pinned to commit `aed9cfd`\n\n(2026-07-27).\n\nIf Hedgehog helps you build better software with AI, give it a ⭐ on GitHub.", "url": "https://wpnews.pro/news/an-opinionated-ai-engineering-workflow-for-bmad", "canonical_source": "https://github.com/skyf0xx/hedgehog", "published_at": "2026-08-04 00:34:11+00:00", "updated_at": "2026-08-04 00:52:28.298063+00:00", "lang": "en", "topics": ["developer-tools", "ai-tools", "ai-agents"], "entities": ["Hedgehog", "skyf0xx", "Claude Code", "Cursor", "Gemini CLI"], "alternates": {"html": "https://wpnews.pro/news/an-opinionated-ai-engineering-workflow-for-bmad", "markdown": "https://wpnews.pro/news/an-opinionated-ai-engineering-workflow-for-bmad.md", "text": "https://wpnews.pro/news/an-opinionated-ai-engineering-workflow-for-bmad.txt", "jsonld": "https://wpnews.pro/news/an-opinionated-ai-engineering-workflow-for-bmad.jsonld"}}