Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add inkeep/open-knowledge-skills --skill software-lifecycle -a claude-code
Open on GitHub

What 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-code

2Manually: put the files in place

~/.claude/skills/software-lifecycle/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/software-lifecycle/

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

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set17

The whole set →
review-a-design review-a-design critiques technical proposals, specs, and ADRs for architectural soundness without editing the text. It flags flaws in goals, constraints, and alternatives. CX Codex +1 252installs record-a-decision The record-a-decision skill turns a settled architecture choice into an ADR with its context, alternatives, and consequences. Use it to keep decision history readable. CX Codex +1 252installs frame-a-proposal The frame-a-proposal skill shapes a design request into a reviewable RFC, starting with the problem and beneficiary before moving to options, trade-offs, and open questions. CX Codex +1 248installs write-a-spec write-a-spec turns an accepted proposal into an implementation spec with current-system mapping, decision records, open questions, migration work, and tests. CX Codex +1 247installs write-a-postmortem write-a-postmortem drafts blameless incident reviews in postmortems/ using the Google SRE framework. Focuses on system affordances and evidence instead of personal fault. CX Codex +1 243installs note-taking note-taking guides agents working in a plain notes setup with notes/ and daily/ folders. Helps capture ideas quickly and connect pages with cross-links. CX Codex +1 179installs personal-crm This skill organizes people, company, meeting, and concept notes into a linked Markdown vault. Use it when an agent needs to maintain a personal CRM. CX Codex +1 126installs writing-workflow writing-workflow — a skill for Claude Code and Codex that structures writing into ideas, drafts, and published stages. Triggers when capturing a note, revising prose, or shipping a piece. CX Codex +1 102installs

Project sponsors

Companies that keep this analytics open