Add exploration-mode, specification-driven-development directives and spec-reviewer skill

[pertrai1]

Summary

Three new files extracted from OpenSpec patterns, generalized to be project- and tool-agnostic:

• directives/exploration-mode.md — Pre-implementation investigation stance for thinking through problems before committing to an approach. Fills the gap between codebase navigation (how to search) and task framing (how to scope).
• directives/specification-driven-development.md — Write specs before code, implement against specs, verify after. Five-phase loop: propose → design → specify → implement → verify. Complements TDD (correctness) and type-driven (shapes) by operating at the "what and why" level.
• skills/spec-reviewer.md — Three-dimensional review of implementation against written specs: completeness, correctness, coherence. Natural pairing with existing test-reviewer — one reviews tests, the other reviews implementation against specs.

What Changed

File	Change
directives/exploration-mode.md	New — directive governing pre-implementation investigation
directives/specification-driven-development.md	New — directive governing spec-first development loop
skills/spec-reviewer.md	New — skill for reviewing implementation against specifications
templates/AGENTS.md	Updated directive table + skills table
templates/CLAUDE.md	Updated directive list
templates/copilot-instructions.md	Updated directive list
README.md	Updated counts, added descriptions, added directives vs skills distinction table

Design Decisions

• No cross-file dependencies — all three files are standalone, matching the existing convention
• Templates updated — agents discover directives through templates; without these updates the new files would be invisible
• Spec-reviewer as skill — it adopts a specialist persona with a review process and output format, matching the test-reviewer pattern
• Exploration-mode as directive — it constrains behavior at a workflow phase ("no code during exploration"), matching the directive pattern
• Directives vs skills table added to README — clarifies the distinction for contributors adding future files

How Directives and Skills Differ

	Directive	Skill
Nature	Rule you follow	Persona you adopt
When	At a workflow phase	For a task type
Output	Constrained behavior	Structured findings

Summary by CodeRabbit

• Documentation
  • Introduced Exploration Mode directive to guide pre-implementation investigation and problem analysis.
  • Added Specification-Driven Development directive for spec-first development workflows with phase gates.
  • Introduced Spec Reviewer skill for reviewing implementation against written specifications.
  • Updated workflow documentation with new directives and guidance on directive vs. skill distinctions.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This pull request introduces two new workflow directives—Exploration Mode and Specification-Driven Development—along with a new Spec Reviewer skill. The README is expanded to document these additions, and directive references in AI agent instruction templates are updated accordingly.

Changes

Cohort / File(s)	Summary
New Directives directives/exploration-mode.md, directives/specification-driven-development.md	Added two new workflow directives: Exploration Mode defines pre-implementation investigation stance and outputs; Specification-Driven Development formalizes a five-phase spec-first loop with gate checks and divergence handling.
New Skill skills/spec-reviewer.md	Introduced spec-reviewer skill defining a structured review process with three dimensions (Completeness, Correctness, Coherence), severity-bucketed issue templates, and scenario coverage checks.
Documentation Updates README.md	Expanded workflow directives from 7 to 9 entries, promoted "Skill" section to plural "Skills" with new spec-reviewer addition, and added "Directives vs Skills" comparison section.
Template Updates templates/AGENTS.md, templates/CLAUDE.md, templates/copilot-instructions.md	Updated mandatory directive and skill tables to include Exploration Mode and Specification-Driven Development directives plus Spec Reviewer skill; reordered directive sequence in instruction lists.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 Explorers and specs, oh what a pair!
New directives bloom with thoughtful care,
Before we code, let's think and see,
Then verify what's meant to be. ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly and clearly summarizes the main changes: adding two new directives (exploration-mode and specification-driven-development) and one new skill (spec-reviewer).
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch add-exploration-and-spec-directives

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e7a775ce4a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Keep bug-fix flow consistent with spec-first rule

The Fix (bug) row says to run phases 1, 4-5, which skips phase 3 entirely (Specify) even though this same directive states “Do not implement before the specification is written” and forbids “Implementing before writing any specification.” This contradiction can cause agents to skip writing requirements for bug fixes and diverge from the contract the directive is meant to enforce. Please either include phase 3 for bug fixes or explicitly define the brief proposal as the required specification artifact.

Useful? React with 👍 / 👎.