Date: 2026-04-23
Status: Bootstrap (hand-derived from 2026-04-23-spear-plugin-design.md; will be regenerated by /spear:init at v0.1.0 to prove SPEAR-built-SPEAR)
EARS subset enforced: Ubiquitous, Event-driven, State-driven, Unwanted (per design §8.2). Optional Feature pattern (WHERE …) accepted without validation in v1.0.0.
Each requirement carries a stable ID. Tasks reference requirements by ID. New requirements append at the next free ID — IDs are never re-used or renumbered.
Ubiquitous. THE SYSTEM SHALL ship .claude-plugin/marketplace.json at the repo root declaring this repo as a Claude Code marketplace named BadgersMC-spear-plugin containing one plugin entry spear.
Ubiquitous. THE SYSTEM SHALL ship plugins/spear/.claude-plugin/plugin.json declaring name: spear, semver version, description, author, and repository fields.
Event-driven. WHEN a user runs /plugin marketplace add BadgersMC/spear-plugin THE SYSTEM SHALL register the marketplace without manifest-validation errors.
Event-driven. WHEN a user runs /plugin install spear@BadgersMC-spear-plugin THE SYSTEM SHALL install the plugin to ~/.claude/plugins/cache/BadgersMC-spear-plugin/spear/<version>/.
Event-driven. WHEN a user runs /plugin reload-plugins after a plugin update THE SYSTEM SHALL load the updated skill bodies and hook scripts on the next session start.
Ubiquitous. THE SYSTEM SHALL ship exactly seven skills: using-spear, init, spec, prove, engine, arch, refine.
Ubiquitous. THE SYSTEM SHALL emit using-spear content via the session-start hook and SHALL NOT register it as a /spear:using-spear slash command.
Event-driven. WHEN a user types /spear:<name> for name in {init, spec, prove, engine, arch, refine} THE SYSTEM SHALL load the corresponding SKILL.md body.
Ubiquitous. THE SYSTEM SHALL keep the using-spear stdout payload under 4096 bytes (~1000 tokens).
State-driven. WHILE the using-spear payload approaches the 4096-byte ceiling THE SYSTEM SHALL truncate in this order: full tasks.md body first, then historical probe results, then the deferral list. Cycle rules and current phase SHALL never be truncated.
Ubiquitous. THE SYSTEM SHALL include in using-spear an explicit deferral note pointing the agent at superpowers:brainstorming, superpowers:writing-plans, superpowers:executing-plans, and superpowers:systematic-debugging for those phases.
Ubiquitous. THE SYSTEM SHALL emit the Verify-Don't-Guess rule and its evidence-source order (context7 → on-disk → WebFetch → mgrep/Read/Glob) in every session-start injection.
Event-driven. WHEN the session-start hook executes THE SYSTEM SHALL probe for context7, mgrep, semgrep availability and SHALL include the probe result in the injected text.
State-driven. WHILE a session is active THE SYSTEM SHALL NOT re-probe; downstream skills SHALL read the cached announcement.
Ubiquitous. THE SYSTEM SHALL document in using-spear the §5.3 briefing contract fields (file paths, signatures, failing test, acceptance criteria, forbidden actions, evidence) so any subagent dispatch inherits them.
Ubiquitous. THE SYSTEM SHALL state that any task whose full briefing exceeds ~1500 tokens MUST be decomposed by spear:spec before dispatch.
Unwanted. IF a task's Evidence: block is empty THEN THE SYSTEM SHALL refuse to advance the task past phase: spec-done.
Event-driven. WHEN spear:prove, spear:engine, or spear:arch runs THE SYSTEM SHALL compute the set of new third-party and internal import paths introduced since the task's baseline snapshot and SHALL fail with a list "Add evidence for: , …" for any import not matched as a substring against any line in the task's Evidence: block.
Unwanted. IF the gate at REQ-031 fails THEN THE SYSTEM SHALL NOT permit the skill to mutate spear-state.json beyond setting an error reason.
Ubiquitous. THE SYSTEM SHALL store state at .claude/spear-state.json per project and SHALL document that consumers must gitignore this path.
Ubiquitous. THE SYSTEM SHALL include a top-level integer version field in the state file. v1.0.0 SHALL emit version: 1.
Ubiquitous. THE SYSTEM SHALL accept phase values from the closed set: idle | spec | spec-done | prove | prove-done | engine | engine-done | arch | arch-done | refine.
Unwanted. IF a skill is invoked from a phase that is not its documented predecessor THEN THE SYSTEM SHALL refuse to run and SHALL emit a human-readable error of the form spear:<skill> requires phase=<expected>; current phase=<actual>.
Event-driven. WHEN a TDD-tagged task progresses THE SYSTEM SHALL follow idle → spec → spec-done → prove → prove-done → engine → engine-done → arch → arch-done → refine → idle.
Event-driven. WHEN a DOC- or INFRA-tagged task progresses THE SYSTEM SHALL follow idle → spec → spec-done → arch → arch-done → refine → idle (skipping prove/engine).
Event-driven. WHEN spear:prove confirms the new test fails THE SYSTEM SHALL set testStatus: red, write testFile and testName, and transition to prove-done.
Event-driven. WHEN spear:engine confirms the referenced test passes THE SYSTEM SHALL set testStatus: green and transition to engine-done. IF the test does not pass THEN THE SYSTEM SHALL remain in engine with the failure reason recorded.
Event-driven. WHEN spear:refine completes a refactor pass with the full suite green THE SYSTEM SHALL mark the task [x] in tasks.md and SHALL reset state to phase: idle clearing currentTaskId, reqId, testFile, testName, testStatus, evidenceCited.
Event-driven. WHEN the session-start hook runs and spear-state.json exists THE SYSTEM SHALL re-run the referenced testFile/testName and SHALL correct testStatus to the observed value, notifying the user when correction occurred.
Ubiquitous. THE SYSTEM SHALL execute any state-file schema migration deterministically inside the session-start hook (not inside an LLM-driven skill) before emitting stdout.
Ubiquitous. THE SYSTEM SHALL read layer rules from the ## Layer Dependency Rules section of docs/implementation.md in the consumer project.
Unwanted. IF a file under domain/** imports from application/** or infrastructure/** THEN spear:arch SHALL fail with file:line:symbol output.
Unwanted. IF a file under application/** imports a framework package (anything outside domain/** + stdlib) THEN spear:arch SHALL fail.
Ubiquitous. THE SYSTEM SHALL allow infrastructure/** to import from any layer.
Unwanted. IF a file under domain/** carries an annotation matching the default denylist (org.springframework.*, jakarta.persistence.*, javax.persistence.*, com.fasterxml.jackson.*, io.micronaut.*, lombok.*) or any pattern in the project's ## Forbidden Domain Annotations YAML list THEN spear:arch SHALL fail.
Event-driven. WHEN spear:init detects a JVM project (presence of build.gradle, build.gradle.kts, or pom.xml) THE SYSTEM SHALL drop src/test/kotlin/architecture/LayerRulesTest.kt reflecting the layer map.
Event-driven. WHEN spear:init runs against a non-JVM project THE SYSTEM SHALL skip the Konsist template and SHALL emit a one-line notice naming the absent template.
Unwanted. IF spear:arch reports any violation THEN THE SYSTEM SHALL refuse to advance to phase: refine.
Event-driven. WHEN spear:init runs THE SYSTEM SHALL detect language and framework from build.gradle.kts, pom.xml, package.json, pyproject.toml, Cargo.toml, go.mod if present and SHALL pre-fill tech-stack.md from detected dependency coordinates.
Event-driven. WHEN spear:init completes THE SYSTEM SHALL have created docs/tech-stack.md, docs/requirements.md, docs/implementation.md, docs/tasks.md from the bundled templates.
Event-driven. WHEN spear:spec writes or updates a REQ- entry in requirements.md THE SYSTEM SHALL validate it as one of: Ubiquitous (THE SYSTEM SHALL <response>), Event-driven (WHEN <event> THE SYSTEM SHALL <response>), State-driven (WHILE <state> THE SYSTEM SHALL <response>), Unwanted (IF <unwanted> THEN THE SYSTEM SHALL <response>). Optional Feature pattern (WHERE …) SHALL be accepted without validation.
Ubiquitous. THE SYSTEM SHALL assign new REQ-IDs as the next free integer above the max existing ID, padded to three digits, never re-using or renumbering existing IDs.
Event-driven. WHEN spear:init derives tasks.md THE SYSTEM SHALL tag every initial task with exactly one of TDD, DOC, INFRA and SHALL include References: (REQ-IDs + spec sections) and an empty Evidence: block per task.
Event-driven. WHEN spear:init finishes successfully THE SYSTEM SHALL create a git commit with subject chore(spear): initialize SPEAR docs containing exactly the four docs plus the Konsist template (when emitted).
Ubiquitous. THE SYSTEM SHALL register a SessionStart hook in plugins/spear/hooks/hooks.json with matcher startup|clear|compact.
Ubiquitous. THE SYSTEM SHALL ship a single polyglot hooks/run-hook.cmd plus extensionless hooks/session-start script. The run-hook.cmd SHALL be valid cmd.exe batch on Windows (locating Git-for-Windows bash) and a no-op heredoc on POSIX shells. Spec amendment approved 2026-04-23 supersedes original §9 dual-script requirement.
Event-driven. WHEN the hook runs under Claude Code (env CLAUDE_PLUGIN_ROOT set, CURSOR_PLUGIN_ROOT unset) THE SYSTEM SHALL emit JSON of shape {"hookSpecificOutput": {"hookEventName": "SessionStart", "additionalContext": "<text>"}}.
Event-driven. WHEN the hook runs with CURSOR_PLUGIN_ROOT set THE SYSTEM SHALL emit {"additional_context": "<text>"} and SHALL NOT emit hookSpecificOutput.
Event-driven. WHEN the hook runs in a directory lacking both docs/requirements.md and docs/tasks.md THE SYSTEM SHALL emit a short one-line "not a SPEAR project" notice and exit 0.
Unwanted. IF the hook encounters any internal error THEN THE SYSTEM SHALL exit 0 with a brief diagnostic in stdout rather than non-zero.
Ubiquitous. THE SYSTEM SHALL defer brainstorming, writing-plans, executing-plans, systematic-debugging to superpowers (no SPEAR replacement skill).
Event-driven. WHEN both docs/requirements.md AND docs/tasks.md are present THE SYSTEM SHALL treat spear:prove as the active TDD entry point.
Unwanted. IF /spear:prove is invoked in a project lacking either docs/requirements.md or docs/tasks.md THEN THE SYSTEM SHALL print not a SPEAR project; use superpowers:test-driven-development and exit without mutating state.
Ubiquitous. THE SYSTEM SHALL ship a script that asserts every SKILL.md carries name and description frontmatter, body is under the per-skill ceiling, and contains no broken internal links.
Ubiquitous. THE SYSTEM SHALL ship hook integration fixtures for each of idle, mid-prove, mid-engine, and stale-state. The stale-state fixture SHALL include a real JUnit test file and a stub gradle on $PATH deterministically returning red or green so the reconciliation path of REQ-049 is actually exercised.
Ubiquitous. THE SYSTEM SHALL ship a script-driven state-machine test suite asserting linear gating per REQ-043, the TDD path REQ-044, the DOC/INFRA path REQ-045, and the refine-clears-to-idle invariant REQ-048.
Ubiquitous. THE SYSTEM SHALL ship TESTING.md with a manual checklist exercising fresh-repo → /spear:init → one full TDD cycle → verify commits, state, Konsist file. Run before each release.
Unwanted. IF a proposed test asserts that the LLM follows skill prose THEN THE SYSTEM SHALL reject the test as out of scope per design §11 final paragraph.
Ubiquitous. THE SYSTEM SHALL use semantic versioning for the plugin and SHALL bump major on breaking state-file schema changes.
Ubiquitous. THE SYSTEM SHALL ship every state-file schema migration as a script under plugins/spear/migrations/N-to-M.sh invoked by the session-start hook before stdout emission.
Event-driven. WHEN a user follows the §3.2 install flow on a clean ~/.claude/ THE SYSTEM SHALL succeed at v0.1.0.
Event-driven. WHEN /spear:init runs against an empty repo at v0.1.0 THE SYSTEM SHALL produce all four docs and (on JVM) a Konsist template — proving SPEAR can rebuild SPEAR.
Event-driven. WHEN at v1.0.0 a user runs a full spec → prove → engine → arch → refine cycle on a single TDD task THE SYSTEM SHALL flip the task to [x] in tasks.md and reset state to idle.
Event-driven. WHEN spear:arch runs against tests/fixtures/layer-violation/ (a Kotlin file under domain/ importing from infrastructure/) THE SYSTEM SHALL block progression with a message naming the offending file and import.
Event-driven. WHEN a Claude Code session starts in a SPEAR project THE SYSTEM SHALL surface the hook output as "SessionStart hook additional context" containing probe results, current task, and current phase.