Agentic Engineering Framework

June 8, 2026 · View on GitHub

Provider-neutral operating guide for AI agents working in this repository.

How to Use This Document

This document defines how any AI agent (Claude, GPT-4, Gemini, Llama, or others) should operate within this project. Provider-specific integration files may exist alongside this document:

Claude Code: Reads CLAUDE.md (auto-loaded)
Cursor/Copilot: Can read this file directly or create .cursorrules
Other LLMs: Read this file as your operating guide

The Agentic Engineering Framework is a governance framework for systematizing how AI agents work within engineering projects. This is not a traditional code library — it's a set of structural rules, patterns, and enforcement mechanisms for agentic workflows.

Works with: Any file-based, CLI-capable AI agent environment.

Core Principle

Nothing gets done without a task. This is enforced structurally by the framework, not by agent discipline.

Four Constitutional Directives (Priority Order)

Antifragility — System strengthens under stress; failures are learning events
Reliability — Predictable, observable, auditable execution; no silent failures
Usability — Joy to use/extend/debug; sensible defaults; actionable errors
Portability — No provider/language/environment lock-in; prefer standards (MCP, LSP, OpenAPI)

Authority Model

Human    →  SOVEREIGNTY  →  Can override anything, is accountable
Framework →  AUTHORITY   →  Enforces rules, checks gates, logs everything
Agent    →  INITIATIVE   →  Can propose, request, suggest — never decides

Task System

File Structure

.tasks/
  active/      # In-progress tasks (e.g., T-042-add-oauth.md)
  completed/   # Finished tasks
  templates/   # Task templates (default.md, inception.md)

Task File Format

Tasks are Markdown with YAML frontmatter. Use default.md as template.

Required frontmatter fields:

id, name, description, status, workflow_type, owner, created, last_update

Body sections:

Context (design docs, specs, predecessor tasks), Updates (chronological log)

Task Lifecycle

Captured → Started Work ↔ Issues → Work Completed

Four statuses: captured, started-work, issues, work-completed.

Workflow Types

Type	Purpose
Specification	Define what to build
Design	Determine how to build
Build	Create implementation
Test	Verify correctness
Refactor	Improve existing code
Decommission	Remove obsolete code
Inception	Explore problem space, validate assumptions, go/no-go decision

Arc System

An arc is a multi-task workspace grouping work by theme — the longitudinal narrative around multiple tasks pursuing one user-observable mechanic. Where a task answers "what are we doing right now," an arc answers "what is the whole thing this row of tasks is in service of, and how will we know when it's done?"

Arcs are optional. Standalone tasks remain first-class. Use an arc when work spans more than ~3 tasks with a shared headline mechanic.

Arc File Structure

Arcs live as YAML files in .context/arcs/. The filename stem is the slug (human-readable); the YAML id: field is the immutable numeric id (arc-NNN, allocated sequentially at create-time). Either form routes to the same arc.

Arc Lifecycle (Four States)

draft  ──── fw arc start ────► in-progress ──── fw arc close ────► closed
   │                                │
   └── fw arc abandon ──┐  ┌── fw arc abandon ┘
                        ▼  ▼
                    abandoned

State	Meaning
`draft`	Created, not yet active. Use for arcs spec'd ahead of pickup.
`in-progress`	Active work. Default after `fw arc start`.
`closed`	Shipped. `demo_evidence` captured. Terminal.
`abandoned`	No longer pursued. `abandonment_reason` captured. Terminal.

Terminal transitions (close, abandon) are refused under $CLAUDECODE=1 — closure decisions belong to the human via Watchtower review (T-1671 §ACD/G-062 Default-to-OPEN gate).

Task ↔ Arc Membership

A task joins an arc via arc_id: in its frontmatter (slug or arc-NNN form). A PreToolUse hook refuses edits to tasks whose arc_id: does not resolve to a registered arc (bypass: FW_ALLOW_ARC_ID_DRIFT=1).

D-Immutability

