𝄞 SpecScore.md
Specification

format: https://specscore.md/features-index-specification

SpecScore Features

SpecScore.Studio: | Explore | Edit | Ask question | Request change |

Core features of the SpecScore specification framework. This table is the canonical Document Types Registry — every SpecScore document type is listed here with its Kind, specification URL, and Consumer Path.

Feature Status Kind URL Consumer Path Index Description
Idea Approved Document https://specscore.md/idea-specification spec/ideas/*.md ideas-index An idea is a pre-spec, lintable one-pager that captures a problem, a recommended direction, an MVP scope, and the assumptions that must hold for the direction to be worth pursuing. Ideas are the optional front-door to SpecScore: they refine a vague concept into something concrete enough to promote into one or more Features.
Feature Stable Document https://specscore.md/feature-specification spec/features/**/README.md features-index 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.
Acceptance Criteria Stable Structure https://specscore.md/acceptance-criteria-specification — — Acceptance criteria (ACs) are optional inline sections within a feature README that bundle related requirements into composite verification conditions. An AC states what must be true for a group of requirements to be satisfied — without prescribing specific inputs, flows, or implementation details. Concrete proof is the scenario's job.
Requirement Stable Structure https://specscore.md/requirement-specification — — A requirement is a discrete, testable rule or condition that a system must satisfy. Requirements live as named subsections within a feature's Behavior section — they are a naming convention, not a separate file artifact. Each requirement is addressable by ID, enabling traceability from acceptance criteria and scenarios back to the specific obligation they verify.
Scenario Stable Document https://specscore.md/scenario-specification spec/features/**/_tests/*.md scenarios-index A scenario is a concrete example of system behavior written in Given/When/Then format. Scenarios live in a feature's _tests/ directory as standalone markdown files, each describing a specific interaction flow with exact inputs and expected outputs. They are the executable proof layer — validating that requirements and acceptance criteria hold under real conditions. Scenarios are linked to the REQs or ACs they validate and are executable by the Rehearse test runner.
Entity Approved Document https://specscore.md/entity-specification spec/features/**/*.entity.md — > Frozen. This Doc-Kind is feature-frozen per decision 0003 — One Structural Language: its contract, lint rules, and specscore entity CLI remain supported unchanged, but it accepts no new capabilities. New structural modelling work uses ModelSpec; a legacy-to-ModelSpec migration path will be specified before formal deprecation.
Property Approved Document https://specscore.md/property-specification spec/features/**/*.property.md — > Frozen. This Doc-Kind is feature-frozen per decision 0003 — One Structural Language: its contract, lint rules, and specscore property CLI remain supported unchanged, but it accepts no new capabilities. New structural modelling work uses ModelSpec; a legacy-to-ModelSpec migration path will be specified before formal deprecation.
Source References Stable Structure https://specscore.md/source-references-specification — — Source references are inline annotations in any source file that link code to SpecScore resources (features, plans, documents). A single prefix — specscore: — lets any tool, linter, or pre-commit hook discover references by binary search, resolve them against the project's spec repository, and transform them into clickable URLs pointing to specscore.org.
Plan Stable Document https://specscore.md/plan-specification spec/plans/**/README.md plans-index A plan is a composite task -- a task that contains subtasks. It bridges feature specifications and change requests to executable work. Plans are mutable documents; snapshots provide immutable reference points for review, approval, and retrospective.
Plans Index Draft Index https://specscore.md/plans-index-specification spec/plans/README.md — The plans index — spec/plans/README.md — is the canonical entry point for understanding what implementation work is planned, in flight, approved, or superseded in a spec repository. It inherits the shared shape of every SpecScore index from the Index feature and declares only the plans-specific overrides: the Contents column set, a Recently Closed section, sub-plan indentation, and an optional per-plan summary convention.
Ideas Index Draft Index https://specscore.md/ideas-index-specification spec/ideas/README.md — The ideas index — spec/ideas/README.md — is the canonical entry point for understanding the pre-spec thinking in a SpecScore repository. It inherits the shared shape of every SpecScore index from the Index feature and declares only the ideas-specific overrides: the Index column set and the archived-exclusion rule that keeps Archived Ideas out of the active index.
Features Index Draft Index https://specscore.md/features-index-specification spec/features/README.md — The features index — spec/features/README.md — is the canonical entry point for understanding the feature surface of a SpecScore repository. It inherits the shared shape of every SpecScore index from the Index feature and declares only the features-specific override: the column set (Feature, Status, Description). Consumer repos that use SpecScore carry a features-index that follows this spec; no extra metadata is required.
Scenarios Index Draft Index https://specscore.md/scenarios-index-specification spec/features/**/_tests/README.md — The scenarios index is the per-feature aggregation of test scenarios living under {feature}/_tests/. One scenarios index exists per feature that has scenarios, at the path {feature-path}/_tests/README.md. It inherits the shared shape of every SpecScore index from the Index feature and declares only scenario-specific overrides: a compact Scenario / Validates column pair that traces each scenario back to the requirements and acceptance criteria it exercises.
Task Stable Document https://specscore.md/task-specification spec/plans/**/tasks/*.md — A task is the atomic unit of work in SpecScore. It is a leaf node -- actionable work that an agent or human picks up and completes. Tasks live as directories with a README.md and carry properties that describe their dependencies, acceptance criteria, status, and artifacts.
Lesson Approved Document https://specscore.md/lesson-specification spec/lessons/*/README.md lessons-index A Lesson is the durable, compact rule learned from a process gap. It is separate from append-only Occurrences that evidence the gap, so a recurring problem enriches evidence without repeatedly rewriting the lesson that names the improvement.
Lessons Index Approved Index https://specscore.md/lessons-index-specification spec/lessons/README.md — The Lessons Index at spec/lessons/README.md is the concise inventory of process-improvement Lessons. It presents recurrence as derived read-model data, never as a hand-maintained counter.
Repo Config Draft Document https://specscore.md/repo-config specscore.yaml — Defines specscore.yaml, the single mandatory repository-level config file for SpecScore projects. Specifies the file name, the mandatory schema-pointer header comment, the optional project identity block, related-project navigation hints, top-level dir-name overrides, modules with code roots, studio configuration, publication policy, and inference defaults so a minimal repo can ship with an effectively empty config.
Adherence Footer Draft Meta — — — The adherence footer is a single italic line at the bottom of every SpecScore document that declares — in one machine-verifiable, human-readable sentence — which specification format the document conforms to. It is the mechanism every Document-Kind feature uses so authors do not re-specify the rule per document type, and so lint can validate conformance from the footer alone.
Document Types Registry Draft Meta — — — The document types registry is the single canonical list of every document type SpecScore defines — Features, Plans, Ideas, Tasks, Scenarios, Indexes, and the Meta features that define SpecScore itself. The registry is a Meta overlay on the features-index: in the SpecScore meta-spec repository, spec/features/README.md serves simultaneously as the features-index (base shape) AND the registry (four additional columns capturing the doc type taxonomy). This feature specifies the overlay — the additional columns, the Kind taxonomy, and the lint cross-check that prevents drift between registry rows and feature-declared URLs.
Index Draft Meta — — — The Index feature specifies the shared shape of every Index-Kind feature in SpecScore — the structural rules that apply equally to the plans index, the ideas index, and any future index (tasks, features, proposals). It defines what every Index-Kind feature has in common: where the canonical index file lives, which sections it must contain, the completeness rule that tooling enforces, and the adherence-footer delegation every index inherits.
Studio Toolbar Approved Meta — — — Replaces the single "View in SpecStudio" link at the top of every feature README with a fixed four-item toolbar — Explore, Edit, Ask question, Request change — linking into the SpecScore.Studio web app at specscore.studio/app/. Defines the canonical byte form of the toolbar line, the URL grammar (/app/{host}/{org}/{repo}/{artifact_path}?op={verb}, per the canonical scheme in Studio URL Scheme decision (D-0001)), the brand attribution rendering rule, the new studio-toolbar lint rule (replacing view-link), and the --fix autofix that rewrites legacy lines into the canonical form.
Decision Approved Document https://specscore.md/decision-specification spec/decisions/<NNNN>-<slug>.md — A decision is a durable, lintable record of a choice made between two or more options — what was chosen, why, what was declined, and what consequences were predicted and then observed. Decisions are SpecScore's Architecture-Decision-Record primitive, adapted to SpecScore conventions (markdown-body metadata, REQ blocks, AC blocks, adherence footer).
Decisions Index Approved Index https://specscore.md/decisions-index-specification spec/decisions/README.md — The decisions index — spec/decisions/README.md — is the canonical entry point for reviewing the architectural, product, and process choices made in a SpecScore repository. It inherits the shared shape of every SpecScore index from the Index feature and declares only the decisions-specific overrides: the Index column set, the numeric ordering rule, and the exclusion of Rejected, Superseded, and Deprecated Decisions from the active index.
Grade body-metadata field Approved — https://specscore.md/feature-specification — — Defines an optional, single-value quality Grade as a canonical body-metadata field on gradeable SpecScore artifacts. The value is validated by specscore spec lint against a value set that defaults to A, B, C, D, F and is configurable per repository in specscore.yaml. The field is defined generically — it is not coupled to any reviewer-gate workflow or to an artifact's Status.
Publication Policy Config Approved — https://specscore.md/feature-specification — — Defines durable project and user configuration for SpecScore publication policy: ordered action lists, event and command scopes, branch safety, precedence, and validation rules. This Feature owns the schema consumed by SpecStudio skills and the specscore CLI; it intentionally does not define conversational prompts or perform git operations.
Drift Recap In Review — https://specscore.md/feature-specification — — A drift recap is a machine-generated, per-acceptance-criterion record of how a Feature's specification compares to the code that claims to satisfy it, captured at a specific commit. It already exists in practice — produced by the specstudio:recap skill — but SpecScore has never defined it. This Feature formalizes it as a first-class, status-less SpecScore document type: a registry row, a format: frontmatter contract, a descriptive provenance metadata block, and a lint rule that validates the YAML summary block the producing tooling already emits. Per Decision D-0002, a drift recap is always written to the user's hub repo (a configured location; default a dedicated repo; may be configured to equal the current code repo) rather than co-located in spec/.
Session Recap In Review — https://specscore.md/feature-specification — — A session recap is an automatically generated journal rollup over a working session window — its goal, decisions, scope changes, what shipped, the commits, verification, and follow-ups — the persisted "summary" projection of the journal. Per Decision D-0002, it is status-less (no Draft → Final → Archived lifecycle, no status: frontmatter), gains an optional human notes/comments section, and is keyed <timestamp>-<title>.md. It lives in the user's hub repo with a per-user subdirectory so one shared repo can hold many people's recaps without collisions. This Feature defines the artifact type — frontmatter, body shape, storage rule, the recaps: config block — and a specscore recap new --session scaffold. SpecScore defines the artifact; a producing skill writes it.
Journal and Summary In Review — https://specscore.md/feature-specification — — The journal is an append-only, low-cost record of SpecScore activity, written one event per file (date-sharded) at the existing event-emission points, plus an on-demand summary projection (day / week / month) computed at query time. It is the rollup spine of the recap model named by Decision D-0002: the session recap and month report are projections of the journal over a time window, and recap.completed / verify.completed events carry report_path + per-AC verdict counts so portfolio rollups link into the detail without scanning recap filenames for the time dimension. This Feature defines Phase 1 (single-repo journal, project-only config) — the event store and schema, write-time stream resolution, deterministic auto-write, explicit write, and the two read commands. The cross-repo journal.repo capability (Phase 2) is a proposal attached to this Feature, gated on the layered-config Feature (Under Review; not yet implemented).
Layered Config In Review — https://specscore.md/feature-specification — — Layered config resolves SpecScore configuration from three layers — specscore.local.yaml (repo, uncommitted) → specscore.yaml (repo, committed) → ~/.specscore.yaml (user/machine) — with the most specific layer winning per key and maps deep-merged. It also introduces user-scoped keys: keys that carry per-user/per-machine paths (e.g. recaps.repo, recaps.user, journal.repo, journal.stream) and therefore MUST NOT be committed into the shared project specscore.yaml, but may be set in specscore.local.yaml or ~/.specscore.yaml. This is the foundational Feature that the recap/portfolio stack depends on: it is what lets a developer point their hub repo and journal at personal locations without leaking those paths to teammates. Until it lands, those keys are documented-but-rejected by their owning Features.
Artifact Frontmatter Convention Approved — https://specscore.md/feature-specification — — Every SpecScore artifact carries two YAML-frontmatter fields: format: — the spec URL for its type (machine-readable, mirrored by the human-visible footer line *This document follows the …*, which is retained, not replaced) — and, for status-bearing types, status: — a mirror of the body **Status:** token. The body **Status:** stays canonical; frontmatter status: is a derived mirror kept in lockstep by the CLI and validated by lint. The footer keeps a human-visible format surface for renderers that hide frontmatter; lint keeps the footer URL and frontmatter format: in sync. This reconciliation follows the Approved Format Declaration — Footer + Frontmatter Mirror Idea, which supersedes the earlier footer-removal stance. This is the generic convention the drift-recap and session-recap Features name as a forward dependency: it defines the format: requirement and the Status-concept classification that determines which types carry status: and which (the status-less ones) must not.
Capability and Platform Implementations Implementing — https://specscore.md/feature-specification — — Defines two roles on the existing SpecScore Feature: a Capability (a platform-agnostic feature definition) and an Implementation (one platform's realization of it). An Implementation links upward with an **Implements:** reference reusing the source-references notation, so the link works across repositories. The Capability owns a single author-declared Implementation Matrix that records each platform's parity level and a one-line brief — making cross-surface feature drift visible at the spec layer instead of silent.
Capability Delivery Matrix Draft — https://specscore.md/feature-specification — — Defines a generated per-CLI matrix that traces every user-facing capability across runtime commands and flags, help, AI skills, and executable tests, so implemented and advertised behavior cannot drift silently.
New-Artefact Template Gallery Stable — https://specscore.md/feature-specification — — Publishes the canonical new-artefact templates as raw Markdown files on specscore.md — one per artefact type at /new/<type>.md — with a browsable index at /new/. Each published file is the bare, ready-to-fill skeleton (canonical section headings plus <!-- … --> authoring prompts), so humans, agents, and (via a later Feature) the CLI can fetch a valid starting point for a new artefact from one authoritative URL. Each skeleton also carries the YAML frontmatter every artefact is required to declare under the Approved Artifact Frontmatter Convention — a format: spec-URL key on every type, plus a status: mirror on status-bearing types — so a filled-in template is convention-clean from the first byte.
CLI Template Runtime-Fetch Stable — https://specscore.md/feature-specification — — The specscore … new scaffolders fetch the canonical artefact template from the published gallery (specscore.md/new/<type>.md) at create-time, fill the known fields (title, date, owner), and write the file — falling back to an embedded copy with a stderr warning when the site is unreachable. This makes the published gallery the live source of truth for templates, so fixes ship via the website without a CLI release, while preserving today's offline-capable UX.
Configurable Ideas Path Approved — https://specscore.md/feature-specification — — Resolve each module's ideas directory through repo-config's per-module path_overrides.ideas_path (default spec/ideas) via a single resolution contract that every reader uses, instead of a hardcoded spec/ideas literal.
Status Vocabulary Approved — https://specscore.md/feature-specification — — A single canonical definition of the lifecycle status values used by every status-bearing SpecScore artifact (Idea, Feature, Plan, Decision, sidekick Seed). Status values are organized by lifecycle role; each role has one shared term reused across artifacts, and every deviation from the shared term is an explicitly documented conscious divergence with a rationale (not silent drift). This Feature also establishes that archival is orthogonal to status — an axis of storage/visibility, never a status value. It is the source of truth the per-artifact Features (idea, feature, plan, decision) conform to, complementing artifact-frontmatter-convention, which governs where status is carried (body-canonical + frontmatter mirror) while this Feature governs which values are legal.
Implementation Commit Provenance Approved — https://specscore.md/feature-specification — — An optional, single provenance reference linking an implemented Task to the actual code commit that implemented it — a cross-repo <repo>@<sha> reference (optional branch) carried on the Task. When code is lost to a merge/rebase, the recorded reference is durable evidence that the work existed and a pointer to recover it. A Plan's implementation evidence is the derived rollup of its tasks' provenance references; it is a distinct axis from the existing plan ## Snapshots Git Hash, which records spec-document state.
Unify Task Status Vocabulary Approved — https://specscore.md/feature-specification — — The 7-value Task status enum — planning, queued, in_progress, blocked, complete, failed, aborted — is the single canonical task-status vocabulary across every surface: the Task entity, plan-inline ### Task N: blocks, the specscore plan new scaffold, the plan execution-band rollup, the task change-status verb, and the implement skill. This Feature retires the divergent pending/in-progress/done/blocked token set that the scaffold and implement skill use today, defines the canonical lifecycle the implement skill follows, and makes specscore spec lint --fix auto-migrate legacy tokens.
GraphSpec Draft Document https://specscore.md/feature-specification spec/features/graphspec/ — GraphSpec is a bootstrap specification language for describing connected domain models.
ModelSpec Validation Draft Document https://specscore.md/feature-specification spec/features/modelspec-validation/ — SpecScore recognizes ModelSpec as a first-class independent specification and provides

