sdlc

sdlc

Turn a ticket into reviewed, merged code without giving an agent control of the gates.

sdlc packages an agent-driven software development workflow as agent skills. It uses Beads for coordination, gives each plan its own branch — or its own Git worktree when the plan asks for one — and saves the evidence from every review. A person must approve each irreversible step.

Tickets and plans are Markdown files you can inspect and edit. Approvals are tied to committed content hashes, reviews are saved as artifacts, and the current execution state is available through the CLI.

See How sdlc works under the hood for the implementation and recovery model.

How it works

The workflow keeps each kind of information in one place:

Store	What it contains
thoughts/ on main	The canonical ticket, plan, and research text, committed when the plan is approved
Beads	Live issues, dependencies, claims, gates, and notes
One branch per plan, optionally its own worktree	Code changes and saved review artifacts
Epic approval notes	The hash chain that connects approved artifacts to a commit on main

Copies of tickets and plans inside a working tree are snapshots. The canonical text always comes from main. /sdlc-next performs one valid transition at a time and stops at every human gate.

Requirements

• Git for branches, commits, and worktrees. A remote is strongly recommended.
• Beads >= 1.1.0 (bd) for issues, dependencies, atomic claims, gates, worktree safety, and recovery signals.
• Node.js 18 or newer for setup, hashing, snapshots, guards, gates, context packets, and local review.
• An agent that supports skills. sdlc is built for Claude Code, Codex, and Pi; Pi reviewer profiles require a subagent extension that discovers project .pi/agents/ files.

Install

Run setup inside your project and choose an agent target. If you omit the target, setup uses the Claude Code-compatible default.

npx @mlangroman/sdlc setup --claude
npx @mlangroman/sdlc setup --codex
npx @mlangroman/sdlc setup --pi

Setup performs these seven tasks:

1. Initializes Git if needed.
2. Creates thoughts/{tickets,plans,designs,docs,reviews}/, a compact workflow contract, a documentation index, and CLAUDE.md -> AGENTS.md symlinks.
3. Creates a starter root AGENTS.md. An existing root instruction file is preserved unless you pass --force.
4. Installs all ten skills in .agents/skills/ and symlinks the same copies for Claude Code.
5. Installs four read-only reviewer profiles for Claude Code, Codex, or Pi (Pi profiles use the project .pi/agents/ convention supported by pi-subagents).
6. Checks for Beads >= 1.1.0 and the required capabilities, then initializes Beads if needed.
7. Installs or updates .beads/PRIME.md, a small project prime that does not inject memory bodies.

Available flags are --claude (the default), --codex, --pi, --force, --skip-skills, --skip-agents, and --skip-beads. Pass any combination of agent flags to install support for multiple hosts. Pi loads the shared .agents/skills/ directory and the root AGENTS.md; enable project-agent discovery in your Pi subagent extension to use the installed .pi/agents/ reviewers. --skip-beads only skips scaffolding; transitions backed by Beads will not run or report healthy without it.

To install only the skills for another supported agent:

npx skills add MJLang/sdlc
npx skills add MJLang/sdlc --skill sdlc-ticket --skill sdlc-plan

Configure a project

Project settings live in .agents/sdlc.json, a shared, committed JSON file that setup installs from template/sdlc.template.json and never overwrites afterward — not even under --force. Edit it directly, or inspect it first with sdlc config (below).

A minimal configuration:

{
  "$schema": "./sdlc.schema.json",
  "version": 1,
  "targets": [
    { "name": "app", "paths": ["src/**", "test/**"], "gates": ["npm run test:app"], "reviewers": ["backend-code-reviewer"] }
  ],
  "gates": ["npm test"],
  "reviewers": ["backend-code-reviewer"]
}

targets names the parts of the repository where work can land; each target's paths classify changed files into review lanes, its gates add target-specific commands on top of the global gates, and its reviewers picks which bundled profiles review it. See docs/configuration.md for the full key reference — type, default, and a working example for every setting, including productDocs, frontendConstraints, beads.mode, beads.mergeSlot, and the reserved models tier/effort policy block.

