Skip to content
BranchesTags

Repository files navigation

SDLC-SPDD Orchestrator

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

Work in progress

SPIKE-001 — Guide as an optional DICE context backend (on main for field confirmation). SPDD markdown (canvases, memory indexes) can be projected into a Neo4j entity graph served by Embabel Guide (jmjava/guide tag sdlc-spdd-projection-v1), so the next run can retrieve context by typed edges (Work ID subgraphs, cross-run lessons per code area) instead of similarity alone. The backend is opt-in per install and resolved at runtime — every command still works on file-based indexes when Guide is absent.

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

Local tools (two GUIs)

These are separate localhost Flask apps. Prefer shell install scripts for production target installs; the ops console is an experimental dogfood UI.

UI Port Start Job
Ops console 5051 ./scripts/sdlc.sh console --target /path/to/app Install/upgrade, SQLite, rollback, Guide+Neo4j lifecycle, launch ADF Viewer
ADF Viewer 5050 ./scripts/sdlc.sh viewer (or console ADF tab) Edit adf/*.adf.json, Jira upload/download

Guide is wired through the console Guide tab and optional slash-command context (guide-dice); the ADF Viewer does not talk to Guide. Full diagram and tabs: docs/ops-console.md.

python3 -m pip install -e './engine[viewer]'
./scripts/sdlc.sh console --target .          # http://127.0.0.1:5051/
./scripts/sdlc.sh viewer --root . --port 5050 # http://127.0.0.1:5050/

Recent highlights

What Why it matters Try it
Ops console + ADF tab (#54, #64) Local UI for install/SQLite/rollback/Guide and viewer start/stop ./scripts/sdlc.sh console
ADF Viewer WYSIWYG + raw ADF editor with explicit Jira sync ./scripts/sdlc.sh viewer · docs/adf-viewer.md
Guide DICE path (#56) Optional typed-graph context behind slash commands docs/guide-flow.md
SDLC pointer / workflow / team registry (#20, #21) Persistent Work ID, phase gates, shared claims ./scripts/sdlc.sh next · /sdlc-spdd-whereami

Pointer and workflow state stay local (.sdlc/pointer, .sdlc/workflows/); team claims live in agent-context/work-registry.tsv and sync through git. Details: agent-context/README.md.

Project status: Milestone 1 make-it-right track is largely complete; make-it-fast measurement landed. We develop this framework through Kent Beck's progression — make it work → make it right → make it fast. Make it work is done. Make it right refactors (shared libs, command-spec generation, extension manifest, analysis Scope Lock, Jira requirements format, milestone subdirs, session-brief archive) are Complete. Make it fast measurement (prompt-optimization ledger + canvas readiness) is Complete; SPIKE-001 (Guide) is on main for field confirmation; SPIKE-002 (local models) remains parked. See the ROADMAP and milestone-1 (root milestone-1.md is a compatibility stub).

We dogfood the framework on itself. Improvements are governed Work IDs with REASONS Canvases under spdd/canvas/ and requirements under requirements/milestones/ — the same workflow this repo asks target projects to use.

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/sdlc.sh next, ./scripts/sdlc-spdd/sdlc.sh claim … Terminal in your installed target project
Shell — orchestrator ./scripts/sdlc.sh next (same CLI, orchestrator repo layout) Terminal in the orchestrator repo clone (dogfooding)

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;
Loading
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.

  1. First day with SDLC-SPDD — hands-on first session
  2. Three-part operating path — how Planning, SPDD, and SDLC work together
  3. 10,000-foot view
  4. Installing into your project
  5. Top useful concepts and commands
  6. 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.

  1. 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.

  2. Tier 2 (on demand) — ./scripts/sdlc-spdd/sdlc.sh start (or 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). Orient first with ./scripts/sdlc-spdd/sdlc.sh next or /sdlc-spdd-whereami.

  3. Paste the Resume Prompt from that brief into chat — load only the files listed under Resolved Context.

  4. Close the loop — ./scripts/sdlc-spdd/sdlc.sh capture (or capture-session-memory.sh) and index-spdd-analysis.sh grow the indexes for the next session.

    ./scripts/sdlc-spdd/sdlc.sh claim ./scripts/sdlc-spdd/sdlc.sh start ./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-whereami Orient: team registry, active Work ID, phase, gates, next command
/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/sdlc.sh Daily workflow CLI: next, claim, resume, advance, capture, team, list-work (orchestrator: scripts/sdlc.sh)
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.

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.

About

SDLC Agents already has the multi-agent phase model, progressive disclosure, stack detection, Java skill support, architecture-test hooks, and a workspace under agent-context/. OpenSPDD adds the stronger REASONS Canvas contract and /spdd-sync idea so the design doc stays aligned with code over time.

jmjava.github.io/sdlc-spdd-orchestrator/

Resources

Readme
MIT license

Contributing

Contributing
Activity

Stars

2 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

Packages

Contributors

Languages