AgentDirective methodology

Make consequential software decisions explicit before an agent implements them.

AgentDirective turns a plain-language project description into safeguards, questions, requirements, tests, and evidence to collect—without allowing a model to become the source of policy.

Understand the methodology See it work Connect an agent

Start here

Three roles, one workflow

The person, the rules, and the coding agent each have a different job.

01

The person decides

People confirm scope, thresholds, approval boundaries, destinations, retention, and other material choices.

02

The rules organize

Published rules connect what the system does to the safeguards that apply and keep open decisions visible.

03

The agent implements and reports

The coding agent receives explicit requirements, records evidence pointers, and states limitations without claiming independent verification.

The trail

See where each result came from

Follow a result from what the system does, through the safeguard and question, to the requirement and evidence.

1What it doesSystem trait

2Failure patternWhat can go wrong

3Control PackSafeguard that applies

4DecisionYou confirm or leave it open

5RequirementWhat to build

6EvidenceWhat the agent reports

Choose a path

Use the same method at different stages

Before implementation

Plan a new project

Detect architecture characteristics, confirm applicability, answer material questions, and compile a directive.

Read the methodology → After implementation

Inspect an existing project

Give a coding agent a read-only checklist, return sanitized metadata, and prioritize gaps without uploading source.

Review an existing project →

How matching works

AgentDirective checks your description for known traits, such as sensitive data or actions that change production. You can correct the list before continuing. Your choices determine which Control Packs apply.

If nothing matches, you can send the description once to Cloudflare AI for suggestions. This is off by default. We do not store the description or response. AI can suggest only a trait from the existing list; it cannot choose a pack, answer a project question, or change your choices.

Repeatable matchingThe same confirmed traits, matching rules, and pack versions produce the same matches.

Open decisions stay open“Not decided” is recorded as unresolved, not a confirmed default.

Versioned resultsEach directive records the methodology, pack, and schema versions used to create it.

1. Identify what the system does

Traits describe capabilities and boundaries, not just technologies. Examples include sensitive data, outside input, tool access, money movement, multiple customers, production changes, and irreversible actions.

Every suggestion shows where it came from

AgentDirective records whether a trait came from you, a published rule, or the optional AI check. A suggestion is never presented as something you explicitly said.

user_stated — selected or written by the user
rule_inferred — matched by versioned rules
model_suggested — suggested by the optional AI check
user_corrected — changed by the user

architecture-model.json

{
  "id": "FINANCIAL_ACTION",
  "value": true,
  "confidence": 0.90,
  "provenance": "rule_inferred",
  "reason": "The proposal includes a payment action."
}

2. Match the safeguards

Each pack has a published applies_when rule. AgentDirective checks it against your confirmed traits and shows why it matched. If nothing matches, it creates a no-match assessment instead of an empty directive.

AI does not choose the safeguards

Only the published pack rules decide what applies. An AI model cannot invent a pack, skip its rule, or hide one that matches.

If you change a project trait, AgentDirective checks the rules again and records what changed.

AUT-001 matching rule

"applies_when": {
  "any": [
    { "characteristic": "FINANCIAL_ACTION", "equals": true },
    { "characteristic": "CONSEQUENTIAL_ACTION", "equals": true }
  ]
}

3. Ask the important questions

Applicable packs surface important questions. Quick Review shows the few most likely to change the build; Full Review shows them all.

StatusMeaningMay provide a binding value?

confirmedAn authorized person supplied the answer.Yes

recommendedA pack recommendation has not been accepted.No

unresolvedThe material question remains open.No

not_applicableThe user says the question does not apply and gives a rationale.No

explicitly_rejectedThe user consciously rejects the safeguard and gives a rationale.No

4. Create, track, and review

Create
Keep one source of truth
agent-directive.json holds the requirements. The readable instructions and agent files come from it.
Track
Keep progress with the project
The coding agent updates one status entry per requirement and records important changes.
Review
Compare claims with evidence
The reviewer checks whether the report is complete and internally consistent. It does not inspect the code itself.
Reassess
Keep history when scope changes
A new directive shows what was added, changed, kept, or retired. Earlier decisions stay visible.

5. Versioning and governance

Schemas, the methodology, the pack library, and individual packs use semantic versions. Applicability or requirement changes require a pack version change. Breaking data-contract changes require a schema major version.

Each pack is expected to carry a distinct failure mode and control objective, technical review, evidence review, applicability fixtures, limitations, and changelog history before it can move from review to released. Packs are not added merely to increase match rates; wording gaps belong in versioned signals or context rules, while genuine control gaps require evidence. At present, every published pack remains in review.

