SDLC-SPDD Orchestrator

Demo videos: Watch three narrated intro segments on GitHub Pages — SDLC-SPDD overview, install/workflow, and Guide RAG dogfooding.

A multi-assistant scaffold for disciplined AI-assisted delivery.

Project status: turning the corner from MVP to "make it right." We develop this framework through Kent Beck's progression — make it work → make it right → make it fast. Phase one (make it work) is done: it functions end to end today. We are now in make it right — refactoring the existing code and docs for readability, maintainability, and extensibility — before any later make it fast work (performance and prompt optimization). Expect the surface to keep improving. See the ROADMAP and milestone-1.md for the current direction and what is in progress.

We dogfood the framework on itself. This second-phase work is driven through SDLC-SPDD: each improvement is a governed Work ID with its own REASONS Canvas under spdd/canvas/ and requirement under requirements/milestones/ — the same workflow this repo asks target projects to use.

A note on judging the code right now: much of this phase is active refactoring. Reviewing AI-assisted code before the make it right loop is complete is like inspecting wet cement and declaring the building unsafe — let the loop finish before drawing conclusions about a given area.

It is built from three parts that work together:

Part	Answers	Artifacts
Planning	Why the work matters	`ROADMAP.md`, `milestone-*.md`, `requirements/`, `session-notes/`
SPDD	What to build (and what not to)	`spdd/canvas/<WORK-ID>.md` (REASONS Canvas)
SDLC	Who acts when and how sessions hand off	phase commands, session briefs, `agent-context/` memory

How Commands Work

This repo uses two kinds of commands. They run in different places — do not mix them up.

Kind	Looks like	Where you run it
Assistant (AI chat)	`/sdlc-spdd-init`, `/sdlc-spdd-plan @requirements/foo.md`	Cursor Chat, Copilot Chat, or Claude Code in your target project
Shell — install (once)	`./scripts/setup-agent-prompts.sh --target ...`	Terminal in the orchestrator repo clone
Shell — daily use	`./scripts/sdlc-spdd/start-agent-session.sh --target . ...`	Terminal in your installed target project

Install/upgrade/verify from the orchestrator clone use ./scripts/<name>.sh. After install, runtime scripts live in the target at ./scripts/sdlc-spdd/. See Script paths.

/sdlc-spdd-* is not a terminal command. Open your target app in Cursor, Copilot, or Claude Code, open AI chat, then:

Cursor: type /sdlc-spdd-init (or / → pick sdlc-spdd-init)
Copilot: type /sdlc-spdd-init, or #prompt:sdlc-spdd-init if slash commands are missing
Claude Code: type /sdlc-spdd-init (or / → pick sdlc-spdd-init)

Full detail: How to run assistant commands.

The Adoption Path

Five steps take you from install to confident daily use. Follow them in order — each step points to one doc.

flowchart TD
    S1["1 - Install and verify<br/>(~5 min)"]
    S2["2 - Run your first session<br/>hands-on walkthrough"]
    S3["3 - Learn the model<br/>how the 3 parts connect"]
    S4["4 - Work day to day<br/>copy-paste prompts and rhythm"]
    S5["5 - Go deeper<br/>per-part value and prompts"]

    S1 --> S2 --> S3 --> S4 --> S5

    S1 -.-> D1["setup-agent-prompts.sh --all<br/>verify-project-install.sh"]
    S2 -.-> D2["First day with SDLC-SPDD"]
    S3 -.-> D3["Three-part operating path"]
    S4 -.-> D4["Session prompt standard<br/>Daily runbook"]
    S5 -.-> D5["What X brings + SPDD/Planning<br/>prompt standards"]

    classDef step fill:#1f6feb,stroke:#0b3a8a,color:#ffffff;
    classDef doc fill:#eef2f7,stroke:#9aa7b8,color:#1b2733;
    class S1,S2,S3,S4,S5 step;
    class D1,D2,D3,D4,D5 doc;

Step	Do this	Read this
1. Install & verify	From orchestrator clone: `setup-agent-prompts.sh --all` then `verify-project-install.sh`	Installing into your project
2. First session	`/sdlc-spdd-init`, then analysis → plan → architect → code → api-test → review one operation	First day with SDLC-SPDD
3. Learn the model	Understand how Planning, SPDD, and SDLC hand off	Three-part operating path
4. Work day to day	Use the default prompts and the start/capture rhythm	Session prompt standard · Daily runbook
5. Go deeper	Drill into one part when you need it	Value guides · Prompt standards

