nl-spec-driven — Summary

nl-spec-driven is a markdown-only, zero-framework educational repository that demonstrates spec-driven AI coding agent control through four files: SPEC.md (execution contract), TASKS.md (deterministic units of work), AGENTS.md (agent behavior constraints), and EXECUTION_GATE.md (human-in-the-loop checklist). It ships no code, no CLI, no agent runtime — just versioned markdown templates that engineers copy into real repositories and use during AI-assisted implementation. The philosophy is that AI coding failures stem from implicit decisions during execution; by defining intent, scope, and constraints in a spec first and enforcing human approval gates at scope boundaries, execution becomes deterministic and auditable. The examples/ directory contains production-grade templates for all four files.

Differs from seeds: This is the most minimal framework in the batch — a pure Archetype 4 "Markdown scaffold, zero primitives" equivalent, analogous to agent-os and claude-conductor in the seed set. Unlike agent-os (which ships 5 commands to write the markdown) or claude-conductor (which has a GitHub Actions harness), nl-spec-driven ships only the markdown templates themselves with no tooling whatsoever. The EXECUTION_GATE.md pattern (4-section human approval checklist) is a sharper formalization of human gates than any seed provides. Closest seed: agent-os, but nl-spec-driven has no commands, no scripts, and 2 stars vs agent-os's 4,646.

nl-spec-driven — Overview

Origin

GitHub: ElliotOne/nl-spec-driven-ai-assisted-coding-agent-control (2 stars, 0 forks, MIT). Author: ElliotOne. Last pushed 2026-02-13. No code, only markdown.

Philosophy

From README:

"This project focuses on one core idea: the model should execute only what a versioned specification allows."

"Most AI coding failures in production come from implicit decisions made during execution."

The controlled alternative:

"Define intent, scope, and constraints in a spec first. Break work into deterministic tasks. Separate planning from execution. Enforce human approval gates for boundary crossings. Keep agent authority explicit and narrow."

This is described as a markdown-only control-plane project:

"No application code. No framework dependency. No orchestration runtime requirement."

Recommended Execution Flow

From README:

1. Update the spec before implementation
2. Approve boundaries and escalation conditions
3. Execute exactly one task
4. Validate output against task verification and spec constraints
5. If requirements change, modify spec first, then continue

Design Principles

• Keep specs short and explicit to reduce ambiguity
• Treat anything not written in spec or tasks as out of scope
• Use examples as templates, not fixed policy
• Human approval required at scope boundary crossings
• "One task at a time" — agents are constrained to serial execution

nl-spec-driven — Architecture

Distribution

• Type: Markdown template set (methodology doc)
• Install: Copy files into project repo
• License: MIT
• Language: None (markdown only)

Install

# Copy templates to your project
cp SPEC.md /path/to/your/project/
cp TASKS.md /path/to/your/project/
cp AGENTS.md /path/to/your/project/
cp EXECUTION_GATE.md /path/to/your/project/
# Edit to match your project

Directory Tree

nl-spec-driven-ai-assisted-coding-agent-control/
  AGENTS.md              # Agent behavior constraints
  SPEC.md                # Project execution contract
  TASKS.md               # Deterministic task definitions
  EXECUTION_GATE.md      # Human approval checklist
  README.md              # Usage guide
  LICENSE
  examples/
    AGENTS.example.md    # Production-grade agent template
    SPEC.example.md      # Full spec template with escalation
    TASKS.example.md     # Task template with verification criteria
    EXECUTION_GATE.md    # (note: no .example suffix in index)

Core Files

Required Runtime

None — works with any AI coding agent that reads files.

Target AI Tools

Any AI coding agent that reads markdown files: Claude Code, Cursor, Copilot, Codex, ChatGPT, etc.

nl-spec-driven — Components

Files (4 core templates)

SPEC.md

• Project context
• Scope (included/excluded)
• Constraints (Always/Ask First/Never)

Example:

## Constraints
Always:
- Run tests
- Follow naming conventions

Ask First:
- Schema changes
- API changes

Never:
- Commit secrets
- Modify pipelines

TASKS.md

• Deterministic task definitions
• File lists per task
• Verification criteria per task

Example:

## Task 1: Input Validation
Files: src/InputValidator.cs
Verification: Tests pass, invalid input rejected

## Requirements:
- Reject empty input
- Reject input exceeding max length

AGENTS.md

• Agent execution behavior constraints
• "Follow SPEC.md exactly. Execute one task at a time. Ask when uncertain."

EXECUTION_GATE.md

4-section human approval checklist:

• Gate 1: Scope — Changed files match task file list; no excluded areas modified
• Gate 2: Constraints — No new dependencies; no API/schema/pipeline changes without approval
• Gate 3: Verification — Required tests run; task criteria satisfied
• Gate 4: Traceability — Code changes map to written requirements; no implicit feature additions

Example Templates (4 in examples/)

Production-grade versions of all core files with:

• examples/SPEC.example.md — Full spec with scope boundaries, escalation conditions, change-control flow
• examples/TASKS.example.md — Deterministic task templates with file lists, concrete requirements, verifiable checks
• examples/AGENTS.example.md — Scoped multi-agent role definitions (Builder, Reviewer, Test) with shared control rules
• examples/EXECUTION_GATE.example.md — Human approval checklist (same as top-level EXECUTION_GATE.md)

Commands / Skills / Hooks

None. This is a methodology framework without any tooling.

nl-spec-driven — Uniqueness

Differs from Seeds

Pure Archetype 4 "Markdown scaffold, zero primitives." Most similar to claude-conductor (0/0/0/0 components, templates) and agent-os (markdown workflow files), but even more minimal: 4 files vs agent-os's 5 commands + scripts. The key distinction from other minimal frameworks is the EXECUTION_GATE.md pattern — a 4-section human approval checklist (Scope, Constraints, Verification, Traceability) that formalizes the human-in-the-loop review step more explicitly than any seed. Claude-conductor has a P0/P1 error ledger as first-class artifact; agent-os has a standards/ directory with style guides. nl-spec-driven has nothing beyond the 4 control files and their example templates. Unlike SPEC-KIT (which automates spec validation with hooks), nl-spec-driven relies entirely on human discipline.

Positioning

• Target user: Engineers who want the minimum viable spec-driven process with no dependencies
• Key differentiator: EXECUTION_GATE.md 4-gate checklist — the most explicit human approval gate formalization in the batch
• Deliberate minimalism: "No application code. No framework dependency. No orchestration runtime requirement." This is the anti-framework framework.

Observable Failure Modes

1. No enforcement: Everything depends on the AI following SPEC.md and the human completing EXECUTION_GATE.md — no automated enforcement
2. 2 stars, 0 forks: Near-zero adoption signal; educational content not yet battle-tested in production
3. No session continuity: Each task requires manually providing SPEC.md and AGENTS.md again
4. Example quality ceiling: The example files are very simple (5-10 lines); production use requires significant customization
5. No version control for spec changes: SPEC.md updates happen without a changelog or diff tracking mechanism