Turn agreed decisions into a specification

Watch

Skill Vault video planned · Video planned

Install

Public release v0.1.2 — install the latest source or pin the tested release.

Install latest

npx skills@latest add MattEspo23/skills --skill to-spec

Reproducible install

npx skills@latest add 'MattEspo23/skills#v0.1.2' --skill to-spec

Clean installs are verified for Codex and Claude Code. The installer copies editable files into the selected agent; review every Skill before giving it tool access.

This is the public, editable adapted baseline. Its deeper Espo-specific revision and Skill Vault video are planned; the released source can be installed now.

What it does

to-spec turns the conversation you have just had into a spec, and publishes it to your issue tracker as a single issue.

It does not interview you. By the time you reach for it the deciding is already done, so it synthesises what is known — from the thread, from the codebase, from your CONTEXT.md and ADRs — rather than opening a fresh round of questions. The spec is a record of decisions already made, not a place where new ones get made.

When to reach for it

You invoke this by typing /to-spec — the agent won't reach for it on its own.

Reach for it when the build is too big for one agent session and has to survive being split across several. That is the whole trigger:

Prerequisites

to-spec publishes the spec as an issue, so setup-espo-skills must have configured a tracker and the triage-label vocabulary for this repo first. Either kind works: a real tracker like GitHub, or local markdown files under .scratch/, which is supported out of the box.

The spec is a decision record

The spec exists because context windows end. Everything you settled while grilling — the shape of the solution, the choices you argued through, what you deliberately refused — is in one conversation that is about to be cleared. The spec is what survives that.

So it does not validate anything, and it does not decide anything. It captures what was decided, in your project's own vocabulary, so that a fresh session can pick the work up without you re-explaining it. Anything the spec asserts that you never actually said is a defect.

Seams before prose

Before it writes a word, to-spec sketches the seams the feature will be tested at, and checks them with you. It prefers seams that already exist to new ones, and takes the highest seam it can — the ideal number across a change is one.

Those agreed seams then travel. tdd works only at pre-agreed seams, and code-review reviews the diff against the spec, so a seam nobody agreed to shows up as a review finding. The binding is indirect — it runs through this document — which is exactly why the seam conversation is worth taking seriously here rather than deferring it to implementation.

Common questions

Where did /to-prd go? It is this skill, renamed in v1.1. "Spec" is now the single through-line term, and the old to-prd slug is dead — reinstall under the new name. The pair that replaced the old vocabulary is spec and tickets: the spec is the destination and the decisions that fix it, the tickets are the execution steps that get there. If you pivot, delete the unfinished tickets and keep the spec.

Why does the spec get the ready-for-agent label? I don't want an agent implementing off it. The label means "no further triage needed" — the document is complete enough for an agent to work from. It is an input designation, not a work order. But if you run AFK agents that poll for ready-for-agent, that distinction isn't visible to them, and they will happily try to build the whole spec in one run instead of picking up the ticket slices. This is the most-reported rough edge on the skill. Until it changes, exclude the parent spec explicitly in your AFK agent's prompt, or strip the label once /to-tickets has run.

Why not go straight from grilling to /to-tickets and skip the spec? Often you should — the spec earns its step only on multi-session work. Where it pays is that the tickets are disposable and the spec isn't: each ticket is sized for one fresh context window and gets deleted or closed, while the spec stays as the one place the reasoning behind them lives. On a single-session change that buys you nothing, and you have paid an extra synthesis step where the model can drift. Go grilling → /implement.

I just finished a wayfinder map. What do I feed it? The main map issue — /to-spec #<map_issue>, not the individual decision tickets. wayfinder produces decisions rather than deliverables, scattered across a map; to-spec is the step that collapses them into one buildable document. Looping the map straight into /implement throws that collapse away.

Is the spec for me to review, or is it just for the agent? Mostly for the agent, and it reads that way — complete, dense, reference-heavy. The parts worth your eyes are the seams and the out-of-scope section, because those are the two places a wrong decision is cheapest to catch and most expensive to discover later. Reading the whole thing end to end is a real complaint people have, and there is no summary mode: the honest answer is that if the spec surprises you, the grilling was too shallow, not the spec too long.

Do I keep the spec frozen once tickets start, or let the agent rewrite it? Nothing keeps it in sync, so in practice it is a snapshot of what you knew at that moment, and it goes stale the first time implementation teaches you something. Treat it as throwaway once the work ships. The artifacts meant to outlive it are your CONTEXT.md and your ADRs — if something learned during implementation deserves to last, it belongs there, not in an edited spec.