Add It to Your Project (about 5 minutes)

Run these from this orchestrator repo, pointing --target at your application:

git clone https://github.com/jmjava/sdlc-spdd-orchestrator.git
cd sdlc-spdd-orchestrator

# 1. Install all three parts into your project
./scripts/setup-agent-prompts.sh --target /path/to/your/project --all

# 2. Confirm the install is complete
./scripts/verify-project-install.sh --target /path/to/your/project

Then open the target project in Cursor, Copilot, or Claude Code and run /sdlc-spdd-init in AI chat — see How commands work above.

Next, follow the hands-on walkthrough: First day with SDLC-SPDD.

Start Here (read in order)

These six pages are the canonical onboarding path. The same order appears in docs/README.md.

First day with SDLC-SPDD — hands-on first session
Three-part operating path — how Planning, SPDD, and SDLC work together
10,000-foot view
Installing into your project
Top useful concepts and commands
Maintaining your project

For the full documentation map, see docs/README.md.

Deeper references, one per part:

Part	Value guide (what it brings)	Prompt standard (how to prompt)
Planning	What planning brings	Planning prompt standard
SPDD	What SPDD brings	SPDD prompt standard
SDLC	What SDLC brings	Session prompt standard (default)
All three	Three-part operating path	—

Not sure which prompt standard to use? See Which prompt standard?.

The Operating Model

The system uses a three-layer flow:

Planning: ROADMAP.md, milestone-*.md, requirements/, requirements/milestones/, session-notes/
        -> inform and summarize
spdd/analysis/, spdd/canvas/, agent-context/ (memory indexes, extensions, sessions)
        -> govern and remember
code / spdd/tasks/ / reviews / sync logs
        -> execute and validate

Layer	Purpose	Examples
Planning narrative	Human-readable roadmap, milestone, milestone requirements, and daily session story	`ROADMAP.md`, `milestone-1.md`, `requirements/milestones/`, `session-notes/2026-06-06.md`
Governed agent context	Work-item contract, memory, handoffs, and reusable context	`spdd/analysis/<WORK-ID>-analysis.md`, `spdd/canvas/<WORK-ID>.md`, `agent-context/memory/` (indexes: `domain-index.md`, `context-index.md`, `session-index.md`, `phase-index.md`, `code-areas.md`), `agent-context/extensions/`, `agent-context/sessions/`
Implementation evidence	Code, review outputs, sync logs, and validation	source files, `spdd/tasks/`, `spdd/reviews/`, `spdd/sync/`, tests

Context loading (every session)

Progressive disclosure is enforced through session briefs and indexes — not by loading whole directories.

Tier 1 (automatic) — each assistant injects one small grounding file (.cursor/rules/sdlc-spdd.mdc, .github/copilot-instructions.md, or CLAUDE.md) on every request.
Tier 2 (on demand) — start-agent-session.sh writes agent-context/sessions/current-session.md with a Resolved Context table: phase files from phase-index.md, SDLC Agents extensions, Work ID artifacts, and area-filtered context-index.md rows (via resolve-agent-context.sh).
Paste the Resume Prompt from that brief into chat — load only the files listed under Resolved Context.
Close the loop — capture-session-memory.sh and index-spdd-analysis.sh grow the indexes for the next session.

./scripts/sdlc-spdd/start-agent-session.sh --target . --work-id --phase ./scripts/sdlc-spdd/resolve-agent-context.sh --target . --phase code --work-id # refresh after adding skills ./scripts/sdlc-spdd/resolve-agent-context.sh --target . --text "Implement retry #TDD #java"

Full detail: Context loading and scaling · SDLC Agents and the framework.

Install into an Application

Clone this repo:

git clone https://github.com/jmjava/sdlc-spdd-orchestrator.git
cd sdlc-spdd-orchestrator

Install the complete system into a target project:

./scripts/setup-agent-prompts.sh --target /path/to/your/project --all

This installs:

