159 lines
6.9 KiB
Markdown
159 lines
6.9 KiB
Markdown
# Antigravity CLI Harness
|
||
|
||
|
||
|
||
<p align="center">
|
||
<a href="LISENCE"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="License"></a>
|
||
<img src="https://img.shields.io/badge/Antigravity_CLI-Plugin-purple" alt="Antigravity CLI Plugin">
|
||
<a href="#architectural-patterns"><img src="https://img.shields.io/badge/Patterns-6_Architectures-orange" alt="6 Architectural Patterns"></a>
|
||
<img src="https://img.shields.io/badge/Mode-Agent_Teams-green" alt="Agent Teams">
|
||
<a href="https://github.com/Kyeong1024/antigravity-cli-harness/stargazers"><img src="https://img.shields.io/github/stars/Kyeong1024/antigravity-cli-harness?style=flat&logo=github" alt="GitHub Stars"></a>
|
||
</p>
|
||
|
||
<p align="center">
|
||
<img src="https://img.shields.io/badge/Layer-Meta--Skill-orange" alt="Meta-Skill Layer">
|
||
<img src="https://img.shields.io/badge/Sub--layer-Team_Architecture_Factory-teal" alt="Team Architecture Factory">
|
||
<a href="README.md"><img src="https://img.shields.io/badge/README-EN_|_KO-lightgrey" alt="README languages"></a>
|
||
</p>
|
||
|
||
A meta-skill that turns a one-line domain description into a working multi-agent team for the **Antigravity CLI**.
|
||
|
||
## Quick start
|
||
|
||
**1. Install the harness plugin**
|
||
|
||
Choose the scope that fits your workflow:
|
||
|
||
- **Global install** — available in every Antigravity CLI session:
|
||
```bash
|
||
git clone https://github.com/Kyeong1024/antigravity-cli-harness
|
||
agy plugin install antigravity-cli-harness
|
||
```
|
||
- **Workspace install** — scoped to a single project. Clone the plugin into `.agents/plugins/harness-plugin` in the project root:
|
||
```bash
|
||
git clone https://github.com/Kyeong1024/antigravity-cli-harness .agents/plugins/harness-plugin
|
||
```
|
||
|
||
Workspace definitions take precedence over global ones, so you can iterate on a project-specific harness without touching the global install.
|
||
|
||
**2. Launch Antigravity CLI and request a harness**
|
||
|
||
```bash
|
||
agy
|
||
> Build me a harness for {your-domain}.
|
||
```
|
||
|
||
The `harness` skill auto-triggers and walks you through scaffolding the team — subagents, skills, orchestrator, and the `AGENTS.md` trigger entry.
|
||
|
||
## What it does
|
||
|
||
Tell the harness *"build me a harness for X"* and it scaffolds, in one go:
|
||
|
||
- A **plugin** under `.agents/plugins/{domain}-plugin/`
|
||
- A team of **subagents** (`agents/{name}/agent.json`), each with a defined role, tool set, and system prompt
|
||
- A set of **skills** (`skills/{name}/SKILL.md`) those agents use to do their work
|
||
- An **orchestrator skill** that wires the team into a workflow with explicit data-passing and error-handling rules
|
||
- A pointer entry in **`AGENTS.md`** so future sessions auto-trigger the harness
|
||
|
||
The result is a reusable, evolvable team architecture — not a one-shot script.
|
||
|
||
## Why a harness?
|
||
|
||
Single-agent prompts hit a ceiling once a task crosses multiple specializations (e.g. analysis → build → QA). A harness solves this by:
|
||
|
||
1. **Splitting expertise** into focused subagents, each with its own context window.
|
||
2. **Standardizing collaboration** through a file-based workspace (`_workspace/`) and an orchestrator.
|
||
3. **Surviving across sessions** — definitions live on disk, so the team is reproducible and improvable over time.
|
||
|
||
## Generated structure
|
||
|
||
```
|
||
.agents/
|
||
└── plugins/
|
||
└── {domain}-plugin/
|
||
├── plugin.json
|
||
├── agents/
|
||
│ └── {agent-name}/
|
||
│ └── agent.json # subagent definition
|
||
└── skills/
|
||
├── {orchestrator}/
|
||
│ └── SKILL.md # workflow that wires the team
|
||
└── {skill-name}/
|
||
├── SKILL.md # how a single capability works
|
||
└── rules/ # progressively-loaded references
|
||
AGENTS.md # trigger pointer + change log
|
||
```
|
||
|
||
## Architectural patterns
|
||
|
||
The harness picks one of six team patterns based on the domain:
|
||
|
||
| Pattern | When to use |
|
||
|---|---|
|
||
| **Pipeline** | Sequential, dependent steps |
|
||
| **Fan-out / Fan-in** | Independent work done in parallel |
|
||
| **Expert Pool** | Conditional routing to specialists |
|
||
| **Producer–Reviewer** | Generate then QA in a loop |
|
||
| **Supervisor** | Central agent manages state and dispatch |
|
||
| **Hierarchical Delegation** | Recursive sub-delegation |
|
||
|
||
## Execution modes
|
||
|
||
| Mode | When |
|
||
|---|---|
|
||
| **Subagent** *(default)* | ≥2 specializations collaborating; each runs in an isolated context via `invoke_subagent` |
|
||
| **Parallel subagent** | Independent work to run concurrently |
|
||
| **Direct execution** | Simple, one-shot tasks where agent separation is overhead |
|
||
|
||
## Workflow
|
||
|
||
The meta-skill runs through seven phases:
|
||
|
||
0. **Audit** — detect existing plugins, decide new build vs. extension vs. maintenance.
|
||
1. **Domain analysis** — identify task types, codebase, user skill level.
|
||
2. **Team architecture** — choose execution mode + pattern, split work into specializations.
|
||
3. **Subagent definitions** — write each `agent.json` with role, tools, and I/O protocol.
|
||
4. **Skill creation** — write `SKILL.md` files with pushy, trigger-friendly descriptions and progressive disclosure into `rules/`.
|
||
5. **Orchestration** — wire the team with file-based data passing, error handling, and follow-up support.
|
||
6. **Validation** — structure checks, trigger checks (should-trigger + near-miss), dry-run.
|
||
7. **Evolution** — collect feedback after each run; update agents/skills and log changes in `AGENTS.md`.
|
||
|
||
## Installation
|
||
|
||
Drop the `.agents/plugins/harness-plugin/` directory into any Antigravity CLI project. The `harness` skill auto-triggers on requests like:
|
||
|
||
- "build a harness for {domain}"
|
||
- "set up a harness", "design a harness"
|
||
- "audit / sync the harness", "harness status"
|
||
|
||
## Usage
|
||
|
||
In an Antigravity CLI session:
|
||
|
||
```
|
||
> Build a harness for a content marketing pipeline.
|
||
```
|
||
|
||
The skill will:
|
||
|
||
1. Audit any existing `.agents/plugins/` and `AGENTS.md`.
|
||
2. Propose a team (e.g. researcher → writer → editor → QA) and confirm with you.
|
||
3. Generate the plugin, write `agent.json`/`SKILL.md` files, and register the trigger in `AGENTS.md`.
|
||
4. Run validation and report.
|
||
|
||
Follow-up turns (`"redo the analyst step"`, `"add a security reviewer"`, `"harness audit"`) are handled by the same skill in extension / maintenance mode.
|
||
|
||
## References
|
||
|
||
The skill ships with internal guides under `.agents/plugins/harness-plugin/skills/harness/rules/`:
|
||
|
||
- `agent-design-patterns.md` — pattern catalog, separation criteria
|
||
- `team-examples.md` — full example team definitions
|
||
- `orchestrator-template.md` — orchestrator skeleton with error handling
|
||
- `skill-writing-guide.md` — `SKILL.md` authoring patterns
|
||
- `skill-testing-guide.md` — trigger and execution testing methodology
|
||
- `qa-agent-guide.md` — designing QA subagents
|
||
|
||
## Acknowledgements
|
||
|
||
Ported from [revfactory/harness](https://github.com/revfactory/harness), with rework for Antigravity CLI's plugin and subagent model.
|