Skip to content
/
Tier A A11 Governance

openspec-reviewed-workflow

openspec-reviewed-workflow · griffithkk3-del/openspec-reviewed-workflow · ★ 0 · last commit 2026-03-27

Inserts a mandatory evidence-driven codebase investigation gate between proposal and specs in OpenSpec workflows, forcing the AI to investigate existing solutions before specifying new ones.

Best whenSpec quality problems originate at the proposal stage — an AI that hasn't investigated the codebase will write specs that compound architectural mistakes thr…
Skip ifGiving OPTIMAL verdict without codebase evidence, Giving RETHINK verdict without a concrete alternative approach
vs seeds
spec-kit(Archetype 2: process enforcement via slash commands + hooks), this schema uses OpenSpec's artifact dependency graph as …
Primitive shape 1 total
Skills 1
00

Summary

openspec-reviewed-workflow — Summary

openspec-reviewed-workflow is an OpenSpec custom schema and Cursor skill that inserts a mandatory evidence-driven review gate between the proposal and specs/design phases of the standard OpenSpec workflow, forcing the AI to investigate the actual codebase before advancing to spec creation.

Problem it solves: When AI writes a proposal, it relies on a snapshot understanding of the codebase and may miss existing utilities, overlook simpler approaches, or introduce unnecessary abstractions. These mistakes compound through specs, design, and tasks. This workflow inserts a review step that forces the AI to execute at least two codebase searches and produce a structured verdict (OPTIMAL / IMPROVABLE / RETHINK) before specs are unlocked.

Distinctive trait: The only framework in this batch designed as an explicit quality gate overlay on top of an existing framework (OpenSpec) rather than adding execution capability. The SKILL.md has unique guardrails: "NEVER give OPTIMAL just to speed things along", "NEVER write a verdict without evidence", requiring code snippets in the review.

Target audience: Teams using OpenSpec who have experienced the pattern of AI generating technically correct but architecturally poor proposals — where the proposal passes surface review but compounds into poor specs and implementation.

Production-readiness: 0 stars, 0 forks, one contributor (griffithkk3-del). Shell-script-based installer. Last commit March 2026. Very early/personal project.

Relationship to seeds: Extends the canonical openspec seed by adding a review artifact between proposal and specs. Most similar to spec-kit (Archetype 2) in the discipline it applies — spec-kit's constitution-driven development forces explicit design decisions; this framework forces explicit codebase investigation. The SKILL.md guardrails pattern (named anti-behaviors: "NEVER rubber-stamp OPTIMAL") echoes Superpowers' Iron Law pattern but applied to review discipline rather than TDD.

01

Overview

openspec-reviewed-workflow — Overview

Origin

Created by griffithkk3-del. The repository description: "Evidence-driven review workflow for OpenSpec — adds a review gate between proposal and specs/design." Zero stars, zero forks. Last commit March 2026.

Philosophy

The README states the core problem clearly:

"When AI writes a proposal, it relies on a snapshot understanding of the codebase — it may miss existing utilities, overlook simpler approaches, or introduce unnecessary abstractions. These mistakes compound through specs, design, and tasks."

The solution:

"This workflow inserts a mandatory review step that forces the AI to: Search the actual codebase for existing solutions, Compare at least 2 alternative approaches, Verify feasibility (dependencies, performance, testability), Produce a structured verdict: OPTIMAL / IMPROVABLE / RETHINK"

Review verdicts

Verdict Meaning Next Step
OPTIMAL Best approach found Proceed to specs/design
IMPROVABLE Direction correct, needs tweaks Update proposal, then proceed
RETHINK Fundamental issues found Rework proposal with alternative

Workflow modification

Standard OpenSpec:

proposal → specs → design → tasks → apply

With this schema:

proposal → review → specs → design → tasks → apply
              ↑
        NEW: evidence-driven investigation

Key design constraint

Specs and design are blocked until the review artifact achieves OPTIMAL or IMPROVABLE-then-fixed verdict. This is a schema-level enforcement, not a suggestion.

02

Architecture

openspec-reviewed-workflow — Architecture

Distribution

  • Type: OpenSpec custom schema + Cursor skill (standalone repo)
  • Installer: Shell script (scripts/install.sh)
  • Language: Shell (installer) + YAML (schema) + Markdown (templates + skill)

Prerequisites

  • OpenSpec CLI: npm install -g @fission-ai/openspec
  • openspec init in target project

Install

git clone https://github.com/griffithkk3-del/openspec-reviewed-workflow.git
cd openspec-reviewed-workflow
./scripts/install.sh /path/to/your-project

The install script:

  1. Copies openspec/schemas/spec-driven-reviewed/ to target project's openspec/schemas/
  2. Copies .cursor/skills/openspec-review-proposal/ to target project's .cursor/skills/
  3. Updates (or creates) openspec/config.yaml to set schema: spec-driven-reviewed

