Spec

Spec

Shape an idea, vague ticket, or open product question into a lightweight product spec. This is the product/requirements gate, not the implementation-design gate.

Use this for:

• Open-ended brainstorming
• Vague tickets that are not ready for implementation design
• Product behavior, scope, and acceptance criteria discovery
• Writing a lightweight spec/PRD before blueprint

Do not use this for:

• Implementation design when the requirement is already clear — use blueprint
• Breaking an approved spec into implementation phases — use break-spec
• Writing code or scaffolding

Do NOT design implementation details, invoke implement, write code, or scaffold until the product behavior and scope are approved or the user explicitly routes to blueprint.

If the repo declares custom lifecycle hooks, read ../lifecycle-hooks.md and honor any phase-boundary hooks before and after spec.

You may skip steps if the current conversation or kickoff already supplied enough context.

Step 1: Load context

Collect any supplied context:

• User idea or prompt
• Ticket title/body/comments
• Codebase findings from kickoff, if provided
• Existing plans/specs in plans/
• Relevant docs or recent commits, plus the matching spec_approved latest pointer entry when the ticket uses custom artifact locations

If working inside a repo, do light codebase exploration before asking detailed questions. Search for existing patterns, data models, API boundaries, and test coverage that affect the product decision. Record facts, not opinions.

Optional visual routing: only when repo-level beislid:visual_surfaces config exists and the effective spec mode is active, load the per-skill auxiliary visual-surface-protocol.md before the Step 5 approval/revision surface. It mirrors canonical .beislid/visual-surface-protocol.md so copied skill installs stay readable. When active, lean toward proposing a supplemental Lavish surface for any non-trivial spec whose requirements, options, flows, data/state models, scope boundaries, acceptance outcomes, or decisions can be communicated visually; do not reserve visual routing for UI changes. Use its BEISLID_VISUAL_PROMPT_V1 envelope for supplemental Lavish HTML review; keep Markdown/chat spec text canonical, treat freeform visual annotations as advisory, and accept only typed workflow-gate responses that validate/normalize to approve or revise. Unknown, malformed, or freeform-only visual feedback falls back to manual Markdown/chat review.

Step 2: Identify unknowns

Write down 5–10 targeted questions about what you do not know. Frame them as questions, not statements. Focus on:

• The problem and who feels it
• Desired behavior
• Success criteria
• Scope boundaries
• Constraints and risks
• Product decisions that block implementation design

Step 3: Interview the user

Ask questions one at a time. Prefer multiple choice when possible. If a question can be answered by the codebase or supplied ticket context, answer it from evidence instead of asking.

For each unresolved question, present:

• What the codebase/ticket suggests
• Your recommended answer
• What decision remains for the user

Step 4: Propose product directions

When there are multiple plausible interpretations or solutions, propose 2–3 product directions with trade-offs and your recommendation. Keep this at the product behavior level. Do not choose file-level implementation details here.

If the requirement is already obvious and only minor details were clarified, this can be a short paragraph.

Step 5: Present the spec for approval

Before writing an artifact, present the proposed spec in concise sections, keep the blocking question out of the draft, and ask for approval or corrections only once in the final response:

• Problem statement
• Current state
• Desired state
• User stories / acceptance outcomes
• Key decisions
• Out of scope
• Work Contract fields when downstream automation needs a stable handoff

Do not proceed until the user approves the product direction.

Optional Lavish review loop: if Step 1 found active beislid:visual_surfaces routing for spec, apply visual-surface-protocol.md here. Default to proposing the surface for visually-communicable specs; skip only when the spec is trivial, purely linear prose, or the effective mode/fallback rules prohibit routing. Respect the effective mode exactly: suggest only mentions the option; prompt asks before generating/opening and falls back to Markdown/chat if declined or unattended without permission; auto may generate/open only within action-policy boundaries and must announce the HTML path before waiting for feedback. The generated surface is supplemental and should use the protocol's review_spec prompt, plan/comparison layout guidance, and approve/revise typed gate controls. Normalize typed feedback with the protocol contract or beislid visual-feedback normalize semantics; manual_review, unknown action/decision, malformed payload, freeform-only feedback, or parser-unavailable hosts continue through Markdown/chat. Copy accepted visual revisions into the Markdown spec, visibly record accepted visual approvals in the canonical Markdown/chat spec, then ask for or record explicit approval of the canonical Markdown/chat spec; never let a visual control bypass this approval gate.

