Product Development Lifecycle agentic delivery system

The PDLC track repository for Advanced SDLC and harness engineering. Four groups build one system here across four weekly modules, and the track submits one integrated group pull request per group per week.

This repository is not the help portal product. It is the delivery system that produces the PDLC lifecycle artifact for the help portal.

Start with STUDENT-GUIDE.md. It carries the setup, the map, the lifecycle commands, a worked change, and what each week must deliver. This README is the reference for the layout and the invariants.

Setup

./scripts/setup.sh
make verify PYTHON=.venv/bin/python

setup.sh creates .venv and installs the shell's dependencies plus any domain package this track carries. It prefers uv when present and falls back to the stdlib venv module.

make verify must pass on a clean clone. If it does not, that is a bug in the track baseline and belongs to the teaching team rather than to the group.

Layout

.claude/settings.json        project-scoped permissions
.claude-plugin/plugin.json   plugin manifest
skills/                      named lifecycle procedures
agents/                      specialist reviewers
hooks/hooks.json             where deterministic interception is wired
scripts/                     deterministic helpers, standard library only
scripts/hooks/               hook implementations
mcp/                         tool servers, and the simulated external services
state/                       the state model and the append-only lifecycle log
scenarios/visible/           cases the track can run
scenarios/heldout/           supplied in Module 4, refused by the guard until then
tests/                       the repository's own checks
docs/                        the track's rules, policies, and identifier schemes
fixtures/                    the track's seed material
evidence/<item>/             what each state transition recorded

The rules that cannot be changed

Three, and each has a test that fails if it is removed.

1. State moves through the CLI. scripts/lifecycle.py is the only writer of state/lifecycle.jsonl. scripts/hooks/guard_paths.py refuses anything else. Regression: tests/test_guard_paths.py.
2. The state model keeps its failure states. A lifecycle with only a happy path is the failure this course studies. Regression: tests/test_state_model.py.
3. Held-out cases stay held out. scenarios/heldout/ is denied in settings and refused by the guard, before it exists. Regression: tests/test_scenarios.py.

Everything else is open: skills, agents, tools, additional hooks, additional states, the track's domain checks, and any scenario added to it.

Working rhythm

Module	Shared capability	What lands here
1	Lifecycle and state	The track's real lifecycle, its artifacts, transitions, and failure states
2	Harness architecture	A context contract, two safe tools, permissions, one interception point, one induced failure
3	Meta-harness controls	One prose rule turned into an executable control with a regression case
4	Verification and operation	An evaluation set, ordered checks, held-out failure analysis, operating measures

Before implementing the group's lens, model the whole capability. The lens is the part to go deeper on, not the part to do instead.

Recording work

python3 scripts/lifecycle.py advance --item <ID> --to context \
  --evidence evidence/<ID>/context-manifest.md --actor agent --note "why"
python3 scripts/lifecycle.py show --item <ID>
make verify

A pull request that claims a transition the log does not contain will be returned.