Machine-scoped overrides

.agents/sdlc.local.json is an optional overlay for settings that vary by machine, not by project. sdlc setup git-ignores it automatically, and it may declare only four top-level keys: $schema, version, local, and models. Every other top-level key is refused by name.

{
  "version": 1,
  "local": {
    "reviewEditor": "code {worktree}",
    "preview": { "command": "npm run dev -- --port {port}", "url": "http://localhost:{port}" }
  }
}

That boundary exists because it is the committed file, not this one, that decides what a change must satisfy before it lands — the gates that must pass, the targets and reviewers it must go through, whether a merge slot is required. .agents/sdlc.local.json is git-ignored, so nothing in it is ever reviewed or reaches main; if it could weaken any of that, an ignored file could quietly disarm the pipeline's own gates. The four keys it may set are genuinely per-machine — an editor command, a local preview URL, a model tier or effort a developer wants to try. The boundary itself is derived from each key's localOverridable flag in the schema, not a hand-maintained list, so it cannot silently drift out of step as keys are added.

Editor validation and inspection

sdlc setup installs two generated JSON Schemas into .agents/: sdlc.schema.json for .agents/sdlc.json, and sdlc.local.schema.json for the overlay. Point an editor at one with the file's $schema key, as in the examples above, to catch a malformed configuration offline before you run anything.

Run sdlc config to print every effective setting and the file that produced it — .agents/sdlc.json, .agents/sdlc.local.json, or default. Narrow to one value with sdlc config --field <dotted.path>, for example sdlc config --field local.reviewEditor.

Add product and vision documents to thoughts/docs/INDEX.md. Ticket and plan creation reads the overview and rows that match the current targets or tags. It opens more documents only when the indexed material leaves an ambiguity.

Run the pipeline

1. Write a ticket

/sdlc-ticket Add CSV export with filter validation

This creates thoughts/tickets/{NNN}-*.md with a summary, scope, and stable acceptance criteria such as AC-001 and AC-002. New tickets have Status: draft.

2. Approve the ticket by hand

Read the ticket, then change Status: draft to Status: approved. That deliberate edit is the first human gate.

3. Write the plan

/sdlc-plan 024

The planner researches the repository. When the work has material unknowns, it may start up to three isolated, read-only research tracks. It then writes thoughts/plans/024-*.md. Each numbered step has Covers:, Files:, Depends on:, and Parallelizable: fields. The plan also includes Current-State Findings and an Approval Attention section for risky operations. Its Verification section maps every acceptance criterion to an exercise.

The bundled plan-reviewer runs one critique. If the planner fixes a blocker, the reviewer may run one more check limited to that correction. The plan then stops at Status: review.

4. Approve the plan

/sdlc-approve 024

Approval creates a Beads epic and its dependent step issues. It commits the ticket, plan, and research synthesis to main, then records their approval hash chain on the epic. If you edit an approved artifact, implementation stops until /sdlc-approve 024 records the amendment.

5. Implement the plan

/sdlc-implement 024

Implementation first runs the compact implement guard. It claims the epic with an identity unique to the current session, checks out the plan branch in the primary checkout — or creates a Beads-managed worktree when the plan declares Isolation: worktree — and works through dependency-ordered step packets. Each step returns a fixed handoff, runs sdlc gates, and commits and pushes before its issue closes.

When the steps are done, sdlc builds review packets for each lane and includes a complete list of changed files. Blocking questions become Beads gates for a person to resolve. /sdlc-implement never merges the work.

6. Inspect the work locally

This step is optional.

/sdlc-review 024

You can also run sdlc review 024 in a terminal with --editor, --artifact, --diff, or --preview. The command locates the worktree, canonical ticket and plan, diff, review artifact, and doctor summary. It is read-only and does not record approval.

