From 4580e62604d2f4a4cb862c499813106f382a6048 Mon Sep 17 00:00:00 2001 From: Andrei Date: Sat, 4 Apr 2026 16:45:30 +0300 Subject: [PATCH 01/17] Clarify newcomer onboarding surfaces --- AGENTS.md | 17 +++++++++++++++++ README.md | 35 +++++++++++++++++++++++++++++++++-- docs/MULTI-REPO-WORKFLOW.md | 2 ++ docs/reference/README.md | 1 + docs/reference/project-map.md | 33 +++++++++++++++++++++++++++++++++ sdp | 2 +- 6 files changed, 87 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index b479ffe7..c8c71023 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,6 +11,23 @@ Use these entrypoints before diving into older plans or runbooks: 3. [docs/architecture/REPO-BOUNDARY.md](docs/architecture/REPO-BOUNDARY.md) — what belongs in `sdp_lab` vs `sdp` 4. [docs/roadmap/ROADMAP.md](docs/roadmap/ROADMAP.md) — current platform-first direction +## Cold Start For Development Agents + +If you enter this repo cold, answer these before doing real work: + +1. Am I changing `sdp_lab`, or am I actually being asked to adopt or publish through `sdp/`? +2. Is the user asking for platform work, or for "use SDP in my project" onboarding? +3. Which single `feature`, `workstream`, or `beads issue` owns this task? +4. Which doc is canonical for this question, instead of a historical plan? + +Minimum first pass: + +1. `git status --short --branch` +2. read [docs/reference/project-map.md](docs/reference/project-map.md) +3. if this is execution work, run `scripts/beads_transport.sh fetch` and `bd ready --json` +4. if the request is about greenfield or brownfield SDP adoption, stop reading private-lab process docs and jump to [sdp/docs/QUICKSTART.md](sdp/docs/QUICKSTART.md) +5. if the path starts with `sdp/`, read [docs/MULTI-REPO-WORKFLOW.md](docs/MULTI-REPO-WORKFLOW.md) before editing anything + ## Project Structure This project has **two repos** with different roles: diff --git a/README.md b/README.md index 88f0570c..f325c99e 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,38 @@ # SDP Lab Control Workspace -Private planning and orchestration workspace for SDP evolution. +Private build, planning, and orchestration workspace for SDP. GitHub repo name: `sdp_lab`. Historical docs and bead IDs may still use `sdp_dev` as a legacy label for the same root repo. +## What This Repo Actually Does + +`sdp_lab` is the private repo where we build and steer the SDP platform itself. + +- platform code lives here: Go binaries, orchestration, evals, adapters, K8s manifests +- planning lives here: roadmap, workstreams, private design docs, execution runbooks +- public protocol artifacts live in `sdp/`: prompts, hooks, schemas, and OSS CLI work + +If your goal is to **use SDP inside your own project**, this repo is not the primary onboarding surface. Start with [`sdp/docs/QUICKSTART.md`](sdp/docs/QUICKSTART.md). + ## Rules - This repo is the default place for strategic planning. - Do not publish private architecture, enterprise scope, or commercial details into OSS repos. - Export to OSS only through sanitized artifacts. +## Choose Your Path + +| Goal | Start here | +|---|---| +| Understand what `sdp_lab` is and what lives here | [`docs/reference/project-map.md`](docs/reference/project-map.md) | +| Contribute to the platform or private lab runtime | [`AGENTS.md`](AGENTS.md), [`docs/MULTI-REPO-WORKFLOW.md`](docs/MULTI-REPO-WORKFLOW.md), [`docs/roadmap/ROADMAP.md`](docs/roadmap/ROADMAP.md) | +| Adopt SDP in a greenfield or brownfield project | [`sdp/docs/QUICKSTART.md`](sdp/docs/QUICKSTART.md), then [`sdp/README.md`](sdp/README.md) | + +## IDE Support Today + +- public onboarding flow is first-class for `Claude Code`, `Cursor`, and `OpenCode` / `Windsurf` +- `Codex` prompt compatibility exists in [`sdp/.codex/`](sdp/.codex/), but the public install flow is still manual rather than auto-detected +- if the question is "can I give SDP my keys and start working?", the honest answer lives in `sdp/`, not in the private-lab runbooks here + ## Start Here Use these as the canonical entrypoints: @@ -20,7 +44,14 @@ Use these as the canonical entrypoints: This README is a broad inventory, not the canonical workflow doc. -## Folders +## Main Components + +- `cmd/`, `internal/` - platform binaries, orchestration, evals, kernel, adapters +- `deploy/` - deployable runtime and observability manifests +- `docs/roadmap/`, `docs/workstreams/`, `docs/plans/` - planning and execution surfaces +- `sdp/` - public submodule for prompts, hooks, schemas, and OSS CLI work + +## Inventory - `docs/architecture/REPO-BOUNDARY.md` - sdp vs sdp_lab boundary (binaries, publish mapping). - `docs/MULTI-REPO-WORKFLOW.md` - parent repo vs submodule commit order, branch defaults, and recovery steps. diff --git a/docs/MULTI-REPO-WORKFLOW.md b/docs/MULTI-REPO-WORKFLOW.md index 29442e1c..505e2637 100644 --- a/docs/MULTI-REPO-WORKFLOW.md +++ b/docs/MULTI-REPO-WORKFLOW.md @@ -1,5 +1,7 @@ # sdp_lab <-> sdp Workflow +If your real goal is "install SDP into my own repo and start using it", leave this doc and go to [../sdp/docs/QUICKSTART.md](../sdp/docs/QUICKSTART.md). This file is only for contributors working across the private parent repo and the public submodule. + Use this repo as a two-repo workspace: | Path | Repo | Remote | Typical change | diff --git a/docs/reference/README.md b/docs/reference/README.md index 8affa544..64579011 100644 --- a/docs/reference/README.md +++ b/docs/reference/README.md @@ -14,6 +14,7 @@ Start here: | Need | Reference | |---|---| | Project identity and read order | [project-map.md](project-map.md) | +| Adopt SDP in another repo | [../../sdp/docs/QUICKSTART.md](../../sdp/docs/QUICKSTART.md) | | Canonical loop and default agents | [agent-catalog.md](agent-catalog.md) | | Canonical skill surface | [skills.md](skills.md) | | Commands | [commands.md](commands.md) | diff --git a/docs/reference/project-map.md b/docs/reference/project-map.md index 61a87a21..02464b92 100644 --- a/docs/reference/project-map.md +++ b/docs/reference/project-map.md @@ -13,6 +13,32 @@ This is the shortest accurate way to orient inside `sdp_lab`. - it uses `main` as the live default branch - historical docs and bead IDs may still say `sdp_dev`; treat that as a legacy label for this same repo +## Who Should Start Here + +Use this doc if you need to understand the private workspace itself: + +- you want to know what this repo does and which components live here +- you are contributing to SDP platform code, evals, adapters, or planning +- you are a development agent entering cold and need the canonical read order + +Do not use this doc as your main onboarding path if your real goal is: + +- install SDP into another repo +- give SDP your IDE and keys +- start greenfield delivery or brownfield adoption + +For that path, go straight to [../../sdp/docs/QUICKSTART.md](../../sdp/docs/QUICKSTART.md). Today that quickstart is honest for `Claude Code`, `Cursor`, and `OpenCode`. `Codex` compatibility exists, but setup is still more manual; use [../../sdp/.codex/INSTALL.md](../../sdp/.codex/INSTALL.md). + +## Main Components + +| Area | What it owns | +|---|---| +| `cmd/`, `internal/` | Go binaries, kernel, adapters, orchestration, evals | +| `deploy/` | K8s runtime and observability manifests | +| `docs/roadmap/`, `docs/workstreams/`, `docs/plans/` | planning, execution queue, and design history | +| `docs/reference/` | stable reference docs for the current canonical loop | +| `sdp/` | public submodule for prompts, hooks, schemas, and OSS CLI work | + Start with these files: 1. [AGENTS.md](../../AGENTS.md) @@ -45,6 +71,7 @@ Use one source per question. |---|---| | What repo owns this file? | [docs/MULTI-REPO-WORKFLOW.md](../MULTI-REPO-WORKFLOW.md) | | What belongs in `sdp_lab` vs `sdp`? | [docs/architecture/REPO-BOUNDARY.md](../architecture/REPO-BOUNDARY.md) | +| How do I adopt SDP in another repo? | [../../sdp/docs/QUICKSTART.md](../../sdp/docs/QUICKSTART.md) | | What is the canonical operator loop? | [docs/plans/2026-03-15-canonical-sdp-loop-and-agent-stack.md](../plans/2026-03-15-canonical-sdp-loop-and-agent-stack.md) | | What agents and skills are on the happy path? | [agent-catalog.md](agent-catalog.md), [skills.md](skills.md) | | What is ready or blocked right now? | `bd ready` and `bd show` are authoritative; `docs/workstreams/INDEX.md` is only the planning summary | @@ -81,6 +108,12 @@ If you are new to this repo, read in this order: 4. [docs/workstreams/INDEX.md](../workstreams/INDEX.md) 5. [docs/SDP_OPERATOR_WORKFLOW.md](../SDP_OPERATOR_WORKFLOW.md) +If you are new to SDP but not to this repo, use this shorter decision: + +1. "I want to use SDP in my own repo" -> [../../sdp/docs/QUICKSTART.md](../../sdp/docs/QUICKSTART.md) +2. "I want to work on SDP platform internals" -> keep reading this file +3. "I am a dev agent entering cold" -> [../../AGENTS.md](../../AGENTS.md), then this file + If you are touching `sdp/`, read these before changing anything: 1. [docs/MULTI-REPO-WORKFLOW.md](../MULTI-REPO-WORKFLOW.md) diff --git a/sdp b/sdp index d8c16a76..353fda58 160000 --- a/sdp +++ b/sdp @@ -1 +1 @@ -Subproject commit d8c16a7673257ef378510f5ae443bcf4643eb4ae +Subproject commit 353fda58970cd343257c245e56c67868e7d74d9f From 4593e108488f9aca2b476dc6c9f2d4c9ae9e859e Mon Sep 17 00:00:00 2001 From: Andrei Date: Sat, 4 Apr 2026 17:22:05 +0300 Subject: [PATCH 02/17] Update sdp submodule for installer fixes --- sdp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdp b/sdp index 353fda58..bec585d2 160000 --- a/sdp +++ b/sdp @@ -1 +1 @@ -Subproject commit 353fda58970cd343257c245e56c67868e7d74d9f +Subproject commit bec585d229b77f238d0aada0750830008dd1d874 From 46ba292bc74995ffad7be4c2bcb450d827a927b5 Mon Sep 17 00:00:00 2001 From: Andrei Date: Sat, 4 Apr 2026 17:23:33 +0300 Subject: [PATCH 03/17] Update sdp submodule for CI fix --- sdp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdp b/sdp index bec585d2..c2743f19 160000 --- a/sdp +++ b/sdp @@ -1 +1 @@ -Subproject commit bec585d229b77f238d0aada0750830008dd1d874 +Subproject commit c2743f195c72e4bd91c2dfac7ce4b49fb2b215f3 From f08a71d7acd5a239b738fd4fef049c5379ee8400 Mon Sep 17 00:00:00 2001 From: Andrei Date: Sat, 4 Apr 2026 17:29:27 +0300 Subject: [PATCH 04/17] Update sdp submodule for detached CI fix --- sdp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdp b/sdp index c2743f19..26dff219 160000 --- a/sdp +++ b/sdp @@ -1 +1 @@ -Subproject commit c2743f195c72e4bd91c2dfac7ce4b49fb2b215f3 +Subproject commit 26dff219521d61d3fed2de0460062cf9521d0c0f From dac3c16f3e2f973010c67b5ba55d3351a239d48a Mon Sep 17 00:00:00 2001 From: Andrei Date: Sat, 4 Apr 2026 20:11:58 +0300 Subject: [PATCH 05/17] Update sdp submodule for init auto fix --- sdp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdp b/sdp index 26dff219..3b269086 160000 --- a/sdp +++ b/sdp @@ -1 +1 @@ -Subproject commit 26dff219521d61d3fed2de0460062cf9521d0c0f +Subproject commit 3b269086d2a47850a66bfd72be1c77498f1d364b From 0dee1764b0ba958851a62751aa06dca8399cd314 Mon Sep 17 00:00:00 2001 From: Andrei Date: Sat, 4 Apr 2026 21:23:56 +0300 Subject: [PATCH 06/17] Sync Codex onboarding rollout --- .beads/interactions.jsonl | 29 +++++++++++++++++++++++++---- docs/reference/project-map.md | 2 +- sdp | 2 +- 3 files changed, 27 insertions(+), 6 deletions(-) diff --git a/.beads/interactions.jsonl b/.beads/interactions.jsonl index 29a60843..875d687d 100644 --- a/.beads/interactions.jsonl +++ b/.beads/interactions.jsonl @@ -129,7 +129,28 @@ {"id":"int-e141ac19","kind":"field_change","created_at":"2026-04-01T11:01:24.260353Z","actor":"Andrei","issue_id":"sdplab-zxl","extra":{"field":"status","new_value":"in_progress","old_value":"open"}} {"id":"int-d980d8ce","kind":"field_change","created_at":"2026-04-01T11:06:19.600313Z","actor":"Andrei","issue_id":"sdplab-zxl","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: rebased branch off origin/main, dropped stray 8004cae from PR history, and force-pushed clean head to PR #68"}} {"id":"int-a5363673","kind":"field_change","created_at":"2026-04-01T11:11:59.432752Z","actor":"Andrei","issue_id":"sdplab-yy6","extra":{"field":"status","new_value":"in_progress","old_value":"open"}} -{"id":"int-23b5fe99","kind":"field_change","created_at":"2026-04-01T11:26:28.627416Z","actor":"Andrei","issue_id":"sdplab-46m","extra":{"field":"status","new_value":"in_progress","old_value":"open"}} -{"id":"int-969c11c6","kind":"field_change","created_at":"2026-04-01T13:04:47.906924Z","actor":"Andrei","issue_id":"sdplab-46m","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: replaced hardcoded dev/master branch assumptions with repo-default branch resolution in orchestrate/evidence paths, updated canonical main-branch runbooks, and verified with targeted tests plus full go quality gates, protocol check, and doc-sync."}} -{"id":"int-5e625362","kind":"field_change","created_at":"2026-04-01T17:16:06.631785Z","actor":"Andrei","issue_id":"sdplab-ioj","extra":{"field":"status","new_value":"in_progress","old_value":"open"}} -{"id":"int-d3220832","kind":"field_change","created_at":"2026-04-01T17:24:26.51622Z","actor":"Andrei","issue_id":"sdplab-ioj","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: restored sdp as a real submodule from the public GitHub remote, repointed the gitlink to a valid OSS commit, recreated the missing multi-repo runbook, and opened an OSS PR to codify the submodule source-of-truth contract."}} +{"id":"int-ab68b478","kind":"field_change","created_at":"2026-04-01T19:05:15.301133Z","actor":"Andrei","issue_id":"sdplab-eib","extra":{"field":"status","new_value":"in_progress","old_value":"open"}} +{"id":"int-df118e37","kind":"field_change","created_at":"2026-04-01T19:07:09.483867Z","actor":"Andrei","issue_id":"sdplab-eib","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Defined wave-1 curated intake policy for superpowers in docs/plans/2026-04-01-superpowers-curated-intake-wave-1.md and linked the canonical skills reference; created follow-up tasks sdplab-hhs, sdplab-rio, sdplab-yqp."}} +{"id":"int-8dcddbc1","kind":"field_change","created_at":"2026-04-04T10:56:41.862364Z","actor":"Andrei","issue_id":"sdplab-9ih","extra":{"field":"status","new_value":"in_progress","old_value":"open"}} +{"id":"int-1d87a0aa","kind":"field_change","created_at":"2026-04-04T11:14:24.137445Z","actor":"Andrei","issue_id":"sdplab-9ih","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"CI green on PR #70 after GitHub Actions upgrades and project entrypoint docs consolidation; follow-up filed for misleading auto-attestation context fields"}} +{"id":"int-eeffd6ff","kind":"field_change","created_at":"2026-04-04T11:17:50.289843Z","actor":"Andrei","issue_id":"sdplab-n8w","extra":{"field":"status","new_value":"in_progress","old_value":"open"}} +{"id":"int-69b3d4cc","kind":"field_change","created_at":"2026-04-04T11:34:39.113281Z","actor":"Andrei","issue_id":"sdplab-n8w","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Review tail fixed: CI auto-attestation now reports branch, sdplab beads IDs, scoped boundary semantics, and pinned golangci-lint results on PR #70"}} +{"id":"int-0896f345","kind":"field_change","created_at":"2026-04-04T11:35:59.079248Z","actor":"Andrei","issue_id":"sdplab-g77","extra":{"field":"status","new_value":"in_progress","old_value":"open"}} +{"id":"int-6d7b5f12","kind":"field_change","created_at":"2026-04-04T11:47:30.280048Z","actor":"Andrei","issue_id":"sdplab-g77","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Review tail fixed: auto-attestation now checks out pull_request.head.sha and reports the real PR head commit in PR #70"}} +{"id":"int-650dd334","kind":"field_change","created_at":"2026-04-04T11:56:24.81657Z","actor":"Andrei","issue_id":"sdplab-8ra","extra":{"field":"status","new_value":"in_progress","old_value":"open"}} +{"id":"int-d1d2bada","kind":"field_change","created_at":"2026-04-04T12:02:08.949847Z","actor":"Andrei","issue_id":"sdplab-8ra","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Merged PR #70 into main and verified push CI green on run 23978394493"}} +{"id":"int-020dc049","kind":"field_change","created_at":"2026-04-04T12:18:15.385858Z","actor":"Andrei","issue_id":"sdplab-cur","extra":{"field":"status","new_value":"in_progress","old_value":"open"}} +{"id":"int-3f580a2e","kind":"field_change","created_at":"2026-04-04T12:39:03.451574Z","actor":"Andrei","issue_id":"sdplab-cur","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Cleaned docs/superpowers-curated-intake, merged PR #71 into main, and verified main CI run 23978985623 green"}} +{"id":"int-9666ed70","kind":"field_change","created_at":"2026-04-04T12:51:09.08271Z","actor":"Andrei","issue_id":"sdplab-6az","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Moved primary checkout to main, aligned sdp submodule to recorded gitlink, pruned stale local branches, and kept only the local .beads runtime diff"}} +{"id":"int-226369ba","kind":"field_change","created_at":"2026-04-04T13:01:40.79935Z","actor":"Andrei","issue_id":"sdplab-3ks","extra":{"field":"status","new_value":"in_progress","old_value":"open"}} +{"id":"int-e28a8c54","kind":"field_change","created_at":"2026-04-04T13:05:14.222887Z","actor":"Andrei","issue_id":"sdplab-3ks","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: clarified that .beads-sdp-mapping.jsonl is helper-only, removed false 1:1 coverage assumptions from canonical docs, and cleaned mixed-format legacy mapping rows"}} +{"id":"int-1c8aaa00","kind":"field_change","created_at":"2026-04-04T13:38:33.948411Z","actor":"Andrei","issue_id":"sdplab-vb6","extra":{"field":"status","new_value":"in_progress","old_value":"open"}} +{"id":"int-610c35e9","kind":"field_change","created_at":"2026-04-04T13:46:02.483844Z","actor":"Andrei","issue_id":"sdplab-vb6","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: clarified newcomer and dev-agent onboarding in sdp_lab, plus public sdp onboarding truth for IDE support and greenfield/brownfield entrypoints"}} +{"id":"int-a4170007","kind":"field_change","created_at":"2026-04-04T14:12:14.224754Z","actor":"Andrei","issue_id":"sdplab-7hv","extra":{"field":"status","new_value":"in_progress","old_value":"open"}} +{"id":"int-c0e62cb5","kind":"field_change","created_at":"2026-04-04T14:41:02.700639Z","actor":"Andrei","issue_id":"sdplab-7hv","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: installer update paths now refresh managed assets and vendored checkout, dirty managed checkouts fail clearly, detached-HEAD CI coverage is in place, and both sdp PR #120 and sdp_lab PR #73 are green"}} +{"id":"int-7a976d87","kind":"field_change","created_at":"2026-04-04T17:12:07.489158Z","actor":"Andrei","issue_id":"sdplab-3rm","extra":{"field":"status","new_value":"in_progress","old_value":"open"}} +{"id":"int-1081ef2e","kind":"field_change","created_at":"2026-04-04T17:12:07.879163Z","actor":"Andrei","issue_id":"sdplab-3rm","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Fixed sdp init --auto first-run hang and scaffold creation"}} +{"id":"int-9a0a2ce2","kind":"field_change","created_at":"2026-04-04T17:47:56.591266Z","actor":"Andrei","issue_id":"sdplab-s3m","extra":{"field":"status","new_value":"in_progress","old_value":"open"}} +{"id":"int-68a52dac","kind":"field_change","created_at":"2026-04-04T17:47:58.221236Z","actor":"Andrei","issue_id":"sdplab-had","extra":{"field":"status","new_value":"in_progress","old_value":"open"}} +{"id":"int-b14b36bb","kind":"field_change","created_at":"2026-04-04T18:23:41.934299Z","actor":"Andrei","issue_id":"sdplab-s3m","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: dry-run init output is truthful, non-duplicative, and no longer creates false .sdp/.claude signals"}} +{"id":"int-17501bc0","kind":"field_change","created_at":"2026-04-04T18:23:41.994542Z","actor":"Andrei","issue_id":"sdplab-had","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: Codex is now first-class in installer/init/doctor/docs with verified install and update path"}} diff --git a/docs/reference/project-map.md b/docs/reference/project-map.md index 02464b92..d75d4efb 100644 --- a/docs/reference/project-map.md +++ b/docs/reference/project-map.md @@ -27,7 +27,7 @@ Do not use this doc as your main onboarding path if your real goal is: - give SDP your IDE and keys - start greenfield delivery or brownfield adoption -For that path, go straight to [../../sdp/docs/QUICKSTART.md](../../sdp/docs/QUICKSTART.md). Today that quickstart is honest for `Claude Code`, `Cursor`, and `OpenCode`. `Codex` compatibility exists, but setup is still more manual; use [../../sdp/.codex/INSTALL.md](../../sdp/.codex/INSTALL.md). +For that path, go straight to [../../sdp/docs/QUICKSTART.md](../../sdp/docs/QUICKSTART.md). Today that quickstart covers `Claude Code`, `Cursor`, `OpenCode`, and `Codex`. Use [../../sdp/.codex/INSTALL.md](../../sdp/.codex/INSTALL.md) for Codex-specific notes after install. ## Main Components diff --git a/sdp b/sdp index 3b269086..31a87b7a 160000 --- a/sdp +++ b/sdp @@ -1 +1 @@ -Subproject commit 3b269086d2a47850a66bfd72be1c77498f1d364b +Subproject commit 31a87b7ae3d3d64ce67ef8bfd140d1d00dd0ad76 From 7c7ea78ece23649507e37a3aba23c1ff56711d6f Mon Sep 17 00:00:00 2001 From: Andrei Date: Sat, 4 Apr 2026 21:31:33 +0300 Subject: [PATCH 07/17] Sync first-run onboarding polish --- .beads/interactions.jsonl | 2 ++ sdp | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/.beads/interactions.jsonl b/.beads/interactions.jsonl index 875d687d..88c467e6 100644 --- a/.beads/interactions.jsonl +++ b/.beads/interactions.jsonl @@ -154,3 +154,5 @@ {"id":"int-68a52dac","kind":"field_change","created_at":"2026-04-04T17:47:58.221236Z","actor":"Andrei","issue_id":"sdplab-had","extra":{"field":"status","new_value":"in_progress","old_value":"open"}} {"id":"int-b14b36bb","kind":"field_change","created_at":"2026-04-04T18:23:41.934299Z","actor":"Andrei","issue_id":"sdplab-s3m","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: dry-run init output is truthful, non-duplicative, and no longer creates false .sdp/.claude signals"}} {"id":"int-17501bc0","kind":"field_change","created_at":"2026-04-04T18:23:41.994542Z","actor":"Andrei","issue_id":"sdplab-had","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: Codex is now first-class in installer/init/doctor/docs with verified install and update path"}} +{"id":"int-f5b45af5","kind":"field_change","created_at":"2026-04-04T18:30:22.508195Z","actor":"Andrei","issue_id":"sdplab-bmi","extra":{"field":"status","new_value":"in_progress","old_value":"open"}} +{"id":"int-5fa41995","kind":"field_change","created_at":"2026-04-04T18:31:25.494703Z","actor":"Andrei","issue_id":"sdplab-bmi","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: first-run doctor/init UX now stays focused for Codex and other non-Claude projects"}} diff --git a/sdp b/sdp index 31a87b7a..c4f65ebf 160000 --- a/sdp +++ b/sdp @@ -1 +1 @@ -Subproject commit 31a87b7ae3d3d64ce67ef8bfd140d1d00dd0ad76 +Subproject commit c4f65ebf8cd594497650d1b2bff2148b652285e1 From 51a089d9ae5e6bb843916423b043adc19b6aaf77 Mon Sep 17 00:00:00 2001 From: Andrei Date: Sat, 4 Apr 2026 21:42:39 +0300 Subject: [PATCH 08/17] Sync Claude onboarding polish --- .beads/interactions.jsonl | 2 ++ sdp | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/.beads/interactions.jsonl b/.beads/interactions.jsonl index 88c467e6..35f39b5e 100644 --- a/.beads/interactions.jsonl +++ b/.beads/interactions.jsonl @@ -156,3 +156,5 @@ {"id":"int-17501bc0","kind":"field_change","created_at":"2026-04-04T18:23:41.994542Z","actor":"Andrei","issue_id":"sdplab-had","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: Codex is now first-class in installer/init/doctor/docs with verified install and update path"}} {"id":"int-f5b45af5","kind":"field_change","created_at":"2026-04-04T18:30:22.508195Z","actor":"Andrei","issue_id":"sdplab-bmi","extra":{"field":"status","new_value":"in_progress","old_value":"open"}} {"id":"int-5fa41995","kind":"field_change","created_at":"2026-04-04T18:31:25.494703Z","actor":"Andrei","issue_id":"sdplab-bmi","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: first-run doctor/init UX now stays focused for Codex and other non-Claude projects"}} +{"id":"int-3799bb0a","kind":"field_change","created_at":"2026-04-04T18:40:50.499931Z","actor":"Andrei","issue_id":"sdplab-5dz","extra":{"field":"status","new_value":"in_progress","old_value":"open"}} +{"id":"int-d01f0c6a","kind":"field_change","created_at":"2026-04-04T18:42:28.475389Z","actor":"Andrei","issue_id":"sdplab-5dz","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: fresh Claude installer path no longer reports managed .claude as a conflict during init"}} diff --git a/sdp b/sdp index c4f65ebf..08051210 160000 --- a/sdp +++ b/sdp @@ -1 +1 @@ -Subproject commit c4f65ebf8cd594497650d1b2bff2148b652285e1 +Subproject commit 0805121064d36cb728559f8146895730de84d469 From 715232d2de2c346408f6ffde273f5002e9dee1a6 Mon Sep 17 00:00:00 2001 From: Andrei Date: Sat, 4 Apr 2026 22:12:39 +0300 Subject: [PATCH 09/17] Sync installer messaging polish --- .beads/interactions.jsonl | 2 ++ sdp | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/.beads/interactions.jsonl b/.beads/interactions.jsonl index 35f39b5e..63dd2296 100644 --- a/.beads/interactions.jsonl +++ b/.beads/interactions.jsonl @@ -158,3 +158,5 @@ {"id":"int-5fa41995","kind":"field_change","created_at":"2026-04-04T18:31:25.494703Z","actor":"Andrei","issue_id":"sdplab-bmi","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: first-run doctor/init UX now stays focused for Codex and other non-Claude projects"}} {"id":"int-3799bb0a","kind":"field_change","created_at":"2026-04-04T18:40:50.499931Z","actor":"Andrei","issue_id":"sdplab-5dz","extra":{"field":"status","new_value":"in_progress","old_value":"open"}} {"id":"int-d01f0c6a","kind":"field_change","created_at":"2026-04-04T18:42:28.475389Z","actor":"Andrei","issue_id":"sdplab-5dz","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: fresh Claude installer path no longer reports managed .claude as a conflict during init"}} +{"id":"int-8870d1fc","kind":"field_change","created_at":"2026-04-04T19:06:12.116613Z","actor":"Andrei","issue_id":"sdplab-wo6","extra":{"field":"status","new_value":"in_progress","old_value":"open"}} +{"id":"int-dc28c8b2","kind":"field_change","created_at":"2026-04-04T19:12:31.613137Z","actor":"Andrei","issue_id":"sdplab-wo6","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: installer now prints configured integrations, clear next steps, and explicit fallback guidance"}} diff --git a/sdp b/sdp index 08051210..5a255335 160000 --- a/sdp +++ b/sdp @@ -1 +1 @@ -Subproject commit 0805121064d36cb728559f8146895730de84d469 +Subproject commit 5a2553352e5335a81f02a83de901bcba1dc68a68 From b803a5d0820500185f09580190357cef2fba05c3 Mon Sep 17 00:00:00 2001 From: Andrei Date: Sat, 4 Apr 2026 22:24:52 +0300 Subject: [PATCH 10/17] Sync harness-aware skill defaults --- .beads/interactions.jsonl | 2 ++ sdp | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/.beads/interactions.jsonl b/.beads/interactions.jsonl index 63dd2296..31c12b95 100644 --- a/.beads/interactions.jsonl +++ b/.beads/interactions.jsonl @@ -160,3 +160,5 @@ {"id":"int-d01f0c6a","kind":"field_change","created_at":"2026-04-04T18:42:28.475389Z","actor":"Andrei","issue_id":"sdplab-5dz","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: fresh Claude installer path no longer reports managed .claude as a conflict during init"}} {"id":"int-8870d1fc","kind":"field_change","created_at":"2026-04-04T19:06:12.116613Z","actor":"Andrei","issue_id":"sdplab-wo6","extra":{"field":"status","new_value":"in_progress","old_value":"open"}} {"id":"int-dc28c8b2","kind":"field_change","created_at":"2026-04-04T19:12:31.613137Z","actor":"Andrei","issue_id":"sdplab-wo6","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: installer now prints configured integrations, clear next steps, and explicit fallback guidance"}} +{"id":"int-117ad938","kind":"field_change","created_at":"2026-04-04T19:17:58.171143Z","actor":"Andrei","issue_id":"sdplab-072","extra":{"field":"status","new_value":"in_progress","old_value":"open"}} +{"id":"int-4a54b521","kind":"field_change","created_at":"2026-04-04T19:24:32.069159Z","actor":"Andrei","issue_id":"sdplab-072","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: sdp skill now auto-detects project-local skills directories across Claude, Cursor, OpenCode, and Codex"}} diff --git a/sdp b/sdp index 5a255335..5af1ac25 160000 --- a/sdp +++ b/sdp @@ -1 +1 @@ -Subproject commit 5a2553352e5335a81f02a83de901bcba1dc68a68 +Subproject commit 5af1ac25d36aa998bf1aa559f8b95191d8383187 From fd40400461f847dd5cb43daa9c48a858028dcbc7 Mon Sep 17 00:00:00 2001 From: Andrei Date: Sat, 4 Apr 2026 22:38:43 +0300 Subject: [PATCH 11/17] Sync quality test timeout fix --- .beads/interactions.jsonl | 2 ++ sdp | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/.beads/interactions.jsonl b/.beads/interactions.jsonl index 31c12b95..35fc3aae 100644 --- a/.beads/interactions.jsonl +++ b/.beads/interactions.jsonl @@ -162,3 +162,5 @@ {"id":"int-dc28c8b2","kind":"field_change","created_at":"2026-04-04T19:12:31.613137Z","actor":"Andrei","issue_id":"sdplab-wo6","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: installer now prints configured integrations, clear next steps, and explicit fallback guidance"}} {"id":"int-117ad938","kind":"field_change","created_at":"2026-04-04T19:17:58.171143Z","actor":"Andrei","issue_id":"sdplab-072","extra":{"field":"status","new_value":"in_progress","old_value":"open"}} {"id":"int-4a54b521","kind":"field_change","created_at":"2026-04-04T19:24:32.069159Z","actor":"Andrei","issue_id":"sdplab-072","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: sdp skill now auto-detects project-local skills directories across Claude, Cursor, OpenCode, and Codex"}} +{"id":"int-8ec28c04","kind":"field_change","created_at":"2026-04-04T19:37:02.070973Z","actor":"Andrei","issue_id":"sdplab-gph","extra":{"field":"status","new_value":"in_progress","old_value":"open"}} +{"id":"int-6fb4baee","kind":"field_change","created_at":"2026-04-04T19:38:25.77008Z","actor":"Andrei","issue_id":"sdplab-gph","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: quality coverage command test is now deterministic, and go test ./cmd/sdp completes without timeout"}} diff --git a/sdp b/sdp index 5af1ac25..8026df9f 160000 --- a/sdp +++ b/sdp @@ -1 +1 @@ -Subproject commit 5af1ac25d36aa998bf1aa559f8b95191d8383187 +Subproject commit 8026df9f7f3f4e81be3968caedbf3267ccef890f From bb006c8d131a88142af06321ea6636a45d50c51c Mon Sep 17 00:00:00 2001 From: Andrei Date: Sun, 5 Apr 2026 11:22:23 +0300 Subject: [PATCH 12/17] Sync doctor test determinism fix --- .beads/interactions.jsonl | 2 ++ sdp | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/.beads/interactions.jsonl b/.beads/interactions.jsonl index 35fc3aae..a10ae4c4 100644 --- a/.beads/interactions.jsonl +++ b/.beads/interactions.jsonl @@ -164,3 +164,5 @@ {"id":"int-4a54b521","kind":"field_change","created_at":"2026-04-04T19:24:32.069159Z","actor":"Andrei","issue_id":"sdplab-072","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: sdp skill now auto-detects project-local skills directories across Claude, Cursor, OpenCode, and Codex"}} {"id":"int-8ec28c04","kind":"field_change","created_at":"2026-04-04T19:37:02.070973Z","actor":"Andrei","issue_id":"sdplab-gph","extra":{"field":"status","new_value":"in_progress","old_value":"open"}} {"id":"int-6fb4baee","kind":"field_change","created_at":"2026-04-04T19:38:25.77008Z","actor":"Andrei","issue_id":"sdplab-gph","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: quality coverage command test is now deterministic, and go test ./cmd/sdp completes without timeout"}} +{"id":"int-d70ba584","kind":"field_change","created_at":"2026-04-05T08:21:30.347091Z","actor":"Andrei","issue_id":"sdplab-6w4","extra":{"field":"status","new_value":"in_progress","old_value":"open"}} +{"id":"int-23c14984","kind":"field_change","created_at":"2026-04-05T08:22:07.801833Z","actor":"Andrei","issue_id":"sdplab-6w4","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: doctor command tests now stub host-dependent checks and verify command wiring deterministically"}} diff --git a/sdp b/sdp index 8026df9f..3f56a1b2 160000 --- a/sdp +++ b/sdp @@ -1 +1 @@ -Subproject commit 8026df9f7f3f4e81be3968caedbf3267ccef890f +Subproject commit 3f56a1b2b75d394b264bc2520d42134a359e85de From 753a6cbc1b3be7d2be2633078d96862e18ae4ef4 Mon Sep 17 00:00:00 2001 From: Andrei Date: Sun, 5 Apr 2026 12:44:41 +0300 Subject: [PATCH 13/17] Sync deploy test determinism fix --- .beads/interactions.jsonl | 4 ++++ sdp | 2 +- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/.beads/interactions.jsonl b/.beads/interactions.jsonl index a10ae4c4..25027375 100644 --- a/.beads/interactions.jsonl +++ b/.beads/interactions.jsonl @@ -166,3 +166,7 @@ {"id":"int-6fb4baee","kind":"field_change","created_at":"2026-04-04T19:38:25.77008Z","actor":"Andrei","issue_id":"sdplab-gph","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: quality coverage command test is now deterministic, and go test ./cmd/sdp completes without timeout"}} {"id":"int-d70ba584","kind":"field_change","created_at":"2026-04-05T08:21:30.347091Z","actor":"Andrei","issue_id":"sdplab-6w4","extra":{"field":"status","new_value":"in_progress","old_value":"open"}} {"id":"int-23c14984","kind":"field_change","created_at":"2026-04-05T08:22:07.801833Z","actor":"Andrei","issue_id":"sdplab-6w4","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: doctor command tests now stub host-dependent checks and verify command wiring deterministically"}} +{"id":"int-e5b5529f","kind":"field_change","created_at":"2026-04-05T09:43:14.729206Z","actor":"Andrei","issue_id":"sdplab-6w4","extra":{"field":"status","new_value":"in_progress","old_value":"closed"}} +{"id":"int-9e4171cf","kind":"field_change","created_at":"2026-04-05T09:43:21.193516Z","actor":"Andrei","issue_id":"sdplab-6w4","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: doctor command tests now stub host-dependent checks and verify command wiring deterministically"}} +{"id":"int-26cd260f","kind":"field_change","created_at":"2026-04-05T09:43:21.228075Z","actor":"Andrei","issue_id":"sdplab-uly","extra":{"field":"status","new_value":"in_progress","old_value":"open"}} +{"id":"int-f8dcc43e","kind":"field_change","created_at":"2026-04-05T09:44:27.209245Z","actor":"Andrei","issue_id":"sdplab-uly","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: deploy command tests now stub git defaults and verify default output deterministically"}} diff --git a/sdp b/sdp index 3f56a1b2..25773b64 160000 --- a/sdp +++ b/sdp @@ -1 +1 @@ -Subproject commit 3f56a1b2b75d394b264bc2520d42134a359e85de +Subproject commit 25773b648120d7660c367ef86c08215cea7c37d9 From 552a404d75ff3aef799681f77a60b658d2ca72e6 Mon Sep 17 00:00:00 2001 From: Andrei Date: Sun, 5 Apr 2026 13:03:36 +0300 Subject: [PATCH 14/17] Add SDP happy path audit --- .beads/interactions.jsonl | 1 + .../2026-04-05-sdp-happy-path-audit.md | 173 ++++++++++++++++++ 2 files changed, 174 insertions(+) create mode 100644 docs/reviews/2026-04-05-sdp-happy-path-audit.md diff --git a/.beads/interactions.jsonl b/.beads/interactions.jsonl index 25027375..f588d201 100644 --- a/.beads/interactions.jsonl +++ b/.beads/interactions.jsonl @@ -170,3 +170,4 @@ {"id":"int-9e4171cf","kind":"field_change","created_at":"2026-04-05T09:43:21.193516Z","actor":"Andrei","issue_id":"sdplab-6w4","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: doctor command tests now stub host-dependent checks and verify command wiring deterministically"}} {"id":"int-26cd260f","kind":"field_change","created_at":"2026-04-05T09:43:21.228075Z","actor":"Andrei","issue_id":"sdplab-uly","extra":{"field":"status","new_value":"in_progress","old_value":"open"}} {"id":"int-f8dcc43e","kind":"field_change","created_at":"2026-04-05T09:44:27.209245Z","actor":"Andrei","issue_id":"sdplab-uly","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: deploy command tests now stub git defaults and verify default output deterministically"}} +{"id":"int-2ae4538d","kind":"field_change","created_at":"2026-04-05T10:03:16.142228Z","actor":"Andrei","issue_id":"sdplab-iir","extra":{"field":"status","new_value":"in_progress","old_value":"open"}} diff --git a/docs/reviews/2026-04-05-sdp-happy-path-audit.md b/docs/reviews/2026-04-05-sdp-happy-path-audit.md new file mode 100644 index 00000000..efc5c0ac --- /dev/null +++ b/docs/reviews/2026-04-05-sdp-happy-path-audit.md @@ -0,0 +1,173 @@ +# SDP Happy Path Audit + +Status: review +Date: 2026-04-05 +Scope: public onboarding surfaces in `sdp/` plus canonical operator workflow in `sdp_lab/` + +## Goal + +Evaluate whether SDP currently presents one coherent happy path from: + +1. task enters the board or queue +2. the system shapes it with progressive disclosure +3. agents execute and verify the work +4. findings loop back into execution +5. the feature reaches deploy with visible proof + +## Desired Happy Path + +The intended product story is: + +1. user drops work onto the board +2. SDP turns that into a shaped feature and executable work +3. agents ask only the missing questions +4. agents implement, verify, review, and surface findings +5. the operator sees clear status and next action +6. the system reaches a clean deploy path with evidence + +This must be legible through: + +- `README` +- `QUICKSTART` +- `CONTRIBUTING` +- CLI help and CLI reference +- operator workflow docs +- skill and reference docs + +## Verdict + +There is no single canonical happy path today. + +Current surfaces describe at least three different products: + +1. public docs path: `@feature -> @oneshot -> @review -> @deploy` +2. CLI path: `sdp init -> sdp plan -> sdp apply -> sdp status/next` +3. private operator path: `Beads -> draft PR -> findings loop -> QA/UAT -> merge` + +These paths overlap, but they are not presented as progressive disclosure of one system. They compete. + +## Findings + +### Critical + +1. No public entrypoint explains the board-to-deploy loop. + + Public docs in [`sdp/README.md`](../../sdp/README.md) and [`sdp/docs/QUICKSTART.md`](../../sdp/docs/QUICKSTART.md) start from install and then jump to skills, but the actual execution system in [`docs/SDP_OPERATOR_WORKFLOW.md`](../SDP_OPERATOR_WORKFLOW.md) is Beads and PR driven. The user requirement "drop task on board and let SDP agents drive it to deploy" is not documented as the primary path anywhere. + +2. Public docs and CLI describe different primary interfaces. + + Public docs lead with skill invocations like `@feature` and `@oneshot`. Runtime help from `sdp --help`, `sdp plan --help`, and `sdp apply --help` leads with CLI commands as the visible workflow. This is not progressive disclosure. It is two different products speaking at once. + +3. Reference docs are materially stale and contradict current runtime truth. + + [`sdp/docs/reference/skills.md`](../../sdp/docs/reference/skills.md), [`sdp/docs/reference/design-spec.md`](../../sdp/docs/reference/design-spec.md), [`sdp/docs/reference/review-spec.md`](../../sdp/docs/reference/review-spec.md), and [`sdp/docs/reference/build-spec.md`](../../sdp/docs/reference/build-spec.md) still describe old `.claude`-only paths, Python-specific gates, `@design`-centric planning, and deployment behavior that no longer matches current CLI or current operator loop. + +### Major + +1. `QUICKSTART` has no honest progressive disclosure from newcomer to operator. + + [`sdp/docs/QUICKSTART.md`](../../sdp/docs/QUICKSTART.md) mixes install, init, skills, optional Beads, and flow summary, but it never says which path is default for: + + - solo user in a repo + - team using Beads + - operator using PR and QA/UAT gates + +2. `CONTRIBUTING` is not aligned with the actual delivery model. + + [`sdp/CONTRIBUTING.md`](../../sdp/CONTRIBUTING.md) still teaches `@idea -> @design -> @build -> @review -> @deploy` as the contribution workflow. That ignores the current CLI path and ignores the Beads/PR/QA/UAT loop that SDP itself uses internally. + +3. CLI help is locally coherent but not connected to the public docs story. + + `sdp --help`, `sdp init --help`, `sdp doctor --help`, `sdp status --help`, `sdp next --help`, `sdp plan --help`, `sdp apply --help`, `sdp build --help`, `sdp verify --help`, and `sdp deploy --help` are much closer to a usable CLI product surface than the reference docs. The problem is not runtime help quality alone. The problem is that README and reference docs do not treat CLI help as source of truth. + +4. The docs do not clearly explain where Beads is optional and where it is required. + + In public docs Beads is positioned as optional tooling. In the actual operator workflow it is the live execution graph. That ambiguity is acceptable only if SDP explicitly defines two modes: + + - lightweight local mode + - full operator mode + + Right now that split is implicit. + +### Minor + +1. `README` references `docs/INSTALL.md`, but that file does not exist. +2. Several reference docs still assume `.claude/skills/*` as the only skill surface despite Cursor, OpenCode, and Codex support. +3. Terms like `feature`, `idea`, `workstream`, `task`, `board`, `Beads issue`, and `deploy` are used across public and private docs without one stable operator glossary for the current loop. + +## Recommended Direction + +Do not patch surfaces independently. + +First define one canonical happy path with two explicit layers: + +1. `Adopt SDP in my repo` + - install + - `sdp init` + - `sdp doctor` + - choose interaction mode: skills or CLI + - run a first success path + +2. `Run SDP as an operator system` + - intake onto board or Beads-backed queue + - shape feature and workstreams + - execute through agents + - loop findings back into queue + - verify, QA/UAT, deploy + +That second layer must explicitly state whether "board" is: + +- a Beads-backed queue +- a projected read model over Beads +- future control-tower UI that is not yet the default public path + +Without that answer, the product promise remains aspirational rather than usable. + +## Remediation Order + +### Phase 1: Canonical path spec + +Produce one short source-of-truth doc for: + +- user types +- default path +- optional advanced path +- artifacts created at each step +- where progressive disclosure happens +- where human approval is required + +### Phase 2: Entry surfaces + +Bring these into alignment with the canonical path: + +- [`sdp/README.md`](../../sdp/README.md) +- [`sdp/docs/QUICKSTART.md`](../../sdp/docs/QUICKSTART.md) +- [`sdp/CONTRIBUTING.md`](../../sdp/CONTRIBUTING.md) +- [`sdp/docs/CLI_REFERENCE.md`](../../sdp/docs/CLI_REFERENCE.md) + +### Phase 3: Runtime help and reference cleanup + +Treat runtime help as product truth and make reference docs subordinate: + +- remove stale spec pages or mark them legacy +- stop documenting old `.claude`-only skill paths as canonical +- rewrite skill/reference docs around the chosen happy path + +### Phase 4: Board-to-deploy proof + +Add one concrete walkthrough that proves the promise: + +1. task enters board or queue +2. clarifications requested only when needed +3. work decomposed into executable units +4. implementation completed +5. findings loop visible +6. review and deploy completion visible + +## Acceptance Criteria For This Product Slice + +- A newcomer can identify one canonical entry doc in under 30 seconds. +- A contributor can tell whether the default flow is skill-first, CLI-first, or Beads-first without inference. +- A user can see how a task moves from board or queue to deploy without opening private historical plans. +- CLI help, quickstart, and contribution docs no longer describe conflicting primary workflows. +- Reference docs either match runtime truth or are explicitly labeled legacy. From ccf88fedd5f7ca20b5b285da0b3a013337bbc3cc Mon Sep 17 00:00:00 2001 From: Andrei Date: Sun, 5 Apr 2026 13:09:11 +0300 Subject: [PATCH 15/17] Add canonical happy path consistency design --- .beads/interactions.jsonl | 2 + ...05-canonical-sdp-happy-path-consistency.md | 683 ++++++++++++++++++ 2 files changed, 685 insertions(+) create mode 100644 docs/plans/2026-04-05-canonical-sdp-happy-path-consistency.md diff --git a/.beads/interactions.jsonl b/.beads/interactions.jsonl index f588d201..d80bc199 100644 --- a/.beads/interactions.jsonl +++ b/.beads/interactions.jsonl @@ -171,3 +171,5 @@ {"id":"int-26cd260f","kind":"field_change","created_at":"2026-04-05T09:43:21.228075Z","actor":"Andrei","issue_id":"sdplab-uly","extra":{"field":"status","new_value":"in_progress","old_value":"open"}} {"id":"int-f8dcc43e","kind":"field_change","created_at":"2026-04-05T09:44:27.209245Z","actor":"Andrei","issue_id":"sdplab-uly","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: deploy command tests now stub git defaults and verify default output deterministically"}} {"id":"int-2ae4538d","kind":"field_change","created_at":"2026-04-05T10:03:16.142228Z","actor":"Andrei","issue_id":"sdplab-iir","extra":{"field":"status","new_value":"in_progress","old_value":"open"}} +{"id":"int-ca19bbb4","kind":"field_change","created_at":"2026-04-05T10:05:57.211265Z","actor":"Andrei","issue_id":"sdplab-mkv","extra":{"field":"status","new_value":"in_progress","old_value":"open"}} +{"id":"int-a82a0bfb","kind":"field_change","created_at":"2026-04-05T10:08:48.757787Z","actor":"Andrei","issue_id":"sdplab-mkv","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: canonical happy path consistency design written with modes, truth model, stage model, surface ownership, and rollout phases"}} diff --git a/docs/plans/2026-04-05-canonical-sdp-happy-path-consistency.md b/docs/plans/2026-04-05-canonical-sdp-happy-path-consistency.md new file mode 100644 index 00000000..bd38bfc5 --- /dev/null +++ b/docs/plans/2026-04-05-canonical-sdp-happy-path-consistency.md @@ -0,0 +1,683 @@ +# Canonical SDP Happy Path Consistency Design + +> **Status:** Draft design +> **Date:** 2026-04-05 +> **Goal:** Define one coherent SDP product path from task intake to deploy, then align docs, help, and operator surfaces around that path. + +Related: + +- [docs/reviews/2026-04-05-sdp-happy-path-audit.md](../reviews/2026-04-05-sdp-happy-path-audit.md) +- [docs/plans/2026-03-15-canonical-sdp-loop-and-agent-stack.md](2026-03-15-canonical-sdp-loop-and-agent-stack.md) +- [docs/SDP_OPERATOR_WORKFLOW.md](../SDP_OPERATOR_WORKFLOW.md) +- [docs/REAL_FEATURE_TO_PR_RUNBOOK.md](../REAL_FEATURE_TO_PR_RUNBOOK.md) +- [docs/CONTROL_TOWER_V2_WORKING_MODEL.md](../CONTROL_TOWER_V2_WORKING_MODEL.md) +- [docs/decisions/ADR-BEADS-FIRST-SOURCE-OF-TRUTH.md](../decisions/ADR-BEADS-FIRST-SOURCE-OF-TRUTH.md) + +--- + +## 1. Problem + +SDP currently describes different happy paths depending on which surface the user reads first. + +Today we have three competing stories: + +1. public docs story: `@feature -> @oneshot -> @review -> @deploy` +2. CLI story: `sdp init -> sdp plan -> sdp apply -> sdp status/next` +3. internal operator story: `Beads -> draft PR -> findings loop -> QA/UAT -> merge` + +This is not progressive disclosure. +It is product split-brain. + +The result: + +- newcomers cannot tell what the default path is +- contributors learn a stale workflow +- CLI help and docs disagree about first-success behavior +- the "drop work on the board and let SDP carry it to deploy" promise is not stated as one coherent system + +The system needs one design, not more local copy edits. + +--- + +## 2. Product Decision + +SDP will describe one canonical product story: + +> A task enters the board-backed queue. SDP shapes it, asks only for missing information, executes it through agents, routes findings back into the same queue, and drives it to a clean deploy path with visible proof. + +Everything else is a disclosure layer or control surface for that same story. + +That means: + +- the canonical state model is board-to-deploy +- the board is not optional in the full product promise +- skills and CLI are not separate workflows +- public install/onboarding is a shorter on-ramp into the same system + +This design resolves the ambiguity by introducing two explicit operating modes. + +--- + +## 3. Operating Modes + +### 3.1 Local Mode + +Use this when a user wants SDP inside one repo and is not yet running a shared queue. + +Goals: + +- install SDP +- initialize repo scaffolding +- inspect health and next step +- shape and execute work locally + +Characteristics: + +- `Beads` is optional +- there may be no visible board UI +- CLI and skills operate directly in the repo +- user still gets the same stages, but without the full operator queue + +Primary first-success path: + +1. install SDP +2. `sdp init` +3. `sdp doctor` +4. shape a task into executable work +5. execute and verify + +### 3.2 Operator Mode + +Use this when SDP is presented as a task system that can carry work from queue to deploy. + +Goals: + +- intake tasks into a durable queue +- shape work with progressive disclosure +- let agents execute with visible status +- route findings back into execution +- reach QA/UAT and deploy with traceable evidence + +Characteristics: + +- `Beads` is required +- the board is a projection over Beads-backed operational truth +- PR, findings, QA/UAT, and deploy are first-class stages +- `status` and `next` explain where the item is and what happens next + +Primary path: + +1. task enters board-backed queue +2. clarification and shaping +3. executable graph becomes ready +4. early draft PR exists +5. agents execute +6. findings re-enter queue +7. QA/UAT passes +8. human approves merge or deploy step + +### 3.3 Why both modes exist + +This is not two products. + +It is one system with progressive disclosure: + +- `Local Mode` is the adoption ramp +- `Operator Mode` is the full product promise + +Public docs must stop pretending that the full board-to-deploy story is available without a queue. + +--- + +## 4. Source-of-Truth Model + +The system must state explicitly what is authoritative at each layer. + +| Layer | Canonical truth | Why | +|------|------------------|-----| +| Operational queue state | `Beads` | Accepted by ADR; durable task graph, readiness, blockers, status | +| Semantic intent | `feature` and `workstream` artifacts | These define meaning and acceptance | +| Integration state | branch + early `draft PR` | Review and merge happen here | +| Verification proof | `evidence`, `trace`, `drift`, `QA/UAT` artifacts | This is completion proof, not queue truth | +| Board/status views | derived projections | They explain state; they do not own it | +| CLI and skills | control surfaces | They operate the system; they do not define truth | + +### 4.1 Board semantics decision + +The board is a derived view over Beads-backed operational truth. + +This is not optional. +It follows directly from [ADR-BEADS-FIRST-SOURCE-OF-TRUTH.md](../decisions/ADR-BEADS-FIRST-SOURCE-OF-TRUTH.md). + +Therefore: + +- SDP must not describe the board as an independent store +- SDP must not imply a future control-tower UI is already the canonical source +- public docs must be honest that today's board-backed mode is Beads-first, with richer board views as projections + +### 4.2 PR semantics decision + +The PR is the integration and review surface, not the planning surface. + +Rules: + +- the PR is opened early +- review findings re-enter Beads +- QA/UAT happens after engineering gates are clean +- merge remains a human approval step + +`@deploy` and `sdp deploy` must be documented accordingly. +They cannot keep implying "automatic production deploy" if the real system is "clean PR plus approval and evidence." + +--- + +## 5. Canonical Happy Path + +The canonical happy path is stage-first. +Commands and skills are mapped onto stages, not the other way around. + +### Stage 0: Install and trust bootstrap + +Outcome: + +- repo has SDP installed +- supported IDE integration is present +- environment is healthy enough to continue + +Primary artifacts: + +- `.sdp/config.yml` +- integration-specific prompt surface +- optional CLI install + +Primary surfaces: + +- `README` +- `QUICKSTART` +- `sdp init` +- `sdp doctor` + +### Stage 1: Intake + +Outcome: + +- a task exists in the board-backed queue +- raw request is captured +- ownership and current state are visible + +Primary artifacts: + +- `Beads` issue +- optional intake artifact or source link + +Primary surfaces: + +- queue or board entrypoint +- `bd ready`, `bd show` +- future board or control-tower projection + +### Stage 2: Clarification and shaping + +Outcome: + +- SDP asks only for missing information +- a `feature` and linked `workstream` contracts exist +- executable Beads graph is ready + +Primary artifacts: + +- `feature` definition +- `workstream` files +- linked Beads issues + +Primary surfaces: + +- conversational shaping skills +- `sdp plan` +- feature agent + +### Stage 3: Execution setup + +Outcome: + +- active branch exists +- early draft PR exists +- ready work is visible + +Primary artifacts: + +- branch +- draft PR +- queue metadata and trace linkage + +Primary surfaces: + +- orchestrator +- PR tooling +- `sdp status` +- `sdp next` + +### Stage 4: Execution + +Outcome: + +- agents implement a ready slice +- evidence is emitted +- drift inputs are available + +Primary artifacts: + +- code/doc changes +- execution evidence +- trace links +- drift inputs + +Primary surfaces: + +- `@oneshot` +- `@build` +- `sdp apply` +- `sdp build` +- implementer agent + +### Stage 5: Findings loop + +Outcome: + +- review, CI, and drift findings become queue items +- blocking vs non-blocking work is visible +- the system returns to execution only when needed + +Primary artifacts: + +- typed findings in Beads +- updated trace +- PR state + +Primary surfaces: + +- reviewer agent +- CI +- drift checks +- `sdp status` +- `sdp next` + +### Stage 6: QA/UAT + +Outcome: + +- feature behavior is checked against intent +- pass or fail is explicit + +Primary artifacts: + +- `qa:pass` evidence or `qa:fail` findings + +Primary surfaces: + +- QA agent +- operator review surface + +### Stage 7: Delivery + +Outcome: + +- clean PR exists +- approval state is visible +- deploy or merge proof is recorded + +Primary artifacts: + +- merged PR or approved release state +- deploy or approval event +- final trace linkage + +Primary surfaces: + +- human approval +- `@deploy` +- `sdp deploy` + +--- + +## 6. Interface Model + +The system must stop documenting commands as if they define separate workflows. + +### 6.1 Skills + +Skills are guided journeys. + +Use them when the user wants: + +- conversation +- clarification +- progressive disclosure +- agent-driven execution + +They should be described as the guided surface over canonical stages. + +### 6.2 CLI + +CLI commands are explicit control primitives. + +Use them when the user wants: + +- terminal control +- scripting +- machine-readable state +- deterministic automation + +They should be described as stage controls and observability tools. + +### 6.3 Board and queue + +Board or queue views are state visibility and intake surfaces. + +They answer: + +- what exists +- what needs attention +- what is waiting on a human +- what is blocked +- what is ready +- what reached review or deploy + +They do not replace CLI or skills. +They make the system legible. + +### 6.4 Design rule + +Docs must describe one stage model and then show: + +- guided surface example +- explicit CLI example + +Never two separate happy paths. + +--- + +## 7. Progressive Disclosure Design + +The product must disclose complexity in layers. + +### Layer A: Product promise + +Audience: + +- newcomer +- evaluator +- OSS user + +Question answered: + +- what does SDP do for me? + +Owned by: + +- `README` + +Must state: + +- one-sentence promise +- two modes: local and operator +- honest note that full board-backed mode requires Beads +- where to start next + +### Layer B: First success + +Audience: + +- repo adopter +- first-time operator + +Question answered: + +- how do I get one task through the system? + +Owned by: + +- `QUICKSTART` + +Must state: + +- install and init +- health check +- how task intake works today +- local mode first success +- operator mode first success + +### Layer C: Stage navigation + +Audience: + +- active user in the terminal + +Question answered: + +- what command should I run now? + +Owned by: + +- CLI help +- `sdp status` +- `sdp next` +- `CLI_REFERENCE` + +Must state: + +- stage purpose +- input and output +- adjacent commands +- when this command is not the right tool + +### Layer D: Detailed operating model + +Audience: + +- contributor +- advanced operator +- maintainer + +Question answered: + +- how is the system supposed to work end to end? + +Owned by: + +- operator workflow docs +- this design doc + +### Layer E: Deep reference + +Audience: + +- maintainers +- auditors +- specialists + +Question answered: + +- what is the exact spec? + +Owned by: + +- reference docs that match runtime truth + +If a reference page is stale, it must be marked `legacy` or removed from primary navigation. + +--- + +## 8. Surface Ownership + +Each surface must answer one job and stop freelancing into others. + +| Surface | Primary job | Must not do | +|--------|-------------|-------------| +| `sdp/README.md` | state the product promise and route users to the right entrypoint | explain full internal protocol or outdated skill-only path | +| `sdp/docs/QUICKSTART.md` | deliver first success with progressive disclosure | act as full protocol spec | +| `sdp/CONTRIBUTING.md` | explain how to contribute to SDP itself using the canonical flow | teach a stale private workflow as if it is canonical | +| `sdp/docs/CLI_REFERENCE.md` | map command groups to stages and purposes | compete with runtime help or define product strategy | +| CLI `--help` | runtime truth for syntax, behavior, and examples | carry full architectural theory | +| operator workflow docs | explain the full operator loop | pretend to be the first document a newcomer should open | +| reference docs | exact detailed specs | remain in primary navigation when stale | + +### 8.1 Help-copy standard + +Each important command help surface should answer these questions in order: + +1. what stage is this for? +2. when should I use this command? +3. what artifact or state does it read or write? +4. what usually comes before it? +5. what usually comes after it? + +Without this structure, component help becomes a pile of flags instead of a usable system guide. + +--- + +## 9. Artifact Chain + +The happy path must expose a visible artifact chain from intake to deploy. + +| Stage | Artifact | +|------|----------| +| intake | queue item or board-backed task | +| shaping | feature definition and clarification record | +| decomposition | workstream files | +| execution graph | linked Beads issues | +| integration | branch + early draft PR | +| implementation | code/doc change and execution evidence | +| review loop | typed findings and updated queue state | +| QA/UAT | pass or fail evidence | +| delivery | approval or deploy event | + +This chain is the minimum needed to make the board promise credible. + +--- + +## 10. Terminology Decision + +We need one stable vocabulary for public and private docs. + +### Canonical terms + +- `board`: visibility surface over Beads-backed queue state +- `queue item`: operational work item in Beads +- `feature`: user-visible outcome and acceptance intent +- `workstream`: execution contract for one change slice +- `finding`: review, CI, drift, or QA issue that re-enters the queue +- `delivery`: clean PR plus approval or deploy proof + +### Terms to avoid as primary public language + +- `.claude`-only skill paths as if they are universal +- `deploy` as shorthand for "automatically shipped to production" when the real system is approval-gated +- legacy identifiers as if they are current public concepts + +--- + +## 11. Rollout Plan + +### Phase 1: Canon lock + +Deliverables: + +- this design doc +- one short public-facing "canonical happy path" doc if needed +- one stable terminology table + +Exit criteria: + +- maintainers agree on modes, truth model, and stage model + +### Phase 2: Entry surface rewrite + +Deliverables: + +- rewrite `README` +- rewrite `QUICKSTART` +- rewrite `CONTRIBUTING` + +Exit criteria: + +- all three surfaces describe the same system + +### Phase 3: Help and CLI alignment + +Deliverables: + +- tighten root help and stage command help +- rewrite `CLI_REFERENCE` +- make `status` and `next` first-class onboarding tools + +Exit criteria: + +- runtime help and doc examples agree + +### Phase 4: Reference cleanup + +Deliverables: + +- rewrite or mark legacy stale reference pages +- remove `.claude`-only assumptions from primary docs +- align skill/reference docs with current stage model + +Exit criteria: + +- primary reference set matches runtime truth + +### Phase 5: Board-to-deploy proof + +Deliverables: + +- one end-to-end walkthrough from queue to deploy +- visible artifact examples +- visible findings loop example + +Exit criteria: + +- a new user can trace one item from intake to delivery without opening historical plans + +--- + +## 12. Non-Goals + +This design does not: + +- build a new board UI now +- replace Beads as operational truth +- promise unattended production deploy +- rewrite every historical document in one pass +- settle every future control-tower implementation detail + +The job here is consistency of the system story and the surfaces that expose it. + +--- + +## 13. Acceptance Criteria + +This design is successful only when these statements become true in the shipped surfaces: + +1. A newcomer can identify the default SDP path in under 30 seconds. +2. Public docs explain that full board-backed operation requires Beads and that board views are projections over that truth. +3. Skills and CLI are described as two control surfaces for one stage model. +4. `README`, `QUICKSTART`, `CONTRIBUTING`, CLI help, and `CLI_REFERENCE` no longer contradict each other about the primary happy path. +5. The path from intake to deploy exposes a visible artifact chain and a visible findings loop. +6. Contributors can tell where human approval still exists and where agents are expected to operate autonomously. + +--- + +## 14. Recommendation + +Lock this design first. + +Then execute consistency work in this order: + +1. public entry surfaces +2. CLI help and CLI reference +3. stale reference cleanup +4. end-to-end walkthrough proof + +Do not start by polishing isolated files. +That is exactly how the current inconsistency was created. From 1a05d6de8c19c608bdf85288a5c75baaf341c681 Mon Sep 17 00:00:00 2001 From: Andrei Date: Sun, 5 Apr 2026 13:30:21 +0300 Subject: [PATCH 16/17] Sync sdp_lab happy path docs --- .beads/interactions.jsonl | 2 + docs/SDP_OPERATOR_WORKFLOW.md | 24 ++- ...026-04-05-sdp-cli-stage-navigation-spec.md | 90 +++++++++++ ...-sdp-operator-mode-runtime-surface-spec.md | 104 ++++++++++++ docs/reference/README.md | 11 +- docs/reference/agent-catalog.md | 11 +- docs/reference/canonical-happy-path.md | 152 ++++++++++++++++++ docs/reference/project-map.md | 32 +++- docs/reference/skills.md | 11 +- 9 files changed, 420 insertions(+), 17 deletions(-) create mode 100644 docs/plans/2026-04-05-sdp-cli-stage-navigation-spec.md create mode 100644 docs/plans/2026-04-05-sdp-operator-mode-runtime-surface-spec.md create mode 100644 docs/reference/canonical-happy-path.md diff --git a/.beads/interactions.jsonl b/.beads/interactions.jsonl index d80bc199..c6f2b204 100644 --- a/.beads/interactions.jsonl +++ b/.beads/interactions.jsonl @@ -173,3 +173,5 @@ {"id":"int-2ae4538d","kind":"field_change","created_at":"2026-04-05T10:03:16.142228Z","actor":"Andrei","issue_id":"sdplab-iir","extra":{"field":"status","new_value":"in_progress","old_value":"open"}} {"id":"int-ca19bbb4","kind":"field_change","created_at":"2026-04-05T10:05:57.211265Z","actor":"Andrei","issue_id":"sdplab-mkv","extra":{"field":"status","new_value":"in_progress","old_value":"open"}} {"id":"int-a82a0bfb","kind":"field_change","created_at":"2026-04-05T10:08:48.757787Z","actor":"Andrei","issue_id":"sdplab-mkv","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: canonical happy path consistency design written with modes, truth model, stage model, surface ownership, and rollout phases"}} +{"id":"int-79bb3929","kind":"field_change","created_at":"2026-04-05T10:26:18.759707Z","actor":"Andrei","issue_id":"sdplab-5fk","extra":{"field":"status","new_value":"in_progress","old_value":"open"}} +{"id":"int-af79d1e4","kind":"field_change","created_at":"2026-04-05T10:29:50.563288Z","actor":"Andrei","issue_id":"sdplab-5fk","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: sdp_lab canonical docs now point to one stable happy-path reference, Operator Mode is explicit, and deferred runtime changes are captured in separate specs"}} diff --git a/docs/SDP_OPERATOR_WORKFLOW.md b/docs/SDP_OPERATOR_WORKFLOW.md index 0af24271..830a5d22 100644 --- a/docs/SDP_OPERATOR_WORKFLOW.md +++ b/docs/SDP_OPERATOR_WORKFLOW.md @@ -1,17 +1,27 @@ # SDP Operator Workflow Status: reference -Scope: local operator workflow for `feature` -> `workstream` -> `beads` -> PR -> `QA/UAT` +Scope: Operator Mode workflow for `feature` -> `workstream` -> `beads` -> PR -> `QA/UAT` ## Overview -This document describes the canonical SDP operator loop for conducting work through linked `feature`, `workstream`, `beads issue`, `evidence`, `trace`, `drift`, and `PR` state. +This document describes the Operator Mode slice of the canonical SDP happy path. + +Use this doc when: + +- work is already entering a board-backed queue +- `Beads` is the operational source of truth +- the question is how SDP moves an item through execution, findings, `QA/UAT`, and delivery + +Do not use this doc as first-run onboarding for repo adoption. +For the stable system story, start with [reference/canonical-happy-path.md](reference/canonical-happy-path.md). Canonical design references: - [../AGENTS.md](../AGENTS.md) - [reference/project-map.md](reference/project-map.md) -- [plans/2026-03-15-canonical-sdp-loop-and-agent-stack.md](plans/2026-03-15-canonical-sdp-loop-and-agent-stack.md) +- [reference/canonical-happy-path.md](reference/canonical-happy-path.md) +- [plans/2026-04-05-canonical-sdp-happy-path-consistency.md](plans/2026-04-05-canonical-sdp-happy-path-consistency.md) ## Workflow Diagram @@ -59,7 +69,7 @@ flowchart TD ## Default Loop -The default operator path in `sdp_lab` is local and PR-driven. +The default Operator Mode path in `sdp_lab` is Beads-backed and PR-driven. - shape work in `feature` and `workstream` - use Beads as the durable execution graph @@ -73,6 +83,12 @@ K8s, swarm, and NATS flows are background or optional execution environments, no Roadmap and workstream docs set planning priority. Beads is still the live execution graph. If `bd ready` disagrees with a planning doc, fix the planning doc or file a Beads follow-up instead of freelancing from stale text. +Board semantics: + +- `Beads` is the operational source of truth +- board and status surfaces are derived projections +- this doc assumes the queue already exists and is visible through Beads-backed state + ## Sequence 1. **Shape `feature`:** confirm linked `workstream` and acceptance are clear enough to execute. diff --git a/docs/plans/2026-04-05-sdp-cli-stage-navigation-spec.md b/docs/plans/2026-04-05-sdp-cli-stage-navigation-spec.md new file mode 100644 index 00000000..fb8f6df3 --- /dev/null +++ b/docs/plans/2026-04-05-sdp-cli-stage-navigation-spec.md @@ -0,0 +1,90 @@ +# SDP CLI Stage Navigation Spec + +> **Status:** Proposed +> **Date:** 2026-04-05 +> **Related issue:** `sdplab-8jb` +> **Scope repo:** `sdp/` + +## Goal + +Align runtime CLI help and navigation surfaces in `sdp/sdp-plugin` with the canonical happy path. + +This spec exists because help strings and navigation behavior are code, not just docs. +They should be changed as an implementation slice in `sdp`, not inside the `sdp_lab` docs sync. + +## Problem + +Current runtime help is materially better than stale docs, but it still underspecifies the stage model: + +- root help lists commands, but does not clearly frame Local Mode vs Operator Mode +- command help does not consistently explain stage purpose, artifact boundaries, or adjacent next step +- `status` and `next` are useful, but they are not presented as the canonical navigation center +- operators still need too much repo knowledge to infer which command belongs to which stage + +## Decision + +`sdp` CLI help must become a stage-navigation surface, not a flat command catalog. + +### Required help contract + +Each major command help must answer, in this order: + +1. what stage this command belongs to +2. when to use it +3. what state or artifact it reads or writes +4. what usually comes before it +5. what usually comes after it + +### Root help contract + +Root help must: + +- state the Local Mode vs Operator Mode split explicitly +- explain that CLI and skills are two control surfaces over one stage model +- group command families by stage or operator job, not by historical implementation accident +- surface `status` and `next` as the primary navigation aids + +### `status` and `next` contract + +`status` and `next` must be treated as first-class onboarding/runtime guidance surfaces. + +They should be able to orient a user without requiring them to open stale reference docs. + +## In Scope + +- root `sdp --help` +- major command help for: + - `init` + - `doctor` + - `status` + - `next` + - `plan` + - `apply` + - `build` + - `verify` + - `deploy` +- grouping and examples in `sdp/docs/CLI_REFERENCE.md` + +## Out of Scope + +- public README and quickstart rewrite +- board UI implementation +- Beads state model changes +- deploy semantics beyond copy/help and stage framing + +## Acceptance Criteria + +1. Root help explains the mode split and points users to `status` and `next` for navigation. +2. Major command help follows one consistent stage-oriented template. +3. `sdp/docs/CLI_REFERENCE.md` matches runtime help and no longer describes a competing primary workflow. +4. A user can infer when to use `plan`, `apply`, `build`, `verify`, and `deploy` without reading historical plans. +5. Help-copy examples do not contradict the canonical board-to-deploy path. + +## Implementation Notes + +Likely touchpoints: + +- `sdp/sdp-plugin/cmd/sdp/*.go` +- `sdp/docs/CLI_REFERENCE.md` + +This work should be implemented in `sdp/` and then synced back into `sdp_lab` through the submodule update flow. diff --git a/docs/plans/2026-04-05-sdp-operator-mode-runtime-surface-spec.md b/docs/plans/2026-04-05-sdp-operator-mode-runtime-surface-spec.md new file mode 100644 index 00000000..8f68dc9d --- /dev/null +++ b/docs/plans/2026-04-05-sdp-operator-mode-runtime-surface-spec.md @@ -0,0 +1,104 @@ +# SDP Operator Mode Runtime Surface Spec + +> **Status:** Proposed +> **Date:** 2026-04-05 +> **Related issue:** `sdplab-20w` +> **Scope repo:** `sdp/` + +## Goal + +Define the runtime changes needed for SDP to make the board-backed Operator Mode promise credible. + +This is not a docs cleanup task. +It is a runtime surface spec for the CLI and supporting state exposure in `sdp/`. + +## Problem + +The canonical product story is: + +1. task enters board-backed queue +2. SDP shapes it +3. agents execute it +4. findings loop back into the same queue +5. the operator sees status and next action +6. the item reaches delivery with proof + +Today the runtime surfaces do not fully expose that story: + +- board semantics are mostly implicit +- `status` and `next` do not consistently expose queue truth, next actor, and delivery gating +- PR, findings, `QA/UAT`, and delivery states are not presented as one visible chain +- the operator still reconstructs too much manually from Beads, docs, and artifacts + +## Decision + +Operator Mode runtime surfaces must expose the same chain that the design docs now describe. + +The CLI does not need to become a board UI. +It does need to expose enough state to make the board-backed system legible. + +## Required Runtime Questions + +In Operator Mode, SDP should be able to answer these questions from runtime surfaces: + +1. what state is this item in right now? +2. why is it in that state? +3. who or what is expected next? +4. what is blocking progress? +5. what is the linked execution graph item? +6. what is the linked PR state? +7. what findings are still open? +8. has `QA/UAT` passed? +9. what human approval, if any, is still required? + +## Scope + +### In scope + +- `status` output contract +- `next` recommendation contract +- visibility of queue-backed state +- visibility of findings loop state +- visibility of PR / `QA/UAT` / delivery gating +- explicit Operator Mode framing in runtime text and JSON surfaces where relevant + +### Out of scope + +- full control-tower UI +- replacing Beads +- changing Beads as source of truth +- autonomous production deployment + +## Truth Model Constraints + +- `Beads` remains the operational source of truth +- board or status views are projections +- PR remains the integration surface +- `evidence`, `trace`, `drift`, and `QA/UAT` remain proof layers + +The runtime must reflect that instead of inventing a second queue model. + +## Candidate Surfaces + +- `sdp status` +- `sdp next` +- any future CLI board or queue summary commands +- exported JSON status contracts consumed by agents or other tooling + +## Acceptance Criteria + +1. Operator-facing runtime surfaces expose queue-backed current state and next actor. +2. Findings loop state is visible without manual artifact archaeology. +3. PR, `QA/UAT`, and delivery gates are represented as part of the same runtime story. +4. The runtime does not imply that board views or status views are the source of truth. +5. A colleague can inspect one item and understand where it is between intake and delivery without opening historical plans. + +## Implementation Notes + +Likely code areas: + +- `sdp/sdp-plugin/cmd/sdp/status*` +- `sdp/sdp-plugin/cmd/sdp/next*` +- any shared state/view builders behind those commands + +This spec should be decomposed into one or more `sdp/` implementation tasks after the owning issue is created. diff --git a/docs/reference/README.md b/docs/reference/README.md index 64579011..bfdd1a78 100644 --- a/docs/reference/README.md +++ b/docs/reference/README.md @@ -5,17 +5,19 @@ Use this directory for stable reference docs, not for historical planning archae Start here: 1. [project-map.md](project-map.md) — what `sdp_lab` is, what the current direction is, and which docs are canonical -2. [agent-catalog.md](agent-catalog.md) — default agent ownership across the canonical loop -3. [skills.md](skills.md) — public and internal skill surface -4. [commands.md](commands.md) — command reference +2. [canonical-happy-path.md](canonical-happy-path.md) — one stable description of Local Mode, Operator Mode, and board-to-delivery flow +3. [agent-catalog.md](agent-catalog.md) — default agent ownership across the canonical loop +4. [skills.md](skills.md) — public and internal skill surface +5. [commands.md](commands.md) — command reference ## Quick Find | Need | Reference | |---|---| | Project identity and read order | [project-map.md](project-map.md) | +| Canonical happy path and mode split | [canonical-happy-path.md](canonical-happy-path.md) | | Adopt SDP in another repo | [../../sdp/docs/QUICKSTART.md](../../sdp/docs/QUICKSTART.md) | -| Canonical loop and default agents | [agent-catalog.md](agent-catalog.md) | +| Canonical loop and default agents | [canonical-happy-path.md](canonical-happy-path.md), [agent-catalog.md](agent-catalog.md) | | Canonical skill surface | [skills.md](skills.md) | | Commands | [commands.md](commands.md) | | Quality gates | [quality-gates.md](quality-gates.md) | @@ -28,6 +30,7 @@ Start here: - prefer reference docs over dated plans when both exist - prefer `project-map.md` for orientation, then follow links into deeper docs +- prefer `canonical-happy-path.md` for the stable system story and use plans only for rationale or rollout detail - treat stale mentions of `sdp_dev`, `dev`, `master`, or `bd sync` as historical unless a live doc still says they are current ## Scope diff --git a/docs/reference/agent-catalog.md b/docs/reference/agent-catalog.md index a7801fd9..f1114b86 100644 --- a/docs/reference/agent-catalog.md +++ b/docs/reference/agent-catalog.md @@ -4,9 +4,16 @@ Status: canonical reference Canonical design reference: -- `docs/plans/2026-03-15-canonical-sdp-loop-and-agent-stack.md` +- `docs/reference/canonical-happy-path.md` +- `docs/plans/2026-04-05-canonical-sdp-happy-path-consistency.md` -This document defines the default SDP agent workflow. +This document defines the default SDP agent workflow for the canonical happy path. + +Mode note: + +- `Local Mode` is the adoption ramp +- this catalog primarily describes the agent ownership model for full `Operator Mode` +- skills and CLI remain control surfaces over the same stage model ## Canonical SDP Loop diff --git a/docs/reference/canonical-happy-path.md b/docs/reference/canonical-happy-path.md new file mode 100644 index 00000000..b308a342 --- /dev/null +++ b/docs/reference/canonical-happy-path.md @@ -0,0 +1,152 @@ +# Canonical Happy Path + +Status: canonical reference + +This is the shortest stable description of how SDP is supposed to work from intake to delivery. + +Use this doc when the question is: + +- what is the default SDP product path? +- how do board, Beads, skills, CLI, PR, and QA/UAT fit together? +- what is the difference between local onboarding and full operator mode? + +For rationale and rollout details, see [../plans/2026-04-05-canonical-sdp-happy-path-consistency.md](../plans/2026-04-05-canonical-sdp-happy-path-consistency.md). + +## Product Promise + +SDP should support one coherent story: + +1. work enters a board-backed queue +2. SDP shapes it with progressive disclosure +3. agents execute through a visible workflow +4. findings loop back into the same queue +5. the feature reaches a clean delivery path with proof + +Everything else is a control surface or a disclosure layer for that same story. + +## Two Modes + +### Local Mode + +Use this when a user wants SDP inside one repo and is not yet running a shared queue. + +Default path: + +1. install SDP +2. `sdp init` +3. `sdp doctor` +4. shape work locally +5. execute and verify locally + +Characteristics: + +- `Beads` is optional +- there may be no visible board UI +- skills and CLI are local control surfaces + +### Operator Mode + +Use this when SDP is presented as a queue or board system that carries work to deploy. + +Default path: + +1. task enters board-backed queue +2. clarification and shaping +3. executable graph becomes ready +4. early draft PR exists +5. agents execute +6. findings re-enter the queue +7. QA/UAT passes +8. human approves merge or delivery step + +Characteristics: + +- `Beads` is required +- the board is a projection over Beads-backed operational truth +- PR, findings, QA/UAT, and delivery are first-class stages + +## Source of Truth + +| Layer | Canonical truth | +|---|---| +| queue state | `Beads` | +| semantic intent | `feature` and `workstream` artifacts | +| integration state | branch + early `draft PR` | +| proof | `evidence`, `trace`, `drift`, `QA/UAT` artifacts | +| board/status views | derived projections | +| skills and CLI | control surfaces | + +Rule: + +- the board is not an independent store +- the board is a visibility surface over Beads-backed truth + +Reference: + +- [../decisions/ADR-BEADS-FIRST-SOURCE-OF-TRUTH.md](../decisions/ADR-BEADS-FIRST-SOURCE-OF-TRUTH.md) + +## Canonical Stages + +| Stage | Result | +|---|---| +| install and bootstrap | repo is ready to use SDP | +| intake | task exists in queue and is visible | +| clarification and shaping | accepted `feature`, `workstream`, and linked Beads graph | +| execution setup | branch and early `draft PR` exist | +| execution | change and execution evidence exist | +| findings loop | review, CI, drift, and QA findings re-enter queue | +| QA/UAT | `qa:pass` or `qa:fail` is explicit | +| delivery | clean PR plus approval or delivery proof | + +## Control Surfaces + +### Board and queue + +Use for: + +- visibility +- intake +- attention routing +- status and blockers + +### Skills + +Use for: + +- guided journeys +- clarification +- progressive disclosure +- agent-driven execution + +### CLI + +Use for: + +- explicit terminal control +- scripting +- machine-readable state +- deterministic automation + +Rule: + +- skills and CLI are not separate workflows +- they are two ways to drive the same stage model + +## Current Canonical References + +| Need | Doc | +|---|---| +| repo orientation | [project-map.md](project-map.md) | +| happy path overview | [canonical-happy-path.md](canonical-happy-path.md) | +| operator execution loop | [../SDP_OPERATOR_WORKFLOW.md](../SDP_OPERATOR_WORKFLOW.md) | +| agent ownership | [agent-catalog.md](agent-catalog.md) | +| skill surface | [skills.md](skills.md) | +| design rationale | [../plans/2026-04-05-canonical-sdp-happy-path-consistency.md](../plans/2026-04-05-canonical-sdp-happy-path-consistency.md) | + +## What This Doc Does Not Do + +- it does not replace public onboarding in `sdp/docs/QUICKSTART.md` +- it does not define exact CLI syntax +- it does not replace historical design rationale + +It defines the stable internal model that other docs must follow. diff --git a/docs/reference/project-map.md b/docs/reference/project-map.md index d75d4efb..7af81471 100644 --- a/docs/reference/project-map.md +++ b/docs/reference/project-map.md @@ -72,7 +72,8 @@ Use one source per question. | What repo owns this file? | [docs/MULTI-REPO-WORKFLOW.md](../MULTI-REPO-WORKFLOW.md) | | What belongs in `sdp_lab` vs `sdp`? | [docs/architecture/REPO-BOUNDARY.md](../architecture/REPO-BOUNDARY.md) | | How do I adopt SDP in another repo? | [../../sdp/docs/QUICKSTART.md](../../sdp/docs/QUICKSTART.md) | -| What is the canonical operator loop? | [docs/plans/2026-03-15-canonical-sdp-loop-and-agent-stack.md](../plans/2026-03-15-canonical-sdp-loop-and-agent-stack.md) | +| What is the canonical happy path from intake to delivery? | [canonical-happy-path.md](canonical-happy-path.md) | +| What is the canonical operator loop? | [canonical-happy-path.md](canonical-happy-path.md), [docs/SDP_OPERATOR_WORKFLOW.md](../SDP_OPERATOR_WORKFLOW.md) | | What agents and skills are on the happy path? | [agent-catalog.md](agent-catalog.md), [skills.md](skills.md) | | What is ready or blocked right now? | `bd ready` and `bd show` are authoritative; `docs/workstreams/INDEX.md` is only the planning summary | | What work exists in backlog form? | `docs/workstreams/backlog/` is canonical backlog; `.beads-sdp-mapping.jsonl` is helper data, not full historical coverage | @@ -81,7 +82,23 @@ Use one source per question. ## Canonical Happy Path -Default workflow: +The canonical system story is stage-first: + +1. install and bootstrap +2. intake into a board-backed queue +3. clarification and shaping +4. execution setup with early draft PR +5. execution +6. findings loop +7. `QA/UAT` +8. delivery + +That story has two explicit modes: + +- `Local Mode` — adoption ramp inside one repo, where `Beads` may still be optional +- `Operator Mode` — full board-to-delivery path, where `Beads` is required and board views are projections over Beads-backed truth + +Default operator workflow: 1. shape `vision` or `feature` 2. decompose into `workstream` and linked `beads issue` @@ -94,9 +111,11 @@ Default workflow: Canonical references: -- [docs/plans/2026-03-15-canonical-sdp-loop-and-agent-stack.md](../plans/2026-03-15-canonical-sdp-loop-and-agent-stack.md) +- [canonical-happy-path.md](canonical-happy-path.md) +- [docs/SDP_OPERATOR_WORKFLOW.md](../SDP_OPERATOR_WORKFLOW.md) - [agent-catalog.md](agent-catalog.md) - [skills.md](skills.md) +- [docs/plans/2026-04-05-canonical-sdp-happy-path-consistency.md](../plans/2026-04-05-canonical-sdp-happy-path-consistency.md) ## Read Order @@ -104,9 +123,10 @@ If you are new to this repo, read in this order: 1. [AGENTS.md](../../AGENTS.md) 2. [docs/reference/project-map.md](project-map.md) -3. [docs/roadmap/ROADMAP.md](../roadmap/ROADMAP.md) -4. [docs/workstreams/INDEX.md](../workstreams/INDEX.md) -5. [docs/SDP_OPERATOR_WORKFLOW.md](../SDP_OPERATOR_WORKFLOW.md) +3. [docs/reference/canonical-happy-path.md](canonical-happy-path.md) +4. [docs/roadmap/ROADMAP.md](../roadmap/ROADMAP.md) +5. [docs/workstreams/INDEX.md](../workstreams/INDEX.md) +6. [docs/SDP_OPERATOR_WORKFLOW.md](../SDP_OPERATOR_WORKFLOW.md) If you are new to SDP but not to this repo, use this shorter decision: diff --git a/docs/reference/skills.md b/docs/reference/skills.md index 3e400730..b0a7253c 100644 --- a/docs/reference/skills.md +++ b/docs/reference/skills.md @@ -4,10 +4,19 @@ Status: canonical reference Canonical design reference: -- `docs/plans/2026-03-15-canonical-sdp-loop-and-agent-stack.md` +- `docs/reference/canonical-happy-path.md` +- `docs/plans/2026-04-05-canonical-sdp-happy-path-consistency.md` This document defines the public SDP skill surface and the internal or conditional skills that support the canonical workflow. +Skills are the guided control surface over the canonical stage model. +They are not a second workflow separate from board state, Beads, CLI, PR, or `QA/UAT`. + +Mode note: + +- `Local Mode` may use skills without a full shared queue +- full board-backed `Operator Mode` still depends on Beads-backed operational truth + ## Canonical Public Surface The public happy path is: From 165e3610e37ef109f89b09f7c13fd55e197a2c63 Mon Sep 17 00:00:00 2001 From: Andrei Date: Sun, 5 Apr 2026 13:48:34 +0300 Subject: [PATCH 17/17] docs: sync sdp runtime-truth doc alignment --- .beads/interactions.jsonl | 3 +++ sdp | 2 +- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/.beads/interactions.jsonl b/.beads/interactions.jsonl index c6f2b204..e6d0bc77 100644 --- a/.beads/interactions.jsonl +++ b/.beads/interactions.jsonl @@ -175,3 +175,6 @@ {"id":"int-a82a0bfb","kind":"field_change","created_at":"2026-04-05T10:08:48.757787Z","actor":"Andrei","issue_id":"sdplab-mkv","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: canonical happy path consistency design written with modes, truth model, stage model, surface ownership, and rollout phases"}} {"id":"int-79bb3929","kind":"field_change","created_at":"2026-04-05T10:26:18.759707Z","actor":"Andrei","issue_id":"sdplab-5fk","extra":{"field":"status","new_value":"in_progress","old_value":"open"}} {"id":"int-af79d1e4","kind":"field_change","created_at":"2026-04-05T10:29:50.563288Z","actor":"Andrei","issue_id":"sdplab-5fk","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: sdp_lab canonical docs now point to one stable happy-path reference, Operator Mode is explicit, and deferred runtime changes are captured in separate specs"}} +{"id":"int-e47dca6c","kind":"field_change","created_at":"2026-04-05T10:34:09.214698Z","actor":"Andrei","issue_id":"sdplab-rzk","extra":{"field":"status","new_value":"in_progress","old_value":"open"}} +{"id":"int-54f54eb5","kind":"field_change","created_at":"2026-04-05T10:48:16.558186Z","actor":"Andrei","issue_id":"sdplab-rzk","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done"}} +{"id":"int-130168d3","kind":"field_change","created_at":"2026-04-05T10:48:16.97244Z","actor":"Andrei","issue_id":"sdplab-0s1","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"Done"}} diff --git a/sdp b/sdp index 25773b64..1dd11370 160000 --- a/sdp +++ b/sdp @@ -1 +1 @@ -Subproject commit 25773b648120d7660c367ef86c08215cea7c37d9 +Subproject commit 1dd11370217baa0e37f86a4aef944d157f0ac36e