nfa-spec

NFA - Nonfunctional, Functional, Agentic

The specification and review gate you run before a coding agent writes code.

NFA is an agent-first implementation standard for services, integrations, automations, internal tools, focused applications, and runtime-agent products.

It turns product intent into three ordered acts:

Act	Purpose	Primary question
1. Foundation and global invariants	Architecture, security, data, reliability, diagnostics, and build constraints	What must every feature respect?
2. Vertical feature slices	Complete user or operator outcomes with interfaces, data deltas, failures, proof, and rollout together	What can one agent build and prove without reconstructing the document?
3. Assembly, progressive QA, and operations	End-to-end journeys, release gates, rollback, hypercare, and decisions	How does the complete system ship and survive?

The standard includes three reusable skills and a deterministic review gate:

write-nfa
  -> review-nfa
       -> deterministic audit
       -> independent specialist mesh
       -> adversarial challenge
       -> NFA_REVIEW.md
       -> hash-bound NFA_REVIEW.json
  -> build-from-nfa
       -> verifies ready attestation and unchanged NFA
       -> builds one approved vertical slice

build-from-nfa refuses missing, stale, conditional, or non-ready reviews.

Readiness is always for the full current NFA document set. A build command may name a slice only to confirm that the slice exists under that full-document attestation.

Quick start

Install the three skill folders using your coding agent's normal skill installation method. For a Codex repository, check them into .agents/skills:

.agents/skills/write-nfa/
.agents/skills/review-nfa/
.agents/skills/build-from-nfa/

Then:

1. Invoke $write-nfa and complete the requirements interview.
2. Invoke $review-nfa in a separate session or independent subagent workflow.
3. Resolve every blocker and major finding.
4. Rerun $review-nfa until NFA_REVIEW.json says ready.
5. Invoke $build-from-nfa for one approved slice.
6. Invoke $build-from-nfa for every implementation-changing request where an NFA exists, including fixes, migrations, configuration, refactors, and deployment changes.
7. Rerun affected review passes after every substantive NFA or reviewed-context change.

Invocation syntax varies by agent. If an agent does not support skills, direct it to read the relevant SKILL.md as binding instructions.

Repository map

Path	Purpose
NFA_TEMPLATE.md	Canonical NFA v2 template
CHECKLIST.md	Canonical readiness checklist
skills/write-nfa/	Requirements interview and vertical-slice drafting
skills/review-nfa/	Multi-agent pressure test and review attestation
skills/review-nfa/references/REVIEW_PROTOCOL.md	Role rubrics, severity, finding schema, and synthesis rules
skills/review-nfa/scripts/nfa_review.py	Deterministic audit, attestation, and stale-review verification
skills/build-from-nfa/	Attestation enforcement and one-slice implementation
examples/garmin-companion.NFA.md	Complete hypothetical data collector and PWA example
tests/	Standard-library tests for the deterministic gate

The root template and checklist are canonical. Matching copies bundled with the applicable skills keep each skill self-contained and must remain byte-for-byte identical.

Why the document is vertical

Horizontal requirements documents separate interfaces, rules, acceptance criteria, data, and implementation plans into distant chapters. Humans can navigate that with meetings and institutional knowledge. Coding agents must reconstruct the feature from scattered context each time.

An NFA v2 slice keeps one capability together:

Outcome and scope
Flow and state model
Surface and rendering contract
Interface contract
Rules and failure behavior
Data and migration delta
Runtime-agent contract
Diagnostic hooks
Verification and evidence gate
Mocks and live replacement gate
Rollout, rollback, and checkpoint

Global invariants remain in Act 1 so security, privacy, data integrity, and reliability are not duplicated differently across slices.

For four or more slices, or when one file becomes difficult to review in a single pass, use:

NFA.md
nfa/slices/S00-foundation.md
nfa/slices/S01-first-outcome.md
nfa/slices/S02-next-outcome.md

The root file remains the manifest and authority. Slice files reference global requirement IDs rather than copying global prose.

Authority and delivery priority

Both are rankings, but they answer different questions.

Authority resolves conflicting statements:

Authority	Meaning
A0	Law, safety, privacy, security, and data integrity
A1	Confirmed product decisions and external contracts
A2	Global system invariants
A3	Slice-level binding requirements
A4	Preferences and optional behavior
A5	Assumptions, proposals, and open questions

Delivery priority controls sequence and scope:

Priority	Meaning
P0	Establishes or protects the usable system
P1	Required for the current release outcome
P2	Planned after the current release gate
P3	Optional or experimental

A P0 convenience feature cannot override an A0 protection. Same-authority changes supersede older requirements only through an explicit decision-log entry.

How the review mesh works

The first pass combines deterministic and semantic review.

The deterministic audit checks:

• NFA file discovery and stable hashing
• Unresolved placeholders and TODO markers
• Duplicate requirement definitions
• Missing authority and modality
• Required slice metadata and sections
• Requirement-to-acceptance mapping
• Open-question ownership and blocked slices

Independent specialist reviewers pressure-test different failure surfaces:

• Business analyst
• Product manager
• Technical lead
• QA lead
• Security and privacy reviewer
• Product designer, who may confirm that presentation is external or not applicable
• DevOps/SRE reviewer, who may confirm that deployment and operations are not applicable
• Data and migration reviewer when state persists
• Runtime-AI reviewer when the product contains model calls