7. Land the change

/sdlc-land 024

Landing checks the reviewed code SHA and the identity of the approved plan. It squash-merges the work into main, audits and promotes project memory from the merged result, closes the epic, and removes the worktree and branch. Landing is the final human gate.

Small changes

/sdlc-chore fix the typo in the export header skips the plan. In one human-invoked pass, it creates a ticket, opens a worktree, runs the gates and review, then merges under the same safety and review contracts.

Discovery work

Use Type: discovery for feasibility spikes, compatibility studies, performance limits, and architectural assumptions. Discovery follows the normal approved ticket -> plan -> approve -> implement -> review -> land lifecycle; it is not a larger chore. Its plan records a Discovery Protocol, and implementation retains thoughts/designs/{NNN}-discovery.md with the approved identities, experiment evidence, cleanup, and either a validated or invalidated decision. Both can complete the discovery; a replacement implementation still needs its own approved ticket and plan.

Autonomous progress

/sdlc-next reads one compact, deterministic sdlc snapshot. It performs the first selected transition, preferring implementation over planning, or reports that the queue is idle. An idle run starts no subagent and gathers no more facts. You can pair /sdlc-next with your agent's loop feature to keep work moving, but it can never approve, land, or cancel anything.

Status and recovery

/sdlc-queue is a read-only dashboard for work that needs a person, work in progress, and stale or drifted state. It includes the exact recovery command for each problem. Use /sdlc-cancel 024 to cancel a line of work or /sdlc-cancel 024 plan to discard the plan and plan the same ticket again.

Core rules

• Tickets explain what to build and why. Plans explain how to build it. Stable acceptance criterion IDs connect the ticket to plan steps and final verification.
• Supported types are feature, bug, refactor, chore, and planned discovery. Only the deliberately bounded chore lane has no plan.
• People control the gates. Ticket approval requires a deliberate edit, and /sdlc-ticket, /sdlc-approve, /sdlc-land, /sdlc-chore, and /sdlc-cancel never run autonomously.
• Frontmatter records gates; Beads records current activity. Artifacts do not have an in progress status.
• Ticket and plan text on main is canonical. Worktree copies are snapshots, and implementers and reviewers receive absolute canonical paths plus the approved plan hash.
• /sdlc-approve commits the gate artifacts and appends their normalized hashes, along with a reachable main commit, to the epic.
• Every plan uses a separate branch, and its own worktree when it declares Isolation: worktree. Each step is pushed before its issue closes, so a crashed session does not strand unpushed work.
• A saved aggregate review binds the exact code SHA to the approved plan. /sdlc-land rejects review evidence after it becomes stale.
• Implementation stages memory candidates. /sdlc-land promotes only facts that remain true in the merged result.

The full generated project contract is in template/thoughts/AGENTS.md.

CLI reference

sdlc hash <file> [--rev <commit>]

sdlc hash thoughts/plans/024-f-csv-export.md
# sha256=<hex>
sdlc hash thoughts/plans/024-f-csv-export.md --rev a1b2c3d
# sha256=<hex of the blob at that commit>

Every skill and check uses the same hash function. It reads the full file as UTF-8, including frontmatter; converts CRLF and lone CR line endings to LF; and hashes the content with exactly one final newline. The output is lowercase hexadecimal. Shell variants of shasum are not part of this contract.

Add --rev <commit> to hash the canonical text at a specific commit instead of the working copy, so an implementer and a reviewer can prove they read identical bytes at the approved commit. <file> may be given absolute or relative to the current directory; it is resolved against the repository root before the read. The command fails clearly and distinctly when the revision does not resolve to a commit versus when the path does not exist at that revision.

sdlc config [--json] [--field <dotted.path>]

sdlc config
sdlc config --field local.reviewEditor
sdlc config --json

