software-lifecycle — Claude Code skill: proposals, decisions, specs
software-lifecycle gives a project a fixed shape for its docs: proposals, decisions, specs, postmortems and guides. The skill carries the status flows and per-folder rules.
MIT 245 installs ★ 17 updated 2026-10-21
npx skills add inkeep/open-knowledge-skills --skill software-lifecycle -a claude-codeWhat software-lifecycle does
The skill gives a project a fixed shape for its docs: proposals lead to decisions, decisions to specs, and incidents to postmortems, with guides/ holding the how-tos. Status values and per-folder rules sit here instead of inside the templates. Templates keep structure only, headings plus frontmatter.
Some of the work is proactive. A proposal stuck at status: draft for more than 14 days gets surfaced so its author can advance or close it. When a new decision lands, the agent looks for nearby records it might supersede and suggests Supersedes: links before the commit. Published postmortems get a Related: block pointing at earlier write-ups of the same subsystem. Guides carry last_verified, so old ones show up in periodic review, and a postmortem's action items can seed a guide stub with the symptom and timeline already in place.
Five authoring flows ship as separate skills: /frame-a-proposal, /write-a-spec, /record-a-decision, /write-a-postmortem, /review-a-design. This one is the map, and it needs the OpenKnowledge MCP server configured: install it into a project with ok seed --pack software-lifecycle, or ok-beta on Beta. It layers on the platform /open-knowledge skill rather than replacing it.
What it helps with
- sort proposals, decisions and specs into the right folders
- move a draft proposal through its status flow
- spot the older decision a new one supersedes
- write a blameless postmortem after an incident
- turn postmortem action items into a guide stub
Example prompts for the agent
- How are docs organized in this project — proposals, decisions, specs?
- My proposal is still
status: draft. What are the next status steps? - Scan
decisions/for records this new decision should supersede.
How to install software-lifecycle
1Skills CLI (Vercel)
npx skills add inkeep/open-knowledge-skills --skill software-lifecycle -a claude-code2Manually: put the files in place
~/.claude/skills/software-lifecycle/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/software-lifecycle/
1Skills CLI (Vercel)
npx skills add inkeep/open-knowledge-skills --skill software-lifecycle -a codex2Manually: put the files in place
.agents/skills/software-lifecycle/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add inkeep/open-knowledge-skills --skill software-lifecycle -a cursor2Manually: put the files in place
.cursor/skills/software-lifecycle/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install inkeep/open-knowledge-skills skills/starter-packs/software-lifecycle/software-lifecycle2Manually: put the files in place
.github/skills/software-lifecycle/SKILL.md1Skills CLI (Vercel)
npx skills add inkeep/open-knowledge-skills --skill software-lifecycle -a gemini-cli2Platform CLI
gemini skills install https://github.com/inkeep/open-knowledge-skills --path skills/starter-packs/software-lifecycle/software-lifecycleManually: put the files in place
.devin/skills/software-lifecycle/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add inkeep/open-knowledge-skills --skill software-lifecycle -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about software-lifecycle
How do I install software-lifecycle in Claude Code?
Run npx skills add inkeep/open-knowledge-skills --skill software-lifecycle -a claude-code. The skill file lands at ~/.claude/skills/software-lifecycle/SKILL.md.
What does software-lifecycle do?
It documents the doc lifecycle: status values for proposals/, decisions/, specs/ and postmortems/, what the agent does in each folder, and how to create documents from templates.
What does it need to run?
An agent host with the OpenKnowledge MCP server configured, plus a project seeded with ok seed --pack software-lifecycle. It works alongside the platform /open-knowledge skill, not in place of it.
Source text
SKILL.md · MIT
---
name: software-lifecycle
description: "How to work in a Software Lifecycle project (the `software-lifecycle` starter pack): proposals → decisions → specs → postmortems, plus guides. Read when the project has these folders, or when asked how this project is organized. Carries the doc lifecycle, status flows, and per-folder agent behaviors so that guidance does not live inside template bodies or folder descriptions. The five workflows — frame a proposal, write a spec, record a decision, write a postmortem, review a design — each ship as their own sibling skill in this pack. Complements the platform `open-knowledge` skill; does not replace it."
compatibility: "Any agent host with the OpenKnowledge MCP server configured. Installed project-local by `ok seed --pack software-lifecycle` (`ok-beta` for Beta)."
metadata:
pack: "software-lifecycle"
author: "Inkeep"
repository: "https://github.com/inkeep/open-knowledge-skills"
---
# 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.
© Inkeep · MIT · inkeep/open-knowledge-skills