Skip to content
Back to search

contract-first-dev

MarketplaceWorks with Claude CodeGitHub

Marketplace for Contract First — machine-checkable specs, ownership boundaries, and guard tests for AI agents

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/akatekhanh--contract-first/badge.svg)](/listings/akatekhanh--contract-first)

HTML

<a href="/listings/akatekhanh--contract-first"><img src="/api/listings/akatekhanh--contract-first/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Structured for native discovery across every major AI coding harness (inspired by [`obra/superpowers`](https://github.com/obra/superpowers)):

Universal (`npx skills`)

npx skills add akatekhanh/contract-first

Antigravity (`agy`)

agy plugin install https://github.com/akatekhanh/contract-first

*(Uses `.antigravity-plugin/plugin.json` and ingests `skills/contract-first/` automatically.)*

Claude Code

Inside Claude Code:

/plugin marketplace add akatekhanh/contract-first
/plugin install contract-first@contract-first-dev

*(Uses `.claude-plugin/marketplace.json` + `.claude-plugin/plugin.json`.)*

OpenAI Codex CLI / App

# Via universal .agents/plugins marketplace or direct skill clone:
git clone https://github.com/akatekhanh/contract-first.git /tmp/contract-first \
  && cp -R /tmp/contract-first/skills/contract-first ~/.codex/skills/contract-first \
  && rm -rf /tmp/contract-first

*(Includes `.codex-plugin/plugin.json` and `.agents/plugins/marketplace.json`.)*

Cursor

Install from repository URL using `.cursor-plugin/plugin.json` (`"skills": "./skills/"`), or clone `skills/contract-first` into `.cursor/skills/`.

Gemini CLI

gemini extensions install https://github.com/akatekhanh/contract-first

*(Uses `gemini-extension.json` + `GEMINI.md`.)*

OpenCode / Hermes / Other Harnesses

Point your harness at `AGENTS.md` or copy `skills/contract-first/` into your shared `~/.agents/skills/` directory:

git clone https://github.com/akatekhanh/contract-first.git /tmp/contract-first \
  && mkdir -p ~/.agents/skills \
  && cp -R /tmp/contract-first/skills/contract-first ~/.agents/skills/contract-first \
  && rm -rf /tmp/contract-first

Once installed, trigger it naturally in any session: - *"Set up contract-first for this repo"* - *"Scaffold the contracts before we start coding"* - *"Audit this repo with contract-first and find spec↔code drift"*

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 20 lines
  1. {
  2. "name": "contract-first-dev",
  3. "description": "Marketplace for Contract First — machine-checkable specs, ownership boundaries, and guard tests for AI agents",
  4. "owner": {
  5. "name": "Quoc Khanh",
  6. "url": "https://github.com/akatekhanh"
  7. },
  8. "plugins": [
  9. {
  10. "name": "contract-first",
  11. "description": "Specs that bite back — scaffold and enforce machine-checkable YAML contracts, file ownership boundaries, and spec↔code guard tests for AI coding agents.",
  12. "version": "1.0.0",
  13. "source": "./",
  14. "author": {
  15. "name": "Quoc Khanh",
  16. "url": "https://github.com/akatekhanh"
  17. }
  18. }
  19. ]
  20. }
