Harness Sample is a small Python project configured to work with several AI coding harnesses (Claude Code, Codex, Gemini CLI, Grok, GitHub Copilot, OpenCode, or a generic setup). It demonstrates a portable, specification-driven workflow for turning an approved feature request into tests, implementation, and reviewable commits.
When AI agents write most of the code, the rules around them matter as much as the code. This repository carries those rules with it, so every agent follows the same workflow:
- Only a human can approve the specification.
- Tests are written before the implementation.
- Separate reviewer sessions check the plan, each task, security, and the final result, and each review is recorded.
- Agents don't merge, push, or deploy without a separate request from a person (
.sdd/POLICY.md).
You can clone this repository as a base, use it as-is, or copy the skills and agent roles you prefer into another repository.
-
Install OpenSpec 1.13.1 (needs Node.js 20.19 or later):
npm install -g @fission-ai/openspec@1.13.1 openspec --version
-
Install Superpowers for your coding harness. For example:
- Claude Code:
claude plugin marketplace add obra/superpowers-marketplace, thenclaude plugin install superpowers@superpowers-marketplace - Codex: open
/plugins, search for Superpowers, and select Install Plugin.
Steps for Gemini CLI, Grok, Copilot, OpenCode, and other harnesses are in
.sdd/harnesses/. Restart the harness and confirm its skills load. - Claude Code:
-
Open this repository with your coding agent and ask it to implement a feature.
AGENTS.mdroutes the request through thesdd-runskill, which checks that OpenSpec and Superpowers are available and then guides the agent through specification, approval, planning, implementation, checks, and review.
To run the sample tests, install uv and run:
uv run --with pytest python -m pytest -qStart with git log --oneline. Each step of the workflow is its own commit.
- Bootstrap project adds portable repository instructions and harness-specific agent guidance.
- The proposal and specification commits capture the feature intent and its observable behavior before implementation.
- Planning commits record the implementation approach and verification criteria.
- Write personalized greeting tests records the test-first step.
- Implement personalized greeting adds
greet_person(name)after the tests were in place. - Mark greeting tasks complete records the completed implementation tasks.
- Record workflow review evidence and Record final review outcome commit the review record (
.sdd-review.json): the human spec approval, the spec, code, security, and final reviews, and the OpenSpec validation result. - Sync and Archive merge the approved spec into
openspec/specs/and move the change toopenspec/changes/archive/. - Updated harness files refreshes the agent workflow files after the run, the way an existing project would receive template updates.
This repository is a demo run on a deliberately small example. I approved the specification myself. Reviews ran as separate agent sessions, recorded in openspec/changes/archive/2026-11-02-add-personalized-greeting/.sdd-review.json, and the implementation tasks ran in the main Codex session. Paths inside that record point to the change folder before it was archived. It is not a claim that larger projects or production rollouts have been exercised here.
OpenSpec (MIT) owns the specification and change files. Superpowers is referenced but not included. See THIRD_PARTY_NOTICES for details.
MIT. See LICENSE.
Cristian Calabro · ccalabro.dev · cristian@ccalabro.dev