What a pack contains

applies_whenWhen it applies

A published rule based on project traits you confirmed.

failure_modesWhat can go wrong

The specific harm or breakdown the pack addresses.

questionsWhat you must decide

Important values that the system must not invent.

requirementsWhat to build

Stable, testable instructions with severity and references.

verificationWhat evidence to keep

Tests, implementation locations, telemetry, policies, or procedures.

control_mappingsRelated guidance

Carefully scoped relationships—not equivalence or certification.

Example: automated actions

AUT-001 applies when a system can perform a financial or high-impact action. It does not choose the limit. It asks you, then puts your answer into a requirement.

Question → requirement → evidence

The question supplies the missing boundary. The requirement defines the implementation. Verification expectations state what a later report should point to.

The example is shortened for readability. The canonical pack remains available through the pack library.

Open the full pack library →

AUT-001, abbreviated

{
  "pack_id": "AUT-001",
  "question": "What limit applies before human approval?",
  "requirement": {
    "id": "AUT-001-R1",
    "statement": "Enforce the confirmed action boundary, escalate outside it, make retries idempotent, and provide a disable path."
  },
  "evidence_expected": [
    "configuration_or_policy",
    "implementation_location",
    "test_result",
    "telemetry_definition"
  ]
}

Pack status

Draft

Initial content and fixtures are being developed.

→

Review

Published for use and evaluation, but not independently released.

→

Released

Technical and evidence reviews are complete.

→

Deprecated

Retained for history with a migration path.

What this checks

These checks exercise visible behavior. Every published pack has a versioned example that runs through the same detector and matching rules used by the public service.

01Selection

Does the example produce the architecture characteristics required by the pack’s published applicability rule?

02Questions

Does the matched pack surface its real material questions without supplying answers on the user’s behalf?

03Instructions

Do confirmed user answers become traceable requirements while unanswered decisions remain visibly unresolved?

Fixed-corpus stress test

25,000 wording variations, with the baseline preserved

Twenty user-background styles and thirty scenario archetypes were combined into 25,000 unique synthetic descriptions. The same corpus was rerun after each bounded detector change; expected labels and the seed were not rewritten to improve the score.

70.72% → 100%

Risk-bearing descriptions that reached at least one applicable Control Pack.

20.41% → 0%

Low-risk controls that incorrectly produced a characteristic or pack.

43.80% → 79.24%

Expected-characteristic micro recall; remaining secondary-label disagreements stay visible.

The first correction removed small team as a standalone multi-tenant signal. That initially lowered the risk-query score because the false positive had also been manufacturing packs for risk-bearing requests. Seven later bounded iterations addressed explicit export, file, tenant, webhook, cost, account, AI, vendor, and destructive-action wording. The stopping rule was reached when every risk-bearing case reached a pack and every low-risk control stayed clean.

Download the versioned configuration →
Download the preserved baseline →
Download the final iteration →

Sealed holdout

New wording exposed a real generalization gap

A second 25,000-description corpus used 30 newly authored scenario families, 25 new user-background styles, new sentence structures, and a different seed. Automated checks found no exact request reuse and no full-query overlap with the development corpus. It was run once against signal dictionary 0.9.9, and the first result was preserved without tuning.

58.41%

Risk-bearing descriptions that reached at least one Control Pack.

28.49%

Expected-characteristic micro recall on the new language.

15.00%

Harmless controls that produced a false positive.

The result shows that the deterministic applicability rules are inspectable once characteristics are present, but the current phrase detector is too dependent on known vocabulary. Failures include missed multi-organization and export language, substring matching such as quota inside “quotation,” and insufficient negation handling for wording such as “no submissions.” Holdout v1 is now closed: improvements must be developed elsewhere and assessed on a fresh holdout.

Download the sealed holdout configuration →
Download the preserved first result →

Live MCP demonstration

From one request to an agent directive

The example below calls the public MCP endpoint. Change the request or start with the invoice example, then answer as many questions as you are prepared to decide.

What are you building?Use a high-level description. Do not include source code, credentials, personal data, or customer records.

Ready to analyze. No information has been sent yet.

1Request
2Detect
3Questions
4Directive

Observed characteristicsReturned by agentdirective_analyze

Matched Control PacksRule-based applicability, with the reason preserved

Published verification cases

One inspectable example for every Control Pack

Each entry explains why the safeguard matters, when its rule applies, the question it asks, the instruction it contributes, and the test evidence it expects. “Run example” sends that exact request through the live MCP service.

Loading the 34 published verification cases…

Verify a pack through MCP

