Agent Harness

A lightweight, file-based operating system for AI coding agents. Drop it into any repo and get a repeatable workflow for shipping features with AI — from spec to plan to implementation to verification to release.

Works with any agent that can read files, write files, and run commands: Claude Code, Cursor, Codex, Windsurf, or anything else.

Why

Most people use AI coding tools like smarter autocomplete. That works for tiny tasks. It breaks the moment the work becomes multi-step, stateful, or spread across frontend, backend, tests, and release notes.

The fix is not a better prompt. The fix is a better operating environment — durable instructions, reusable skills, file-based memory, and a human-in-the-loop verification cycle.

That is what this repo provides.

Structure

.agent/
  AGENTS.md                          # Global rules, roles, guardrails, stopping conditions
  SKILLS/
    saas-spec-to-plan/SKILL.md       # SaaS: spec -> implementation plan
    saas-implement-feature/SKILL.md  # SaaS: execute approved plan in chunks
    saas-browser-qa/SKILL.md         # SaaS: verify UI flows in browser
    saas-regression-guard/SKILL.md   # SaaS: expand test coverage around changes
    saas-release-notes/SKILL.md      # SaaS: prepare release summary

    cli-spec-to-plan/SKILL.md        # CLI: spec -> command-oriented plan
    cli-command-implementer/SKILL.md # CLI: implement commands with predictable UX
    cli-fixture-validator/SKILL.md   # CLI: validate with fixtures and snapshots
    cli-release-packager/SKILL.md    # CLI: prepare for shipping

    mcp-spec-to-plan/SKILL.md        # MCP: spec -> tool-by-tool plan
    mcp-tool-designer/SKILL.md       # MCP: implement tools with strict schemas
    mcp-schema-validator/SKILL.md    # MCP: validate schemas and behavior
    mcp-example-client/SKILL.md      # MCP: generate usage examples

    mobile-spec-to-plan/SKILL.md     # Mobile: spec -> screen-and-flow plan
    mobile-screen-implementer/SKILL.md # Mobile: implement screen by screen
    mobile-flow-qa/SKILL.md          # Mobile: verify user flows
    mobile-state-guard/SKILL.md      # Mobile: harden loading/error/empty states

docs/
  TASK.md                            # The original task or feature request
  PLAN.md                            # Step-by-step plan (generated before coding)
  QA.md                              # Verification notes and test results
  RELEASE.md                         # Release summary and rollout notes

tests/
  fixtures/                          # Test fixtures and snapshots

CHANGELOG.md                         # Running log of meaningful changes

The Loop

Every product type uses the same core workflow:

Write the task in docs/TASK.md
Generate a plan — agent writes docs/PLAN.md
Review and approve the plan
Implement in chunks — agent codes 3 steps max, then stops
Verify — agent runs tests/QA and writes docs/QA.md
Release prep — agent writes docs/RELEASE.md

Quick Start

1. Copy into your repo

cp -r .agent/ /path/to/your/project/.agent/
cp -r docs/ /path/to/your/project/docs/

2. Write a task

Edit docs/TASK.md with a concrete feature request.

3. Ask the agent to plan

Read docs/TASK.md. Use the correct planning skill for this project type.
Write a detailed implementation plan to docs/PLAN.md. Do not edit code yet.

4. Approve the plan

Review docs/PLAN.md. Edit scope if needed. Mark it approved.

5. Implement

Use the correct implementation skill. Execute the next 3 approved steps
from docs/PLAN.md. Update tests and CHANGELOG.md. Stop after the chunk.

6. Verify

Use the relevant verification skill. Write results to docs/QA.md.
Highlight broken states, regressions, or missing coverage.

7. Release

Use the release skill. Read the plan, QA notes, and changelog.
Write release notes and rollout notes to docs/RELEASE.md.

Skill Packs

Pick the skills that match your product:

Product Type	Skills	Focus
SaaS Web App	`saas-*`	Full-stack features, routes, auth, browser QA
CLI Tool	`cli-*`	Commands, flags, output formats, exit codes
MCP Server	`mcp-*`	Tool schemas, strict interfaces, usage examples
Mobile App	`mobile-*`	Screens, navigation, state transitions, permissions

You can use multiple packs in the same repo if your project spans surfaces.

Customization

Add new skills — create a folder under .agent/SKILLS/ with a SKILL.md
Edit guardrails — modify .agent/AGENTS.md to match your team's rules
Extend verification — add project-specific checks to the QA skills
Add roles — define new roles in AGENTS.md for your workflow

License

MIT

agent-harness

Specs

README