Morphness

A self-improving agent harness for Claude Code

🧭 Plan → 🛠️ Build → ✅ QA → 🔁 Retro → ✂️ Prune → 🌍 Share

A ready-made AI coding workflow that starts generic, morphs into your project's own,

and gets better every time someone shares a lesson.

💜 From the community, for the community 💜

🌐 Website · 🚀 Install · ✨ Why · 🧠 How it works · 📦 What you get · 🧰 Make it yours · 🦋 How it morphs · 🌍 Community · 🤝 Contributing

Morphness is an open-source, multi-agent harness for Claude Code:
a set of subagents, CLAUDE.md / AGENTS.md rules, checklists and a review loop for AI coding
agents. If you have been writing those by hand (what people now call harness engineering or
context engineering), Morphness is that work packaged, with a loop that keeps it current.

You talk to a Technical Lead in the main chat. It plans each feature with testable acceptance
criteria and waits for your approval, then hands the work to a Full-stack agent and a mandatory
QA agent. After every feature, a short retrospective turns what went wrong into rules. After
every ten, a prune audits those rules: the ones that caught problems stay, and the ones that never
fire get questioned, then moved out of the rules every session loads.

The harness you have after fifty features is shaped by your project, your stack and how you work.
Rules that prove themselves can also leave your repo as community lessons, so the next team on
your stack starts with them.

[!NOTE]
Morphness was built and run for about 150 features on a real product,
Twinpage. Its starting checklist and its first lessons come from problems
that actually happened there.

✨ Why use it

🚀 Install

🤖 Ask your agent. Copy this into any Claude Code session inside your repo. It works for a new
or an existing project:

Set up the Morphness agent harness in this repo by following
https://github.com/antarsoft/morphness/blob/main/INSTALL.md step by step.
Scan the repo first, then ask me the setup questions one at a time with your suggested answer.
Keep my existing files, install skills or connectors only after I say yes, and put every change
on a new branch for me to review.
If Morphness is already installed here, follow its UPDATE.md instead and show me what changed upstream.

🔌 Or as a plugin:

/plugin marketplace add antarsoft/morphness
/plugin install morphness@morphness
/morph-init

git clone --depth 1 https://github.com/antarsoft/morphness /tmp/morphness
/tmp/morphness/scripts/install.sh /path/to/your/repo   # copies, never overwrites
# then, in Claude Code inside your repo, paste:
#   Follow /tmp/morphness/skills/morph-init/SKILL.md to set up the harness here
# (or install the plugin above and run /morph-init)

The setup (/morph-init, or your agent following INSTALL.md) works for new and ongoing
projects. On an ongoing one, it scans the repo first and suggests answers. Then it asks a short
series of questions, one at a time, each with a suggested answer: what you're building, who
approves, where you run Claude, your stack, the commands behind each check, branches and
environments, who merges, and which optional modules you want. It explains each technical term the
first time it comes up, so you don't need to be a developer to answer. You can also point it at a
brief or fill in an answers file instead.

If the folder isn't a git repository yet, the setup starts one, and it can create the GitHub
repository on your yes. With your yes it also applies branch protection on the host, or gives you
the steps to do it yourself.

It suggests skills, connectors and community lessons that fit your stack, and installs only the ones
you accept. Existing files such as your CLAUDE.md are kept, settings are merged with the diff
shown, and everything lands on a branch for you to review.

• Claude Code with plugins, subagents (the Agent tool) and effort levels.
• Models: opus and sonnet. The legal writer prefers fable and falls back to opus.
• Tools: git and bash. gh for /morph-share to open its PR, and for applying branch
  protection or creating the repository during setup (each has a manual fallback). python3 for the
  feature cost estimate.
• Cost: each feature is about three agent runs (plan, build, QA) plus a short retro, with the
  Technical Lead and Full-stack on opus at high effort by default. Every hand-off ends with a
  Cost ≈ $… line priced at public API rates (harness/MODEL_PRICES.md, editable for your own).
  Tune spend with the medium variants and project/HARNESS_AGENTS.md § Effort per feature.

Your first feature

1. Ask the Technical Lead: plan <feature>.
2. Read the plan and its acceptance criteria, then approve it.
3. It opens a draft PR and delegates the build to Full-stack. QA checks every criterion, and the
   PR is marked ready once it passes.
4. You merge (or let the Technical Lead merge into the integration branch, with merge_by_agent).
   You also get a short retro, the feature's cost, and a steps file for anything only you can do.
   When a connected service's official connector can do a step, the Technical Lead offers to do it
   instead, and runs each action only after your yes.

For a small change, ask for light mode (no feature folder or retro). When you want an answer
rather than a change, ask a question and the Technical Lead uses research mode.

[!TIP]
⭐ If Morphness saves you a rework round, star the repo so more teams find it.

🧠 How it works

flowchart TB
    TL["🧭 Technical Lead plans"] -->|you approve| FS["🛠️ Full-stack builds"]
    FS --> QA{"✅ QA verifies"}
    QA -->|fail| FS
    QA -->|pass| R["🔁 Retro: lessons → rules"]
    R -.->|every 10 features| P["✂️ Prune: keep what fired"]
    P -.-> TL
    P -.->|/morph-share| C[("🌍 Community catalog")]