Prints every effective setting resolved from .agents/sdlc.json and .agents/sdlc.local.json, one key=value (source) line per setting, where source names the file that produced it or the literal default. --field narrows the output to one dotted key. --json returns the same resolved shape doctor and guard embed. Exits non-zero with every configuration error when the configuration is invalid, legacy, or missing, and writes nothing.

sdlc doctor <NNN> [--json]

sdlc doctor 024
sdlc doctor 024 --json

doctor is a deterministic, read-only integrity check for one line of work. It verifies the canonical artifacts, hashes, and approval history. It then compares Git with the Beads mappings, dependencies, health, native gates, and worktrees. The report also covers stale claims, orphan signals, the newest review, and merge-slot state when that feature is enabled.

It returns one of these states:

State	Meaning	Exit
ready_for_planning	The approved ticket is valid and has no active plan.	0
ready_for_approval	The plan is structurally valid, has review status, and is waiting for a person.	0
healthy	The approved hash chain agrees with the current execution and review state.	0
reapproval_required	The ticket or plan changed, or no approval record can be reproduced.	2
legacy	The artifact predates the current contract and needs an explicit migration.	2
blocked	A structural or native coordination invariant makes the next transition unsafe.	3

Exit 1 means the invocation is invalid or a required dependency is completely unavailable. People can read the text output; skills use --json. Models never write or save a parallel JSON sidecar.

Beads 1.1 in embedded mode does not implement JSON output for bd doctor. In that mode, sdlc uses guarded context and focused native checks. Server mode runs both the agent and server doctor profiles.

sdlc snapshot --view=next|queue --json

snapshot collects the Beads installation, context, health, and ready work. It records gate dependency edges and worktrees, then checks for stale claims, orphans, cycles, and escalations. It also includes Git corroboration, optional merge-slot state, and one diagnosis for every active artifact. The next view returns ordered candidates, stable rejection codes, and the selected transition. The queue view returns the five dashboard sections. Output is compact JSON with stable keys, and the command is mechanically read-only.

sdlc guard <stage> <NNN>

Valid stages are plan, approve, implement, review, and land. An accepted guard prints one OK line. That line contains only the caller's identity and state fields plus stable warning codes. A refusal prints coded errors and a recovery command while preserving the doctor exit meanings: 2 for drift or legacy data, 3 for a blocker, and 1 for invalid input or an unavailable dependency. Use sdlc doctor --json for the full diagnosis.

sdlc resume <NNN> [--runtime <name>] [--json]

Every session mints a fresh Beads actor, so a plan an earlier session was implementing always looks like a foreign or stale claim to the next one. resume mints a new actor, adopts the plan epic under it, resets any orphaned in_progress child claims to open, and appends exactly one audit note to the epic recording who it adopted from. It requires a clean worktree, nothing unpushed, and no merge slot held by another actor; a refusal reports every failing precondition at once, with the specific dirty paths, unpushed commits, or merge-slot holder, never a bare refusal.

resume deliberately does not resolve gates, clear human escalations, close or reopen issues, touch the merge slot, or touch Git. It only adopts claims — recovering a gated or escalated plan is still a human decision.

sdlc gates [--cwd <worktree>] [--target <target>]

gates runs the configured global commands, followed by commands for the selected target. Add a deliberate one-off command by repeating --command <cmd>; it receives the label ad-hoc. Successful runs print one line with duration and counts. A failure returns a bounded excerpt and the full log path without hiding the failing exit code.

Logs have owner-only permissions. sdlc keeps ten runs, caps each log with a truncation marker, and stores them under the common Git directory. If that location is unavailable, it uses an owner-only, repository-specific temporary directory. If neither location is safe, it refuses to run the commands.

sdlc review-packet <NNN>

review-packet creates one deterministic packet per configured reviewer. Use --reviewer to select one reviewer. The --base, --head, and --json flags control the projection. A packet contains the current ticket intent and acceptance criteria, approved identity, and relevant plan steps. It also contains every changed file, the lane diff, lexical cross-lane interfaces in both directions, the latest gate summary, and earlier findings.

