{
  "markdown": "# Agent Protocols\n\n**Structured engineering protocols that make AI coding agents work like senior engineers.**\n\nMost AI agents generate plausible code. These protocols make them generate _correct_ code with specs, tests, reviews, and deployment gates enforced at every step. Each protocol encodes a specific engineering discipline as a repeatable, verifiable workflow.\n\n```mermaid\nflowchart LR\n  D[Define] --> P[Plan] --> B[Build] --> V[Verify] --> R[Review] --> S[Ship] --> O[Operate]\n```\n\n```mermaid\nflowchart LR\n  spec[\"/spec\"] --> plan[\"/plan\"] --> build[\"/build\"] --> test[\"/test\"] --> review[\"/review\"] --> ship[\"/ship\"]\n  review -.->|optional| simplify[\"/code-simplify\"]\n  simplify --> review\n```\n\n---\n\n## Table of Contents\n\n- [Visual lifecycle](#visual-lifecycle)\n- [Why This Exists](#why-this-exists)\n- [Quick Start](#quick-start)\n- [Commands](#commands)\n- [Protocols](#protocols)\n- [Agent Personas](#agent-personas)\n- [Reference Checklists](#reference-checklists)\n- [How Protocols Work](#how-protocols-work)\n- [Project Structure](#project-structure)\n\n---\n\n## Why This Exists\n\nAI coding agents have a consistency problem. They can write code, but they skip tests, ignore edge cases, rationalize away quality steps, and produce changes that look right but break in production.\n\nAgent Protocols solves this by encoding the practices that experienced engineers follow instinctively -- spec before code, test before merge, measure before optimize -- into structured workflows that agents follow deterministically.\n\n**What makes this different:**\n\n- **Anti-rationalization tables.** Every protocol includes a table of excuses agents commonly use to skip steps (\"I'll add tests later\", \"This is too simple for a spec\") paired with factual rebuttals. The agent can't talk itself out of doing the work.\n- **Verification is mandatory.** Every protocol ends with evidence requirements -- not \"seems right\" but \"tests pass\", \"build succeeds\", \"no security warnings\". The agent must prove it.\n- **Progressive context loading.** Protocols load on-demand based on what the agent is doing. No context window bloat. The right protocol activates at the right time.\n\n---\n\n## Quick Start\n\n### Claude Code\n\n**From the marketplace (recommended):**\n\n```bash\nclaude /plugin install agent-protocols\n```\n\n**From source:**\n\n```bash\nclaude /plugin marketplace add arneesh/agent-protocols\nclaude /plugin install agent-protocols@agent-protocols\n```\n\n### Cursor\n\nCopy any skill you need from `skills/` into `.cursor/rules/`. See [Cursor setup guide](docs/cursor-setup.md).\n\n### GitHub Copilot\n\nUse agent definitions from `agents/` as Copilot personas and protocol content in `.github/copilot-instructions.md` See [Copilot setup guide](docs/copilot-setup.md)\n\n### Any Agent\n\nPaste the content of any `SKILL.md` into your agent's system prompt, rules file, or conversation context. Protocols are plain Markdown -- they work anywhere.\n\n---\n\n## Commands\n\nSeven slash commands map directly to the development lifecycle. Each activates the right protocols automatically.\n\n| Phase    | Command          | Principle               | What Happens                                                                    |\n| -------- | ---------------- | ----------------------- | ------------------------------------------------------------------------------- |\n| Define   | `/spec`          | Spec before code        | Writes a PRD with objectives, structure, testing strategy, and boundaries       |\n| Plan     | `/plan`          | Small, atomic tasks     | Decomposes the spec into verifiable tasks with acceptance criteria              |\n| Build    | `/build`         | One slice at a time     | Implements in thin vertical slices with tests at every step                     |\n| Verify   | `/test`          | Tests are proof         | Runs the TDD workflow -- red, green, refactor                                   |\n| Review   | `/review`        | Improve code health     | Five-axis review: correctness, readability, architecture, security, performance |\n| Simplify | `/code-simplify` | Clarity over cleverness | Reduces complexity while preserving exact behavior                              |\n| Ship     | `/ship`          | Faster is safer         | Pre-launch checklist, staged rollout, monitoring setup                          |\n\nProtocols also activate contextually -- designing an API triggers `api-and-interface-design`, building UI triggers `frontend-ui-engineering`, debugging triggers `debugging-and-error-recovery`.\n\n---\n\n## Protocols\n\n25 protocols organized by development phase. Each is a structured workflow with steps, verification gates, and anti-rationalization tables. Use them through commands or reference any protocol directly.\n\n### Define\n\n| Protocol                                                           | Purpose                                                                              | Trigger                                                |\n| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------ | ------------------------------------------------------ |\n| [idea-refine](skills/idea-refine/SKILL.md)                         | Structured divergent/convergent thinking to turn vague ideas into concrete proposals | Rough concept that needs exploration                   |\n| [spec-driven-development](skills/spec-driven-development/SKILL.md) | PRD covering objectives, commands, structure, code style, testing, and boundaries    | Starting a new project, feature, or significant change |\n\n### Plan\n\n| Protocol                                                                   | Purpose                                                                                       | Trigger                                                             |\n| -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |\n| [planning-and-task-breakdown](skills/planning-and-task-breakdown/SKILL.md) | Decompose specs into small, verifiable tasks with acceptance criteria and dependency ordering | Spec exists and needs implementable units                           |\n| [research-spike-and-poc](skills/research-spike-and-poc/SKILL.md)           | Timeboxed technical exploration with evidence and proceed/pivot/stop recommendation           | Choosing libraries, proving feasibility, unknown integration effort |\n\n### Build\n\n| Protocol                                                                                       | Purpose                                                                                      | Trigger                                                            |\n| ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |\n| [incremental-implementation](skills/incremental-implementation/SKILL.md)                       | Thin vertical slices -- implement, test, verify, commit with feature flags and safe defaults | Any change touching more than one file                             |\n| [test-driven-development](skills/test-driven-development/SKILL.md)                             | Red-Green-Refactor with test pyramid (80/15/5), test sizes, and the Beyonce Rule             | Implementing logic, fixing bugs, or changing behavior              |\n| [context-engineering](skills/context-engineering/SKILL.md)                                     | Feed agents the right information at the right time via rules files and MCP integrations     | Starting a session, switching tasks, or when output quality drops  |\n| [source-driven-development](skills/source-driven-development/SKILL.md)                         | Ground every framework decision in official docs -- verify, cite, flag what's unverified     | Working with any framework or library                              |\n| [frontend-ui-engineering](skills/frontend-ui-engineering/SKILL.md)                             | Component architecture, design systems, state management, responsive design, WCAG 2.1 AA     | Building or modifying user-facing interfaces                       |\n| [api-and-interface-design](skills/api-and-interface-design/SKILL.md)                           | Contract-first design, Hyrum's Law, error semantics, boundary validation                     | Designing APIs, module boundaries, or public interfaces            |\n| [internationalization-and-localization](skills/internationalization-and-localization/SKILL.md) | i18n/l10n: keys, ICU plurals, RTL, locale formats, pseudo-localization                       | Multiple languages, regional formats, or translated user-facing UI |\n\n### Verify\n\n| Protocol                                                                       | Purpose                                                                                   | Trigger                                             |\n| ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- | --------------------------------------------------- |\n| [browser-testing-with-devtools](skills/browser-testing-with-devtools/SKILL.md) | Chrome DevTools MCP for live runtime data -- DOM, console, network, performance profiling | Building or debugging anything in a browser         |\n| [debugging-and-error-recovery](skills/debugging-and-error-recovery/SKILL.md)   | Five-step triage: reproduce, localize, reduce, fix, guard with stop-the-line rule         | Tests fail, builds break, or behavior is unexpected |\n\n### Review\n\n| Protocol                                                             | Purpose                                                                                         | Trigger                                                           |\n| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |\n| [code-review-and-quality](skills/code-review-and-quality/SKILL.md)   | Five-axis review, ~100-line changes, severity labels, review speed norms                        | Before merging any change                                         |\n| [code-simplification](skills/code-simplification/SKILL.md)           | Chesterton's Fence, Rule of 500, reduce complexity while preserving exact behavior              | Code works but is harder to read/maintain than it should be       |\n| [karpathy-guidelines](skills/karpathy-guidelines/SKILL.md)           | Behavioral guardrails against LLM coding pitfalls -- think first, simplify, be surgical, verify | Writing, reviewing, or refactoring code with an AI agent          |\n| [security-and-hardening](skills/security-and-hardening/SKILL.md)     | OWASP Top 10, auth patterns, secrets management, dependency auditing                            | Handling user input, auth, data storage, or external integrations |\n| [performance-optimization](skills/performance-optimization/SKILL.md) | Measure-first -- Core Web Vitals, profiling workflows, bundle analysis                          | Performance requirements exist or regressions suspected           |\n\n### Ship\n\n| Protocol                                                                   | Purpose                                                                          | Trigger                                                    |\n| -------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ---------------------------------------------------------- |\n| [git-workflow-and-versioning](skills/git-workflow-and-versioning/SKILL.md) | Trunk-based development, atomic commits, ~100-line changes, commit-as-save-point | Making any code change                                     |\n| [ci-cd-and-automation](skills/ci-cd-and-automation/SKILL.md)               | Shift Left, feature flags, quality gate pipelines, failure feedback loops        | Setting up or modifying build/deploy pipelines             |\n| [deprecation-and-migration](skills/deprecation-and-migration/SKILL.md)     | Code-as-liability, compulsory vs advisory deprecation, migration patterns        | Removing old systems or sunsetting features                |\n| [documentation-and-adrs](skills/documentation-and-adrs/SKILL.md)           | Architecture Decision Records, API docs, inline standards -- document the _why_  | Architectural decisions, API changes, or shipping features |\n| [shipping-and-launch](skills/shipping-and-launch/SKILL.md)                 | Pre-launch checklists, staged rollouts, rollback procedures, monitoring          | Preparing to deploy to production                          |\n\n### Operate\n\n| Protocol                                                                               | Purpose                                                                     | Trigger                                                       |\n| -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------- |\n| [incident-response-and-postmortems](skills/incident-response-and-postmortems/SKILL.md) | Live incident triage, stabilize, communicate, recover, blameless postmortem | Production outage, SLO breach, on-call alert, customer impact |\n\n### Meta\n\n| Protocol                                                 | Purpose                                                                  | Trigger                                              |\n| -------------------------------------------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------- |\n| [using-agent-skills](skills/using-agent-skills/SKILL.md) | Skill discovery flowchart -- maps task types to the appropriate protocol | Starting a new task and unsure which protocol to use |\n\n---\n\n## Agent Personas\n\nSpecialized agent configurations for targeted analysis. Load a persona when you need a specific engineering perspective.\n\n| Persona                                                        | Role                  | What It Evaluates                                                       |\n| -------------------------------------------------------------- | --------------------- | ----------------------------------------------------------------------- |\n| [Code Reviewer](agents/code-reviewer.md)                       | Senior Staff Engineer | Five-axis code review with \"would a staff engineer approve this?\" bar   |\n| [Test Engineer](agents/test-engineer.md)                       | QA Specialist         | Test strategy, coverage gaps, the Prove-It pattern, test quality        |\n| [Security Auditor](agents/security-auditor.md)                 | Security Engineer     | Vulnerability detection, threat modeling, OWASP Top 10 assessment       |\n| [Performance Engineer](agents/performance-engineer.md)         | Performance Engineer  | Measure-first analysis, profiling, Core Web Vitals, latency regressions |\n| [Documentation Specialist](agents/documentation-specialist.md) | Technical Writer      | ADRs, API docs, runbooks, accuracy vs code                              |\n| [Release Engineer](agents/release-engineer.md)                 | Platform / SRE        | CI/CD gates, staged deploys, rollback, launch readiness                 |\n| [Accessibility Specialist](agents/accessibility-specialist.md) | A11y Engineer         | WCAG 2.1 AA, keyboard and screen reader flows, inclusive UI             |\n| [Spec Analyst](agents/spec-analyst.md)                         | Product Engineer      | PRD quality, scope boundaries, testable acceptance criteria             |\n\n---\n\n## Reference Checklists\n\nSupplementary material that protocols pull in on demand. These provide detailed patterns without bloating the core protocol files.\n\n| Reference                                                           | Covers                                                                     |\n| ------------------------------------------------------------------- | -------------------------------------------------------------------------- |\n| [testing-patterns.md](references/testing-patterns.md)               | Test structure, naming, mocking, React/API/E2E examples, anti-patterns     |\n| [security-checklist.md](references/security-checklist.md)           | Pre-commit checks, auth, input validation, headers, CORS, OWASP Top 10     |\n| [performance-checklist.md](references/performance-checklist.md)     | Core Web Vitals targets, frontend/backend checklists, measurement commands |\n| [accessibility-checklist.md](references/accessibility-checklist.md) | Keyboard nav, screen readers, visual design, ARIA, testing tools           |\n\n---\n\n## How Protocols Work\n\nEvery protocol follows a consistent structure designed for AI agent consumption:\n\n```\nSKILL.md\n  Frontmatter          name + description (used for discovery)\n  Overview             What this protocol does and why it matters\n  When to Use          Triggering conditions and exclusions\n  Process              Step-by-step workflow with checkpoints\n  Rationalizations     Excuses agents use to skip steps + rebuttals\n  Red Flags            Observable signs the protocol is being violated\n  Verification         Evidence requirements -- tests, builds, runtime data\n```\n\n```mermaid\nflowchart TB\n  FM[\"Frontmatter: name, description\"] --> OV[Overview]\n  OV --> WU[When to Use]\n  WU --> PR[Process]\n  PR --> RR[Rationalizations]\n  RR --> RF[Red Flags]\n  RF --> VE[Verification]\n```\n\n---\n\n## Project Structure\n\n```\nagent-protocols/\n├── skills/                              # 25 engineering protocols\n│   ├── idea-refine/                     #   Define\n│   ├── spec-driven-development/         #   Define\n│   ├── planning-and-task-breakdown/     #   Plan\n│   ├── research-spike-and-poc/          #   Plan\n│   ├── incremental-implementation/      #   Build\n│   ├── test-driven-development/         #   Build\n│   ├── context-engineering/             #   Build\n│   ├── source-driven-development/       #   Build\n│   ├── frontend-ui-engineering/         #   Build\n│   ├── api-and-interface-design/        #   Build\n│   ├── internationalization-and-localization/ # Build\n│   ├── browser-testing-with-devtools/   #   Verify\n│   ├── debugging-and-error-recovery/    #   Verify\n│   ├── code-review-and-quality/         #   Review\n│   ├── code-simplification/             #   Review\n│   ├── security-and-hardening/          #   Review\n│   ├── performance-optimization/        #   Review\n│   ├── karpathy-guidelines/             #   Review\n│   ├── git-workflow-and-versioning/     #   Ship\n│   ├── ci-cd-and-automation/            #   Ship\n│   ├── deprecation-and-migration/       #   Ship\n│   ├── documentation-and-adrs/          #   Ship\n│   ├── shipping-and-launch/             #   Ship\n│   ├── incident-response-and-postmortems/ # Operate\n│   └── using-agent-skills/              #   Meta\n├── agents/                              # Specialist personas (review, QA, security, perf, docs, release, a11y)\n├── references/                          # 4 supplementary checklists\n├── hooks/                               # Session lifecycle hooks\n├── .claude/commands/                    # 7 slash commands\n└── docs/                                # Setup guides\n```\n\n---\n\n## License\n\nMIT\n",
  "bytes": 19897,
  "sha": "6d073024468fbd5563912859b7b72f8418a0fdf0b55e48f2de1277ea2a620e8d",
  "repo_slug": "arneesh/agent-protocols",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_arneesh_agent_protocols_agent_protocols_b508387a/readme"
}