/cspec — Write a Feature Specification

Turn a feature idea into a structured specification with testable rules before any code is written.

When to Use

  • Starting a new feature — before writing any code or tests
  • After creating a feature branch and before the TDD cycle
  • When you need to clarify requirements and surface edge cases early
  • Not for: bug fixes (use /cdebug), refactoring (use /crefactor), or changes that already have an approved spec

How It Fits in the Workflow

/cspec is the first skill you run after /csetup. It produces the spec document that drives everything downstream. After the spec is approved, you run /creview to challenge it with fresh eyes. The full pipeline is: /cspec → /creview → /ctdd → /cverify → /cdocs → merge.

What It Does

  1. Socratic brainstorm — challenges your assumptions with targeted questions: “What problem does this solve? Not the feature — the problem.” Scales depth to your confidence level.
  2. Reads project context — ARCHITECTURE.md, antipatterns, drift debt, QA history, and recent git log to ground the spec in your codebase’s reality
  3. Researches current best practices (when needed) — spawns a dedicated research agent (agents/cspec-research.md) with web search tools for topics where training data may be stale (new library versions, security protocols, rapidly-evolving APIs). Web content is treated as untrusted advisory data. Saves findings to an artifact.
  4. Drafts the spec — at standard intensity, produces Rules (R-001, R-002…) with test levels. At high/critical intensity, produces Invariants, Prohibitions, Boundary Conditions, and optionally STRIDE analysis.
  5. Walks you through the spec — presents rules in small groups for approval, resolves open questions, checks against known antipatterns, and advances the workflow state when approved

Example 

User: /cspec — add rate limiting to the login endpoint

Agent: Before writing the spec, let me understand the problem.
       What's driving this? Brute force attacks, or general API abuse?

User: Brute force. We've had credential stuffing attempts.

Agent: What's the simplest version that would be useful? Per-IP limiting,
       per-account limiting, or both?

User: Per-account first. IP limiting can come later.

Agent: Based on our discussion, here's what I understand: rate limiting on
       the login endpoint to prevent credential stuffing, scoped to
       per-account lockout. IP-based limiting is out of scope for now.

       [reads ARCHITECTURE.md, antipatterns, recent git log]

       # Spec: Login Rate Limiting

       ## Rules
       - **R-001** [unit]: After 5 failed login attempts for the same email
         within 15 minutes, subsequent attempts return 429 with a
         Retry-After header
       - **R-002** [integration]: The lockout counter resets after a
         successful login
       - **R-003** [unit]: The lockout duration is configurable via
         environment variable (default: 15 minutes)
       - **R-004** [integration]: Rate limit state persists across server
         restarts (stored in Redis/database, not in-memory)
       - **R-005** [unit]: The 429 response does not reveal whether the
         email exists in the system

       Does this look right? Anything to add or change?

What It Reads / Writes

Reads Writes
AGENT_CONTEXT.md .correctless/specs/{task-slug}.md
ARCHITECTURE.md .correctless/artifacts/research/{slug}-research.md (if research triggered)
.correctless/antipatterns.md .correctless/artifacts/token-log-{slug}.json
.correctless/meta/drift-debt.json (high+ intensity) Workflow state (advances to review phase)
.correctless/artifacts/qa-findings-*.json  
Git log (recent 20 commits)  

Integration Test Contracts

For [integration] rules, /cspec defines Entry/Through/Exit contract constraints derived from .correctless/ARCHITECTURE.md entrypoints (ABS-023). The contract format (ABS-024) tells the TDD agent exactly what the integration test must exercise:

  • Entry: which entrypoint the test must use (from the entrypoint’s test_via field)
  • Through: which components must be exercised and which must NOT be mocked
  • Exit: what observable behavior must hold (expressible as a test assertion without internal state)

If no entrypoints are defined in ARCHITECTURE.md, the skill prompts you to run /carchitect first or skip contracts for this spec. Rules tagged [unit] are not affected — contracts apply only to [integration] rules.

Architecture Awareness

At high+ intensity, /cspec mechanically identifies which trust boundaries (TB-xxx) and design patterns (PAT-xxx) from .correctless/ARCHITECTURE.md are relevant to the feature being specified.

Trust boundary matching (high+ intensity): After gathering the feature’s file scope, the skill extracts all TB-xxx entries and matches them against the feature’s affected files. Matching uses file-scope overlap (comparing file paths against TB entry references) with keyword fallback for TB entries that lack file path references. You confirm the matched list before STRIDE analysis runs. Per-TB security questions are derived from each boundary’s documented invariant, not from generic security keywords.

Pattern detection (all intensities): After drafting spec rules, the skill checks whether any rule introduces a convention not covered by an existing PAT-xxx entry. If so, it asks whether the pattern should be flagged for /cupdate-arch after implementation.

Pattern composition check (high+ intensity): For each potential new pattern, the skill checks it against existing PAT-xxx entries and warns if it contradicts or duplicates an existing pattern.

When ARCHITECTURE.md has no TB-xxx or PAT-xxx entries, these features are dormant — no error, no warning.

Intensity Levels

Standard intensity produces 5 sections: What, Rules (R-xxx with test levels), Won’t Do, Risks, Open Questions. Simple and fast.

High/critical intensity scales artifact weight by intensity level. High adds Boundary Conditions and Complexity Budget. Critical adds STRIDE analysis, Environment Assumptions, and Design Decisions. At high/critical intensity, the skill also checks drift debt and recommends an intensity level based on trust boundaries touched.

Common Issues

  • On the main branch: The skill will tell you to create a feature branch first. The workflow state machine requires a feature branch.
  • Research takes a while: If the skill spawns the research agent (for new libraries, security topics, or rapidly-evolving APIs), expect 1-3 extra minutes. The agent searches the web for current information. It announces when research starts and finishes.
  • Spec feels over-specified: Start with fewer rules. You can always add more during /creview. The review skill exists specifically to catch what you missed.