Ayyildiz Context Engineering Framework

ACEF Developer Guide

A practical guide for developers who will use ACEF on a real codebase — a stack-agnostic way to let an AI agent understand your project first, route the work correctly, and run only the steps that case needs. For the full process see SDLC & frameworks; for role-specific use see Roles.

🧭What ACEF is

ACEF is not a code generator and not a second methodology. It is a thin layer that makes AI-assisted work fit your repo, doing three things:

Extract

Reads a project adapter from the repo — stack, commands, CI, tests, golden examples, risky areas — from evidence, not guesses.

Route

Classifies each request and runs only the SDLC steps that case needs. No ceremony.

Orchestrate

Drives existing tools (BMAD, Kiro, spec-kit, GSD, your own skills) through that adapter, behind one front-door agent.

🎯

Grounding rule: a golden neighbor is only qualified when the consumed symbol, hook, signature, or contract also matches. File-level similarity is not enough.

🧱

BMAD actor rule: in the full BMAD lane, the conductor/dispatcher coordinates only. PRD, UX, architecture, stories, ATDD, development, code review, verify-patch, test review, and Process Judge must be performed by concrete worker personas. A worker cannot review or mark done its own output.

💬How to use it

You don't pick routes, phases, or skills. You talk to the acef agent in plain language and it drives the rest:

You

I want to add a notifications screen to this app.

ACEF

Brownfield, small feature. I'll copy the screen pattern your repo already uses, implement, then review. Which area is the entry point — anything special?

You

Write tests for this service — there are none yet.

ACEF

No test pattern here yet. First I'll set up one example test in your stack and get your approval — that becomes the pattern. Then we expand. OK?

Replies are short by default (one step at a time). Ask for more depth anytime:

detail → the route's purpose, inputs/outputs, why, risks
how → which skills, adapter values, and files will run
teach → explains the ACEF concept with an example

🚦Routes — which one, when

The agent classifies your intent into one route and runs only its steps. You don't choose this — it's here so you understand what it's doing.

A · Small feature

localized, follows an existing pattern

Short brief → golden neighbor → implement → review.

B · Large feature

multi-module, new pattern, or touches data/auth/payment

Requirements → design → planning → build per task → review.

C · Bug fix

correct known broken behavior

Reproduce → root cause → minimal fix → regression test → review.

D · Test cases

produce test cases from the product

Flows → acceptance criteria → test cases.

E · Test automation

repo needs its first automation

Inspect tests → bootstrap one approved test → automate a flow.

F · Unit / integration

add coverage to a module

Find pattern (or bootstrap) → focused tests → run.

⬆️

Escalation rule: if the request is ambiguous, low-confidence, or touches a risk area (auth, payment, migration, contract, multi-repo), the agent moves up a route — never down — and asks at most a couple of yes/no questions.

🔍Onboarding a repo

The first time ACEF touches a repo it extracts the project adapter (read-only). Everything else relies on it.

acef-adapter  →  {project}-adapter.md

Captures (each field cites a source path):
  identity / lifecycle · stack + package manager · layout · real commands
  (build / test / lint / typecheck) · test setup · CI/CD · golden neighbors
  pattern registry · do-not-copy · reuse probes · risk surface
  local generation docs / skills / stubs · completion evidence
  (structure · registration · discoverability · runtime)
  + freshness stamp (generated_at · commit · scope covered)

