# Antigravity CLI Harness

![Antigravity CLI](docs/images/antigravity-cli.png)

<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.
