plumbline-spec-engine

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# Specification engine

## Outcome and completion

Create or adopt one controlling product specification for the current task. A
specification is complete when it states the product outcome, users/workflows,
scope, non-goals, required behavior, constraints, acceptance/proof direction,
and remaining assumptions or residual questions clearly enough for planning.

## Adopt the strongest source

Assess sufficiency, not Plumbline conformance. Accept a user-supplied internal
or external design, handoff, attachment, or prior plan when it settles outcome,
users/workflows, scope, non-goals, behavior, constraints, and acceptance/proof.
Adopt it at the latest safe phase without replaying settled shaping.

When an artifact is sufficient for execution but lacks a separate specification
file, preserve the artifact. Do not require a separate file when the supplied
artifact is sufficient. Recommend a companion only when it materially
improves product clarity or recovery. Keep one controlling source for the task;
name competing candidates and ask the user to select one rather than silently
merging them.

Read `references/specification-template.md`,
`references/artifact-lifecycle.md`, and `references/product-autonomy.md` when
creating, adopting, or expanding a specification. Use the repository's
existing canonical/transient locations. For a blank repository, use
`docs/specs/<feature-slug>.md`.

## Adopt a shaping handoff

When an approved shaping handoff exists, promote it in place as the active
specification. Expand its compact headings into the existing specification
template instead of creating a competing file. Preserve decisions, research
findings and source links, open product questions, fog items, rejected
alternatives, and non-goals. Carry non-blocking fog into assumptions or
residual questions; leave it visible without blocking planning.

Materialize chat-only or attachment-only requirements before long-running work
when a durable record is needed. Preserve source and provenance, avoid
rewriting large or binary inputs wholesale, hash large inputs when appropriate,
and use a safe Markdown extraction when committing the original is unsafe.

## Resolve product questions only

Ask only blocking product questions, one at a time, with a recommendation. Technical
choices belong to the agent and should come from repository evidence, research,
conventions, and safe defaults. Record product amendments explicitly and keep
the approved source's intent intact.

When the controlling artifact is sufficient for the next phase, report the
adoption or companion recommendation once and direct the user to
`plumbline-plan` or `plumbline-execute`. Specification creates or adopts the
contract; it does not implement code.

From nickyfactz/plumbline, MIT.

More from nickyfactz/plumbline