Using Agent Harness

Using Agent Harness

This meta-skill is both a pre-flight checker and an intent router. It enforces skill usage before any response, then routes the user's intent to the correct agent persona and skill scope.

Instruction Priority

User instructions always take precedence:

1. User's explicit instructions (CLAUDE.md, GEMINI.md, AGENTS.md, direct requests) — highest priority
2. This skill — overrides default system behavior where they conflict
3. Default system prompt — lowest priority

Pre-Flight Rule (Mandatory)

Before responding to anything — including clarifying questions — invoke the relevant skill first.

If there is even a 1% chance a skill is relevant, YOU ABSOLUTELY MUST invoke it. This is not negotiable. This is not optional. You cannot rationalize your way out of this.

digraph skill_flow {
    "User message received" [shape=doublecircle];
    "About to enter plan mode?" [shape=doublecircle];
    "Already brainstormed?" [shape=diamond];
    "Invoke brainstorming skill" [shape=box];
    "Might any skill apply?" [shape=diamond];
    "Invoke the skill" [shape=box];
    "Announce: 'Using [skill] to [purpose]'" [shape=box];
    "Has checklist?" [shape=diamond];
    "Create a todo per item" [shape=box];
    "Follow skill exactly" [shape=box];
    "Respond (including clarifications)" [shape=doublecircle];

    "About to enter plan mode?" -> "Already brainstormed?";
    "Already brainstormed?" -> "Invoke brainstorming skill" [label="no"];
    "Already brainstormed?" -> "Might any skill apply?" [label="yes"];
    "Invoke brainstorming skill" -> "Might any skill apply?";

    "User message received" -> "Might any skill apply?";
    "Might any skill apply?" -> "Invoke the skill" [label="yes, even 1%"];
    "Might any skill apply?" -> "Respond (including clarifications)" [label="definitely not"];
    "Invoke the skill" -> "Announce: 'Using [skill] to [purpose]'";
    "Announce: 'Using [skill] to [purpose]'" -> "Has checklist?";
    "Has checklist?" -> "Create a todo per item" [label="yes"];
    "Has checklist?" -> "Follow skill exactly" [label="no"];
    "Create a todo per item" -> "Follow skill exactly";
}

Red Flags

These thoughts mean STOP — you are rationalising. Invoke the skill instead.

Skill Priority

When multiple skills could apply, use this order:

1. Process skills first (brainstorming, systematic-debugging) — these determine HOW to approach the task
2. Implementation skills second (frontend-design, mcp-builder) — these guide execution

"Let's build X" → brainstorming first, then implementation skills. "Fix this bug" → systematic-debugging first, then domain-specific skills.

Skill Types

Rigid (TDD, systematic-debugging): Follow exactly. Don't adapt away the discipline.

Flexible (patterns): Adapt principles to context.

The skill itself tells you which type it is.

User Instructions

Instructions say WHAT, not HOW. "Add X" or "Fix Y" doesn't mean skip workflows.

Post-Implementation Gate (Mandatory)

After any file edit — before claiming the task is done — verification is required.

This gate is as non-negotiable as the Pre-Flight Rule. Skipping it is the exact failure mode this harness was built to prevent.

Files edited (Write / Edit / NotebookEdit called)
        ↓
UI / auth / functional change?
        ↓ yes                          ↓ no
Run /verify                     Run the relevant test / build command
Open app in browser             Show actual command output
Confirm:                              ↓
  • No console errors           State actual result with evidence
  • No Failed to fetch              ↓
  • Forms submit correctly      Claim completion
  • No regressions
        ↓
Claim completion

Completion phrases that are BLOCKED without prior /verify:

What /verify means for UI tasks:

• Open the affected page in a browser
• Check browser console (zero errors, zero Failed to fetch)
• Exercise the changed flow (form submit, tab switch, auth redirect, etc.)
• Scroll to check no layout regressions

Two Entry Paths (Both Supported)

Path 1 — Slash commands (explicit, backwards-compatible): Users can always invoke a command directly. Commands route straight to their skill — no agent lookup needed.

Commands are always valid. When a user types one, follow it directly — skip the intent routing below.

Path 2 — Intent routing (natural language): When a user describes what they want to build, fix, or review — without using a slash command — match their words against the keyword table below to determine:

1. Which agent to invoke (the who)
2. Which skill to start with (the how)
3. Which command applies (the when)

Intent → Agent → Skill Routing Table

API & Integration Work

Trigger words: API, endpoint, REST, GraphQL, OpenAPI, Swagger, versioning, rate limiting, JWT, OAuth, pagination, contract, webhook, idempotent, CRUD, HTTP, request/response

→ Agent: api-developer → Start with skill: api-and-interface-design or spec-driven-development → Command: /spec then /build

Database & Data Storage

Trigger words: database, schema, table, migration, SQL, query, index, PostgreSQL, MySQL, MongoDB, Redis, ORM, Prisma, Drizzle, normalization, foreign key, join, slow query, NoSQL

