Agent skill deep dive

The SDLC Skill

A complete software development lifecycle,
encoded as composable agent skills

/sdlc orchestrator 80+ associated skills 7 pipeline stages 25+ create/review pairs

What is it?

/sdlc is an orchestrator: it runs sub-skills in sequence, each phase consuming the previous phase's output
Enter at any phase, or resume in-progress work with /sdlc continue
Every artifact is a markdown file under .sdlc/, git-versioned and reviewable
Every skill also works standalone (/create-pr, /review-implementation) when you want just one phase

.sdlc/
├── context/
│   ├── project-overview.md
│   ├── use-cases.md
│   ├── goals.md
│   ├── architecture.md
│   ├── schema.dbml
│   ├── conventions.md
│   ├── vocabulary.md
│   └── infrastructure.md
├── features/
│   └── 42-notifications/
│       ├── requirements.md
│       ├── specification.md
│       ├── plan.md
│       ├── tasks/
│       └── review-plan.md
├── knowledge/      # decisions, assumptions
└── templates/      # editable defaults

Six ideas at the core

Create / Review pairing

Every create-* skill has a matching review-* skill that audits it, often in a fresh subagent context.

File-first artifacts

Requirements, specs, plans and findings are traceable files, not chat history. IDs link issue to code.

Gates and backtracking

Phases stop when work is not needed or not feasible. Failures backtrack to the root-cause phase, never silently skip.

Proportionality

Fast paths for small work: a typo fix should not need a specification. When in doubt, include more phases.

Resumable state

A state file and per-feature progress logs mean any session can pick up exactly where the last one stopped.

Measured process

Each skill records one telemetry event, so you can see where your SDLC time actually goes.

The pipeline: 7 stages

1. Issuecreate-issue, review-issue, qualify-issue, triage, prioritize (RICE)

→

2. Needs validationdoes this address a genuine need? (gate: stop if not)

→

3. Requirements + researchrequirements, CLI design, existing solutions, codebase analysis, feasibility (gate)

→

4. Designspec, lifecycle, mockups, telemetry, observability, plan, assumptions, tasks

5–6. Build + testtests, implementation, docs, visual proof, PR: validate / verify / review, CI, merge

→

7. Deploymentdeploy-pr with smoke tests and rollback verification

→

Learningsretrospective: what went well, root causes, actions

Plus parallel flows: setup, project context, bug-fix fast path, cross-cutting records, and maintenance.

Idea 1 · Create / review pairing

25+ pairs: create-plan → review-plan, create-tests → review-tests, and so on
Reviews run in a fresh subagent context for independent judgment
Verdicts: approved (proceed), changes-requested (revision mode), rejected (stop)
Findings persist as review-<artifact>.md beside the artifact, so the verdict survives across sessions and machines
Drift detection can regress an approved review to changes-requested, re-opening the loop

Why it matters

Reviews catch problems while they are still cheap: a contradiction in requirements costs minutes to fix, the same flaw discovered in production costs days. The pairing turns quality from a heroic act into a default step.

Idea 2 · Everything is a traceable file

Feature directory named after its issue: 42-notification-system ← issue #42
Cross-reference IDs: FEAT-42, FR-1, NFR-2, TC-5 link requirements to tests to tasks
No issue yet? A p-prefixed feature (p1-onboarding) marks it as pending, promotable later with /create-placeholder-issue
SDLC_DIR can mirror artifacts outside the repo, keyed by {owner}/{repository}, for forks and third-party code
Local-only state (state.yml, progress.md) is gitignored and never committed

Each artifact carries frontmatter state:

---
issue: "#42"
title: "Notification System"
status: draft
session_link: http://localhost:10000/?session=ses_...
---

Review findings live beside it, with their own verdict and date.

Idea 3 · Gates and backtracking

Gates stop bad work early

Needs gate: not a genuine need? stop, record findings on the issue
Feasibility gate: not viable? stop before design
Plan sign-off: the author approves the draft PR before implementation
Assumption gate: a critical invalidated assumption sends you back to design

Backtracking rules

Return to the nearest phase that owns the root cause (implementation ambiguity → fix the spec, not the issue)
Re-derive downstream: changing an upstream artifact invalidates everything below it
Record why via /create-decision
Never silently skip a failed phase; more than two phases of backtrack depth needs the user

Idea 4 · Proportionality: fast paths

Scenario	Example	Path
Bug fix	Off-by-one in pagination logic	`fix-issue` (reproduce → fix → proof → PR)
Hotfix	Patch a production incident	implementation → PR → merge → deploy
Config change	Toggle a feature flag	implementation → PR → merge → deploy
Dependency update	Bump a library, patch a CVE	implementation → PR → review → merge
Refactor	Rename, extract helper	tests → implementation → PR → review → merge
Docs only	Fix a typo, add an example	documentation → PR → merge

Invariants: always open a PR so CI runs and the change is reviewable, never skip CI before merging, and when in doubt include more phases.