Step 6: Finalize the approved spec

Use this template for the approved spec text. Do NOT include exact file paths or code snippets unless the user explicitly wants an implementation-adjacent note; those belong in blueprint.

[Feature Name]

Problem Statement

What's broken or missing. Who it affects.

Current State

How things work today. What patterns exist.

Desired State

What the world looks like after this is released.

User Stories

• As a [role], I want [thing] so that [outcome]

Key Decisions

Decisions already resolved during the interview, with rationale.

Out of Scope

What this spec explicitly does not cover.

The approved spec text is the source for any artifact. Use the Spec artifact shape from artifact-templates.md when writing or summarizing it. Do not add implementation details while writing an artifact.

When the next workflow needs stable requirements, finalize a work-contract-v1 section in or alongside the spec.

Required structure:

• Headings: Kind, Status, Source, Problem, Desired Outcome, Constraints, Acceptance Outcomes, Unknowns / Human Decisions, Risk Classification, Extension Slots, and Ownership Boundary.
• Extension Slots YAML keys: scope_classification, proof_requirements, slice_plan, and children.

Population rules:

• scope_classification must include kind, confidence, rationale, recommended_route, requires_human_approval, requires_split, and split_reason.
• Valid kinds are atomic, single_pr, multi_slice, project, and draft-only unknown; valid confidence values are low, medium, and high.
• Use atomic only for bounded, clear, low-branching work; use single_pr for one coherent PR; use multi_slice for multiple independently shippable slices; use project when milestones/contracts/ownership boundaries are needed before execution.
• unknown is allowed only for draft or needs-human-decision contracts and routes to spec_refinement with requires_human_approval: true.
• Show the classifier before using it to route downstream work. requires_human_approval: true means an extra approval boundary beyond normal spec/blueprint approval.
• Require extra approval when classification triggers decomposition, fanout, project planning, contradicts the user's route, or has low-confidence, high-consequence impact. When true, stop, present the classifier and proposed route, wait for explicit approval, record approved/declined, and do not invoke downstream automation until approved. Prefer refinement questions that reduce approval burden over under-classifying.
• proof_requirements uses proof-requirement-v1; use [] only when no proof has been identified.
• slice_plan: null and children: [] are reserved for #58.
• Broad/project work should not jump directly to scaffolding by default.
• Missing product decisions belong under Unknowns / Human Decisions; do not invent them to unblock blueprint.
• Work Contracts are Beislið planning semantics, not Rondo execution/proof/run state or Memento curated memory.

Examples: typo-level doc fix with no branching → atomic; one coherent skill behavior update → single_pr; multiple shippable workflow slices → multi_slice; broad new-product or cross-system initiative needing milestones/boundaries → project.

Step 7: Run spec_approved lifecycle actions

If inside a git repo with .beislid/workflow.md, read only the beislid:lifecycle_actions block and execute supported events.spec_approved.actions[] entries in order. If no workflow exists, preserve standalone usefulness by offering a local write to plans/-spec.md after explicit approval. If a workflow exists but no spec_approved action is configured, do not ask for ad-hoc tracker/local destinations; workflow config controls lifecycle actions.

Supported P0 action shapes:

- name: write-spec-artifact
  type: artifact
  approval: prompt # optional; prompt when omitted, auto creates missing target
  on_failure: prompt # optional; prompt when omitted, or continue | abort
  path: 'plans/{feature}-spec.md' # optional default
- name: post-spec-body-to-tracker
  type: tracker
  approval: prompt # posts approved spec body through ticket_update.issue_tool / issue_command
  on_failure: prompt # optional; prompt when omitted, or continue | abort
