yuxiaowang-520/harness-craft

---

This repository is built around a simple belief:

The biggest failure mode in agent-driven development is not intelligence — it is system instability.

Most teams don’t get blocked because the model “can’t write code”. They get blocked because:

These are not prompt problems. They are engineering system problems.

Quick Navigation

Core Idea

The goal is not to add one more clever prompt. The goal is to upgrade agent work into a system that is:

Prompt Tricks vs. Engineering Systems

Quick Start

One-Command Install (Recommended)

Platform At A Glance

[!TIP] New here? Install the flagship profile first. It gives you the smallest complete system: persistent context, long-run execution, controlled collaboration, and learned knowledge.

Why Codex Uses AGENTS.md

Claude has a native rules/ layer. Codex does not. In Codex, the always-on equivalent is AGENTS.md, so the installer renders the same guardrails into a managed AGENTS.md block.

That means:

• Claude: rules stay as short markdown files under ~/.claude/rules/ or .claude/rules/
• Codex: the same rule layer is installed into ~/.codex/AGENTS.md or .codex/AGENTS.md

In both cases, the end result is the same: always-on guardrails with no manual invocation once installed.

Manual Install (Fallback)

If you prefer not to use the installer, skills can still be copied manually.

# Claude skills
mkdir -p ~/.claude/skills
cp -R skills/repo-bootstrap ~/.claude/skills/
cp -R skills/longrun-dev ~/.claude/skills/
cp -R skills/learn ~/.claude/skills/
cp -R skills/agent-team-dev ~/.claude/skills/

# Codex skills
mkdir -p ~/.codex/skills
cp -R skills/repo-bootstrap ~/.codex/skills/
cp -R skills/longrun-dev ~/.codex/skills/
cp -R skills/learn ~/.codex/skills/
cp -R skills/agent-team-dev ~/.codex/skills/

Claude rules can also be installed manually:

mkdir -p ~/.claude/rules
cp -r rules/common ~/.claude/rules/
cp -r rules/python ~/.claude/rules/   # pick your language

# Or project-level (current project only)
mkdir -p .claude/rules
cp -r rules/common .claude/rules/

For Codex guardrails, prefer scripts/install.py because Codex needs AGENTS.md management rather than direct rules/ copying.

Once installed, the AI agent will automatically:

The 4 Flagship Skills

If you only try four things from this repo, start here:

---

repo-bootstrap

Protects context. The real power of this skill is not generating a few documents — it turns repo understanding from hidden background knowledge into an explicit, persistent workspace.

What problem it actually solves

An agent needs more than source code to work effectively. It also needs to know:

• What the user is actually trying to achieve
• What decisions have already been made
• How the repo is actually built, tested, and deployed
• What is still unknown or uncertain
• Whether the current plan still matches execution reality

When this information lives only in chat history, it is extremely fragile. One session switch, one parallel thread, one agent handoff — and facts mix with assumptions.

Architecture

This skill splits repo cognition into six durable artifacts:

• .harness/state.json: machine-readable single source of truth
• .harness/memory.md: ongoing working memory
• .harness/prompt.md: user intent, constraints, explanation history
• .harness/repowiki.md: repo facts — directories, commands, environment
• .harness/plan.md: design approach, assumptions, risks, validation paths
• .harness/checklist.md: real execution ledger — file changes, validation status

These responsibilities must stay separated:

Why this design is strong

1. It doesn’t pretend automation can replace understanding. Scripts can auto-detect languages, frameworks, commands, config files and directory structure — but that automation only builds the skeleton. It doesn’t claim to provide deep understanding.

2. It treats update rules as governance, not suggestions. memory.md and prompt.md should be updated every session; repo fact changes must be reflected in repowiki.md; non-trivial implementations must sync plan.md and checklist.md.

3. It manages unknowns explicitly. A mature memory system records not only what is known, but also what is still unknown, how to discover it, and what should not be assumed by default.

This makes the system more honest, and much easier to hand off.

---

longrun-dev

Keeps long tasks on track. Most agent demos excel at showing how work starts. The real difficulty is controlling how work continues.

Why long tasks fail most often

Once a task spans many sessions, highly predictable failure modes emerge:

• The agent doesn’t know where it left off last time
• The baseline is already broken, but it keeps building on top of the damage
• Feature scope drifts silently across rounds
• Progress is narrative only — no structure
• The model feels done, but the system has zero completion evidence

These problems can’t be solved by adding another paragraph that says “please work carefully.” They require state files, recovery entry points, execution order, completion criteria, and scope throttling.

Architecture

This skill generates a longrun harness inside the target repo:

• .longrun/init.sh: dependency setup and smoke checks
• .longrun/feature_list.json: feature definitions with pass/fail status
• .longrun/progress.md: append-only session progress log
• .longrun/session_state.json: current recovery state and session info

The most important point: long-task state becomes a repo asset, not a conversation asset.

Control model

Why it embodies real “systems thinking”

The most powerful idea in this skill is not complexity — it is restraint.

“One feature per session” looks simple, but it is one of the highest-leverage control points for agents. The most common advanced failure mode is not that agents can’t do the work — it’s that they do too much, too broadly, beyond the original task boundary.

This skill cuts long-horizon tasks into a series of verifiable, recoverable, accountable units. At the end of each session, the system can re-evaluate:

• Is the baseline healthy?
• Is the scope stable?
• Is the evidence sufficient?

This is the kind of engineering constraint that long-running autonomous development actually needs.

---

agent-team-dev

Governs multi-agent collaboration. The hardest problem in multi-agent systems is not parallel capacity — it is boundary governance.

What problem it actually solves

Multi-agent workflows spiral out of control because:

• Multiple agents edit the same files with no clear ownership
• Everyone is analyzing, but nobody owns final integration authority
• Review happens too early, or is too broad
• The main thread loses its role as the single source of truth

Without governance, multi-agent just amplifies single-agent instability.

Architecture

This skill deliberately keeps the team in a small, explicit topology:

Mode selection

How it differs from “role-play” multi-agent

It doesn’t indulge in the theatrics of multi-agent — it returns to the fundamentals of engineering organization:

• The main thread must retain a Team Lead
• Parallelism is not the default — it is a risk-driven choice
• Roles exist for responsibility isolation, not for appearances
• Review must be independent, and must happen after integration
• There can only be one source of truth

The point of this skill is not “more agents = smarter” — it’s “multiple agents must be governed first.”

---

learn

Makes agents smarter over time. Every conversation between a developer and an agent contains high-value knowledge: corrections, patterns, facts, preferences. Without a learning system, this knowledge evaporates when the session ends. The agent starts from zero next time, and the user has to teach the same things again.

What problem it actually solves

• The agent was corrected last session — “don’t mock the database” — and this session it mocks it again
• The user has said “keep responses concise” three times, but the agent is still verbose
• The project has a specific deploy pipeline, and it needs to be re-explained every time
• User coding preferences (naming style, architecture patterns) are never remembered

Architecture

This skill is built around one core belief: conversations are a gold mine of reusable knowledge that gets wasted every time a session ends. What the user teaches the agent should be systematically preserved.

Four knowledge types, prioritized

1. Corrections — user corrected the agent’s approach (highest value). These represent mistakes the agent made and must never repeat.
2. Patterns — repeated workflow or coding convention. E.g., “in this project, always run lint before commit.”
3. Facts — project/environment-specific truths. E.g., “CI uses Node 20”, “deploy requires staging approval.”
4. Preferences — user’s personal style choices. E.g., “keep responses concise”, “write comments in Chinese.”

Strength evolution model

One of the most carefully designed aspects of learn. Knowledge is not permanently valid once saved — it needs to be validated, strengthened, and can be overturned:

New knowledge created → strength: weak, confirmed: 0
  ↓ Applied once without user correction
strength: weak, confirmed: 1
  ↓ Applied again without correction
strength: medium, confirmed: 2
  ↓ Repeatedly validated
strength: strong, confirmed: 4+
  ↓ User explicitly confirms ("yes, exactly")
strength: strong (immediate jump)

User says “no, that’s wrong” → downgrade or delete. No automatic decay — knowledge doesn’t disappear just because it hasn’t been used recently. Stale knowledge is cleaned up through /learn-review.

This is more practical than floating-point confidence: weak/medium/strong is enough to distinguish “first observation” from “thoroughly validated” without forcing the system to split hairs between 0.47 and 0.52.