Agents and independent evaluators can call the same fixture directly. The response includes the example request, detected characteristics, all observed matches, the target pack’s questions and requirements, methodology versions, and explicit limitations.

A reproducible public check

Change AUT-001 to any published pack identifier. A successful response reports result: "passed" only when the target pack appears in the live observed match set.

The case library is versioned separately so changes to examples can be distinguished from changes to packs or methodology.

MCP tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "agentdirective_verify_pack",
    "arguments": { "pack_id": "AUT-001" }
  }
}

One source, several useful files

The compiler creates .agentdirective/agent-directive.json first. The Markdown instructions, prompts, status templates, and manifest come from the same file, so they stay in sync.

Matching and editing happen in your browser. When you choose to create the files, your description, traits, answers, and any optional context or prior directive are sent to the Cloudflare-hosted compiler for that request. The service does not store those inputs or generated files. Compilation is deterministic; it does not call an AI model.

A requirement carries its decision state

A confirmed parameter can be implemented. An unresolved parameter remains visible in unresolved_decisions and must not be silently filled by the agent.

Stable IDs link controls, decisions, tests, observability, evidence, and later status reports.

agent-directive.json

{
  "directive_id": "AD-7Q2K8M4P",
  "directive_version": "1.0.0",
  "methodology_version": "0.1.0",
  "controls": [{
    "control_id": "AUT-001",
    "pack_version": "1.0.0",
    "requirements": [{
      "requirement_id": "AUT-001-R1",
      "decision_status": "confirmed",
      "parameters": { "value": "500", "unit": "USD" },
      "verification_required": true
    }]
  }]
}

What the bundle contains

Each file has one job. The filename is shown second so you can understand the hand-off before learning its technical name.

Build rules and decisions.agentdirective/agent-directive.jsonThe structured source of truth for requirements and the decisions behind them.

Implementation progress.agentdirective/control-status.jsonWhat the agent reported for each requirement: implemented, partial, unresolved, or another status.

Change history.agentdirective/control-events.jsonlA running record of important changes and later reassessments.

Readable agent instructions.agentdirective/IMPLEMENTATION_PROMPT.mdInstructions derived from the same build rules, written for an agent hand-off.

Bundle contents and checksumsmanifest.jsonA list of included files and fingerprints used to detect accidental changes.

Completed, draft, and no-match are different results

ResultWhen it is usedWhat is handed off

DirectiveAt least one pack matched and every surfaced decision has a confirmed value.Implementation contract

Draft directiveAt least one pack matched and one or more surfaced decisions remain open.Contract with explicit questions

No-match assessmentNo current Control Pack matched the confirmed characteristics.Assessment and next steps; no directive

Requirement drift

If a later request conflicts with a confirmed requirement, the coding agent should stop and surface the conflict. Weakening, removing, or rejecting a safeguard is a new decision and a new event—not a silent edit.

Three layers that must not be collapsed

1Agent-reported status

The coding agent says whether a requirement is implemented, partial, unresolved, not applicable, or rejected.

2Evidence pointers

Relative file paths, named tests and outcomes, telemetry names, procedures, or safe digests support the claim without embedding source.

3Review result

The reviewer determines whether the submitted metadata supports, omits, or contradicts the claim within the selected scope.

Report status without overstating it

Use specific, limited evidence

Each test has a result. Each file path stays relative to the repository. A partial status must say what remains unfinished.

implemented means “the agent reports this exists,” not “AgentDirective independently verified the behavior.”

control-status.json

{
  "requirement_id": "AUT-001-R1",
  "status": "partial",
  "implementation_summary": "Boundary and idempotency checks are present.",
  "evidence": {
    "code_locations": ["src/refunds/policy.ts:42"],
    "tests": [{
      "name": "refund boundary rejects duplicate request",
      "result": "passed"
    }],
    "telemetry": ["refund_escalated"],
    "other": []
  },
  "limitations": ["Emergency disable path is not yet available."]
}

Review result vocabulary

supported

Submitted metadata is consistent for the narrow check performed.

unsupported

Expected status or evidence is absent.

contradicted

A supplied test, status, or artifact conflicts with the claim.

unverifiable

The package cannot establish the claim without source or runtime inspection.

not_reviewed

The check falls outside the selected review scope.

Privacy boundary

Safe to submit

Directive and status metadata
Repository-relative paths
Test names and outcomes
Telemetry event names
Short implementation summaries
Known limitations and safe digests

Do not submit

Source code or file contents
Secrets, credentials, or environment values
Personal or customer data
Production records or raw logs
Absolute paths or repository URLs
Proprietary build artifacts