- name: run-approved-spec-hook
  type: cli
  command: 'planning-hook {event} {ticket_id} {artifact_path}'
  approval: prompt # required for cli
  classes: [git-remote] # optional action-policy classes
  on_failure: prompt # optional; prompt when omitted, or continue | abort

Execute type: artifact, type: tracker, and type: cli under spec_approved; skip other providers as reserved. Multiple actions are allowed and run in order. Before each supported action, evaluate action policy: artifact actions use action id lifecycle.spec_approved. with class workspace-write; tracker actions use ticket.update; CLI actions use lifecycle.spec_approved. with configured classes or the conservative default [workspace-write, git-remote]. A policy denial records denied and skips that action; a policy ask boundary must be handled before running.

For artifact actions, approval: prompt asks write/skip and shows action name, resolved path, and parent directory creation. approval: auto writes automatically only when the target does not exist. Existing targets always prompt: overwrite / choose another path / skip. Default path: plans/{feature}-spec.md. Supported artifact placeholders are {feature}, {kind} (spec), and {ticket_id} when ticket context is known. Derive {feature} from the approved spec title, then ticket title, then branch name; ask for a filename stem if none is available. Slug values by lowercasing, replacing non-alphanumeric runs with -, collapsing repeats, stripping edge -, and keeping names readable (about 60 chars). If {ticket_id} is used without ticket context, ask for another path or skip. Paths must be relative, stay inside the repo root (or cwd for standalone fallback), contain no .., and end in .md. Create parent directories only as part of an approved or auto write.

Artifact content must be the approved spec as primary content. It may add a clearly labeled ## Artifact Context section with known source event, ticket, branch, and related lifecycle status. Do not alter approved decisions. Treat written spec artifacts as checkpoint-compatible state seeds for fresh-context handoff into break-spec or blueprint. After the artifact is written, update .beislid/checkpoints/latest.json with a latest.spec_approved entry containing event, path, ticket, branch, source_skill, and written_at when available; pointer write failures are non-blocking and should be reported.

For tracker actions, approval: prompt asks post/skip and shows action name plus tracker target. approval: auto posts once configured after policy allows it. Tracker actions must use the approved spec body, including the canonical ## Validation/Test Plan section, as the tracker update body through the configured ticket_update issue channel. Treat tracker posts as same-session lifecycle results, not local checkpoint artifacts.

For CLI actions, approval is required. approval: prompt asks run/skip and shows action name, command summary, placeholders used, and action-policy classes. approval: auto runs once configured after policy allows it. Supported CLI placeholders are {ticket_id}, {id} (alias), {branch}, {event} (spec_approved), {feature}, {kind} (spec), and {artifact_path} (latest written/auto-written artifact path for this event, or empty). Pass placeholder values through argv construction when available or shell-quote them before execution; never splice raw branch/ticket text into a shell and never expose the approved spec body as a command-line placeholder.

on_failure may be prompt, continue, or abort; omitted means prompt. On failed actions, prompt asks retry / skip or explicitly override / abort, continue warns and routes onward without that side effect, and abort stops downstream routing.

Record lifecycle results as written, auto-written, posted, ran, skipped, denied, reserved, not configured, or failed, with paths/action names/tracker targets when available.

Step 8: Output and route

Print the approved spec summary, lifecycle status/path list, and routing recommendation.

Then route by scope_classification when present:

• atomic or single_pr: hand off to blueprint with the approved spec/Work Contract and any lifecycle artifact path written in this session.
• multi_slice: hand off to break-spec with the approved spec/Work Contract and any lifecycle artifact path written in this session.
• project: recommend spec_refinement until project boundaries are approved, then hand off to break-spec/slice planning; do not scaffold by default.
• unknown: keep refining; do not hand off to automation as approved.
• If invoked by kickoff, return the approved spec or Work Contract, lifecycle status/path, and routing recommendation to kickoff.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: sandsower
• Source: sandsower/beislid
• License: MIT

Install and usage instructions live in the source repository linked above.