Feature Spec

Feature Spec

Creates a complete product feature specification with acceptance criteria, scope, dependencies, and risks. Delegates to the Prometeo (PM) agent

Category: productivity Source: davepoon/buildwithclaude

What Is Feature Spec?

Feature Spec is an advanced Claude Code skill designed to automate and standardize the process of creating detailed product feature specifications. By leveraging the Prometeo (PM) agent, Feature Spec orchestrates the generation of comprehensive documentation for new features or product requirements, including acceptance criteria, scope, dependencies, and risk assessment. This skill is particularly valuable during project planning, serving as a workflow orchestrator that ensures every aspect of a feature is well-defined and ready for implementation by development teams.

Feature Spec integrates seamlessly into automated workflows, reducing manual effort and minimizing the risk of overlooked requirements or ambiguous specifications. The output is a consistent, structured markdown document placed at docs/specs/{feature-name}.md, ready for handoff to engineering or other stakeholders.

Why Use Feature Spec?

Defining clear, unambiguous feature specifications is a critical part of successful software delivery. Inconsistent or incomplete specs can lead to delays, miscommunication, and costly rework. Feature Spec addresses these challenges by standardizing the specification process and embedding best practices into each step. Key reasons for adopting Feature Spec include:

  • Consistency: Every specification follows a proven structure, reducing variability and increasing quality.
  • Efficiency: Automated checklists and delegated research streamline the documentation process.
  • Accountability: Explicit acceptance criteria and risk identification ensure all parties understand the requirements.
  • Traceability: Each spec is stored systematically, making it easy to review changes and maintain project history.
  • Seamless Handoff: Structured handoff notes facilitate smooth transitions from planning to development.

By using Feature Spec, teams can focus more on innovation and less on administrative overhead, while ensuring that all necessary details are captured upfront.

How to Get Started

Getting started with Feature Spec is straightforward. The skill is invoked as a command, typically from within a Claude Code or compatible chatbot environment. It accepts a concise feature description and handles the rest, orchestrating the process via the Prometeo (PM) agent.

Basic Usage

To create a feature spec for user authentication using JWT tokens, use:

/feature-spec user authentication with JWT tokens

Detailed Usage

For a more complex feature such as a multi-tenant billing system with Stripe integration, the command would be:

/feature-spec multi-tenant billing system with Stripe integration

Upon invocation, the skill will:

  1. Run a SIGN IN checklist (identity, task, memory review) to ensure proper context.
  2. Research existing specs to check for conflicts or overlaps.
  3. Create a comprehensive specification file at the appropriate location.
  4. Execute a Spec Completion (TIME OUT) checklist to verify completeness.
  5. Prepare handoff notes for the Dev agent.
  6. Run a SIGN OUT checklist to update memory and finalize deliverables.

Key Features

Feature Spec incorporates several robust features to support effective product planning and documentation:

  • End-to-End Workflow Orchestration: Automates the entire specification lifecycle, from initial context gathering to final handoff.
  • Acceptance Criteria Generation: Translates requirements into clear, testable user stories using the GIVEN/WHEN/THEN format.
  • Scope Definition: Delineates what is in-scope and out-of-scope, minimizing ambiguity.
  • Dependency Mapping: Identifies upstream and downstream dependencies, ensuring all prerequisites are documented.
  • Risk and Open Questions Analysis: Highlights potential risks and outstanding questions, enabling proactive mitigation.
  • Integration with Prometeo (PM) Agent: Delegates research and documentation tasks to a specialized project management agent for higher accuracy.
  • Structured Markdown Output: Specifications are output as well-organized markdown files, suitable for inclusion in code repositories or documentation portals.

Example Output Structure

A typical output at docs/specs/webhook-event-system.md might look like:

## Webhook Event System Spec

## Problem Statement
Enable real-time notifications via webhooks for external integrations.

## Success Metrics
- 95% delivery rate for webhook events
- Average delivery time < 2 seconds

## User Stories
### Story 1: Event Trigger
**GIVEN** a subscribed event  
**WHEN** the event occurs  
**THEN** a webhook should be sent to the configured endpoint

## Scope
- In-Scope: Event registration, delivery retries, monitoring dashboard
- Out-of-Scope: Third-party webhook authentication

## Dependencies
- Requires event bus integration
- Depends on external endpoint availability

## Risks
- Potential for webhook abuse (DoS)
- Handling of failed deliveries

## Open Questions
- How to authenticate webhook endpoints?
- Maximum retries before dropping events

## Dev Handoff Notes
Refer to `docs/specs/webhook-event-system.md` for implementation details.

Best Practices

To maximize the value of Feature Spec, consider the following best practices:

  • Be Specific: Clearly articulate the feature’s purpose and scope in your command. Vague prompts yield less useful specs.
  • Iterate: Review and refine generated specs as requirements evolve.
  • Collaborate: Share the spec with stakeholders for feedback before handoff.
  • Update: Re-run Feature Spec if significant changes occur to ensure documentation remains current.
  • Integrate: Include the output in your codebase or documentation repository for easy access by all teams.

Important Notes

  • Feature Spec relies on the Prometeo (PM) agent for research and content generation—ensure this agent is set up and accessible.
  • The skill is most effective when used at the outset of feature planning, before development begins.
  • Generated specs are stored in markdown format under docs/specs/, so ensure your repository has this structure.
  • While the skill automates much of the process, human review is recommended to validate business logic and technical assumptions.
  • Use clear, unambiguous language in prompts to avoid misinterpretation.
  • Remember to address all open questions and risks before finalizing the specification for development handoff.