Arc identifiers are append-only: no renumber, no reuse, no delete. Slug rename is permitted but rare. The historical record is the artefact. See 012-ArcSystem.md for the full invariant.

For the complete reference (fields, audit checks, Watchtower surface, CLI verbs), see 012-ArcSystem.md.

Enforcement Tiers

Tier	Description	Bypass	Implementation
0	Consequential actions (force push, hard reset, rm -rf /, DROP TABLE)	Human approval via `fw tier0 approve`	PreToolUse hook on Bash (check-tier0.sh)
1	All standard operations (default)	Create task or escalate to Tier 2	PreToolUse hook on Write/Edit (check-active-task.sh)
2	Human situational authorization	Single-use, mandatory logging	Git --no-verify + bypass log
3	Pre-approved categories (health checks, status queries, git-status)	Configured	Defined in 011-EnforcementConfig.md

Working with Tasks

When starting work (BEFORE reading code, editing files, or invoking external workflows):

Check for existing task or create new one following default.md template
Set status to started-work
Set focus on the task: fw context focus T-XXX
THEN proceed with implementation
Log every action in Updates section with: action, output, context snapshot

When encountering issues:

Set status to issues
Log error reference and healing loop suggestions
Record resolution when fixed for pattern learning

When completing:

Verify all acceptance criteria met
Set status to work-completed
Generate episodic summary for future reference

Context Integration

Tasks feed three memory types:

Working Memory — Active task status and pending actions
Project Memory — Patterns across all tasks (failure modes, effective approaches)
Episodic Memory — Completed task histories for future reference

Error Escalation Ladder

A — Don't repeat the same failure
B — Improve technique
C — Improve tooling
D — Change ways of working

Agents

Each agent has a bash script (mechanical) and AGENT.md (intelligence/guidance).

Agent	Location	Purpose	Command
Task Create	`agents/task-create/`	Create new tasks	`fw task create --name "..." --type build`
Task Update	`agents/task-create/`	Change task status	`fw task update T-XXX --status ...`
Audit	`agents/audit/`	Check compliance	`fw audit`
Session Capture	`agents/session-capture/`	Ensure nothing lost	See `AGENT.md` checklist
Git	`agents/git/`	Enforce traceability	`fw git commit -m "T-XXX: ..."`
Handover	`agents/handover/`	Session continuity	`fw handover --commit`
Context	`agents/context/`	Manage memory fabric	`fw context init`
Healing	`agents/healing/`	Error recovery	`fw healing diagnose T-XXX`
Resume	`agents/resume/`	Post-compaction recovery	`fw resume status`
Observe	`agents/observe/`	Capture anomalies	`fw observe "description"`
Dispatch	`agents/dispatch/`	Sub-agent prompt templates	Read templates before dispatching

Session Protocols

Session Start

Initialize context: fw context init
Read .context/handovers/LATEST.md to understand current state
Review the "Suggested First Action" section
Set focus: fw context focus T-XXX
Run fw metrics to see project status

Mid-Session Recovery (after context compaction)

Run resume: fw resume status
Sync working memory: fw resume sync
Continue from recommendations

Session End

Run session capture checklist (agents/session-capture/AGENT.md)
Create tasks for all uncaptured work
Update practices with learnings
Generate handover: fw handover --commit
Fill in the [TODO] sections in the handover document
Run fw metrics to verify state

Do not end a session without generating a handover.

fw CLI

The fw command is the single entry point for all framework operations:

fw help              # Show all commands
fw version           # Show version and paths
fw doctor            # Check framework health
fw audit             # Run compliance audit
fw metrics           # Show project metrics
fw context init      # Initialize session
fw context focus T-XXX
fw git commit -m "T-XXX: description"
fw handover --commit # Generate and commit handover
fw task create --name "Fix bug" --type build --owner human
fw work-on "name" --type build  # Create task + set focus + start
fw healing diagnose T-XXX
fw promote suggest   # Check graduation candidates
fw tier0 approve     # Approve a blocked destructive command

Quick Reference

