skills.rest
davidsunglee
davidsungleeCOMMUNITY
Explore all skills by this author →
GitHub

define-spec

Writes structured specs to docs/specs/ via interactive Q&A with subagent dispatch and commit gating.

Updated May 19, 2026
Search Tags:#spec writing#workflow orchestration#artifact validation#interactive q&a#commit gating#subagent dispatch#multiplexer detection
One-click install
npx skills add https://github.com/davidsunglee/pi-flow --skill define-spec-davidsunglee
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: define-spec
Source: https://github.com/davidsunglee/pi-flow/tree/main/packages/pi-flow-core/skills/define-spec
Command: npx skills add https://github.com/davidsunglee/pi-flow --skill define-spec-davidsunglee

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires @aphotic/pi-mux-subagents, and includes scripts (resource) components.

What problem does it solve? Turning a rough idea, an existing draft, or freeform text into a well-structured, reviewable specification requires codebase grounding, intent clarification, and disciplined scope control — this Skill automates that entire spec-writing workflow. ## Core Features & Use Cases - Three input shapes: Accepts an idea ID (IDEA-<hex>), an existing spec path under docs/specs/, or freeform text, and detects the shape automatically. - Mux or inline execution: Detects a terminal multiplexer (herdr, cmux, tmux, zellij, wezterm) and dispatches a spec-designer subagent in a pane, or runs the procedure inline when no mux is available. - Validated artifact handoff: Verifies the SPEC_ARTIFACT marker, file existence, path shape, and freshness, with transcript-backed recovery when the marker is missing. - Use Case: Run /define-spec IDEA-075cf515 to turn a captured idea into a committed spec under docs/specs/, then choose fastlane or deep workflow for implementation. ## Quick Start Ask the assistant to run /define-spec with an idea ID, an existing spec path, or a freeform description of the feature you want specified.

Frequently Asked Questions about define-spec

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write a spec from an idea using define-spec?▼

Run /define-spec with an idea ID like IDEA-075cf515. The skill reads docs/ideas/<id>.md, surveys the codebase, runs interactive Q&A, and writes a structured spec to docs/specs/ gated on your review before commit.

What input formats does the define-spec skill accept?▼

It accepts three shapes: an idea ID matching IDEA-<8 hex chars>, a path to an existing spec under docs/specs/ (relative or absolute), or freeform text. The shape is detected automatically by pattern without prompting.

Can I run spec design without a subagent or multiplexer?▼

Yes. Include an override phrase like --no-subagent or "no subagent" in your input, or set PI_SUBAGENT_MODE=headless. The skill then runs the full spec-design procedure inline in the current session.

Why does define-spec fail with a pi-mux-detect error?▼

The helper delegates multiplexer detection to pi-mux-detect from the @aphotic/pi-mux-subagents peer package. If that package is missing or broken, detection fails loudly rather than silently falling back to inline mode; install the peer dependency to fix it.

What happens if the spec-designer subagent does not emit SPEC_ARTIFACT?▼

The orchestrator first tries an on-disk fallback checking the expected path exists, is non-empty, and is fresher than the pre-dispatch baseline. If that fails, it attempts transcript-backed recovery for exactly one valid written spec path, otherwise it stops without committing.

Does define-spec commit the spec automatically?▼

No. After the spec is written, the skill pauses for user review with commit, refine, or stop options. Only an explicit commit choice invokes the commit skill for the spec file.

Related Skills

Explore More Software Engineering Skills→
MohamedSayedKMohamedSayedK

idea

Appends a dated raw idea bullet to a Markdown ideas backlog file.

Community
Basic
gelowzzzgelowzzz

implement-feature

Orchestrate parallel coder agents through feature spec waves with review gates.

Community
Advanced
brainfish-aibrainfish-ai

commit-doc

Review git status and diffs to generate structured commit messages.

Official
Intermediate
liminal-ailiminal-ai
1

ls-team-spec

Orchestrate the Liminal Spec pipeline with agent teams and external verification subagents.

Official
Advanced