Software lifecycle

One home for the docs an engineering team writes around its code: the pitch for a change, the decision that settles it, the plan to build it, and the write-up when something breaks. Each links to the next, and an AI keeps the connections current. Built on the Software lifecycle starter pack.

A software lifecycle knowledge base is where an engineering team's thinking lives before, during, and after the code: the proposal that argued for a change, the decision that settled it, the spec that built it, and the postmortem written when it broke. Those are the usual names for each stage, and if they're new to you the page explains them as it goes. One folder per stage, one flow connecting them, and an AI that keeps the links between them honest.

The stages are the standard artifacts an engineering org already produces — RFCs, ADRs, specs, blameless postmortems, runbooks — but here they live as linked markdown an agent reads and writes alongside you, not as scattered Google Docs, Notion pages, and Slack threads that nobody can trace six months later.

Engineering leads get every proposal, decision, and spec in one linked graph, with the agent surfacing what supersedes what, so design docs stop rotting across scattered tools. OSS maintainers give contributors the why behind the code — in accepted proposals and frozen ADRs — instead of leaving them to do archaeology through closed PRs. On-call engineers get postmortems that link to each other and stub the follow-up guides automatically, so recurring incidents become visible instead of quietly repeating.

The flow

proposals/    in-flight, RFC-shape design proposals   (draft → fcp → accepted/rejected)
   ↓ 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

The pack ships a template for each: proposal, decision, spec / plan / tasks (the GitHub spec-kit three-file shape), postmortem, and guide / onboarding-guide / runbook. Templates carry only structure; what each section is for is taught to the agent by the folder itself, so document bodies stay clean.

The scenario

Your team is deciding whether to move the job queue off Postgres onto a dedicated broker. Over two weeks:

An engineer writes proposals/0007-dedicated-job-broker.md — motivation, design, drawbacks, alternatives, unresolved questions. Status draft.
After review it reaches fcp (final comment period), then accepted. The agent graduates it into decisions/0007-adopt-nats-for-jobs.md, a frozen ADR that links back to the proposal.
Implementation gets a specs/007-job-broker/ folder — spec.md, plan.md, tasks.md — referencing the parent decision.
Three weeks post-ship the broker drops messages under load. postmortems/2026-07-14-job-broker-message-loss.md captures the timeline and root cause, and the agent surfaces a Related: link to an older queue postmortem that shares the subsystem.

Nothing here is new to your team. What's new: it's all one linked graph an agent can read back to you, and the links stay correct because the agent maintains them.

What's in your project after seeding

Pick Software lifecycle in the starter-pack picker, or run:

ok seed --pack software-lifecycle

By default the pack nests everything under a project-docs/ subfolder:

your-project/
└── project-docs/
    ├── proposals/       0001-feature-name.md …
    ├── decisions/       NNNN-title.md (ADRs)
    ├── specs/           NNN-name/{spec,plan,tasks}.md
    ├── postmortems/     YYYY-MM-DD-name.md
    └── guides/          how-to / onboarding / runbooks

Each folder carries an .ok/frontmatter.yml description the agent reads on every directory listing, plus its templates under .ok/templates/. That description is where the workflow lives — so the agent knows an accepted proposal graduates to decisions/, that ADRs freeze once accepted, and that a new decision superseding an old one links back via Supersedes:.

Seeding also installs a skill

ok seed --pack software-lifecycle installs the Software lifecycle project skill into your agent editors (Claude Code, Cursor, Codex, OpenCode). It's the "how to work here" guidance behind the behaviors below — the status flows, the Supersedes: scanning, the postmortem follow-ups — read automatically, and editable like any other doc. It lands as a real SKILL.md committed to your repo, one per detected editor. See Skills and what OpenKnowledge writes to disk.

What the agent does for you

The pack teaches the agent behaviors you'd otherwise have to remember. They're encoded in the pack skill and run when you prompt the agent — not background automations that fire on a timer.

When	The agent	Why it matters
A new decision lands	Scans existing ADRs touching the same subsystem, surfaces `Supersedes:` candidates before commit	The decision log stays a true chain, not a pile
A proposal sits at `draft` > 14 days	Surfaces it to advance, park, or close	Stale proposals don't silently die
A postmortem is published	Scans action items for guide-shaped follow-ups and stubs a guide pre-filled with the symptom	The fix becomes documented, not just discussed
A new postmortem	Adds a `Related:` block linking prior postmortems in the same subsystem	Recurring incidents become visible

When	Do
Per design change	A proposal in `proposals/`; advance its status as review moves
On acceptance	Graduate to a `decisions/` ADR with a `Supersedes:` chain where relevant
Per implementation	A `specs/NNN-name/` folder derived from the decision
Per incident	A blameless postmortem; let the agent link related ones and stub follow-up guides
Monthly	Ask the agent to surface stale `draft` proposals and guides past their `last_verified` date

Software lifecycle

The flow

The scenario

What's in your project after seeding

What the agent does for you

Step by step

1. Seed the pack

2. Write the first proposal

3. Graduate it to a decision

4. Derive the spec

5. Write postmortems as incidents happen

Cadence

Further reading

On this page