GitHub

Ayyildiz Context Engineering Framework

ACEF

ACEF gets real work done in the codebase you already have — new features, bug fixes, tests, and the plan around them — built the way your project already works. You say what you want in plain language; you get a change that fits your repo, not generic boilerplate.

🧭What ACEF does

Plans and gates the work

Turns a brief into a traceable plan, surfaces the risk, and holds a go/hold/kill gate before risky work merges — with a status view of what's in flight.

Ships features

In the pattern your repo already uses, like it was hand-written.

Fixes bugs at the root

In your code's own style, the smallest correct fix.

Writes the tests you're missing

In your project's real test setup — and turns product flows into test cases. Bootstraps the first test if there are none.

💬How to start

You
How big is this billing change, and what's the risk?
ACEF
Large feature, high risk — it touches payment and spans the API and dashboard. It needs a brief, a plan, and your go-ahead before the payment step merges.
You
I want to add a new feature to this project.
ACEF
I’ll check the repo, pick the right route, and use the project’s own patterns.
You
I need tests for this codebase.
ACEF
I’ll inspect the current setup, then choose the smallest safe test path for this repo.

📚Where to read more

Overview

The full picture: routes, onboarding a repo, how to ask, and ACEF's honest status.

SDLC & frameworks

How ACEF maps the lifecycle and where BMAD, Kiro, spec-kit, GSD, and OpenSpec fit.

Roles

What a developer, PM, and QA/test engineer can do with ACEF.

✅What to remember

  • ACEF isn't a second methodology — it adapts to the repo you already have.
  • Full BMAD work separates the conductor from worker personas, so the same actor cannot build and approve its own work.
  • Implementation workers are fenced to one active story/phase with narrow allowed paths, no ledger edits, no subagent spawning, and a bounded commit budget.
  • Stories that depend on third-party framework internals ground the real installed API before ATDD, so agents cannot fake green with shims or vendor overrides.
  • Runtime-wired work needs at least one real entrypoint smoke with content assertions, not just isolated helper tests or status-only routes.
  • Quick fixes, lightweight work, full BMAD, and guarded work have lane-specific closeout bundles; touched surfaces must be declared and proven at the runtime surface that changed.
  • Evidence artifacts now require runner-shaped command/exit metadata and runner proof, so plain prose logs cannot satisfy typed evidence or lightweight surface evidence.
  • Functional requirements close only when traced to an owning story and an exercised capability, not merely a supporting artifact.
  • Lean runtime is the default: evidence stays on disk; chat reports only artifact path, verdict, key evidence, and next step.
  • Story workers receive a maximum-150-line role-specific current-context slice instead of repeatedly reading the full ledger and planning set.
  • Fresh sessions start from acef-status and acef-next, so the current allowed action, write boundary, evidence requirements, and stop condition come from typed repo state.
  • Workflow definitions can be versioned as small YAML graphs and validated with acef-workflow-validate; nodes pass artifact paths instead of full chat history.
  • bug-hunter is a measured, report-only JIT review lens for bounded PR/lightweight review; it is recommended when useful but kept out of the minimal default install.
  • Optional acef-query retrieval uses Context Mode when available and a deterministic file fallback otherwise; gates never depend on it.
  • acef-context-experiment compares baseline, file fallback, and Context Mode retrieval before worker defaults are changed.
  • Future tools such as symbol indexes, graph memory, MCP runtimes, and eval frameworks require measured admission before adoption.
  • CHANGELOG.md records the human-readable framework history; docs/ai/capabilities/*.json records what is documented, wired, enforced, proven, or installed.
  • capability-change stops ACEF flow/gate/role changes from being reported as implemented when they only changed markdown.
  • intake-decision-gate makes planning/execution runs record route, confidence, interview questions, approved brief, execution approval, and unresolved questions before dispatch.
  • evidence-runner-proof is proven: typed evidence and lightweight surface evidence must carry runner proof, while signed evidence remains a future hardening step.
  • The front-door skill is compact and loads detailed ACEF reference files just-in-time.
  • Full BMAD epics seed their Process Judge gates up front; the next epic waits until the prior one is PASS.
  • Every active run starts with a delivery ledger, active ledger pointer, and Session Handoff before workers fan out.
  • Full BMAD records run-level delegation authorization for ACEF-required persona workers only, so independent reviewers can run without repeated prompts.
  • Claude Code, Codex, and OpenCode users can install the ACEF/BMAD guard to enforce these boundaries during ACEF/BMAD lanes. 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 worker scope is in an implementation phase and the path is in allowedPaths.
  • Codex users also run scripts/acef-codex-guard as the certification/pre-commit backstop for worker-scope checks.
  • scripts/install-acef-bmad-guard now installs 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.
  • acef-closeout-verify is the per-surface "done" verifier: it derives required evidence from the adapter's surface registry and enforces fail-closed rules — cold-process fresh-read for persistence, reachability as separate evidence (isolated render is partial, not pass), fail-closed on unknown surfaces, and no story self-downgrade of a surface its goal owns. It is CI-gated and wired into install-acef-tools. The rule is recorded in method/DELIVERY_RULES.md as "Done = surface-proven."