ACEF — Ayyildiz Context Engineering Framework

ACEF is a stack-agnostic SDLC operating system for AI-assisted software work.

It helps an AI agent understand your project first, route the work correctly, and run only the steps needed for that specific case. ACEF does not replace tools like BMAD, Kiro, GSD, OpenSpec, or spec-kit — it orchestrates them through the reality of your current project.

ACEF v2 Status

The v2 empirical matrix (72 runs: 12 seeded-defect tasks × 3 lanes × 2 clients, July 2026) updated both v1 claims — full write-up in docs/experiments/empirical-validation/report-v2.md:

• Token overhead fell in the v2 benchmark. After the worker short-circuit (scoped workers read only their compiled current context, never the ACEF references), ACEF lane overhead fell from +39%/+65% (v1, codex) to +20%/+24%; on opencode ACEF lanes in that experiment cost the same as or less than baseline. These results do not establish the cost of current Fix, Standard, or Full workflows, or attribute account-wide usage to an individual task.
• The v1 quality edge did not replicate. On a task set purpose-built to be lane-sensitive (scope bait, test-weakening bait, hidden findings, multi-file wiring, durable persistence, multi-system defects), every lane — including baseline — performed at ceiling with current-generation agents. ACEF is therefore not claimed to catch defects that strong agents miss on bounded single-step tasks.

What ACEF's process controls still offer is what method/CONTROL_RATIONALE.md always documented: auditable actor separation, scope fencing, durable evidence, and drift control for unattended, multi-session, or multi-worker delivery — a regime the current benchmark does not exercise. Measuring that regime (multi-step epic benchmarks) is the next validation frontier. The v2 evidence and treatment remain frozen; later control changes use a new versioned contract and experiment instead of rewriting that result.

ACEF still does not promote SQLite, vector, graph, SCIP, Serena, Codebase-Memory, or Context Mode-backed retrieval as defaults.

v3 — Slice lane (2026-10-20)

Status: merged to main, tag v3.0.0-alpha; capability record docs/ai/capabilities/slice-lane.json (specified). Full lane: method/SLICE_LANE.md.

What was measured. In b2press-rebuild (observations/ACEF_EVAL_REPORT.md, final verdict 2026-10-08), 7 slices ran under ACEF: all 7 PASS, one real defect caught (a flaky race test exposed by re-running the evidence on a clean tree), product quality equal to the native comparison runs, 1.7× developer tokens on the one slice with a direct token comparison (P03-LIST-01), and 162 friction items plus 70+ manual interventions. The owner retired the heavy flow for attended work there on 2026-10-07. Limits: one product, one team, one model family, small sample; escaped defects were not measured.

What the Slice lane keeps. Numbered acceptance items; an allowed-file list from a usage scan; a re-run of every claimed command on a clean tree before review; an independent reviewer in a separate session (another model family for money and migration slices); mutations (TAM: 3–5 per new or changed rule; HAFİF: one per behaviour change); real-browser evidence (1280 and 390 px) when the slice touches UI; a targeted re-review in the same reviewer session after REVISE; a closing note with fixed fields. What it drops: admission, typed run state, acef-state/acef-next, ledgers, preflight artifacts, and gate records.

For HAFİF, mutations are a reasoned N/A when no behaviour/rule changes; in any class, browser evidence is a reasoned N/A when the slice touches no UI (route, view, or component). The slice and dev report record the reason; the independent reviewer confirms it. TAM requirements remain intact.

Where it applies. The Slice lane is the default for attended single-team work. The v2 Fix/Standard/Full + Guarded lanes stay intact for unattended, multi-session, or multi-worker delivery. The Slice lane sits beside admission (owner decision 2026-10-20): no admission, typed approvals, acef-next model binding, or Fix counters. The v2 text is kept; where it names another default, a "Slice lane exception" sentence follows it (method/SLICE_LANE.md, "Reconciled v2 statements"), and /acef picks the Slice lane for attended work.

Planned for v0.2. A closing-note gate before merge; a fixed REVISE reason enum in review findings; a time/token header line in every review report. Four low-severity v0.1.2 items (R1–R4) are open.

Feedback, monitoring and product language (2026-10-27)

Added in v3.0.0-beta.4 to beta.7 on the owner's decision; details in CHANGELOG.md, rules in method/.