Without Target paths, the model classifies changes. The CLI does not apply a silent heuristic.

sdlc review-artifact

sdlc review-artifact --template 024 --round 1 --head <reviewed-head> > thoughts/reviews/024-round1.md
sdlc review-artifact --validate thoughts/reviews/024-round1.md

A format the CLI validates is a format the CLI should produce. --template emits the aggregate skeleton with every mechanically known value already resolved: title, reviewed code SHA, approved plan SHA-256, approved plan commit, and the reviewer set derived from review-packet. Use --reviewers a,b,c to override that set. It fills nothing else — verdicts, findings, and control-line values are review evidence, so a template never manufactures them.

--validate parses one artifact, checks convergence against the previous round when that file exists next to it, and exits non-zero on failure. It reports every failure with its line number, so one pass repairs the whole artifact instead of one round trip per problem. Add --json for the structured result.

Verdict lines accept a hyphen, en dash, or em dash and normalize to — on write; the dash an agent cannot reliably control never halts a review. Structure stays strict: exactly one verdict line, it must be the final standalone line, and counts must reconcile against the component reports.

sdlc actor <runtime> [--new]

sdlc actor claude --new
# sdlc:claude:<session-id>

actor creates or restores the session identity used for BEADS_ACTOR. Unique actors prevent two agent sessions under the same OS and Git user from sharing a Beads claim. At the root boundary, a skill captures the printed value once and prefixes every mutating Beads command with BEADS_ACTOR="<session-actor>". It does not depend on a shell export surviving or look up the most recent actor.

sdlc review <NNN>

This command opens a local inspection of an implemented plan, as described in step 6. Every optional action requires an explicit flag, and only --preview starts a process.

Reference

Tickets and acceptance traceability

Every ticket has stable acceptance criteria:

## Acceptance Criteria

- AC-001: A user can export the selected records.
- AC-002: Invalid filters use the repository-standard validation response.

Once a plan exists, criterion IDs are never reassigned. Removed criteria stay in the ticket as ~~AC-NNN~~ - removed: <reason>. Each plan step declares Covers: AC-001, AC-002, or Covers: none - <reason> for a purely enabling step. The Verification section maps every active criterion to an exercise.

Doctor rejects missing or unknown coverage unless a person records the same reasoned waiver in both the plan and the epic notes: waiver: id=AC-NNN; reason=....

Reproducible approval

Plans record Source Ticket Hash: sha256=<hex>. After /sdlc-approve commits the gate artifacts, it appends this record to the epic:

approval: plan-sha256=<hex> ticket-sha256=<hex> commit=<main-sha>

The newest reproducible record is authoritative. Its commit must be reachable from main, and its hashes must match the bytes in that commit. Later notes that are malformed or cannot be reproduced produce warnings but never become authoritative.

Adaptive research

Research is a bounded part of /sdlc-plan, not a separate pipeline state. Simple work stays in the planning session. Material unknowns in the repository can become up to three independent, read-only research tracks. Researchers cite file:line, retain disagreements and unanswered questions, report confidence, and do not plan or edit.

At most one summary is saved to thoughts/designs/{NNN}-research.md. It is tied to the ticket hash and a Git baseline. Editing the ticket invalidates all of the research. An unrelated landing invalidates none of it. Only tracks whose cited evidence paths changed need to run again.

Review convergence

sdlc includes backend, frontend, and stack-neutral code reviewers. The configured Target paths determine which reviewers run. Each reviewer receives the diff for its lane, cross-lane interfaces, and a complete changed-file list from the same clean HEAD.

Interface discovery reads the complete contents of changed files in both directions and resolves imports, requires, and includes lexically. Binary, unreadable, and unmatched files remain visible in the inventory without being assigned by a fallback guess. Each reviewer checks the approved plan hash and uses stable IDs scoped to that reviewer, such as MF-backend-001. In later rounds, it verifies old findings before reviewing a fresh packet for the new HEAD.

