From bf90d11d43d6b24821f0d8fbf702027f59af05c6 Mon Sep 17 00:00:00 2001 From: dmccoystephenson Date: Sun, 17 May 2026 19:14:40 +0000 Subject: [PATCH] Add README and CLAUDE.md documentation README highlights the value of tailored dev loops and explains what the skill generates. CLAUDE.md captures template conventions, what belongs here vs. generated skills, and the doc sources of truth. Co-Authored-By: Claude Sonnet 4.6 --- CLAUDE.md | 43 ++++++++++++++++++++++++++++++++++++++ README.md | 62 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 105 insertions(+) create mode 100644 CLAUDE.md create mode 100644 README.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..083dd9e --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,43 @@ +# CLAUDE.md — create-dev-loop + +## What this repo is + +`create-dev-loop` is a single Claude Code skill file (`create-dev-loop.md`) that, when invoked, generates a tailored `-dev-loop` skill for the current repository. The skill file is the product; this repo is its home. + +## Skill file conventions + +The generated skill template lives entirely inside `create-dev-loop.md`. All placeholder syntax uses `{{PLACEHOLDER}}` (double braces). Conditional blocks use `{{#if VAR}}...{{/if}}`. These are resolved at generation time by Claude — there is no build step. + +When editing the template: +- Keep phase numbers stable — generated skills reference them by number in edge-case instructions +- Every `{{placeholder}}` in the template must have a corresponding row in the Step 4 substitution table +- Fenced code blocks inside the template are escaped with a leading backslash on the triple-backtick (` \`\`\` `) so they survive being embedded inside the outer markdown code block in `create-dev-loop.md` + +## What belongs here vs. in generated skills + +Changes to **how repos are explored or how skills are structured** belong in `create-dev-loop.md`. + +Repo-specific findings (build commands, reviewer names, branch prefixes) belong **only** in the generated skill, never back-ported here. + +## Testing changes + +There is no automated test suite. Validate changes by running `/create-dev-loop` against a real repo and confirming: +1. The generated skill file compiles (no unresolved `{{placeholders}}` remain) +2. The slash command link resolves correctly +3. The reported summary accurately reflects the target repo + +Use `dpm-dev-loop` or `herald-dev-loop` as reference implementations when evaluating whether a generated skill looks correct. + +## Commit and PR conventions + +- Branch prefix: `feature/` for new capability, `fix/` for corrections +- Commit messages: imperative mood, no trailing period, no co-author trailer unless Claude authored the commit +- Squash merge PRs; delete branches after merge +- Reference issue numbers with `Closes #N` in the PR body + +## Documentation sources of truth + +| File | What to verify | +|---|---| +| `create-dev-loop.md` | Steps, template placeholders, and substitution table are internally consistent | +| `README.md` | Described behavior matches what `create-dev-loop.md` actually does | diff --git a/README.md b/README.md new file mode 100644 index 0000000..3a56ceb --- /dev/null +++ b/README.md @@ -0,0 +1,62 @@ +# create-dev-loop + +A Claude Code skill that generates a **tailored autonomous dev loop** for any git repository — one slash command away from continuous, repo-aware development. + +## Why a tailored dev loop? + +Generic AI coding assistants treat every repo the same. A tailored dev loop encodes what makes *your* repo tick: + +| Generic assistant | Tailored dev loop | +|---|---| +| Guesses your test command | Knows `./mvnw test` vs `cargo test` vs `pytest` | +| Ignores your PR template | Fills it in from `.github/pull_request_template.md` | +| Doesn't know your branch convention | Enforces `feature/` or `fix/` based on your `CONTRIBUTING.md` | +| Skips your linter | Runs `ruff check` / `eslint` / `golangci-lint` before every push | +| Opens PRs with placeholder reviewers | Requests the right person from `CODEOWNERS` or adds `Copilot` | +| Repeats the same mistakes | Self-audits each cycle and files improvement issues | + +When Claude knows your build system, test suite, doc sources, and reviewer patterns, it doesn't drift. It ships work that passes CI, matches your conventions, and closes the right issues — without hand-holding. + +## What it does + +Running `/create-dev-loop` in any repo will: + +1. **Explore** the repository — reads `CLAUDE.md`, `CONTRIBUTING.md`, CI workflows, build files, linter configs, recent PRs, and `CODEOWNERS` +2. **Compile** a repo-specific profile — build command, test command, branch prefix, reviewer, doc sources, code patterns +3. **Generate** a ready-to-use `-dev-loop` skill file at `~/local-skills/-dev-loop/` +4. **Register** it as a slash command at `~/.claude/commands/-dev-loop.md` + +The generated skill drives a 10-phase loop: triage → work selection → implementation → PR → review → address comments → doc check → merge → self-audit → repeat. + +## Usage + +``` +/create-dev-loop +``` + +Run this from inside any git repository. If a skill already exists for the repo, you'll be asked whether to overwrite it. + +The skill reports the command name and a summary of the choices made (build system, test runner, doc sources, reviewer, branch prefix) when it finishes. + +## Requirements + +- [Claude Code](https://claude.ai/code) CLI +- `gh` (GitHub CLI) authenticated for PR/issue operations +- A git repository + +## Generated skill structure + +Each generated `-dev-loop` skill encodes: + +- **Build & test commands** — exact commands from CI or build files, not guesses +- **Branch naming** — from `CONTRIBUTING.md` or inferred from recent branches +- **Reviewer** — from `CODEOWNERS`, recent PR reviewers, or `Copilot` if configured +- **Lint/format step** — only if present in CI; omitted otherwise +- **Documentation sources** — every doc file that can drift from the implementation +- **Scan checklist** — repo-specific anti-patterns from `CLAUDE.md` plus universal ones +- **Code patterns** — conventions from `CLAUDE.md` encoded directly into Phase 3 + +## Related skills + +- `dpm-dev-loop` — the reference implementation this skill is modeled on +- `herald-dev-loop` — another example of a repo-specific generated loop