Multi-platform adaptation of the SPEAR methodology — Spec-Proven Engineering with Architectural Requirements.
This repo adapts the original Claude Code plugin for three platforms:
| Platform | Skills directory | How it works |
|---|---|---|
| Hermes Agent | skills/ |
Native Hermes skills loaded via skill_view(). Install at ~/./skills/spear-*/. |
| Codex (OpenAI) | codex-skills/ |
Codex plugin with .codex-plugin/plugin.json + hooks/ + skills. |
| Claude Code | codex-skills/ |
Also works on Claude Code via ${CLAUDE_PLUGIN_ROOT} compat. |
All platforms follow the same SPEAR cycle: spec → prove → engine → arch → refine.
spec → prove → engine → arch → refine
Each phase is its own skill. A session-start hook injects the cycle rules, current phase, and tool-probe results into every session.
Skills are installed at ~/./skills/spear-*/. Load them by name:
spear-using-spear— Load first in any SPEAR project.spear-init— Bootstrap SPEAR docs in a greenfield project.spear-spec— Author/revise EARS requirements and derive tasks.spear-prove— Write the failing test (red).spear-engine— Write minimum implementation (green).spear-arch— Enforce layer boundaries and annotation denylist.spear-refine— Refactor, close task, reset state.
codex plugin marketplace add BadgersMC/spear-plugin-hermes
codex plugin install spear@BadgersMC-spear-plugin-hermes
Codex loads the spear-using-spear skill at every session start via the SessionStart hook. Other skills are invoked on demand.
/plugin marketplace add BadgersMC/spear-plugin-hermes
/plugin install spear@BadgersMC-spear-plugin-hermes
State is tracked in .claude/spear-state.json per project (gitignored).
Valid phases: idle | spec | spec-done | prove | prove-done | engine | engine-done | arch | arch-done | refine
jq1.6+ (for state-file I/O)node20+ (for EARS validator)bash(for hook scripts)
SPEAR defers to platform-native skills for:
- Brainstorming → platform ideation/brainstorming skills
- Writing plans → platform plan-writing skills
- Executing plans → platform plan-execution skills
- Debugging → platform debugging skills
- TDD (outside SPEAR) → platform TDD skills
Inside a SPEAR project, spear:prove supersedes platform TDD skills.
- Design spec — why it exists and what it does.
- Requirements — EARS-formatted REQ-IDs.
- Implementation — architecture, data flows, layer rules.
- Tasks — current work.
- TS-Spear — full source (Phases 0–5): Gradle multi-module Paper plugin, tests, benchmarks, shadow JAR build. Docs in
reference-implementations/ts-spear/docs/. - TS-Spear overview — SPEAR pattern mapping and citeable entry point (links to source + docs above).
MIT