Narness is an AI Workspace Engineering framework for making AI coding agents work inside repositories that are understandable, progressively discoverable, deterministic, and provable.
The project started from a simple harness-engineering principle:
If a rule can be enforced by code, hooks, scripts, a compiler, Git, or CI, do not leave that rule only in a prompt.
That principle remains the Enforcement Plane of Narness. The broader goal is to design the entire repository as an execution environment for agents.
AI Workspace
=
Context Architecture
+ Capability Architecture
+ Constraint Architecture
+ Evidence Architecture
+ Lifecycle Orchestration
A good workspace does not depend on an agent remembering everything. It provides the right context at the right time, exposes procedures as discoverable capabilities, turns important rules into deterministic checks, derives the proof required for a change, and blocks unproven states from authoritative history.
AI WORKSPACE
|
+---------------------+----------------------+
| | |
Instructions Capabilities Evidence
| | |
AGENTS / scoped Skills / tools Tests / checks
Rules / approval Scripts / assets Snapshots / E2E
| | |
+---------------------+----------------------+
|
Orchestration
|
Hooks -> Git hooks -> CI -> Review -> Release
|
v
Authoritative Repository
See docs/architecture.md for the complete model.
Narness treats an AI workspace as three independent design problems.
Root instructions
-> scoped instructions
-> skill metadata
-> SKILL.md
-> task-relevant references / scripts / assets
The question is: what should the agent know now?
Root AGENTS.md / CLAUDE.md files are contracts and routers, not encyclopedias. Procedures belong in Skills. Historical design reasoning belongs in ADRs or design notes.
L0 Prompt
L1 AGENTS / convention
L2 Skill
L3 Agent hook
L4 Deterministic script
L5 Language / tool-native rule
L6 Git lifecycle gate
L7 Server-side CI / repository ruleset
The question is: where should this rule be guaranteed?
Discover
-> Understand
-> Change
-> Fast feedback
-> Pre-push proof
-> PR evidence
-> Review
-> Land
-> Release
The question is: when should the workspace intervene?
Edit-time hooks should be fast and corrective. Local Git hooks should provide the smallest sufficient proof. CI is the repository authority and owns authoritative proof.
| Concept | Responsibility |
|---|---|
| Workspace Contract | Global invariants, approval boundaries, project structure, and routing |
| Knowledge Plane | Separates standing rules, procedures, and design decisions |
| Capability Plane | Packages procedures as discoverable Skills with progressive disclosure |
| Enforcement Plane | Sinks rules from prompts into hooks, scripts, native rules, Git, and CI |
| Evidence Architecture | Defines what proves a change correct for its behavioral surface |
| Lifecycle Orchestration | Runs the right evidence at edit, commit, push, CI, review, and release time |
A checkpoint is not just a command:
Checkpoint
=
Invariant
+ Scope
+ Evidence
+ Executor
+ Failure Feedback
Narness keeps long-lived research and design questions under docs/topics/.
Topics are intentionally different from canonical architecture documents. They are places to accumulate investigation, reference implementations, competing designs, experiments, and evolving conclusions. When a conclusion becomes stable, it should graduate into the main architecture, adoption guides, Skills, scripts, examples, or CI.
Current topics:
| Topic | Focus |
|---|---|
| AI Workspace | The repository as an agent execution environment: context, capabilities, constraints, evidence, and lifecycle orchestration. |
| Harness Engineering | How instructions, Skills, hooks, deterministic checks, Git, CI, and repository rules shape reliable agent behavior. |
| Engineering Surfaces | How one semantic model can route context before a change and derive constraints and evidence after a change. |
| Agent-Native Repository Architecture | How repositories can optimize for agent-first consumability while preserving human auditability and one canonical source of truth. |
| Change-to-Evidence Planning | How a repository change becomes an explainable set of affected Surfaces, evidence obligations, evidence records, and proof gates. |
This structure is expected to grow as Narness research expands into areas such as progressive context disclosure, capability architecture, evidence architecture, quality gates, and agent observability.
.
├── README.md
├── CLAUDE.md
├── docs/
│ ├── architecture.md
│ ├── adoption.md
│ └── topics/
│ ├── README.md
│ ├── ai-workspace/
│ ├── harness-engineering/
│ ├── engineering-surfaces/
│ ├── agent-native-repository-architecture/
│ └── change-to-evidence-planning/
├── examples/
│ └── rust-workspace/
├── plugins/
│ └── narness/
├── cli/
├── narness-policy/
└── scripts/
└── narness-repo-english.sh
Narness currently ships:
- a Claude Code plugin with a
narnessSkill and progressive reference material; - edit-time
PostToolUsefeedback for Rust compilation; - single-responsibility Rust validation scripts;
- shared Git hook entrypoints for commit, commit-message, and push gates;
- copyable Rust tool and GitHub Actions configuration;
- a CLI that validates runtime prerequisites from
.narness.toml; - a policy engine prototype;
- a runnable Rust workspace example showing the AI Workspace pattern.
The current implementation is Rust-first. The architecture is language-independent.
narness plan is the next architectural direction, not a shipped command yet. Its proposed contract is documented in docs/architecture.md: change set -> affected surfaces -> required evidence -> execution plan.
claude plugin marketplace add https://github.com/BestNathan/narness-engineering
claude plugin install narnessDeclare requirements in .narness.toml:
[[checks]]
type = "version"
name = "node"
min = "22"
[[checks]]
type = "exists"
name = "rg"Then run:
npx narness
npx narness --jsoncargo test --manifest-path examples/rust-workspace/Cargo.toml
bash plugins/narness/scripts/narness-rust-fmt.sh examples/rust-workspace
bash plugins/narness/scripts/narness-rust-check.sh examples/rust-workspace
bash plugins/narness/scripts/narness-rust-test-unit.sh examples/rust-workspace --scope=full
bash plugins/narness/scripts/narness-rust-test-integration.sh examples/rust-workspace --scope=fullThe example contains a root workspace contract, a task Skill with progressive disclosure, unit and integration evidence, an environment declaration, and a stable CI required gate.
Start with docs/adoption.md:
- write a small root Workspace Contract;
- move task procedures into Skills;
- express checks as single-responsibility executable primitives;
- mount fast checks in agent and Git hooks;
- map change surfaces to required evidence;
- make CI the authoritative full-scope gate;
- expose one stable required status to repository rules.
- Prefer deterministic enforcement over prompt-only requirements.
- Keep root instructions small and route to scoped knowledge.
- Load Skill metadata broadly, Skill instructions selectively, and supporting detail lazily.
- Keep executable validation primitives single-responsibility.
- Put validation logic in scripts or native tools; orchestration layers only decide when and at what scope to run them.
- Optimize local proof for relevance and speed; optimize CI proof for authority.
- Fail loud. A failed check must say where, why, and how to fix it.
- Keep repository-authored content in English.