→ Agent: db-architect → Start with skill: database-design or database-migration → Command: /spec then /build

Infrastructure, CI/CD & Deployment

Trigger words: Docker, Kubernetes, Terraform, CI/CD, pipeline, deploy, container, GitHub Actions, GitOps, Helm, secrets, environment variables, infrastructure, IaC, Ansible, SLO, incident, monitoring, alerting

→ Agent: senior-devops → Start with skill: ci-cd-and-automation or docker-expert → Command: /build or /ship

Frontend & UI

Trigger words: component, React, Next.js, Vue, Tailwind, CSS, HTML, UI, UX, accessibility, WCAG, keyboard navigation, state management, Zustand, Redux, re-render, bundle, design system, dark mode, responsive, animation

→ Agent: senior-frontend-engineer → Start with skill: frontend-ui-engineering or react-best-practices → Command: /spec then /build

Cloud Architecture

Trigger words: cloud, AWS, Azure, GCP, multi-region, disaster recovery, high availability, IAM, cost optimization, serverless, Lambda, Cloud Run, CloudFormation, auto-scaling, Well-Architected, CDN, VPC, vendor lock-in

→ Agent: senior-cloud-architect → Start with skill: cloud-architect or documentation-and-adrs → Command: /spec or /build

Backend Services & APIs

Trigger words: 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

→ Agent: senior-backend-engineer → Start with skill: backend-architect or api-and-interface-design → Command: /spec then /build

AI / ML Features

Trigger words: AI, LLM, GPT, Claude, Anthropic, prompt, RAG, vector, embedding, fine-tuning, agent, LangChain, LangGraph, evaluation, hallucination, guardrail, tool use, function calling, AI safety, semantic search, chatbot

→ Agent: ai-ml-engineer → Start with skill: spec-driven-development or llm-app-patterns → Command: /spec then /build

Code Review & Quality

Trigger words: review, check my code, is this good, feedback on, before merge, pull request, PR, clean up, refactor, simplify, code smell, technical debt

→ Agent: code-reviewer → Start with skill: code-review-and-quality → Command: /review

Security

Trigger words: security, vulnerability, audit, hack, inject, XSS, SQL injection, CSRF, auth bypass, secure, harden, OWASP, CVE, token, password, encryption, sensitive data

→ Agent: security-auditor → Start with skill: security-and-hardening → Command: /review or /ship

Testing

Trigger words: test, spec, coverage, failing test, bug proof, unit test, integration test, E2E, Cypress, Playwright, Jest, pytest, mock, stub, test suite

→ Agent: test-engineer → Start with skill: test-driven-development → Command: /test

Web Performance

Trigger words: slow, performance, LCP, INP, CLS, Core Web Vitals, Lighthouse, bundle size, lazy load, preload, render blocking, TTFB, speed

→ Agent: web-performance-auditor → Start with skill: performance-optimization → Command: /webperf

QA Verification

Trigger words: verify, QA, does this work, check if it works, make sure nothing is broken, confirm the fix, regression check, validate the feature, working as expected, smoke test, sanity check, verify all the fixes are in place, is this working, confirm this is fixed

→ Agent: senior-qa-engineer → Start with skill: quality-assurance → Command: /test or direct invocation

Cross-Cutting Skills (No Agent — Invoke Directly)

These skills fire regardless of domain. They cover situations that happen across every project and are not tied to a specific engineering area. Check these before routing to a domain agent — they often apply first.

Receiving Code Review Feedback

Trigger words: someone reviewed my code, here are review comments, my PR has comments, reviewer said, feedback on my PR, address these comments, code review feedback, reviewer flagged

→ Skill: receiving-code-review → No agent. Invoke directly. Evaluate each comment technically before implementing.

Requesting a Code Review

Trigger words: request a review, ready for review, submit for review, ask for feedback, PR is ready, want someone to review

→ Skill: requesting-code-review → No agent. Invoke directly before opening a PR or asking for a review.

Finishing a Development Branch

Trigger words: I'm done, implementation complete, finished the feature, ready to merge, done with the branch, all tests pass, wrap this up, close this out

→ Skill: finishing-a-development-branch → No agent. Invoke directly when work is complete and the path forward (merge, PR, cleanup) needs to be decided.

Systematic Debugging

Trigger words: bug, broken, not working, unexpected behaviour, crash, error, failing, something is wrong, why is this happening, root cause, trace this

→ Skill: systematic-debugging → No agent. Invoke directly before proposing any fix. Root cause first, patch second.

Verification Before Completion

Trigger words: it works, I think it's done, looks good, should be fixed, seems to work, I believe this is correct, that should do it, done

→ Skill: verification-before-completion → No agent. Invoke whenever a completion or success claim is about to be made. Evidence before claims.

Writing a Plan

Trigger words: plan this, how should I approach, break this down, map this out, before I start, let me plan, write a plan for

