Open Knowledge Pack 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 | open-knowledge-pack-software-lifecycle-frame-a-proposal | A change needs designing and arguing before anyone builds it. |

| Write a spec | open-knowledge-pack-software-lifecycle-write-a-spec | An accepted proposal needs scoping into an implementable spec. |

| Record a decision | open-knowledge-pack-software-lifecycle-record-a-decision | A decision was actually made and needs its context and consequences preserved. |

| Write a postmortem | open-knowledge-pack-software-lifecycle-write-a-postmortem | An incident happened and the team needs a blameless write-up. |

| Review a design | open-knowledge-pack-software-lifecycle-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.