Action	Command
Start work	`fw work-on "name" --type build`
Resume task	`fw work-on T-XXX`
Create task	`fw task create --name "..." --type build`
Update status	`fw task update T-XXX --status ...`
Commit changes	`fw git commit -m "T-XXX: description"`
Install git hooks	`fw git install-hooks`
Run audit	`fw audit`
View metrics	`fw metrics`
Initialize session	`fw context init`
Set focus	`fw context focus T-XXX`
Add learning	`fw context add-learning "..." --task T-XXX`
Diagnose issue	`fw healing diagnose T-XXX`
Resume state	`fw resume status`
Generate handover	`fw handover --commit`
Read last handover	`cat .context/handovers/LATEST.md`
Approve Tier 0	`fw tier0 approve`
Project health	`fw doctor`
Create arc	`fw arc create <slug> --name "..." --headline-mechanic "..." --anchor T-XXXX`
Start arc (draft → in-progress)	`fw arc start <slug>`
Close arc (ship)	`fw arc close <slug> --demo <path\|url\|none> --decision "..."`
Abandon arc (no longer pursued)	`fw arc abandon <slug> --reason "<≥30 chars>"`
Focus arc	`fw arc focus <slug>`
List arcs	`fw arc list`
Show arc detail	`fw arc show <slug>`
Rank tasks by BVP	`fw bvp`
Show per-driver detail for a task	`fw bvp T-XXX`
Filter ranking by quadrant	`fw bvp --quadrant {hv-lc\|hv-hc\|lv-lc\|lv-hc}`
Change driver weight (§ACD)	`fw bvp weight --set Dn=N --rationale "..."`
Confirm task scores	`fw bvp confirm T-XXX`
Approve arc-scoped driver (§ACD)	`fw arc approve-driver <arc> "<name>" [--weight N]`
Surface estimator-proposed scoped drivers	`fw arc show-suggestions <arc>`
Driver-session prompts (propose/sharpen)	`policy/prompts/bvp-driver-session.md` (keystone — three workflows A/B/C)
Recover legacy consumer (pre-T-2232)	`fw consumer-recover <host> [path] [--apply] [--via {ssh,termlink}]`

Glossary

Term	Definition
Antifragility	Constitutional directive #1. The system strengthens under stress — failures become learning events that improve future behavior, not just errors to recover from.
Arc	A multi-task workspace grouping work by theme. Holds the longitudinal narrative around several tasks pursuing one user-observable mechanic. Has a four-state lifecycle (`draft → in-progress → closed/abandoned`), an immutable `arc-NNN` id, and a human-readable slug. Optional — tasks without an arc remain first-class. See `012-ArcSystem.md`.
D-Immutability	The arc-system axiom that identifiers are append-only: no renumber, no reuse, no delete. Slug rename is permitted but rare. The historical record (including closed and abandoned arcs) is the artefact.
Blast Radius	The set of downstream components affected by a change. Computed by the Component Fabric via `fw fabric blast-radius`.
Context Fabric	The persistent memory system managed by the Context Agent. Stores working memory (session state), project memory (patterns, decisions), and episodic memory (task histories). Lives in `.context/`.
Enforcement Tiers	Four levels of action governance. Tier 0: human-approved destructive actions. Tier 1: standard operations (require active task). Tier 2: human situational overrides. Tier 3: pre-approved safe operations.
Episodic Memory	Condensed history of completed tasks — what was done, what worked, what failed. Auto-generated on task completion. Stored in `.context/episodic/`. Used by agents to learn from past experience.
Healing Loop	The antifragile error-recovery cycle: classify failure, look up similar patterns, suggest recovery, log resolution. Triggered when a task enters `issues` status. See `fw healing`.
Horizon	Priority scheduling field on tasks. `now` = ready to work on, `next` = ready after current work, `later` = parked/backlog. Controls handover suggestions and task ordering.
Inception	A workflow type for exploring a problem space before committing to build. Produces a go/no-go decision with evidence. Build tasks are created separately after a GO decision. See `050-Inceptions.md` for the lifecycle, disposition gate, scoring exception (`target_blast_radius` + VoI), three-tier adjudication, and park-state semantics.
Project Memory	Patterns, decisions, and learnings accumulated across all tasks. Persists between sessions. Stored in `.context/project/`.
Sovereignty	The human's absolute authority in the Authority Model. Humans can override anything but are accountable for the outcome. Structural gates enforce sovereignty — agents cannot bypass them.
Working Memory	Active session state: current focus, pending actions, recent context. Lives in `.context/working/`. Refreshed each session via `fw context init`.
BVP (Business Value Points)	A directive-weighted score on tasks/arcs: `Σ(driver_weight × driver_score)` where score is 0–5 and weight is 0–9. Surfaces high-value/low-cost work in the quadrant view. Adapted from Geelen 2019; see `040-ValueDrivers.md`.
Value Driver	A named dimension along which work is scored. Carries a weight (integer 0–9). Total drivers (protected + free) ≤ 9. See `040-ValueDrivers.md`.
Free Driver	A project-level value driver beyond the four constitutional directives. Up to 5 per project; adding a 6th triggers M1 add-one-drop-one. Managed via `fw bvp driver --add/--remove` (§ACD).
Arc-Scoped Driver	A driver registered on a single arc, distinguishing what the global directives don't capture. Cap 3 per arc, weight ≤ 6 (M2). Managed via `fw arc approve-driver` (§ACD).
Directive Scoring	The per-task act of assigning 0–5 to each driver. Calibrated to ±1 across independent scorers; rubric in `policy/bvp-scoring-rubric.md`.
Quadrant	The split of the task list on median BVP × median cost (`hv-lc`, `hv-hc`, `lv-lc`, `lv-hc`). Medians are recomputed live each invocation — no calibration thresholds to set.

