🧬 Steroid-Workflow

AI coding guardrails that enforce a structured pipeline — so the AI can't cut corners, skip steps, or hallucinate solutions.

Steroid-Workflow wraps your AI coding assistant in an 8-phase pipeline with physical enforcement. Every idea flows through codebase scanning, specification, research, architecture, TDD implementation, and verification — producing enterprise-grade output with documentation, CI/CD, error handling, and deployment guidance.

The Problem

AI coding tools are powerful but unreliable. Without guardrails, they:

• Skip planning and jump straight to code
• Forget requirements halfway through
• Write fake tests that always pass
• Silently delete working code during refactors
• Produce weekend-hackathon quality output for production projects

Steroid-Workflow makes these failures physically impossible through git hooks, gate checks, and circuit breakers.

Quick Start

# 1. Inside any project with git init
npx steroid-workflow init

# 2. Tell your AI what to build
> "Build me a habit tracker like Apple Health"

# 3. The AI automatically follows the pipeline
#    If it doesn't, say: "Use the steroid pipeline."

No config. No dependencies. Works with any AI-powered IDE.

How It Works

graph LR
    A["📡 Scan"] --> B["🎯 Vibe Capture"]
    B --> C["📋 Specify"]
    C --> D["🔬 Research"]
    D --> E["🏗️ Architect"]
    E --> F["⚡ Engine"]
    F --> G["✅ Verify"]
    H["🔍 Diagnose"] -.-> F

    style A fill:#1e3a5f,color:#fff
    style B fill:#2d5a3d,color:#fff
    style C fill:#4a3d6b,color:#fff
    style D fill:#5a3d3d,color:#fff
    style E fill:#3d4a5a,color:#fff
    style F fill:#6b5a2d,color:#fff
    style G fill:#2d6b5a,color:#fff
    style H fill:#5a4a3d,color:#fff

| Phase | What Happens | Output | |-------|-------------|--------| | Scan | Detects tech stack, project structure, test infra | context.md | | Vibe Capture | Translates your idea into a structured brief | vibe.md | | Specify | Converts the brief into user stories with acceptance criteria | spec.md | | Research | Investigates tech choices, security, deployment, architecture | research.md | | Architect | Creates atomic execution plan with quality, docs, and deploy tasks | plan.md | | Engine | Builds using TDD, commits atomically, captures learnings | Working code | | Verify | Runs core verification by default, with optional deep scans for code smells and licenses | verify.md, verify.json | | Diagnose | Root cause analysis for bugs (fix intent only) | diagnosis.md |

Each phase hands off to the next. No manual intervention needed.

Smart Intent Routing

You don't need to tell the AI which pipeline to use — it detects your intent automatically:

| You Say | Pipeline | |---------|----------| | "Build a dashboard" | scan → vibe → spec → research → architect → engine → verify | | "Fix the login bug" | scan → diagnose → targeted fix → verify | | "Refactor the API" | scan → specify target state → architect → engine → verify | | "Upgrade to React 19" | scan → research → architect → engine → verify | | "Document the API" | scan → specify → engine → verify |

Prompt Intelligence

Before the workflow commits to a path, steroid-workflow can normalize messy user language into a structured brief:

• node steroid-run.cjs normalize-prompt "<message>" — infer intent, ambiguity, complexity, assumptions, and recommended route
• node steroid-run.cjs prompt-health "<message>" — score clarity, completeness, ambiguity, and risk
• node steroid-run.cjs session-detect — detect whether this looks like new work, continuation, or post-failure recovery

This helps with vague prompts, mixed prompts, non-technical phrasing, and continuation requests like "continue what we were doing yesterday."

Once written, .memory/changes/<feature>/prompt.json becomes the machine-readable receipt and .memory/changes/<feature>/prompt.md becomes the readable handoff brief. The later phases can preserve assumptions, non-goals, continuation context, and recommended route instead of forcing every model to reconstruct them from scratch.

What You Get

Your AI Can't Skip Steps

A git pre-commit hook blocks any code commit unless the AI went through the pipeline. IDE config injection ensures every AI model sees the rules first.

Errors Stop Before They Snowball

A 5-level circuit breaker tracks command failures. At level 1, the AI retries. By level 4, it stops and presents the error history for human review. At level 5, execution is halted entirely.

Proof Your Code Matches the Spec

A two-stage review system checks (1) whether the AI built what was requested and (2) whether it's well-built. Both stages must pass before core verification can succeed, and archive now depends on a machine-readable verification receipt.

Enterprise-Grade Output

Every project automatically includes:

• README, CHANGELOG, and deployment documentation
• Error boundaries, loading states, input validation
• Security considerations and dependency auditing
• CI/CD workflow (GitHub Actions)
• License audit (flags GPL/AGPL viral licenses)
• Code comments following explain-why-not-what standards

AI Safety Guardrails

Protections specifically designed for non-technical users:

• Adaptive Discussion — AI detects your technical level
• Prompt Intelligence — vague, mixed, and non-technical prompts are normalized into explicit assumptions, non-goals, and recommended routes
• Prompt Preservation — your exact requirements survive the entire pipeline
• Brownfield Detection — won't scaffold over your existing project
• Anti-Deletion Guard — can't silently remove working code
• True TDD Guard — fake tests like expect(true).toBe(true) are blocked
• Anti-Loop Directive — stops the AI from guessing the same broken fix repeatedly
• Optional Deep Verification — verify-feature --deep can run knip, madge, gitleaks, and license checks when you want extra scrutiny
• Command Allowlist — only known dev commands can execute through the circuit breaker

Language Support

| Language | Scan | Build | Lint | Test | |----------|------|-------|------|------| | JavaScript/TypeScript | ✅ | npm run build | eslint | npm test | | Python | ✅ | py_compile | flake8/ruff | pytest | | Rust | ✅ | cargo build | cargo clippy | cargo test | | Go | ✅ | go build | golangci-lint | go test | | Java/Kotlin | ✅ | mvn/gradle | checkstyle | mvn test | | Ruby | ✅ | — | rubocop | rspec | | PHP | ✅ | — | phpstan | phpunit | | C#/.NET | ✅ | dotnet build | — | dotnet test | | Dart/Flutter | ✅ | flutter build | dart analyze | flutter test |

Supported IDEs

Works with any AI-powered IDE or CLI:

| IDE | Config | |-----|--------| | Gemini CLI / Antigravity | GEMINI.md | | Cursor | .cursorrules | | Claude Code | CLAUDE.md | | OpenAI Codex | AGENTS.md | | GitHub Copilot | .github/copilot-instructions.md | | Windsurf | .windsurfrules | | Cline | .clinerules | | Aider | .agents/steroid-maestro.md |

All configs are auto-generated during install.

Update

npx steroid-workflow@latest update

Your project state (.memory/) is preserved. Only skills, configs, and enforcement layers are refreshed.

Verify Installation

node steroid-run.cjs audit

Checks all enforcement layers: git hook, 8 skills, 7 gates, circuit breaker, IDE configs, and knowledge stores.

For Power Users

See ARCHITECTURE.md for:

• Full command reference (22+ commands)
• Gate map and enforcement layer details
• Intent routing internals
• Prompt intelligence and adaptive route selection
• Memory system, review system, and analytics dashboard
• Fork credits and sources

License

MIT © nzkbuild