Quickstart

Install specsmd v2, capture a first intent, and complete a first bolt

Follow these steps in a fresh project. When you finish, you will have a completed bolt under docs/specsmd/bolts/ with a walkthrough.

There is no v2 npm CLI. Install the specsmd plugin from a marketplace, or use the manual install path.

Prerequisites

• An AI coding tool that can load Agent Skills (Claude Code, Codex, or any tool that reads .agents/skills/)
• A project directory you can write to
• Node.js 18+ (the flow’s scripts are plain Node; they install nothing into your project)

1. Install the plugin

Pick the channel that matches your tool.

/plugin marketplace add /absolute/path/to/specs.md
/plugin install specsmd@specsmd

codex plugin marketplace add fabriqaai/specs.md --ref main-v2
codex plugin install specsmd

codex plugin marketplace add /absolute/path/to/specs.md
codex plugin install specsmd

mkdir -p .agents/skills
cp -R /path/to/specs.md/plugins/specsmd/skills/* .agents/skills/

Open the project in your coding tool and start a new session. The using-specsmd skill is the session bootstrap — it explains the flow and does not write files.

2. Initialize the artifact tree

Invoke the specsmd-init skill by name:

Use the specsmd-init skill.

The skill asks one question: the project’s autonomy bias.

If you are unsure, accept balanced (empty input).

The skill detects whether the workspace is empty or already has code, and whether it is a single project or a monorepo. In an existing codebase it may propose inferred standards — accept, edit, or skip them. That confirmation is not a second required question; initialization already completed after the bias.

You now have docs/specsmd/ with project.md and shipped recipe and standard files.

3. Capture a first intent

Invoke the intent-create skill. You can paste the following as the outcome you want. It is small on purpose so the first bolt can finish in one sitting.

Use the intent-create skill.

Title: Health signal

Problem: A caller cannot tell whether the service is ready to accept work.

Outcome: A caller can ask whether the service is ready and receive a clear yes or a clear no.

Scope: One readiness question and one readiness answer. A not-ready answer may include a short reason.

Non-goals: Authentication, metrics history, alerting, and changing other product behavior.

Confirm the brief when the skill summarizes it. The skill writes docs/specsmd/intents/{id}/brief.md through the flow’s scripts. Do not create that file by hand.

4. Decompose into work items

Invoke the work-item-decompose skill against that intent:

Use the work-item-decompose skill on the Health signal intent.

You want one vertical slice, complexity low (no new correctness or interoperability decisions beyond the stated yes/no). A typical item looks like this in spirit:

• Behavior: a caller who asks whether the service is ready receives yes or no.
• Definition of Done:
  • (gating) Asking whether the service is ready yields a yes or a no.
  • (gating) A no includes a short reason the caller can read.
  • (advisory) A yes does not include unrelated product data.

The skill records a suggested ceremony from complexity × your autonomy bias. For low × balanced that suggestion is autopilot. You can override it when you start the bolt.

5. Start a bolt

Invoke the bolt-start skill:

Use the bolt-start skill. Start a bolt for the health-signal work item.
Accept the recommended recipe and ceremony unless you want to change them.

If the skill offers draft bolts, choose ignore (this quickstart has none unless you already ran bolt-plan).

With a low item and balanced bias:

• Recommended recipe is simple (plan → implement → walkthrough)
• Recommended ceremony is autopilot (no approval stops)

Your explicit choice always wins. For this first bolt, accept the recommendations so you can reach completion without a gate.

The skill creates docs/specsmd/bolts/{id}/bolt.md. Note the bolt id it reports.

6. Execute through completion

Invoke the bolt-execute skill:

Use the bolt-execute skill on the bolt you just started. Run every remaining stage and complete the bolt.

What happens on simple + autopilot:

1. plan — writes plan.md and advances (no stop)
2. implement — implements the readiness behavior from the work item
3. walkthrough — writes walkthrough.md (what changed, why, deviations, how to verify — no source listings)
4. complete — the flow’s complete script records the bolt complete and cascades that status onto the work item and intent

If completion is refused, the refusal names the missing evidence or unmet gating criterion. Produce that, then ask bolt-execute to complete again. Do not edit status fields in frontmatter by hand.

7. Confirm you finished

Invoke the specsmd-status skill:

Use the specsmd-status skill.

You should see:

• Shaping — empty of this intent (it is no longer unbolted)
• Building — no active bolt for this work
• Shipping — the completed bolt listed

On disk, a completed first bolt looks like this:

docs/specsmd/
├── project.md
├── intents/
│   └── 001-health-signal/
│       ├── brief.md
│       └── work-items/
│           └── 001-readiness-answer.md
└── bolts/
    └── bolt-{worktree}-001/
        ├── bolt.md          # status: complete
        ├── plan.md
        └── walkthrough.md

That is a completed first bolt. You can start another intent, decompose further, or inspect the concepts.

If something stalls