Cursor commands, GitHub Copilot prompt files, and Claude Code commands.
Always-on operating-model grounding for each assistant: .cursor/rules/sdlc-spdd.mdc, .github/copilot-instructions.md, and CLAUDE.md.
target-local runtime scripts under scripts/sdlc-spdd/.
local SDLC-SPDD docs under docs/sdlc-spdd/.
planning scaffolding: ROADMAP.md, milestone-1.md, and session-notes/ when missing.
SPDD and agent context folders: spdd/ and agent-context/ (including extensions/ for SDLC Agents skills and phase rules, and memory indexes such as phase-index.md).

Upgrade an existing target project without overwriting application source, canvases, feature workspaces, existing memory, roadmap, milestones, or session notes:

./scripts/upgrade-project.sh --target /path/to/your/project --all

Day-One Flow

Below, /sdlc-spdd-* lines run in AI chat (Cursor/Copilot/Claude Code); ./scripts/... lines run in a terminal. Do not paste /sdlc-spdd-* into a shell — see How commands work.

In the target project, open AI chat (Cursor Chat, Copilot Chat, or Claude Code) and run:

/sdlc-spdd-init

If you already have milestone checklist items, map them into SDLC-SPDD work:

./scripts/sdlc-spdd/create-work-from-milestone.sh --target . --milestone milestone-1.md --all

Start or resume an agent session (creates current-session.md with Resolved Context):

./scripts/sdlc-spdd/start-agent-session.sh --target . --work-id FEAT-001-my-feature --phase analysis

Paste the Resume Prompt from agent-context/sessions/current-session.md into AI chat. Load only files listed under Resolved Context in that brief.

Analyze, plan, architect, code, test, and review one operation:

/sdlc-spdd-analysis @requirements/my-feature.md @ROADMAP.md @milestone-1.md
./scripts/sdlc-spdd/index-spdd-analysis.sh --target . --work-id FEAT-001-my-feature
/sdlc-spdd-plan @spdd/analysis/FEAT-001-my-feature-analysis.md
/sdlc-spdd-architect @spdd/canvas/FEAT-001-my-feature.md
/sdlc-spdd-code @spdd/canvas/FEAT-001-my-feature.md operation T01
/sdlc-spdd-api-test @spdd/canvas/FEAT-001-my-feature.md
/sdlc-spdd-review @spdd/canvas/FEAT-001-my-feature.md

Verify deterministic side-effects after each command (best-effort command invocation evidence):

./scripts/sdlc-spdd/verify-agent-command-effects.sh --target . --work-id FEAT-001-my-feature --step plan
./scripts/sdlc-spdd/verify-agent-command-effects.sh --target . --work-id FEAT-001-my-feature --step architect
./scripts/sdlc-spdd/verify-agent-command-effects.sh --target . --work-id FEAT-001-my-feature --step code --operation T01
./scripts/sdlc-spdd/verify-agent-command-effects.sh --target . --work-id FEAT-001-my-feature --step review

Capture session memory and milestone progress:

./scripts/sdlc-spdd/capture-session-memory.sh \
  --target . \
  --work-id FEAT-001-my-feature \
  --phase code \
  --summary "Completed T01" \
  --validation "tests passed" \
  --milestone milestone-1.md \
  --roadmap-note "FEAT-001 completed first implementation operation." \
  --next "/sdlc-spdd-review @spdd/canvas/FEAT-001-my-feature.md"

Verify planning sync was captured (session-notes + milestone, optionally roadmap):

./scripts/sdlc-spdd/verify-agent-command-effects.sh --target . --work-id FEAT-001-my-feature --step capture --milestone milestone-1.md --require-roadmap

Milestone/session-notes sync is a required part of the flow, not a temporary check.

Refresh the roadmap summary from SPDD canvases:

./scripts/sdlc-spdd/sync-roadmap-from-spdd.sh --target .

Core Assistant Commands

/sdlc-spdd-* commands run in AI chat (Cursor/Copilot/Claude Code), not a terminal — see How commands work and How to run assistant commands.

Command	Use it for
`/sdlc-spdd-init`	Initialize project context
`/sdlc-spdd-analysis`	Fowler Step 3: domain keywords, scoped code scan, analysis artifact
`/sdlc-spdd-plan`	Create REASONS Canvas from accepted analysis
`/sdlc-spdd-architect`	Harden the canvas before coding
`/sdlc-spdd-code`	Implement one approved operation
`/sdlc-spdd-api-test`	Generate cURL API test script (Fowler Step 5 verification)
`/sdlc-spdd-review`	Compare implementation to the canvas
`/sdlc-spdd-prompt-update`	Update the canvas first when behavior or acceptance criteria change
`/sdlc-spdd-retro`	Capture reusable learnings
`/sdlc-spdd-sync`	Reconcile accepted implementation drift back into prompt artifacts

