You describe a feature to your AI coding assistant. It starts writing code immediately. No requirements. No design. No task breakdown. You spend the next hour correcting assumptions it made in the first minute.
The problem isn't the AI. It's that nobody told it to think first.
SpecOps adds a structured thinking step to AI coding. One command triggers a 4-phase workflow:
- Understand the codebase and context
- Spec requirements, design, and ordered tasks
- Implement from the spec, not from assumptions
- Complete with verified acceptance criteria
Specs are git-tracked, survive across sessions, and work natively with Claude Code, Cursor, OpenAI Codex, and GitHub Copilot.
Claude Code (plugin marketplace):
/plugin marketplace add sanmak/specops
/plugin install specops@specops-marketplace
/reload-plugins
One-line install (any platform):
bash <(curl -fsSL https://raw.githubusercontent.com/sanmak/specops/main/scripts/remote-install.sh)
# Inspect the script first: https://github.com/sanmak/specops/blob/main/scripts/remote-install.shOr clone and run:
git clone https://github.com/sanmak/specops.git && cd specops && bash setup.shTry it:
/specops Add user authentication with OAuth
Platform-specific install details: QUICKSTART.md | Full command reference: docs/COMMANDS.md
Without SpecOps:
You: "Add OAuth authentication"
Agent: *writes auth.ts, picks JWT without asking, hardcodes Google,
skips rate limiting, creates 6 files*
You: "No, I needed GitHub too, and..." (30 min of corrections)
With SpecOps:
You: "/specops Add OAuth authentication"
Agent:
requirements.md -> 4 user stories, 12 acceptance criteria (EARS notation)
design.md -> JWT vs sessions trade-off, provider abstraction layer
tasks.md -> 8 ordered tasks with dependencies and effort estimates
Then implements each task against verified criteria.
| Problem | How SpecOps handles it |
|---|---|
| AI starts coding without understanding the domain | 7 vertical templates: backend, frontend, infra, data pipelines, library/SDK, fullstack, builder |
| Specs lost when you close the session | Git-tracked spec files with cross-session context recovery |
| Agent forgets decisions from yesterday | Local memory layer, loaded automatically every session |
| No way to review specs before coding starts | Built-in team review workflow with configurable approval gates |
| Agent hallucinates vague acceptance criteria | EARS notation for precise requirements: WHEN [event] THE SYSTEM SHALL [behavior] |
| Specs drift from codebase after implementation | 5 automated drift checks with audit and reconcile commands |
| Production reveals things specs missed | Production learnings layer: capture discoveries, link to specs, surface in future work |
| Locked into one AI coding tool | One source of truth, 4 platform outputs |
Every feature of SpecOps was specified, designed, and implemented using the SpecOps workflow. All specs are public in .specops/. The friction log captures 42 lessons learned that shaped the tool.
Large features that span multiple bounded contexts are automatically detected and split into coordinated specs.
You: "/specops Add OAuth authentication and payment processing"
Agent:
Scope assessment → 2 bounded contexts detected (auth, payments)
Proposed split:
Spec 1: oauth-authentication (wave 1 — walking skeleton)
Spec 2: payment-processing (wave 2 — depends on auth)
Initiative: oauth-payments (tracks both specs)
You approve → 2 specs created, linked via specDependencies
/specops initiative oauth-payments → executes both in order
SpecOps handles the coordination: dependency gates block implementation until required specs complete, execution waves ensure correct ordering, and initiative tracking provides a single dashboard across all member specs.
Specs end at "completed." But production reveals things specs never anticipated — performance cliffs, implicit contracts, scaling limits. Those learnings typically live in git commits, incident tickets, and tribal knowledge, disconnected from the specs that created the code.
SpecOps closes this loop. Production discoveries are captured, linked to originating specs, and surfaced when working on future specs that touch the same code.
# During a production incident fix:
/specops learn batch-processing
→ Category: performance
→ Learning: "Concurrent writes above 500 connections degrade P99"
→ Prevention: "Design docs must include concurrency limits for write-heavy ops"
→ Reconsider when: "PostgreSQL upgraded past v15"
# Later, starting a new spec that touches the same files:
/specops Add real-time data export
→ Phase 1 loads relevant learnings automatically:
"1 production learning relevant to this work:
[high] (spec: batch-processing) Concurrent writes above 500 connections degrade P99
Prevention rule: Design docs must include concurrency limits"
→ The agent factors this into its design before writing a single line
Three capture mechanisms keep it zero-friction: explicit capture at the moment of discovery (/specops learn), agent-proposed extraction during bugfix workflows (approve/reject, zero writing), and passive extraction from git history (/specops reconcile --learnings). Learnings are immutable records with supersession chains — they can't go stale because they're point-in-time snapshots. "Reconsider When" conditions are evaluated by the agent to flag invalidated learnings automatically.
Design informed by ADR immutability (Netflix), fitness functions (ThoughtWorks), and trigger-based review patterns from the architecture decision record community.
- Production learnings: the only spec tool that captures post-deployment discoveries, links them to originating specs, and surfaces relevant learnings in future work. No competitor closes the spec-to-production feedback loop.
- Multi-platform: the only spec-driven development tool that works across Claude Code, Cursor, OpenAI Codex, and GitHub Copilot from a single source
- Spec decomposition: automatic scope assessment splits large features into multiple coordinated specs with dependency tracking and initiative orchestration
- Vertical awareness: domain-specific spec templates. Infrastructure specs include rollback steps and resource definitions. Data pipeline specs include data contracts and backfill strategy.
- Enforcement, not suggestions: CI-integrated drift detection, checkbox completion gates, dependency gates, and approval workflows that block implementation until specs are approved
- Open source, local, no lock-in: everything is git-tracked markdown. No cloud service, no account required. MIT license.
Full comparison with Superpowers, Kiro, EPIC/Reload, and Spec Kit | Plan Mode vs Spec Mode
| Platform | Trigger |
|---|---|
| Claude Code | /specops [description] |
| Cursor | Use specops to [description] |
| OpenAI Codex | Use specops to [description] |
| GitHub Copilot | Use specops to [description] |
Create .specops.json in your project root. Configuration is optional. SpecOps uses sensible defaults.
{
"specsDir": ".specops",
"vertical": "backend",
"team": {
"conventions": ["Use TypeScript", "Write tests for business logic"],
"reviewRequired": true
}
}Examples: examples/ | Full schema reference: REFERENCE.md | Steering files: STEERING_GUIDE.md
Specs generated by SpecOps follow writing principles from Rich Sutton (importance ordering), George Orwell (cut unnecessary words), Jeff Bezos (narrative over bullet points), Leslie Lamport (precision over completeness), and Steven Pinker (concrete over abstract). Every requirement passes the ANT test (Arguably Not True): if a statement cannot be false, it carries no information and gets rewritten. Full writing rules.
Design and implementation follow engineering principles from Fred Brooks (conceptual integrity), Barbara Liskov (substitutability), Kent Beck (test-first development), Nancy Leveson (failure reasoning), and Eliyahu Goldratt (constraint identification). Every component gets one responsibility, every integration point documents its failure mode, and every acceptance criterion maps to a test. Full engineering rules.
Contributions welcome. See CONTRIBUTING.md for guidelines.