Write harnesses
A harness is a package that references many other resources, together with your organization's working conventions. To write one, you need to be a Member or above in the organization, and every resource you plan to include must already be released on Tara.
What does a harness contain?
A harness works like a distribution: installing one gives you a complete working environment. It holds a list of agents, skills, prompts, and kits with version constraints. It also holds working conventions that are inserted into the project's CLAUDE.md, default settings for .claude/settings.json, and project template files such as .bandum.json.
Directory layout
harness-web/
├── .claude-plugin/
│ └── plugin.json
├── template/
│ ├── CLAUDE.md
│ ├── settings.json
│ └── .bandum.json
├── docs/
│ ├── cai-dat.md
│ └── su-dung.md
├── README.md
└── CHANGELOG.mdtemplate/CLAUDE.md is required, and a harness must have dependencies. Plugins don't load a CLAUDE.md at the root, so put all conventions in template/.
Declare plugin.json
{
"name": "harness-web",
"version": "1.0.0",
"description": "Web development environment: role-based agents and an S/M/L workflow",
"author": { "name": "Platform team" },
"dependencies": [
{ "name": "agent-dev", "version": "~1.1.0" },
{ "name": "agent-reviewer", "version": "~1.1.0" },
{ "name": "skill-sdlc", "version": "^1.2.0" },
{ "name": "kit-scm-github", "version": "^1.3.0" }
],
"metadata": {
"forge": {
"schema": 1,
"type": "harness",
"org": "acme",
"owners": ["owner@example.com"],
"roles": ["Dev", "Reviewer", "Test"],
"engines": ["claude-code"],
"status": "active",
"model": "sonnet-std",
"docs": [
{ "type": "install", "path": "docs/cai-dat.md", "title": "Installation guide" },
{ "type": "usage", "path": "docs/su-dung.md", "title": "Usage guide" }
]
}
}
}Use ~1.1.0 for agents so they receive only patches and the environment stays stable. For skills and kits whose interface rarely changes, ^1.2.0 is reasonable. To move to a new minor version of an agent, release a new version of the harness. That way, your environment changes only when the harness changes.
model is the default model alias, looked up in the catalog. Tara rejects an alias that isn't in the catalog.
Write template/CLAUDE.md
This file holds the conventions that go into the CLAUDE.md of every project that uses the harness. Keep it short and imperative, and make every rule verifiable.
## AI workflow (harness-web)
- Branch `feature/<ISSUE-ID>-<description>`; commit `<ISSUE-ID> <short description>`; never push directly to the main branch.
- Give each issue exactly one label `type: feature|bug|debt|risk`.
- Never put secrets, tokens, or customer data in code, prompts, or commits.When a user runs ph init, Phillip inserts this content into a block marked phillip:begin … phillip:end. Running it again replaces only what's inside the block, and anything the user wrote outside the block is kept.
Write template/settings.json
Phillip merges this file into the project's .claude/settings.json. It keeps values the user already set and merges lists. The example below blocks reads of auto-generated directories to save context.
{
"permissions": {
"deny": ["Read(./node_modules/**)", "Read(./dist/**)"]
}
}Bundled docs
Kits and harnesses must have install and usage docs. Other types are only recommended. Declare them in metadata.forge.docs, as in the example above. Tara separates the docs from the install package, stores them per version, and puts their sha256 in the digital signature. Users read them with ph tara docs harness-web.
Check, submit, and try
First, check and submit.
ph tara check ./harness-web
ph tara publish ./harness-webAfter approval, try it on a clean project.
ph init harness-web
ph tara listIf everything is correct, ph tara list shows all the versions locked in phillip.lock, including indirect dependencies.
Troubleshooting
If Tara reports a harness needs template/CLAUDE.md, add that file, and don't put a CLAUDE.md at the root. If it reports dependency "…" is not on Tara (not released, or private), that resource isn't released or is private. If it reports no version of "…" satisfies constraint "…", your constraint is too tight for the released versions. If you get a warning about a dependency with no constraint, add ~ or ^.