Feature Hierarchy

spec/features/
├── idea/                      # How to structure pre-spec ideation artifacts
├── feature/                   # How to structure and write features
├── requirement/               # How to define addressable rules in Behavior sections
├── acceptance-criteria/       # How to define abstract verification conditions
├── scenario/                  # How to write concrete behavior examples
├── entity/                    # How to define typed business objects with YAML-frontmatter source of truth
├── property/                  # How to define reusable single-field property definitions
├── source-references/         # How to link code to specifications
├── capability-delivery-matrix/ # CLI runtime/help/skill/test traceability
├── plan/                      # How to structure planning documents
├── plans-index/               # How to structure the plans index
├── ideas-index/               # How to structure the ideas index
├── features-index/            # How to structure this features index
├── scenarios-index/           # How to structure per-feature scenarios indexes
├── task/                      # How to define discrete units of work within a plan
├── lesson/                    # Compact process-improvement rules with occurrence evidence
├── lessons-index/             # How to structure the lessons index
├── repo-config/               # Repo-level config (specscore.yaml): identity, modules, studio, publication policy
├── adherence-footer/          # Shared footer mechanism
├── document-types-registry/   # Canonical list of document types (this registry)
├── index/                     # Shared shape of every Index-Kind feature
└── publication-policy-config/ # Durable project and user publication policy config

The specscore CLI is specified separately at specscore/specscore-cli.

Integration with Orchestration Tools

SpecScore specs are format-agnostic. These features define the mental model and conventions:

See synchestra.io for orchestration on top of SpecScore.

Open Questions

None at this time.

This document follows the https://specscore.md/features-index-specification

View as Markdown