Reviewers do not need to invent a finding. An approval must instead include Clean-Pass Evidence for the ticket and acceptance criteria, plan conformance, repository conventions, tests and failure paths, and any relevant risk surfaces. An unsupported clean pass is malformed.

Each round saves one aggregate Markdown artifact under thoughts/reviews/. Its ## Overall section contains machine-checked controls, and Verdict: must be its final line:

## Overall

Scope-Check: PASS - unplanned=none
AC-Coverage: PASS - verified=AC-001,AC-002; missing=none
Fix-Disposition: fixed=MF-backend-001; persists=none; new=none

- backend-code-reviewer: APPROVED

Verdict: APPROVED

The skill does not hand-author this format: sdlc review-artifact --template generates the skeleton and --validate checks the filled result. See sdlc review-artifact.

The first round uses Fix-Disposition: N/A. Any code change invalidates earlier approvals. If the number of MUST FIX findings fails to decrease in a round, sdlc saves the artifact, labels the epic human, and stops unattended review. Plans allow at most three rounds and chores allow two. A retry for a malformed artifact at the same HEAD does not consume a round.

Before adding its binding note to the epic, sdlc commits the approved aggregate. The note has the form review: APPROVED sha=... code-sha=... plan-sha256=... plan-commit=... rounds=<n>. /sdlc-land reproduces every identity in that record.

Native Beads safety

sdlc uses specific Beads features without asking Beads to act as another workflow engine:

• A session-specific actor, BEADS_ACTOR=sdlc:<runtime>:<session-id>, prevents concurrent sessions from sharing claims.
• Research, critique, code review, snapshots, /sdlc-queue, /sdlc-review, and doctor use native Beads --readonly enforcement. Prompts are not the security boundary.
• A blocking implementation question creates a dedicated human gate for the step. Resolving the gate does not close unfinished work. The human label remains a separate, non-gating escalation signal.
• sdlc creates, finds, and safely removes worktrees through bd worktree. Dirty files, unpushed commits, and stashes stop normal cleanup.
• Doctor and /sdlc-queue report health, dependency cycles, gates, possible stale claims corroborated by Git activity, and orphaned commits that refer to issues. These are recovery clues, not permission for an autonomous repair.
• Merge slots, which serialize landing, and Dolt server mode are conservative, opt-in settings. bd batch is limited to amendment subsets supported by its transaction grammar and is never presented as atomic across Git and Beads.

Bundled agents

Agent	Job
plan-reviewer	Runs a bounded pre-approval critique with stable PC-NNN findings.
backend-code-reviewer	Checks backend correctness, plan conformance, and repository conventions.
frontend-code-reviewer	Checks the UI and design system, WCAG, responsive behavior, performance, and plan conformance.
general-code-reviewer	Provides a stack-neutral fallback for unmapped lanes.

All four agents are read-only. setup --claude installs Claude Code definitions. setup --codex renders the same bodies as sandboxed, read-only Codex profiles. setup --pi renders Pi Markdown profiles in .pi/agents/ for a project-agent-aware subagent extension such as pi-subagents; the profiles inherit the project instructions and skills. Snapshot collection runs in the CLI, not in an agent. If a required reviewer is missing, the workflow stops.

Tagged project memory

The project prime installed by setup contains workflow pointers but no memory bodies. Each ticket carries two to five stable retrieval tags. Planning searches for exact tag:<tag> markers and recalls only applicable keys. Implementation appends memory-candidate: notes. After the squash merge, /sdlc-land promotes only facts that are still true and records the merge SHA as provenance. Cancelled work never promotes its candidates.

Migrate an existing install to 0.6.0

Version 0.6.0 moves project configuration out of the generated thoughts/AGENTS.md and into .agents/sdlc.json. This is a breaking change to the configuration contract, released as a minor version under this repository's pre-1.0 convention — there is no automated migration, so move the twelve settings in your project's ## Project Configuration section by hand:

