/ct-spec-writer

name: ct-spec-writer
description: Technical specification writing using RFC 2119 language for clear, unambiguous requirements. Creates protocol specifications, technical requirements, API specifications, and architecture documents with testable requirements and compliance criteria. Use when writing specifications, defining protocols, documenting requirements, or creating API contracts. Triggers on specification tasks, protocol definition needs, or requirement documentation.
version: 2.1.2
protocol: specification
adrRefs:
  - ADR-014
  - ADR-023
dependencies: []
sharedResources:
  - subagent-protocol-base
  - task-system-integration
compatibility:
  - claude-code
  - cursor
  - windsurf
  - gemini-cli
license: MIT
metadata:
  version: 2.1.2
  tier: on-demand
  install: harness
  covers:
    - packages/core/src/validation/protocols/cant/specification.cant
    - packages/core/src/validation/protocols/protocols-markdown/specification.md
  loomStage: specification
  lastReviewed: 2026-09-28
  stability: stable

Specification Writer Context Injection

**Protocol**: @src/protocols/specification.md **Type**: Context Injection (cleo-subagent) **Version**: 2.0.0

---

Purpose

Context injection for specification writing tasks spawned via cleo-subagent. Provides domain expertise for creating clear, unambiguous technical specifications using RFC 2119 language.

---

Capabilities

1. **Protocol Specifications** - Define behavior rules with RFC 2119 keywords 2. **Technical Requirements** - Document system requirements with constraints 3. **API Specifications** - Define interfaces, schemas, and contracts 4. **Architecture Documents** - Document system design decisions

---

RFC 2119 Keywords (MANDATORY)

Use these keywords with their precise meanings:

| Keyword | Meaning | Compliance | |---------|---------|------------| | **MUST** | Absolute requirement | 95-98% | | **MUST NOT** | Absolute prohibition | 93-97% | | **SHOULD** | Recommended unless good reason exists | 75-85% | | **SHOULD NOT** | Discouraged unless good reason exists | 75-85% | | **MAY** | Truly optional | 40-60% |

---

Specification Structure

Standard Layout

# {Specification Title} v{X.Y.Z}

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHOULD",
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document
are to be interpreted as described in RFC 2119.

---

## Overview

{2-3 sentence summary of what this spec defines}

---

## Definitions

| Term | Definition |
|------|------------|
| {term} | {definition} |

---

## Requirements

### {Category 1}

**REQ-001**: {Requirement description}
- Rationale: {Why this requirement exists}
- Verification: {How to verify compliance}

### {Category 2}

**REQ-002**: {Requirement description}
...

---

## Constraints

| ID | Constraint | Enforcement |
|----|------------|-------------|
| CON-001 | {constraint} | {how enforced} |

---

## Compliance

A system is compliant if:
1. {condition 1}
2. {condition 2}
3. {condition 3}

Non-compliant implementations SHOULD {remediation}.

---

Writing Guidelines

Be Precise

• Every requirement MUST be testable
• Avoid ambiguous terms ("appropriate", "reasonable", "adequate")
• Use specific values, not ranges when possible

Be Complete

• Define all terms that might be misunderstood
• Cover error cases and edge conditions
• Specify what happens when requirements conflict

Be Organized

• Group related requirements
• Use consistent numbering (REQ-XXX, CON-XXX)
• Cross-reference related sections

---

Through SDK (preferred)

Specifications are first-class docs SSoT records — created via `cleo docs add --type spec`, auto-attached to the parent task, and addressable by a stable slug. This is the canonical write path; the legacy "write to `docs/specs/<NAME>.md` and commit" pattern is deprecated below.

Write the spec attached to its parent task

cleo docs add T1234 docs/specs/auth-protocol.md \
  --type spec \
  --slug auth-protocol-v2 \
  --desc "Auth protocol v2 — RFC 2119 requirements"

• `--type spec` is the canonical taxonomy value for a specification.

Other allowed values: `adr | research | handoff | note | llm-readme`.

• `--slug` is the kebab-case retrieval handle. Use the spec topic +

version (e.g. `auth-protocol-v2`, `release-pipeline-v3`). The CLI returns `E_SLUG_RESERVED` with 3 alternatives on collision (legacy `E_SLUG_TAKEN` aliased under `details.aliases` for one release — T10386) — pick one rather than silently overwriting.

• Near-duplicate slugs (e.g. `auth-protocol-v2` vs an existing

`auth-protocol`) surface a `W_SLUG_SIMILAR` warning with the top match (T10361). Pass `--allow-similar` to proceed when the new spec intentionally forks; every bypass is audited to `.cleo/audit/similar-bypass.jsonl`.

• Unknown flags fail fast with `E_UNKNOWN_FLAG` + did-you-mean

suggestions (T10359) — `--titel`/`--lables` become "did you mean --type/--labels?". Run `cleo docs add --help` for the canonical surface.

• The owner ID (`T1234`) auto-attaches the spec to its parent task so

downstream stages (`ct-validator`, decomposition, implementation) can discover the spec via `cleo docs list --task T1234 --type spec`.

Publish the spec to a git-tracked path (when the spec must ship on disk)

cleo docs publish --for T1234 --to docs/specs/auth-protocol.md

Atomic tmp-then-rename. The published file lands in the next commit; the SSoT blob remains canonical and continues to track future versions.

Fetch the spec back by slug

cleo docs fetch auth-protocol-v2          # latest version
cleo docs versions --for T1234            # every SHA version

Discover sibling specs in this project

cleo docs list --type spec --project      # every spec in the project
cleo docs list --task T1234 --type spec   # specs attached to T1234

Deprecated: Direct filesystem write

The legacy "write to `docs/specs/{{SPEC_NAME}}.md` an