These are defaults; change any of them (see Make it yours).

Morphness runs in plain Claude Code (CLI, desktop, web). If you use a Claude Project with a
coordinator and threads, the claude-projects module adds a playbook for the Project instructions
and advised settings (coordinator opus · medium, feature threads opus · high).

📦 What you get

🧰 Make it yours

/morph-init writes your answers into harness.config.yml, and you can edit it by hand any time.
Run /morph-doctor afterwards to check the wiring. An abridged example:

branches:
  integration: dev          # feature branches start here and PRs target it
  production: main          # moves only through a release
  default: dev              # the code host's default branch

environments:               # in the order code moves through them; add staging, or keep one
  - { name: dev, branch: dev, deploy: host, real_data: false }
  - { name: production, branch: main, deploy: host, real_data: true }

branch_protection: { enabled: true, required_approvals: 0, delete_merged_branches: true }
merge_by_agent: never       # or integration: the Technical Lead merges ready feature PRs there
release_tags: true          # tag every production merge; false, or per-package for monorepos

modules: [roadmap, data-access, browser-e2e]

checks:                     # commands for each name live in project/CONTROLS.md
  before_qa: [install, typecheck, lint, unit, build]
  before_signoff: [install, typecheck, lint, unit, build, e2e-full]

ci_gate: false              # true: CI on the PR is the gate; false: the QA record is
risk_areas: [auth, billing, migrations]   # never medium effort, always a careful plan

agents:
  fullstack: { model: opus, medium_model: sonnet, default: high, variants: [medium, high, xhigh] }
  qa: { model: sonnet, default: high, variants: [medium, high] }
  researcher: { model: sonnet, high_model: opus, default: medium, variants: [medium, high] }

cost: { track: true, prices: harness/MODEL_PRICES.md }   # estimated $ per feature

loop:
  retro_max_items: 3        # usual action items per retro (soft limit)
  prune_every: 10           # features between prunes
  qa_max_rounds: 2          # QA rework rounds before asking you

Beyond the config, everything is a file in your repo that you own:

🦋 How it morphs

Once installed, the harness belongs to your repo, and the loop is what changes it:

1. 🔁 Retro after each feature: only the action items its findings call for (usually up to
   three, none is fine), each with why it was raised, which the Technical Lead approves, defers or
   skips.
2. 📝 Learnings file per feature.
3. ✂️ Prune every ten learnings files. The rule audit sorts rules into fired, never fired,
   insurance and too new. Rules that earn nothing get cut, and trials (an effort level, a new
   check, a model) are decided by their KPIs. It also shows each feature's cost against the last
   window, checks whether the problem behind each retro item came back, and reads the short
   look-back on research files. Every hand-off ends with a Prune counter: N/10 line, so you see a
   prune coming.

See template/harness/MORPHING.md.

🔄 Staying up to date

Upstream keeps improving too: new modules, sharper process rules, fixes. Nothing upstream ever
overwrites your copy. Instead:

• /morph-update lists what changed in Morphness since your copy last synced and fits your project,
  says why each item matters, and applies only what you accept. A file you never edited takes the
  new version; a file you edited gets a merge that keeps your rules, shown before it's written.
• Every prune runs the same check read-only, so a harness that falls behind gets noticed.
• No plugin? Tell your agent: "Follow https://github.com/antarsoft/morphness/blob/main/UPDATE.md".

Each kit change ships with a short note in updates/, and releases are dated
(CHANGELOG.md).

🌍 Community lessons

💜 From the community, for the community. Your harness learns from your project. The catalog
learns from everyone's.

Each Morphness project runs its own retro and prune loop. When a prune shows a rule actually
fired (it caught a real problem), that rule can leave your repo and help every other team on
a similar stack.

The catalog starts with 112 lessons from Twinpage, the product Morphness was built on. 83 of
them already ship inside the kit as its default rules; the other 29 are stack- and service-specific
and get offered when they match your project. It grows with every PR, and yours would be the
second project in it.

flowchart TB
    A["🧪 Your project: a rule fires"] -->|/morph-share| B["📤 PR with a portable lesson"]
    B -->|maintainer review| C[("📚 Community catalog")]
    C -->|/morph-update| D["🧩 Other projects on your stack"]
    D -.->|their rules fire too| C

The rest are the kit's built-in rules, kept in the catalog so other projects can add their evidence.

How to contribute

1. 📤 Share. After a prune, run /morph-share. It picks the rules that fired, strips anything
   project-specific, and drafts a PR to lessons/.
2. 🔍 Review. A maintainer checks the lesson is new, portable and backed by evidence. Lessons
   are amended, never replaced: your report strengthens an existing lesson when one matches.
3. 📥 Spread. Everyone running /morph-update sees the new lesson if it matches their stack,
   and picks whether to take it.

A new lesson needs evidence (a fired count from a prune audit) to get in. See CONTRIBUTING.md and lessons/README.md.

🏗️ Built with Morphness

Products and projects that run on a Morphness harness. Add yours with a one-row PR (see
CONTRIBUTING.md § Showcase).