This skill should be used when the user asks to "write a spec", "create a functional specification", "define feature specs", "document user flows", "define business rules", "design data models", "define API contracts", or needs to transform requirements into detailed feature specifications with user flows, business rules, edge cases, data models, and API contracts.
From pm-architect-greenfieldnpx claudepluginhub nbkm8y5/claude-plugins --plugin pm-architect-greenfieldThis skill uses the workspace's default tool permissions.
Provides UI/UX resources: 50+ styles, color palettes, font pairings, guidelines, charts for web/mobile across React, Next.js, Vue, Svelte, Tailwind, React Native, Flutter. Aids planning, building, reviewing interfaces.
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
Builds 3-5 year financial models for startups with cohort revenue projections, cost structures, cash flow, headcount plans, burn rate, runway, and scenario analysis.
Transform a REQUIREMENTS.md artifact into a comprehensive FUNCTIONAL_SPEC.md artifact containing detailed feature specifications, user flows, business rules, edge cases, data models, and API contracts. This is the third step in the greenfield specification pipeline — it takes prioritized requirements and produces implementation-ready specifications.
[Raw Idea] → [PROBLEM_BRIEF.md] → [REQUIREMENTS.md] → **SPECIFICATION WRITING** → [FUNCTIONAL_SPEC.md] → Architecture → ...
Input: artifacts/greenfield/<project_name>/REQUIREMENTS.md
Output: artifacts/greenfield/<project_name>/FUNCTIONAL_SPEC.md
Load the REQUIREMENTS.md and extract:
Map requirements to feature specifications: typically one FS per REQ, but related REQs may be combined into a single feature spec if they share the same user flow.
Create feature specifications (FS-NNNN) by grouping related requirements:
Grouping rules:
Feature spec structure:
FS-NNNN: [Feature Name]
Requirements: REQ-NNNN, REQ-NNNN
Priority: [Inherited from highest-priority mapped REQ]
For each feature spec, create at least one user flow using Mermaid diagrams:
User flow types:
Mermaid format:
flowchart TD
A[User Action] --> B{Decision Point}
B -->|Yes| C[Success State]
B -->|No| D[Error State]
C --> E[Next Step]
D --> F[Recovery Action]
Rules for user flows:
For each feature spec, identify and document business rules:
Business rule format:
BR-NNNN: [Business Rule Title]
Feature: FS-NNNN
Rule: [Precise, unambiguous statement of the rule]
Source: [REQ-NNNN or domain knowledge]
Validation: [How to verify the rule is enforced]
Example:
- Valid: [Example of rule being satisfied]
- Invalid: [Example of rule being violated]
Rules for business rules:
For each feature spec, identify edge cases that require special handling:
Edge case format:
EC-NNNN: [Edge Case Title]
Feature: FS-NNNN
Scenario: [Description of the unusual but valid scenario]
Expected Behavior: [What the system should do]
Related Business Rules: BR-NNNN
Common edge case categories:
Create data model definitions for each feature spec that involves data persistence:
Data model format:
Entity: [Entity Name]
Feature: FS-NNNN
Description: [What this entity represents]
| Field | Type | Required | Constraints | Description |
|-------|------|----------|-------------|-------------|
| id | UUID | Yes | Primary key | Unique identifier |
| name | string | Yes | Max 255 chars | Display name |
| status | enum | Yes | [active, inactive, deleted] | Current state |
| created_at | datetime | Yes | Immutable | Creation timestamp |
| updated_at | datetime | Yes | Auto-updated | Last modification |
Relationships:
- [Entity Name] has many [Related Entity]
- [Entity Name] belongs to [Parent Entity]
Indexes:
- [field_name] — [purpose, e.g., "lookup by status"]
- [field_a, field_b] — [purpose, e.g., "unique constraint on name per parent"]
Rules for data models:
id fieldcreated_at and updated_at fieldsFor features that expose or consume APIs, define contracts:
API contract format:
API-NNNN: [Endpoint Name]
Feature: FS-NNNN
Method: GET | POST | PUT | PATCH | DELETE
Path: /api/v1/[resource]
Authentication: Required | Optional | None
Authorization: [Role or permission required]
Request:
Headers:
- Content-Type: application/json
- Authorization: Bearer {token}
Path Parameters:
- id (string, required): [description]
Query Parameters:
- page (integer, optional, default=1): [description]
- limit (integer, optional, default=20, max=100): [description]
Body:
```json
{
"field_name": "type — description",
"field_name": "type — description"
}
```
Response:
Success (200):
```json
{
"data": { ... },
"meta": { "page": 1, "limit": 20, "total": 100 }
}
```
Error (400):
```json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Human-readable message",
"details": [{ "field": "name", "issue": "required" }]
}
}
```
Error (404):
```json
{
"error": {
"code": "NOT_FOUND",
"message": "Resource not found"
}
}
```
Rate Limiting: [requests per minute/hour]
Idempotency: [Yes/No — if Yes, specify idempotency key]
Rules for API contracts:
Write the artifact following the template at ${CLAUDE_PLUGIN_ROOT}/reference/templates/FUNCTIONAL_SPEC.template.md.
The artifact must follow the standard artifact template structure:
# FUNCTIONAL_SPEC: [Project Name]
## Summary
[2-3 sentence summary: number of feature specs, coverage of requirements, key design decisions]
## Inputs
- **Requirements**: `REQUIREMENTS.md` — [REQ count, priority breakdown]
- **Problem Brief**: `PROBLEM_BRIEF.md` — [referenced for constraints and non-goals]
## Outputs
- This document (FUNCTIONAL_SPEC.md)
- Feeds into: ARCHITECTURE.md (via architecture skill)
- Feeds into: TASKS.md (via task-breakdown skill)
## Assumptions
- [ASM-0001]: [Assumption text — inherited or new]
- ...
## Open Questions
- [OQ-0001]: [Question that affects feature design]
- ...
## Main Content
### Feature Specifications Overview
| ID | Feature Name | Requirements | Priority | User Flows | Business Rules | Edge Cases |
|----|-------------|-------------|----------|------------|----------------|------------|
| FS-0001 | [Name] | REQ-0001, REQ-0002 | P0 | 2 | 3 | 4 |
| FS-0002 | [Name] | REQ-0003 | P1 | 1 | 2 | 2 |
| ... | ... | ... | ... | ... | ... | ... |
---
### FS-0001: [Feature Name]
**Requirements**: REQ-0001, REQ-0002
**Priority**: P0
**Description**: [Detailed description of what this feature does and why]
#### User Flows
##### Happy Path: [Flow Name]
```mermaid
flowchart TD
A[User starts action] --> B{Validation passes?}
B -->|Yes| C[Process request]
C --> D[Return success]
B -->|No| E[Show validation errors]
E --> A
Steps:
flowchart TD
A[User action] --> B{System available?}
B -->|No| C[Show error message]
C --> D[Offer retry]
B -->|Yes| E[Continue flow]
BR-0001: [Business Rule Title]
BR-0002: [Business Rule Title]
EC-0001: [Edge Case Title]
EC-0002: [Edge Case Title]
Entity: [Entity Name]
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
| id | UUID | Yes | Primary key | Unique identifier |
| ... | ... | ... | ... | ... |
Relationships:
Indexes:
API-0001: [Endpoint Name]
Request:
{
"field": "type — description"
}
Response (201):
{
"data": { "id": "uuid", "field": "value" }
}
Error (400):
{
"error": { "code": "VALIDATION_ERROR", "message": "Details" }
}
[... same structure as FS-0001 ...]
[How errors are handled across all features — error codes, user messages, logging]
[Shared auth model referenced by all API contracts]
[Shared validation patterns used across features]
**Output path**: `artifacts/greenfield/<project_name>/FUNCTIONAL_SPEC.md`
## Determinism Rules
1. FS-NNNN IDs: Sort alphabetically by feature name, assign sequential 4-digit numbers starting from 0001
2. BR-NNNN IDs: Sort by parent FS-NNNN first, then alphabetically by rule title within each FS, assign sequential 4-digit numbers starting from 0001 globally
3. EC-NNNN IDs: Sort by parent FS-NNNN first, then alphabetically by edge case title within each FS, assign sequential 4-digit numbers starting from 0001 globally
4. API-NNNN IDs: Sort by parent FS-NNNN first, then by HTTP method order (GET, POST, PUT, PATCH, DELETE), then alphabetically by path, assign sequential 4-digit numbers starting from 0001 globally
5. Data model entities listed alphabetically within each FS
6. No timestamps in artifact body
7. Sections must appear in template order
8. Feature specs ordered by FS-NNNN ID
## Cross-Referencing
The FUNCTIONAL_SPEC.md artifact is referenced by:
- **ARCHITECTURE.md**: Components are designed to implement feature specs
- **TASKS.md**: Tasks map to specific FS-NNNN, BR-NNNN, EC-NNNN, or API-NNNN items
- **IMPLEMENTATION_PLAN.md**: Sprint planning references FS priorities
This artifact references:
- **REQUIREMENTS.md**: Every FS maps to REQ-NNNN IDs
- **PROBLEM_BRIEF.md**: Constraints and non-goals inform feature boundaries
## Handling Complexity
### Large Feature Specs
If a feature spec exceeds 200 lines:
- Split into sub-features (FS-0001a, FS-0001b) only if they have independent user flows
- Otherwise, use clear subsections within the single FS
- Document the complexity in the Summary section
### Missing API Details
If API contracts cannot be fully specified:
- Define the endpoint path, method, and auth requirements at minimum
- Mark request/response bodies as "[TBD — pending data model finalization]"
- Add an Open Question for the missing details
### Conflicting Business Rules
If two business rules within the same feature contradict:
- Document both with a note: "[CONFLICT — see OQ-NNNN]"
- Add an Open Question specifying the conflict
- Do not silently resolve by removing one rule
## Quality Checklist
Before completing, verify:
- [ ] Every REQ-NNNN from REQUIREMENTS.md maps to at least one FS-NNNN
- [ ] Every FS has a happy path user flow with Mermaid diagram
- [ ] P0 features have error path flows documented
- [ ] Every FS has at least one business rule with examples
- [ ] Edge cases cover boundary values, concurrency, and permission boundaries
- [ ] Data models include all required fields (id, created_at, updated_at)
- [ ] Data model relationships and indexes are documented
- [ ] API contracts include success and error responses
- [ ] API contracts specify authentication, authorization, and rate limiting
- [ ] All IDs are sequential and deterministically ordered
- [ ] Mermaid diagrams are syntactically valid
- [ ] Cross-cutting concerns (error handling, auth, validation) are documented
- [ ] No business rule contradicts a constraint from the problem brief
- [ ] Artifact follows the standard template structure
## Common Pitfalls
1. **User flows without decision points**: A linear flow with no branches is not a flow, it is a procedure. Real flows have error handling and decision logic.
2. **Business rules that are vague**: "Users should have appropriate access" is vague. "Only users with the 'admin' role can delete other users' accounts" is precise.
3. **Missing error responses in API contracts**: Every endpoint must handle at least 400 (bad request) and 404 (not found) errors. Auth-protected endpoints need 401 and 403.
4. **Data models without indexes**: If a field is used in queries (WHERE, ORDER BY, JOIN), it needs an index. Document the purpose of each index.
5. **Edge cases that are actually business rules**: "Email must be unique" is a business rule, not an edge case. "What happens when two users try to register with the same email simultaneously" is an edge case.
6. **Specifying implementation in the spec**: "Use Redis for caching" is an implementation decision. "Frequently accessed data should be cached with a TTL of 5 minutes" is a specification.
7. **Ignoring cross-cutting concerns**: Error handling, logging, and auth patterns should be consistent across all features, not defined per-feature.