Core Scripts

Script	Use it for
`scripts/setup-agent-prompts.sh`	Install the framework into a target project
`scripts/upgrade-project.sh`	Upgrade framework-owned files in an existing target project
`scripts/sdlc-spdd/start-agent-session.sh`	Create `current-session.md` with Resolved Context and a progressive-disclosure Resume Prompt
`scripts/sdlc-spdd/resync-agent-session.sh`	Check or reconcile feature/canonical canvas drift
`scripts/sdlc-spdd/capture-session-memory.sh`	Persist session summary, validation, decisions, pitfalls, patterns, and next steps
`scripts/sdlc-spdd/index-spdd-analysis.sh`	Index analysis domain keywords and code areas into `domain-index.md` and `context-index.md`
`scripts/sdlc-spdd/resolve-agent-context.sh`	Resolve phase files (`phase-index.md`), `#SkillName` skills, extensions, and area-filtered index rows
`scripts/sdlc-spdd/create-work-from-milestone.sh`	Map milestone checklist items to Work IDs, requirements, feature workspaces, and draft canvases
`scripts/sdlc-spdd/sync-roadmap-from-spdd.sh`	Refresh a managed roadmap summary from SPDD canvas metadata
`scripts/sdlc-spdd/summarize-session-notes.sh`	Import existing daily session notes into durable memory

Repository Layout

Path	Purpose
`docs/`	User guides, onboarding path, runbooks, and reference docs
`scripts/`	Install, upgrade, validation, and target-local runtime script templates
`templates/`	REASONS Canvas templates, Cursor commands, Copilot prompts, Claude Code commands, stack rules, project-doc templates
`agent-context/`	Memory, playbooks, harness files, and framework-owned context templates
`examples/`	Reference workflows and sample projects

Documentation Paths

New users should follow Start Here above. The lists below group the remaining docs by task.

Daily operation

Setup and upgrade

What each part brings

Deep theory (read later)

Read these after the value guides above. They explain historical context, compliance, and architecture — not first steps.

Jira runbook
Integration linking
Hybrid SDLC Agents + SPDD model
SPDD compliance
Architecture
Context loading, indexing, and bootstrap — tiers, bootstrap and index-based loading, scaling
SDLC Agents and the framework — progressive disclosure, #SkillName, extensions, and resolve script
Design decisions

What This Is Not

This is not a compiled multi-agent runtime and not a replacement for Cursor, GitHub Copilot, Claude Code, Jira, SDLC Agents, or OpenSPDD.

It is a repository-based operating model that makes AI-assisted work more governable, reviewable, and reusable.

License

MIT

Attribution

This project is inspired by:

SDLC Agents: multi-agent software delivery lifecycle
OpenSPDD: structured prompt-driven development and REASONS Canvas style design contracts

This project is not an official extension of either project unless that relationship is established later.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

SDLC-SPDD Orchestrator

How Commands Work

The Adoption Path

Add It to Your Project (about 5 minutes)

Start Here (read in order)

The Operating Model

Context loading (every session)

Install into an Application

Day-One Flow

Core Assistant Commands

Core Scripts

Repository Layout

Documentation Paths

Daily operation

Setup and upgrade

What each part brings

Deep theory (read later)

What This Is Not

License

Attribution

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 66 Commits
.github		.github
agent-context		agent-context
docs		docs
examples		examples
requirements/milestones		requirements/milestones
scripts		scripts
spdd		spdd
templates		templates
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
ROADMAP.md		ROADMAP.md
STARTER-SPEC.md		STARTER-SPEC.md
TESTING.md		TESTING.md
milestone-1.md		milestone-1.md

Folders and files

Latest commit

History

Repository files navigation

SDLC-SPDD Orchestrator

How Commands Work

The Adoption Path

Add It to Your Project (about 5 minutes)

Start Here (read in order)

The Operating Model

Context loading (every session)

Install into an Application

Day-One Flow

Core Assistant Commands

Core Scripts

Repository Layout

Documentation Paths

Daily operation

Setup and upgrade

What each part brings

Deep theory (read later)

What This Is Not

License

Attribution

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages