From 82ef6e033742143b8bd12e435711ccf2bb89668c Mon Sep 17 00:00:00 2001 From: dmccoystephenson Date: Wed, 29 Jul 2026 01:51:04 +0000 Subject: [PATCH 1/2] Fix doc drift in the trust model and restated conventions Co-Authored-By: Claude Opus 5 (1M context) --- CONTRIBUTING.md | 14 +++++++++++++- RESEARCH.md | 2 +- SECURITY.md | 29 ++++++++++++++++++++++------- 3 files changed, 36 insertions(+), 9 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 34a8d9c..a02e6cf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -33,6 +33,16 @@ contributors: - If your change implements or contradicts a finding in `RESEARCH.md`, update that file in the same PR (see its "How to use this document" section for the entry format). +- Repo-specific findings (build commands, reviewer names, branch prefixes) + belong **only** in a generated skill — never back-port them into + `create-dev-loop.md`. Only changes to *how repos are explored or how + skills are structured* belong here. +- Steps 3, 5, and 6 are a load-bearing interface, not internal detail: + downstream tooling reads generated skills from exactly the paths Steps 3 + and 5 write, and depends on the repo Step 6 creates. Changing where a + skill is written, what it's named, or what Step 6 creates is a breaking + change — call it out in your PR description. See "What belongs here vs. + in gardener" in [`CLAUDE.md`](CLAUDE.md). ## Making a change @@ -59,8 +69,10 @@ contributors: one the first time — Step 6 creates a GitHub repo, and Steps 3 and 5 write to `~/local-skills/` and `~/.claude/commands/`. 4. Commit using imperative mood, no trailing period (e.g. `Add SKILL_REPO_OWNER placeholder`). + Don't add a co-author trailer unless an AI agent actually authored the commit. 5. Open a PR referencing any related issue with `Closes #N`. Describe what - you tested it against. + you tested it against. PRs are squash-merged and the branch is deleted + after merge. ## Retrofitting existing generated skills diff --git a/RESEARCH.md b/RESEARCH.md index 9ca6ccc..9ba3a66 100644 --- a/RESEARCH.md +++ b/RESEARCH.md @@ -16,7 +16,7 @@ This document records the empirical findings that inform the design of `create-d - **First-party sources** (Anthropic, OpenAI, vendor research with numbers) count as evidence but must be flagged as first-party so readers can weight them appropriately. - **Confidence levels**: `high` = replicated across multiple independent studies; `medium` = one well-cited study, plausible; `low` = single paper, contested, or inferred from adjacent literature. -Last reviewed: 2026-07-27. +Last reviewed: 2026-07-29. --- diff --git a/SECURITY.md b/SECURITY.md index 09310a7..3616f37 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -18,15 +18,30 @@ You should expect an initial response within a few days. ## Trust model `/create-dev-loop` reads files from whatever repository you run it in — -`CLAUDE.md`, `CONTRIBUTING.md`, `README.md`, CI configs, `CODEOWNERS`, and -recent PR descriptions — and uses their content to decide what the -generated skill does: its stated identity, its self-review rubric, its -reviewer, its branch conventions, and so on (Step 2 of +`CLAUDE.md`, `CONTRIBUTING.md`, `README.md`, build files (`pom.xml`, +`package.json`, `Cargo.toml`, `Makefile`, `pyproject.toml`, `go.mod`, …), +CI workflows, linter and formatter configs, `CODEOWNERS`, the PR template, +documentation sources, and recent commit and PR history — and uses their +content to decide what the generated skill does (Step 2 of `create-dev-loop.md`). -This means the target repo's content directly shapes an autonomous -skill that will later create branches, open PRs, and push commits with -`gh`/`git`. **Only run `/create-dev-loop` against repositories you trust.** +That content shapes more than cosmetic details like the skill's stated +identity, its reviewer, or its branch prefix. Step 4 also derives from it: + +- **The shell commands the generated skill runs.** `COMPILE_CMD`, + `TEST_CMD`, `LINT_CMD`, and `EXTERNAL_SIGNAL_CMD` are taken from the + target repo's build files and CI workflows, and the generated skill + executes them verbatim — in its Phase 3 build-verification step and its + Phase 4 external-signal anchor. +- **Which paths are exempt from autonomous merge.** `DO_NOT_AUTO_MERGE` + decides what the generated skill refuses to merge without a human. +- **What the skill checks itself against.** `SELF_REVIEW_RUBRIC` becomes + the repo-specific half of its pre-merge self-review. + +This means the target repo's content directly shapes an autonomous skill +that will later run those commands and create branches, open PRs, push +commits, and merge PRs with `gh`/`git`. **Only run `/create-dev-loop` +against repositories you trust.** A repository crafted to manipulate the generation process (e.g. planted instructions in `CLAUDE.md` aimed at the agent rather than at humans) could cause the generated skill to encode unsafe or unintended behavior. This is From 53adf93f27a802a45980d524e38f00a99408650a Mon Sep 17 00:00:00 2001 From: dmccoystephenson Date: Wed, 29 Jul 2026 01:52:16 +0000 Subject: [PATCH 2/2] Clarify that DO_NOT_AUTO_MERGE can only widen the merge gate Co-Authored-By: Claude Opus 5 (1M context) --- SECURITY.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/SECURITY.md b/SECURITY.md index 3616f37..b702473 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -34,7 +34,10 @@ identity, its reviewer, or its branch prefix. Step 4 also derives from it: executes them verbatim — in its Phase 3 build-verification step and its Phase 4 external-signal anchor. - **Which paths are exempt from autonomous merge.** `DO_NOT_AUTO_MERGE` - decides what the generated skill refuses to merge without a human. + adds to the paths the generated skill refuses to merge without a human. + It can only widen that list — a universal baseline (`.github/workflows/*`, + anything under `security/`, large deletions) holds regardless of what the + target repo says. - **What the skill checks itself against.** `SELF_REVIEW_RUBRIC` becomes the repo-specific half of its pre-merge self-review.