AGENTS.md

This file provides guidance to AI coding agents (Claude Code, Cursor, Copilot, Antigravity, etc.) when working with code in this repository.

Repository Overview

agent-harness is a production-grade collection of engineering skills and specialist agent personas for AI coding assistants (Claude Code, Cursor, Copilot, Gemini CLI, and others). Skills are step-by-step workflows that encode what senior engineers do consistently. Agent personas are specialist roles that apply those skills from a specific engineering perspective.

Agent Personas

twelve specialist personas are available in agents/. Each persona adopts a single engineering role and operates within its curated skill scope.

Architecture: Command → invokes Agent persona → persona invokes Skill(s).

Each persona's Composition block (in its .md file) lists its curated skill scope — the 20 skills it may invoke. When an agent is active, invoke a skill from its scope by name: Use skill <skill-name> to.... Skills outside an agent's scope can be invoked manually or via a slash command at any time. The full scope registry is at scripts/agent-scopes.json.

OpenCode Integration

OpenCode uses a skill-driven execution model powered by the skill tool and this repository's /skills directory.

Core Rules

• If a task matches a skill, you MUST invoke it
• Skills are located in skills/<skill-name>/SKILL.md
• Never implement directly if a skill applies
• Always follow the skill instructions exactly (do not partially apply them)

Intent → Skill Mapping

When the user describes a task without naming an agent or command, map their words to the right agent and entry-point skill. The using-agent-harness skill handles routing automatically — the table below is the reference.

API & Integration

Keywords: API, endpoint, REST, GraphQL, OpenAPI, Swagger, versioning, rate limiting, JWT, OAuth, pagination, contract, webhook, idempotent, CRUD, HTTP method, request/response schema → api-developer → api-and-interface-design, spec-driven-development

Database & Data Storage

Keywords: database, schema, table, migration, SQL, query, index, slow query, PostgreSQL, MySQL, MongoDB, Redis, ORM, Prisma, Drizzle, normalization, foreign key, join, NoSQL, transaction → db-architect → database-design, database-migration

Infrastructure, CI/CD & Deployment

Keywords: Docker, Kubernetes, Terraform, CI/CD, pipeline, deploy, container, GitHub Actions, GitOps, Helm, secrets, environment variables, IaC, SLO, incident, monitoring, alerting, blue-green, canary → senior-devops → ci-cd-and-automation, git-workflow-and-versioning

Frontend & UI

Keywords: component, React, Next.js, Vue, Tailwind, CSS, HTML, UI, UX, accessibility, WCAG, keyboard navigation, state management, Zustand, Redux, re-render, bundle, design system, responsive, animation → senior-frontend-engineer → frontend-ui-engineering, react-best-practices

Cloud Architecture

Keywords: cloud, AWS, Azure, GCP, multi-region, disaster recovery, high availability, IAM, cost optimization, serverless, Lambda, Cloud Run, CloudFormation, auto-scaling, Well-Architected, VPC, vendor lock-in → senior-cloud-architect → cloud-architect, documentation-and-adrs

Backend Services

Keywords: backend, service, microservice, async, message queue, Kafka, RabbitMQ, cache, Redis, gRPC, Go, Golang, Node.js, Python, FastAPI, Django, circuit breaker, background job, event sourcing, CQRS, worker → senior-backend-engineer → backend-architect, api-and-interface-design

AI / ML Features

Keywords: AI, LLM, GPT, Claude, Anthropic, prompt, RAG, vector, embedding, fine-tuning, agent, LangChain, LangGraph, evaluation, hallucination, guardrail, tool use, function calling, semantic search, chatbot → ai-ml-engineer → spec-driven-development, llm-app-patterns

Code Review & Quality

Keywords: review, check my code, is this good, feedback, before merge, pull request, PR, refactor, simplify, code smell, technical debt → code-reviewer → code-review-and-quality

Security

Keywords: security, vulnerability, audit, XSS, SQL injection, CSRF, auth bypass, secure, harden, OWASP, CVE, token, password, encryption, sensitive data, prompt injection → security-auditor → security-and-hardening

Testing

Keywords: test, coverage, failing test, bug proof, unit test, integration test, E2E, Cypress, Playwright, Jest, pytest, mock, stub, test suite → test-engineer → test-driven-development

QA Verification

Keywords: verify, QA, does this work, check if it works, make sure nothing is broken, confirm the fix, regression check, validate the feature, feature verification, working as expected, verify all fixes, end-to-end check, smoke test, sanity check, verify all the fixes are in place, is this working, confirm this is fixed → senior-qa-engineer → quality-assurance

Web Performance

Keywords: slow, performance, LCP, INP, CLS, Core Web Vitals, Lighthouse, bundle size, lazy load, render blocking, TTFB, page speed → web-performance-auditor → performance-optimization

General Feature / New Functionality

Keywords: build, implement, add, create, new feature (without a domain keyword above) → spec-driven-development, then domain agent, then incremental-implementation, test-driven-development

Planning / Breakdown

Keywords: plan, break down, tasks, roadmap, how do I approach, where do I start → planning-and-task-breakdown

Bug / Error

Keywords: bug, broken, error, not working, unexpected, crash, failing, regression, something is wrong, why is this happening, root cause → systematic-debugging

Simplification / Cleanup

Keywords: simplify, clean up, reduce complexity, too complex, hard to read, refactor → code-simplification

Receiving Code Review Feedback

Keywords: someone reviewed my code, here are review comments, PR has comments, reviewer said, feedback on my PR, address these comments, code review feedback → receiving-code-review

Requesting a Code Review

Keywords: request a review, ready for review, submit for review, ask for feedback, PR is ready, want someone to review → requesting-code-review

Finishing a Branch

