diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..24f2b70 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,29 @@ +name: Bug report +description: Something in the CDD workflow, template, scripts, or slash commands is broken. +labels: ["bug"] +body: + - type: markdown + attributes: + value: | + Thanks for reporting. This form is for breakage — a command, script, + template file, or part of the workflow not behaving as documented. + For a suggestion or improvement idea, use the **Idea** form instead. + - type: textarea + id: what-happened + attributes: + label: What happened, and what you expected + description: Describe the problem and what you expected to happen instead. + placeholder: | + I ran ... and got ... + I expected ... + validations: + required: true + - type: textarea + id: context + attributes: + label: What you ran / environment (optional) + description: > + The exact command(s), the CDD command or script involved, and anything + about your setup that might matter (OS, shell, Claude Code version). + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..dac5e7d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,7 @@ +blank_issues_enabled: true +contact_links: + - name: Understand how CDD works + url: https://github.com/drabaioli/cdd/blob/main/doc/knowledge_base/claude-driven-development.md + about: > + The fastest way to understand CDD is to open a clone with `claude` and ask + Claude Code about it. Start with the process document linked here. diff --git a/.github/ISSUE_TEMPLATE/idea.yml b/.github/ISSUE_TEMPLATE/idea.yml new file mode 100644 index 0000000..1901cb0 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/idea.yml @@ -0,0 +1,28 @@ +name: Idea +description: Suggest a workflow or template improvement. +labels: ["idea"] +body: + - type: markdown + attributes: + value: | + Have a way to make CDD sharper? CDD is meant to be turned on itself, so + friction you hit and ideas you have feed directly into the process and + the template. Thanks for taking the time. + - type: textarea + id: idea + attributes: + label: The idea, and the friction it addresses + description: > + What would you change or add, and what problem or rough edge does it + solve? Concrete examples of where you hit the friction help a lot. + validations: + required: true + - type: textarea + id: context + attributes: + label: Additional context (optional) + description: > + Anything else — alternatives you considered, where in the workflow or + template this lands, links to related issues. + validations: + required: false diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..6e36c2f --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,132 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, caste, color, religion, or sexual +identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the overall + community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or advances of + any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email address, + without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official email address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at +drabaioli@gmail.com. +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of +actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or permanent +ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the +community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. + +For answers to common questions about this code of conduct, see the FAQ at +[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at +[https://www.contributor-covenant.org/translations][translations]. + +[homepage]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html +[Mozilla CoC]: https://github.com/mozilla/diversity +[FAQ]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations diff --git a/README.md b/README.md index 16cadd0..0a706a2 100644 --- a/README.md +++ b/README.md @@ -2,54 +2,52 @@ [![template-smoke](https://github.com/drabaioli/cdd/actions/workflows/template-smoke.yml/badge.svg)](https://github.com/drabaioli/cdd/actions/workflows/template-smoke.yml) -CDD is a human-in-the-loop workflow for building real software with Claude Code — without losing control of the decisions, and without the docs, the roadmap, and the agent's context rotting as the project grows. The agent carries the implementation, verification, and documentation work across git worktrees; every decision passes through an explicit human checkpoint. - -## Three objectives - -CDD is built around three goals, in tension and balanced on purpose: - -- **Automate everything except the decisions that matter.** The agent does the implementation, verification, and documentation work. The human stays in control through six explicit checkpoints — picking the task, approving the handoff, approving the plan, approving any base-branch merge, approving roadmap edits, and merging the PR. Everything *between* those gates is automated; the gates themselves never are. -- **Bake in engineering best practices.** Tests, linting, formatting, CI, and living documentation are not optional extras bolted on at the end. The workflow expects them at every step and reconciles the docs and roadmap as part of each change, so quality and context don't erode as the project grows. -- **Improve the workflow as you use it.** CDD is meant to be turned on itself. Whenever a session surfaces friction or a better way of working, that improvement is folded back into the process and the template — so the workflow, and the practices it enforces, get sharper over time. +Build real software with Claude Code without handing over the wheel. CDD is a human-in-the-loop workflow: the agent carries the implementation, verification, and documentation across git worktrees, and every decision that matters passes through an explicit human gate. The docs, the roadmap, and the agent's context stay current as the project grows instead of rotting behind it. ## How it works -Every task moves through the same cycle. Each step is a fresh Claude Code session doing exactly one job, handing off to the next through files — a handoff file, the roadmap, the docs — never a shared chat window. The numbered locks across the top of the diagram are the six human checkpoints; the agent never crosses one without your explicit approval (approving the plan, ③, is the load-bearing one). +Every task moves through the same cycle. Each step is a fresh Claude Code session doing exactly one job, handing off to the next through files (a handoff file, the roadmap, the docs) rather than a shared chat window. A session loads only the context it needs to start, then follows links to the rest (the process doc, the architecture and feature docs) when a step actually calls for them, so context stays lean and never bloats with material the current job doesn't use. The locks across the top of the diagram are the human gates: the agent never crosses one without your explicit approval, and approving the plan is the load-bearing one. -![CDD task cycle: start a session and run /cdd-next-step to queue a task, spin up an isolated worktree, build in plan mode, optionally /cdd-merge-base, run /cdd-pre-pr to self-review and open the PR, review on GitHub, optionally /cdd-process-pr for review feedback, merge, then clean up and repeat — with six locked human checkpoints across the top.](doc/assets/task-cycle.png) +![CDD task cycle: start a session and run /cdd-next-step to queue a task, spin up an isolated worktree, build in plan mode, optionally /cdd-merge-base, run /cdd-pre-pr to self-review and open the PR, review on GitHub, optionally /cdd-process-pr for review feedback, merge, then clean up and repeat, with locked human gates across the top.](doc/assets/task-cycle.png) One full turn around the cycle: -1. **Pick the next task.** Start a session with `claude`, then run `/cdd-next-step`. It proposes what to work on — the next roadmap item, an off-roadmap prompt you type, or a GitHub issue (`#NN`). +1. **Pick the next task.** Start a session with `claude`, then run `/cdd-next-step`. It proposes what to work on: the next roadmap item, an off-roadmap prompt you type, or a GitHub issue (`#NN`). 2. **Confirm the intent.** You confirm the task is what you actually want and settle any roadmap-related decisions it raises. Once that's clear, it writes a handoff file for the implementation session. 3. **Spin up an isolated worktree.** Run `-worktree ` to create a dedicated git worktree and branch. It automatically launches the implementation session, which opens in plan mode. -4. **Review and approve the plan.** The session rebuilds its context from the handoff and the docs, then presents a plan. You approve it — this is the key checkpoint — and it implements the task, updates the architecture/feature docs and the roadmap, and commits the work locally (no push yet). +4. **Review and approve the plan.** The session rebuilds its context from the handoff and the docs, then presents a plan. You approve it (this is the key gate), and it implements the task, updates the architecture/feature docs and the roadmap, and commits the work locally (no push yet). 5. **Integrate the base branch if it moved.** If the base branch advanced while you were working, run `/cdd-merge-base`. It does more than resolve textual conflicts: it performs a *logical* merge, adopting newer base-branch features where the task should now use them. -6. **Self-review and open the PR.** In a fresh session, run `/cdd-pre-pr`. It runs the CI gates, code-reviews the diff, reconciles the docs and roadmap, and ends by offering to open the PR — the point at which the branch is first pushed. +6. **Self-review and open the PR.** In a fresh session, run `/cdd-pre-pr`. It runs the CI gates, code-reviews the diff, reconciles the docs and roadmap, and ends by offering to open the PR, the point at which the branch is first pushed. 7. **Review on GitHub.** You read the diff on GitHub and leave review comments, exactly as you would on any PR. 8. **Address the feedback.** Run `/cdd-process-pr` on the branch. It triages the review comments, makes the requested changes, replies in each thread, and commits and pushes back to the PR. 9. **Merge.** You squash-merge the branch on GitHub. 10. **Clean up and repeat.** Back in your terminal, run `-worktree-done` to remove the feature worktree and fast-forward your base branch to the freshly merged state. Then go again. -The [process document](doc/knowledge_base/claude-driven-development.md) describes the full lifecycle, the artifacts, the edit rules, and the reasoning behind every checkpoint. Read it first if you want to understand what CDD is and why. +The [process document](doc/knowledge_base/claude-driven-development.md) describes the full lifecycle, the artifacts, the edit rules, and the reasoning behind every gate. Read it first if you want to understand what CDD is and why. -## Quick start +## Three objectives + +CDD is built around three goals, in tension and balanced on purpose: -CDD's front door is its guided commands — run them from a Claude Code session inside a clone of this repo (`git clone https://github.com/drabaioli/cdd.git && cd cdd && claude`). +- **Automate everything except the decisions that matter.** The agent handles implementation, verification, and documentation. You keep control through explicit human gates: picking the task, approving the plan, approving any base-branch merge, merging the PR. Everything between the gates is automated; the gates never are. +- **Bake in engineering best practices.** Tests, linting, formatting, CI, and living documentation aren't bolted on at the end. The workflow expects them at every step and reconciles docs and roadmap with each change, so quality and context don't erode as the project grows. +- **Improve the workflow as you use it.** CDD is meant to be turned on itself. Friction surfaced in a session folds back into the process and the template, so the workflow gets sharper over time. + +## Quick start -To start a brand-new project, run `/cdd-bootstrap`. It walks you through defining the project and drafting a real roadmap through conversation, then scaffolds everything for you in one go — overview, `CLAUDE.md`, and roadmap already filled in — leaving you ready to run the task cycle above. +CDD's front door is its guided commands. Run them from a Claude Code session inside a clone of this repo (`git clone https://github.com/drabaioli/cdd.git && cd cdd && claude`). -To bring CDD to a project you already have, run `/cdd-retrofit`. It installs CDD into an existing codebase, or upgrades a project already running CDD, preserving your local customizations along the way. +**Start a brand-new project:** run `/cdd-bootstrap`. It walks you through defining the project and drafting a real roadmap through conversation, then scaffolds everything in one go (overview, `CLAUDE.md`, and roadmap already filled in), leaving you ready to run the task cycle above. -For a one-off deliverable that doesn't warrant a whole project — a single script plus a README, with no roadmap or project substrate — run `/cdd-quick-create`. +**Bring CDD to a project you already have:** run `/cdd-retrofit`. It installs CDD into an existing codebase, or upgrades a project already running CDD, preserving your local customizations along the way. -For the lower-level, non-interactive bootstrap recipe behind `/cdd-bootstrap`, see [`template/BOOTSTRAP.md`](template/BOOTSTRAP.md). +**Produce a one-off deliverable** that doesn't warrant a whole project (a single script plus a README, no roadmap or project substrate): run `/cdd-quick-create`. ## Command reference CDD ships seven slash commands, all prefixed `cdd-` so they autocomplete as a group. -**Per-task cycle** — shipped into every CDD project via the template: +**Per-task cycle**, shipped into every CDD project via the template: | Command | What it does | | --- | --- | @@ -58,27 +56,27 @@ CDD ships seven slash commands, all prefixed `cdd-` so they autocomplete as a gr | `/cdd‑pre‑pr` | Pre-PR checklist: CI gates, code review, and doc/roadmap reconciliation; ends with an opt-in step to open the PR. | | `/cdd‑process‑pr` | Triage and address the open PR's review feedback, reply in-thread, and commit and push. | -**CDD-repo-only** — run from a session inside this repo; they operate *on* a target, so the template ships no copy: +**CDD-repo-only**, run from a session inside this repo; they operate *on* a target, so the template ships no copy: | Command | What it does | | --- | --- | -| `/cdd‑bootstrap` | Guided greenfield: define the project + draft a roadmap through conversation, then scaffold it. | +| `/cdd‑bootstrap` | Guided greenfield: define the project and draft a roadmap through conversation, then scaffold it. | | `/cdd‑retrofit` | Install or upgrade CDD in an existing project. | | `/cdd‑quick‑create` | Produce a one-off self-contained deliverable (script + README), no project substrate. | -`-worktree` (and its companion `-worktree-done`) is a **shell helper** sourced from your `~/.bashrc`, not a slash command — it spins up and tears down the per-task git worktree that an implementation session runs in. +`-worktree` (and its companion `-worktree-done`) is a **shell helper** sourced from your `~/.bashrc`, not a slash command. It spins up and tears down the per-task git worktree that an implementation session runs in. ## Questions? -The fastest way to understand how CDD works is to ask it directly: open your local clone with `claude` and ask Claude Code questions about the project. The process doc, the template, and these docs are all right there for it to read — "why six checkpoints?", "what does `/cdd-merge-base` actually do?", and so on. +The fastest way to understand how CDD works is to ask it directly: open your local clone with `claude` and ask Claude Code questions about the project. The process doc, the template, and these docs are all right there for it to read: "why the human gates?", "what does `/cdd-merge-base` actually do?", and so on. ## Contributing -At this stage CDD accepts **GitHub issues only — pull requests aren't open yet**. Bug reports, suggestions, and questions about the workflow are very welcome: please [open an issue](https://github.com/drabaioli/cdd/issues). Have a change in mind? Raise it as an issue first and we can discuss it there. Direct PRs aren't being accepted for now — that will change as the project opens up. +At this stage CDD accepts **GitHub issues only; pull requests aren't open yet**. Bug reports, suggestions, and questions about the workflow are very welcome: please [open an issue](https://github.com/drabaioli/cdd/issues). Have a change in mind? Raise it as an issue first and we can discuss it there. Direct PRs aren't being accepted for now. That will change as the project opens up. ## Status -In active use, and dogfooded on itself. CDD has driven full task cycles end-to-end — real merges and PR reviews — on a downstream demo project (see [`demo/`](demo/)) and been retrofitted onto existing real-world codebases, with the friction found along the way folded back into the template. See [`doc/knowledge_base/roadmap.md`](doc/knowledge_base/roadmap.md) for what's done and what's next. +In active use, and dogfooded on itself. CDD has driven full task cycles end to end (real merges and PR reviews) on a downstream demo project (see [`demo/`](demo/)) and been retrofitted onto existing real-world codebases, with the friction found along the way folded back into the template. See [`doc/knowledge_base/roadmap.md`](doc/knowledge_base/roadmap.md) for what's done and what's next. ## License diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..0bbf1a5 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,35 @@ +# Security Policy + +CDD is a workflow project — process documentation, a copy-paste template, and a +handful of shell scripts (the bootstrap, the worktree helpers, the CI smoke and +drift checks). Most "vulnerabilities" here would be in that shell tooling rather +than in a running service, but we take reports seriously regardless. + +## Reporting a vulnerability + +**Please do not open a public issue for security problems.** + +Report privately through GitHub's **private vulnerability reporting**: + +1. Go to the [Security tab](https://github.com/drabaioli/cdd/security) of this + repository. +2. Click **Report a vulnerability**. +3. Fill in the advisory form. + +This keeps the report confidential until a fix is available. + +## What to include + +- A clear description of the issue and why it's a security concern. +- Steps to reproduce — the command(s) you ran and the affected file(s) + (for example, a script in `tools/`, `scripts/`, or `template/`). +- The impact you believe it has. + +## What to expect + +This is a small, single-maintainer project, so responses are best-effort rather +than bound to a formal SLA. You can expect an initial acknowledgement, a +discussion of the issue through the private advisory, and — once a fix lands — +credit in the advisory if you'd like it. + +Thanks for helping keep CDD and the projects built on it safe. diff --git a/doc/assets/cdd-social-preview.png b/doc/assets/cdd-social-preview.png new file mode 100644 index 0000000..90365be Binary files /dev/null and b/doc/assets/cdd-social-preview.png differ diff --git a/doc/knowledge_base/roadmap.md b/doc/knowledge_base/roadmap.md index 8cb9bbc..589c014 100644 --- a/doc/knowledge_base/roadmap.md +++ b/doc/knowledge_base/roadmap.md @@ -156,10 +156,10 @@ Prepare CDD to be open-sourced publicly: license it, rewrite the README to expla - [x] Add a standard MIT `LICENSE` at the repo root (holder: Diego Andres Rabaioli; year 2026). Repo-root only — not added to `template/` or wired into `bootstrap-cdd-project.sh`, since the template is copied verbatim into downstream projects without dragging a license along. - [x] Rewrite the README from scratch: what CDD is and how to use it; guided entry points (`/cdd-bootstrap`, `/cdd-retrofit`, `/cdd-quick-create`) lead the quick start with the manual `bootstrap-cdd-project.sh` recipe below; a complete reference of all 7 slash commands; the task-cycle image (`doc/assets/task-cycle.png`); a short issues-only Contributing section. Kept the two-big-ideas framing, the six-checkpoint concept, the `template-smoke` badge, and the Status section. - [ ] `CONTRIBUTING.md` (full version, once PRs are accepted). -- [ ] `CODE_OF_CONDUCT.md`. -- [ ] `.github/` issue templates (and a PR template, when PRs open). -- [ ] `SECURITY.md`. -- [ ] GitHub repo metadata: description, topics, and a social-preview / OG image (1280×640). -- [ ] Confirm the public repo home / org and update the README badge + clone URLs accordingly (currently point at `github.com/drabaioli/cdd`). +- [x] `CODE_OF_CONDUCT.md`. — Contributor Covenant 2.1 at the repo root; enforcement contact `drabaioli@gmail.com`. Repo-root only, not added to `template/`. +- [x] `.github/` issue templates: `bug_report.yml` and `idea.yml` forms plus `config.yml` (blank issues enabled). PR template deferred until PRs open. +- [x] `SECURITY.md`. — Repo-root file directing reporters to GitHub private vulnerability reporting (not email); wording assumes the repo setting is enabled (manual one-time toggle). +- [x] GitHub repo metadata: description, topics (via `gh repo edit`), and a 1280×640 social-preview image. +- [x] Confirm the public repo home / org and update the README badge + clone URLs accordingly (currently point at `github.com/drabaioli/cdd`). — Public home stays `github.com/drabaioli/cdd` (no org move); README badge, clone URL, and issues URL verified correct — no rewrite needed. **Milestone:** CDD is presentable and safe to open-source publicly — licensed, with a README that explains and demonstrates the workflow — with the remaining open-source essentials tracked.