Installation

Quick install

curl -fsSL https://raw.githubusercontent.com/DimitriGeelen/agentic-engineering-framework/master/install.sh | bash

This checks prerequisites, clones to ~/.agentic-framework, links fw to PATH, and runs fw doctor.

Set INSTALL_DIR to customize: INSTALL_DIR=/opt/framework curl -fsSL .../install.sh | bash

Manual install

git clone https://github.com/DimitriGeelen/agentic-engineering-framework.git ~/.agentic-framework
sudo ln -sf ~/.agentic-framework/bin/fw /usr/local/bin/fw
fw doctor

Verify

fw version
fw doctor

Isolation Model (T-1189/G-031)

The framework supports two canonical isolation patterns:

Pattern	Mechanism	Use case
Vendored dir	`fw init` / `fw vendor` copies framework into `.agentic-framework/`	Consumer projects (default)
Shim dispatch	`bin/fw-shim` detects project, routes to vendored copy	Multi-project environments

How it works: fw init /path/to/project calls do_vendor() which copies bin/, lib/, agents/, web/, docs/, .tasks/templates/, FRAMEWORK.md, and metrics.sh into the project's .agentic-framework/ directory. The project is then self-contained. The shim (~/.local/bin/fw) detects which project you're in and routes to that project's vendored copy.

Upgrading: fw upgrade /path/to/project syncs the vendored copy from the framework repo. It delegates to the same do_vendor() function, ensuring the same files are synced.

Legacy patterns to avoid:

Manual cp from framework to project — use fw vendor instead
Symlinks into framework repo — breaks project isolation
Oversized global install at ~/.agentic-framework — the shim obsoletes this

fw doctor checks for problematic patterns (nested vendored dirs, oversized global installs).

Setting Up a New Project

# Initialize project (auto-detects interactive mode)
fw init /path/to/project

# Then:
cd /path/to/project
fw doctor           # Verify setup
fw context init     # Start first session
fw work-on "First task" --type build

Updating the framework

From within any project that uses the framework:

fw update            # pulls latest changes into your framework installation

Or manually update the framework repo:

cd /path/to/agentic-engineering-framework
git pull

Projects reference the framework via framework_path in .framework.yaml. After updating the framework installation, all projects pointing to it will use the new version on their next fw invocation.