A tool-agnostic engineering workflow plugin for AI coding agents. Not bound to any language, framework, runtime, AI agent, model, or cloud.
Language policy. All normative content — methodology docs, skills, schemas, templates, operating contract — is authored in English. New contributions MUST be English.
Install once; it works across Claude Code, Cursor, Gemini CLI, Windsurf, Codex, Aider, OpenCode, or any agent that reads AGENTS.md.
See the whole stack on one page.
docs/diagrams.md§6 — All pieces together maps the normative layer (contracts), execution layer (skill + phases), carrier artifacts (manifest + evidence + ROADMAP), and mechanical guardrails (runtime hooks + CI hooks) in a single diagram. Read it before drilling into any specific file.
-
Runtime operating contract —
AGENTS.mdHonest reporting, scope discipline, source-of-truth rules, surface-first analysis, evidence requirements, Change Manifest contract. -
Engineering workflow skill —
skills/engineering-workflow/SKILL.mdFour execution modes (Zero-ceremony / Three-line delivery / Lean / Full), phase minimums (Phase 0 – 8), capability-category guidance, spec / plan / test / completion templates. -
Methodology documentation —
docs/Four canonical surfaces, 10 SoT patterns, breaking-change severity matrix, rollback modes, cross-cutting concerns, AI operating contract, security & supply-chain disciplines, change decomposition, team / org-scale disciplines, AI project memory, automation contract, multi-agent handoff, worked examples. -
Structured AI output contract —
schemas/+skills/engineering-workflow/templates/manifests/Change Manifest JSON Schema (YAML canonical + JSON generated mirror for Node/browser consumers) and worked example manifests (CRUD, mobile offline, game live-ops, multi-agent handoff progression, security-sensitive JWT rotation). Schema carries a reusable$defs.deprecationmarker so L3/L4 breaking changes can declare deprecate-then-remove timelines directly in-manifest. A generatedCHANGELOG.jsonmirrors the human-readable CHANGELOG for release-automation consumers. -
Stack bridges (optional, opt-in) —
docs/bridges/The only place where specific framework / tool / language names appear. Bridges map the tool-agnostic methodology onto a given stack (Flutter, Android Kotlin + XML, Android Jetpack Compose, Ktor, Unity 3D). Add more bridges for your own stack by copyingdocs/stack-bridge-template.md. -
Multi-agent bridge (Claude Code) —
agents/Three role-bound sub-agents —planner,implementer,reviewer— with tool-permission matrices that enforce the multi-agent-handoff contract mechanically (Reviewer has no write tools; Planner has no edit tools; Implementer cannot spawn further sub-agents). Seedocs/multi-agent-handoff.md§tool-permission-matrix. Other runtimes apply the same matrix using their own agent mechanism (seeAGENTS.md§7). -
Runnable starter example —
examples/starter-repo/A minimal end-to-end demonstration: a schema-valid Change Manifest for a tiny change (/healthzendpoint), cited evidence artifacts, a closed ROADMAP initiative, and a 30-line validator. Clone and runmake validateto see the full contract execute in under a minute. Use as a seed for your own project. -
Agent-runtime hook contract + reference bundle —
docs/runtime-hook-contract.md+reference-implementations/hooks-claude-code/A tool-agnostic contract for event-driven guardrails inside the agent's own loop (pre-commit, post-tool-use, on-stop). Four categories (phase-gate / evidence / drift / completion-audit), JSON-over-stdin event schema, exit-code semantics0 = pass / 1 = block / 2 = warn. A Claude Code reference bundle ships the POSIX-sh hook bundle wiring these categories ontoPreToolUse/PostToolUse/Stopevents — see the Agent-runtime hooks section below for an overview, ordocs/runtime-hooks-in-practice.mdfor install steps.
If you are a single contributor (no team handoff, no release coordination) and want to start fast, pick the lightest fitting mode. Forced-Full triggers (canonical-content edits, public-API breaks, money-movement, auth/PII/secrets, staged rollout, cross-team handoff) override this table — solo does not waive them.
| You are doing… | Use mode |
|---|---|
| Pure Q&A, research, code reading, no files modified | Zero-ceremony — no artifact, no methodology ceremony |
| Tiny typo / comment-only edit / sub-five-line fix with no public-behavior impact | Zero-ceremony |
| Small single-surface tweak with public impact, familiar config / refactor, or one-consumer change needing a short record | Three-line delivery — three-line record, no manifest |
| Single-surface but non-trivial change, or evidence will need to be cited later | Lean — minimal artifact chain (six steps) |
| Multi-surface coordination, public contract break, auth / PII / secrets, staged rollout, cross-team handoff, or any forced-Full trigger | Full — complete artifact trail |
If unsure, take the 3-question fit test at docs/onboarding/when-not-to-use-this.md (§"Is this for you? (3 questions)"). For a 60-second mode-pick under any condition, see docs/onboarding/orientation.md (§"The first 60 seconds of any task"). The complete forced-Full table lives in skills/engineering-workflow/references/mode-decision-tree.md (§"Scenarios that force Full").
# One-off install
/plugin marketplace add https://github.com/<your-org>/agent-protocol
/plugin install agent-protocol@agent-protocolOr local dev (symlink this repo into your plugins directory):
ln -s /absolute/path/to/agent-protocol ~/.claude/plugins/agent-protocolClaude Code auto-loads .claude-plugin/plugin.json, skills/*/SKILL.md, agents/*.md, and hooks/hooks.json per the Claude Code plugin convention (components live at plugin root, not under .claude-plugin/).
- Clone or add this repo as a submodule in your project.
- Cursor auto-loads
.cursor/rules/*.mdc. Copy or symlink the file:
cp -r agent-protocol/.cursor/rules/engineering-workflow.mdc <your-project>/.cursor/rules/Or keep the full repo in your project and point Cursor at it.
Drop GEMINI.md at your project root (or in a parent directory Gemini CLI discovers):
cp agent-protocol/GEMINI.md <your-project>/GEMINI.md
# or
ln -s /path/to/agent-protocol/GEMINI.md <your-project>/GEMINI.mdGemini loads it at session start.
cp agent-protocol/.windsurfrules <your-project>/.windsurfrulesAgent Protocol ships as a Codex plugin at the repository root. The Codex manifest lives at .codex-plugin/plugin.json, and the local marketplace entry lives at .agents/plugins/marketplace.json.
For a user-wide install, clone the repo and add it to your local Codex marketplace:
git clone https://github.com/EsatanGW/agent-protocol.git ~/agent-protocol
mkdir -p ~/plugins ~/.agents/plugins
ln -sfn ~/agent-protocol ~/plugins/agent-protocolThen add an agent-protocol entry to ~/.agents/plugins/marketplace.json with source.path set to ./plugins/agent-protocol. Restart Codex so it reloads the local marketplace.
After install, start by asking Codex to classify surfaces, identify the source of truth, and choose the lightest workflow mode before editing. See docs/codex-install.md for the 60-second use path plus user-wide, workspace-scoped, and hook opt-in installation details.
Place AGENTS.md at your project root. These agents follow the agents.md convention and will read it automatically.
cp agent-protocol/AGENTS.md <your-project>/AGENTS.mdPoint your system prompt at AGENTS.md and make skills/ + docs/ + schemas/ available via file access. The content is already tool-agnostic; worked-example manifests live under skills/engineering-workflow/templates/manifests/.
agent-protocol/
├── AGENTS.md # Universal operating contract (read first)
├── CLAUDE.md # Claude Code-specific guidance (for repo contributors)
├── GEMINI.md # Gemini CLI bridge
├── .windsurfrules # Windsurf bridge
├── .cursor/rules/ # Cursor bridge
│ └── engineering-workflow.mdc
├── .agents/plugins/ # Codex local marketplace entry
│ └── marketplace.json
├── .codex-plugin/ # Codex plugin manifest
│ └── plugin.json
├── .claude-plugin/ # Claude Code plugin manifest only
│ ├── plugin.json
│ └── marketplace.json
├── assets/ # Codex plugin icons
│ ├── agent-protocol.svg
│ └── agent-protocol-small.svg
├── agents/ # Role-bound sub-agents (Planner / Implementer / Reviewer)
│ ├── planner.md
│ ├── implementer.md
│ └── reviewer.md
├── hooks/ # Plugin entry point for Claude Code auto-discovery
│ └── hooks.json # Wires reference-implementations/hooks-claude-code/hooks/*.sh
├── skills/ # Workflow execution layer
│ └── engineering-workflow/
│ ├── SKILL.md
│ ├── phases/ # Phase 0 – 8 detail
│ ├── references/ # Checklists, decision trees, phase minimums
│ └── templates/ # Spec / plan / test / completion templates
│ └── manifests/ # Change Manifest worked examples (CRUD / mobile-offline / game-gacha / mission-evaluator / multi-agent-handoff / security-sensitive)
├── docs/ # Methodology (tool-agnostic)
│ ├── product-engineering-operating-system.md
│ ├── principles.md
│ ├── surfaces.md
│ ├── source-of-truth-patterns.md
│ ├── breaking-change-framework.md
│ ├── rollback-asymmetry.md
│ ├── cross-cutting-concerns.md
│ ├── security-supply-chain-disciplines.md
│ ├── change-decomposition.md
│ ├── team-org-disciplines.md
│ ├── ai-operating-contract.md
│ ├── ai-project-memory.md
│ ├── multi-agent-handoff.md
│ ├── automation-contract.md
│ ├── automation-contract-algorithm.md
│ ├── codex-install.md
│ ├── phase-gate-discipline.md # Per-phase gate + ROADMAP contract
│ ├── adoption-strategy.md
│ ├── glossary.md
│ ├── onboarding/ # Fast-path docs (incl. orientation.md)
│ ├── bridges/ # Stack-specific bridges (ONLY place with tool names)
│ │ ├── flutter-stack-bridge.md
│ │ ├── android-kotlin-stack-bridge.md
│ │ ├── ktor-stack-bridge.md
│ │ └── unity-stack-bridge.md
│ └── examples/ # Worked examples across domains
│ ├── bugfix-example.md
│ ├── refactor-example.md
│ ├── migration-rollout-example.md
│ ├── game-dev-example.md
│ ├── game-liveops-example.md
│ ├── mobile-offline-feature-example.md
│ ├── ml-model-training-example.md
│ ├── data-pipeline-example.md
│ └── embedded-firmware-example.md
├── schemas/ # Change Manifest + surface-map JSON Schemas (dual-format)
│ ├── change-manifest.schema.yaml # canonical (comments, anchors)
│ ├── change-manifest.schema.json # generated — Node / browser consumers
│ ├── surface-map.schema.yaml
│ └── surface-map.schema.json
├── reference-implementations/ # Non-normative example validators + hook bundles
│ ├── validator-posix-shell/ # POSIX shell + yq + pluggable schema validator (minimal)
│ ├── validator-python/ # Python 3.10+ validator (covers all rules including 2.4, 2.5, 3.2, 3.4)
│ ├── community/
│ │ └── validator-node/ # community-maintained TypeScript / Node validator (same rule coverage as Python; not officially synced)
│ ├── roles/ # Runtime-neutral Planner / Implementer / Reviewer role prompts
│ ├── hooks-claude-code/ # Runtime-hook reference bundle + selftest harness
│ ├── hooks-cursor/ # Cursor adapter
│ ├── hooks-gemini-cli/ # Gemini CLI adapter
│ ├── hooks-windsurf/ # Windsurf adapter
│ └── hooks-codex/ # Codex adapter
├── ROADMAP.md # Multi-session tracking artifact for in-flight initiatives
├── CHANGELOG.md # Human-readable release history (Keep-a-Changelog)
├── CHANGELOG.json # Generated machine-readable release feed
├── CONTRIBUTING.md
├── VERSIONING.md
├── LICENSE
└── .github/release_template.md
Most coding agents optimize for "write code that looks right." This plugin optimizes for managing change:
- Before code: identify source of truth, enumerate affected surfaces, classify risk, pick workflow mode.
- During code: evidence for every surface you touch; no silent scope expansion; SoT before consumers.
- After code: structured completion artifact (Change Manifest) that a human or downstream agent can verify.
The method is expressed as capability categories (file read, code search, shell execution, sub-agent delegation), not vendor tool names, so it ports cleanly to any runtime.
Don't first ask:
- "Is this a frontend problem?"
- "Is this a backend problem?"
First ask:
- Where is the source of truth for this capability?
- Which surfaces will feel the change?
- Which consumers will be affected?
- What evidence proves this change actually works?
The four core surfaces:
| Surface | Content |
|---|---|
| User surface | UI, routes, components, copy, state, i18n, a11y |
| System interface surface | APIs, events, jobs, webhooks, SDK boundaries, public contracts |
| Information surface | schema, fields, enums, validation, config, feature flags |
| Operational surface | logs, audit, telemetry, docs, migration, rollout, rollback |
Full definitions and extensions: docs/surfaces.md.
docs/operational-cheat-sheet.md— per-role top 5 actions + 5-second checks + "when you see X, go to Y" navigation. Use this when you need the decision fast; use the linked docs when you need the reasoning.docs/decision-trees.md— single-page hub for the three most-asked routing decisions: Need a Change Manifest?, Which SoT pattern (1–10 + 4a)?, Single-agent or multi-agent role split? Routes to the canonical source for each.
docs/onboarding/orientation.md— canonical single-page onboarding; contains the three-minute and one-page summaries as named sectionsdocs/phase-gate-discipline.md— per-phase gate + ROADMAP contractdocs/onboarding/when-not-to-use-this.md— recognise when the methodology is overkill (also covers scenarios where the methodology partially fits but has known gaps — incident response, pure research, A/B tests, etc.)
See AGENTS.md "Recommended reading order", or browse the docs/ index for a 4-tier classification of every methodology document (onboarding / core contract / disciplines / references).
- Multiple agents cooperating on one change →
docs/multi-agent-handoff.md+skills/engineering-workflow/templates/manifests/change-manifest.example-multi-agent-handoff.yaml - Multi-agent roles on a non-Claude-Code runtime (Cursor / Gemini CLI / Windsurf / Codex) →
docs/multi-agent-handoff.md§Enforcement across runtimes +reference-implementations/roles/ - Feature too large to ship as one change →
docs/change-decomposition.md - Security / supply-chain / PII path touched →
docs/security-supply-chain-disciplines.md+skills/engineering-workflow/templates/manifests/change-manifest.example-security-sensitive.yaml - Team / org-scale concerns (consumer registry, deprecation queue) →
docs/team-org-disciplines.md - Adoption review — is the team applying the methodology or going through the motions? →
docs/adoption-anti-metrics.md(non-normative diagnostic aids) - Long-lived session or cross-session work →
docs/ai-project-memory.md - Writing a validator / CI gate for this methodology →
docs/automation-contract.md(capability spec) +docs/automation-contract-algorithm.md(normative algorithm) + non-normative language references: first-classvalidator-posix-shell/(minimal, zero-dep) andvalidator-python/(full rule coverage), plus community-maintainedcommunity/validator-node/— each ships aDEVIATIONS.mdthat maps exactly which rules it closes - Deprecating a schema field or API surface →
docs/change-manifest-spec.md§"Deprecating a field" (decision table) +$defs.deprecationinschemas/change-manifest.schema.yaml(reusable deprecation marker) - Writing agent-runtime hooks (pre-tool-use, pre-commit, on-stop) → Agent-runtime hooks section below +
docs/runtime-hook-contract.md+reference-implementations/hooks-claude-code/
A fresh checkout can run the high-signal local-runnable checks via two commands:
make install-dev # installs PyYAML, jsonschema, pytest, and the validator-python editable package
make verify-local # runs link / drift / schema / role / legacy-term / template / version / cluster /
# changelog-json / starter-repo manifest / re-entry-trigger pytest /
# validator-python pytest checks
# (uses AGENT_PROTOCOL_SKIP_TAG_CHECK=1 since the release tag is not yet created)make verify-local is a contributor-side wrapper for the same high-signal checks CI runs on every push; CI workflows remain authoritative for release decisions. Hook-bundle selftests (which require yq and bash) and methodology-mcp-server smoke tests (which run in the MCP-server tier) are NOT in make verify-local — run them directly when working in those areas:
sh reference-implementations/hooks-claude-code/selftests/selftest.shpytest reference-implementations/methodology-mcp-server/tests/
The release-tag final gate runs make verify-release-tag after the tag is created (without the AGENT_PROTOCOL_SKIP_TAG_CHECK flag).
See docs/codex-install.md for runtime-specific install paths.
Event-driven guardrails that fire inside the AI agent's own execution loop — before each tool call, after each edit, at end-of-turn — not in CI. They exist to catch failures early (while the agent can still correct) instead of late (after a PR has shipped). Sibling to docs/ci-cd-integration-hooks.md, which covers the CI/CD layer; the two share the same exit-code contract (0 = pass / 1 = block / 2 = warn).
The primary bundle at reference-implementations/hooks-claude-code/ ships the POSIX-sh hook bundle covering all four hook categories (phase-gate / evidence / drift / completion-audit), plus a settings.example.json, a DEVIATIONS.md, and a hermetic self-test harness. The current per-script inventory lives in the bundle's own README so this index does not drift each time a script is added or renamed. Thin adapter bundles for Cursor, Gemini CLI, Windsurf, and Codex reuse the same hook scripts under each runtime's native registration format.
Where to go next:
docs/runtime-hook-contract.md— normative contract: four categories (A phase-gate / B evidence / C drift / D completion-audit), event schema, latency budgets, non-functional requirements.docs/runtime-hooks-in-practice.md— how-to guide: install on Claude Code, wire adapters on other runtimes, configuration knobs, adoption ramp (4-week staging), and the template for writing a custom hook.
skills/engineering-workflow/SKILL.md— main skillskills/engineering-workflow/references/startup-checklist.mdskills/engineering-workflow/references/mode-decision-tree.md
docs/bridges/flutter-stack-bridge.mddocs/bridges/android-kotlin-stack-bridge.mddocs/bridges/android-compose-stack-bridge.mddocs/bridges/ios-swift-stack-bridge.mddocs/bridges/react-nextjs-stack-bridge.mddocs/bridges/ktor-stack-bridge.mddocs/bridges/unity-stack-bridge.md
Other stacks: copy docs/stack-bridge-template.md into docs/bridges/<your-stack>-stack-bridge.md and fill it in for your team.
- Version strategy:
VERSIONING.md - Change history:
CHANGELOG.md - Contribution rules:
CONTRIBUTING.md
MIT. Fork, localize, customize internally — welcome.