1. For each setting, find its new dotted key in the legacy-migration table and write it into .agents/sdlc.json.
2. Delete the entire ## Project Configuration section from thoughts/AGENTS.md, not just its values.
3. Run setup again with your agent target and --force.

Setup, sdlc doctor, and every sdlc guard <stage> refuse to run while that section remains, naming .agents/sdlc.json, the shipped template, and the exact settings they found. That refusal is deliberate: silently ignoring the old section would mean a project's gates, targets, and reviewers stopped being enforced without anyone deciding that on purpose.

Migrate an existing install to 0.5.1

Version 0.5.1 namespaces every pipeline skill with sdlc- to avoid collisions with harness-native commands. Run setup again with the required agent target and --force, then verify and remove stale unprefixed SDLC skill directories such as .agents/skills/plan/ and .claude/skills/plan/. The commands now use /sdlc-ticket, /sdlc-plan, /sdlc-approve, /sdlc-implement, /sdlc-review, /sdlc-land, /sdlc-chore, /sdlc-cancel, /sdlc-next, and /sdlc-queue.

Migrate an existing install to 0.4

Run setup again with the required agent target and --force. This refreshes the compact contracts, skills, reviewer profiles, and managed prime; it never touches .agents/sdlc.json, which installs once and stays out of --force's reach for good. Setup creates the documentation index only when it is missing, so it keeps a project-curated index intact. Configure the ordered gates plus any per-target gates, paths, and reviewers in .agents/sdlc.json (see Configure a project). A project without target paths remains safe, but review packets retain the complete diffs so the model can classify them explicitly.

The old pipeline-snapshot profile is no longer installed. Remove stale copies from .claude/agents/pipeline-snapshot.md and .codex/agents/pipeline-snapshot.toml. /sdlc-next and /sdlc-queue now call sdlc snapshot directly.

Gate logs can contain sensitive test output. sdlc retains ten owner-only, capped runs in Git common state or the documented temporary fallback, never in the worktree.

Setup manages .beads/PRIME.md. If you do not rerun setup, copy template/beads/PRIME.md there so new sessions stop injecting memory bodies. Fill in thoughts/docs/INDEX.md before depending on targeted document reads.

Migrate work from before 0.3.0

The shape of an artifact selects its contract; there is no hidden version file.

• A plan uses the current contract when it has both Source Ticket Hash and a reproducible approval: record. If either is missing, it is legacy.
• Before approval, legacy tickets and plans need acceptance criterion IDs, Covers: fields, the source hash, all required sections, and a critique.
• Approved legacy work with open issues pauses in /sdlc-queue for an explicit /sdlc-approve resync that preserves step and issue IDs.
• Completed legacy work with a valid legacy review can land through the compatibility parser, which prints a prominent warning.
• A legacy claim that shares an identity must be reassigned explicitly. Existing step-level human labels finish through the legacy path.

Migration never invents semantic acceptance coverage or waivers without human review.

Release

Skill frontmatter versions must match package.json. Bump them together:

npm run bump:patch
npm run bump:minor

Repository layout

docs/                   architecture and implementation guides
skills/                 the ten transition skills installed by the skills CLI
template/
  thoughts/AGENTS.md    generated project workflow contract
  AGENTS.root.md        starter root instructions
  beads/PRIME.md        minimal project-specific Beads prime
  agents/               read-only plan and code reviewers
lib/                    config, diagnostics, snapshots, guards, gates, packets, artifacts
bin/sdlc.mjs            setup and public workflow CLI
test/                   unit and fixture-repository integration tests
scripts/                release-version helpers

Acknowledgements

The research -> plan -> implement contracts in this pipeline draw on the RPI loop contributed by Southpaw17 and JeffBNimble. Those ideas include bounded research tracks, hash-bound approvals, plan critique, and review convergence.

License

MIT