Keywords: I'm done, implementation complete, finished the feature, ready to merge, done with the branch, all tests pass, wrap this up, close this out → finishing-a-development-branch

Verification / Completion Claims

Keywords: it works, I think it's done, looks good, should be fixed, seems to work, I believe this is correct, done → verification-before-completion

Writing a Plan

Keywords: plan this, how should I approach, break this down, map this out, before I start, let me plan, write a plan for → planning-and-task-breakdown

Executing a Plan

Keywords: execute the plan, follow the plan, implement the plan, carry out the steps, run through the plan → subagent-driven-development

Brainstorming

Keywords: brainstorm, ideas for, what are the options, how could we, explore approaches, what are the possibilities, think through → brainstorming

Lifecycle Mapping (Implicit Commands)

OpenCode does not support slash commands like /spec or /plan.

Instead, the agent must internally follow this lifecycle:

• DEFINE → spec-driven-development
• PLAN → planning-and-task-breakdown
• BUILD → incremental-implementation + test-driven-development
• VERIFY → debugging-and-error-recovery
• REVIEW → code-review-and-quality
• SHIP → shipping-and-launch

Execution Model

For every request:

1. Determine if any skill applies (even 1% chance)
2. Invoke the appropriate skill using the skill tool
3. Follow the skill workflow strictly
4. Only proceed to implementation after required steps (spec, plan, etc.) are complete

Anti-Rationalization

The following thoughts are incorrect and must be ignored:

• "This is too small for a skill"
• "I can just quickly implement this"
• "I’ll gather context first"

Correct behavior:

• Always check for and use skills first

This ensures OpenCode behaves similarly to Claude Code with full workflow enforcement.

Orchestration: Personas, Skills, and Commands

This repo has three composable layers. They have different jobs and should not be confused:

• Skills (skills/<name>/SKILL.md) — workflows with steps and exit criteria. The how. Mandatory hops when an intent matches.
• Personas (agents/<role>.md) — roles with a perspective and an output format. The who.
• Slash commands (.claude/commands/*.md) — user-facing entry points. The when. The orchestration layer.

Composition rule: the user (or a slash command) is the orchestrator. Personas do not invoke other personas. A persona may invoke skills.

The only multi-persona orchestration pattern this repo endorses is parallel fan-out with a merge step — used by /ship to run code-reviewer, security-auditor, and test-engineer concurrently and synthesize their reports. Do not build a "router" persona that decides which other persona to call; that's the job of slash commands and intent mapping.

See docs/agents.md for the decision matrix and references/orchestration-patterns.md for the full pattern catalog.

Claude Code interop: the personas in agents/ work as Claude Code subagents (auto-discovered from this plugin's agents/ directory) and as Agent Teams teammates (referenced by name when spawning). Two platform constraints align with our rules: subagents cannot spawn other subagents, and teams cannot nest. Plugin agents silently ignore the hooks, mcpServers, and permissionMode frontmatter fields.

Creating a New Skill

Directory Structure

skills/
  {skill-name}/           # kebab-case directory name
    SKILL.md              # Required: skill definition
    scripts/              # Required: executable scripts
      {script-name}.sh    # Bash scripts (preferred)
  {skill-name}.zip        # Required: packaged for distribution

Naming Conventions

• Skill directory: kebab-case (e.g. web-quality)
• SKILL.md: Always uppercase, always this exact filename
• Scripts: kebab-case.sh (e.g., deploy.sh, fetch-logs.sh)
• Zip file: Must match directory name exactly: {skill-name}.zip

SKILL.md Format

---
name: {skill-name}
description: {One sentence describing what the skill does, followed by one or more "Use when" trigger conditions. Include trigger phrases like "Deploy my app" or "Check logs" when helpful.}
---

# {Skill Title}

{Brief overview of what the skill does and why it matters.}

## How It Works

{Numbered list explaining the skill's workflow}

Equivalent headings like `Workflow`, `Core Process`, or `When to Use` are fine when they communicate the same structure clearly.

## Usage (Optional)

Include this section only if the skill ships runnable helpers under `scripts/`. Markdown-only skills can omit both the section and the directory entirely.

```bash
bash /mnt/skills/user/{skill-name}/scripts/{script}.sh [args]

Arguments:

• arg1 - Description (defaults to X)

Examples: {Show 2-3 common usage patterns}

Output

{Show example output users will see}

Present Results to User

{Template for how Claude should format results when presenting to users}

Troubleshooting

{Common issues and solutions, especially network/permissions errors}

### Best Practices for Context Efficiency

Skills are loaded on-demand — only the skill name and description are loaded at startup. The full `SKILL.md` loads into context only when the agent decides the skill is relevant. To minimize context usage:

- **Keep SKILL.md under 500 lines** — put detailed reference material in separate files
- **Write specific descriptions** — helps the agent know exactly when to activate the skill
- **Use progressive disclosure** — reference supporting files that get read only when needed
- **Prefer scripts over inline code** — script execution doesn't consume context (only output does)
- **File references work one level deep** — link directly from SKILL.md to supporting files

### Script Requirements

- Use `#!/bin/bash` shebang
- Use `set -e` for fail-fast behavior
- Write status messages to stderr: `echo "Message" >&2`
- Write machine-readable output (JSON) to stdout
- Include a cleanup trap for temp files
- Reference the script path as `/mnt/skills/user/{skill-name}/scripts/{script}.sh`

### Creating the Zip Package

After creating or updating a skill:

```bash
cd skills
zip -r {skill-name}.zip {skill-name}/

End-User Installation

Document these two installation methods for users:

Claude Code:

cp -r skills/{skill-name} ~/.claude/skills/

claude.ai: Add the skill to project knowledge or paste SKILL.md contents into the conversation.

If the skill requires network access, instruct users to add required domains at claude.ai/settings/capabilities.