Create AI Harness

Markdown-based AI workflow scaffold for coding projects.

create-ai-harness installs a small, model-agnostic .ai/ context system plus a compact AGENTS.md protocol. Its goal is to help AI coding assistants use less context, avoid hallucinations, document stable project facts, and stop wasting tokens on repeated validation loops.

Why This Exists

AI coding tools often lose time and tokens because they:

• reload too much context for every task,
• guess project architecture instead of reading stable notes,
• repeat failed tests or package warnings,
• forget local commands and conventions,
• leave useful project knowledge trapped in one chat session.

This harness gives the assistant a concrete workflow and a tiny project memory layer that can be reused across tools and sessions.

Who Can Use It

Use this in any repository where AI agents help with development:

• solo developers using Codex, Cursor, Claude Code, Copilot, or other agents,
• teams that want consistent AI workflows across projects,
• agencies maintaining many client repositories,
• open source maintainers who want AI agents to understand project rules quickly,
• developers trying to reduce token usage and repeated context loading.

The system is plain Markdown. It is not tied to one vendor or model.

What It Installs

AGENTS.md
.ai/
  ACTIVE_TASK.md
  README.md
  architecture.md
  commands.md
  context-map.md
  conventions.md
  decisions.md
  known-issues.md
  project-context.md
  self-improvement.md
  testing.md
  workflow.md

Core files:

• AGENTS.md: short universal protocol for AI assistants.
• .ai/context-map.md: tells the model which context to load for each task.
• .ai/project-context.md: purpose, stack, package manager, repo shape.
• .ai/commands.md: real install/build/test/lint commands.
• .ai/architecture.md: non-obvious architecture and data flow.
• .ai/testing.md: validation commands and retry budget.
• .ai/ACTIVE_TASK.md: temporary scratchpad, overwritten per task.

Installation

Run in the root of your project:

npx @francove/create-ai-harness

The CLI detects common project metadata from files like package.json, lockfiles, workspace config, source folders, and test dependencies. It then fills the dynamic .ai/ files with initial project-specific context.

Usage

After installation, tell your AI coding assistant to follow AGENTS.md.

Example prompt:

Follow AGENTS.md and use the .ai harness. Fix the failing build with the smallest safe diff.

For normal development tasks, the assistant should:

1. Start at .ai/context-map.md.
2. Load only the routed context needed for the task.
3. Inspect source files only after minimal context is loaded.
4. Implement the smallest useful change.
5. Validate with commands from .ai/commands.md.
6. Update .ai/ only when the new knowledge will help future tasks.

Metrics

Audit the installed harness:

npx @francove/create-ai-harness metrics

Example output:

AI Harness Metrics
AGENTS.md: 41 lines
.ai files: 12
.ai total: 100 lines
largest file: AGENTS.md 41 lines
approx context: 1321 tokens
placeholders: 0
context budget: yes
validation budget: yes
score: good

Use this to track whether the harness stays compact. The key signals are:

• low .ai total lines,
• no placeholders,
• context budget present,
• validation budget present,
• ACTIVE_TASK.md stays short,
• no oversized context files.

Common Use Cases

Bootstrap AI Context In A New Project

npx @francove/create-ai-harness

The CLI creates the harness and fills initial context from the project structure.

Standardize AI Workflows Across Repos

Install the harness in each repository so every AI assistant follows the same workflow: plan lightly, load minimal context, validate safely, and preserve reusable project knowledge.

Reduce Token Usage

The context map prevents the assistant from reading every doc file by default. It starts with only the relevant .ai/ files, then moves to source inspection.

Avoid Infinite Test Loops

The validation budget tells agents to run each validation once, retry only after relevant changes, and stop on repeated failures or warnings-only success.

Preserve Project Knowledge

Stable discoveries go into .ai/:

• real commands,
• architecture that is not obvious from source,
• conventions that repeat across the codebase,
• important decisions,
• known recurring issues.

Temporary notes, history, generic framework facts, and obvious source details should not be stored.

Updating An Existing Harness

Run the installer again:

npx @francove/create-ai-harness

Behavior:

• AGENTS.md is treated as canonical and replaced with a backup.
• Dynamic .ai/ files are preserved when they already contain real project data.
• Placeholder-like dynamic files are regenerated from current project metadata.

Design Principles

• Markdown only.
• Vendor agnostic.
• Minimal context first.
• Source files beat broad docs.
• Context is dynamic, compact, and project-specific.
• No fixed limit on how many .ai/ files can change; value and size are the constraint.
• Validation has a retry budget to prevent token waste.

CLI Commands

# install or update harness
npx @francove/create-ai-harness

# aliases
npx @francove/create-ai-harness init
npx @francove/create-ai-harness install

# audit context size and health
npx @francove/create-ai-harness metrics

Best Practices

• Keep .ai/ files short.
• Replace stale facts instead of appending history.
• Do not store information that is obvious from source code.
• Keep ACTIVE_TASK.md temporary and overwrite it every task.
• Run metrics after large AI-assisted tasks to catch context drift.

License

ISC