Manual install alternative

cp -r openspec/schemas/spec-driven-reviewed/ your-project/openspec/schemas/
cp -r .cursor/skills/openspec-review-proposal/ your-project/.cursor/skills/
echo "schema: spec-driven-reviewed" > your-project/openspec/config.yaml

What gets installed

your-project/
├── openspec/
│   ├── config.yaml                              ← Updated: schema: spec-driven-reviewed
│   └── schemas/
│       └── spec-driven-reviewed/
│           ├── schema.yaml                      ← Workflow definition
│           └── templates/
│               ├── proposal.md
│               ├── review.md                    ← NEW: review report template
│               ├── design.md
│               ├── spec.md
│               └── tasks.md
└── .cursor/
    └── skills/
        └── openspec-review-proposal/
            └── SKILL.md                         ← Cursor skill for review

Target AI tools

  • Cursor (primary — the skill is in .cursor/skills/)
  • Any OpenSpec-compatible tool (the schema works without the Cursor skill; the schema's review artifact instruction contains the full process)

Schema version

v1 (OpenSpec custom schema format)

03

Components

openspec-reviewed-workflow — Components

Schema artifacts (6, defined in schema.yaml)

Artifact ID Generated file Requires Key constraint
proposal proposal.md — Must include Capabilities section listing new/modified specs
review review.md proposal MANDATORY: 2 codebase searches; OPTIMAL/IMPROVABLE/RETHINK verdict
specs specs/**/*.md proposal + review Blocked until review completes
design design.md proposal + review Blocked until review completes; only for non-trivial changes
tasks tasks.md specs + design Implementation checklist
(apply) source code tasks Read context + implement

Skills (1)

Located at .cursor/skills/openspec-review-proposal/SKILL.md:

Name Purpose
openspec-review-proposal Cursor AI skill for the review step: executes 2+ codebase searches, produces alternative comparison, gives verdict

Commands

Count: 0 — Uses OpenSpec CLI commands (openspec new, openspec continue).

Subagents

Count: 0

Hooks

Count: 0

MCP Servers

Count: 0

Scripts

Script Purpose
scripts/install.sh Shell script: copies schema + skill + updates config.yaml

Templates (5)

Template Purpose
proposal.md Proposal template (standard OpenSpec)
review.md Review report template (6 sections: summary, evidence, alternatives, feasibility, verdict, action items)
design.md Design template (standard OpenSpec)
spec.md Spec delta template (standard OpenSpec)
tasks.md Task checklist template (standard OpenSpec)

Key addition: review.md template (6 sections)

  1. Summary
  2. Research & Evidence (must include code snippets + search keywords)
  3. Alternative Analysis (comparison table with at least 2 approaches)
  4. Feasibility Check (dependency, performance, testability)
  5. Verdict: OPTIMAL / IMPROVABLE / RETHINK
  6. Action Items (for IMPROVABLE: specific edits to proposal.md)
05

Prompts

openspec-reviewed-workflow — Prompts (Verbatim)

1. SKILL.md — Review skill guardrails (full key sections)

The .cursor/skills/openspec-review-proposal/SKILL.md is the primary prompt artifact:

---
name: openspec-review-proposal
description: Review a proposal with evidence-driven codebase investigation before advancing
  to specs/design.
license: MIT
compatibility: Requires OpenSpec CLI and the spec-driven-reviewed schema.
metadata:
  author: OpenSpec Reviewed Workflow
  version: "1.0"
---

Review a proposal by investigating the codebase and producing an evidence-driven review report.

## Steps

2. **Execute codebase investigation (MANDATORY)**

   You **MUST** perform at least 2 search operations before writing the review.

   **Evidence recording rules:**
   - For each search, record the keyword/pattern and the results
   - If you find reusable code, include the file path and a code snippet
   - If you find conflicts, include the file path and describe the conflict
   - If you claim no reusable code exists, you **MUST** list all search keywords
     you attempted

5. **Produce verdict**

   Rate as exactly one of:
   - **OPTIMAL**: The proposal is the best approach. No material improvements needed.
   - **IMPROVABLE**: The direction is correct but specific improvements are needed.
     List exact edits to `proposal.md` in Action Items.
   - **RETHINK**: The proposal has fundamental issues. Provide a concrete alternative
     approach in the Alternative Analysis section grounded in codebase evidence.

Prompting technique: Mandatory evidence requirement with explicit failure mode prevention. The "if you claim no reusable code exists, you MUST list search keywords" instruction prevents the AI from rubber-stamping a clean search.

2. SKILL.md — Guardrails section (verbatim)

## Guardrails

- NEVER skip the codebase investigation step
- NEVER write a verdict without evidence to support it
- NEVER give OPTIMAL just to speed things along
- NEVER give RETHINK without a concrete alternative
- DO reference the target project's active conventions and rules when evaluating
- DO check whether the proposal reuses existing code and avoids unnecessary abstraction

Prompting technique: Named anti-behaviors (NEVER X pattern). Like Superpowers' Iron Laws but applied to review discipline rather than TDD. Each NEVER statement names a specific cognitive shortcut the AI might take.

3. schema.yaml — review artifact instruction (verbatim, key section)

  - id: review
    instruction: |
      HARD CONSTRAINTS (non-negotiable):
      1. You MUST execute at least 2 code search operations (Grep/Read) before
         filling the Research & Evidence section. If you claim no reusable code
         exists, you MUST list the search keywords you attempted.
      2. For a RETHINK verdict, you MUST provide a concrete alternative approach
         in the Alternative Analysis section, grounded in codebase evidence.
      3. For an IMPROVABLE verdict, you MUST list exact edits to make to
         proposal.md in the Action Items section.

      ### Step 3: Alternative Analysis
      For each change proposed, consider:
      - Can this be solved with a 1-line config/parameter change?
      - Can this be solved by reusing an existing mechanism?
      - Is there a simpler approach the proposal missed?
      Build a comparison table with at least 2 approaches.

Prompting technique: HARD CONSTRAINTS label + numbered requirements. The "HARD CONSTRAINTS (non-negotiable)" header signals unconditional rules, analogous to Superpowers' <HARD-GATE> XML tags but using plain Markdown headers.

Key Prompting Techniques

  1. Named anti-behaviors (NEVER X): Six explicit forbidden actions prevent the AI from taking cognitive shortcuts during review
  2. Mandatory evidence requirements: Minimum search count + code snippet requirements prevent empty "OPTIMAL" verdicts
  3. Verdict-gated action items: IMPROVABLE verdict requires specific proposal edits; RETHINK requires concrete alternatives
  4. 1-line test question: "Can this be solved with a 1-line config/parameter change?" — the simplicity check is embedded in the review process
09

Uniqueness

openspec-reviewed-workflow — Uniqueness and Positioning

differs_from_seeds

Extends the canonical openspec seed by inserting one additional artifact (review.md) between proposal and specs. Compared to the unmodified openspec seed (where specs are generated immediately after proposal), this schema adds a mandatory codebase investigation gate. The SKILL.md guardrails pattern ("NEVER give OPTIMAL just to speed things along") echoes superpowers' Iron Law technique but applied to evidence quality during design review rather than TDD during implementation. Compared to spec-kit (Archetype 2 — constitution-driven development), both frameworks enforce upfront design discipline, but spec-kit uses slash-commands and hooks to enforce process; this framework uses the OpenSpec artifact dependency graph to block downstream work. The install mechanism (shell script copies schema + skill into an existing project) is unique in the batch — the only framework that installs into an existing OpenSpec project rather than setting one up from scratch.

Positioning

  • Niche: "Evidence-driven proposal review gate for OpenSpec projects"
  • Primary differentiator: The only framework in the batch designed as a quality gate overlay — it adds one artifact and one blocking dependency to an existing workflow
  • The RETHINK verdict: Three-value verdict system (not pass/fail) that explicitly provides guidance for the "fundamentally wrong approach" case

Observable failure modes

  1. Rubber-stamp risk: Despite the guardrails, the AI can still claim "OPTIMAL" if the codebase has no evidence to the contrary. The minimum-2-searches requirement helps but doesn't fully prevent false OPTIMALs.
  2. Cursor-only skill: The .cursor/skills/ location means only Cursor users get the structured skill. Other AI tools must rely on the schema's plain-text instruction.
  3. No RETHINK enforcement: A RETHINK verdict requires the user to manually revise the proposal and re-run review — there's no automated enforcement of this cycle.
  4. Zero adoption signals: 0 stars, 0 forks suggest this is a personal experiment with no external validation.
  5. Install script Python dependency: The install.sh uses a Python 3 inline script to update config.yaml — this silently requires Python 3 to be available on the system.

Explicit antipatterns

From the SKILL.md:

  • Giving OPTIMAL without evidence
  • Giving RETHINK without a concrete alternative
  • Skipping codebase investigation
  • Writing reviews based on theory rather than found code
04

Workflow

openspec-reviewed-workflow — Workflow

Phases (modified from standard OpenSpec)

# Phase OpenSpec command Blocked by Artifact
1 Proposal openspec new my-feature — proposal.md
2 Review (NEW) openspec continue my-feature — (but proposal must exist) review.md
3 Specs openspec continue my-feature review must be complete specs/**/*.md
4 Design (optional) openspec continue my-feature review must be complete design.md
5 Tasks openspec continue my-feature specs + design tasks.md
6 Apply openspec apply tasks source code

The review step (Phase 2) — process

From schema.yaml instruction (5 steps):

  1. Read the Proposal — identify key claims, target files, new abstractions
  2. Codebase Investigation (MANDATORY) — at least 2 Grep/Read operations
  3. Alternative Analysis — build comparison table with ≥2 approaches
  4. Feasibility Check — dependency availability, performance, testability
  5. Verdict — exactly one of: OPTIMAL / IMPROVABLE / RETHINK

Review verdict consequences

Verdict What happens
OPTIMAL Proceed to specs as-is
IMPROVABLE Update proposal.md per action items, then proceed
RETHINK Rework proposal with alternative approach, then re-run review

Approval gates

Count: 2

Gate Type Description
Review verdict gate yes-no Specs/design blocked until review artifact has OPTIMAL or IMPROVABLE verdict
RETHINK rework gate freetext-clarify RETHINK verdict requires proposal revision and re-review

Phase to artifact map

Phase Artifact
proposal openspec/changes/{id}/proposal.md
review openspec/changes/{id}/review.md
specs openspec/changes/{id}/specs/{capability}/spec.md
design openspec/changes/{id}/design.md (optional)
tasks openspec/changes/{id}/tasks.md
apply source code
06

Memory Context

openspec-reviewed-workflow — Memory and Context

State storage

File-based (OpenSpec directory layout + review.md):

File Purpose
openspec/changes/{id}/proposal.md Change proposal
openspec/changes/{id}/review.md Review report with verdict
openspec/changes/{id}/specs/**/*.md Delta specs (blocked until review)
openspec/changes/{id}/design.md Design (blocked until review)
openspec/changes/{id}/tasks.md Task checklist

Review persistence

The review.md file persists the codebase investigation evidence:

  • Search keywords attempted
  • Code snippets found
  • Alternative comparison table
  • Verdict (OPTIMAL/IMPROVABLE/RETHINK)
  • Action items (for IMPROVABLE)

This creates an audit trail of the pre-implementation review — reviewers can verify that the AI actually searched the codebase.

Cross-session handoff

Yes — all state in files. Review verdict and action items persist between sessions.

Memory type

File-based, project-scoped.

07

Orchestration

openspec-reviewed-workflow — Orchestration

Multi-agent

No.

Orchestration pattern

Sequential with a blocking gate. The review artifact blocks all downstream artifacts (specs, design) via requires: [proposal, review] in the schema.

Isolation mechanism

None.

Multi-model

No.

Execution mode

Interactive-loop (OpenSpec's continue command advances one artifact at a time).

Prompt chaining

Yes. The review artifact reads proposal.md and produces review.md. The specs and design artifacts depend on both proposal.md and review.md — the review verdict is part of the context for spec creation.

Auto-validators

None. The review is manual (AI-executed but not automatically re-run or monitored).

08

Ui Cli Surface

openspec-reviewed-workflow — UI, CLI, and Observability

Dedicated CLI binary

None. Uses OpenSpec CLI commands.

Local web dashboard

None.

IDE integration

Cursor (primary — the .cursor/skills/openspec-review-proposal/SKILL.md is placed in Cursor's skill directory).

Observability

The review.md file serves as an audit trail:

  • Lists all search keywords attempted
  • Includes code snippets found
  • Shows the comparison table
  • Records the verdict and action items

This makes the pre-implementation review inspectable by humans without requiring the AI to re-run the investigation.

Installation observability

The install.sh script prints:

Installed spec-driven-reviewed workflow into: /path/to/project
Updated schema default in: /path/to/project/openspec/config.yaml

Related frameworks

same archetype · same primary tool · same memory type

OpenHarness ★ 13k
A11 Governance

Open-source Python agent runtime providing complete harness infrastructure: tools, memory, governance, swarm coordination, and…

Trae Agent ★ 12k
A11 Governance

Research-friendly open-source CLI coding agent by ByteDance, designed for academic ablation studies and modular LLM provider…

Sweep AI ★ 7.7k
A11 Governance

Autonomous GitHub bot that converts issues to pull requests using a sequential multi-agent pipeline.

Agent Governance Toolkit (microsoft) ★ 2.3k
A11 Governance

Enterprise-grade AI agent governance: YAML policy enforcement, 12-vector prompt injection defense, zero-trust identity,…

TDD Guard ★ 2.1k
A11 Governance

Mechanically enforces the Red-Green-Refactor TDD cycle by blocking file writes that violate TDD principles via a PreToolUse hook…

Agentic Coding Flywheel Setup (ACFS) ★ 1.5k
A11 Governance

Take a complete beginner from laptop to three AI coding agents running on a VPS in 30 minutes via an idempotent manifest-driven…