The authoritative path

Deterministic signals and context rules identify candidate architecture characteristics. The user corrects them. A rule engine then selects Control Packs. Optional model output may suggest a characteristic only when local detection finds nothing; it cannot decide applicability or supply a business value.

1. Extract architecture characteristics

Characteristics describe capabilities and boundaries, not technologies alone. Examples include sensitive data, untrusted input, tool access, financial action, multiple tenants, production modification, and irreversible action.

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

2. Match Control Packs

Every pack carries a machine-readable applies_when expression. The rule engine evaluates it against the confirmed architecture model and records why the pack matched.

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

3. Ask and capture decisions

Applicable packs surface material questions. Quick Review prioritizes the few questions most likely to change implementation; Full Review exposes every applicable question.

4. Compile, track, and review

1. Compile
   Create the canonical directive first

   agent-directive.json is the source of truth. Human-readable instructions and agent wrappers are derived from it.

2. Track
   Keep requirement status repository-local

   The coding agent updates one status entry per requirement and appends material changes to an event history.

3. Review
   Compare claims with expected evidence

   The bounded reviewer checks schema validity, completeness, evidence pointers, and contradictions without calling agent claims independent verification.

4. Reassess
   Preserve history when scope changes

   A new directive reports added, changed, unchanged, and retired requirements. Prior decisions are not rewritten invisibly.

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 technical review, evidence review, applicability fixtures, limitations, and changelog history before it can move from review to released. At present, every published pack remains in review.

Pack anatomy

Example: bounded autonomous action

AUT-001 applies when a system can perform a financial or consequential action. It does not choose the allowed amount. It asks the user, then compiles the answer into a requirement.

{
  "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

Canonical first, readable second

The compiler emits .agentdirective/agent-directive.json first. Markdown instructions, implementation prompts, status templates, and manifests are derived from the same object so they cannot drift through separate authoring.

{
  "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

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

Report status without overstating it

{
  "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

Privacy boundary

The read-only assessment flow

1. Describe
   Provide a high-level project description

   Mention users, data, integrations, important actions, automation, and AI features.

2. Plan
   Generate a project-specific checklist

   Deterministic matching selects applicable packs, requirements, evidence expectations, and open questions.

3. Inspect
   The coding agent reads the repository locally

   It does not change files and returns only the bounded assessment object.

4. Audit
   Submit sanitized metadata

   The reviewer prioritizes unsupported, contradictory, partial, and unverified claims.

5. Improve
   Return a bounded improvement prompt

   The agent receives the gaps but must still ask the user about every open decision.

Let a connected agent handle the handoff

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.

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.

Call a tool over JSON-RPC

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."
    }
  }
}

Public HTTP routes

Core artifacts

Published schemas

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

Version semantics

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.