Handbook
Software development lifecycle
SDLC (software development lifecycle) here means the generic delivery flow this page describes and which documentation to update at each step. It pairs with Documentation structure — proposal (where files live, including…
Delivery phases (reader-facing): Discover / Prioritize → Specify → Design → Build → Verify → Release. These names match ordinary software-delivery language. Letters A–F are optional internal shorthand (still used in methodology bridges, examples, and cross-maps)—they are not the primary vocabulary on this page.
PDLC (product lifecycle): This SDLC covers how to build the product right — from discovery and prioritization through specification, implementation, verification, and release. The Product Development Life Cycle (Product development lifecycle (PDLC)) covers building the right product — problem discovery, solution validation, planning and commitment, go-to-market, growth, and sunset. The named SDLC phases above sit inside the PDLC as the Build & Release engine. See PDLC ↔ SDLC bridge for phase alignment, artifact handoffs, role mapping, and a worked example.
Forge (delivery methodology): when using Forge on this SDLC foundation — connection to phases, tracking spine, and ceremony intents — see Forge — connection to the SDLC foundation and Forge — major processes & flow maps.
Methodology depth (Scrum, Kanban, XP, phased, Lean, Spiral, V-Model, DevOps, SAFe, FDD, Crystal, DSDM, Shape Up, DA, BDD, RAD, Agile, agentic SDLC): see Methodology guides (blueprint) — full guides with external links and adoption notes.
Ceremonies (foundation vs forks): methodology-neutral intent types (why recurring collaboration exists) and per-methodology mappings — Ceremonies — blueprint package.
Bridge (intents ↔ Scrum / Kanban / phased / XP names): Methodology bridge — foundation intents ↔ named ceremonies — matrix, blend suggestions, calendar mapping.
Discipline bridges: Cross-cutting disciplines each have a bridge mapping their practices to SDLC phases (A–F shorthand) and PDLC P1–P6 — see BRIDGES.md for the full index, or jump to a specific discipline: BA · PM · Testing · Architecture · DevOps · Big Data · Data Science.
Path examples below use a common docs/ layout; adjust names if your tree differs.
1. Roles (can be one person)
| Role | Responsibility |
|---|---|
| Owner | Prioritizes work breakdown / backlog; accepts epic or story done. |
| Implementer | Implements work items; updates specs, backlog, and traceability as agreed below. |
Deeper (methodology-neutral): delivery archetypes (demand, build, flow, assurance, governance), how Scrum / Kanban / phased / XP map titles onto them, and how that relates to Contributor in engineering tracking — see Roles, archetypes & methodology titles.
2. Phases & documentation obligations
Ceremony intents vs phases (C1–C6)
Recurring collaboration (ceremonies) should cover the six intent types over time: C1 Align, C2 Commit, C3 Sync, C4 Inspect, C5 Improve, C6 Assure/release — see Ceremony foundation (methodology-neutral). They do not replace the artifact tables below; they explain why teams hold planning, reviews, and gates.
| Phase | Shorthand | Intents most engaged (typical) | Illustrative ceremony pressure | Detail |
|---|---|---|---|---|
| Discover / Prioritize | (A) | C1, C2 | Prioritization, roadmap/backlog sessions | Discover / Prioritize |
| Specify | (B) | C1, C6 (readiness) | Refinement, “definition of ready,” risk triage | Specify |
| Design (lightweight) | (C) | C1, C6 | Design review, NFR alignment | Design (lightweight) |
| Build | (D) | C2, C3, C6 (ongoing) | Pull/commit selection, standups, CI as assurance | Build |
| Verify | (E) | C3, C4, C6 | Test progress sync, stakeholder demo, quality gates | Verify |
| Release | (F) | C4, C6 | Go/no-go, release approval, post-release learnings → C5 | Release |
Methodology mapping: the same intents appear as Sprint Planning, replenishment, tollgates, planning game, etc. — Methodology bridge — foundation intents ↔ named ceremonies.
Discover / Prioritize
Activities: Ideas, rough sizing, ordering.
Artifacts (typical)
| Artifact | Action |
|---|---|
| Planning source of truth | One place for prioritized work (WBS/CSV, backlog, board, or optional high-level docs/ROADMAP.md from Roadmap — {project name}). Record where it lives in docs/PROJECT.md or root README.md. |
| Work breakdown (WBS) | e.g. docs/requirements/WBS.csv — new epics/stories or statuses such as draft / backlog. |
| Spec files under your milestone tree | Optional until you commit to build. |
Exit: A backlog item is ready to specify when it has a clear outcome and a home in the WBS (or equivalent).
Specify
Activities: Acceptance criteria, edge cases, dependencies, risks.
Artifacts (typical)
| Artifact | Action |
|---|---|
| Story (or feature) spec | status: ready when acceptance criteria are agreed. |
| Risk register | e.g. docs/requirements/risks/register.csv — add or update rows when scope changes risk. |
| Themes / tags matrix | e.g. docs/requirements/traceability/themes-matrix.csv if you use themes. |
Exit: Story (or equivalent) is ready; implementation tasks can be split.
Design (lightweight)
Activities: Enough design to implement without rework; record durable decisions only when useful.
Artifacts (typical)
| Artifact | When |
|---|---|
| Epic/story body | Sketches, interfaces, UX notes in the same spec. |
| ADRs | e.g. docs/adr/ — when a choice is hard to reverse or affects multiple modules. |
| Architecture notes | e.g. docs/architecture/ when subsystems or data flow need a shared picture. |
Exit: No blocking unknown for this scope remains undocumented.
Build
Activities: Implementation, tests, local verification.
Artifacts (typical)
| Artifact | Action |
|---|---|
| Task-level notes | Link requirement or task IDs in commits or PR descriptions when useful. |
| WBS / backlog | Set items to in_progress when work starts. |
| API / public surface | Language-appropriate doc comments (e.g. KDoc, Javadoc, Rustdoc, docstrings). |
| CI pipeline config | e.g. .github/workflows/, GitLab CI, Jenkinsfile — lives in-repo; document what runs and merge/release gates in docs/development/ (or equivalent). See §7. |
| Optional agents & automation | When blueprints/agents/ is adopted: container recipes (e.g. browser/E2E) in agents/; document image build and recipe steps beside other CI gates. Broader agentic practices: Agentic SDLC (cross-cutting); coding and AI review standards: Agentic coding standards (cross-cutting). See Documentation structure — proposal and the agents blueprint. |
| Test plan (lightweight) | For non-trivial scope: outline scope, levels (unit/integration/e2e/manual), and exit criteria — story spec, docs/testing/, or Test plan — [scope]. |
Exit: Acceptance criteria met; tests added or skip justified in the story/PR.
Verify
Activities: Automated tests, manual checks, regression of related behavior.
Artifacts (typical)
| Artifact | Action |
|---|---|
| Tests ↔ requirements | e.g. docs/requirements/traceability/tests-matrix.csv, or inline references in tests. |
| Quality gates (CI) | Pipeline must pass agreed checks (build, lint/static analysis, tests) before merge or release — documented in docs/development/ (see §7). |
| Story spec | status: done when verified. |
Exit: Story done; backlog row matches reality; CI reflects the same bar as local verification unless a temporary exception is recorded (story/PR).
Release
Activities: Versioning, packaging, distribution, compliance checks.
Artifacts (typical)
| Artifact | Action |
|---|---|
docs/release/ (or equivalent) |
Checklists, privacy / compliance links, signing notes (no secrets in repo). |
Root README.md |
User-visible features if changed. |
| Planning / milestone status | Updated to reflect what shipped (wherever you track it). |
| Release CI (optional) | Tag/build pipelines, store upload, or signing orchestration — secrets in CI vault, not in Git; document process in docs/release/ or docs/development/. |
Exit: Artifact published to the intended distribution channel (app store, registry, fleet, etc.); status docs updated.
After release: operations, PDLC, and new Ore
Operations, maintenance, growth, maturity, and sunset are not a seventh SDLC phase. They belong to the product lifecycle: especially PDLC P5 (Grow) and P6 (Mature / Sunset) in Product development lifecycle (PDLC). Signal from production, customers, and the business feeds continuous discovery and prioritization; in Forge terms, new demand and learning typically re-enter as Ore (see Forge — connection to the SDLC foundation and Forge ↔ SDLC ↔ PDLC bridge). For the full PDLC ↔ SDLC map, see PDLC ↔ SDLC bridge.
3. Definition of Done (story or equivalent)
A story is done when:
- Acceptance criteria in the spec are met (or explicitly waived with reason).
- The canonical backlog (e.g. WBS) marks the story
done. - Tests: New logic has automated coverage or a documented exception.
- CI: Required pipeline checks pass for the merged change (or a documented waiver by Owner).
- Risks: Risk register updated if mitigation shipped or risk closed.
- User-facing changes: Product README or UI copy reviewed if applicable.
4. Definition of Done (epic or equivalent)
An epic is done when all in-scope child stories are done, your planning view reflects completion, and residual risks are accepted or closed.
5. Change control
- Requirement IDs (if used) stay stable once referenced in code, tests, or ADRs; deprecate with a note rather than silent renumbering.
- Scope management: Scope changes show up in the backlog/WBS (or equivalent)—prefer explicit new stories/tasks over hidden scope. Descoping is explicit (cancelled/deferred); epics close when in-scope children are done. Risks update when scope shifts materially.
- Time and effort: Git activity shows when work touched the repo, not duration or billable hours. Explicit time (if needed) lives in a tracker or agreed in-repo log — see project
sdlc/TRACKING-FOUNDATION.mdwhen present. - ADRs: Prefer supersede with a new ADR over deleting history.
See the change management process for diagram, tables, and links to tracking docs.
6. Review cadence (suggested)
| Cadence | Activity |
|---|---|
| Per change request / PR | Touch backlog/specs when scope or status changes. |
| Weekly / end of milestone | Planning/backlog accuracy, open risks, README freshness. |
| Before major release | Release checklist, privacy/compliance docs, signing process (documented, not secret values). |
7. CI/CD, quality gates, and test plans
CI/CD means continuous integration (build + checks on every push/PR) and, when you adopt it, continuous delivery or deployment (automation toward release).
Testing depth: Testing & quality assurance is the cross-cutting testing knowledge base — test levels and types, test design techniques, modern strategies (shift-left, TDD, BDD, contract testing, AI-augmented), and the test automation frameworks landscape. Reference it when choosing what to test and which tools to use; this section covers where testing fits in the pipeline.
| Concept | What to capture |
|---|---|
| Pipeline | Where it lives (e.g. .github/workflows/), which branches trigger it. |
| Quality gates | Mandatory steps: e.g. compile, lint/static analysis, unit tests, dependency/license scan — document the list so “green” matches team expectations. |
| Test plan | For meaningful scope: what to test (levels, environments), who runs manual/exploratory checks, and done criteria — use a story spec section or Test plan — [scope]. |
| Traceability | Keep tests ↔ requirements links in your traceability matrix or in code as your project prefers. |
| Optional automation images | If blueprints/agents/ is present: same recipe should pass locally (container) and in CI unless waiver is documented. |
Merge policy (suggested): No merge to the main branch while required CI checks are failing, unless Owner explicitly accepts risk and a waiver is noted in the PR or story.
Release policy (suggested): No release artifact from automation until the same (or stricter) gates pass on the release commit/tag; add release-only checks (e.g. ProGuard, signing) as the product matures.
Where to write details: docs/development/ (or your dev guide) — not in blueprints/sdlc/ except this generic section.
Keep product-specific context in docs/PROJECT.md (or equivalent), not in this file.