specify

Convert approved briefs into testable acceptance scenarios in spec.md files.

Updated Feb 26, 2026
One-click install
npx skills add https://github.com/bernajaber/pi-product-system --skill specify-bernajaber
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: specify
Source: https://github.com/bernajaber/pi-product-system/tree/main/skills/specify
Command: npx skills add https://github.com/bernajaber/pi-product-system --skill specify-bernajaber

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Converts an approved Gate 1 brief into a precise, internal specification of acceptance scenarios so downstream agents (plan, build, test) have clear, testable requirements and do not rely on assumptions.

Core Features & Use Cases

  • Transforms brief capabilities into 1-3 user-focused acceptance scenarios per capability, including empty state, error/edge cases, and boundary conditions.
  • Enforces product constitution rules and workflow transitions by updating workflow-state.json to advance the project to the planning phase.
  • Use case: After discovery approves a brief for a new feature, run this Skill to produce spec.md that the build and test pipelines use to generate tasks and automated checks.

Quick Start

Convert the approved brief at .pi/specs/<feature>/brief.md into .pi/specs/<feature>/spec.md containing clear, independently testable acceptance scenarios and update the workflow state to proceed to planning.

Frequently Asked Questions about specify

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

FAQPage Schema
How do I convert a product brief into testable acceptance scenarios?

To convert a product brief into testable acceptance scenarios, you apply this Skill to an approved brief.md file, generating a spec.md document with structured, independently testable user-behavior scenarios.

What is the best way to structure acceptance scenarios for automated testing?

The best way to structure acceptance scenarios for automated testing is to define user-focused behaviors that include empty states, error cases, and boundary conditions, ensuring each scenario is independently testable.

How do I manage workflow state transitions after approving a feature brief?

You manage workflow state transitions by updating the workflow-state.json file, setting the currentPhase to plan after generating the internal specification from the approved brief.

When do I need to generate acceptance scenarios from a brief?

You need to generate acceptance scenarios from a brief after discovery approves it for a new feature, ensuring downstream build and test pipelines have clear requirements rather than relying on assumptions.

Does this specification process require an approved brief before running?

Yes, this specification process requires a Gate 1 approved brief located at .pi/specs/<feature>/brief.md to correctly produce the internal spec.md file for downstream planning.

What edge cases should be included in feature acceptance scenarios?

Acceptance scenarios should include empty state, error cases, and boundary conditions alongside the primary user-focused behaviors to ensure comprehensive test coverage for the feature.