agentleFS
SaikaAcoSaikaAco/saika-hermes-skills/skills/to-spec/SKILL.md

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

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.
  • liufeng1976Skill

    setup-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

  • AWSSkill

    to-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

  • RoentekSkill

    loop-me

    Grill me about specs for the workflows I want to build, within this workspace.

    Also in 49 projects that use this

  • AWSSkill

    wizard

    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

  • ryotaroh180105Skill

    claude-handoff

    Hand the current conversation off to a fresh background agent that picks up the work immediately.

    Also in 39 projects that use this

  • LesaniSkill

    writing-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

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
  1. Distinctive:

    Use LIGHT automatically when a concise contract would reduce drift but a persistent specification would be disproportionate.

    line 57
  2. Distinctive:

    Use FULL when the user explicitly requests a specification, when a valid FULL Wayfinder handoff is ready, or automatically when any of …

    line 87
  3. Very specific:

    When selecting FULL automatically, announce that choice in one sentence and name the intended artifact path or chat-only.

    line 98
  4. Distinctive:

    Do not interview the user or reopen settled decisions.

    line 108
  5. Distinctive:

    Do not silently choose among unresolved route-changing alternatives.

    line 109
  6. Very specific:

    Do not publish to an external tracker, apply labels, notify collaborators, create implementation tickets, invoke plan, implement, commit, …

    line 110
  7. Distinctive:

    Use one or more of:

    line 122
  8. Distinctive:

    Do not require a specific tracker or named research skill.

    line 131
  9. Distinctive:

    When the source is Bounded Grill:

    line 139
  10. Very specific:

    Treat suspected fog as empty or explicitly non-route-changing.

    line 146
  11. Distinctive:

    When the source is Wayfinder:

    line 157
  12. Distinctive:

    Do not ask the missing questions inside To-Spec.

    line 198
  13. Distinctive:

    Before declaring specification readiness, each acceptance criterion must state, directly or through an explicit shared scope:

    line 206
  14. Distinctive:

    If a missing threshold, scope, rubric or evaluation method changes success meaning or authority, use the existing BLOCKED route.

    line 228
  15. Distinctive:

    When a higher-priority source supersedes a lower-priority record, preserve the old handle, mark it stale or superseded, and explain the …

    line 252
  16. Distinctive:

    Do not write code or mutate the inspected project during this pass.

    line 273
  17. Distinctive:

    Prefer complete coverage over extensive prose.

    line 291
  18. Distinctive:

    every current authoritative decision/source handle has a row.

    line 370
  19. Distinctive:

    every row maps to a requirement, constraint, acceptance item, or explicit out-of-scope disposition.

    line 371
  20. Distinctive:

    every negative requirement and material exception remains visible.

    line 373
  21. Distinctive:

    no stale or superseded record is treated as current.

    line 374
  22. Distinctive:

    every acceptance statement passes the measurable-acceptance gate above.

    line 375
  23. Distinctive:

    every unsupported claim is marked as an assumption.

    line 376
  24. Distinctive:

    no requirement expands scope without an authoritative source.

    line 377
  25. Very specific:

    Use gap rather than pretending coverage when a decision was weakened, omitted, contradicted, or cannot be verified.

    line 379
  26. Distinctive:

    When the specification or LIGHT contract passes its coverage/readiness gate, To-Spec may return this traceable downstream packet without …

    line 385
  27. Distinctive:

    If the specification changes, invalidate the snapshot, coverage evidence, and any downstream draft graph.

    line 412
  28. Distinctive:

    Do not invoke To-Tickets automatically.

    line 414
  29. Distinctive:

    create a tracker issue or external document.

    line 430
  30. Distinctive:

    create implementation tickets or modify a FULL Wayfinder map.

    line 433
  31. Distinctive:

    start planning or implementation.

    line 434
  32. Distinctive:

    After producing the draft, report:

    line 436
  33. Distinctive:

    Conversation-only synthesis: Use authoritative source handles.

    line 470
  34. Distinctive:

    Execution signaling: Never apply an agent-ready label automatically.

    line 477
  35. Distinctive:

    FULL for every job: Prefer LIGHT when persistence and complete coverage would cost more than they save.

    line 485

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 execution

To-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 action

LIGHT 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 DRAFT specification 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_SPEC packet;
  • a settled conversation with identifiable decisions and evidence;
  • a wayfinder-to-spec-v1 packet 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:

  1. Require schema: grill-route-v1.
  2. Continue only for route: DIRECT_SPEC.
  3. Require destination, accepted decision handles or exact accepted values, constraints, negative requirements, evidence handles, suspected fog, out-of-scope boundaries, and persistence status.
  4. Treat suspected fog as empty or explicitly non-route-changing. Otherwise return BLOCKED and route to Wayfinder.
  5. Allow persistence: pending only 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:

  1. Require schema: wayfinder-to-spec-v1.
  2. Continue only for outcome: READY_FOR_SPEC.
  3. 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.
  4. Resolve each handle from its authoritative record; do not treat the packet gist as a replacement for ticket rationale.
  5. Return BLOCKED when 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 lookup

Do 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:

  1. current accepted Wayfinder or project decision records;
  2. the user's current explicit direction;
  3. applicable project instructions, policies, and requirements;
  4. verified repository state and source documentation;
  5. 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

  1. Inventory all current decision IDs or source handles.
  2. Preserve the exact force of each accepted value, including exceptions, constants, ordering, defaults, retry behavior, negative requirements, and rejected alternatives that constrain implementation.
  3. Assign spec-local requirement IDs such as REQ-001. These identify requirements only; they never replace or renumber authoritative decision IDs.
  4. Draft the specification using the template below.
  5. Map every current decision/source handle to its concrete coverage.
  6. Audit for omission, weakening, contradiction, unsupported expansion, stale references, and unverifiable acceptance language.
  7. Return BLOCKED if 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: none

Rules:

  • Emit it only after the selected To-Spec readiness and coverage gates pass.
  • decomposition_authority: granted requires the current user to explicitly accept this exact source snapshot for To-Tickets decomposition; otherwise use pending.
  • publication_authority is always none. 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-agent or 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, or granted) 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

  1. Re-interviewing. Route missing decisions to Bounded Grill or Wayfinder.
  2. Conversation-only synthesis. Use authoritative source handles.
  3. Summary weakening. Preserve exceptions, negatives, constants, and rationale pointers.
  4. Prose inflation. Optimize for complete coverage, not maximum length.
  5. Assumption laundering. Mark unsupported claims explicitly.
  6. Stale decisions. Preserve history but compile only current records.
  7. Premature publication. A draft is local/chat-only without approval.
  8. Execution signaling. Never apply an agent-ready label automatically.
  9. Ticketization leakage. A downstream handoff does not draft or publish tickets; decomposition and publication remain separately authorized.
  10. Task leakage. Requirements and acceptance evidence are not an implementation task list.
  11. Implementation drift. FULL stops after the draft unless the current request already authorized downstream work; LIGHT returns only to work already authorized.
  12. 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-only target.
  • Any FULL Grill input passed the grill-route-v1 contract.
  • Any FULL Wayfinder input passed the wayfinder-to-spec-v1 contract.
  • 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, or BLOCKED.
  • Any ticketization handoff conforms to to-spec-ticketization-v1, binds one exact source snapshot, and leaves publication authority none.
  • 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.