• Central feedback log (scripts/acef-note, store ~/CODE/acef-feedback, method/FEEDBACK_LOOP.md): every host writes observations as one-line entries; coordinators read at most five at intake, review brief and before shared infrastructure changes; acef-note version/check skip the log when nothing changed.
• Version check (scripts/acef-version-check --repo <host>): at session start a host learns it is behind and which CHANGELOG sections to read. Every framework PR adds a CHANGELOG entry (AGENTS.md "Changelog"); bundles are tagged.
• Updates keep host changes: the installers replace a file only if the host never changed it, and merge the model routing policy three-way.
• Waste detection during the day (scripts/acef-detect, scripts/detectors/): stuck agents, waiting work, idle or contended runners, review loops, forgotten sessions, inactive improvements and overrunning work raise alerts with an owner and a deadline in the coordinator's 15-minute loop. A failed source read never closes an alert.
• Weekly retro (scripts/acef-retro, method/WEEKLY_RETRO.md): numbers, repeats, overdue alerts and at most five numbered proposals; the owner answers by number.
• Product language (method/PRODUCT_LANGUAGE.md, templates/slice/user-profiles.md, templates/slice/user-goal-tour.md): screens are for the end user; evidence stays in reports; each host defines its users; user-goal tours are a pre-check, not real user testing. Pilot on one screen before rollout (docs/slice-lane/product-language-pilot.md).
• Model choice (method/MODEL_CHOICE.md): one class table (critical, standard, mechanical, light, browser tour, trivial lookup) for Claude and Codex agents, effort levels, and waiting rules; a project's own decision wins.

Core idea

Generic AI development frameworks are useful, but they fall short on real codebases because they don't know:

• the actual repo structure
• the safe patterns to copy
• the test and CI setup
• the risky areas
• the team's real conventions

ACEF is one package that unifies five layers — the actual delivery engine, not just an orchestration shell:

1. Operating model — personas, execution workflows (Fix / Standard / Full), assurance (Baseline / Guarded), and local implementation style (mechanical / standard). method/OPERATING_MODEL.md
2. Test & flow engine — real skills for user-flow → test-cases → tests, and bootstrapping the first test. method/TEST_PIPELINE.md + skills/
3. BMAD v2 heavy lane — the full story lifecycle for epics / risky work (drives BMAD-METHOD, with a hard installed-skill preflight). method/BMAD_V2_LANE.md
4. Codemap / project adapter — grounds everything in your real repo and extracts the pattern registry for conformance, including local generation docs, skills, stubs, and the registration/discoverability/runtime evidence that defines a complete work shape (evidence-pinned, no embeddings). skills/map-codebase + skills/acef-adapter
5. Delivery rules (the glue) — first choose repository-native vs ACEF; then choose ACEF Fix, Standard, or Full (BMAD v2) for execution depth; finally add Baseline or Guarded assurance independently from risk. method/DELIVERY_RULES.md

A front-door agent (acef) ties them together and routes each request, so the user never has to pick a layer, route, or skill.

For full BMAD work, the conductor/dispatcher is only the lifecycle coordinator. It must not author PRDs, UX specs, architecture, stories, code, tests, reviews, or done-state judgments itself. Each phase binds to a concrete worker persona, and a worker that wrote code cannot review, verify, or mark its own work done.

What's in this repo

method/      The delivery engine — how the work actually runs
  OPERATING_MODEL.md   personas + tracks (Layer 1)
  CONTEXT_RETRIEVAL.md optional bounded retrieval adapters and acef-query
  CONTEXT_POLICY.md    role-specific context budgets and worker input policy
  STATE_MACHINE_CONTEXT.md acef-next state-machine pushed context contract
  WORKFLOW_AS_CODE.md  minimal workflow YAML, artifact passing, and fresh-node context contract
  ACEF_COCKPIT.md      cockpit direction — v1 = read-only state viewer (compiler/proxy deferred, shell bought)
  TYPED_STATE.md       JSON sidecars for machine-readable ACEF state
  TRUST_MODEL.md       what ACEF guards do and do not guarantee
  CONTROL_RATIONALE.md why the sidecars, guards, evidence, approvals, and gates exist
  control-dosing.json  machine-readable lane/control dose manifest
  VALIDATION_PLAN.md   empirical thresholds before calling ACEF proven
  STABILIZATION_ROADMAP.md  phased plan for context diet, typed state, parser, evidence, and measurement
  docs/research/tooling-admission.md measured admission notes for future tools/backends
  TEST_PIPELINE.md     the test/flow skill chain (Layer 2)
  BMAD_V2_LANE.md      the heavy story lifecycle for epics (Layer 3)
  ADAPTER_MEMORY.md    snapshot vs adapter memory vs run ledger state
  PATTERN_REGISTRY.md  machine-readable conformance registry contract
  PRODUCT_RISK_MODEL.md domain-agnostic product risk / edge-case modeling method (documented-only)
  RULE_ENFORCEMENT_MAP.md  which rules are machinery/shard/JIT vs documentation-only
  DELIVERY_RULES.md    lane selection + promotion — the glue (Layer 5)
  SLICE_LANE.md        v3 default lane for attended single-team work (slice-method v0.1.1)
