3.4 KiB

Raw Permalink Blame History

adr-authoring

ADDED Requirements

Requirement: Standard ADR template

The plugin SHALL provide a single customized-Nygard ADR template used identically in every project, with frontmatter fields id, date, status, supersedes, superseded-by, affected-paths, affected-components, and body sections Context, Decision, Consequences, and Alternatives rejected. The plugin SHALL NOT provide per-project or per-client template variants.

Scenario: Template contains all required fields

WHEN a new ADR is generated in any project
THEN the resulting file contains every frontmatter field and body section listed above, in template order

Scenario: No project-specific variation

WHEN ADRs are generated in two different projects
THEN both files follow the identical template structure

Requirement: One file per decision at the standard location

ADRs SHALL be stored one-file-per-decision at docs/adr/NNNN-kebab-title.md, where NNNN is a 4-digit zero-padded sequential ID derived by scanning the existing directory contents (max existing ID + 1), never by trusting the index file.

Scenario: Sequential ID assignment

WHEN docs/adr/ contains ADRs 0001 and 0002 and a new ADR titled "Use Postgres" is created
THEN the new file is docs/adr/0003-use-postgres.md

Scenario: ID derived from directory, not index

WHEN the index file is stale or missing but docs/adr/0007-*.md exists
THEN the next generated ADR receives ID 0008

Requirement: Mechanically maintained index

The plugin SHALL maintain an index file at docs/adr/README.md listing every ADR's ID, title, status, and date. The index SHALL be regenerated in full from the directory contents on every ADR write, with no LLM involvement, and SHALL declare itself generated/never-hand-edited.

Scenario: Index updated on ADR creation

WHEN a new ADR is created via the generator
THEN the index file is regenerated and contains a row for the new ADR

Scenario: Index self-heals

WHEN an ADR file was added or edited manually and the generator next runs
THEN the regenerated index reflects the actual directory contents

Requirement: One-invocation ADR creation skill

The plugin SHALL provide a create skill (/os-adr:create) that produces a correctly templated, correctly numbered, and indexed ADR in a single invocation, and an init skill (/os-adr:init) that sets up docs/adr/ plus the index in a project that has none.

Scenario: Create in one invocation

WHEN the user (or agent) invokes /os-adr:create with a decision to record
THEN a new templated ADR file exists under docs/adr/ and the index includes it, with no further steps required

Scenario: Init on a fresh project

WHEN /os-adr:init runs in a project without docs/adr/
THEN docs/adr/ and an empty index exist and any session-hook suppression flag for the project is cleared

Requirement: Supersession is mechanical

WHEN a new ADR declares supersedes: NNNN, the generator SHALL set superseded-by on the referenced ADR and update its status accordingly, without manual edits.

Scenario: Superseding an existing ADR

WHEN a new ADR 0009 is created with supersedes: 0004
THEN ADR 0004's frontmatter gains superseded-by: 0009 and status Superseded, and the regenerated index shows both statuses

3.4 KiB Raw Permalink Blame History