@brad-frost-web/bfw-process

The Brad Frost Web Software Creation Process — encoded, portable, and agent-ready.

bfw-process drops BFW's software creation rules, phase gates, and Eddie-first discipline into any project in one command. Any AI coding agent — Claude Code, OpenHands, Cursor, Cline, or anything that reads AGENTS.md — automatically loads BFW's rules on the first turn of every session.

Stop re-explaining the process. Install it instead.

What you get

Running bfw-process init in a project adds:

• AGENTS.md — the universal, cross-agent source of truth (core principles, always-on rules, phase structure)
• CLAUDE.md — a Claude Code-compatible mirror of AGENTS.md
• .microagents/ — always-on + keyword-triggered microagents (repo.md, eddie.md, eleventy.md, nuxt.md, accessibility.md, testing.md)
• SPEC.md — a starter spec file (Phase 2 template, status: draft)
• .bfw-process/ — phase definitions, checklists, the verify-phase script, and your project's config (mode, owners, project type)

Everything is markdown. Everything is readable. No runtime, no daemon, no magic.

Two modes

BFW projects happen in two very different contexts, and bfw-process treats both as first-class.

Full mode (default)

The six-phase gauntlet from the BFW Software Creation Process. Spec before build, phase gates enforced, tests written alongside code, ship-readiness checked before deploy.

npx @brad-frost-web/bfw-process init

Quick mode

For teaching, podcasting, live-coding, and prototyping — when speed and immediacy matter more than rigor. Phase gates are skipped. SPEC.md is optional. Ship-readiness checks are off. Eddie-first, design-tokens-only, and WCAG AA semantic baseline remain on even in quick mode, because they're muscle memory and cheap.

npx @brad-frost-web/bfw-process init --mode=quick

Promoting Quick to Full

After a teaching call or a demo, if the quick-mode code is actually worth shipping:

bfw-process mode full

…or simply tell the agent "do it for real now" in a session. The agent will generate a SPEC.md from the existing code, stop at the Phase 2 gate, and walk the project back through the Full-mode flow as refinement rather than a rewrite.

The hard gate

Phase 5 → Phase 6 (ship-readiness → deploy) is the one hard gate. Everything else is soft — checklists the agent reads. Ship-readiness runs real checks and exits non-zero on failure:

• Unit tests pass
• Automated a11y audit clean (axe or equivalent)
• Responsive spot-check
• Each spec user flow verified
• Lighthouse regression check

Projects scaffolded with bfw-process init expose the gate as an npm script:

npm run bfw:ship

That's the canonical invocation — it uses the pinned version in devDependencies, so CI and collaborators hit the same checks. npx bfw-process verify-phase ship still works, but it re-resolves from the registry each time.

Owner bypass

BFW core members (currently Brad Frost and Ian Frost by default) can bypass the ship gate in emergencies:

BFW_OWNER_OVERRIDE=1 npm run bfw:ship

The bypass requires the current git user.email to match an entry in .bfw-process/config.json's owners array. Non-owners get no bypass path. Every bypass is logged to .bfw-process/overrides.log with timestamp, user, and which checks were skipped.

Add additional owners per-project by editing config.json.

Installing into a project

npm (preferred)

# In an existing project
npm install --save-dev @brad-frost-web/bfw-process
npx bfw-process init

init pins @brad-frost-web/bfw-process in the project's devDependencies at the currently-installed version (exact, no caret) and adds an npm run bfw:ship script that runs the Phase 5 hard gate. Pinning is what makes the process reproducible: CI and every collaborator resolve to the same version, and a project audited today can replay its audit later against the same rules.

You can also one-shot without a prior install:

npx @brad-frost-web/bfw-process init

…but still run npm install afterward so the pin in package.json is materialized in node_modules.

Git submodule (for non-Node projects)

git submodule add https://github.com/Brad-Frost-Web/bfw-process.git .bfw-process-src
./.bfw-process-src/scripts/bootstrap.sh

The submodule path doesn't touch package.json (non-Node projects typically don't have one). If your project does have a package.json, prefer the npm path so the process version is pinned alongside your other dependencies.

CLI reference

bfw-process init [--mode=full|quick] [--type=content-site|app|recipe|script] [--yes] [--force]
bfw-process sync                    update generated files, preserve SPEC.md + config.json
bfw-process mode [full|quick]       show or set current mode
bfw-process verify-phase <phase>    run checklist; phase = scope|spec|build|ship
                                    (refused on design/* branches — use design promote first)
bfw-process design promote          archive current design branch, draft SPEC.md, file feature issue
                                    [--dry-run] [--yes] [--force] [--no-push]

Design branches

BFW projects support a sketch-first branch type for exploratory work — the first half of the double diamond. See AGENTS.md §5.3 for the full contract. The short version:

# Open an exploration issue (use the "Design exploration" template), then:
gh issue develop <N> --checkout --name design/<N>-<slug>

# Sketch freely. Eddie is the default; the agent will ask one confirming question
# when invited to "color outside the lines". a11y baseline stays on always.
# SPEC.md is NOT required while sketching. `npm run bfw:ship` will refuse on a design/* branch.

# When the exploration is ready to become production work:
bfw-process design promote

design promote validates the branch, creates an archive/design-<N>-<slug> tag at HEAD, pushes it to origin, generates or amends SPEC.md (status: draft), and files a parent feature issue tracking the production implementation. The design branch is never merged — fresh feature/* branches off develop carry the production work.

Updating a consuming project

When BFW publishes a new version of the process:

npm install --save-dev @brad-frost-web/bfw-process@latest
npx bfw-process sync

sync refreshes the generated files (AGENTS.md, microagents, phase docs, checklists) and bumps the pinned version in package.json to match the running bfw-process version. Your SPEC.md, CLAUDE.md, and config.json are left untouched.

npm update alone won't move the pin — the devDep is pinned exactly, not as a range. Use npm install --save-dev ...@latest (or @<version>) to change the pin.

Authoring this package

This repo self-hosts: it uses its own process on itself. See SPEC.md for the Phase 2 spec and .bfw-process/config.json for its own configuration. Contributions and amendments require review from at least one co-owner.

License

MIT © Brad Frost Web LLC — Brad Frost, Ian Frost