Agent Starter Kit

Speak naturally. A Maestro agent breaks your request into tasks and routes each one to a specialized AI model.

The scaffold for a fully customizable, multi-model AI harness in pure natural language. The smartest model orchestrates the workflow while cheaper/faster ones handle the less complicated bits, extending your premium coding plan (such as Claude Code).

It's model-agnostic: orchestrate from Claude, plan on GLM, review on Qwen, or any combination you want.

Setup

1. Run the installer via npx:

   cd /path/to/your/project
   npx @gugamistri/harness

   This creates the .agent/ directory with all framework files and a symlink AGENTS.md in the project root.

2. Start the AI agent (e.g., claude, or whatever CLI you use).

3. Say "Please comply with AGENTS.md." — this boots the Maestro and loads the framework.

4. The Maestro orchestrates everything. On first run, it automatically dispatches the Contextualizer to map the codebase.

5. Customize — add personas, rules, skills, and providers to fit your project (see Customization below).

How It Works

The Maestro is the conductor. It receives user requests, decomposes them, and dispatches work to specialized personas:

• Architect — plans implementations, defines before/after states
• Coder — writes software following the plan
• Reviewer — checks work for correctness and quality
• Contextualizer — documents project structure for orientation

Each persona has an identity (who they are), a playbook (what they do), a handoff format (what they deliver), and red lines (what they must not do). Each persona also declares a preferredModel — the Maestro uses this to route work to the right provider automatically.

Structure

personas/    Specialized AI roles (who does the work)
rules/       Constraints organized by authority level
skills/      Reusable procedures and protocols

Slash Commands

The framework provides custom slash commands for supported CLIs:

| Command | Description | |---------|-------------| | /plan | Plan a feature with the Architect | | /code | Write code with the Coder | | /review | Review work for quality | | /test | Run tests and report results | | /fix | Fix errors with recovery protocol | | /refactor | Refactor code safely | | /context | Update codebase context | | /docs | Update documentation | | /commit | Commit with proper message | | /memory | Manage long-term memory | | /spec | Create feature spec |

Commands are installed in:

• .opencode/commands/ for OpenCode CLI
• .claude/commands/ for Claude Code

Rules Hierarchy

• Commandments — absolute, never bypassed
• Edicts — authoritative within scope, not bent
• Counsel — wise guidance, may be deviated from with justification

Skills

Skills codify procedures that personas reference. They answer "how to do X" so personas can focus on "what to do."

• agent-memory — long-term memory across sessions
• boot — session startup sequence
• context-maintenance — schema and rules for .context.md files
• dispatch — how the Maestro assembles and sends work to personas.
• task-tracking — file-based to-do for multi-step work

Customization

• Dispatch — edit skills/dispatch.md to match your CLI agents. The Providers table and CLI Dispatch section are pre-configured for Claude Code and opencode (Qwen). Add rows for any other provider/model you use.
• Add new personas to personas/ following the schema in personas/README.md
• Add rules to rules/commandments/, rules/edicts/, or rules/counsel/
• Add skills to skills/ following the schema in skills/README.md
• Modify existing files to match your project's needs

Each directory has a README with the full schema definition.

FAQ

Why this over other harnesses?

Frameworks like GSD, HumanLayer, and OpenDev are software — they require a programming language, dependencies, and runtime integration. This kit is pure natural language. Every persona, rule, and skill is a Markdown file. There is no code to install, no SDK to learn, no build step to maintain.

Other harnesses are bulldozers — heavy with built-in packages, skills, and guidance that consume tokens every session, even when most of it is irrelevant to your project. This kit is a scalpel: minimal by design, meant to be extended with your own tailored personas, rules, and skills. You pay only for the context you actually need. Add a persona by writing a .md file. Change a rule by editing a line. Swap a provider by updating a table row.

Why multi-model?

Coding plans are routinely quantized and rate-limited weeks after launch — the version you fell in love with gradually loses sharpness as the provider optimizes for throughput. A multi-model harness fights this in three ways:

1. Resilience. Spreading work across providers means you're less affected when any single plan degrades. If one provider tightens limits or loses quality, shift that persona's preferredModel to another row in the Providers table.
2. Token conservation. The orchestrator (Maestro) only handles routing and decomposition. Token-heavy roles like Architect and Coder are delegated to other capable models, so your premium plan lasts longer.
3. Fresh eyes. Different models catch different things. A reviewer running on a separate provider will flag issues that the coder's model normalized.

What do I need to run this?

A coding plan or API key for each provider you route to. We recommend coding plans — Claude Code (Anthropic), Codex (OpenAI), and Alibaba Model Studio (Qwen) offer flat-rate pricing with generous token allowances designed for agentic workflows. API keys work too, but plans are more cost-effective for sustained use. Each provider needs its CLI tool installed (e.g., claude for Claude Code, opencode for Qwen). If you only route to one provider, one plan is enough.

How does the Maestro use multiple models from a single CLI?

The dispatch skill (skills/dispatch.md) handles this automatically. When a persona's preferredModel matches the host runtime (e.g., you're running Claude Code and the persona wants claude), the Maestro dispatches natively using the host's built-in subagent mechanism (e.g., the Task tool). When the preferredModel points to a different provider (e.g., qwen), the Maestro shells out to that provider's CLI tool (e.g., opencode) by piping the assembled prompt via stdin. The Providers table in skills/dispatch.md maps each model to its CLI — add rows for any provider you want to use.

Can I use this with just one model?

Yes. Set every persona's preferredModel to your host runtime (e.g., claude) and the framework runs entirely within a single provider. You still benefit from the structured decomposition, review pipeline, and long-term memory — just without the multi-model routing.

How should I assign models to personas?

Each persona declares a preferredModel in its frontmatter — this is what the Maestro uses to route work. Keep premium models as the orchestrator (Maestro makes routing decisions and manages context — short, high-leverage interactions worth the cost). For the rest, match the model to the persona's job using role-specific benchmarks:

• Coder — LiveCodeBench (real-world coding tasks)
• Architect — Artificial Analysis Long Context Reasoning (multi-step reasoning across large contexts)
• Reviewer — IFBench (instruction following and constraint verification)

These benchmarks are examples — new ones emerge frequently. Pick whatever benchmark best measures the capability each role needs, then set preferredModel accordingly in the persona's frontmatter.

Does the framework auto-update?

Yes. On every session start, the boot sequence runs npx @gugamistri/harness update. If the update brings changes, the Maestro reads the changelog, purges any long-term memory entries that the update made obsolete, and reboots with the new instructions.

What does "model-agnostic" mean? Which models are supported?

Any model with a CLI tool that can accept a prompt via stdin works. As a quality floor, we recommend models scoring 1300+ ELO on GDPval-AA — a benchmark for general-purpose reasoning. Below that threshold, personas may struggle with multi-step tasks.