The adapter separates three memories: the codemap snapshot (what the repo looks like), adapter living-knowledge (patterns, golden neighbors, do-not-copy, risk boundaries), and the delivery ledger (one run's gate summaries, drift notes, and next allowed step).

Living entries carry source evidence, confidence, freshness, maturity, and an update trigger. Soft rules should graduate into mechanical checks and then retire from prose.

pattern-registry.json entries also carry evidence, lastVerifiedCommit, and enforcedBy. PARTIAL registries permit only covered mechanical/standard work shapes; guarded work needs extraction or explicit risk acceptance.

The process validator now checks registry contract shape, reuse-before-create evidence, do-not-copy misuse, partial work-shape permission, finding promotion, graduation reconciliation, session handoff, clean-tree, epic gates, claimed outputs, adapter freshness, and REPLAN count.

The guard hook also runs the reuse/do-not-copy/PARTIAL checks before implementation writes in active ACEF/BMAD lanes, so workers cannot skip the conformance ledger under context pressure.

Lean runtime is the default: evidence stays in artifacts on disk; chat reports only path, verdict, key evidence, and next step unless the user asks for detail.

The append-only ledger remains authoritative, but ordinary story workers consume a role-specific ACEF_CURRENT_CONTEXT.md hot slice capped at 150 lines. Story Process Judge receives a compact story slice; only Epic Process Judge reads the full ledger.

acef-query context can supply bounded source material for that hot slice. It uses Context Mode when available and a deterministic file fallback otherwise; retrieval is optional and cannot satisfy a gate.

acef-context-experiment measures baseline, file fallback, and Context Mode retrieval with JSONL metrics before ACEF changes worker defaults. Byte reduction is treated as a lead, not billing proof.

Future tooling is gated by measured admission. Symbol search, graph memory, structural rule engines, MCP runtime controls, and eval frameworks stay candidates until ACEF records a real gap they solve.

The acef front-door skill is compact and loads detailed reference files just-in-time, so routine runs do not pay for the full method body upfront.

An ACEF run must bootstrap its target state before worker fan-out: create docs/ai/, create the delivery ledger, set ACEF_ACTIVE_LEDGER or docs/ai/ACEF_ACTIVE_LEDGER, and write a complete Session Handoff. Source repos are evidence; the target repo owns the run gates.

Full BMAD ledgers also record Delegation Authorization once per run. It permits only ACEF-required persona workers, not open-ended subagent delegation.

If multiple delivery ledgers exist, set ACEF_ACTIVE_LEDGER or docs/ai/ACEF_ACTIVE_LEDGER. Without an active pointer, implementation writes are denied rather than satisfied by stale ledger evidence.

For PARTIAL registries, the ledger must declare track: and workShape:; guarded or uncovered work needs explicit human risk acceptance.

Freshness stamps point to the commit where evidence was verified. A committed registry remains fresh only when that commit is reachable from HEAD and no covered source paths changed since.

It does not install, write tests, or change code. It reads manifests, lock files, CI workflows, and the directory tree — no embeddings, no guessing. Re-run only when it goes stale (big refactor, new module, dependency or contract change), not for every task.

ℹ️

Per-repo, not per-stack: even if two repos both look like “web”, ACEF still extracts each repo’s own stack, test setup, CI, and golden neighbors separately.

🛠️Task how-to

Small feature

Adapter must be fresh → the agent picks a qualified golden neighbor → copies its pattern → review. No heavy spec/design.

Large feature

acef-specify starts with real BMAD preflight. If BMAD resolves, ACEF imports its PRD/architecture/stories output; if it does not, ACEF halts instead of imitating BMAD with generic subagents.

Bug fix

Give expected vs actual + a repro. The agent finds root cause, makes the minimal fix matching local style, adds a regression test.

Tests (none yet)

acef-test-bootstrap detects the framework from evidence (or proposes the stack default and asks), writes one idiomatic test, runs it, and gets your approval — that becomes the golden test.

Release

acef-release-adapter builds a readiness checklist from the repo's real workflows: staged rollout, rollback, changelog — and flags deploy-only workflows that aren't real test gates.

⚙️Delivery engine

The repo ships more than the front-door agent. The engine is in method/ and the agent reads mirrored copies from skills/acef/references/.

Operating model

Planner, Developer, Judge, Test Author, Documentation Maintainer, plus mechanical/standard/guarded tracks.

Four lanes

quick-fix, lightweight, full-bmad, and guarded each have mechanical lane selection and closeout bundles.

Adapter memory

Codemap snapshot, adapter living-knowledge, and run ledger stay separate so repo memory stays grounded and small.

Conformance loop

Reuse-before-create runs in both lanes; every conformance finding becomes a patch, registry update, do-not-copy update, mechanical-check proposal, or human deferral.

Architecture conformance

Before epics/stories, an independent gate checks adapter/codemap evidence, golden-neighbor claims, source discrepancies, counts/inventories, do-not-copy entries, and deliberate divergences. Findings must be revised, accepted, spiked, turned into story AC, or promoted to registry/mechanical checks.

Rule enforcement

Method prose is not enforcement. Load-bearing rules move to machinery, fresh sharded workers, or just-in-time injection.

Process validator

scripts/acef-process-validator checks clean-tree certification state, preflight PASS, claimed output paths, adapter freshness, registry shape, reuse-before-create, do-not-copy misuse, partial work-shape permission, finding promotion, graduation reconciliation, probed vertical-slice completeness, guarded boundary tests, actor separation, source reconciliation, epic/current context contracts, lane selection/closeout, touched-surface evidence, runner-proof evidence, session handoff, epic gates, capability-change classification, and REPLAN count.

Capability ledger

CHANGELOG.md explains what changed for humans; docs/ai/capabilities/*.json records whether each ACEF capability is documented-only, wired, enforced, proven, or installed. Markdown-only changes cannot be reported as implemented.

Typed evidence

acef-state writes actor, worker-scope, hashed command evidence, gate verdict, and approval JSON sidecars. Validators bind PASS to the right actor, Git state, raw output hash, runner command/exit header, runner proof, and explicit human approval.

Fresh state

acef-status and acef-next turn typed repo state into a small startup packet: current action, allowed paths, forbidden actions, required evidence, and stop condition.

Surface closeout verifier

acef-closeout-verify derives the evidence a story owes per touched surface from the adapter's surface registry and enforces fail-closed: cold-process fresh-read for persistence (separate process must read what another wrote; a same-process read does not count), reachability as separate evidence (isolated render is partial, not pass), fail-closed on unknown surfaces (no nearest-match), and no story self-downgrade of a surface its goal owns. CI-gated; wired into install-acef-tools. The rule is recorded in method/DELIVERY_RULES.md as "Done = surface-proven."

Workflow graph

Small YAML workflows describe node order and artifact passing. acef-workflow-validate checks the graph; it does not replace evidence, gates, or Process Judge.

Review lenses

bug-hunter is a measured report-only JIT lens for bounded PR/lightweight review. It helps find behavioral defects and hollow-green risks without patching or approving gates.

Process gates

ACEF_PREFLIGHT.md must PASS before planning or implementation; Process Judge and Epic Process Judge verify skills, phase order, artifacts, and evidence before done.

Intake decision

Typed runs entering planning or execution must record route, confidence, asked questions or inferred answers, and unresolved questions in ACEF_ACTIVE_RUN.json; lane-selection fails if this was skipped.

Actor separation

Full BMAD story evidence records ATDD actor, Developer actor, Code Review actor, Verify-Patch actor, Test Review actor, and Process Judge actor. Self-review is invalid.

Epic boundary

Every epic gets a seeded Process Judge gate. The final story points to that gate, and the next epic waits for PASS plus explicit Epic Transition Approval. Generic go on / devam is not enough.

Speed mode

ACEF can fan out independent, non-overlapping stories and require inline worker reports to reduce round trips. Risky or guarded work keeps separate reviewers and Process Judges.

Test pipeline

User flows become test cases before automation: test-user-flow-mapper → test-case-planner → generators.

🧩Skills reference

Skill	Does	Status
`acef`	Front door. Routes intent, coordinates helpers, guides and teaches.	DRAFT
`acef-adapter`	Extract the per-repo project adapter, pattern registry, and living memory (evidence-based, no embeddings).	DRAFT
`acef-router`	Classify a request into a route + the minimum questions.	DRAFT
`acef-specify`	Requirements/design/tasks — import if present, else lightweight.	DRAFT
`acef-test-bootstrap`	First approved golden test for a repo with none.	DRAFT
`acef-release-adapter`	Release/CD readiness from the repo's real config.	DRAFT
`map-codebase`	Auto-generate a code-grounded map and pattern registry of any repo (+ freshness stamp).	READY
`bug-hunter`	Optional report-only JIT lens for bounded PR/lightweight review.	MEASURED
`implementation-shape-review`	Optional report-only lens for finding simplification targets before a separate patch actor changes code.	WIRED
`test-user-flow-mapper`, `test-case-planner`	Turn product/user flows into structured test cases before automation.	DRAFT
`test-browser-generator`, `test-gen`, `test-generator`	Generate browser/E2E and unit/integration tests from approved cases and adapter evidence.	DRAFT
`test-strategy`, `test-risk-classifier`, `test-coverage-auditor`	Pick test levels, rank risky behavior, and find weak or missing coverage.	DRAFT
`flow-document-composer`, `flow-suite-composer`, `storymap`	Compose flow docs, QA suites, story maps, and testable journeys.	DRAFT

Plus BMAD-METHOD for Route B when installed. ACEF does not accept "BMAD-like" generic subagents as BMAD; the real BMAD conductor/skills must resolve first.

acef-* names are reserved for ACEF-specific orchestration/core skills. The unprefixed skills are reusable workhorses that ACEF calls, not renamed copies.

✅Honest status

ACEF labels every capability so you always know what is real:

READY

Working skill or real artifact, used on real repos.

DRAFT

Written, research-informed definition — not yet tested on a real project.

MISSING

Not built or not found yet.

Today the methodology, repo-local helper CLIs, typed-state/context policy, and workflow guardrails have real repo evidence behind them. map-codebase is READY; bug-hunter is measured as an optional JIT review lens; implementation-shape-review is wired as an optional review lens but not enforced as a required gate. Quick-fix, lane closeout, touched-surface validation, and evidence runner proof are recorded as proven capability records. acef-closeout-verify is CI-gated and enforces the "Done = surface-proven" rule per the adapter's surface registry. Capability records prevent those states from being blurred.

📦Setup

ACEF ships as AI-agent skills. The front door is the acef skill; it delegates to helpers and reads its own portable methodology docs, so it works in any repo.

skills/
  acef/                  # the orchestrator (front door) + references/ (portable method docs)
  acef-adapter/          # project adapter + living memory extraction
  acef-router/           # route classification
  acef-specify/          # requirements / design / tasks (import or lightweight)
  acef-test-bootstrap/   # first golden test for a repo with no tests
  acef-release-adapter/  # release / CD readiness
  map-codebase/          # auto-generate a code-grounded map + pattern registry
  test-*/ flow-*/        # user flows, test cases, risk, generators, test suites
  storymap/ bug-hunter/  # planning + optional bounded review lens

Nothing in the skills is project-specific — every stack value comes from the adapter you extract per repo.

ACEF ships a portable BMAD guard hook in claude-plugins/acef-bmad-guard/. Clone users can install it with scripts/install-acef-bmad-guard --repo /path/to/repo; the installer writes the full guard into the repo's .acef/hooks/ directory, installs a repo-local OpenCode plugin, and wires a git pre-commit gate (acef-precommit-gate.sh) that runs lean-evidence on active runs and also requires gate-decider for guarded/full-BMAD commits; full gate-verdict remains a closeout/CI gate. Claude Code and Codex users can add --global-dispatcher once per machine for a tiny dispatcher that only forwards to repos with a local hook. Claude plugin users can enable that directory as a Claude Code plugin. The hook blocks dispatcher/conductor writes and blocks crossing into Epic N+1 until Epic N Process Judge is PASS. When the harness does not propagate worker identity (as with Claude Code subagents), the hard wall degrades from per-actor to scope-level enforcement: a guarded write is allowed only when the conductor-written active worker scope is in an implementation phase and the path is in allowedPaths. Set ACEF_WORKER_ID to restore strict per-actor enforcement. Use node scripts/smoke-acef-hook-active-ledger to verify active ledger scoping and node scripts/smoke-acef-opencode-plugin to verify the OpenCode adapter. Restart Claude Code / Codex / OpenCode after installing hooks.

⚖️Principles

Stack-agnostic. The core knows no stack; every stack value comes from the adapter.
Code-grounded. Copy a real golden neighbor; never invent a pattern the repo already has.
Surface-real. A claim closes through the surface that consumes it: browser/screen, HTTP, command, queue, storage, mail, webhook, or library contract.
No ceremony. Run only the steps a route needs. No dashboards or cadences unless asked.
Human approval on risk. Auth, payment, migrations, secrets, shared APIs, releases, and multi-repo work need a human before execution.
Honesty. Always label READY / DRAFT / MISSING. Never present a draft as proven.