software-lifecycle

# Software Lifecycle pack — how to work here This project holds the doc lifecycle for an engineering team or OSS project. The flow is **proposals → decisions → specs → postmortems**, with **guides** as the how-to bucket. This skill holds the workflow so templates and folder descriptions stay clean. > This skill is pack guidance. The platform `/open-knowledge` skill (read/write/preview/linking/grounding rules) still governs every markdown operation — this layers the lifecycle conventions on top. ## The flow ``` proposals/ in-flight RFC-shape design proposals ↓ accepted decisions/ frozen ADRs (the record of what was decided) ↓ derived specs/ implementation specs for accepted proposals ↓ when things break postmortems/ blameless incident write-ups guides/ how-to / onboarding / runbooks (referenced throughout) ``` ## Per-folder rules + agent behaviors **`proposals/`** — One file per proposal (`0001-feature-name.md`). Status flows `draft → fcp → accepted/rejected`. An accepted proposal graduates to a record in `decisions/`. Shape: Motivation / Design / Drawbacks / Alternatives / Unresolved questions. *Agent: when a proposal sits at `status: draft` more than 14 days, surface it for the author to advance, park, or close.* **`decisions/`** — Architecture Decision Records (MADR / Nygard shape). Frozen once accepted. One file per decision (`NNNN-title.md`); status `proposed/accepted/deprecated/superseded`. A new decision that supersedes an older one links back via `Supersedes:`. *Agent: on a new decision, scan existing records touching the same subsystem and surface `Supersedes:` candidates before commit.* **`specs/`** — Implementation specs derived from accepted proposals. Prefer the `github/spec-kit` shape: one folder per spec (`specs/NNN-name/`) with `spec.md` + `plan.md` + `tasks.md` (the pack ships all three templates). References the parent proposal. *Agent: when a spec moves to `status: shipped`, suggest a postmortem template if the owner reports an incident in the spec's subsystem.* **`postmortems/`** — Blameless incident write-ups, one file per incident (`YYYY-MM-DD-name.md`): Summary / Timeline / Root cause / What went well / Action items (Google SRE shape). *Agent: surface a `Related:` block linking prior postmortems that share subsystems.* **`guides/`** — How-to guides, onboarding docs, and service-bound runbooks (Diátaxis how-to). Ships `guide`, `onboarding-guide`, and `runbook` templates. Carries `last_verified` so stale guides surface in periodic reviews. *Agent: when a postmortem is published, scan its action items for guide-shaped follow-ups and stub a guide pre-filled with the symptom and timeline excerpt.* ## The five workflows Authoring in this project is procedural, not conventional. Each workflow ships as its own skill so it loads only when the work calls for it — reach for the one that matches the task rather than writing into a folder from scratch. | Workflow | Sibling skill | When | | --- | --- | --- | | Frame a proposal | `/frame-a-proposal` | A change needs designing and arguing before anyone builds it. | | Write a spec | `/write-a-spec` | An accepted proposal needs scoping into an implementable spec. | | Record a decision | `/record-a-decision` | A decision was actually made and needs its context and consequences preserved. | | Write a postmortem | `/write-a-postmortem` | An incident happened and the team needs a blameless write-up. | | Review a design | `/review-a-design` | An existing proposal, spec, or decision needs pressure-testing for soundness. | ## Templates Create docs with `write({ document: { path, template: "<name>" } })`. Templates carry only structure (headings + frontmatter scaffold); what each section is for is described above, not repeated in the document body.