Scope isolation and promotion

Knowledge is stored at two levels:

• Project (.claude/learned/ or .codex/learned/): project-specific knowledge, the default destination
• Global (~/.claude/learned/ or ~/.codex/learned/): cross-project universal knowledge

Promotion rules are deliberately conservative: only when a project-scoped entry reaches strength = strong and its content contains no project-specific references will the system suggest promotion — but the user always confirms.

Why not auto-promote? Because the cost of false promotion (polluting global scope) far exceeds the cost of missed promotion (teaching it again in another project).

User experience design

“Getting smarter over time” can’t just be a technical fact — the user must feel it:

• Every /learn run clearly reports what was learned, what was skipped, and why
• When the agent makes a different decision based on learned knowledge, it says so:

  “Using real database for integration tests (learned: don’t mock DB)”

• /learn-review shows cumulative statistics: 23 global entries / 12 project entries
• New sessions announce: “Loaded 8 project entries and 15 global entries”

Why it works: Conversations are full of knowledge that agents lose between sessions. This skill turns that loss into lasting growth. Two commands, Markdown files, three strength tiers, and a quality gate — simple enough to actually use, transparent enough to trust, and structured enough to compound over time.

How learned knowledge actually takes effect

The learn skill only stores knowledge — it does not auto-load. To close the loop, install the assistant’s always-on guardrail layer:

• Claude Code: install the learned-knowledge rule from rules/common/
• Codex: install harness-craft’s managed AGENTS.md block via scripts/install.py

Once installed, the agent will automatically load and apply accumulated knowledge in future sessions. The full pipeline:

/learn → saves knowledge files → always-on guardrails auto-load them next session → agent applies and cites

Without that always-on layer, /learn still extracts knowledge, but future sessions won’t use it automatically. See Quick Start and the Rules Reference for installation details.

How the Stack Fits Together

flowchart LR
    A[repo-bootstrapPersist repo memory] --> B[longrun-devControl long-running execution]
    B --> C[agent-team-devCoordinate parallel work]
    A --> C
    C --> D[Verified deliverywith evidence and handoff]
    D --> E[learnExtract & accumulate knowledge]
    E -->|next session| A

• repo-bootstrap makes the agent remember the project
• longrun-dev makes the agent stay on track
• agent-team-dev makes multiple agents cooperate without chaos
• learn makes the agent get smarter over time

Skills vs Rules

This repo provides two complementary systems:

In short: Rules are the agent’s instincts. Skills are the agent’s learned expertise. Claude and Codex expose the always-on layer differently, but the design goal is the same.

Rules Reference

Rules take effect automatically after installation. In Claude they live in rules/; in Codex the same guardrails are rendered into AGENTS.md.

Common Rules (all languages)

Python Rules (.py/.pyi files only)

Full Skill Inventory

Beyond the flagship quartet, the repo includes a broader reusable library:

Recommended Operating Order

For serious repo work, a strong default is:

1. Install skills and rules (see Quick Start)
2. Use repo-bootstrap to make repo knowledge persistent
3. Use longrun-dev when the task will span multiple sessions
4. Use learn after productive sessions to accumulate knowledge
5. Use agent-team-dev only when bounded parallelism is worth the coordination cost
6. Layer on domain-specific skills after the operating system is in place

Companion skills by category:

• Architecture: api-design, backend-patterns, frontend-patterns, coding-standards
• Quality: tdd-workflow, e2e-testing, verification-loop, security-review
• Research: deep-research, openai-docs, article-writing
• Delivery: gh-address-comments, gh-fix-ci, yeet, linear

Who This Is For

• Builders who want agents to act more like durable collaborators than chat assistants
• Teams running multi-step implementation, testing, and delivery through agents
• Engineers who care about handoff quality, verification discipline, and controlled autonomy
• Anyone who has felt that agent workflows are impressive in demos but unreliable in production

Contributing

Contributions are welcome. The standard is practical usefulness.

A good contribution should:

• Solve a recurring real-world problem
• Have clear trigger conditions
• Define a concrete workflow, not generic advice
• Include scripts or references when they materially improve execution
• Rules should stay short (10–50 lines each) — move long workflows to skills

---