Idea 5 · Resumable by design

state.yml tracks the run: current_phase always holds what comes next, plus the GitHub ref and feature directory
Each feature has a progress.md with a pipeline status table, task progress, and current blocker
Sessions write boundary markers: what was accomplished, where to pick up next
/sdlc continue scans for unfinished features and offers to resume at the recorded re-entry point
The Linked-PR Guard checks for competing PRs before every phase, so parallel work never collides silently

Concurrent-safe

Skills re-read shared .sdlc/ files at each step instead of trusting earlier reads, because other sessions may have changed them. Reviews, statuses, and feature numbering are always checked against current disk state.

Ideas 6 & 7 · Knowledge and measurement

Cross-cutting knowledge records

Assumptions: basis, risk, validation plan (Active → Validated / Invalidated / Deferred)
Decisions: context, alternatives, trade-offs, consequences; /supersede-decision to evolve them
Questions: named answerer, what it blocks, needed-by date
Learnings: structured retrospectives after each feature
Any of these can be captured at any phase

Telemetry on the process itself

Every skill records one event to a local SQLite database (best-effort, never blocking)
summary shows counts per step and average time-to-reach each step
That column is the bottleneck signal: steps that consistently take long to reach are where to investigate
Plain SQLite, so query it directly for custom analysis

The associated skill families

Setup

sync-sdlc, initialize-sdlc-directory, update-sdlc-templates, configure-labels, onboard-repository

Issue intake

create-issue, review-issue, qualify-issue, triage-issues, prioritize-issues, search-existing-issues, check-duplicates

Research

create-requirements, existing-solutions, codebase-analysis, feasibility + review counterparts

Design

specifications, lifecycle, mockups, telemetry, observability, plan, validate-assumptions, tasks

Build + PR

create-tests, create-implementation, validate-implementation, create-pr, validate-pr, verify-pr, review-pr, handle-pr-ci, handle-pr-reviewer-feedback, merge-pr

Bug fixes

fix-issue orchestrator, reproduce-issue (with recorded before/after proof), check-linked-pr

Deploy + learn

deploy-pr, observe-production, create-learnings

Project + maintenance

create-project, create-goals, create-roadmap, create-service-levels, identify-feature-opportunities, audit-sdlc, find-dead-code, find-complexity-hotspots, propagate-changes, sdlc-status

Getting started · Day one

1 · Bootstrap

Run /sdlc setup or /sync-sdlc. It creates the .sdlc/ tree, populates templates, and writes a short SDLC anchor into your AGENTS.md so every future agent session knows where the artifacts live.

2 · Add context

Run /create-project. It interviews you to fill project-overview.md, architecture.md, conventions.md, and more. Context flows into every artifact the pipeline produces afterwards.

3 · Labels

Run /configure-labels once per repository to set up the standard issue label taxonomy the triage skills expect.

Already have a codebase without .sdlc/? /sync-sdlc reconciles the two and reports drift instead of starting from zero.

Getting started · Your first run

Full pipeline: /sdlc issue with a feature idea, then let it walk through create → review → next phase
Start smaller: /sdlc bugfix <issue> runs the fast path: duplicates check, reproduction with a recorded "before" video, fix, comparable "after" proof, PR
Just one phase: invoke skills directly, like /review-implementation or /create-pr, when you want full control
Watch the rhythm: draft, review, address findings, advance. Getting comfortable with that loop is 90% of using the system

# a feature, end to end
/sdlc issue "Add dark mode toggle"

# a bug, the fast way
/sdlc bugfix 57

# resume later, any session
/sdlc continue

# where am I?
/sdlc status

Tips for beginners · Driving the pipeline

Never lose your place

/sdlc status and /sdlc continue are read-only and safe. Use them liberally: they show where you are and resume exactly where the last session stopped.

Do not skip the reviews

The review-* skills are where cheap mistakes get caught. Address the findings before advancing; revision mode exists for exactly that.

Match the path to the work

A typo does not need a specification; a new auth flow does. Fast paths exist precisely so the full pipeline stays affordable for work that needs it.

Trust the gate verdicts

If a needs or feasibility review says stop, stopping early is the feature working, not failing. The findings stay on the issue for when conditions change.

Tips for beginners · Making it yours

Templates are yours

Edit .sdlc/templates/ to match how your team writes. /update-sdlc-templates merges upstream improvements with your changes later.

Record as you go

/create-decision and /create-assumption cost a minute in the moment and save a day of archaeology six months later.

Watch the telemetry

After a few runs, the telemetry summary shows average time-to-reach each step, revealing which phases are worth trimming for your team.

Process as code

The lifecycle is not meetings and ceremony.
It is files, reviews, and gates that any agent, in any session, can pick up.

github.com/tomzx/agents

skills/sdlc/SKILL.md skills/sdlc/references/shared.md /sdlc setup

Navigate: arrows or space · press ESC for the slide overview · append ?print-pdf to the URL for PDF export