Using VisionSpec Methodologies in Spec Kit¶

This guide walks through installing VisionSpec's One-Way-Door methodology — exported as native GitHub Spec Kit extensions, workflows, and bundles — into a real Spec Kit project, and using it to scope a real piece of work end to end.

Not the same as visionspec export speckit

GitHub SpecKit target covers VisionSpec's spec.md / plan.md / tasks.md exporter, which turns an already-reconciled VisionSpec project into files for Spec Kit to execute. This guide covers a different, newer mechanism: packaging a whole VisionSpec workflow methodology — templates, rubrics, review gates, and phase ordering — as installable Spec Kit plugins, for use in any Spec Kit project, VisionSpec-authored or not. The two are complementary; see See Also.

What you're installing¶

The aws-one-way-door workflow family — Amazon's Working Backwards, with one-way-door ceremony — exports as six components, generated by visionspec speckit export and committed under speckit/ in this repo:

Component	Kind	What it does
`one-way-door`	Extension	Writes press, faq, mrd (optional), prd, narrative-6p, uxd, with a PR/FAQ review gate and a mandatory decision-meeting gate
`one-way-door-engineering`	Extension	Writes trd, tpd, ird — the technical wing, installed alongside the product extension
`one-way-door-chain`	Workflow (generated)	Runs the full sequence end to end, unattended
`risk-adjusted`	Workflow (hand-authored)	Triages work first — bug, feature, or initiative — then routes into the right amount of ceremony
`product-management`	Bundle	`one-way-door` + `risk-adjusted`, for teams that stop at requirements
`product-builders`	Bundle	Adds `one-way-door-engineering`, for teams that carry through delivery

Prerequisites¶

Spec Kit installed.

uv tool install specify-cli
specify check

This repo cloned, with the plugin artifacts generated:

cd ~/go/src/github.com/ProductBuildersHQ/visionspec
go run ./cmd/visionspec speckit export aws-one-way-door -o speckit

A target project. This guide uses grokify/petstore — an existing Go API backend with an OpenAPI spec and no customer-facing website yet — as the test project, but any repo works.

Step 1 — Frame the work¶

Before installing anything, name what you're actually trying to decide. Petstore today is an API only. Adding a public storefront website is:

Reversible? The code is — you can always take a website down. But it's petstore's first customer-facing brand surface: a public commitment to a new channel, with pricing and positioning implications you haven't made yet.
Blast radius? Broad — it's public, not an internal tool.

That's a one-way door by the definition the methodology uses, even though nothing about it is technically hard to build. This is exactly the judgment call risk-adjusted is built to make explicit rather than skip.

Step 2 — Install the extensions¶

cd ~/go/src/github.com/grokify/petstore

specify init --here --force --integration claude \
  --extension ~/go/src/github.com/ProductBuildersHQ/visionspec/speckit/extensions/one-way-door \
  --extension ~/go/src/github.com/ProductBuildersHQ/visionspec/speckit/extensions/one-way-door-engineering

--here --force initializes Spec Kit in petstore's existing directory instead of scaffolding a new one — safe on a non-empty repo. specify init's --extension flag accepts a local path directly.

Verify:

ls .claude/skills/ | grep one-way-door

You should see one skill per command — speckit-one-way-door-press, speckit-one-way-door-faq, and so on — plus speckit-one-way-door-engineering-trd, -tpd, -ird.

That's everything the walkthrough below needs. The risk-adjusted and one-way-door-chain workflows are optional — they orchestrate this same chain for unattended or CI runs; see Automating with specify workflow run.

Step 3 — Start the chain¶

Open the project in your agent (Claude Code, here) and start at the founding artifact. You already made the door-test call in Step 1, so just say so:

/speckit-one-way-door-press Add a public-facing storefront website to Petstore, slug=storefront-website

The agent resolves the slug, writes .specify/initiatives/storefront-website/press.md, self-checks it against the rubric, and tells you what to run next. Keep going the same way, one command per turn — /speckit-one-way-door-faq slug=storefront-website, then -prd, -narrative-6p, -uxd.

This is the normal way to use the chain: a conversation with your agent, one command at a time. specify workflow run (see Automating) exists for a different situation — running the whole thing unattended, with nobody watching.

Step 4 — Work the chain¶

Each command reads its prerequisites, writes its document from the extension's template, and self-checks against the rubric before it reports done. Documents land under:

.specify/initiatives/storefront-website/
├── press.md
├── faq.md
├── prd.md
├── narrative-6p.md
└── uxd.md

Two stops are worth knowing before you hit them. Each is written directly into the command as an instruction the agent follows — not a separate CLI mechanism — so in conversation it simply pauses and asks:

PR/FAQ review, after faq — read the press release and FAQ together. Iterating here, possibly through several drafts, is the method working as intended, not a delay. Tell the agent to revise, or to continue.
Decision meeting, after narrative-6p — a hard stop. The command will not continue to uxd without your explicit approval, recorded in decision.md. This is deliberate: build spend on a one-way door should never happen automatically.

Step 5 — Hand off to engineering¶

After uxd, the product chain is done. If you installed one-way-door-engineering (Step 2), continue directly:

/speckit-one-way-door-engineering-trd slug=storefront-website

which carries through trd → tpd → ird, then hands off to /speckit.specify — read the PRD, UXD, and TRD, and pass their scope, requirements, and user stories as its description. /speckit.specify synthesizes spec-kit's own spec.md from that, which /speckit.plan then reads. If you skipped the engineering extension, uxd's own output already tells you to do the same with just the PRD and UXD.

Why hand off to /speckit.specify, not /speckit.plan?

/speckit.plan reads a FEATURE_SPEC that only /speckit.specify's create-new-feature script produces. Skipping straight to plan finds no current feature. Handing your PRD/UXD content to /speckit.specify as its description is a synthesis step, not wasted work — it mirrors how the legacy SpecKit target already treats spec.md as downstream of the PRD/TRD rather than hand-authored independently.

Installing for a whole team¶

Rather than picking extensions individually, install a role bundle:

specify bundle install ~/go/src/github.com/ProductBuildersHQ/visionspec/speckit/bundles/product-builders

Use product-management instead if the team stops at requirements (no one-way-door-engineering). See speckit/README.md for the full component list and catalog-based install (once published).

Automating with `specify workflow run`¶

Everything above also runs unattended — useful for CI, or a batch of initiatives with nobody watching. Install the workflow first (Step 2 skipped this, since the conversational path doesn't need it):

specify workflow add ~/go/src/github.com/ProductBuildersHQ/visionspec/speckit/workflows/risk-adjusted --dev

specify workflow run never prompts interactively for its inputs — the prompt: text in a workflow's inputs: schema is descriptive metadata only (shown by specify workflow info), not a live prompt. Every input the run needs must be supplied up front with -i name=value, or it fails immediately with Required input '...' not provided:

specify workflow run risk-adjusted \
  -i work="Add a public-facing storefront website to Petstore" \
  -i slug=storefront-website \
  -i work_type=unsure \
  -i reversibility=one-way \
  -i blast_radius=broad

Those last two answer the door test per Step 1, so the run routes to the initiative branch. Already certain it's a one-way door? -i work_type=initiative alone is enough — or skip risk-adjusted's triage entirely and run the straight-line chain:

specify workflow add ~/go/src/github.com/ProductBuildersHQ/visionspec/speckit/workflows/one-way-door-chain --dev
specify workflow run one-way-door-chain -i work="..." -i slug=storefront-website

one-way-door-chain is generated straight from the family's execution sequence and review gates — it has no triage logic of its own, so use it when the ceremony decision is already made.

Gates do prompt interactively here, at a real terminal — the run pauses for your approve/reject, same intent as the conversational STOP instructions. Running non-interactively (CI, a scripted agent) instead pauses the run rather than prompting:

specify workflow status                      # find the run_id
specify workflow resume <run_id> -i choice=approve

Prefer the conversational path if you're already in an agent session

Each command-type step in a workflow run dispatches to the target agent's own CLI non-interactively — e.g. claude -p /speckit-one-way-door-press ... — as a fresh, disposable subprocess. If you're already talking to an agent, workflow run spins up a second, separate instance to do the same job; Steps 3–5 are the more direct route. workflow run earns its keep in a script or CI job with nobody watching.

Troubleshooting¶

specify extension add rejects the path with "Got unexpected extra argument(s)." The extension path is a positional argument, and --dev is a flag with no value: specify extension add <path> --dev, not specify extension add --dev <path>.

uxd tells you to continue with a command that doesn't exist. You only installed one-way-door, not one-way-door-engineering. That's expected — the message is a conditional handoff, not a broken reference; install the engineering extension or continue at /speckit.specify instead.

/speckit.plan fails with "no current feature." You (or an agent) jumped straight from uxd/ird to /speckit.plan, skipping /speckit.specify. Run /speckit.specify first, passing the PRD/UXD content as its description — see Step 5.

Generated commands look stale after changing a VisionSpec template or rubric. Re-run the exporter and reinstall:

go run ./cmd/visionspec speckit export aws-one-way-door -o speckit
specify extension add one-way-door --dev --force

(specify workflow run only) Error: Required input 'work' not provided. Every required input needs an explicit -i name=value — see Automating. This never happens on the conversational path; there are no CLI-resolved "inputs" there, just what you type.

(specify workflow run only) A gate never prompts; the run just says paused. You're running non-interactively (no TTY — common in a scripted or CI context). Use specify workflow status to find the run_id, then specify workflow resume <run_id> -i choice=approve.