Feature: Feature

Status: Stable

Summary

A feature is the atomic unit of product specification in SpecScore. It describes a capability the product should have — what it does, why it matters, and how it behaves. Features live in the spec repository under spec/features/ as directories with a mandatory README.md. They can nest (sub-features), accept change requests via proposals, trigger plans, and drive execution through task management tools.

This specification defines the structure, metadata, lifecycle, and conventions that every feature must follow.

Problem

Projects that use structured specifications often have implicit conventions — scattered across contributor guides, root README files, and learned by example. There is no single document that answers:

• What must a feature directory contain?
• What metadata does a feature carry?
• What is a feature's lifecycle?
• How do features relate to plans, proposals, and tasks?

Without a formal definition, new features are created inconsistently, AI agents cannot reliably navigate the feature tree, and validation tools have nothing to validate against.

Design Philosophy

Features are the "what" layer of a specification. They describe desired product behavior — not how to build it (that is the plan's job) and not who is building it right now (that is execution/task management's job).

Features are living documents. Plans are also mutable, but use snapshots to capture immutable reference points (approval, checkpoints, completion). A feature spec evolves as proposals are accepted and incorporated. The feature README always reflects the current desired behavior — not a historical snapshot.

Behavior

Feature location

Features live under spec/features/ in the spec repository:

spec/features/
  README.md                     <- feature index
  {feature-slug}/
    README.md                   <- feature specification
    _tests/                     <- test scenarios (optional)
      {scenario-slug}.md
      flows/
    proposals/                  <- change requests (optional)
      README.md
      {proposal-slug}/
        README.md
    {sub-feature-slug}/         <- sub-feature (optional)
      README.md

REQ: directory-readme

Every feature directory MUST contain a README.md file. This file is the feature specification — the single source of truth for what the feature does and how it behaves.

REQ: slug-format

Feature slugs MUST be lowercase, hyphen-separated, and URL-safe. Underscores, spaces, and special characters are not permitted.

Examples of valid slugs: claim-and-push, model-selection, ui, source-references.

Reserved _ prefix convention

Directories prefixed with _ are reserved for SpecScore tooling and extensions:

REQ: underscore-reserved

Directories prefixed with _ are NOT sub-features. They MUST be excluded from the feature index and Contents table.

Feature README structure

Every feature README follows this template:

# Feature: {Title}

**Status:** {status}

## Summary

One to three sentences describing the feature's purpose.

## Contents

(Only if the feature has sub-features or child directories)

| Directory   | Description                     |
|-------------|---------------------------------|
| [child/](child/README.md) | Brief description of the child |

### child

1-7 sentence summary of each child directory.

## Problem

Why this feature exists. What gap or pain point it addresses.

## Behavior

How the feature works. The bulk of the spec — structure, rules,
examples, edge cases. Topics use ### headings; individual rules
use `#### REQ: {slug}` under their topic.
See [Requirement](../requirement/README.md).

## Interaction with Other Features

(Optional) How this feature relates to other features.

## Dependencies

- feature-slug-1
- feature-slug-2

(Or omit the section entirely if the feature is independent.)

## Acceptance Criteria

Not defined yet.

(Or: a table of ACs when defined.)

## Outstanding Questions

- Question 1
- Question 2

(Or: "None at this time." — the section is never omitted.)

REQ: title-format

Every feature README title MUST use the # Feature: {Title} format. The Feature: prefix is required.

REQ: status-field

A **Status:** field MUST appear immediately after the title. The value MUST be one of: Conceptual, In Progress, Stable, Deprecated.

REQ: required-sections

Every feature README MUST include these sections:

Optional sections

Features MAY include additional sections as needed:

Required section behavior

These requirements define how specific required sections behave when they have no content.

REQ: outstanding-questions

The Outstanding Questions section MUST always be present in every feature README. If there are no open questions, it MUST explicitly state "None at this time." The section MUST NOT be omitted.

REQ: ac-section

The Acceptance Criteria section MUST always be present in every feature README. When no ACs are defined, it MUST state "Not defined yet." and a corresponding Outstanding Question ("Acceptance criteria not yet defined for this feature.") MUST be raised.

REQ: contents-when-children

When a feature has child directories (sub-features), its README MUST include a Contents section with:

1. An index table listing each child directory with a description
2. A 1-7 sentence summary for each child, giving readers context without requiring them to open each child

Feature statuses

These statuses describe the feature's specification maturity, not its implementation progress. A feature can be Stable in spec while its implementation is still in development — the spec is the source of truth for desired behavior.

Feature nesting and identification

Features can contain sub-features as child directories. Each sub-feature is a full feature with its own README.md, status, and lifecycle.

spec/features/ui/
  README.md                  <- parent feature
  hub/
    README.md                <- sub-feature
  tui/
    README.md                <- sub-feature

REQ: path-identification

Features MUST be identified by their path relative to spec/features/. This path is the canonical identifier used in plans, source references, and spec tooling.

Feature index

The feature index (spec/features/README.md) is the entry point for understanding the product's planned capabilities. It contains:

1. An Index table with columns: Feature, Status, Description
2. A Feature Summaries section with a paragraph per feature
3. A Feature dependency graph showing relationships
4. An Outstanding Questions section

REQ: index-completeness

The feature index (spec/features/README.md) MUST list every top-level feature. An unlisted feature is a validation error.

Relationship to Other Artifacts

Features and proposals

Proposals are change requests attached to a feature. They live under {feature}/proposals/ and follow the proposal lifecycle (draft -> submitted -> approved -> implemented). A proposal is non-normative until its content is incorporated into the feature's main README.

Features and plans

Plans bridge features to execution. A plan is triggered by either a new feature spec or an approved proposal. Plans live separately in spec/plans/ but reference the features they affect.

Every plan lists its affected features in its header. Each affected feature's README includes a Plans section back-referencing active plans.

Features and execution

Features do not directly reference execution units. The plan bridges specifications to execution.

Features and outstanding questions

Every feature maintains an Outstanding Questions section. Questions follow the standard question lifecycle defined by the Outstanding Questions feature.

Tooling Support

SpecScore features can be queried programmatically by spec-aware tools:

• Feature info — Retrieve structured metadata (status, parent, children, dependency counts) plus section table-of-contents with line ranges.
• Feature list — Flat listing of all feature IDs.
• Feature tree — Hierarchical view with optional focus and direction.
• Feature deps/refs — Dependency and reverse-dependency traversal.

For Synchestra integration, see synchestra.io CLI documentation.

Configuration

Feature behavior is configured through the project definition file. See Project Definition for available settings.

Interaction with Other Features

For tool integrations (CLI, UI, API, LSP), see Synchestra.

Acceptance Criteria

AC: readme-structure

Requirements: feature#req:title-format, feature#req:status-field, feature#req:required-sections

A feature README has a correctly formatted title (# Feature: {Title}), a valid status field immediately after the title, and all required sections present. A README that violates any of these is rejected by validation.

AC: empty-state-text

Requirements: feature#req:outstanding-questions, feature#req:ac-section

Sections with no content use their prescribed placeholder text. Outstanding Questions says "None at this time." when empty. Acceptance Criteria says "Not defined yet." when undefined, and a corresponding Outstanding Question is raised.

Outstanding Questions

• Should features have a machine-readable metadata format (YAML frontmatter) in addition to the markdown convention (**Status:** X), or is the markdown convention sufficient for both humans and parsers?
• Should sub-feature status roll up to the parent? (e.g., if all sub-features are Stable, is the parent automatically Stable?)
• How should features handle versioning? When a feature undergoes a major redesign, should the old spec be archived or superseded in place?

View as Markdown