Spec Items¶

Spec items are the core building blocks of FuncSpec. Each item captures a single unit of requirement, design decision, or implementation task.

Item Types¶

FuncSpec has two distinct item types:

Functional Specs (F-xxx)¶

Functional specs describe what the system should do from a product or user perspective. They focus on behavior, not implementation.

Examples: - "Users can reset their password via email" - "The checkout flow accepts credit cards and PayPal" - "Admins can export reports as CSV or PDF"

Functional specs are assigned sequential permalinks: F-1, F-2, F-3, and so on.

Technical Specs (T-xxx)¶

Technical specs describe how something will be implemented. They are typically more granular and reference specific components, services, or APIs.

Examples: - "Implement PasswordResetService using HMAC-signed tokens with 1-hour expiry" - "Add stripe_customer_id column to the users table" - "Create POST /api/v1/exports endpoint returning presigned S3 URL"

Technical specs use the T-xxx permalink prefix.

Tip

A common workflow is to write functional specs first, then use AI Generate Tech Specs to derive technical specs automatically.

Creating a Spec Item¶

Via Web Interface¶

In your project, click New Spec Item
Choose the type: Functional or Technical
Fill in the fields:
Title: A short, descriptive summary
Description: Full details in Markdown (rich editor supported)
Priority: Low, Medium, High, or Critical
Tags: Comma-separated labels for filtering
Parent: Optionally nest under another spec item
Click Save

Via CLI¶

# Create a functional spec
funcspec items create \
  --project my-app \
  --type functional \
  --title "User password reset" \
  --description "Users can reset their password via a link sent to their email address."

# Create a technical spec with tags and priority
funcspec items create \
  --project my-app \
  --type technical \
  --title "Implement PasswordResetService" \
  --priority high \
  --tags "auth,backend"

Via API¶

curl -X POST https://funcspec.net/api/v1/projects/42/spec/items \
  -H "X-Api-Key: $FUNCSPEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "User password reset",
    "type_of": "functional",
    "description": "Users can reset their password via email.",
    "priority": "high",
    "tags": ["auth", "security"]
  }'

Item States¶

Every spec item moves through a lifecycle:

draft → inbox → accepted
                rejected

State	Description
draft	Work in progress, not yet ready for review
inbox	Submitted for team review and triage
accepted	Approved — this requirement is in scope
rejected	Out of scope or superseded

Transitioning State¶

Via web: Use the status badge dropdown on any item, or the Inbox view for bulk triage.

Via CLI:

funcspec items transition F-12 --state accepted
funcspec items transition F-15 --state rejected

Via API:

curl -X POST https://funcspec.net/api/v1/projects/42/spec/items/15/transition \
  -H "X-Api-Key: $FUNCSPEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"state": "accepted"}'

Note

Only accepted items appear in exports and are included in AI batch operations by default.

Implementation Status¶

Accepted technical specs can track implementation progress separately from their acceptance state:

Status	Description
pending	Not yet started
in_progress	Implementation underway
implemented	Code is written
verified	Implementation verified by code audit
not_applicable	Won't be implemented (with reason)

Transition implementation status via the item detail view or CLI:

funcspec items transition-impl T-7 --status implemented

Tags and Priorities¶

Tags¶

Tags are free-form labels for organizing and filtering specs:

Add multiple tags per item (e.g., auth, api, v2, breaking-change)
Filter by tag in the spec list view or via ?tag=auth in the API
Tags are scoped to a project

Priorities¶

Priority	Use for
critical	Blockers, must-haves for launch
high	Core functionality
medium	Default — standard features
low	Nice-to-haves, future consideration

Parent/Child Hierarchy¶

Spec items can be nested to represent hierarchical requirements:

F-1: Authentication System
├── F-2: Email/password login
├── F-3: OAuth login (Google, GitHub)
└── F-4: Two-factor authentication

To set a parent: - Web: Select "Parent Item" when creating or editing - CLI: --parent F-1 - API: "parent_id": 1

Note

Parents and children can be the same type (functional or technical). There is no enforced depth limit, but deeply nested hierarchies can become hard to navigate.

Permalinks¶

Every item has a permanent identifier that never changes:

Functional items: F-1, F-2, …
Technical items: T-1, T-2, …

Permalinks appear in: - The item URL: /acme/my-app/spec/F-12 - CLI references: funcspec items show F-12 - API paths use the numeric ID, but the permalink is included in the response

Version History¶

FuncSpec tracks every change to a spec item:

What changed: Title, description, state, tags, priority
Who changed it: Author attribution
When: Timestamp for every version

Access version history via the item's History tab in the web interface, or via the API.

Editing and Deleting¶

Editing¶

Click Edit on any item (requires Editor or Admin role). The description field uses a rich Markdown editor with support for tables, code blocks, and task lists.

# Edit via CLI (opens $EDITOR)
funcspec items edit F-12

# Update specific fields
funcspec items update F-12 --title "New title" --priority high

Deleting¶

Warning

Deleting an item removes it and all associated AI reviews, proposals, and dependency edges. This cannot be undone.

funcspec items delete F-12 --confirm

Inbox¶

The Inbox is a queue of items with state inbox, designed for triage workflows. Team members submit draft specs to the inbox; admins or editors review and accept or reject them.

Access the Inbox via Project → Inbox or via the API:

curl https://funcspec.net/api/v1/projects/42/inbox \
  -H "X-Api-Key: $FUNCSPEC_API_KEY"