𝄞 SpecScore.md
GitHub
Specification

Feature: Project Definition

Status: Stable

Summary

How SpecScore discovers and configures specification projects. Every SpecScore project has a specscore-project.yaml file as its entry point, declaring project metadata and directory conventions.

Contents

Directory Description
_tests/ Test scenarios for project definition requirements

Problem

SpecScore needs a consistent way to discover where specifications and documents live within a repository. Without a project definition file, tools must guess directory layouts, project names, and repository associations. A standard project file eliminates ambiguity for both human contributors and spec-aware tooling.

Behavior

Project file location

The project configuration file is specscore-project.yaml. It lives at the root of the specification repository.

REQ: project-file-location

Every SpecScore project MUST have a specscore-project.yaml file at the repository root. This file is the entry point for all SpecScore tooling.

Mandatory fields

The project file has one mandatory field:

Field Description
title Human-readable project name

REQ: title-required

The specscore-project.yaml file MUST contain a title field. A project file without a title is invalid.

Optional fields

Field Default Description
description — Brief description of the project
repos — List of code repository URLs associated with this project
project_dirs.specifications spec Directory for technical specifications (features, architecture, etc.)
project_dirs.documents docs Directory for user-facing documentation

REQ: optional-field-defaults

When optional project_dirs fields are omitted, SpecScore MUST use the default values: spec for project_dirs.specifications and docs for project_dirs.documents.

Repository structure

SpecScore specification projects follow a standard directory layout:

{repo}/
  specscore-project.yaml        # Project configuration
  README.md                     # Project overview
  spec/                         # Specifications (configurable)
    features/
      ...
    plans/
      ...
  docs/                         # Documentation (configurable)
    ...

REQ: directory-layout

The spec/ and docs/ directories MUST be configurable via project_dirs fields. Tools MUST resolve specification and document paths using the configured values rather than hardcoded defaults.

Example

title: My Service
description: Backend API and web frontend for Acme Corp
repos:
  - https://github.com/org/my-service-api
  - https://github.com/org/my-service-web
project_dirs:
  specifications: spec
  documents: docs

Orchestration tool extensions

Orchestration tools (like Synchestra) may extend specscore-project.yaml with additional fields:

# Example: Synchestra extension
state_repo: https://github.com/org/project-synchestra
planning:
  auto_create: false

REQ: unknown-fields-ignored

SpecScore MUST ignore unknown fields in specscore-project.yaml. This allows any orchestration tool to add its own configuration alongside the standard SpecScore fields without causing validation errors.

Acceptance Criteria

Not defined yet.

Outstanding Questions

View as Markdown