README.md · README · 195 lines
  1. # Contract First — Specs That Bite Back
  2. > **A multi-provider, multi-model AI agent skill that scaffolds machine-checkable YAML contracts, file ownership boundaries, and spec↔code guard tests so coding agents never drift.**
  3. [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
  4. [![Python 3 Stdlib Only](https://img.shields.io/badge/Scripts-Python%203%20Stdlib%20Only-green.svg)](skills/contract-first/scripts/)
  5. [![Multi-Provider](https://img.shields.io/badge/Providers-Antigravity%20%7C%20Claude%20Code%20%7C%20Codex%20%7C%20Cursor%20%7C%20Gemini%20CLI%20%7C%20OpenCode-purple.svg)](#installation)
  6. <p align="center">
  7. <img src="assets/contract-first-hero.gif" alt="Contract First — Specs that bite back (hand-drawn architecture workflow)" width="100%">
  8. </p>
  9. ---
  10. ## Why This Exists
  11. When most of your code is written by AI agents, a constraint that lives only in your head—or in a paragraph an agent is *supposed* to remember—**is not a constraint**.
  12. - Prose rules burn context and silently rot.
  13. - Parallel agents without file boundaries negotiate interfaces *through* your codebase and leave four half-compatible versions of the same idea.
  14. - Open design decisions turn into bare `TODO`s that agents treat as permission to invent.
  15. **Contract First** turns your spec into **executable data**—three YAML contracts, JSON Schemas, a file-ownership boundary table, and automated guard tests—before the first line of implementation code is written.
  16. ---
  17. ## The Five Rules
  18. 1. **If a rule can't be tested, don't write it as a rule.** Important enough to keep → make it a test.
  19. 2. **A matrix is DATA, not a Markdown table.** Only then can tests compare it against real enums and route guards in code.
  20. 3. **One SSOT.** Never keep a parallel `.md` copy of a YAML contract.
  21. 4. **Order: Spec → Contract → Code.** Domain decides the API; API decides the layers. Unbuilt endpoints live under `x-planned-operations`.
  22. 5. **An agent that finds the contract wrong REPORTS it — it does not edit it.** Otherwise the contract becomes a scratchpad.
  23. ---
  24. ## Installation
  25. Structured for native discovery across every major AI coding harness (inspired by [`obra/superpowers`](https://github.com/obra/superpowers)):
  26. ### Universal (`npx skills`)
  27. ```bash
  28. npx skills add akatekhanh/contract-first
  29. ```
  30. ### Antigravity (`agy`)
  31. ```bash
  32. agy plugin install https://github.com/akatekhanh/contract-first
  33. ```
  34. *(Uses `.antigravity-plugin/plugin.json` and ingests `skills/contract-first/` automatically.)*
  35. ### Claude Code
  36. Inside Claude Code:
  37. ```text
  38. /plugin marketplace add akatekhanh/contract-first
  39. /plugin install contract-first@contract-first-dev
  40. ```
  41. *(Uses `.claude-plugin/marketplace.json` + `.claude-plugin/plugin.json`.)*
  42. ### OpenAI Codex CLI / App
  43. ```bash
  44. # Via universal .agents/plugins marketplace or direct skill clone:
  45. git clone https://github.com/akatekhanh/contract-first.git /tmp/contract-first \
  46. && cp -R /tmp/contract-first/skills/contract-first ~/.codex/skills/contract-first \
  47. && rm -rf /tmp/contract-first
  48. ```
  49. *(Includes `.codex-plugin/plugin.json` and `.agents/plugins/marketplace.json`.)*
  50. ### Cursor
  51. Install from repository URL using `.cursor-plugin/plugin.json` (`"skills": "./skills/"`), or clone `skills/contract-first` into `.cursor/skills/`.
  52. ### Gemini CLI
  53. ```bash
  54. gemini extensions install https://github.com/akatekhanh/contract-first
  55. ```
  56. *(Uses `gemini-extension.json` + `GEMINI.md`.)*
  57. ### OpenCode / Hermes / Other Harnesses
  58. Point your harness at `AGENTS.md` or copy `skills/contract-first/` into your shared `~/.agents/skills/` directory:
  59. ```bash
  60. git clone https://github.com/akatekhanh/contract-first.git /tmp/contract-first \
  61. && mkdir -p ~/.agents/skills \
  62. && cp -R /tmp/contract-first/skills/contract-first ~/.agents/skills/contract-first \
  63. && rm -rf /tmp/contract-first
  64. ```
  65. Once installed, trigger it naturally in any session:
  66. - *"Set up contract-first for this repo"*
  67. - *"Scaffold the contracts before we start coding"*
  68. - *"Audit this repo with contract-first and find spec↔code drift"*
  69. ---
  70. ## What Gets Scaffolded in Your Project
  71. ```text
  72. <your-repo>/
  73. ├── contracts/
  74. │ ├── business-spec.yaml # 1. Domain: actors, state machine, flows, copy, AC
  75. │ ├── openapi.yaml # 2. API + entity model (OpenAPI 3.1 + x-planned-operations)
  76. │ ├── architecture.yaml # 3. Layers, file ownership, persistence, ADRs, blockers
  77. │ └── schemas/
  78. │ ├── business-spec.schema.json # JSON Schema Draft 2020-12
  79. │ └── architecture.schema.json # JSON Schema Draft 2020-12
  80. ├── tests/
  81. │ └── test_spec.py # Strict YAML loader + schema + orphan-enum + ADR + AC guards
  82. └── AGENTS.md # Short pointer to contracts/, never restates them
  83. ```
  84. ---
  85. ## Multi-Agent & Multi-Model Fan-Out
  86. <p align="center">
  87. <img src="assets/multi-provider.gif" alt="Multi-Provider & Multi-Model — one repo, six harnesses, three model tiers, one shared contract gate (hand-drawn sketchbook diagram)" width="100%">
  88. </p>
  89. The `ownership` table in `contracts/architecture.yaml` acts as a second contract when fanning work out across parallel agents or mixed model families:
  90. | Role | Owns | Recommended Model Tier | Examples (Multi-Provider) |
  91. |---|---|---|---|
  92. | `ARCHITECT` | `contracts/`, entities, ports/interfaces, shared signatures | Frontier / high-reasoning | Claude Opus · Gemini Pro / Neon · GPT-5 (high) |
  93. | `AGENT-DOMAIN` / `ADAPTER` / `API` / `FE` | One implementation layer inside owned files | Mid / balanced | Claude Sonnet · Gemini Pro · GPT-5 / Codex |
  94. | `RESEARCH` | Read-only lookup & repo exploration | Fast / lightweight | Claude Haiku · Gemini Flash · GPT-5 mini |
  95. | `REVIEWER` | Diff vs. contract verification | **Separate agent / cross-model** | Pair different families (e.g., Gemini writes, Claude reviews) |
  96. See [`skills/contract-first/references/multi-agent-ownership.md`](skills/contract-first/references/multi-agent-ownership.md) for the full sequencing protocol.
  97. ---
  98. ## CLI Scripts (Zero External Dependencies)
  99. Both helper scripts use **Python 3 standard library only** and are CI-ready (`exit 0` clean, `exit 1` findings/skipped, `exit 2` error).
  100. ### 1. Scaffold a new contract bundle
  101. ```bash
  102. python3 skills/contract-first/scripts/scaffold_contracts.py /path/to/repo --name "My App" --date 2026-11-22
  103. # Preview without writing:
  104. python3 skills/contract-first/scripts/scaffold_contracts.py /path/to/repo --name "My App" --dry-run
  105. ```
  106. ### 2. Audit an existing repo for contract defects
  107. ```bash
  108. python3 skills/contract-first/scripts/contract_audit.py /path/to/repo --format text
  109. # CI mode (file:line:severity:message, hard failures only):
  110. python3 skills/contract-first/scripts/contract_audit.py /path/to/repo --severity HIGH
  111. ```
  112. What `contract_audit.py` catches automatically:
  113. - Missing contract files or meta-schemas (`schemas/*.schema.json`)
  114. - Missing `# yaml-language-server: $schema=...` header lines
  115. - Duplicate YAML mapping keys (which parsers silently overwrite)
  116. - YAML 1.1 implicit-typing traps (`YES`/`NO`/`ON`/`OFF`, version floats like `1.10`, bare dates) and tab indentation
  117. - Broken ADR invariants (decided ADRs missing `date`/`rationale`; open ADRs missing `resolution_criteria`/`default_if_unresolved`, or files in `affects` written before the decision was made)
  118. - Dangling `blocked_by` references or `ownership` entries pointing to nonexistent files
  119. - Duplicate `operationId`s parked in both `paths` and `x-planned-operations`
  120. - Bidirectional `AC-*` acceptance criteria ↔ `covers("AC-...")` test markers
  121. - Parallel Markdown twins (`docs/architecture.md`, `business-spec.md`, etc.)
  122. ---
  123. ## Repository Structure
  124. ```text
  125. contract-first/
  126. ├── .antigravity-plugin/plugin.json # Antigravity (agy) native plugin
  127. ├── .claude-plugin/ # Claude Code plugin + marketplace
  128. ├── .codex-plugin/plugin.json # Codex CLI / App plugin
  129. ├── .cursor-plugin/plugin.json # Cursor plugin
  130. ├── .agents/plugins/marketplace.json # Universal .agents marketplace
  131. ├── gemini-extension.json + GEMINI.md # Gemini CLI extension
  132. ├── AGENTS.md # Universal agent entry point
  133. ├── skills/contract-first/
  134. │ ├── SKILL.md # Core skill instructions
  135. │ ├── references/ # Progressive-disclosure deep guides
  136. │ └── scripts/ # Zero-dependency scaffold + audit CLIs
  137. ├── tests/test_skill_layout.py # Manifest sync, layout & script smoke tests
  138. └── .github/workflows/ci.yml # Automated CI verification
  139. ```
  140. ---
  141. ## License
  142. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.