A · Small feature
Brief / route→Golden neighbor→Implement→Review
Use this when the change is small, local, and already matches an existing pattern.
The process
SDLC & Frameworks
ACEF doesn't invent a new lifecycle. It overlays the normal SDLC, then orchestrates the frameworks you already use — BMAD v2, Kiro, spec-kit, GSD, OpenSpec — through your project's real adapter, running only the phases a given request needs.
🗺️The shape
This guide starts at the first brief. Once the work is framed, ACEF routes into the SDLC phases below and only runs the parts that matter for that request.
1 Brief / Route→
2 Requirements→
3 Design→
4 Planning→
5 Implement→
6 Review/Test/CI→
7 Release→
8 Feedback
ℹ️
Most requests touch only a few of these. A bug fix
skips 2–4 entirely; a small feature skips heavy requirements/design. The router decides which phases run.
⚙️Delivery model
ACEF runs one of two lanes, then applies process gates before anything is marked done.
| Lane | Use when | Gate |
|---|---|---|
| Lightweight | Small, scoped, ongoing work | Planner / Developer / Judge, with mechanical · standard · guarded tracks |
| Full BMAD v2 | Epics, large features, core behavior, multi-module, or risky-and-large work | Real BMAD conductor/skills must resolve, and each phase must bind to a separate worker persona |
Preflight + Story Judge
ACEF_PREFLIGHT.md must PASS before planning or implementation. Before a story/task is done, verify route, lane, track, skill paths, phase order, artifacts, and evidence.
Epic Process Judge
Before epic close, verify drift audit, trace, epic test-review, E2E/user-flow evidence, manual QA ledger, product-done audit, retrospective, and status close.
Surface-realism
When a story creates the first reusable UI/runtime pattern, it needs a round-trip proof through the real surface before other stories reuse it. UI epics need representative E2E at close.
Test cases first
For risky/large work, user flows become test cases before automation and before final story slicing.
Separation of powers
The conductor routes the lifecycle. Test Author, Developer, Code Reviewer, Verify-Patch Reviewer, Test Reviewer, and Process Judge are separate actors. A worker cannot approve its own output.
Typed gate evidence
acef-state records each actor and worker scope, captures command output with a hash, and requires Process Judge PASS to cite successful evidence. Epic transitions use an exact hashed human approval quote.
Seeded epic gates
Epics/stories generation creates every Epic N Process Judge [PENDING] row up front. The next epic cannot start until the prior epic gate is PASS.
Architecture conformance
Before epics/stories, an independent Architect or Process Judge checks codemap use, golden-neighbor claims, source discrepancies, counts, and do-not-copy entries. Findings need a ledger disposition before stories start.
Accelerated cadence
Independent, non-overlapping stories may run in parallel, workers must return complete final reports inline, and low-risk work can use lighter review tiers. Guarded/security/routing/storage work keeps full separation.
Lean runtime
Evidence stays on disk. Chat reports path, verdict, key evidence, and next step; no full artifact or broad search dumps by default.
🔢The 8 phases
1 · Brief & Routeentry
Take the brief, classify it into a route, and detect risk. Greenfield vs brownfield is a deterministic check, not a question.
Frameworks: ACEF router · BMAD scale levels (idea)
2 · Requirementswhat to build
User-facing behavior + acceptance criteria, with traceable IDs. Imported if a tool already produced them.
Frameworks: BMAD PRD · Kiro requirements (EARS) · spec-kit FR/US/SC IDs
3 · Designhow to build it
Architecture, data flow, contracts, affected modules, risks.
Frameworks: BMAD architecture · Kiro design
4 · Planningbreak it down
Story map → epics → user stories → tasks, each traced back to a requirement.
Frameworks: BMAD stories/tasks · storymap · OpenSpec deltas (brownfield)
5 · Implementbuild
Follow the repo's golden neighbor — but ground it at the symbol level, not the file level: diff the target's real signatures and return shapes against the neighbor's before reusing, so a verbatim copy can't ship a type error. Minimal, code-grounded change per task.
Frameworks: your project's own build skills, via the adapter
6 · Review / Test / CIverify
Review against the repo's standard; bootstrap a test pattern if none exists; run the gate.
Frameworks: your test stack (detected) · review skills
7 · Release / CDship
Readiness checklist, staged rollout, rollback — from the repo's real workflows.
Frameworks: your CI/CD, surfaced via the release adapter
8 · Feedbacklearn
What went wrong / what to change → update the rule or checklist. No metric ceremony unless asked.
Frameworks: lessons / retro
🅱️BMAD v2 in detail
BMAD v2 is itself a full pipeline (Analysis → Planning → Solutioning → Implementation) with agent personas. ACEF uses BMAD as the large-feature heavy lane and imports its output — it never regenerates what BMAD already produced.
⚠️
Real BMAD only: Route B starts with a
capability preflight. The conductor and required BMAD skills/commands must resolve to real paths. If they
do not, ACEF halts instead of running a BMAD-like generic-subagent imitation. Fallback to non-BMAD guarded
work requires explicit human approval.
🧱
Actor separation: a full BMAD story
is invalid unless its evidence records the ATDD actor, Developer actor, Code Review actor, Verify-Patch
actor, Test Review actor, and Process Judge actor. Generic subagents are not enough; each worker must be
bound to a valid persona. Guarded stories cannot use self-review.
🔒
Optional hard wall: Claude Code, Codex, and OpenCode users can
install
claude-plugins/acef-bmad-guard/ or run scripts/install-acef-bmad-guard --repo /path/to/repo.
The full guard is repo-local under .acef/hooks/; Claude Code and Codex can use the optional
--global-dispatcher shim to find that local hook.
When an ACEF lane marker is present, the hook blocks the dispatcher/conductor from writing BMAD artifacts or
implementation files while allowing dedicated persona workers. It also blocks Epic N+1 story-start commands
until Epic N Process Judge is PASS.| BMAD produces | ACEF maps it to |
|---|---|
| PRD (functional / non-functional requirements) | requirements.md |
| Architecture document | design.md |
| Epics / stories / tasks | tasks.md |
| Readiness report | Definition-of-Ready evidence |
⚠️
BMAD also has its own brief/research/analysis phase, which
overlaps ACEF's front. Rule of thumb: generate once. If BMAD already made the spec,
ACEF imports + enriches it (risk, DoR, test cases, golden neighbor, traceability) — it does not run a second
pipeline. On small or quick work, BMAD is skipped entirely.
🔌Where each framework plugs in
ACEF orchestrates; it doesn't force you to use all of these. You use what your project already has, and ACEF imports the output through the adapter into one canonical format.
| Framework | Plugs into | What ACEF takes |
|---|---|---|
| BMAD v2 | Phases 2–4 (large feature) | PRD→requirements, architecture→design, stories→tasks; import, don't regenerate |
| Kiro | Phases 2–4 (spec format) | the 3-file requirements/design/tasks shape + EARS acceptance criteria |
| GitHub spec-kit | Phases 2–4 (traceability) | FR-###/US#/SC-### IDs + tasks tagged to stories |
| OpenSpec | Phase 4 (brownfield currency) | ADDED/MODIFIED/REMOVED deltas that keep living specs current |
| GSD | Phase 1 / onboarding | orientation + codebase mapping |
The differentiator vs any single tool: ACEF binds all of them to your extracted adapter (per-repo, evidence-based) and runs them behind one agent — no ceremony, no double work.
🚦Routes vs phases
A route is just a subset of phases. This is why "every job goes through all 8 phases" is false.
| Route | Phases it runs |
|---|---|
| A · Small feature | 1 → 5 → 6 (skip 2–4) |
| B · Large feature | 1 → 2 → 3 → 4 → 5 → 6 |
| C · Bug fix | 1 → 5 → 6 (root-cause first) |
| D · Test cases | 2 (flows→AC) → 6 |
| E · Test automation | 6 (bootstrap first) |
| F · Unit / integration | 6 |
🧩Route drawings
Same routes, but spelled out. Each card shows the shortest useful path for that job.
B · Large feature
Brief / route→Requirements→Design→Planning→Implement→Review
Use this when scope is larger, a new contract appears, or multiple modules are affected.
C · Bug fix
Brief / route→Reproduce→Root cause→Fix→Review
Use this when the job is about restoring behavior, not adding a new feature shape.
D · Test cases
Brief / route→Flows→Acceptance criteria→Test cases→Review
Use this when the output is a test plan or structured cases before automation.
E · Test automation
Brief / route→Detect stack→Bootstrap 1 test→Approve pattern→Expand
Use this when the project needs the first real test pattern before broader automation can scale.
F · Unit / integration
Brief / route→Detect stack→Unit / integration→Run gate
Use this when the job is about test coverage in the project’s actual framework and command set.