My work is a refactor or a module boundary, not a feature. Does the template fit? Less well, and this is a known limitation. The template leans hard on user stories, which is the wrong shape for architectural work — you end up writing stories nobody asked for around decisions that are really about interfaces and invariants. Lean on the implementation-decisions and testing-decisions sections instead, and let the durable architectural calls land as ADRs via grill-with-docs rather than trying to make the spec carry them.

Will it check the tracker for related work, or cite the ADRs it's respecting? No to both. It reads and respects the ADRs covering the area it touches, but it doesn't link them, and it doesn't search the tracker for overlapping issues before drafting — so a spec can quietly duplicate work someone already filed. Search the tracker yourself first if the area is busy.

/to-tickets couldn't read my spec — it kept truncating. Very large specs can outgrow what a tracker issue will serve back cleanly, and there is no local copy to fall back on. The fix is context hygiene: don't clear or compact between /to-spec and /to-tickets. Run them in the same window and the spec never has to be re-fetched at all.

It's working if

• It starts writing rather than asking you a fresh round of questions.
• It puts the seams to you before it writes, and proposes as few as it can get away with.
• It comes back in your project's nouns, not generic product-management boilerplate.
• Every decision in it is one you can remember making. Nothing was invented to fill a section.
• The out-of-scope section has real things in it — the things you refused are usually the most useful lines on the page.

Where it fits

to-spec is a step in the main build chain, and only on the multi-session branch of it:

grill-with-docs → to-spec → to-tickets → implement → code-review

Its neighbours upstream are grill-with-docs, which does the deciding this skill only records, and wayfinder, whose finished map merges onto the chain right here. Downstream, to-tickets cuts the spec into tracer-bullet tickets for implement to build. When you're unsure which skill or flow fits, ask-espo routes you.

Try it once

Use the core behavior in one conversation before installation. The repeatable Skill package is the primary path when you want the behavior available across future work.

Turn the decisions already settled in this conversation into a spec. Do not interview me again. Identify the behavioral seams, acceptance evidence, non-goals, and unresolved risks.

Source & license

Released in EspoAI Skills v0.1.2; adapted from mattpocock/skills v1.2.3. The released package is skills/engineering/to-spec/SKILL.md.

The public package is MIT-licensed and pinned here to the exact release commit. View the released EspoAI source

The adapted baseline preserves the upstream copyright, MIT permission notice, and pinned provenance. View the original pinned source

Skill package files

The full Skill text as copied from content/skill-vault/skills/to-spec/. Supporting agent configuration files stay in that folder.

SKILL.md

---
name: to-spec
description: Turn the current conversation into a spec and publish it to the project issue tracker — no interview, just synthesis of what you've already discussed.
---

This skill takes the current conversation context and codebase understanding and produces a spec. Do NOT interview the user — just synthesize what you already know.

The issue tracker and triage label vocabulary should have been provided to you — run `/setup-espo-skills` if not.

## Process

1. Explore the repo to understand the current state of the codebase, if you haven't already. Use the project's domain glossary vocabulary throughout the spec, and respect any ADRs in the area you're touching.

2. Sketch out the seams at which you're going to test the feature. Existing seams should be preferred to new ones. Use the highest seam possible. If new seams are needed, propose them at the highest point you can. The fewer seams across the codebase, the better - the ideal number is one.

Check with the user that these seams match their expectations.

3. Write the spec using the template below, then publish it to the project issue tracker. Apply the `ready-for-agent` triage label - no need for additional triage.

<spec-template>

## Problem Statement

The problem that the user is facing, from the user's perspective.

## Solution

The solution to the problem, from the user's perspective.

## User Stories

A LONG, numbered list of user stories. Each user story should be in the format of:

1. As an <actor>, I want a <feature>, so that <benefit>

<user-story-example>
1. As a mobile bank customer, I want to see balance on my accounts, so that I can make better informed decisions about my spending
</user-story-example>

This list of user stories should be extremely extensive and cover all aspects of the feature.

## Implementation Decisions

A list of implementation decisions that were made. This can include:

- The modules that will be built/modified
- The interfaces of those modules that will be modified
- Technical clarifications from the developer
- Architectural decisions
- Schema changes
- API contracts
- Specific interactions

Do NOT include specific file paths or code snippets. They may end up being outdated very quickly.

Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it within the relevant decision and note briefly that it came from a prototype. Trim to the decision-rich parts — not a working demo, just the important bits.

## Testing Decisions

A list of testing decisions that were made. Include:

- A description of what makes a good test (only test external behavior, not implementation details)
- Which modules will be tested
- Prior art for the tests (i.e. similar types of tests in the codebase)

## Out of Scope

A description of the things that are out of scope for this spec.

## Further Notes

Any further notes about the feature.

</spec-template>