spec-templates

Spec Templates

Provides templates for structured feature specifications.

When to Use

• At the end of soleur:brainstorm to create spec.md
• At the end of soleur:plan to create tasks.md
• When starting any new feature in knowledge-base/project/specs/

spec.md Template

Use this template for feature specifications:

# Feature: [name]

## Problem Statement

[What problem are we solving?]

## Goals

- [What we want to achieve]

## Non-Goals

- [What is explicitly out of scope]

## Functional Requirements

### FR1: [name]

[User-facing behavior]

## Technical Requirements

### TR1: [name]

[Architecture, performance, security considerations]

tasks.md Template

Use this template for task tracking:

# Tasks: [name]

## Phase 1: Setup

- [ ] 1.1 Task description

## Phase 2: Core Implementation

- [ ] 2.1 Main task
  - [ ] 2.1.1 Subtask if needed

## Phase 3: Testing

- [ ] 3.1 Task description

Directory Structure

Each feature gets its own directory:

knowledge-base/project/specs/feat-<name>/
  spec.md      # Requirements (FR/TR)   — indexed in INDEX.md
  tasks.md     # Phased task checklist  — indexed in INDEX.md
  <anything else>                        # working state, NOT indexed

Only spec.md and tasks.md are listed in knowledge-base/INDEX.md. Every other file sitting flat in a spec directory is treated as branch-lifetime working state and is on disk but unindexed (ADR-174). A file you deliberately organise into a subdirectory stays indexed — that is the escape hatch for durable content. If a file here is durable knowledge rather than scratch, either fold it into spec.md or file it under the knowledge-base domain it belongs to — do not rely on it being discoverable through the index.

Usage Examples

Creating a spec for "user-auth" feature

1. Create directory: knowledge-base/project/specs/feat-user-auth/
2. Create spec.md using the template above
3. Fill in Problem Statement, Goals, Non-Goals
4. Add Functional Requirements (FR1, FR2, ...)
5. Add Technical Requirements (TR1, TR2, ...)

Creating tasks from a spec

1. Read the spec.md to understand requirements
2. Create tasks.md using the template
3. Break down each FR/TR into concrete tasks
4. Organize into phases (Setup, Core, Testing)
5. Use hierarchical numbering (2.1, 2.1.1, etc.)

component.md Template

Use this template for project overview component documentation in knowledge-base/project/components/:

---
component: <component-name>
updated: YYYY-MM-DD
primary_location: <path/to/component/>
related_locations:
  - <other/path>
dependencies:
  - <other-component-name>
---

# <Component Name>

[One paragraph - what this component does]

## Purpose

[Why this component exists and its role in the system]

## Responsibilities

- [Key responsibility 1]
- [Key responsibility 2]

## Key Interfaces

[Public APIs, entry points, exported types]

## Data Flow

[How data enters and exits this component - include mermaid diagram if helpful]

## Dependencies

- **Internal**: [other components it uses]
- **External**: [third-party packages]

The `dependencies:` frontmatter list is the **machine-readable** form of the
`**Internal**` line and MUST be kept in agreement with it. The prose line is
human context; the frontmatter field is what
[`c4-from-components.ts`](../../lib/c4-from-components.ts) parses into diagram
edges. Emit both. A doc that names internal dependencies only in prose yields a
diagram of disconnected boxes — see the relationship-count gate in
[`sync.md`](../../commands/sync.md).

## Examples

[Usage examples with code]

## Related Files

- `path/to/file` - [description]

## See Also

- [constitution.md](../constitution.md) for coding conventions
- [Related component](./related.md)

YAML Frontmatter Fields

| Field | Required | Description | |-------|----------|-------------| | component | Yes | Kebab-case component name | | updated | Yes | Date last updated (YYYY-MM-DD) | | primary_location | Yes | Main directory/file path | | related_locations | No | Additional paths if component spans directories | | dependencies | No | Kebab-case component names this component uses. The machine-readable form of the Internal line; parsed into C4 diagram edges. Omit (or []) when the component genuinely has none | | status | No | active, deprecated (default: active) |

Creating a component doc

1. Identify the logical component (not just directory structure)
2. Create knowledge-base/project/components/<name>.md
3. Fill in frontmatter with accurate paths
4. Document purpose, responsibilities, and interfaces
5. Add data flow diagram if the component has complex interactions
6. Link to related files and other components

prd.md Template

Use this template for reverse-engineered Product Requirements Documents emitted by [code-to-prd](../code-to-prd/SKILL.md). PRDs land at knowledge-base/product/prd/<project>-prd.md. Section order is load-bearing — the code-to-prd test harness asserts every header.

---
project: "<package.json name, kebab-case>"
framework: "next.js"
generator: "code-to-prd@v1"
generated_at: "<ISO-8601 UTC>"
walker_count: <int>
walker_excluded: <int>
---

# PRD — <project-name>

<!-- BANNER:DUE-DILIGENCE — non-removable per code-to-prd FR7 -->
> **Due-diligence disclaimer.** [verbatim from banner-template.md]

<!-- BANNER:PII-CONFIDENTIALITY — non-removable per code-to-prd FR7 -->
> **Confidentiality / PII notice.** [verbatim from banner-template.md]

### How to Read This PRD

[Redaction-token format, "redacted ≠ leaked" framing, rotation instruction.]

## Overview

- Project name, framework detected, walk stats.

## Routes

### App Router

[Routes derived from `app/**/page.{tsx,jsx,ts,js}` and `app/**/route.{ts,js}`.]

### Pages Router

[Routes derived from `pages/**/*.{tsx,jsx,ts,js}` excluding `pages/_*`.]

## State Shapes

[Top-level `useState`/`useReducer`/server-component props (regex, best-effort).]

## API & External Dependencies

[fetch() URLs + `@/lib/api*`/`@/server/*` imports + `process.env.*` names + third-party SDK packages from `package.json`.]

## Coverage Caveats

### Frameworks not scanned
### Extraction techniques used
### Excluded by path filter
### GDPR Art. 9 special-category disclaimer

## Gap Analysis

[Populated by `@agent-soleur:product:spec-flow-analyzer` Task spawn. Degraded-success leaves `SKIPPED (spec-flow-analyzer unavailable at <ISO-8601>)`.]

---

_Adapted from `alirezarezvani/claude-skills` (MIT) — see [plugins/soleur/NOTICE](../../NOTICE)._

Coverage Caveats contract

## Coverage Caveats MUST be non-empty on every emit. All four subsections are mandatory regardless of extractor coverage — even on a maximally simple input. "None" is forbidden. The four subsections (frameworks not scanned, extraction techniques, exclusion counts, Art. 9 disclaimer) are asserted by the code-to-prd test harness.

Banner contract

Banners are non-removable — operator-edit of the rendered PRD is allowed, but the dual-banner block (sentinels BANNER:DUE-DILIGENCE + BANNER:PII-CONFIDENTIALITY) must remain intact. Verbatim string match enforced by the test harness.