One final challenger tries to disprove the synthesis, find shared blind spots, detect scope expansion, and catch fixes that create new contradictions.

Each finding must cite exact evidence, describe a triggering condition and concrete failure, propose replacement text, identify owner decisions, and use one of three severities:

• blocker: unsafe, contradictory, unfalsifiable, or non-implementable
• major: requires a consequential assumption or likely material rework
• minor: bounded clarity, diagnostics, traceability, or maintainability gap

Generic advice, compliments, unsupported best practices, and hypothetical future features are not findings.

Every selected reviewer works in a fresh context with no inherited drafting history and no peer communication. The gate derives required roles from the NFA and a complete coverage matrix, rather than trusting command-line role declarations. It records each reviewer run and every accept, merge, or rejection disposition so final findings have raw-review provenance.

Review attestation

review-nfa creates two artifacts beside the specification:

NFA_REVIEW.md
NFA_REVIEW.json

The JSON attestation contains:

• Hash and manifest of every authoritative NFA file
• Hash of the human-readable review
• Scope, reviewed context, and the reviewed repository commit where applicable
• Derived reviewer roles and fresh-context evidence
• Findings and counts
• Derived verdict

The attestation command requires a final-findings file and a review-evidence file. Evidence contains coverage, runs, and dispositions. For against-code and release scope it also requires one or more context paths and a git root. release additionally requires durable release evidence.

First derive the current hashes and required reviewer set:

python3 skills/review-nfa/scripts/nfa_review.py prepare <nfa-path> \
  --scope specification \
  --output <review-inputs.json>

Use the same context arguments on prepare and attest. Reviewer envelopes must use the generated nfa_hash and context_hash.

python3 skills/review-nfa/scripts/nfa_review.py attest <nfa-path> \
  --findings <final-findings.json> \
  --evidence <review-evidence.json> \
  --scope specification \
  --report-output <path-to-NFA_REVIEW.md> \
  --output <path-to-NFA_REVIEW.json>

For implementation comparison, add --scope against-code --context-path <path> --git-root <repository-root>. For release, add --scope release, the same context arguments, and --release-evidence <release-evidence-file>. Release evidence is JSON with release_id, timezone-aware observed_at and expires_at, migration_identity, and configuration_fingerprint; it stops verifying after expiry. The command generates NFA_REVIEW.md; do not hand-edit the generated report.

The evidence file has this shape:

{
  "coverage": [
    {"role": "business-analyst", "selected": true, "trigger": "always", "omission_reason": null},
    {"role": "data-migration", "selected": false, "trigger": "not applicable", "omission_reason": "N/A - no persistent state."}
  ],
  "runs": [
    {
      "role": "business-analyst",
      "run_id": "ba-01",
      "nfa_hash": "<current-nfa-hash>",
      "scope": "specification",
      "context_hash": "<current-context-hash>",
      "phase": "first-pass",
      "isolation": {"fresh_context": true, "inherited_history": false, "peer_communication": false},
      "findings": []
    }
  ],
  "dispositions": [],
  "synthesis": {
    "meaningful_dissent": [],
    "maintenance_risk": "The most likely first-month maintenance source and why.",
    "next_action": "The exact next action justified by the verdict."
  }
}

Use the full schema and role rubrics in REVIEW_PROTOCOL.md. There are no --reviewers, --review-mode, or partial-attestation arguments.

Verdicts are mechanical:

• not_ready: at least one blocker
• conditional: zero blockers and at least one major
• ready: zero blockers, zero majors, complete derived reviewer coverage, fresh independent reviewer contexts, and current NFA, context, evidence, and report hashes

Changing any NFA file, reviewed context, evidence, report, or attestation invalidates verification. A report-only editorial correction can regenerate the report and re-attest with unchanged current findings and evidence. A substantive NFA, code, context, or release-evidence change requires the deterministic audit and affected reviewer passes to be rerun before a new attestation. build-from-nfa verifies the ready full-document attestation before editing implementation:

python3 skills/build-from-nfa/scripts/nfa_review.py verify <nfa-path> \
  --slice <slice-id> \
  --require-scope specification

Runtime agents and coding agents

Keep these separate.

Runtime-agent contracts live inside the slice that ships the model behavior. They define evidence, tools, permissions, output validation, stop conditions, failure states, evaluations, and rollback.

Build-agent protocol lives in Act 1. It defines context, ownership, isolation, parallelism, implementation budget, review gates, and what happens after failed proof.

N/A or None by design is valid runtime-agent behavior when a deterministic implementation better serves the outcome.

Practical rules

• Keep the NFA with the deployable unit, not in a separate workspace the coding agent will never read.
• Tell AGENTS.md, CLAUDE.md, or the equivalent to read the NFA before implementation.
• Write a design change into the NFA before changing implementation.
• Never record success before the represented external work is confirmed.
• Never treat an empty response as proof that a failed dependency returned no data.
• Make safety mechanisms report their own failure through an independent path.
• Treat mocks as local evidence only until their named live gate passes.
• Mark implementation status from evidence, not intended work.

NFA is intentionally narrower than a universal SRS. Regulated or safety-critical work still needs its domain-specific compliance and assurance artifacts.

Origin

Written by Arthur Grishkevich at Alchemail, based on requirements patterns used across production automations and agent-built services.

MIT licensed. Fork it, adapt it to your stack, and open a PR when you improve it.