From 55187babe2080e54472d4e2d0b550d3926c09777 Mon Sep 17 00:00:00 2001 From: Marlon Kranz Date: Tue, 17 Nov 2026 23:31:47 +0100 Subject: [PATCH 1/4] feat(config): layered config with repo and user files Settings lived in one per-repo devline.local.md (plus a user copy that only the design skill read), so personal preferences had to be repeated in every repo and project rules sat next to them in an ignored file. Each key now resolves from the first layer that sets it: the request, the committed repo file .claude/devline.md, the user file ${CLAUDE_CONFIG_DIR:-~/.claude}/devline/config.md, then the owner skill's Defaults section. Both files use flat YAML frontmatter plus optional prose for rules no key can say, such as squash merges. One shared reference holds the lookup rules, the legacy fallback and the key table; skills and agents point to it instead of naming a file. A missing new file falls back to the old devline.local.md, with a one-time hint to move it. Keys that nothing read are dropped from the documented set: frontend_framework, the cve_ branch, commit and push keys, and the migrate_ keys. --- agents/dependency.md | 4 +- agents/implementer.md | 2 +- agents/references/cloud-infra.md | 2 +- agents/references/documentation.md | 2 +- skills/brainstorm/SKILL.md | 2 +- skills/deps/SKILL.md | 9 +++- skills/design/SKILL.md | 6 +-- skills/design/tests/test_structure.py | 2 + skills/devline/SKILL.md | 9 ++-- skills/git/SKILL.md | 4 +- skills/kb-dependency-management/SKILL.md | 4 +- skills/kb-tdd-workflow/SKILL.md | 11 +++- skills/setup/references/config.md | 69 ++++++++++++++++++++++++ 13 files changed, 106 insertions(+), 20 deletions(-) create mode 100644 skills/setup/references/config.md diff --git a/agents/dependency.md b/agents/dependency.md index 72cb983..7b7b99a 100644 --- a/agents/dependency.md +++ b/agents/dependency.md @@ -15,12 +15,12 @@ You are a senior software engineer specializing in dependency updates. You recei 1. **Update targets** — package name(s), ecosystem, current/affected version, target version, reason (CVE ID, migration, etc.). Migrations also include: migration-guide URLs, known breaking changes, whether a migration tool exists, and a migration checklist. 2. **Repository path** — the absolute path to work in 3. **Commit message format** — e.g. `chore(deps): CVE-XXXX-XXXXX` or `chore(deps): migrate [pkg] from v[old] to v[new]` -4. **Settings** — branch strategy, auto-commit, auto-push, and any `devline.local.md` overrides +4. **Settings** — branch strategy, auto-commit, auto-push, and any devline config overrides 5. **Mode** — whether the **Migration block** below is enabled ## Execution process -1. `cd` into the repository path; read `.claude/devline.local.md` for repo-specific settings (the launcher may have passed these — check for local overrides). +1. `cd` into the repository path; resolve the devline config for this repo (`${CLAUDE_PLUGIN_ROOT}/skills/setup/references/config.md`); the launcher may have passed settings, but the repo's own config can override them. 2. Follow the launcher's git workflow **exactly** — its checkout/pull/branch steps run before any code changes. If none specified, fall back to the kb-dependency-management defaults. 3. Detect all ecosystems present (kb-dependency-management). 4. **[Migration block: run first if enabled — see below.]** diff --git a/agents/implementer.md b/agents/implementer.md index e9a5380..51aebbc 100644 --- a/agents/implementer.md +++ b/agents/implementer.md @@ -42,7 +42,7 @@ If you find discrepancies: implement the *intent* of the spec using the *reality ### 4. Set Up Test Infrastructure - Check for existing test framework configuration -- If `.claude/devline.local.md` exists, check for `test_framework` override +- A `test_framework` set in the devline config (`${CLAUDE_PLUGIN_ROOT}/skills/setup/references/config.md`) overrides detection - Create test files following existing conventions - Verify tests can be discovered and run diff --git a/agents/references/cloud-infra.md b/agents/references/cloud-infra.md index 5a41de3..da96b95 100644 --- a/agents/references/cloud-infra.md +++ b/agents/references/cloud-infra.md @@ -13,7 +13,7 @@ Before writing infra code, detect what the project uses: 5. `cdk.json` / `Pulumi.yaml` → CDK/Pulumi 6. `.github/workflows/` → GitHub Actions 7. `Jenkinsfile`, `.gitlab-ci.yml`, `azure-pipelines.yml` → other CI/CD -8. `.claude/devline.local.md` `cloud_provider` override +8. `cloud_provider` in the devline config (`${CLAUDE_PLUGIN_ROOT}/skills/setup/references/config.md`) overrides detection Apply TDD to infra too: write a validation script or smoke test before the change (e.g., a test that the Docker image builds and starts before writing the Dockerfile). diff --git a/agents/references/documentation.md b/agents/references/documentation.md index bd3ecc8..d15a106 100644 --- a/agents/references/documentation.md +++ b/agents/references/documentation.md @@ -4,7 +4,7 @@ On-demand guidance for the docs-keeper: separate documentation files (README, AP ## Documentation Detection -Before writing, check what exists: `docs/`, `README.md`, `CHANGELOG.md`; doc generators (`typedoc.json`, `mkdocs.yml`, `docusaurus.config.js`, `.readthedocs.yml`, javadoc); `.claude/devline.local.md` `doc_format` override. Match the existing format, style, and structure. +Before writing, check what exists: `docs/`, `README.md`, `CHANGELOG.md`; doc generators (`typedoc.json`, `mkdocs.yml`, `docusaurus.config.js`, `.readthedocs.yml`, javadoc); `doc_format` in the devline config (`${CLAUDE_PLUGIN_ROOT}/skills/setup/references/config.md`) overrides detection. Match the existing format, style, and structure. ## Writing Standards diff --git a/skills/brainstorm/SKILL.md b/skills/brainstorm/SKILL.md index aafa38f..267720d 100644 --- a/skills/brainstorm/SKILL.md +++ b/skills/brainstorm/SKILL.md @@ -65,7 +65,7 @@ Before writing the document, evaluate whether the feature warrants splitting int Decide how thorough the feature's tests should be — `deep` or `focused` — in this order: -1. **Config wins silently.** If `.claude/devline.local.md` sets `test_depth` to `deep` or `focused`, use it and say nothing. +1. **Config wins silently.** If the request or the devline config (`${CLAUDE_PLUGIN_ROOT}/skills/setup/references/config.md`) sets `test_depth` to `deep` or `focused`, use it and say nothing. 2. **Infer from signals.** Otherwise read the repo's existing test style AND the user's prompt: - Repo: dense per-method unit tests on trivial code → lean `deep`; sparse, or integration/behavior-heavy → lean `focused`. - Prompt: "production-grade", "thorough", "exhaustive" → `deep`; "quick", "prototype", "just wire it up" → `focused`. diff --git a/skills/deps/SKILL.md b/skills/deps/SKILL.md index 63c1599..a88caf6 100644 --- a/skills/deps/SKILL.md +++ b/skills/deps/SKILL.md @@ -67,7 +67,14 @@ Present a migration plan and **wait for approval** before launching any agents: ## Step 4: Read Settings (patch mode) -Check `.claude/devline.local.md` in each repo. Map CVE settings to the generic ones (prefixed wins): `cve_verify_build` → `dep_verify_build` (default `true`), `cve_verify_tests` → `dep_verify_tests` (default `true`). Git workflow is not configurable. For **migrate mode**, build + test verification is always on and cannot be disabled. +Resolve the config for each repo; lookup and precedence: `${CLAUDE_PLUGIN_ROOT}/skills/setup/references/config.md` (the repo layer is that repo's own `.claude/devline.md`). Git workflow is not configurable here. + +### Defaults + +- `cve_verify_build`: the value of `dep_verify_build` (default `true`); the prefixed key wins. +- `cve_verify_tests`: the value of `dep_verify_tests` (default `true`); the prefixed key wins. + +For **migrate mode**, build + test verification is always on and cannot be disabled. ## Step 5: Launch dependency agents diff --git a/skills/design/SKILL.md b/skills/design/SKILL.md index e229323..0093417 100644 --- a/skills/design/SKILL.md +++ b/skills/design/SKILL.md @@ -25,13 +25,13 @@ python3 -I /scripts/gallery.py ``` capture needs playwright-core in `~/.cache/devline/capture`. If it's missing, ask before installing (about 150 MB): `npm i --prefix ~/.cache/devline/capture playwright-core && node ~/.cache/devline/capture/node_modules/playwright-core/cli.js install chromium`. Without it, the critic judges from the HTML only and the report says so. -## Settings -Read `.claude/devline.local.md` (repo), then `~/.claude/devline.local.md` (user); the repo wins. All keys optional: +## Defaults +The devline config files override these; lookup and precedence: `${CLAUDE_PLUGIN_ROOT}/skills/setup/references/config.md`. - `sketch_model` (default `sonnet`) for seeds, sketch and cull; `design_model` (default `opus`) for build, refine and critique; `mockup_model` (default `sonnet`) - `design_sketches` (default 10), `design_pick`: `ask` (default) | `auto` - `design_mode`: `auto` (default) | `m3e-strict` | `default` -**Precedence for counts and who picks:** the user's request (a number, "you pick", "just build three") > settings > ask when it isn't obvious. Never override an explicit instruction in the request. +**Precedence for counts and who picks:** the user's request (a number, "you pick", "just build three") > config > ask when it isn't obvious. Never override an explicit instruction in the request. ## Inputs (both modes) - **Facts**: the real content (files, a facts file, the project itself). Never invent content. diff --git a/skills/design/tests/test_structure.py b/skills/design/tests/test_structure.py index 350d89c..312dc25 100644 --- a/skills/design/tests/test_structure.py +++ b/skills/design/tests/test_structure.py @@ -33,6 +33,8 @@ def test_named_paths_exist(self): for doc in (SKILL, AGENT): # kb-m3e ships separately; strict mode checks for it at run time. text = read(doc).replace("kb-m3e/references", "") + # Plugin-root paths point outside this skill (e.g. the shared config reference). + text = re.sub(r"\$\{CLAUDE_PLUGIN_ROOT\}/\S+", "", text) paths = set(PATH.findall(text)) self.assertTrue(paths, f"{doc.name}: no references/ or scripts/ paths found") for p in paths: diff --git a/skills/devline/SKILL.md b/skills/devline/SKILL.md index b9a6236..cdece8d 100644 --- a/skills/devline/SKILL.md +++ b/skills/devline/SKILL.md @@ -19,7 +19,7 @@ That's it. Do NOT read source files to understand errors. Do NOT run a second bu ## Change Classification (before Stage 1) -Read `fast_lane` from `.claude/devline.local.md` (default `auto`; values `auto|always|off`). Classify the request before starting Stage 1: +Resolve `fast_lane` from the config (see Defaults). Classify the request before starting Stage 1: - **Bug/fix/debug** (bug fix, compile error, test failure, stack trace — not a new feature): skip Stages 1-2 (brainstorm/plan), run the build once, then launch a **debugger** agent, followed by a **reviewer**. - **SMALL → Fast Lane.** Classify SMALL when ANY of: the user invoked `/devline:quick`, OR `fast_lane: always`, OR it's a bugfix/typo/small tweak, OR the change is ≲1 file / ≲30 lines with **no new component, no schema/migration, no new endpoint, and no new UI surface**. Ambiguous? Ask ONE AskUserQuestion — "This looks small — fast lane or full pipeline?" (default: fast lane). Skip the question when `fast_lane: always` (force fast) or `fast_lane: off` (never fast — run the full pipeline). @@ -64,9 +64,10 @@ Mark each `in_progress` when starting and `completed` when done. **Do not render Persist all mutable state to files — conversation context is disposable summaries only. During Stage 3, state files (`.devline/state.md`, `.devline/deferred-findings.md`, `.devline/fix-task-*.md`) are written per `references/implementation-protocol.md`. On resume-after-crash (or any uncertain pipeline state), read `references/recovery.md` for the state-file schemas and the recovery protocol. -## Configuration +## Defaults + +The devline config files override these; lookup and precedence: `${CLAUDE_PLUGIN_ROOT}/skills/setup/references/config.md`. -Read `.claude/devline.local.md` (if it exists): - **`auto_approve_brainstorm`** (default: `false`) — Skip brainstorm approval gate - **`auto_approve_plan`** (default: `false`) — Skip plan approval gate - **`fast_lane`** (default: `auto`; `auto|always|off`) — Controls fast-lane detection for small changes (see Change Classification above) @@ -74,7 +75,7 @@ Read `.claude/devline.local.md` (if it exists): ## Pipeline Stages ### Stage 0: Branch Setup (Automatic) -1. Read branching settings from `.claude/devline.local.md` (`branch_format`, `branch_kinds`, `protected_branches`) +1. Resolve the branching settings (`branch_format`, `branch_kinds`, `protected_branches`) from the config, falling back to the git skill's Defaults 2. **Active pipeline detection:** If `.devline/state.md` exists, this is a resume scenario (new conversation or post-compaction). Run the recovery protocol (`references/recovery.md`) and ask the user whether to resume or start fresh. If resuming, skip to the recovered stage. 3. If on a protected branch (default: main, master, develop, release, production, staging): create a branch using `branch_format` (default: `{kind}/{title}`). The `{kind}` must be one of `branch_kinds` (default: feat, fix, refactor, docs, chore, test, ci). 4. Create `.devline/`; if git does not already ignore it, add it to `.git/info/exclude` (local, no tracked-file change) diff --git a/skills/git/SKILL.md b/skills/git/SKILL.md index 1af26e3..d26d62d 100644 --- a/skills/git/SKILL.md +++ b/skills/git/SKILL.md @@ -12,7 +12,7 @@ You handle commits, pushes and pull requests during or at the end of a devline p ## Defaults -`.claude/devline.local.md` overrides any value here; a later config layer may replace this section. The rest of this skill refers to these values instead of repeating them. +The devline config files override any value here; lookup and precedence: `${CLAUDE_PLUGIN_ROOT}/skills/setup/references/config.md`. Git policy written as prose in those files (squash merges, a PR for every change, commit size) wins over these defaults too. The rest of this skill refers to these values instead of repeating them. - **Protected branches** (`protected_branches`): main, master, develop, release, production, staging. - **Branch names**: `branch_format` `{kind}/{title}`; `branch_kinds` feat, fix, refactor, docs, chore, test, ci. @@ -34,7 +34,7 @@ Each mode includes the one before it. Free text maps to the nearest mode ("commi ## Branch guard (all modes) -Read `protected_branches`, `branch_format` and `branch_kinds` from `.claude/devline.local.md`, falling back to the Defaults. If the current branch is protected: +Resolve `protected_branches`, `branch_format` and `branch_kinds` from the config, falling back to the Defaults. If the current branch is protected: - `commit`: ask whether to branch off first. Offer a name built from `branch_format`, with `{kind}` taken from the commit type when it is one of `branch_kinds` (otherwise `chore`) and `{title}` a short kebab-case summary. - `push` / `pr`: offer to branch off as above. If the user declines, push only after an explicit yes to pushing to that branch. diff --git a/skills/kb-dependency-management/SKILL.md b/skills/kb-dependency-management/SKILL.md index a4e478b..ac6980f 100644 --- a/skills/kb-dependency-management/SKILL.md +++ b/skills/kb-dependency-management/SKILL.md @@ -114,9 +114,9 @@ Check for custom test commands in `package.json` scripts, `Makefile`, or CI conf - If the failure is a straightforward compatibility issue (import path changed, method renamed, type signature updated), fix it as part of the update - If the failure is complex or touches significant application logic, do not commit — report the issue with details (error output, affected files) and let the user decide -## Settings +## Defaults -Read `.claude/devline.local.md` YAML frontmatter in each repo for these settings. All are optional — defaults shown: +Resolve these from the devline config in each repo; lookup and precedence: `${CLAUDE_PLUGIN_ROOT}/skills/setup/references/config.md`. | Setting | Default | Description | |---------|---------|-------------| diff --git a/skills/kb-tdd-workflow/SKILL.md b/skills/kb-tdd-workflow/SKILL.md index b1a1579..2c535df 100644 --- a/skills/kb-tdd-workflow/SKILL.md +++ b/skills/kb-tdd-workflow/SKILL.md @@ -9,6 +9,13 @@ disable-model-invocation: false Test-driven development produces better-designed, more maintainable code by writing tests before implementation. The critical skill is choosing the right test level — not defaulting to unit tests with mocks. +## Defaults + +The devline config files override these; lookup and precedence: `${CLAUDE_PLUGIN_ROOT}/skills/setup/references/config.md`. + +- `test_depth`: `auto` (`auto`, `deep`, `focused`). +- `test_framework`: auto-detect. + ## Core Philosophy: Right Level, Real Dependencies 1. **Default to the highest useful level.** If a test can run against real infrastructure in under 5 seconds, it should. Don't mock what you can test for real. @@ -46,7 +53,7 @@ E2E tests are defined at the **feature level** by the planner (see Feature-Goal ## Test Depth -A per-feature dial (from `.claude/devline.local.md` `test_depth`, or inferred during brainstorm). Two levels: +A per-feature dial (`test_depth`, see Defaults; `auto` means inferred during brainstorm). Two levels: - **deep** — exhaustive: a unit test per method plus edge cases and all configs, plus integration and E2E. This is the current default thoroughness. - **focused** — big behavior tests over whole classes/workflows plus targeted tests for genuinely hard logic; integration/E2E for real journeys; SKIP exhaustive per-method unit tests for trivial code (getters, passthroughs, obvious branches). @@ -152,7 +159,7 @@ Check the project for existing test infrastructure before creating tests: 4. Look for E2E test setup (`playwright.config`, `cypress.config`, `e2e/`, `tests/e2e/`) 5. Match existing patterns — naming conventions, directory structure, assertion style -If `.claude/devline.local.md` exists, check for `test_framework` override. +A `test_framework` set in the config (see Defaults) overrides detection. ## Parallel Task Testing diff --git a/skills/setup/references/config.md b/skills/setup/references/config.md new file mode 100644 index 0000000..8e9c31e --- /dev/null +++ b/skills/setup/references/config.md @@ -0,0 +1,69 @@ +# devline configuration + +Every devline setting is optional. A skill resolves each key on its own, from the first layer that sets it: + +1. **The request.** Whatever the user says in the current request ("build three", "skip the plan gate", "branch it as fix/…"). +2. **Repo:** `.claude/devline.md` in the repository root, committed. Project rules: git policy, testing approach, design system, `design_mode`. +3. **User:** `${CLAUDE_CONFIG_DIR:-~/.claude}/devline/config.md`. Personal preferences across repos: models, voice, what AI may and may not do. +4. **Plugin default:** the owner skill's `## Defaults` section. + +Layers merge key by key: a repo file that sets only `branch_format` still takes every other key from the user file or the defaults. Missing files are fine; read them fresh each time, nothing is cached. + +## Format + +```markdown +--- +branch_format: "{kind}/{title}" +protected_branches: [main, release] +test_depth: focused +--- + +Squash-merge every PR. Open a PR for every change, never push to main. +``` + +- Frontmatter: flat `key: value` lines, one key per line, no nesting. Lists use `[a, b]` or `- item` lines; a pipe-separated string (`"main|release"`) means the same. Lines starting with `#` are comments. Hooks may parse this, so keep it that flat. +- Below the frontmatter, optional free prose for rules no key can say. A skill that owns the topic follows it (the git skill follows git policy written here). When the repo and user prose disagree, the repo wins. +- Unknown keys are ignored. + +## Legacy files + +Before 0.5, settings lived in `devline.local.md`. If a layer's file is missing but its legacy file exists, read the legacy file as that layer: + +| Layer | File | Legacy file | +|---|---|---| +| Repo | `.claude/devline.md` | `.claude/devline.local.md` | +| User | `${CLAUDE_CONFIG_DIR:-~/.claude}/devline/config.md` | `${CLAUDE_CONFIG_DIR:-~/.claude}/devline.local.md` | + +The first time in a session you read a legacy file, tell the user once: "Read settings from ``; move them to `` (`/devline:setup` offers to do it)." The new file wins when both exist. + +## Keys + +"Layer" is where a key usually belongs; any key works in either file. + +| Key | Default | Owner | Layer | +|---|---|---|---| +| `auto_approve_brainstorm` | `false` | devline | user | +| `auto_approve_plan` | `false` | devline | user | +| `fast_lane` | `auto` (`auto`, `always`, `off`) | devline | user | +| `protected_branches` | `[main, master, develop, release, production, staging]` | git | repo | +| `branch_format` | `"{kind}/{title}"` | git | repo | +| `branch_kinds` | `[feat, fix, refactor, docs, chore, test, ci]` | git | repo | +| `test_depth` | `auto` (`auto`, `deep`, `focused`) | kb-tdd-workflow | repo | +| `test_framework` | auto-detect | kb-tdd-workflow | repo | +| `doc_format` | auto-detect | agents/references/documentation.md | repo | +| `cloud_provider` | auto-detect | agents/references/cloud-infra.md | repo | +| `dep_branch_strategy` | `main` (`main`, `branch`) | kb-dependency-management | repo | +| `dep_auto_commit` | `true` | kb-dependency-management | repo | +| `dep_auto_push` | `true` | kb-dependency-management | repo | +| `dep_verify_build` | `true` | kb-dependency-management | repo | +| `dep_verify_tests` | `true` | kb-dependency-management | repo | +| `cve_verify_build` | value of `dep_verify_build` | deps | repo | +| `cve_verify_tests` | value of `dep_verify_tests` | deps | repo | +| `design_model` | `opus` | design | user | +| `sketch_model` | `sonnet` | design | user | +| `mockup_model` | `sonnet` | design | user | +| `design_sketches` | `10` | design | user | +| `design_pick` | `ask` (`ask`, `auto`) | design | user | +| `design_mode` | `auto` (`auto`, `m3e-strict`, `default`) | design | repo | + +Owner is the skill whose `## Defaults` section defines the key (`skills//SKILL.md`), or the file that reads it. What each value does is described there. From 2bf0a1af29bc439c2b5c250bc0844381588317ba Mon Sep 17 00:00:00 2001 From: Marlon Kranz Date: Tue, 17 Nov 2026 23:31:47 +0100 Subject: [PATCH 2/4] feat(setup): write repo and user config from templates Setup wrote only the per-repo devline.local.md, walking four fixed batches. It now asks which config file to write, lists the keys that usually belong in that layer with their defaults, asks for prose rules, and writes only what differs from the defaults. When a legacy devline.local.md exists without its replacement, setup offers to move it and flags personal settings before they land in the committed repo file. The output-token check moves into the prerequisites step. --- skills/setup/SKILL.md | 37 ++++---- skills/setup/assets/devline-local-template.md | 90 ------------------- skills/setup/assets/repo-config-template.md | 7 ++ skills/setup/assets/user-config-template.md | 7 ++ 4 files changed, 32 insertions(+), 109 deletions(-) delete mode 100644 skills/setup/assets/devline-local-template.md create mode 100644 skills/setup/assets/repo-config-template.md create mode 100644 skills/setup/assets/user-config-template.md diff --git a/skills/setup/SKILL.md b/skills/setup/SKILL.md index f3ee33c..bbbee41 100644 --- a/skills/setup/SKILL.md +++ b/skills/setup/SKILL.md @@ -1,20 +1,22 @@ --- name: setup -description: This skill should be used when the user runs "/setup", "setup my project", "initialize CLAUDE.md", "create CLAUDE.md", or wants to set up the devline clarification protocol for a project. Creates a CLAUDE.md with the clarification protocol and interactively generates a minimal devline.local.md with only non-default settings. +description: This skill should be used when the user runs "/setup", "setup my project", "initialize CLAUDE.md", "create CLAUDE.md", or wants to set up the devline clarification protocol for a project. Creates a CLAUDE.md with the clarification protocol and interactively writes the devline config files (repo and user) with only non-default settings. user-invocable: true disable-model-invocation: true --- # Setup -Set up the devline pipeline for a project. Two files are created: +Set up the devline pipeline for a project. Up to three files are created: 1. **`CLAUDE.md`** in the project root — non-obvious project context + workflow orchestration for devline -2. **`.claude/devline.local.md`** — pipeline settings (only non-default values) +2. **`.claude/devline.md`** — repo config, committed (only non-default values) +3. **`${CLAUDE_CONFIG_DIR:-~/.claude}/devline/config.md`** — user config for every repo (only non-default values) Assets: - **[assets/claude-md-template.md](assets/claude-md-template.md)** — CLAUDE.md template with 4 sections (header, workflow orchestration, core principles, project context) -- **[assets/devline-local-template.md](assets/devline-local-template.md)** — All available pipeline settings organized in 4 batches with defaults +- **[references/config.md](references/config.md)** — config layers, precedence, legacy files, and every key with its default and usual layer +- **[assets/repo-config-template.md](assets/repo-config-template.md)** and **[assets/user-config-template.md](assets/user-config-template.md)** — the two config file skeletons ## Process @@ -35,6 +37,8 @@ Missing prerequisites: Only show the missing ones. If `gh` is missing, note that it's needed for PR creation, issue management, and GitHub API workflows. +Also check `CLAUDE_CODE_MAX_OUTPUT_TOKENS`. If it is unset or below 128000, suggest adding `export CLAUDE_CODE_MAX_OUTPUT_TOKENS=128000` to the user's shell profile: the designer and other agents produce large outputs, and the default 32K limit cuts them off. + ### 1. CLAUDE.md Read `CLAUDE.md` in the working directory root. @@ -47,23 +51,19 @@ Read the template from [assets/claude-md-template.md](assets/claude-md-template. After presenting all sections, show the assembled preview using **AskUserQuestion** and write only after confirmation. -### 2. devline.local.md - -Check if `.claude/devline.local.md` exists. - -- **Exists** → inform the user, show current contents, ask: **skip**, **override** (replace), or **merge** (add missing settings from what they configure below). -- **Does not exist** → proceed with interactive setup. +### 2. Config files -Read the settings template from [assets/devline-local-template.md](assets/devline-local-template.md). Walk through all 4 batches. For each batch: +Read [references/config.md](references/config.md) for the layers, the legacy file names and the key table. -1. Show the batch name, list every setting with its default value -2. Ask: "Do you want to change anything in this batch, or keep all defaults?" -3. If they want changes, ask what they want — do not ask for each setting individually -4. Record only the settings that differ from defaults +**Legacy move.** For each layer whose new file is missing but whose legacy file exists (Legacy files in the reference), show the legacy file and offer to move it to the new path. The repo file becomes committed once moved, so point out any key or prose that looks personal (models, voice, what AI may do) and offer to put it in the user file instead. Move only on a yes; on a no, leave it (skills keep reading it and remind the user). -After all batches, collect only the non-default settings. If no settings were changed, inform the user that defaults will be used and no file is needed — do **not** create an empty or all-defaults file. +**Which files.** Ask with AskUserQuestion: repo config, user config, both, or neither. For each chosen file: -If there are non-default settings, assemble the file using the output format from the template. Show the preview using **AskUserQuestion** and write only after confirmation. Create `.claude/` directory if needed. +1. If it exists, show its contents and ask: **skip**, **edit** (keep it and change what the user names), or **override**. +2. List the keys whose Layer column matches the file, grouped by owner, each with its default. Ask what to change; do not ask key by key. A key from the other layer is fine if the user wants it here. +3. Ask for prose rules no key can say: for the repo, git policy (squash merges, a PR for every change, commit size), testing approach, design system; for the user, voice and what AI may and may not do. +4. Keep only values that differ from the defaults. If nothing differs and there is no prose, say the defaults apply and write no file. +5. Fill the matching template ([repo](assets/repo-config-template.md), [user](assets/user-config-template.md)), drop the placeholder lines, show the preview with **AskUserQuestion**, and write only after confirmation. Create the directory if needed. ### 3. Recommended additions (optional) @@ -94,6 +94,5 @@ Setup complete. A few tips: - Keep CLAUDE.md lean and accurate. Add clarifications when agents get stuck; remove stale entries. - Do not add information that can easily be derived from code, tests, or git history. - If you need to change agent or workflow behavior, consider cloning the devline plugin and editing agents/skills directly — CLAUDE.md should stay focused on project context. -- devline.local.md only needs non-default settings. Full settings reference is in the devline README. -- Restart Claude Code after editing devline.local.md. +- The config files only need non-default settings: `.claude/devline.md` for project rules (commit it), `${CLAUDE_CONFIG_DIR:-~/.claude}/devline/config.md` for personal preferences. The request beats the repo file, which beats the user file. ``` diff --git a/skills/setup/assets/devline-local-template.md b/skills/setup/assets/devline-local-template.md deleted file mode 100644 index a8789a6..0000000 --- a/skills/setup/assets/devline-local-template.md +++ /dev/null @@ -1,90 +0,0 @@ -# devline.local.md Settings Template - -Settings are presented in 4 batches during setup. For each batch, show all settings with defaults and ask if the user wants to change anything. Only non-default values are written to the final file. - ---- - -## Pre-check — Environment - -Before presenting batches, check for `CLAUDE_CODE_MAX_OUTPUT_TOKENS`. If unset or below 128000, suggest: - -``` -export CLAUDE_CODE_MAX_OUTPUT_TOKENS=128000 -``` - -Explain: The designer and other agents can produce large outputs. The default 32K limit will cause API errors. Recommend adding this to the user's shell profile (`~/.zshrc`, `~/.bashrc`, etc.). - ---- - -## Batch 1 — Pipeline Flow - -``` -auto_approve_brainstorm: false — Pause for approval after brainstorming -auto_approve_plan: false — Pause for approval after planning - ⚠ In multi-phase pipelines, this skips ALL phase plan approvals. - Multiple phases can execute without any human checkpoint until deep review. -fast_lane: auto — Fast-lane small changes (branch→implement→one review→commit, skipping - brainstorm, plan, design system, deep review, and all gates). - auto = detect small changes, always = force fast lane, off = always full pipeline. -``` - ---- - -## Batch 2 — Branching - -``` -branch_format: "{kind}/{title}" — Branch naming format ({kind}, {title} placeholders) -branch_kinds: "feat|fix|refactor|docs|chore|test|ci" — Allowed branch kinds (pipe-separated) -protected_branches: "(main|master|develop|release|production|staging)" — On these, Stage 0 auto-creates a feature branch (regex group) -``` - ---- - -## Batch 3 — Framework Detection & Review - -``` -test_framework: auto-detect — Override: "vitest", "jest", "pytest", etc. -frontend_framework: auto-detect — Override: "react", "vue", "svelte", etc. -doc_format: auto-detect — Override: "markdown", "asciidoc", etc. -cloud_provider: auto-detect — Override: "aws", "gcp", "azure", etc. -test_depth: auto — auto = infer & ask if unclear | deep = exhaustive (every method/config) | focused = big workflow/class tests + hard logic, skip trivial-method units -sketch_model: sonnet — Model for design seeds, sketches, cull (/devline:design) -design_model: opus — Model for design builds, refines, critiques -mockup_model: sonnet — Model for design mockups -design_sketches: 10 — Sketches per design exploration -design_pick: ask — ask = you pick sketches to build | auto = critic's top 3 -design_mode: auto — auto = M3E strict when the project uses M3E | m3e-strict | default -``` - ---- - -## Batch 4 — Dependency Management - -``` -dep_branch_strategy: "main" — "main" = commit directly, "branch" = branch per update -dep_auto_push: true — Push after verification -dep_auto_commit: true — Commit after verification -dep_verify_build: true — Build check before commit -dep_verify_tests: true — Test suite before commit - -CVE patcher overrides (same defaults as dep_*): - cve_branch_strategy, cve_auto_push, cve_auto_commit, cve_verify_build, cve_verify_tests - -Migration overrides (branch_strategy defaults to "branch"): - migrate_branch_strategy: "branch", migrate_auto_push: true, migrate_auto_commit: true - Note: build/test verification always on for migrations -``` - ---- - -## Output Format - -Only non-default settings are written. If nothing was changed, no file is created. - -```markdown ---- -# Devline Local Settings — only non-default values. -# Full reference: https://github.com/Conava/claude-devline#settings-reference - ---- -``` diff --git a/skills/setup/assets/repo-config-template.md b/skills/setup/assets/repo-config-template.md new file mode 100644 index 0000000..b0c4a9f --- /dev/null +++ b/skills/setup/assets/repo-config-template.md @@ -0,0 +1,7 @@ +--- +# devline repo settings, committed. Only values that differ from the defaults. +# Keys, defaults and precedence: https://github.com/Conava/claude-devline/blob/main/skills/setup/references/config.md + +--- + + diff --git a/skills/setup/assets/user-config-template.md b/skills/setup/assets/user-config-template.md new file mode 100644 index 0000000..37e11c1 --- /dev/null +++ b/skills/setup/assets/user-config-template.md @@ -0,0 +1,7 @@ +--- +# devline user settings, for every repo. Only values that differ from the defaults. +# Keys, defaults and precedence: https://github.com/Conava/claude-devline/blob/main/skills/setup/references/config.md + +--- + + From 8751aa7176462d540ff81b17c31061bc8a4db6f9 Mon Sep 17 00:00:00 2001 From: Marlon Kranz Date: Tue, 17 Nov 2026 23:31:47 +0100 Subject: [PATCH 3/4] docs(readme): replace the settings reference with a short config section The full key tables duplicated the skills and drifted from them. The README now explains the two files and the precedence, shows one example, and links the shared key table. --- README.md | 84 +++++++------------------------------------------------ 1 file changed, 10 insertions(+), 74 deletions(-) diff --git a/README.md b/README.md index 0d9e6f6..b5cdd1d 100644 --- a/README.md +++ b/README.md @@ -58,7 +58,7 @@ git clone https://github.com/Conava/claude-devline.git claude --plugin-dir ./claude-devline ``` -Then run `/devline:setup` in your project. It creates a `CLAUDE.md` (project context for agents) and a `.claude/devline.local.md` (pipeline settings) through an interactive walkthrough. +Then run `/devline:setup` in your project. It creates a `CLAUDE.md` (project context for agents) and, if you want them, the [config files](#configuration) through an interactive walkthrough. ### Requirements @@ -159,7 +159,7 @@ flowchart LR
Stage 0: Branch Setup (automatic) -Reads branching config from `.claude/devline.local.md`. If you're on a protected branch (main, master, develop, release, production, staging), it creates a feature branch using your configured format (default: `feat/your-feature-name`). Sets up the `.devline/` working directory and, if git does not already ignore it, adds it to `.git/info/exclude` so no tracked file changes. +Reads the branching settings from your [config](#configuration). If you're on a protected branch (main, master, develop, release, production, staging), it creates a feature branch using your configured format (default: `feat/your-feature-name`). Sets up the `.devline/` working directory and, if git does not already ignore it, adds it to `.git/info/exclude` so no tracked file changes. If a previous pipeline left artifacts behind, it detects them and asks whether to resume or start fresh. @@ -514,7 +514,7 @@ Captures (stills, scroll or scripted recordings, frame-change report, page error Messages follow the `writing` skill. The body says why the change was needed and what it does at a level the code doesn't show, and never restates the diff. The PR body follows the repo's PR template when there is one. Otherwise it has a short `## Description` (what and why: intended effect, use case, issue), then the technical details (how it works, trade-offs, notable effects, closed issues), screenshots for UI changes, and a short `## Verification` only when it is needed. -The skill never pushes to a protected branch without asking and never force-pushes on its own. It uses `--force-with-lease` only when you ask. It never merges. New branch names follow `branch_format` and `branch_kinds` (see [Branching strategy](#branching-strategy)). +The skill never pushes to a protected branch without asking and never force-pushes on its own. It uses `--force-with-lease` only when you ask. It never merges. New branch names follow `branch_format` and `branch_kinds` (see [Configuration](#configuration)). --- @@ -552,87 +552,23 @@ The `/graphic-design` skill covers logo design (55 styles), corporate identity p ## Configuration -Create `.claude/devline.local.md` with YAML frontmatter, or run `/devline:setup` for guided setup. Every setting is optional -- defaults work out of the box. +Every setting is optional; the defaults work out of the box. Two files can override them, each with flat YAML frontmatter and optional prose below it for rules no key can say: -### Quick examples +- **Repo:** `.claude/devline.md`, committed. Project rules: branch naming, git policy, testing approach, design mode. +- **User:** `${CLAUDE_CONFIG_DIR:-~/.claude}/devline/config.md`. Personal preferences across repos: models, voice, what AI may do. -**Auto-approve everything (for when you trust the pipeline):** -```yaml ---- -auto_approve_brainstorm: true -auto_approve_plan: true ---- -``` +Each key comes from the first place that sets it: your request, then the repo file, then the user file, then the plugin default. -**Jira branch naming:** ```yaml --- branch_format: "PROJ-{ticket}/{title}" -branch_kinds: "PROJ" +test_depth: focused --- -``` -**Always take the fast lane for small changes:** -```yaml ---- -fast_lane: always ---- +Squash-merge every PR. Open a PR for every change. ``` -
-All settings - -#### Pipeline gates - -| Setting | Default | Description | -|---------|---------|-------------| -| `auto_approve_brainstorm` | `false` | Skip approval after brainstorming | -| `auto_approve_plan` | `false` | Skip approval after planning | -| `fast_lane` | `auto` | Fast-lane small changes to implement -> review -> commit. `auto` = detect, `always` = force, `off` = always run the full pipeline | - -#### Branching strategy - -| Setting | Default | Description | -|---------|---------|-------------| -| `branch_format` | `"{kind}/{title}"` | Branch naming (`{kind}`, `{title}` placeholders) | -| `branch_kinds` | `"feat\|fix\|refactor\|docs\|chore\|test\|ci"` | Allowed branch kinds | -| `protected_branches` | `"(main\|master\|develop\|release\|production\|staging)"` | Branches the pipeline auto-creates a feature branch off of, and branches `/devline:git` will not push to without asking | - -#### Framework overrides - -| Setting | Default | Description | -|---------|---------|-------------| -| `test_framework` | auto-detect | e.g., `"vitest"`, `"jest"`, `"pytest"` | -| `frontend_framework` | auto-detect | e.g., `"react"`, `"vue"`, `"svelte"` | -| `doc_format` | auto-detect | e.g., `"markdown"`, `"asciidoc"` | -| `cloud_provider` | auto-detect | e.g., `"aws"`, `"gcp"`, `"azure"` | - -#### Dependency management - -| Setting | Default | Description | -|---------|---------|-------------| -| `dep_branch_strategy` | `"main"` | `"main"` = default branch, `"branch"` = per-update branch | -| `dep_auto_push` | `true` | Push after verification | -| `dep_auto_commit` | `true` | Commit after verification | -| `dep_verify_build` | `true` | Run build check | -| `dep_verify_tests` | `true` | Run test suite | - -#### Design - -| Setting | Default | Description | -|---------|---------|-------------| -| `sketch_model` | `sonnet` | Model for cheap exploration steps (seeds, sketches, cull) | -| `design_model` | `opus` | Model for builds, refines and critiques | -| `mockup_model` | `sonnet` | Model for mockups | -| `design_sketches` | `10` | Number of sketches per exploration | -| `design_pick` | `ask` | `ask` = you pick which sketches to build, `auto` = take the critic's top 3 | -| `design_mode` | `auto` | `auto` = M3E strict when the project uses M3E, `m3e-strict`, or `default` | - -A number or "you pick" in the request always wins over these settings. Design settings are read from `.claude/devline.local.md`, then `~/.claude/devline.local.md`. - -The `deps` skill (patch mode) also honors `cve_`-prefixed overrides (e.g. `cve_verify_build`), which take priority over the generic `dep_` keys. Migrate mode always runs build and test verification (not configurable). - -
+Run `/devline:setup` to write either file, or to move settings from an older devline version into place. Every key, its default and the skill that reads it are listed in [skills/setup/references/config.md](skills/setup/references/config.md). --- From 459204b24d2578928fb4690368aafa574f8a8603 Mon Sep 17 00:00:00 2001 From: Marlon Kranz Date: Tue, 17 Nov 2026 23:31:47 +0100 Subject: [PATCH 4/4] test(setup): check the config key table against its owners Fails when a key in the shared table is missing from its owner's Defaults section, when an owner stops pointing to the shared reference, or when any file other than the migration note names the legacy config file. Runs in the validate workflow. --- .github/workflows/validate.yml | 2 + skills/setup/tests/test_config.py | 72 +++++++++++++++++++++++++++++++ 2 files changed, 74 insertions(+) create mode 100644 skills/setup/tests/test_config.py diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml index 23dba68..cc23811 100644 --- a/.github/workflows/validate.yml +++ b/.github/workflows/validate.yml @@ -45,3 +45,5 @@ jobs: run: python3 -m unittest discover -s skills/kb-m3e/tests -v - name: Test kb-engineering (structure and helper) run: python3 -m unittest discover -s skills/kb-engineering/tests -v + - name: Test setup (config structure) + run: python3 -m unittest discover -s skills/setup/tests -v diff --git a/skills/setup/tests/test_config.py b/skills/setup/tests/test_config.py new file mode 100644 index 0000000..ea5d552 --- /dev/null +++ b/skills/setup/tests/test_config.py @@ -0,0 +1,72 @@ +"""Structure checks for the layered devline config.""" +import re +import unittest +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[3] +REF = ROOT / "skills/setup/references/config.md" +REF_PATH = "${CLAUDE_PLUGIN_ROOT}/skills/setup/references/config.md" +LEGACY = "devline" + ".local" # split so this file doesn't match itself +DESIGN_KEYS = {"design_model", "sketch_model", "mockup_model", "design_sketches", "design_pick", "design_mode"} + + +def read(path): + return path.read_text(encoding="utf-8") + + +def key_table(): + """{key: owner} from the Keys table of the reference.""" + keys = read(REF).split("\n## Keys\n", 1)[1] + return dict(re.findall(r"(?m)^\| `([a-z_]+)` \| [^|]+ \| ([^|]+?) \|", keys)) + + +def owner_file(owner): + return ROOT / owner if "/" in owner else ROOT / "skills" / owner / "SKILL.md" + + +def defaults_section(text): + m = re.search(r"(?m)^(#+) Defaults\s*$", text) + if not m: + return None + rest = text[m.end():] + end = re.search(rf"(?m)^#{{1,{len(m.group(1))}}} ", rest) + return rest[: end.start()] if end else rest + + +class Config(unittest.TestCase): + def test_table_has_the_keys_in_use(self): + keys = key_table() + self.assertGreaterEqual(len(keys), 20) + self.assertLessEqual(DESIGN_KEYS, set(keys)) + + def test_every_key_is_defined_by_its_owner(self): + for key, owner in key_table().items(): + with self.subTest(key=key, owner=owner): + path = owner_file(owner) + self.assertTrue(path.is_file(), f"owner {owner} not found") + text = read(path) + if path.name == "SKILL.md": + text = defaults_section(text) + self.assertIsNotNone(text, f"{owner} has no Defaults section") + self.assertIn(f"`{key}`", text) + + def test_owners_point_to_the_reference(self): + for owner in set(key_table().values()): + with self.subTest(owner=owner): + self.assertIn(REF_PATH, read(owner_file(owner))) + + def test_legacy_name_only_in_the_migration_note(self): + skip = {".git", "__pycache__", ".devline"} + for path in ROOT.rglob("*"): + if not path.is_file() or skip & set(path.relative_to(ROOT).parts) or path == REF: + continue + try: + text = read(path) + except UnicodeDecodeError: + continue + with self.subTest(file=str(path.relative_to(ROOT))): + self.assertNotIn(LEGACY, text) + + +if __name__ == "__main__": + unittest.main()