spec

name	spec
description	Create or modify a spec following the project's spec format and conventions. Use when the user wants to write a new spec, add requirements or scenarios to an existing spec, or restructure spec content. Triggers on: "write a spec", "create a spec", "add a requirement", "spec this out", "define the behavior", "what should the spec look like", "new spec for", "update the spec".

Write or Modify a Spec

Help the user create or change a spec that describes desired system behavior.

User Input

$ARGUMENTS

Before Anything Else

Read these two files in full before proceeding:

1. specs/index.spec.md — what a spec is, the required format, naming conventions, and what does and does not belong
2. workflows/specs/spec-change.workflow.md — the full spec change workflow (framing, grounding, drafting, critic passes, synthesis)

Then follow the workflow phases in order.

Steps

Phase 1 — Frame

Establish the framing before writing anything:

• Desired state only. Ask the user what the system should do, not what's currently broken. If they describe a bug, redirect: "What should the correct behavior be?"
• Scope boundary. Which bounded contexts does this change touch? (IAM, Management, Ingestion, Extraction, Graph, Query, Shared Kernel, UI)
• Reserved terms check. Verify no collision with Kartograph domain model terms (KnowledgeGraph, DataSource, Tenant, Workspace, Group, APIKey, SyncRun, JobPackage, MutationLog, Adapter, EncryptedCredential, DomainProbe, etc.)

Phase 2 — Ground in the codebase

Read actual code and existing specs in the affected areas. Confirm your understanding without wasting the user's time:

• Read existing specs in the target domain
• Grep the bounded contexts identified in Phase 1
• Summarize back in 3-5 sentences: what you found, what you believe they want, what's ambiguous
• Ask only where the codebase doesn't give a clear answer

Do not proceed to drafting until the user confirms.

Phase 3 — Draft the Spec

Follow the format from specs/index.spec.md:

• Purpose section — one paragraph describing the domain or feature
• Requirements — each states an observable behavior using RFC 2119 keywords (SHALL, MUST, SHOULD, MAY)
• Scenarios — concrete Given/When/Then examples for each requirement that could be turned into tests

Include: data model, write paths, read paths, authorization (SpiceDB), migration plan for all existing consumers.

Phase 4 — Critic Pass

Spawn critics in parallel per the workflow. Standard critics (every spec change):

• Schema / migration
• SpiceDB authorization
• Kartograph terminology

Plus scope-driven critics based on the bounded contexts identified in Phase 1.

Phase 5-6 — Synthesize and Present

Separate findings into factual errors (fix directly) and design decisions (present to user with 2-3 concrete options each, one at a time).

Phase 7 — Apply and Verify

Apply all fixes. Run a second critic pass (Phase 8). Stop when only MINORs remain.

Final — Name and Place the File

• Filename: <descriptive-title>.spec.md
• If the spec exceeds ~300 words or covers multiple distinct topics, split into a directory with multiple files
• Place in specs/{bounded-context}/