to-spec
Skill2 starsChanged 4 months agoMITView on GitHub
Use when settled requirements need a clear execution contract. Applies a lightweight in-session specification automatically for medium jobs and a durable traceable draft when explicitly requested or when complex work needs persistent acceptance evidence.
195 other projects use a version of this.
Adopted by
Most recently taken up by
- bepaldes/heimdall-agenttheir own version, first seen Nov 16, 2026
- philoserf/claude-code-configtheir own version, first seen Nov 15, 2026
- Kealman/cland-v0their own version, first seen Nov 15, 2026
- ydavidtimothy-spec/skillstheir own version, first seen Nov 15, 2026
- trajectonomics/skillstheir own version, first seen Nov 15, 2026
- hanjiang-215/ticket-index-skillstheir own version, first seen Nov 15, 2026
Used with
Projects with it also use setup-ts-deep-modules, to-questionnaire and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
liufeng1976Skillsetup-ts-deep-modules
Wire dependency-cruiser into a TypeScript repo so each package is a deep module — implementation hidden in subfolders, reachable only through its entry-point files. User-invoked.
Also in 43 projects that use this
AWSSkillto-questionnaire
Turn a decision you can't fully answer into a questionnaire for someone else to fill in.
Also in 90 projects that use this
RoentekSkillloop-me
Grill me about specs for the workflows I want to build, within this workspace.
Also in 49 projects that use this
AWSSkillwizard
Generate an interactive bash wizard that walks a human through steps only they can perform. Use when provisioning infrastructure, setting up credentials or CI secrets, walking an unfamiliar third-party dashboard, or running a one-off migration or cutover. Don't invoke this for steps the agent can perform itself.
Also in 116 projects that use this
ryotaroh180105Skillclaude-handoff
Hand the current conversation off to a fresh background agent that picks up the work immediately.
Also in 39 projects that use this
LesaniSkillwriting-beats
Shape an article as a journey of beats, choose-your-own-adventure style. The user picks a starting beat from the raw material, you write only that beat, then offer options for where to pivot next, beat by beat, until the article reaches a natural end. Use when the user has raw material and wants to assemble it as a narrative rather than an argument.
Also in 51 projects that use this
- +2 more from aws
Other versions195 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 195
- mattpocock/skills★ 325ksame name
- QuivrHQ/quivr★ 40ksame name
- The-Vibe-Company/quivr★ 40ksame name
- formbricks/formbricks★ 13ksame name
- ArcReel/ArcReel★ 6.6ksame name
- vinvcn/mattpocock-skills-zh-CN★ 5.8ksame name
- withcoral/coral★ 4.9ksame name
- bestofjs/bestofjs★ 3.1ksame name
- moeru-ai/xsai★ 667same name
- nodetool-ai/nodetool★ 637same name
185 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository12 other files it gives its agents.
- bounded-grillingSkill
- burnable-visual-briefsSkill
- context-budget-orchestrationSkill
- hermes-backup-recoverySkill
- hermes-workspace-hygieneSkill
- kanban-workflowsSkill
- planSkill
- prototypeSkill
- skill-lifecycle-managementSkill
- to-ticketsSkill
- wayfinderSkill
- wfSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
35 rules. 0 are common, 31 are distinctive, and 4 are very specific to this project.
0
Common
Most of the 183 edited versions we read keep these.
31
Distinctive
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 57
Use LIGHT automatically when a concise contract would reduce drift but a persistent specification would be disproportionate.
- Distinctive: line 87
Use FULL when the user explicitly requests a specification, when a valid FULL Wayfinder handoff is ready, or automatically when any of …
- Very specific: line 98
When selecting FULL automatically, announce that choice in one sentence and name the intended artifact path or chat-only.
- Distinctive: line 108
Do not interview the user or reopen settled decisions.
- Distinctive: line 109
Do not silently choose among unresolved route-changing alternatives.
- Very specific: line 110
Do not publish to an external tracker, apply labels, notify collaborators, create implementation tickets, invoke plan, implement, commit, …
- Distinctive: line 122
Use one or more of:
- Distinctive: line 131
Do not require a specific tracker or named research skill.
- Distinctive: line 139
When the source is Bounded Grill:
- Very specific: line 146
Treat suspected fog as empty or explicitly non-route-changing.
- Distinctive: line 157
When the source is Wayfinder:
- Distinctive: line 198
Do not ask the missing questions inside To-Spec.
- Distinctive: line 206
Before declaring specification readiness, each acceptance criterion must state, directly or through an explicit shared scope:
- Distinctive: line 228
If a missing threshold, scope, rubric or evaluation method changes success meaning or authority, use the existing BLOCKED route.
- Distinctive: line 252
When a higher-priority source supersedes a lower-priority record, preserve the old handle, mark it stale or superseded, and explain the …
- Distinctive: line 273
Do not write code or mutate the inspected project during this pass.
- Distinctive: line 291
Prefer complete coverage over extensive prose.
- Distinctive: line 370
every current authoritative decision/source handle has a row.
- Distinctive: line 371
every row maps to a requirement, constraint, acceptance item, or explicit out-of-scope disposition.
- Distinctive: line 373
every negative requirement and material exception remains visible.
- Distinctive: line 374
no stale or superseded record is treated as current.
- Distinctive: line 375
every acceptance statement passes the measurable-acceptance gate above.
- Distinctive: line 376
every unsupported claim is marked as an assumption.
- Distinctive: line 377
no requirement expands scope without an authoritative source.
- Very specific: line 379
Use gap rather than pretending coverage when a decision was weakened, omitted, contradicted, or cannot be verified.
- Distinctive: line 385
When the specification or LIGHT contract passes its coverage/readiness gate, To-Spec may return this traceable downstream packet without …
- Distinctive: line 412
If the specification changes, invalidate the snapshot, coverage evidence, and any downstream draft graph.
- Distinctive: line 414
Do not invoke To-Tickets automatically.
- Distinctive: line 430
create a tracker issue or external document.
- Distinctive: line 433
create implementation tickets or modify a FULL Wayfinder map.
- Distinctive: line 434
start planning or implementation.
- Distinctive: line 436
After producing the draft, report:
- Distinctive: line 470
Conversation-only synthesis: Use authoritative source handles.
- Distinctive: line 477
Execution signaling: Never apply an agent-ready label automatically.
- Distinctive: line 485
FULL for every job: Prefer LIGHT when persistence and complete coverage would cost more than they save.
“Common” is measured: kept by at least 6 in 10 of the 183 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Traceable To-Spec
Lineage
This is an MIT-licensed adaptation of Matt Pocock's public
to-spec.
It retains conversation-to-spec synthesis without another interview while
adding Hermes-specific authority, traceability, coverage, blocking, safety,
and persistence contracts.
The complete upstream MIT notice is preserved in
references/third-party-notices.md.
Overview
To-Spec compiles already-settled decisions, evidence, and project context into a reviewable specification. It preserves authoritative source handles, makes negative requirements explicit, and proves coverage. It does not itself create publication, task-creation, or implementation authority.
It is a compiler, not an interview or planning loop:
clear route:
Bounded Grill or settled conversation -> To-Spec
large or foggy route:
Bounded Grill -> Wayfinder -> To-Spec
approved implementation decomposition:
To-Spec -> To-Tickets -> optional per-ticket Plan / authorized executionTo-Tickets is a separate, explicitly invoked compiler. To-Spec may emit a traceable handoff but never drafts, publishes, labels, or runs tickets itself.
Adaptive invocation and operating level
Choose LIGHT or FULL before compiling.
LIGHT — model-invokable, embedded contract
Use LIGHT automatically when a concise contract would reduce drift but a persistent specification would be disproportionate. Typical signals include two or more of:
- the goal is settled and at least two constraints or acceptance conditions matter;
- the job has at least three meaningful steps or touches multiple seams;
- the user has already authorized planning, building, shipping, or review and a short requirements check would improve fidelity;
- a LIGHT Wayfinder route is ready to become concrete;
- scope, out-of-scope, assumptions, or recovery boundaries need to be explicit.
LIGHT remains in the current conversation and creates no file, issue, label, tracker item, or durable handoff. Keep it compact:
Goal
Scope / out of scope
Requirements and constraints
Observable acceptance
Assumptions / gaps
Authorized next actionLIGHT may be embedded inside an already-authorized task and then return control to that task. It does not create new authority, but it also does not cancel planning or implementation that the user already explicitly authorized.
FULL — durable traceable draft
Use FULL when the user explicitly requests a specification, when a valid FULL Wayfinder handoff is ready, or automatically when any of these hard signals makes durable coverage materially valuable:
- the work will likely span sessions or reviewers;
- three or more authoritative decisions or source handles must remain traceable;
- an external interface, migration, safety boundary, or costly rollback is involved;
- persistent acceptance evidence is needed for implementation or handoff.
When selecting FULL automatically, announce that choice in one sentence and
name the intended artifact path or chat-only. Persist only to an already
authorized project convention or path. External publication, tracker mutation,
labels, notifications, tasks, and implementation remain separately governed
by the current user request.
Authority boundary
- FULL produces a
DRAFTspecification unless the user explicitly assigns another reviewed state. LIGHT produces only an in-session contract. - Do not interview the user or reopen settled decisions.
- Do not silently choose among unresolved route-changing alternatives.
- Do not publish to an external tracker, apply labels, notify collaborators,
create implementation tickets, invoke
plan, implement, commit, or deploy unless that exact downstream action is independently authorized by the current user request. - A specification never creates new implementation authority. After LIGHT or FULL, continue only with downstream actions the user already explicitly authorized; otherwise stop at the contract or draft.
- External publication, task creation, planning, and implementation each require explicit authority; one never implies another.
Accepted inputs
Use one or more of:
- a Bounded Grill
DIRECT_SPECpacket; - a settled conversation with identifiable decisions and evidence;
- a
wayfinder-to-spec-v1packet plus its authoritative map and decision tickets; - existing project requirements, policy records, ADRs, or specifications;
- relevant codebase and documentation evidence.
Do not require a specific tracker or named research skill. Use the tools and source hierarchy available in the active profile.
LIGHT may compile an ordinary settled task or LIGHT Wayfinder route without a schema packet. The strict handoff contracts below apply to FULL.
FULL Grill handoff contract
When the source is Bounded Grill:
- Require
schema: grill-route-v1. - Continue only for
route: DIRECT_SPEC. - Require destination, accepted decision handles or exact accepted values, constraints, negative requirements, evidence handles, suspected fog, out-of-scope boundaries, and persistence status.
- Treat suspected fog as empty or explicitly non-route-changing. Otherwise
return
BLOCKEDand route to Wayfinder. - Allow
persistence: pendingonly when exact accepted values and actual source timestamps are present; the resulting specification must preserve them as its first durable consumer.
For WAYFINDER, return the packet for Wayfinder and stop. For BLOCKED,
preserve the named evidence or authority blocker and stop.
FULL Wayfinder handoff contract
When the source is Wayfinder:
- Require
schema: wayfinder-to-spec-v1. - Continue only for
outcome: READY_FOR_SPEC. - Require destination, map handle, every current decision handle, scope,
out-of-scope boundaries, evidence handles, assumptions/non-blocking
deferrals, stale/superseded handles, readiness owner, actual timestamp, and
persistence: confirmed. - Resolve each handle from its authoritative record; do not treat the packet gist as a replacement for ticket rationale.
- Return
BLOCKEDwhen the packet is incomplete, stale, contradictory, or not durably persisted.
For DESTINATION_COMPLETE_WITHOUT_SPEC, report that To-Spec is not applicable
and stop. For BLOCKED, preserve Wayfinder's blockers and stop.
Readiness gate
For LIGHT, run a compact readiness check and expose material gaps instead of inventing decisions. For FULL, inspect the supplied sources and classify every material gap before drafting.
Return BLOCKED instead of a specification when any of these remain:
- an unresolved decision can change scope, destination, architecture or execution class, supported cohort, authority or safety boundary, dependency structure, or acceptance method;
- accepted decisions materially contradict one another;
- a required authoritative record is stale, superseded, or unavailable;
- critical evidence cannot be obtained without guessing;
- the requested output would require authority the user has not granted.
For each blocker, return:
gap
why it changes the route or authority
decision/evidence owner
recommended route: bounded-grilling | wayfinder | evidence lookupDo not ask the missing questions inside To-Spec. Route them to the owning workflow and stop.
Non-route-changing implementation details may remain explicit assumptions or local-spec choices when they are safe, reversible, and testable.
Measurable acceptance (LIGHT and FULL)
Before declaring specification readiness, each acceptance criterion must state, directly or through an explicit shared scope:
- the supported situations, starting conditions and triggering operation;
- the observable expected outcome, evidence source and evaluation method;
- the pass/fail rule, including any expected blocked or inconclusive outcome;
- a valid baseline and relevant negative/boundary cases, plus what passing does not establish.
Measurable does not mean numerical: a qualitative criterion may use an explicit rubric, named decision owner and reviewable artifact. LIGHT may express these in one Given/When/Then statement; FULL reuses its acceptance matrix. Do not add mandatory documents, exhaustive case combinations or a testing framework for simple requirements.
Tests implement agreed criteria; they must not silently define ambiguous ones.
A model's confidence label, a field named equivalent, or an unchanged binding
hash is not by itself evidence of causality, semantic equivalence or meaningful
progress. Name the criterion-specific observation/comparison that establishes
the claim within its supported scope. Do not turn bounded protocol conformance
into a promise to solve every task or prove arbitrary prompt/program equivalence.
If a missing threshold, scope, rubric or evaluation method changes success meaning or authority, use the existing BLOCKED route. Do not invent the missing value, hide it as an assumption, silently narrow an accepted requirement, or create new machinery just to make it appear testable. Do not reopen a settled, sufficiently measurable criterion or ask about ordinary reversible details.
Specification readiness is not implementation acceptance: an unimplemented but fully specified behavior can be ready. Conversely, passing authored tests does not prove requirement coverage. When consuming existing test results, preserve source requirement IDs, negatives and exceptions; distinguish covered criteria from unproven ones instead of reshaping the specification to fit green tests. An expected blocking outcome can pass its own case without proving the valid success path or the entire feature complete.
Source precedence
Apply this order:
- current accepted Wayfinder or project decision records;
- the user's current explicit direction;
- applicable project instructions, policies, and requirements;
- verified repository state and source documentation;
- explicit assumptions.
When a higher-priority source supersedes a lower-priority record, preserve the old handle, mark it stale or superseded, and explain the replacement. Never resolve a contradiction by silently blending incompatible statements.
Grounding pass
Inspect only the relevant context needed to ground the specification:
- project instructions and accepted requirements;
- authoritative decision records and their current status;
- domain vocabulary and applicable ADRs;
- current interfaces, seams, behavior, and prior tests;
- primary sources for externally constrained facts.
Separate:
- observed facts with handles;
- accepted human decisions with handles;
- safe local-spec choices;
- explicit assumptions requiring later verification.
Do not write code or mutate the inspected project during this pass.
FULL compilation process
- Inventory all current decision IDs or source handles.
- Preserve the exact force of each accepted value, including exceptions, constants, ordering, defaults, retry behavior, negative requirements, and rejected alternatives that constrain implementation.
- Assign spec-local requirement IDs such as
REQ-001. These identify requirements only; they never replace or renumber authoritative decision IDs. - Draft the specification using the template below.
- Map every current decision/source handle to its concrete coverage.
- Audit for omission, weakening, contradiction, unsupported expansion, stale references, and unverifiable acceptance language.
- Return
BLOCKEDif the audit exposes a route-changing gap; otherwise emit the draft and completion report.
Prefer complete coverage over extensive prose. Merge redundant user stories or requirements rather than repeating them.
FULL specification template
# <Specification title>
Status: DRAFT
Generated: <actual timestamp from a time tool>
Destination/source: <Wayfinder map, Grill packet, conversation, or project handles>
## Problem and destination
<Current problem, intended outcome, and why it matters.>
## Users and observable outcomes
<Actors, affected cohorts, and independently observable outcomes.>
## Scope
<Included behavior and boundaries.>
## Out of scope
<Explicit exclusions and reasons when material.>
## Requirements
### REQ-001 — <short requirement name>
- Requirement:
- Source decisions/evidence:
- Constraints and exceptions:
- Negative requirements:
- Observable acceptance:
## Accepted decisions and constraints
<Authoritative decision handles, accepted values, and rationale pointers.
Do not replace the authoritative record with a weaker summary.>
## Solution and seams
<High-level solution shape and the stable interfaces, operational boundaries,
or domain-specific seams where behavior can be observed and verified.>
## Acceptance and verification evidence
| Requirement | Observable outcome | Verification method | Required evidence |
|---|---|---|---|
| REQ-001 | ... | ... | ... |
## Safety, recovery, and authority boundaries
<Side-effect limits, failure handling, rollback/recovery expectations, and
actions that still require human authorization.>
## Assumptions and non-blocking deferrals
<Explicit, testable assumptions and deferred details that do not change the
selected route.>
## Decision coverage
| Decision/source handle | Status | Covered by | Fidelity check |
|---|---|---|---|
| ... | current | REQ-001 / constraint / out-of-scope | exact / strengthened / gap |Adapt section vocabulary to the domain. For software, seams may be APIs, modules, user interfaces, or integration tests. For non-software work, use the relevant operational boundaries and evidence surfaces instead.
FULL coverage gate
The draft passes only when:
- every current authoritative decision/source handle has a row;
- every row maps to a requirement, constraint, acceptance item, or explicit out-of-scope disposition;
- every negative requirement and material exception remains visible;
- no stale or superseded record is treated as current;
- every acceptance statement passes the measurable-acceptance gate above;
- every unsupported claim is marked as an assumption;
- no requirement expands scope without an authoritative source.
Use gap rather than pretending coverage when a decision was weakened,
omitted, contradicted, or cannot be verified. A route-changing gap changes the
result to BLOCKED.
To-Tickets handoff
When the specification or LIGHT contract passes its coverage/readiness gate, To-Spec may return this traceable downstream packet without creating tickets:
schema: to-spec-ticketization-v1
spec_state: LIGHT_READY | DRAFT_READY
spec_handle: <chat handle or authorized path>
source_snapshot: <version/revision/content fingerprint>
source_owner: <acceptance owner>
requirement_ids: []
decision_handles: []
evidence_handles: []
coverage_status: passed
grounding_status: passed
persistence: none | confirmed
decomposition_authority: pending | granted
publication_authority: noneRules:
- Emit it only after the selected To-Spec readiness and coverage gates pass.
decomposition_authority: grantedrequires the current user to explicitly accept this exact source snapshot for To-Tickets decomposition; otherwise usepending.publication_authorityis alwaysnone. To-Tickets must show the complete graph and obtain separate approval bound to that exact graph and backend.- If the specification changes, invalidate the snapshot, coverage evidence, and any downstream draft graph.
- Do not invoke To-Tickets automatically. Return the packet and stop unless the current request already explicitly includes ticket decomposition.
Output and persistence
LIGHT stays in chat and reports its compact contract plus the authorized next action; it writes no artifact.
For FULL, if the user supplied an authorized local path or the active project
has a clear specification convention, write the DRAFT there. Otherwise
return the complete draft in chat and ask where it should be saved only if
persistence is needed.
Unless the current user request explicitly authorized the named downstream action, do not:
- create a tracker issue or external document;
- apply
ready-for-agentor any equivalent execution-facing state; - mark the specification accepted on the user's behalf;
- create implementation tickets or modify a FULL Wayfinder map;
- start planning or implementation.
After producing the draft, report:
- artifact path or
chat-only; - source handles consumed;
- requirement and decision-coverage counts;
- assumptions, deferrals, and gaps;
- ticketization handoff state (
not-emitted,pending, orgranted) and source snapshot when emitted; - any external publications, tasks, labels, planning, or implementation
actions actually taken, plus their explicit authority source; normally
none.
Completion states
LIGHT returns exactly one:
LIGHT_READY— compact in-session contract is complete and may return to an already-authorized task;BLOCKED— a route-changing decision, contradiction, authority gap, or critical evidence gap remains.
FULL returns exactly one:
DRAFT_READY— the durable specification and coverage audit are complete;BLOCKED— a route-changing decision, contradiction, authority gap, or critical evidence gap remains.
LIGHT_READY and DRAFT_READY describe contract readiness only. Neither means
accepted, published, ready for an agent, or newly authorized for
implementation.
Common pitfalls
- Re-interviewing. Route missing decisions to Bounded Grill or Wayfinder.
- Conversation-only synthesis. Use authoritative source handles.
- Summary weakening. Preserve exceptions, negatives, constants, and rationale pointers.
- Prose inflation. Optimize for complete coverage, not maximum length.
- Assumption laundering. Mark unsupported claims explicitly.
- Stale decisions. Preserve history but compile only current records.
- Premature publication. A draft is local/chat-only without approval.
- Execution signaling. Never apply an agent-ready label automatically.
- Ticketization leakage. A downstream handoff does not draft or publish tickets; decomposition and publication remain separately authorized.
- Task leakage. Requirements and acceptance evidence are not an implementation task list.
- Implementation drift. FULL stops after the draft unless the current request already authorized downstream work; LIGHT returns only to work already authorized.
- FULL for every job. Prefer LIGHT when persistence and complete coverage would cost more than they save.
Verification checklist
- LIGHT or FULL was selected from observable task signals.
- LIGHT created no file, issue, label, tracker item, or durable handoff.
- Any automatic FULL selection was announced with an authorized path or
chat-onlytarget. - Any FULL Grill input passed the
grill-route-v1contract. - Any FULL Wayfinder input passed the
wayfinder-to-spec-v1contract. - Readiness was checked before drafting.
- No unresolved route-changing decision was silently answered.
- Relevant project and source evidence was inspected.
- Facts, decisions, local choices, and assumptions are distinct.
- For FULL, every current decision/source handle has coverage.
- Negative requirements and exceptions remain explicit at the selected operating level.
- Acceptance outcomes and evidence methods are observable at the selected operating level.
- The output state is
LIGHT_READY,DRAFT_READY, orBLOCKED. - Any ticketization handoff conforms to
to-spec-ticketization-v1, binds one exact source snapshot, and leaves publication authoritynone. - To-Spec created no ticket graph, ticket file, tracker issue, or agent-ready label.
- No external publication, label, task, plan, or implementation occurred without explicit authority from the current user request.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