skills/      The ACEF agent skills you install into Claude Code
  acef/ acef-adapter/ acef-router/ acef-specify/ acef-test-bootstrap/ acef-release-adapter/   orchestration + adapter memory
  map-codebase/                                                          codemap + pattern registry / repo grounding (Layer 4)
  test-user-flow-mapper/ test-case-planner/ test-browser-generator/
  test-gen/ test-generator/ test-coverage-auditor/ test-strategy/ test-risk-classifier/
  flow-document-composer/ flow-suite-composer/ storymap/ bug-hunter/      test, flow, and review workhorses (Layer 2)
templates/slice/  Slice-lane templates copied into applications (slice, reports, review brief/checklist, closing note)
scripts/slice/    Slice-lane scripts: gate, standards ratchet, module boundaries, codex review, metrics, selfcheck + tests
docs/slice-lane/  Slice-lane source docs (Turkish): adoption, open questions, metrics demo, METHOD-01 reviews, SOURCES
schemas/slice-*.schema.json  slice-method.json project declaration and intervention log schemas
LICENSES/         Third-party licence texts for derived content (Cloudflare MIT for the TAM review annex)
archive/external-skills/  Non-ACEF third-party skill snapshots kept for reference only, not installed as ACEF skills
docs/        The developer-guide website (also published via GitHub Pages)
README.md
CHANGELOG.md Curated human-readable history of ACEF framework changes

Naming convention: acef-* skills are ACEF-specific orchestration/core skills. Unprefixed skills such as map-codebase, test-case-planner, and storymap are reusable workhorses that ACEF calls; they are intentionally not renamed because they can be used outside ACEF too.

Install & use

ACEF runs as a set of Claude Code skills — they're Markdown instruction files the agent follows. No build, no npm, no services.

1. Get Claude Code and a Claude account.

