From 5cfea93afe0a5ac7b8a94a7a915cddad64d5a22f Mon Sep 17 00:00:00 2001 From: Diego Andres Rabaioli Date: Thu, 18 Jun 2026 15:49:46 +0200 Subject: [PATCH] Prefix all CDD slash commands with `cdd-` (#27) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rename every CDD slash command to a `cdd-` prefixed name so they autocomplete as a discoverable group: /next-step→/cdd-next-step, /pre-pr→/cdd-pre-pr, /merge-main→/cdd-merge-main, /process-pr→/cdd-process-pr, /bootstrap→/cdd-bootstrap, /retrofit→/cdd-retrofit, /quick-create→/cdd-quick-create. Renames all 11 command files (7 repo + 4 template copies), sweeps every cross-reference across the process doc, template, demo, docs, and the in-helper `/next-step` hints, and updates the drift-check machinery (`command-drift-whitelist.txt`, `command-drift-check.sh`). Records the work as a completed item under roadmap Phase 8. Clean rename: no backward-compatible aliases. Scope is slash commands only; the `cdd-worktree`/`-worktree` shell helper naming is left to issue #24. Co-Authored-By: Claude Opus 4.8 (1M context) --- .../{bootstrap.md => cdd-bootstrap.md} | 12 +- .../{merge-main.md => cdd-merge-main.md} | 6 +- .../{next-step.md => cdd-next-step.md} | 2 +- .claude/commands/{pre-pr.md => cdd-pre-pr.md} | 8 +- .../{process-pr.md => cdd-process-pr.md} | 8 +- .../{quick-create.md => cdd-quick-create.md} | 14 +- .../commands/{retrofit.md => cdd-retrofit.md} | 12 +- CLAUDE.md | 16 +-- README.md | 12 +- demo/README.md | 8 +- demo/seed/CLAUDE.md | 6 +- demo/seed/doc/architecture/overview.md | 2 +- demo/seed/doc/features/overview.md | 2 +- demo/seed/doc/knowledge_base/roadmap.md | 4 +- demo/setup.sh | 4 +- doc/architecture/bootstrap-and-retrofit.md | 8 +- doc/architecture/demo.md | 2 +- doc/architecture/index.md | 2 +- doc/architecture/overview.md | 2 +- doc/features/demo.md | 2 +- doc/features/index.md | 2 +- doc/features/template.md | 20 +-- doc/knowledge_base/README.md | 2 +- .../claude-driven-development.md | 134 +++++++++--------- doc/knowledge_base/roadmap.md | 65 ++++----- scripts/command-drift-check.sh | 6 +- scripts/command-drift-whitelist.txt | 6 +- .../{merge-main.md => cdd-merge-main.md} | 6 +- .../{next-step.md => cdd-next-step.md} | 2 +- .../commands/{pre-pr.md => cdd-pre-pr.md} | 6 +- .../{process-pr.md => cdd-process-pr.md} | 8 +- template/BOOTSTRAP.md | 18 +-- template/CLAUDE.md | 8 +- template/doc/index.md | 2 +- template/doc/knowledge_base/README.md | 2 +- template/tools/PROJECT-worktree.sh | 4 +- tools/bootstrap-cdd-project.sh | 16 +-- tools/cdd-worktree.sh | 4 +- 38 files changed, 222 insertions(+), 221 deletions(-) rename .claude/commands/{bootstrap.md => cdd-bootstrap.md} (91%) rename .claude/commands/{merge-main.md => cdd-merge-main.md} (93%) rename .claude/commands/{next-step.md => cdd-next-step.md} (99%) rename .claude/commands/{pre-pr.md => cdd-pre-pr.md} (93%) rename .claude/commands/{process-pr.md => cdd-process-pr.md} (95%) rename .claude/commands/{quick-create.md => cdd-quick-create.md} (71%) rename .claude/commands/{retrofit.md => cdd-retrofit.md} (91%) rename template/.claude/commands/{merge-main.md => cdd-merge-main.md} (93%) rename template/.claude/commands/{next-step.md => cdd-next-step.md} (99%) rename template/.claude/commands/{pre-pr.md => cdd-pre-pr.md} (96%) rename template/.claude/commands/{process-pr.md => cdd-process-pr.md} (95%) diff --git a/.claude/commands/bootstrap.md b/.claude/commands/cdd-bootstrap.md similarity index 91% rename from .claude/commands/bootstrap.md rename to .claude/commands/cdd-bootstrap.md index b32378d..d11606f 100644 --- a/.claude/commands/bootstrap.md +++ b/.claude/commands/cdd-bootstrap.md @@ -1,6 +1,6 @@ -Scaffold a new greenfield project on the CDD workflow: `/bootstrap` (takes no argument). +Scaffold a new greenfield project on the CDD workflow: `/cdd-bootstrap` (takes no argument). -Run this command from a CDD-repo session (it needs the CDD repo's `template/` and `bootstrap-cdd-project.sh`). This command exists only in the CDD repo; it deliberately has no counterpart in `template/.claude/commands/` (it operates *on* a new target project, so downstream projects have no use for it — see the process doc, Section 2.7). It is the greenfield sibling of `/retrofit`: `/retrofit` adapts an *existing* project, `/bootstrap` creates a *new* one. +Run this command from a CDD-repo session (it needs the CDD repo's `template/` and `bootstrap-cdd-project.sh`). This command exists only in the CDD repo; it deliberately has no counterpart in `template/.claude/commands/` (it operates *on* a new target project, so downstream projects have no use for it — see the process doc, Section 2.7). It is the greenfield sibling of `/cdd-retrofit`: `/cdd-retrofit` adapts an *existing* project, `/cdd-bootstrap` creates a *new* one. This is a **guided** command, not a brief-to-files converter. The discovery conversation is part of the job: you walk the user through defining the project, then encode the result into the initial docs and roadmap, then scaffold the project in a single bootstrap invocation. The generated project starts with a real, filled-in overview, `CLAUDE.md`, and roadmap — not the template's pre-filled "survey the codebase" bootstrap phase, which is for files-only installs. @@ -22,7 +22,7 @@ Have a conversation to define the project. Do not dump a rigid questionnaire; as The user may not have firm answers for everything; capture intent and mark genuinely open areas rather than inventing detail. This material becomes the project overview (`doc/knowledge_base/project-overview.md`) and seeds `CLAUDE.md`. -**Off-ramp:** if discovery reveals this isn't really a project — a single self-contained artifact, finished in essentially one sitting, used as-is by future-you — apply the shared scope-triage heuristic (process doc, Section 6) and **offer to drop to `/quick-create`** instead of scaffolding the full substrate. Surface the signals; the human decides. +**Off-ramp:** if discovery reveals this isn't really a project — a single self-contained artifact, finished in essentially one sitting, used as-is by future-you — apply the shared scope-triage heuristic (process doc, Section 6) and **offer to drop to `/cdd-quick-create`** instead of scaffolding the full substrate. Surface the signals; the human decides. **Checkpoint:** present a structured summary of the captured definition (the seven headings above). Get explicit confirmation or corrections before writing anything. @@ -56,7 +56,7 @@ The bootstrap script refuses a path that already exists and is non-empty, so che [[ -e "" && -n "$(ls -A "" 2>/dev/null)" ]] && echo "exists and non-empty" ``` -If it exists and is non-empty, stop and ask for a different location — `/bootstrap` is for greenfield. (Suggest `/retrofit` if the user actually meant to install CDD into an existing project.) An absent path or an empty directory is fine. +If it exists and is non-empty, stop and ask for a different location — `/cdd-bootstrap` is for greenfield. (Suggest `/cdd-retrofit` if the user actually meant to install CDD into an existing project.) An absent path or an empty directory is fine. **Checkpoint:** confirm the target path before staging the overlay. @@ -118,6 +118,6 @@ Report: [[ -f "/tools/-worktree.sh" ]] && source "/tools/-worktree.sh" ``` -- The next command: `cd `, run `claude`, and `/next-step` — it picks up the real first phase of the roadmap. Unlike a files-only install, there is **no** codebase-survey bootstrap phase to clear first; the docs are already populated. +- The next command: `cd `, run `claude`, and `/cdd-next-step` — it picks up the real first phase of the roadmap. Unlike a files-only install, there is **no** codebase-survey bootstrap phase to clear first; the docs are already populated. -(The bootstrap script prints its own generic "fill in CLAUDE.md / look at the pre-filled roadmap" block; your summary supersedes it for the `/bootstrap` path, where those are already done.) +(The bootstrap script prints its own generic "fill in CLAUDE.md / look at the pre-filled roadmap" block; your summary supersedes it for the `/cdd-bootstrap` path, where those are already done.) diff --git a/.claude/commands/merge-main.md b/.claude/commands/cdd-merge-main.md similarity index 93% rename from .claude/commands/merge-main.md rename to .claude/commands/cdd-merge-main.md index 50934eb..4fc8fba 100644 --- a/.claude/commands/merge-main.md +++ b/.claude/commands/cdd-merge-main.md @@ -140,7 +140,7 @@ adopt: ## 7. Verify -Run the project build and tests to confirm the merged state is healthy. Use the same commands as `/pre-pr` step 2, with the same "tail 40 lines + exit code" capture pattern. +Run the project build and tests to confirm the merged state is healthy. Use the same commands as `/cdd-pre-pr` step 2, with the same "tail 40 lines + exit code" capture pattern. If anything fails, report the failure and stop. Do not push. @@ -156,7 +156,7 @@ Present a final summary: - [ ] Build passes - [ ] Tests pass -Next: re-run /pre-pr before opening or updating the PR. +Next: re-run /cdd-pre-pr before opening or updating the PR. ``` -The user should re-run `/pre-pr` in a fresh session after `/merge-main` to ensure the merged state passes all gates. +The user should re-run `/cdd-pre-pr` in a fresh session after `/cdd-merge-main` to ensure the merged state passes all gates. diff --git a/.claude/commands/next-step.md b/.claude/commands/cdd-next-step.md similarity index 99% rename from .claude/commands/next-step.md rename to .claude/commands/cdd-next-step.md index db5333a..eae72ad 100644 --- a/.claude/commands/next-step.md +++ b/.claude/commands/cdd-next-step.md @@ -112,7 +112,7 @@ When you defer a question, list it explicitly in the handoff's Notes section so When the user signals they're ready, draft: -**Branch name**: short, lowercase, underscore-separated. No `fix/` / `feature/` prefix. Derive from the task (e.g. `imu_calibration_wiring`, `setpoint_timeout_handling`). **Issue-driven mode**: prefix the name with the fixed `gh_issue_NN_` token so the issue number is durable and groups cleanly — `gh_issue_NN_` (e.g. `gh_issue_42_dark_mode`). This token is the sole mechanism threading the issue to its PR (`/pre-pr` turns it into `Closes #NN`). +**Branch name**: short, lowercase, underscore-separated. No `fix/` / `feature/` prefix. Derive from the task (e.g. `imu_calibration_wiring`, `setpoint_timeout_handling`). **Issue-driven mode**: prefix the name with the fixed `gh_issue_NN_` token so the issue number is durable and groups cleanly — `gh_issue_NN_` (e.g. `gh_issue_42_dark_mode`). This token is the sole mechanism threading the issue to its PR (`/cdd-pre-pr` turns it into `Closes #NN`). **Implementation prompt**: a self-contained prompt for the new session. Critical rule, the new session will read `CLAUDE.md`, the roadmap, and the architecture/feature docs itself. Include only context that is **not** inferable from the repo: diff --git a/.claude/commands/pre-pr.md b/.claude/commands/cdd-pre-pr.md similarity index 93% rename from .claude/commands/pre-pr.md rename to .claude/commands/cdd-pre-pr.md index acc7989..7f13187 100644 --- a/.claude/commands/pre-pr.md +++ b/.claude/commands/cdd-pre-pr.md @@ -71,7 +71,7 @@ git fetch origin main git log --oneline HEAD..origin/main ``` -If `origin/main` has advanced beyond the branch point, mention it and recommend running `/merge-main` before opening the PR. Do not merge from this session. +If `origin/main` has advanced beyond the branch point, mention it and recommend running `/cdd-merge-main` before opening the PR. Do not merge from this session. ## Command-set drift (CDD repo only) @@ -82,7 +82,7 @@ This check is specific to the CDD repo (the meta-project): it surfaces unintende ./scripts/command-drift-check.sh ``` -The script renders the template through `bootstrap-cdd-project.sh --stage` with this repo's own identifiers, so expected substitution drift cancels out mechanically. Intentionally one-sided files are listed in `scripts/command-drift-whitelist.txt`; CDD-meta-only sections of shared files (such as this one) are fenced with `cdd-only` markers and stripped before comparison. The same script asserts that the handoff schema headings match between the process doc (Section 2.6) and `next-step.md`, that the worktree helpers (`tools/cdd-worktree.sh` vs the rendered template helper) match from the first function definition onward, and that no `cdd-only` markers leak into the template itself. CI runs it on every PR via `template-smoke.yml`. +The script renders the template through `bootstrap-cdd-project.sh --stage` with this repo's own identifiers, so expected substitution drift cancels out mechanically. Intentionally one-sided files are listed in `scripts/command-drift-whitelist.txt`; CDD-meta-only sections of shared files (such as this one) are fenced with `cdd-only` markers and stripped before comparison. The same script asserts that the handoff schema headings match between the process doc (Section 2.6) and `cdd-next-step.md`, that the worktree helpers (`tools/cdd-worktree.sh` vs the rendered template helper) match from the first function definition onward, and that no `cdd-only` markers leak into the template itself. CI runs it on every PR via `template-smoke.yml`. If the script exits 0, report "no drift" and continue. If it reports divergence, present each diff to the user; for each, the user decides whether to reconcile the repo copy, reconcile the template copy, or record a justified exception (a whitelist entry or a `cdd-only` fence). Apply fixes only on user approval. Do not auto-edit either tree from this step. @@ -106,7 +106,7 @@ Present a checklist summary: - [ ] README up to date - [ ] Roadmap up to date - [ ] CI gaps surfaced: none / proposed (list them) -- [ ] No upstream drift (or: /merge-main recommended) +- [ ] No upstream drift (or: /cdd-merge-main recommended) - [ ] Reconciliation edits committed ``` @@ -140,7 +140,7 @@ gh auth status && git remote get-url origin # origin should be a github.com UR If either is missing, say so in one line and skip this step (the checklist above still stands). -If §6 found upstream drift, restate the recommendation to run `/merge-main` before opening the PR, and let the user decide whether to proceed anyway. +If §6 found upstream drift, restate the recommendation to run `/cdd-merge-main` before opening the PR, and let the user decide whether to proceed anyway. Ask: **"Open a PR now?"** Do not pre-show a title or body, and do not print manual `gh` instructions — just ask whether to proceed. diff --git a/.claude/commands/process-pr.md b/.claude/commands/cdd-process-pr.md similarity index 95% rename from .claude/commands/process-pr.md rename to .claude/commands/cdd-process-pr.md index 2024fa4..2b02f14 100644 --- a/.claude/commands/process-pr.md +++ b/.claude/commands/cdd-process-pr.md @@ -1,8 +1,8 @@ Address the open PR's review feedback: read the review comments for the current branch, triage them, implement the change-requests (pushing back where warranted), then auto-post in-thread replies and auto-commit + push the result. -Run this command on the feature branch (not on main), after a PR has been opened and someone has reviewed it. It is a post-review side-loop, analogous in position to `/merge-main`. +Run this command on the feature branch (not on main), after a PR has been opened and someone has reviewed it. It is a post-review side-loop, analogous in position to `/cdd-merge-main`. -**Note on automation:** this command has a single checkpoint, placed up front: the triage plan in step 4. Once the user approves that plan, the rest of the run — edits, in-thread replies, commit, push — executes without further confirmation gates (see the process doc, "The `/process-pr` exception"). Do not add per-action gates after the plan is approved. Review threads are never resolved by this command; the user resolves them. +**Note on automation:** this command has a single checkpoint, placed up front: the triage plan in step 4. Once the user approves that plan, the rest of the run — edits, in-thread replies, commit, push — executes without further confirmation gates (see the process doc, "The `/cdd-process-pr` exception"). Do not add per-action gates after the plan is approved. Review threads are never resolved by this command; the user resolves them. ## 1. Discover the open PR @@ -89,7 +89,7 @@ Classify each open item and present a short plan to the user **before editing an Present the plan compactly, e.g.: ``` -## /process-pr triage (PR #NUMBER) +## /cdd-process-pr triage (PR #NUMBER) 1. [change-request] src/foo.ts:42 — "rename to X" → will rename. 2. [question] review summary — "why no retry?" → will answer, no code change. @@ -147,7 +147,7 @@ Push to the PR branch. Sequencing note: if you want the reply in step 6 to cite Summarize what was processed: ``` -## /process-pr summary (PR #NUMBER) +## /cdd-process-pr summary (PR #NUMBER) - Threads addressed: - Questions answered: - Change-requests declined: (replies explain why) diff --git a/.claude/commands/quick-create.md b/.claude/commands/cdd-quick-create.md similarity index 71% rename from .claude/commands/quick-create.md rename to .claude/commands/cdd-quick-create.md index 9491d8d..b004c3c 100644 --- a/.claude/commands/quick-create.md +++ b/.claude/commands/cdd-quick-create.md @@ -1,18 +1,18 @@ -Produce a small, self-contained deliverable — a script plus a README, not a full CDD project: `/quick-create` (takes an optional one-line description of what to build). +Produce a small, self-contained deliverable — a script plus a README, not a full CDD project: `/cdd-quick-create` (takes an optional one-line description of what to build). -Run this command from a CDD-repo session. It is the third sibling of `/bootstrap` and `/retrofit`: `/bootstrap` creates a new CDD *project*, `/retrofit` adapts an *existing* one, and `/quick-create` creates a lightweight *deliverable* — a one-off artifact with none of the project substrate (no roadmap, no `doc/` tree, no `.claude/commands/`, no worktree helper, no baseline marker, no `/pre-pr` lifecycle). Like its siblings it exists only in the CDD repo and has no counterpart in `template/.claude/commands/`; unlike them it needs neither `template/` nor the bootstrap script, because a one-off has no template — it writes plain files directly (see the process doc, Section 6). +Run this command from a CDD-repo session. It is the third sibling of `/cdd-bootstrap` and `/cdd-retrofit`: `/cdd-bootstrap` creates a new CDD *project*, `/cdd-retrofit` adapts an *existing* one, and `/cdd-quick-create` creates a lightweight *deliverable* — a one-off artifact with none of the project substrate (no roadmap, no `doc/` tree, no `.claude/commands/`, no worktree helper, no baseline marker, no `/cdd-pre-pr` lifecycle). Like its siblings it exists only in the CDD repo and has no counterpart in `template/.claude/commands/`; unlike them it needs neither `template/` nor the bootstrap script, because a one-off has no template — it writes plain files directly (see the process doc, Section 6). -This is a **guided** command, but deliberately lighter than `/bootstrap`: a few natural questions, not the seven discovery headings. What it keeps from CDD is the part that pays off even for a one-off — a little guided discovery, clean single-purpose code, and a README so future-you can use it. What it drops is everything a single artifact doesn't need. +This is a **guided** command, but deliberately lighter than `/cdd-bootstrap`: a few natural questions, not the seven discovery headings. What it keeps from CDD is the part that pays off even for a one-off — a little guided discovery, clean single-purpose code, and a README so future-you can use it. What it drops is everything a single artifact doesn't need. **Checkpoint discipline:** confirm the scope (step 1), then the captured definition (step 2), then the name and target (step 3) — each before moving on. The deliverable is written **files-first** (step 4), before any version control. The two outward-facing actions — a local commit (step 6) and a GitHub repo (step 7) — are offered separately, confirmed individually, and never done silently or by default. ## 1. Scope check (the gate) -Before discovery, confirm this is actually a deliverable and not a project. Apply the shared scope-triage heuristic (process doc, Section 6): a task is a **project** (→ `/bootstrap`) when any of these hold — it is expected to evolve across many sessions and needs a roadmap; it has more than one cooperating component or an architecture worth documenting; it involves multiple collaborators or handoffs; it is long-lived and will accrete features. It is a **deliverable** (→ `/quick-create`) when none hold: a single self-contained artifact, finished in essentially one sitting, used as-is by future-you. +Before discovery, confirm this is actually a deliverable and not a project. Apply the shared scope-triage heuristic (process doc, Section 6): a task is a **project** (→ `/cdd-bootstrap`) when any of these hold — it is expected to evolve across many sessions and needs a roadmap; it has more than one cooperating component or an architecture worth documenting; it involves multiple collaborators or handoffs; it is long-lived and will accrete features. It is a **deliverable** (→ `/cdd-quick-create`) when none hold: a single self-contained artifact, finished in essentially one sitting, used as-is by future-you. -If, from the description (`$ARGUMENTS`) or an opening exchange, project-signals trip, **surface them and offer to switch to `/bootstrap`** rather than proceeding. The human decides. +If, from the description (`$ARGUMENTS`) or an opening exchange, project-signals trip, **surface them and offer to switch to `/cdd-bootstrap`** rather than proceeding. The human decides. -**Checkpoint:** if any project-signal is present, name it and get an explicit "stay lightweight" or "switch to `/bootstrap`" before continuing. +**Checkpoint:** if any project-signal is present, name it and get an explicit "stay lightweight" or "switch to `/cdd-bootstrap`" before continuing. ## 2. Lightweight discovery @@ -89,4 +89,4 @@ Report: - What was written: the artifact(s) and the README, plus any optional extras (inline dependency metadata, license header). - Whether a smoke test ran and its result. - Whether a local commit was made (step 6) and whether a GitHub repo was created (step 7). -- That this is a **deliverable**, not a project: there is no roadmap, worktree helper, or `/pre-pr` lifecycle. If it later grows into a project, `/retrofit` can install CDD onto it. +- That this is a **deliverable**, not a project: there is no roadmap, worktree helper, or `/cdd-pre-pr` lifecycle. If it later grows into a project, `/cdd-retrofit` can install CDD onto it. diff --git a/.claude/commands/retrofit.md b/.claude/commands/cdd-retrofit.md similarity index 91% rename from .claude/commands/retrofit.md rename to .claude/commands/cdd-retrofit.md index 0c0f0e9..2776702 100644 --- a/.claude/commands/retrofit.md +++ b/.claude/commands/cdd-retrofit.md @@ -1,4 +1,4 @@ -Install CDD into an existing project, or upgrade a project already running CDD, at the path given as argument: `/retrofit `. +Install CDD into an existing project, or upgrade a project already running CDD, at the path given as argument: `/cdd-retrofit `. Run this command from a CDD-repo session (it needs the CDD repo's `template/`, `bootstrap-cdd-project.sh`, and git history). The mode — **install** or **upgrade** — is auto-detected from the target. This command exists only in the CDD repo; it deliberately has no counterpart in `template/.claude/commands/` (it operates *on* target projects, so downstream projects have no use for it — see the process doc, Section 2.7). @@ -27,7 +27,7 @@ Also note `/.gitignore`: if any path the retrofit will write (`.claude/` Probe for CDD scaffolding in the target: ```bash -ls /.claude/commands/next-step.md /doc/knowledge_base/roadmap.md 2>/dev/null +ls /.claude/commands/cdd-next-step.md /doc/knowledge_base/roadmap.md 2>/dev/null ``` - Either file present → **upgrade mode** (section 4). @@ -61,7 +61,7 @@ WT="$(dirname "")/$(basename "")-$BRANCH" ## 3. Install mode -A files-only install of the template. No codebase survey, no generated architecture doc or roadmap — the template roadmap ships with a pre-filled bootstrap phase (survey the codebase, draft the initial architecture docs, write the feature docs, fill in the roadmap), so the project's first `/next-step` picks those up as the next unchecked tasks. +A files-only install of the template. No codebase survey, no generated architecture doc or roadmap — the template roadmap ships with a pre-filled bootstrap phase (survey the codebase, draft the initial architecture docs, write the feature docs, fill in the roadmap), so the project's first `/cdd-next-step` picks those up as the next unchecked tasks. ### 3.1 Confirm the three identifiers @@ -90,7 +90,7 @@ Walk every file in `$STAGE/render`. All writes go into `$WT` (the isolated workt - **Absent in `$WT`** → copy it directly (create parent dirs as needed). This covers the slash commands, doc skeletons, the worktree helper, `.claude/settings.json`, and the marker in the common case. - **Present in `$WT`** (collision — typically `CLAUDE.md`, sometimes `doc/` files or `.claude/settings.json`) → propose a merge interactively, one file at a time: - - `CLAUDE.md`: keep the project's existing content; propose adding the CDD pieces it lacks (the Key references table rows for `doc/`, and the Workflow section referencing `/next-step`, `/pre-pr`, `/merge-main`). Show the proposed result; apply only on approval. + - `CLAUDE.md`: keep the project's existing content; propose adding the CDD pieces it lacks (the Key references table rows for `doc/`, and the Workflow section referencing `/cdd-next-step`, `/cdd-pre-pr`, `/cdd-merge-main`). Show the proposed result; apply only on approval. - `.claude/settings.json`: merge the `permissions.allow` arrays (union); show the result before writing. - Anything else: show both versions and propose the merge; the user decides per file. - Never delete or move existing files. @@ -106,7 +106,7 @@ Walk every file in `$STAGE/render`. All writes go into `$WT` (the isolated workt ``` Stage with `add -A` — the worktree was fresh, so this captures exactly the retrofit's writes. Gitignored paths won't be staged (see the section 1 gitignore warning). Commit only on this dedicated branch; never commit onto the target's existing branches. -- Print next steps: the exact `source` line for `$WT/tools/-worktree.sh` (and, after merge, `/tools/...`) to add to `~/.bashrc`; how to review and merge the branch (`git -C "$WT" show`, then open a PR from `cdd-retrofit`); and that once merged they can remove the worktree with `git -C worktree remove "$WT"`. Then run `/next-step` in the target — it will pick up the roadmap's pre-filled bootstrap tasks (codebase survey, initial architecture and feature docs, CLAUDE.md stubs, roadmap fill) as the first task. Warn the user: on an existing project without prior doc discipline this first task is a doc reconciliation that forces the docs to match the code for the first time, so it may be slow and span several early PRs — that is expected, not a fault. Where docs already exist, it reconciles and adopts them rather than overwriting. +- Print next steps: the exact `source` line for `$WT/tools/-worktree.sh` (and, after merge, `/tools/...`) to add to `~/.bashrc`; how to review and merge the branch (`git -C "$WT" show`, then open a PR from `cdd-retrofit`); and that once merged they can remove the worktree with `git -C worktree remove "$WT"`. Then run `/cdd-next-step` in the target — it will pick up the roadmap's pre-filled bootstrap tasks (codebase survey, initial architecture and feature docs, CLAUDE.md stubs, roadmap fill) as the first task. Warn the user: on an existing project without prior doc discipline this first task is a doc reconciliation that forces the docs to match the code for the first time, so it may be slow and span several early PRs — that is expected, not a fault. Where docs already exist, it reconciles and adopts them rather than overwriting. ## 4. Upgrade mode @@ -199,4 +199,4 @@ Report, in both modes: - The marker value written. - Upstream candidates surfaced (upgrade mode), with a pointer to file them as a roadmap item in the CDD repo. - Any gitignore warnings from step 1. -- The next steps for the user: review the retrofit branch and open a PR from it; remove the worktree once merged (`git -C worktree remove "$WT"`); `/next-step` for fresh installs — noting that for a first-time install without prior doc discipline that first `/next-step` is a doc reconciliation that may be slow and span several early PRs (expected, not a fault). +- The next steps for the user: review the retrofit branch and open a PR from it; remove the worktree once merged (`git -C worktree remove "$WT"`); `/cdd-next-step` for fresh installs — noting that for a first-time install without prior doc discipline that first `/cdd-next-step` is a doc reconciliation that may be slow and span several early PRs (expected, not a fault). diff --git a/CLAUDE.md b/CLAUDE.md index 549e586..7751d0b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -14,8 +14,8 @@ CDD is a human-in-the-loop workflow for evolving software projects together with | Features of this repo | `doc/features/index.md` | | Template (what gets copied into new projects) | `template/` | | Bootstrap procedure for new projects | `template/BOOTSTRAP.md` | -| Guided greenfield bootstrap | `.claude/commands/bootstrap.md` (`/bootstrap`) | -| Lightweight one-off deliverable | `.claude/commands/quick-create.md` (`/quick-create`) | +| Guided greenfield bootstrap | `.claude/commands/cdd-bootstrap.md` (`/cdd-bootstrap`) | +| Lightweight one-off deliverable | `.claude/commands/cdd-quick-create.md` (`/cdd-quick-create`) | | Non-interactive bootstrap script | `tools/bootstrap-cdd-project.sh` | | Demo / dogfooding subsystem (seed + automation) | `demo/` (start with `demo/README.md`) | @@ -30,7 +30,7 @@ Each doc directory keeps an `index.md` pointer list: read the index, then load o - Template files use a three-identifier placeholder model — `` (display), `` (shell-command slug), `` (directory/repo slug) — plus a bare `PROJECT` token internal to `template/tools/PROJECT-worktree.sh` (substitution artifact, valued the same as ``). Free-form `<...>` text is fill-in content. Do not introduce a templating engine; placeholders must remain plain text so the template stays human-readable and Claude-readable. See section 2.9 of the process doc for the model, and `template/BOOTSTRAP.md` for the bootstrap recipe. - The template is generic. Do not introduce content drawn from a specific downstream project (e.g. firmware-specific conventions, web-specific build commands) into `template/` files. Per-project-type variants are deferred design (see process doc section 6). - `demo/` is a third artifact, separate from `template/` and `scripts/`. Its filled-in seed (`demo/seed/`) holds concrete "Markdown Renderer" project content — which is allowed *because* it lives under `demo/`. None of it may leak into `template/`. `demo/setup.sh` must keep wrapping `bootstrap-cdd-project.sh` (via `--overlay`) rather than duplicating the substitution logic. -- The CDD repo's own `.claude/commands/` and the template's `.claude/commands/` may drift slightly if needed, but unintended drift is a defect. `scripts/command-drift-check.sh` (run by CI and `/pre-pr`) verifies this mechanically: it renders the template and diffs — the command set and the worktree helper bodies — so only real divergence surfaces; justified exceptions live in `scripts/command-drift-whitelist.txt` or behind `cdd-only` markers. Justified one-sided cases: `/retrofit` (`.claude/commands/retrofit.md`), `/bootstrap` (`.claude/commands/bootstrap.md`), and `/quick-create` (`.claude/commands/quick-create.md`) live only in the CDD repo — all three operate *on* a target from a CDD session (retrofit adapts an existing project, bootstrap creates a new one, quick-create produces a one-off deliverable), so the template ships no copy. +- The CDD repo's own `.claude/commands/` and the template's `.claude/commands/` may drift slightly if needed, but unintended drift is a defect. `scripts/command-drift-check.sh` (run by CI and `/cdd-pre-pr`) verifies this mechanically: it renders the template and diffs — the command set and the worktree helper bodies — so only real divergence surfaces; justified exceptions live in `scripts/command-drift-whitelist.txt` or behind `cdd-only` markers. Justified one-sided cases: `/cdd-retrofit` (`.claude/commands/cdd-retrofit.md`), `/cdd-bootstrap` (`.claude/commands/cdd-bootstrap.md`), and `/cdd-quick-create` (`.claude/commands/cdd-quick-create.md`) live only in the CDD repo — all three operate *on* a target from a CDD session (retrofit adapts an existing project, bootstrap creates a new one, quick-create produces a one-off deliverable), so the template ships no copy. ## Build & test @@ -58,7 +58,7 @@ demo/setup.sh mdr_demo_99 --base /tmp/cdd-demo-smoke --local-only The `template-smoke` GitHub Actions workflow runs the same checks on every PR: shellcheck, the command-set drift check, the end-to-end smoke, and the demo seed-overlay step. -When `/pre-pr` runs in this repo, the "build / format / lint / test" gates collapse into the checks above plus a doc reconciliation pass. +When `/cdd-pre-pr` runs in this repo, the "build / format / lint / test" gates collapse into the checks above plus a doc reconciliation pass. ## Module layout @@ -91,8 +91,8 @@ See `doc/knowledge_base/claude-driven-development.md` for the full picture. This project uses CDD on itself. Every CDD session is a fresh context doing exactly one job (see process doc section 3 for the session taxonomy). -- **To start a new task** (handoff session): run `/next-step` from the main worktree to produce a handoff, then run `cdd-worktree ` to spin up the implementation worktree (implementation session, opens in plan mode). `/next-step` has three front-ends: no argument picks the next roadmap item; a task prompt starts off-roadmap work (intent-driven); and `#NN` / a bare integer / the `issue`/`issues` keyword sources the task from a GitHub issue (issue-driven), naming the branch `gh_issue_NN_`. -- **When main has advanced under a feature branch** (merge session): run `/merge-main` in a fresh context on the feature branch. -- **Before opening a PR** (pre-PR session): run `/pre-pr` in a fresh context to verify the process doc and template are consistent and the roadmap reflects what landed; it auto-commits its own reconciliation edits (local, no push) and ends with an opt-in step to open the PR (adding `Closes #NN` when the branch carries the `gh_issue_NN` token). -- **When a PR review leaves comments** (PR-review session): run `/process-pr` in a fresh context on the feature branch. +- **To start a new task** (handoff session): run `/cdd-next-step` from the main worktree to produce a handoff, then run `cdd-worktree ` to spin up the implementation worktree (implementation session, opens in plan mode). `/cdd-next-step` has three front-ends: no argument picks the next roadmap item; a task prompt starts off-roadmap work (intent-driven); and `#NN` / a bare integer / the `issue`/`issues` keyword sources the task from a GitHub issue (issue-driven), naming the branch `gh_issue_NN_`. +- **When main has advanced under a feature branch** (merge session): run `/cdd-merge-main` in a fresh context on the feature branch. +- **Before opening a PR** (pre-PR session): run `/cdd-pre-pr` in a fresh context to verify the process doc and template are consistent and the roadmap reflects what landed; it auto-commits its own reconciliation edits (local, no push) and ends with an opt-in step to open the PR (adding `Closes #NN` when the branch carries the `gh_issue_NN` token). +- **When a PR review leaves comments** (PR-review session): run `/cdd-process-pr` in a fresh context on the feature branch. - Keep the process doc, template, and roadmap consistent as part of every change. Process-first, then template. diff --git a/README.md b/README.md index e1ef23c..37139d1 100644 --- a/README.md +++ b/README.md @@ -16,12 +16,12 @@ A task flows through up to five sessions, each driven by one slash command: ```mermaid %%{init: {'theme':'base', 'themeVariables': {'background':'#0a0f1a', 'primaryColor':'#16243a', 'primaryTextColor':'#cfe3f0', 'primaryBorderColor':'#6f9fc4', 'lineColor':'#4a6c8c', 'textColor':'#b9d2e6', 'edgeLabelBackground':'#0a0f1a', 'fontFamily':'Poppins, Verdana, Helvetica, Arial, sans-serif', 'fontSize':'14px'}, 'flowchart': {'curve':'basis', 'padding':14, 'nodeSpacing':55, 'rankSpacing':60}}}%% flowchart TD - NS("Handoff session
/next-step, on the main worktree"):::agent + NS("Handoff session
/cdd-next-step, on the main worktree"):::agent IMPL("Implementation session
opens in plan mode — ③ plan approved —
implement, update docs + roadmap, commit"):::agent - MM("Merge session
/merge-main: integrate main, dry-run first"):::opt - PP("Pre-PR session
/pre-pr: CI gates, code review, doc reconciliation"):::agent + MM("Merge session
/cdd-merge-main: integrate main, dry-run first"):::opt + PP("Pre-PR session
/cdd-pre-pr: CI gates, code review, doc reconciliation"):::agent REV("Human reviews the PR on GitHub"):::human - PPR("PR-review session
/process-pr: triage + address review comments"):::opt + PPR("PR-review session
/cdd-process-pr: triage + address review comments"):::opt DONE("Squash-merge, worktree teardown"):::human NS -->|"  ① task selected ② handoff approved
a fresh worktree is spun up  "| IMPL @@ -50,9 +50,9 @@ git clone https://github.com/drabaioli/cdd.git ~/Code/cdd && cd ~/Code/cdd --path ~/Code/my-project ``` -The script copies the template, substitutes the placeholders, and makes the initial scaffold commit. Then fill in `CLAUDE.md` and `doc/knowledge_base/roadmap.md`, source `tools/myproj-worktree.sh` from `~/.bashrc`, run `claude`, and start with `/next-step`. Full procedure in [`template/BOOTSTRAP.md`](template/BOOTSTRAP.md). +The script copies the template, substitutes the placeholders, and makes the initial scaffold commit. Then fill in `CLAUDE.md` and `doc/knowledge_base/roadmap.md`, source `tools/myproj-worktree.sh` from `~/.bashrc`, run `claude`, and start with `/cdd-next-step`. Full procedure in [`template/BOOTSTRAP.md`](template/BOOTSTRAP.md). -For a guided greenfield start instead of the manual recipe, run `/bootstrap` from a Claude Code session in this repo: it walks you through defining the project, drafts a real roadmap and project overview, and scaffolds the new project — overview, `CLAUDE.md`, and roadmap already filled in — in one go. To install CDD into an *existing* project, use `/retrofit` from a Claude Code session in this repo instead. When the task is a one-off — a single self-contained script plus a README, not a project worth a roadmap — run `/quick-create` for a lightweight guided session that writes the deliverable directly, with no project substrate. +For a guided greenfield start instead of the manual recipe, run `/cdd-bootstrap` from a Claude Code session in this repo: it walks you through defining the project, drafts a real roadmap and project overview, and scaffolds the new project — overview, `CLAUDE.md`, and roadmap already filled in — in one go. To install CDD into an *existing* project, use `/cdd-retrofit` from a Claude Code session in this repo instead. When the task is a one-off — a single self-contained script plus a README, not a project worth a roadmap — run `/cdd-quick-create` for a lightweight guided session that writes the deliverable directly, with no project substrate. ## What's in this repo diff --git a/demo/README.md b/demo/README.md index 7c279d6..59f685f 100644 --- a/demo/README.md +++ b/demo/README.md @@ -4,7 +4,7 @@ This directory is a **third artifact** of the CDD repo, alongside `template/` an The `demo/` subsystem serves two purposes from one shared seed: -- **Demo** — a reproducible, visual walkthrough of CDD's task cycle: one reviewable PR, two parallel branches that conflict, and a `/merge-main` that resolves the conflict *and* delivers a dependency. +- **Demo** — a reproducible, visual walkthrough of CDD's task cycle: one reviewable PR, two parallel branches that conflict, and a `/cdd-merge-main` that resolves the conflict *and* delivers a dependency. - **Dogfooding** — a real greenfield project (CDD roadmap Phase 2) so working past the demo is genuine work. The seed project is **Markdown Renderer**: a small local Flask app where you paste Markdown, see it rendered live, and copy the result as **rich text** so it pastes formatted into Gmail, Google Docs, or Word — not as raw `# Heading` source. The key technical spine: pasting into email clients needs `text/html` on the clipboard, and email strips `