How the read-only review works

Describe
Explain what the project does
Mention users, data, integrations, important actions, automation, and AI features.
Plan
Create a project-specific checklist
Published matching rules select relevant packs, requirements, expected evidence, and open questions.
Inspect
Your coding agent reads the repository locally
It makes no changes and returns only the requested assessment fields.
Review
Submit a report with sensitive details removed
The reviewer highlights claims that are unsupported, contradictory, incomplete, or not verifiable from the report.
Improve
Get a focused improvement prompt
The agent receives the gaps but must still ask you about every open decision.

Let a connected agent handle the handoff

Two purpose-built MCP tools

agentdirective_existing_project_plan returns the checklist and assessment template. After local inspection, agentdirective_existing_project_audit accepts the sanitized object and returns findings.

The web workflow remains available for agents without remote MCP support.

Open the existing-project review →

Instruction for a connected agent

Use AgentDirective to review this existing project.

1. Call agentdirective_existing_project_plan.
2. Inspect the repository locally and read-only.
3. Do not send source, secrets, personal data, or absolute paths.
4. Call agentdirective_existing_project_audit with the sanitized assessment.
5. Present the findings and ask me about every open decision.

Reassess a project that already has a directive

When a project changes after its first review, start from the directive it already has instead of describing it from scratch. Upload agent-directive.json on the review page for an existing project, edit the description to say what changed, and the compiled result is compared against the previous version.

Added — applicable now, but not before. These need decisions and implementation.
Changed — already applicable, but the requirement or its confirmed value is different.
Retired — no longer applicable to the project as now described.
Unchanged — carried through. Implementation already reported still applies.

Values you confirmed previously are offered again rather than asked fresh, and are recorded with the originating directive as their rationale. Nothing is applied without an explicit click: a value confirmed against the old description is not automatically confirmed against the new one.

The same delta from a connected agent

A connected agent gets the identical comparison by passing the project’s current agent-directive.json as previous_directive. The response adds a delta object alongside the newly compiled files.

{
  "name": "agentdirective_compile",
  "arguments": {
    "description": "… the project as it is now …",
    "decisions": [],
    "previous_directive": { "…": "the existing agent-directive.json" }
  }
}

Remote MCP endpoint

The hosted endpoint speaks JSON-RPC 2.0 over HTTP. It requires no account or API key and receives no repository access.

Remote MCP serverhttps://agentdirective.org/mcp

agentdirective_analyze

Detect characteristics, match packs, and return open questions.

agentdirective_compile

Compile a canonical bundle from the user’s answers. Pass previous_directive to also receive a delta of added, changed, unchanged, and retired requirements.

agentdirective_review

Run the bounded directive metadata review.

agentdirective_existing_project_plan

Create a read-only checklist for an existing project.

agentdirective_existing_project_audit

Review the sanitized existing-project assessment.

agentdirective_packs

Read the versioned Control Pack library.

Call a tool over JSON-RPC

Analyze before writing code

The response contains detected characteristics, applicable packs, and questions for the user. It deliberately does not contain answers to those questions.

Most MCP clients configure the endpoint as a remote server; direct JSON-RPC is shown here to make the protocol behavior concrete.

HTTP request

POST https://agentdirective.org/mcp
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "agentdirective_analyze",
    "arguments": {
      "description": "A support assistant reads customer messages and can issue refunds."
    }
  }
}

Report implementation from a local agent

The remote endpoint cannot read or write a project. When the local MCP server or CLI is installed in the project, the coding agent can update the bundle and generate the report a person reads without uploading source code or project files.

agentdirective_report_batch

Record status and evidence pointers for many requirements in one rollback-protected transaction. The complete status document, existing event history, and proposed events are validated before either lifecycle file changes.

agentdirective_render_report

Render the directive and reported status as self-contained HTML or Markdown. Dismissed and unresolved requirements remain visible, and an agent-reported status is never presented as verification.

agentdirective_check

Check that the local bundle is structurally complete and internally consistent.

agentdirective_status

Summarize implemented, partial, unresolved, and not-applicable requirements.

Finish the reporting loop

Prefer one agentdirective_report_batch MCP call after implementation so a long run cannot quietly stop after reporting only some requirements. The response names anything still unreported.

Then render the report and give the generated file to the user. It describes typed statuses and evidence pointers; it does not inspect the code or certify the result.

CLI verification and report

agentdirective check
agentdirective status --format html \
  --out implementation-report.html

Public HTTP routes

GET /api/healthMethodology versions and deployment provenance.

GET /api/methodologyPublished versions, counts, modes, and limitations.

GET /api/packsCanonical Control Pack library.

GET /api/oscal/catalogThe Control Pack library as a schema-validated NIST OSCAL 1.2.2 catalog, for tooling that already reads OSCAL.

GET /api/vocabularyRecognized platform names and their review cues.

GET /api/benchmarkVersioned benchmark dataset and current results.

GET /api/public-recordsPublic disclosures mapped to reviewed safeguards; alias of /api/trends.

POST /api/semantic-fallbackOne consented Cloudflare AI suggestion request, accepted only after zero deterministic characteristics.

POST /api/compileCompile a directive from description, applicable packs, and decisions; rejects zero-pack input.

POST /api/existing-project/planCreate a read-only existing-project assessment plan.

POST /api/existing-project/auditReview a sanitized existing-project assessment.

POST /api/reviewReview a sanitized directive/status package.

POST /api/outcomesRecord one consented, allowlisted design-change category as an aggregate count; no free text or identifiers.

POST /api/journey-eventsRecord one allowlisted aggregate workflow event; descriptions, identifiers, and free text are rejected.

Three projections, one canonical source

catalogControl Pack library

Pack objectives, questions, requirements, and explicitly partial external mappings.

profileOne compiled directive

Selected safeguards and only the parameter values the user actually confirmed.

assessment-resultsStatus observations

Agent-reported status and optional bounded metadata-review outcomes, with no control findings.

Minimal integration path

Fetch
Fetch the catalog
Read GET https://agentdirective.org/api/oscal/catalog and cache it by metadata.version and metadata.oscal-version.
Compile
Compile a directive
Use the browser, API, CLI, or MCP workflow. A downloaded bundle contains .agentdirective/oscal-profile.json.
Resolve
Resolve the import
The profile imports the public catalog and includes the selected pack and requirement identifiers.
Preserve
Preserve open decisions
Only confirmed values appear under modify.set-parameters. Never default a parameter that the profile leaves unset.
Interpret
Display status honestly
Treat assessment-results entries as observations. Do not convert metadata-review vocabulary into compliant/non-compliant status.

Public OSCAL cataloghttps://agentdirective.org/api/oscal/catalog

Compatibility and migration

ConsumerSupportAction

OSCAL 1.2.2 catalog/profileNativeValidate directly

OSCAL 1.2.2 assessment resultsObservation-onlyPreserve no-finding boundary

OSCAL 1.1.x onlyNot declared compatibleConvert explicitly and revalidate

AgentDirective nativeCanonicalPrefer agent-directive.json

No stored AgentDirective artifact needs an in-place migration. Regenerate the OSCAL projection from the canonical directive or status document so the declared version and schema-validated structure move together.

Repository-local export

CLI

agentdirective oscal .agentdirective
agentdirective oscal .agentdirective --model catalog
agentdirective oscal .agentdirective --model assessment-results \
  --review-report review-report.json

The public catalog and every generated projection declare OSCAL 1.2.2 and are validated against NIST's published JSON schemas during the release gate.

Core artifacts

ArtifactRoleAuthority

agent-directive.jsonRequirements, decisions, tests, observability, and traceability.Canonical

control-status.jsonCoding-agent-reported status and evidence pointers.Reported

control-events.jsonlAppend-only implementation and reassessment history.Historical

manifest.jsonBundle file list and integrity digests.Integrity

review-report.jsonBounded findings and explicit limitations.Review result

Published schemas

Schemas use JSON Schema Draft 2020-12. The links below resolve to the exact machine-readable contracts served by AgentDirective.

agent-directive-v1Canonical directive control-pack-v1Control Pack definition architecture-model-v1Confirmed characteristics decision-set-v1Structured user decisions control-status-v1Reported implementation status control-event-v1Append-only lifecycle event bundle-manifest-v1Bundle integrity manifest review-report-v1Bounded review result ai-agent-flow-map-v1Editable intended-design flow map

Version semantics

Schema version

Changes when the machine-readable contract changes. Breaking changes require a major version.

Methodology version

Changes when interpretation, sequencing, or governance rules change.

Pack library version

Identifies the complete collection used for matching.

Pack version

Changes when a pack’s applicability, requirements, questions, or evidence expectations change.

Interpretation limits

A detected phrase is a candidate, not a conclusion.
A Control Pack is a design safeguard, not a certification.
A framework mapping indicates support, partial coverage, or relevance—not equivalence.
A confirmed decision records what a user chose; it does not establish that the choice is legally or operationally sufficient.
An implemented status is an agent claim, not independent verification.
A supported review result means the submitted metadata is consistent for the check performed.