2. Install the skills — local-first is preferred. Copy the core ACEF skills into the repo you are working on:

   scripts/install-acef-skills --repo /path/to/your/repo
   scripts/install-acef-tools --repo /path/to/your/repo
   

   This installs the default local set for Claude, Codex, and OpenCode: acef, acef-adapter, acef-router, acef-test-bootstrap, map-codebase, and spec-readiness. For OpenCode, the same installer also writes repo-local slash command wrappers under .opencode/commands/ (/acef, /acef-adapter, /acef-router, /acef-test-bootstrap, /map-codebase). OpenCode skills live under .opencode/skills/, but slash commands are a separate .opencode/commands/*.md mechanism. The tools installer adds repo-local helper CLIs under .acef/bin/, including acef-status, acef-next, acef-workflow-validate, acef-process-validator, acef-codex-guard, acef-query, acef-context-experiment, acef-context-experiment-report, acef-context-actor-prompt, acef-context-actor-prompt-batch, acef-context-record-actor-report, and update-acef-installation. It also installs shared parser support under .acef/bin/lib/, typed-state schemas under .acef/schemas/, and the default control-dosing manifest under .acef/control-dosing.json. Every local install writes docs/ai/ACEF_INSTALLATION.json with the source checkout path, commit, branch, dirty/clean source state, installed components, and the update command. Use --tool codex|claude|opencode to target one tool, or --all-core to copy every skill in this repo. Optional measured review lenses such as bug-hunter and implementation-shape-review stay out of the minimal default install; add them explicitly:

   scripts/install-acef-skills --repo /path/to/your/repo --review-lenses
   

   Global install is still possible, but should stay minimal:

   cp -R skills/* ~/.claude/skills/
   

   Prefer repo-local .claude/skills/, , and for project-specific ACEF work.

Codex support

ACEF is tool-agnostic, so Codex can run the same method docs, ledgers, adapters, validators, and hook guard. Install the guard into the target repo, then install the global dispatcher once if Codex needs a PreToolUse entry:

scripts/install-acef-bmad-guard --repo /path/to/repo
scripts/install-acef-bmad-guard --repo /path/to/repo --global-dispatcher

Codex PreToolUse then checks exec_command, apply_patch, and file-write tools before they land, but only in repos that carry the local .acef/hooks/acef-bmad-hard-wall.mjs engine.

Use the CLI guard as the explicit certification/backstop before accepting worker output, before commits, or from a git hook/CI wrapper:

.acef/bin/acef-codex-guard --repo /path/to/repo --role worker --story 3.5 --base-ref HEAD

The Codex guard reads the same docs/ai/ACEF_ACTIVE_LEDGER and docs/ai/ACEF_ACTIVE_WORKER_SCOPE.json files as the Claude hook. It fails if a worker edits docs/ai/ACEF_*, changes files outside allowedPaths, exceeds maxCommits, or works under the wrong activeStory.

For practical Codex use:

1. Start an ACEF run normally and create the ledger + active ledger pointer.
2. Before dispatching an implementation worker, write docs/ai/ACEF_ACTIVE_WORKER_SCOPE.json.
3. Let the Codex PreToolUse guard block out-of-scope writes during the run.
4. After the worker returns, run .acef/bin/acef-codex-guard ... and the relevant .acef/bin/acef-process-validator checks before accepting the output.
5. For stronger enforcement, call .acef/bin/acef-codex-guard from a repo-local pre-commit hook.

Full BMAD also needs run-level delegation authorization. Record ## Delegation Authorization once in the ledger: delegation is approved only for ACEF-required persona workers, with one story/phase per worker, no worker-spawned subagents, no worker ledger edits, active worker scope before implementation writes, and final report then STOP. This satisfies tools that require explicit user authorization before spawning independent reviewers without turning delegation into a blank check.

OpenCode support

OpenCode can load ACEF's normal AGENTS.md rules and SKILL.md files directly. Its supported skill locations include .opencode/skills/<name>/SKILL.md, ~/.config/opencode/skills/<name>/SKILL.md, and Claude-compatible .claude/skills/<name>/SKILL.md / ~/.claude/skills/<name>/SKILL.md.

OpenCode slash commands are separate from skills. A skill can be available without /acef existing. Run scripts/install-acef-skills --repo <repo> --tool opencode to install both:

• .opencode/skills/<name>/SKILL.md for skill discovery;
• .opencode/commands/<name>.md for slash commands such as /acef.

Run the installer in the target repo to copy the ACEF guard plugin into .opencode/plugins/. The plugin adapts OpenCode's tool.execute.before event to the repo-local .acef/hooks/acef-bmad-hard-wall.mjs engine. It checks OpenCode write, edit, apply_patch, and bash calls before they land.

If you want one OpenCode user-level plugin for all repos, run the installer with --global-dispatcher; the global plugin still dispatches to each repo's local .acef/hooks engine.

OpenCode still needs the same ACEF run files as the other tools:

1. Create typed docs/ai/ACEF_ACTIVE_RUN.json or an ACEF-owned marker such as .acef-lightweight-lane or .acef-bmad-lane.
2. Set docs/ai/ACEF_ACTIVE_LEDGER.
3. For implementation workers, write docs/ai/ACEF_ACTIVE_WORKER_SCOPE.json.
4. Restart OpenCode after installing or updating the plugin.

The method/ docs are the engine the agent follows (personas, execution workflows, assurance, the test pipeline). Read them to understand how delivery actually runs; the agent applies them for you.

Lean runtime

ACEF defaults to lean reporting. Evidence remains durable on disk; chat gets compact summaries only:

• artifact path
• verdict
• key evidence command/path
• next allowed step
• decision needed from the human

Optional bounded retrieval is available through:

.acef/bin/acef-query context --repo /path/to/repo --story 5.2 --role developer

acef-query uses Context Mode when its CLI is available, but indexes only the active ledger, matching Epic Context Pack, current-context file, and matching story artifacts under a content-hashed source label. It falls back to a deterministic file slice when Context Mode is absent or fails. Context Mode remains optional: retrieval output is a candidate input, never a gate verdict or source of truth.

Measure retrieval modes before changing worker defaults:

.acef/bin/acef-context-experiment --repo /path/to/repo --story 5.2 --role reviewer --task-type review --mode files

The experiment compares controlled baseline, files, and context-mode modes and records JSONL metrics under docs/experiments/context-retrieval/runs/. Byte reduction is not billing proof; token/cost fields require client usage data.

Do not paste full PRDs, story specs, ledgers, broad rg output, or long logs into chat unless the user asks for detail.

The acef front-door skill is intentionally compact. It routes and names which reference files to load just-in-time; the detailed operating rules live in skills/acef/references/ and method/ so every run does not pay for the full method body upfront.

Process validators

ACEF ships a stack-agnostic process validator for cheap mechanical gates:

.acef/bin/acef-process-validator --repo /path/to/repo --check clean-tree
.acef/bin/acef-process-validator --repo /path/to/repo --check preflight
.acef/bin/acef-process-validator --repo /path/to/repo --check claims --ledger docs/ai/ACEF_feature_DELIVERY_AUDIT.md
.acef/bin/acef-process-validator --repo /path/to/repo --check adapter-freshness --adapter docs/codebase-map.md
.acef/bin/acef-process-validator --repo /path/to/repo --check pattern-registry
.acef/bin/acef-process-validator --repo /path/to/repo --check reuse-before-create --ledger docs/ai/ACEF_feature_DELIVERY_AUDIT.md
.acef/bin/acef-process-validator --repo /path/to/repo --check do-not-copy --ledger docs/ai/ACEF_feature_DELIVERY_AUDIT.md
.acef/bin/acef-process-validator --repo /path/to/repo --check partial-workshape --ledger docs/ai/ACEF_feature_DELIVERY_AUDIT.md
.acef/bin/acef-process-validator --repo /path/to/repo --check finding-promotion --ledger docs/ai/ACEF_feature_DELIVERY_AUDIT.md
.acef/bin/acef-process-validator --repo /path/to/repo --check graduation-reconciliation --ledger docs/ai/ACEF_feature_DELIVERY_AUDIT.md
.acef/bin/acef-process-validator --repo /path/to/repo --check vertical-slice --ledger docs/ai/ACEF_feature_DELIVERY_AUDIT.md
.acef/bin/acef-process-validator --repo /path/to/repo --check test-authenticity
.acef/bin/acef-process-validator --repo /path/to/repo --check guarded-test-floor --ledger docs/ai/ACEF_feature_DELIVERY_AUDIT.md
.acef/bin/acef-process-validator --repo /path/to/repo --check actor-separation --ledger docs/ai/ACEF_feature_DELIVERY_AUDIT.md
.acef/bin/acef-process-validator --repo /path/to/repo --check worker-scope --ledger docs/ai/ACEF_feature_DELIVERY_AUDIT.md
.acef/bin/acef-process-validator --repo /path/to/repo --check evidence-manifest --ledger docs/ai/ACEF_feature_DELIVERY_AUDIT.md
.acef/bin/acef-process-validator --repo /path/to/repo --check gate-verdict --ledger docs/ai/ACEF_feature_DELIVERY_AUDIT.md
.acef/bin/acef-process-validator --repo /path/to/repo --check source-reconciliation --ledger docs/ai/ACEF_feature_DELIVERY_AUDIT.md
.acef/bin/acef-process-validator --repo /path/to/repo --check epic-context-pack --ledger docs/ai/ACEF_feature_DELIVERY_AUDIT.md
.acef/bin/acef-process-validator --repo /path/to/repo --check current-context --ledger docs/ai/ACEF_feature_DELIVERY_AUDIT.md
.acef/bin/acef-process-validator --repo /path/to/repo --check capability-change
.acef/bin/acef-process-validator --repo /path/to/repo --check session-handoff --ledger docs/ai/ACEF_feature_DELIVERY_AUDIT.md
.acef/bin/acef-process-validator --repo /path/to/repo --check epic-boundary --ledger docs/ai/ACEF_feature_DELIVERY_AUDIT.md --target-epic 2
.acef/bin/acef-process-validator --repo /path/to/repo --check epic-transition-approval --ledger docs/ai/ACEF_feature_DELIVERY_AUDIT.md --target-epic 2

These checks are the first step in moving ACEF rules out of agent memory and into machinery. capability-change is the freshness check for ACEF itself: if an agent changes ACEF flows, gates, roles, checks, hooks, or enforcement, it must add a capability record that states whether the change is only documented or actually wired, enforced, proven, and installed. A method-doc edit alone must be reported as documented-only. Run clean-tree before certification, Process Judge, or external verifier handoff so a verifier never certifies commit N while the builder has uncommitted N+1 edits layered on top. The P1 conformance checks are deliberately mechanical: the registry must satisfy the contract, the ledger must record which local neighbor/probe was checked before creation, and do-not-copy entries cannot be cited as reusable patterns. The Claude Code guard hook also runs those P1 checks before implementation writes in active ACEF/BMAD lanes. The hook also enforces the worker scope fence: implementation workers cannot write outside their active story manifest, edit docs/ai/ACEF_*, spawn subagents, or commit without citing the active story. When an implementation write is blocked by a stale or mismatched active worker scope, the hook reports the active story, phase, worker id, allowed paths, requested path, and the recovery choice: close the stale lane marker/scope for a normal hotfix, or dispatch a worker whose identity and allowed paths match the task. When story tests depend on third-party framework APIs, run a grounding spike first and record the proven contract before ATDD. Green tests built on fake descriptors, vendor overrides, monkey patches, or test-only framework shims are not evidence; they are a REPLAN signal. When behavior depends on a runtime entrypoint, include a real-runtime smoke: hit the real HTTP route, command, queue, scheduler, CMS/admin runtime, or template path and assert meaningful content or a negative guard. Status-only checks and isolated helper/component tests do not prove the production path. Typed evidence and lightweight surface evidence must also carry runner-shaped command/exit metadata and runner proof. Plain prose logs, even with matching hashes, do not satisfy the evidence contract. When a story establishes the first reusable UI/runtime pattern for a surface, it needs a small round-trip proof through that surface before later stories reuse it. Reuse stories can stay lighter, but the first pattern must prove the real entry path, state change, reload/re-entry, and runtime output. UI-visible claims cannot close on non-UI evidence alone. When a story adds author-controlled input that should affect another surface, prove the binding with a non-default value: enter it through the real input surface, save/dispatch through the normal path, reload the consuming surface, and assert the authored value appears. Defaults, placeholders, stock images/data, mocks, and stale caches are masking risks; they must be explicitly rejected in the evidence. Run test-authenticity before story/epic close to reject warning-as-pass, silent catch/continue, self-referential assertions, and status-only runtime smoke.

Story close also requires canonical ledger evidence for ATDD ordering and actor separation: record the red-before-dev test artifact/commit, expected-fail command, observed red result, later implementation commit, and the actor identities for every phase that ran. Detailed reports can live elsewhere, but the ledger row must show the chain at a glance.

Developer prompts also enforce source comment hygiene: delivery evidence belongs in ACEF artifacts, while source comments only carry durable technical invariants. Story/Epic/AC/NFR labels, judge/reviewer language, and gate-pass explanations should not be written into production code. Every FR assigned to an epic must trace to an owning story and an exercised capability. A supporting artifact such as a form definition, model, seeder, or route file is not enough. Vertical-slice evidence uses source/path#probe and test/path#probe; the production source must contain the entrypoint probe and the test must contain the runtime probe plus an assertion. For PARTIAL registries, the ledger must declare track: and workShape:; uncovered or guarded work requires explicit human risk acceptance. For P2 self-hardening, each ledgered Conformance finding: must record a Disposition:: patch, registry update, do-not-copy update, mechanical check, or explicit human deferral/risk acceptance. If a disposition promises graduation to registry/do-not-copy/mechanical enforcement, it must also record Reconciled: with an existing file path or enforcedBy: value. For session continuity, every active delivery ledger must include ## Session Handoff with current step, last passed gate, next allowed step, active lane/track, and ledger path. Guarded or blocked handoffs must state what not to continue without.

Quick verify:

node scripts/test-acef-process-validator
node scripts/test-acef-control-dosing
node .acef/bin/acef-process-validator --repo . --check clean-tree
node scripts/smoke-acef-hook-active-ledger
node scripts/smoke-acef-opencode-plugin

GitHub Actions runs the regression test from .github/workflows/validate.yml.

Current capstone review: docs/capstone-review-2026-06-21.md. Typed-state real-project evidence: docs/dogfood-typed-state-detaysoft-2026-06-23.md.

Dependency: BMAD (large-feature flow only)

For the large-feature route (Route B), ACEF uses BMAD-METHOD (MIT) as the heavy delivery engine. BMAD is not bundled here; install/wire it separately if you need Route B. Every other route works without it.

Route B starts with a hard preflight. ACEF must resolve the real BMAD conductor/skills or commands before it proceeds. If BMAD is missing, ACEF must stop and ask you to install/wire it or choose a different lane. A generic subagent running a BMAD-like checklist is not BMAD.

Route B also requires actor separation. New four-actor-v3 stories record distinct ATDD, Development, Code Review, and Patch Assurance actors; close is deterministic and a Story Process Judge runs only for a waiver, evidence conflict, ambiguity, or gate anomaly. Existing six-actor-v2 runs retain their separate Verify-Patch, Test Review, and Story Process Judge records. A generic worker is invalid unless explicitly bound to a BMAD/ACEF persona in artifact evidence.

Route B also requires seeded epic gates. When epics/stories are generated, every epic gets an Epic N Process Judge [PENDING] row or artifact before implementation starts. The last story in an epic points to that gate, and the next epic cannot start until the prior epic gate is PASS.

Process gates

ACEF separates implementation review from process review:

• Parent-objective supervisor binds every new installed run to a stable objective/scope fingerprint. It consolidates at 5 runs, 3 replans, 6 review cycles, or 30 active control minutes without product progress, and refuses an eighth run or fifth replan. Manual-QA findings enter one typed ledger instead of recursively opening review lifecycles. New Fix/Standard objectives use versioned no-progress accounting: validated successful deliveries reset churn, while lifetime totals remain visible. Full and existing objectives retain v1 accounting.

• Worktree freshness handshake refuses new admitted work when the installed runtime or its recorded ACEF source digest changed. Refresh every linked worktree with scripts/update-acef-installation --repo /path/to/repo --all-worktrees.

• Preflight artifact (docs/ai/ACEF_PREFLIGHT.md by default) is required before admitted ACEF planning, implementation, test generation, release, or done-state changes. It records route/lane/track, required skills, resolved paths, adapter freshness, test setup, API/backend source of truth, risk gates, approvals, and a PASS / FAIL / HALT verdict.

• Judge reviews the change and returns MERGE / REVISE / REPLAN.

• Process Judge verifies that the required workflow, assurance profile, skills, phase order, and artifacts were actually used. It is mandatory at epic close and conditional at four-actor-v3 story close; legacy six-actor-v2 story gates remain actor-decided.

• Actor separation is part of the gate: new four-actor-v3 story evidence records distinct ATDD, Developer, Code Review, and Patch Assurance actors plus any conditional Story Process Judge. Existing six-actor-v2 stories retain Verify-Patch, Test Review, and Story Process Judge records. Self-review is invalid on Full work and cannot be waived by Guarded assurance.

• Epic Process Judge verifies epic closeout gates before an epic is product-done: drift audit when needed, trace, epic test-review, E2E/user-flow evidence, manual QA ledger, product-done audit, retrospective, and final status close. If the epic contains UI/user-facing claims, it needs at least one representative E2E/browser/screen flow at epic close.

• Epic boundary is mechanical: continue without me may skip waiting for a human checkpoint, but it never skips the seeded Epic Process Judge gate. Starting Epic N+1 also requires explicit with an exact human quote naming the target epic; generic continuation phrases (, , , ) are not valid transition approval.

A workflow claim is invalid unless the required skill exists, was invoked, and left evidence on disk. Subagent output is a lead, not gate evidence, until the conductor verifies the backing source path, command, or artifact.

Honest status

This is a research-informed draft:

• the developer-guide website is ready
• the agent skills exist as draft definitions and have been only lightly exercised
• the agent skills and workhorse skills exist as draft definitions and have been only lightly exercised
• real-world dogfooding on your own repo is still required before treating any route as proven

Treat ACEF as a framework to apply and harden on your codebase, not a finished, battle-tested product.

Website

The site lives in docs/ and is published with GitHub Pages (Source: main, Folder: /docs).

License

License not selected yet. BMAD-METHOD, referenced as an optional dependency, is MIT-licensed and not redistributed here. LICENSES/ holds third-party licence texts for derived content only (Cloudflare MIT for the Slice lane's TAM review annex in templates/slice/review-brief.md); it does not select a licence for ACEF itself.