Docs spine

Skill MrEyratnz/software-factory/skills/docs-spine

Author and maintain the docs spine (VISION.md, ARCHITECTURE.md, numbered ADRs, ROADMAP.md) with exact templates, monotonic ADR numbering via the connector, and merged-green roadmap checkbox discipline. Use when starting a repo, recording a decision, adding a milestone, or checking off a roadmap item.From its SKILL.md

Install

npx -y skills add MrEyratnz/software-factory --skill docs-spine

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

5.1 KB, as published. Nobody here has run it

docs-spine

The docs spine is the durable, human-and-agent-readable memory of the project: why (VISION), how it is shaped (ARCHITECTURE), what we decided and why (ADRs), and what is left (ROADMAP). These four files live under docs/ (ADRs under docs/adr/) — the layout /factory-init stamps and the .factory/config.json defaults (roadmapPath: docs/ROADMAP.md, adrDir: docs/adr) point at; when in doubt, defer to those config keys rather than a hard-coded path. They are the source of truth agents read before acting. Runtime verdicts come from the connector — do not eyeball.

Invariants (never violate)

The four files always exist: docs/VISION.md, docs/ARCHITECTURE.md, docs/adr/NNNN-*.md, docs/ROADMAP.md (or wherever roadmapPath/adrDir point).
ADR numbers are monotonic and connector-assigned. Call adr_index for the next number. Never hand-pick — concurrent agents will collide.
ADRs are append-only. To reverse a decision, write a NEW ADR that supersedes the old one and set the old one's Status: to superseded by ADR NNNN. Never rewrite decided history.
Roadmap items are checked [x] ONLY when merged with green tests — never in advance, never "about to". The flip is enforced by guard-roadmap, which demands a merged-green proof.
Work the roadmap top-to-bottom. roadmap_next names the next item; roadmap_status / roadmap_check are the authority on state — not your reading of the file.

ADR procedure

adr_index → get the next number NNNN (zero-padded, e.g. 0009) and confirm no collision. It scans the repo's configured adrDir (default docs/adr), so numbering honors a non-default ADR location.
Create <adrDir>/NNNN-kebab-title.md (default docs/adr/…) from the template below.
Start at Status: proposed; flip to accepted when the decision is merged.
If it changes system shape, reflect the outcome in docs/ARCHITECTURE.md in the same PR.
For contested design, use the judge-panel method (ADR-0009): 3 stance proposals → adversarial panel names each fatal flaw → synthesize a decision that resolves every named flaw, recorded here.

ADR template (exact headings)

# ADR NNNN — <concise decision title>

Status: proposed | accepted | superseded by ADR NNNN · Date: YYYY-MM-DD

## Context

<The forces at play: the problem, constraints, and what made a decision necessary.
State facts, not the choice.>

## Decision

<The choice, in active voice: "We will …". Include what was explicitly rejected.>

## Consequences

<What becomes easier and harder. New obligations, follow-up ADRs, tech-debt created.
Name the trade-off you accepted.>

ROADMAP procedure

Structure as ordered milestones M0..Mn, each a heading with - [ ] checkbox items.
Order items by dependency; the agent takes the first unchecked item (roadmap_next).
Check [x] only after the item's PR is merged green. Add the proof link inline so the guard-roadmap receipt is auditable.
Never add "future" checked items; never batch-check. One item, one merged-green flip.

ROADMAP.md skeleton

# Roadmap

Worked top-to-bottom. An item flips to [x] only when merged with green tests (guard-roadmap).

## M0 — Foundations
- [x] Scaffold modular monorepo + CI gates  (merged: #12)
- [ ] Design tokens single-source + drift gate

## M1 — Core domain
- [ ] Kernel domain model + contract-test-suite-per-port
- [ ] First adapter behind a port

## M2 — Delivery
- [ ] release-please wired (Conventional Commits)
- [ ] Smoke-test the built artifact in CI

VISION.md skeleton

# Vision

## Problem
<Who hurts and how, today.>

## Outcome
<The changed world when this works. One paragraph.>

## Principles
- <Non-negotiable that decides ties, e.g. "autonomy over convenience">

## Non-goals
- <Explicitly out of scope, so agents don't drift into it.>

ARCHITECTURE.md skeleton

# Architecture

## Shape
Modular monolith: kernel < modules < app. Ports/adapters; dependency direction enforced by
dependency-cruiser. Contract-test-suite per port.

## Modules
| Module | Responsibility | Depends on |
|--------|----------------|------------|
| kernel | pure domain    | —          |
| <mod>  | <capability>   | kernel     |
| app    | composition    | modules    |

## Cross-cutting
- Testing: typecheck → module-boundary → unit → BDD → build → generated-artifact drift.
- Decisions of record: see `docs/adr/`. This file reflects their outcomes, never overrides them.

Definition of done

Next ADR number came from adr_index, not a guess.
ADR has all headings (Status/Context/Decision/Consequences) and a Date.
ARCHITECTURE reflects any shape change from the ADR (same PR).
Every [x] in ROADMAP has a merged-green proof (guard-roadmap passes).