→ Skill: planning-and-task-breakdown → No agent. Invoke before touching code on any multi-step task.

Executing a Plan

Trigger words: execute the plan, follow the plan, implement the plan, carry out the steps, run through the plan, start the plan

→ Skill: executing-plans → No agent. Invoke when a written plan exists and execution is starting.

Brainstorming

Trigger words: brainstorm, ideas for, what are the options, how could we, what should I build, explore approaches, what are the possibilities, think through

→ Skill: brainstorming → No agent. Invoke before any creative or architectural decision. Options before commitment.

Extracting Underspecified Intent

Trigger words: interview me, grill me, help me figure out what I actually want, I'm not sure what I need, ask me questions first

→ Skill: interview-me → No agent. Invoke when a request is underspecified — one question at a time until confident what's actually being asked for.

Refining a Vague Idea

Trigger words: help me think through this idea, refine this concept, I have a rough idea, explore this direction, is this idea any good

→ Skill: idea-refine → No agent. Invoke on a vague concept that needs divergent/convergent thinking before it's concrete enough to spec.

Deep-Diving a Feature-Shaped Idea

Trigger words: deep dive on this idea, go deep on requirements, ask me everything before we build this, cover every angle, fully spec this before building, don't miss anything — or a one-liner naming a feature domain with many independent sub-decisions (role-based access, multi-tenancy, notifications, payments, search, a workflow engine)

→ Skill: deep-dive → No agent. Invoke when a short idea implies a whole feature domain rather than one ambiguity — builds a decision tree grounded in the codebase, interrogates it in batched rounds scaled to the idea's real size (not a fixed count), and produces a ready-to-use prompt plus a detailed spec file. Upstream of spec-driven-development, not a replacement for it — and upstream of breakdown-feature-prd too, when the idea needed that much interrogation before it's concrete enough to write PRDs from. → Command: /deep-dive

Writing Feature PRDs

Trigger words: write a PRD for this feature, break down this project into feature PRDs, product requirements, PM-facing spec, user stories and acceptance criteria for this feature, document all the features in this project

→ Skill: breakdown-feature-prd → No agent. Invoke for a product-facing PRD (Problem/Solution/Impact, personas, Given/When/Then user stories) grounded in project context or docs — either swept across every feature it identifies, or for one named feature. Not the engineering spec itself (spec-driven-development is downstream of this). → Command: /breakdown-feature-prd

Planning a Feature's Technical Implementation

Trigger words: implementation plan for this feature, technical design for this feature, turn this PRD into an architecture doc, system architecture for this feature, database schema and API design for this feature

→ Skill: breakdown-feature-implementation → No agent. Invoke when a feature PRD exists and needs a technical design — architecture, database schema, API design, frontend architecture, security/performance — before task breakdown. Not a task list itself (planning-and-task-breakdown is downstream of this). → Command: /breakdown-feature-implementation

Coordinating Multiple Agents on a Plan

Trigger words: coordinate multiple agents, dispatch subagents for this plan, run these tasks in parallel with fresh agents, subagent-driven execution

→ Skill: subagent-driven-development → No agent. Invoke when executing a written plan whose tasks are independent enough to dispatch to fresh subagents, each reviewed before the next starts.

Starting a Brand-New Project from a Vague Prompt

Trigger words: new project, start from scratch, I have an idea for an app, greenfield project, build me a [thing] from nothing

→ Skill: not-a-vibe-coder → No agent. Invoke only for brand-new projects — turns a vague prompt into 8 structured planning files. Do not use on existing codebases.

Lifecycle Commands

When the user describes a full feature (not just one concern), follow the lifecycle:

Routing Decision Process

1. Read the user's message — extract the domain nouns and action verbs
2. Match against the keyword table — find the strongest signal category
3. Check for multiple concerns — if the task spans multiple domains (e.g. "build a secure API with a database"), route to the primary domain agent first; surface secondary concerns in their skill invocations
4. State the route — tell the user which agent and skill you're invoking and why
5. Invoke the agent/skill — do not implement without first routing

Multiple Domain Signals

When a request spans multiple domains, apply this priority order:

1. Security concerns → always surface to security-auditor
2. Primary build domain → route to domain agent
3. Testing → test-engineer at the end
4. Review → code-reviewer before ship

Example: "Build a user registration endpoint with password hashing and email verification"

• Primary: api-developer (endpoint)
• Secondary: security-auditor (password hashing)
• Lifecycle: /spec → /build → /test → /ship

Anti-Patterns

Do not:

• Implement without routing first
• Skip the domain agent for "simple" tasks
• Route everything to code-reviewer — that is for review, not build
• Invoke multiple agents sequentially yourself — use /ship for fan-out

Relationship to Other Skills

This skill is the entry point. After routing, hand off to the domain agent which then uses its ## When to Invoke Skills table to pull the right skill from its scope.

User intent → using-agent-harness (this skill) → Agent persona → Skill