From 55187babe2080e54472d4e2d0b550d3926c09777 Mon Sep 17 00:00:00 2001 From: Marlon Kranz Date: Tue, 17 Nov 2026 23:31:47 +0100 Subject: [PATCH 01/17] 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 02/17] 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 03/17] 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 04/17] 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() From 625352920127347f5b23351b3acc373775a35cb4 Mon Sep 17 00:00:00 2001 From: Marlon Kranz Date: Tue, 17 Nov 2026 23:35:13 +0100 Subject: [PATCH 05/17] feat(planner): refactor first, summary for approval, task reach The planner offers a preparatory refactor as its own earlier task and bakes small local cleanups in silently. Plans open with a Summary for approval that the planner returns verbatim, every task names its Reach, and owner requirements must appear in plan text. --- agents/planner.md | 22 +++++++++++++--------- agents/references/plan-format.md | 6 ++++++ 2 files changed, 19 insertions(+), 9 deletions(-) diff --git a/agents/planner.md b/agents/planner.md index 3a34f2f..a2f93b2 100644 --- a/agents/planner.md +++ b/agents/planner.md @@ -100,15 +100,20 @@ With the user's input incorporated: - Document design decisions: choice, rationale, alternatives considered - Challenge yourself aggressively — prefer the simplest design that works -### 4. Proactive Improvements +### 4. Refactor First and Proactive Improvements -As you research, you will encounter code smells, latent bugs, inconsistencies. +Make the change easy, then make the easy change. Check whether the structure of the code you will touch fits the change. Features get glued onto structures that don't fit (a second container kind while widgets still live inside the first). -**How to handle them:** +- **Structure doesn't fit, and the request is one of a family likely to grow** → plan a preparatory refactor as its own task in an earlier wave. Offer it in the Summary for approval with the reason; the user can decline it. +- **Small local cleanup that makes the change smaller** (rename, extract a helper, remove a duplicate branch) in files a planned task already modifies → **bake it into that task** without asking. + +As you research you will also find code smells, latent bugs and inconsistencies: - Touches files a planned task already modifies → **bake it into that task** - Unrelated to any planned task's files → **create a standalone task** - Unclear whether worth including → **ask the user** via `STATUS: NEEDS_INPUT` +**Owner requirements:** every requirement from the brainstorm, the NEEDS_INPUT answers or the orchestrator's brief must appear in plan text (a task spec or Design Decisions), never only in the conversation. + ### 5. Define Tasks Each task is a spec for one agent running in an isolated worktree. @@ -119,6 +124,8 @@ Each task is a spec for one agent running in an isolated worktree. The plan must be **complete** (the implementer has all the context to understand the goal and constraints) but not **prescriptive** (don't write pseudocode or step-by-step instructions). Give the why, the what, and the boundaries — trust the implementer with the how. +**Reach per task:** set each task's `**Reach:**` to the categories from the Reach section of kb-blast-radius that its change touches, or `none`. The orchestrator adds a focused review for tasks with a reach category. + **Agent and model selection per task:** - **implementer** — feature/application code (default); also handles build, CI/CD, Docker, infrastructure-as-code, and tooling (infra) tasks - **debugger** — fixing failing tests or unexpected behavior @@ -150,7 +157,7 @@ The final wave must include a dedicated E2E test task (see `## Feature E2E Task` **Shared resource files (critical — the #1 cause of merge conflicts):** Shared resource files are files that multiple tasks need to modify but no single task "owns." Common examples: -- **Translation/i18n files** (`en.json`, `de.json`, `messages/*.properties`) — every component task adds keys +- **Translation/i18n files** (`en.json`, `de.json`, `messages/*.properties`) — every component task adds keys. A UI task either owns a key namespace or the plan lists every key it needs. - **Global CSS/theme files** (`globals.css`, `tokens.css`) — multiple tasks add styles - **Route/navigation configs** (`routes.ts`, `next.config.js`) — every page task adds routes - **Shared type definitions** (`types.ts`, `index.d.ts`) — multiple tasks add types @@ -225,13 +232,10 @@ Write the full plan to `.devline/plan.md`. See `references/plan-format.md` for t ### 7. Return Summary After writing the plan, return only: -- 2-3 sentence architecture overview -- Task list (name, agent type, dependencies) -- Key trade-offs or decisions made -- Proactive improvements (baked in, standalone, or deferred to user) +- The plan's `## Summary for approval` section, verbatim - Path: the plan file written (`.devline/plan.md` or `.devline/plan-phase-N.md` in phase mode) -The orchestrator handles user approval. +Each phase plan has its own Summary for approval. The orchestrator handles user approval. ### Iteration diff --git a/agents/references/plan-format.md b/agents/references/plan-format.md index 841f6ae..31f5b0f 100644 --- a/agents/references/plan-format.md +++ b/agents/references/plan-format.md @@ -9,6 +9,10 @@ **Phase:** [N of M — or "single" for non-phased plans] **Test Depth:** [deep | focused — carried from the brainstorm] +## Summary for approval + +[Only what a human must read before approving or asking for changes, at most 40 lines. Numbered decisions, each with your recommendation. Then: stages this plan adds beyond the preset, each with its reason; a preparatory refactor, if offered, with the reason; known conflicts with other branches. End with "Approve as is, or name the numbers to change."] + ## Architecture Overview [High-level design: components, data flow, key abstractions. Component diagram if helpful.] @@ -50,6 +54,7 @@ Rules enforced by the orchestrator: **Agent:** [implementer / debugger] **Model:** [sonnet (default) / opus — use opus for tasks requiring complex architectural reasoning, large refactors, or tricky logic] **UI:** [yes / no] +**Reach:** [categories from kb-blast-radius Reach this task touches (security surface, resource use, public contract, persisted data, UI, concurrency, build/release), or none] **Files owned:** [exact list of files this task creates/modifies] **Context:** @@ -90,6 +95,7 @@ The final wave SHOULD include a dedicated E2E task ONLY for features with a genu **Agent:** implementer **Model:** sonnet **UI:** no +**Reach:** none **Files owned:** [E2E test files only] **Context:** From 4b4a9460ffda0b433ae7808be990713678c5c797 Mon Sep 17 00:00:00 2001 From: Marlon Kranz Date: Tue, 17 Nov 2026 23:35:13 +0100 Subject: [PATCH 06/17] feat(implementer): commit only in a worktree, show the red run In place, the implementer leaves changes uncommitted for the main session. It checks its worktree base, links env files, keeps scratch and evidence where they survive, steps back before appending special cases, and reports the first failing run and integration notes. --- agents/implementer.md | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/agents/implementer.md b/agents/implementer.md index 51aebbc..ae1c695 100644 --- a/agents/implementer.md +++ b/agents/implementer.md @@ -28,6 +28,7 @@ Before writing anything — this is the most common cause of bugs when skipped: - **Trace the execution path** from trigger to final effect. Read the real code at each step. - **Replicate existing patterns.** Use the codebase's existing mechanisms (observer, lifecycle, event bus). When you must deviate from an established pattern (e.g., using raw `fetch()` instead of the project's `apiRequest()` wrapper), preserve the full contract — error handling, typing, logging — that the pattern provides. A justified deviation from the happy path still needs the error path. - **Check for existing utilities before creating new ones.** `grep` for CSS classes, helper functions, shared components, and constants before writing your own. Duplicating existing utilities (e.g., redefining `.sr-only` when Tailwind provides it) introduces maintenance debt. +- **Step back before appending.** If the change would add a special case, a duplicated branch or code that grows around the structure, restructure within your owned files first. A refactor beyond your owned files goes under Notes, not into the diff. - **Check platform/framework constraints.** Verify APIs you plan to use exist in the target platform. - **UI work:** if `docs/design-system/MASTER.md` exists, it and its Corrections section are binding; every colour, size, radius, shadow and duration comes from a token (add a named token first if one is missing), never a literal. - **Read the checklists.** Use Read on each kb-engineering checklist its Stack and Change tables select (`testing.md` Core at minimum) before writing code. This holds for every task, however small; selecting one from the table is not reading it. @@ -63,7 +64,7 @@ Under `focused`, write the acceptance/behavior tests the plan lists (one per acc - Write one failing test that defines expected behavior - For `[integration]` tests: set up real infrastructure (Testcontainers, `@DataJpaTest`, test DB) before writing the test. The test should hit real databases, real HTTP handlers, real event buses. - **Parallel compilation safety:** Before running your first test, verify that all types your code references actually exist in the codebase. In monolithic-compilation languages (Kotlin, Java, Scala), a single unresolved symbol blocks compilation for the entire module. If a type from another task doesn't exist yet, this is a missing dependency the planner didn't catch — report it in your output under Notes and move on to parts of the task that don't depend on it. The orchestrator will requeue the blocked work after the dependency completes. -- Run the test — confirm it fails for the right reason +- Run the test — confirm it fails for the right reason, and record that first failing run: the command and the failing assertion line. For a bug fix, the regression test must fail on the unfixed code. **Green Phase:** - Write the code to make the test pass — use Obvious Implementation when clear, Fake It when uncertain @@ -108,6 +109,7 @@ After all tests are green, before declaring done: Do NOT commit with failing tests unless it's case 4 (cross-task conflict you cannot resolve). ### 9. Commit +Commit only when you run in your own worktree (toplevel under `.claude/worktrees/`). Otherwise make no commit: leave the changes in place and list every changed file in the report. ```bash git add && git commit -m "task-N: " ``` @@ -136,7 +138,12 @@ Minimize build invocations — each cold start adds 10-15s overhead. 4. **Timeouts:** The Bash tool defaults to 120s — sufficient for targeted test runs. Set `timeout: 600000` only for the final full-suite run (step 8). **Parallel isolation (when in a worktree):** -- **First command — verify your CWD:** Run `pwd` and confirm it contains `.claude/worktrees/`. If it doesn't, you are writing to the main repo and will corrupt other agents' work. Stop and report the issue. +- **First command — verify your CWD:** Run `pwd` and `git rev-parse --show-toplevel` and confirm the toplevel is your worktree (it contains `.claude/worktrees/`). If it doesn't, you are writing to the main repo and will corrupt other agents' work. Stop and report the issue. +- **Base check:** if the brief gives a base SHA and `git merge-base --is-ancestor HEAD` fails, run `git rebase ` (a fresh worktree fast-forwards) and re-check. If it still fails, stop and report. +- **Env files:** symlink each env file the brief lists from the main checkout (`ln -s
/ `). Never `cat` or copy its contents into output. +- **Scratch:** use the brief's scratch dir for scripts and PID files (`$!` to `/.pid`). +- **Evidence** (screenshots, logs, budget JSON) goes to `.devline/out/` in your working tree; report those paths. +- **Partial work:** if the brief points at a `partial.patch` from a killed predecessor, read it and reuse only what you verify against the plan and tests. Say what you kept. - Use `--no-daemon` for Gradle/Maven to avoid daemon lock contention - Isolate Gradle caches: run `export GRADLE_USER_HOME="$(pwd)/.gradle-home"` as your very first command. Verify it points to YOUR worktree directory (`echo $GRADLE_USER_HOME` — must contain `.claude/worktrees/`), not the main repo. Sharing `GRADLE_USER_HOME` across parallel agents corrupts caches. - For npm/yarn/pnpm: use `--frozen-lockfile` to avoid lock contention @@ -151,7 +158,7 @@ Minimize build invocations — each cold start adds 10-15s overhead. | Cargo | `cargo test my_test` | `cargo test` | **Error recovery:** -- Follow kb-engineering `agent-process.md` ("When it does not work"): after two failed attempts at the same fix, stop and re-diagnose. If that does not resolve it, document it, commit what you have, report back. +- Follow kb-engineering `agent-process.md` ("When it does not work"): after two failed attempts at the same fix, stop and re-diagnose. If that does not resolve it, document it, commit what you have if in a worktree (otherwise leave it), report back. - If a build hangs past the timeout, investigate the root cause (daemon lock, infinite loop) and try once more with `--no-daemon`. ## Bash Discipline @@ -170,13 +177,18 @@ Minimize build invocations — each cold start adds 10-15s overhead. ### Test Results - X tests passed, Y failed, Z skipped +- Red: failed with before the change (one line per behavior, or "not applicable: ") ### Verification Evidence [all seven fields as in kb-engineering "Verification": Commands, Real-app run (with output dir), Screenshots read, Log scan, Budgets, Flake checks, Not verified; write an unused one as "not run: reason", never drop it] +### Integration notes +[what downstream tasks must know: new names, contracts, workarounds; "none" allowed] + ### Notes - Test depth worked at: [deep | focused] - Checklists read: [files and groups you opened with Read; `testing.md` Core is always one, so "none" means step 2 is unfinished] - [Deviations from plan or issues discovered] - [Dependencies on other tasks] +- Committed: yes (worktree branch) | no (in place) ``` From 5303ed024f3105d72c93025a461707d0ad54826a Mon Sep 17 00:00:00 2001 From: Marlon Kranz Date: Tue, 17 Nov 2026 23:35:13 +0100 Subject: [PATCH 07/17] feat(reviewer): structure fit, focus reviews and red-run check A focus parameter (security, resources, optimization, best-practices) runs the specialist stages without new agents. Builds go through the launcher's shared lock, in-place changes are reviewed against the base, and missing red-run evidence blocks bug fixes. --- agents/reviewer.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/agents/reviewer.md b/agents/reviewer.md index e881d7e..f4c47bb 100644 --- a/agents/reviewer.md +++ b/agents/reviewer.md @@ -57,7 +57,18 @@ The launcher passes one of two scopes: 9. **Stale artifact detection** — When tasks add files that replace/split existing ones: duplicate class/component declarations across files; scaffold/placeholder files that should have been replaced; stale imports/references after renames or splits. -10. **Run tests (MANDATORY)** — Execute the suite once with `timeout: 300000`; also run typecheck and build. A runtime-facing task without `### Verification Evidence` (see kb-engineering "Verification Evidence"), or with failed log scans or budgets, is blocking. Read the screenshots the implementer reported. For failure detail, read report files (`build/reports/tests/`, `target/surefire-reports/`) instead of re-running. **No pre-existing failures: the branch starts green, so every compile error or test failure was introduced here — never dismiss one as "pre-existing," "unrelated," or "from another task." Any compile error or test failure is automatically BLOCKING.** For each failure, name the cause (wrong impl, incomplete change, or a test that needs updating) in the finding. +10. **Structure fit** — Did the change go through the architecture or grow around it? Look for appended special cases, duplicated branches, flags threaded through layers. Note optimization opportunities in touched code; deferrable unless measurable. A preparatory refactor the plan offered and the user accepted, but the implementation skipped, is blocking. + +11. **Run tests (MANDATORY)** — Execute the suite once with `timeout: 300000`; also run typecheck and build. If the launcher names a shared lock, run builds and full suites as `nice -n 19 flock ` so parallel reviewers don't clobber shared build output. For uncommitted (in-place) changes, review `git diff ` plus untracked files, not `HEAD~1`. A task without `- Red:` evidence is blocking for a bug fix, deferrable otherwise. A runtime-facing task without `### Verification Evidence` (see kb-engineering "Verification Evidence"), or with failed log scans or budgets, is blocking. Read the screenshots the implementer reported. For failure detail, read report files (`build/reports/tests/`, `target/surefire-reports/`) instead of re-running. **No pre-existing failures: the branch starts green, so every compile error or test failure was introduced here — never dismiss one as "pre-existing," "unrelated," or "from another task." Any compile error or test failure is automatically BLOCKING.** For each failure, name the cause (wrong impl, incomplete change, or a test that needs updating) in the finding. + +## Focus (optional) + +The launcher may pass `focus:` with one or more values. With a focus, review only that area, in depth; verdicts are unchanged. + +- `security`: read `${CLAUDE_PLUGIN_ROOT}/skills/kb-engineering/checklists/security.md` in full and run the project's dependency audit. +- `resources`: run the project's budgets, or `${CLAUDE_PLUGIN_ROOT}/skills/kb-engineering/helpers/procbudget.py` per `performance.md`; report the numbers. +- `optimization`: hot paths and allocations in touched code; each finding carries a measurement or the reason it can't be measured. +- `best-practices`: the relevant references: kb-engineering stack checklists, and for UI the design skill's `${CLAUDE_PLUGIN_ROOT}/skills/design/references/craft-floor.md` and `antipatterns.md` (plus `${CLAUDE_PLUGIN_ROOT}/skills/kb-m3e/SKILL.md` when the project uses Material 3). ## Test depth (both scopes) From f892c8125a1beecf430e07f02be11dac37face97 Mon Sep 17 00:00:00 2001 From: Marlon Kranz Date: Tue, 17 Nov 2026 23:35:13 +0100 Subject: [PATCH 08/17] feat(brainstorm): grill in rounds over the decision frontier Each round asks every open decision whose prerequisites are settled, with a recommended answer, and sends facts to Explore subagents. A clear idea runs zero rounds. Adapted from Matt Pocock's grilling skill (MIT). --- skills/brainstorm/SKILL.md | 30 ++++++++++++++++++------------ 1 file changed, 18 insertions(+), 12 deletions(-) diff --git a/skills/brainstorm/SKILL.md b/skills/brainstorm/SKILL.md index 267720d..a17f986 100644 --- a/skills/brainstorm/SKILL.md +++ b/skills/brainstorm/SKILL.md @@ -28,18 +28,20 @@ Read the user's input. Briefly scan the existing codebase for context — just e Use explore subagents only if the idea is vague enough to need codebase context. -### 2. Clarify with Structured Questions +### 2. Grill in Rounds -Use the **AskUserQuestion** tool with concrete selectable options. +List the decisions this feature needs and how they depend on each other: a decision that only makes sense once another is answered sits below it. The frontier is every open decision whose prerequisites are settled. -- Ask **1-4 questions in a single AskUserQuestion call** -- **Scale questions to ambiguity:** Clear ideas need 0-1 questions. Vague ideas need 2-4. State obvious defaults as assumptions in the output. -- Every question MUST have **2-4 concrete options** with labels and descriptions -- Use `multiSelect: true` when choices aren't mutually exclusive -- Add a recommended option first with "(Recommended)" when there's a clear best choice -- **Always ask about platform** when the feature involves a UI +Each round: +- **Ask the whole frontier at once**, and nothing that depends on an open answer. Answers open the next frontier; repeat. +- **Use AskUserQuestion**, at most 4 questions per call; use several calls when the frontier is larger. Give 2-4 concrete options with labels and descriptions (`multiSelect: true` when they aren't exclusive). Use a plain free-text question when no options fit. +- **Recommend an answer for every question.** List it first, labeled "(Recommended)", worded so that accepting it is the default. +- **Look up facts, don't ask for them.** If the code or environment can answer, send Explore subagents in parallel. Only the questions that depend on those facts wait. +- **Never decide for the user.** Scope, behavior, platform and trade-offs are theirs to answer. -**Focus questions on:** scope and boundaries, user-facing behavior, platform, aesthetic direction, integration points. +Stop when the frontier is empty. A clear idea may have an empty frontier after reading the code: run zero rounds and state your assumptions in the output. + +Always put these on the frontier: **platform** when the feature involves a UI, and **test depth** (step 4). Questions that talking can't settle, such as how something looks or feels, go to the design stage, not to more rounds. ### 3. Evaluate Scope and Detect Phases @@ -133,7 +135,7 @@ After receiving answers (or immediately if the idea is clear enough), write `.de Use AskUserQuestion: ```json { - "question": "Brainstorm written to .devline/brainstorm.md. Does this capture what you want?", + "question": "Brainstorm written to .devline/brainstorm.md. Do we now understand the same thing?", "header": "Confirm Brainstorm", "options": [ {"label": "Looks good, proceed!", "description": "Hand off to the planner"}, @@ -143,13 +145,17 @@ Use AskUserQuestion: } ``` -If the user wants changes, update `.devline/brainstorm.md` and confirm again. +This confirms shared understanding: the frontier is empty and the document says what the user means. If the user wants changes, update `.devline/brainstorm.md` and confirm again. ## Guidelines - Write `.devline/brainstorm.md` — this is the deliverable - Stay high-level — architecture and scope, not implementation - Be conversational and fast — the user wants momentum -- Always use AskUserQuestion with structured options +- Use AskUserQuestion with structured options, each with a recommended answer - Default to sensible assumptions and state them in the document - Always identify UI impact explicitly — the planner and design system stage depend on it + +## Credits + +The grilling rounds are adapted from Matt Pocock's `grilling` skill, used under the MIT license: https://github.com/mattpocock/skills From df1edf28b30dffc73faef6c2b0ad277ce6b621d1 Mon Sep 17 00:00:00 2001 From: Marlon Kranz Date: Tue, 17 Nov 2026 23:35:13 +0100 Subject: [PATCH 09/17] feat(handoff): add /devline:handoff Writes .devline/handoff.md with the seven parts of the compaction summary plus a read-next list, and prints the first message for a fresh session. Runs only when typed. --- skills/handoff/SKILL.md | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 skills/handoff/SKILL.md diff --git a/skills/handoff/SKILL.md b/skills/handoff/SKILL.md new file mode 100644 index 0000000..0d46672 --- /dev/null +++ b/skills/handoff/SKILL.md @@ -0,0 +1,36 @@ +--- +name: handoff +description: Write a handoff file so a fresh session can pick up this work. Runs only when typed as /devline:handoff. Saves goal, user instructions, failed attempts, working state and open questions to .devline/handoff.md, then prints the one line to start the new session with. +argument-hint: "[focus]" +user-invocable: true +disable-model-invocation: true +--- + +# Handoff + +Write `.devline/handoff.md` so a new session can continue without this conversation. `$ARGUMENTS` is an optional focus: weight the file toward it. + +## Rules + +- Point, don't copy. Name plans, commits, state files, logs and diffs by path or SHA. Quote only the specific error lines the work is about. +- Strip secrets: no tokens, keys, passwords or `.env` contents. Name the file, never its values. +- Keep paths, URLs and identifiers exact. +- Do not stop agents, commit or change anything else. + +## Steps + +1. Find the git root. Create `.devline/` there. If git does not already ignore it, add it to `.git/info/exclude`. +2. If `.devline/handoff.md` exists, show its modification date and ask before overwriting. If the user declines, stop. +3. Write the file with these sections, in order: + 1. **Goal and status**: what the user asked for overall, what is done, what is in progress right now, and the immediate next step. + 2. **Everything the user pointed you to**: one line each, with the context and intent it was given in: file paths, directories, log locations, URLs, repos, screenshots (what they showed and what the user wanted noticed), commands, error messages. + 3. **What the user said**: requirements, decisions, preferences and every correction, with what was wrong. Quote short ones verbatim. Mark which are already written to a file (give the path) and which exist only in this conversation. + 4. **Attempts that failed**: for the current problem, each approach tried, how it failed (error, symptom, measurement) and why, including hypotheses ruled out and the evidence. + 5. **Working state**: files changed and why, branches, worktrees, running processes or servers (PID or how to find them), background agents and what each is doing, uncommitted work. + 6. **Open questions waiting on the user**, and what each answer unblocks. + 7. **Skills, commands or references the next steps will need.** + 8. **Read next**: an ordered list of files to read first, most important first, each with a few words on why. +4. If `.devline/state.md` exists, add the pipeline to Working state: current stage, chosen stages, tasks in progress, worktrees, and whether agents are still running. Agents do not survive the session, so say that any running agent is lost and its task must be relaunched; point at `.devline/tasks/N/partial.patch` where one exists. +5. Print the first message for the new session, with the absolute path: + + `Read /.devline/handoff.md and continue.` From 4779484dc5eb8569be97cc56239afcdc2fa8c462 Mon Sep 17 00:00:00 2001 From: Marlon Kranz Date: Tue, 17 Nov 2026 23:35:13 +0100 Subject: [PATCH 10/17] feat(devline): protocols for base checks, evidence and partial work Worktree launches record the base SHA and check disk space, evidence is copied out before removal, running agents are stopped first, and a killed agent's work is saved as a patch for its successor to evaluate. In-place agents never commit. The state file gains a Stages table and Agent and Worktree columns. --- skills/devline/references/agent-health.md | 2 +- skills/devline/references/recovery.md | 28 ++++++---- .../devline/references/worktree-protocol.md | 53 +++++++++++++------ 3 files changed, 55 insertions(+), 28 deletions(-) diff --git a/skills/devline/references/agent-health.md b/skills/devline/references/agent-health.md index f6911db..b2f34e9 100644 --- a/skills/devline/references/agent-health.md +++ b/skills/devline/references/agent-health.md @@ -9,7 +9,7 @@ Elapsed time is computed from the absolute ISO 8601 timestamp in `state.md`'s Ta | < 20 min | Normal operation | — | | 20 min | `SendMessage` nudge: "Status check — progress and blockers?" | ⚠️ | | 30 min | Investigate: check written files, query via `SendMessage` for detailed status. If clearly progressing, let continue. | 🐌 | -| 45 min | **Hard kill.** `TaskStop` immediately. Follow killed-agent recovery protocol (see worktree-protocol.md). Relaunch fresh agent with context from previous work. | 🔁 | +| 45 min | **Hard kill.** `TaskStop` immediately. Save its partial work as `partial.patch` and relaunch a fresh agent per the killed-agent recovery protocol (worktree-protocol.md); the new brief points at the patch to evaluate, not trust. | 🔁 | If a task fails on its second relaunch (three total attempts): escalate to the user. diff --git a/skills/devline/references/recovery.md b/skills/devline/references/recovery.md index de21bc5..a0f9df4 100644 --- a/skills/devline/references/recovery.md +++ b/skills/devline/references/recovery.md @@ -18,12 +18,18 @@ Create when entering Stage 3. Update after every status change. Always end the f - **Active agents:** 3/10 - **Pipeline started:** 2026-03-20T14:00:00 +## Stages +| Stage | Reason | Added at | +|-------|--------|----------| +| security scan | touches auth | assess | +| optimization pass | hot path in task 4 | plan | + ## Task Progress -| # | Status | Review Attempts | Notes | -|---|--------|-----------------|-------| -| 1 | done | 1 (CLEAN) | | -| 2 | building | 0 | Launched 2026-03-20T14:28:00 | -| 3 | blocked | 0 | Waiting on 1 | +| # | Status | Agent | Worktree | Review Attempts | Notes | +|---|--------|-------|----------|-----------------|-------| +| 1 | done | implementer (sonnet) | | 1 (CLEAN) | | +| 2 | building | implementer (sonnet) | .claude/worktrees/abc123 | 0 | Launched 2026-03-20T14:28:00 | +| 3 | blocked | | | 0 | Waiting on 1 | ## Pending Fix Cycles | Task | Fix File | Created | @@ -40,6 +46,8 @@ Create when entering Stage 3. Update after every status change. Always end the f Key schema rules: - **Active agents** counter tracks concurrency against the 10-agent limit - **Launched** timestamps are absolute ISO 8601 — they survive compaction and enable health monitoring to compute elapsed time after recovery +- **Stages** lists the extra stages added beyond the preset and why; **Added at** is `assess` or `plan` +- **Agent** and **Worktree** record who runs the task and where; no agent IDs (they go stale, see recovery step 6) - **Pending Fix Cycles** tracks orphaned fix-task files so recovery can resume them - Task **Status** values: `blocked`, `queued`, `building`, `reviewing`, `fixing`, `done`, `failed` @@ -74,8 +82,8 @@ If unsure of pipeline state — after compaction, conversation resume, or starti 4. **Read the active plan file** — `.devline/plan.md` for single-phase, or `.devline/plan-phase-N.md` (where N is the current phase from state.md) for multi-phase — restore task definitions, dependencies, acceptance criteria. Validate `**Branch:**` and `**Status:**` against current git state. 5. **Cross-check git log against state.md** — run `git log --oneline` and grep for `task-N:` commits. If a task has a commit in git but state.md shows `building` or `reviewing`, the crash happened after commit but before state update — mark that task as `done` in state.md. This prevents relaunching already-completed tasks. 6. **Check `TaskList`** — this is the ground truth for what agents are running (state.md agent IDs are conversation-scoped and may be stale after compaction). -7. **Check for orphaned `.devline/fix-task-*.md` files** — each represents an interrupted fix cycle. Resume by launching an implementer for each. -7. **Read `.devline/agent-log.md`** if it exists — the SubagentStop hook logs agent completions here. Cross-reference with state.md to identify agents that completed but weren't processed (e.g., due to compaction between completion and processing). -8. **Recompute active agent count** from TaskList and update state.md. -9. **Recompute elapsed times** from absolute timestamps in state.md's Task Progress table. Resume health monitoring escalation based on actual elapsed time. -10. Resume orchestration from the recovered state. +7. **Check for orphaned `.devline/fix-task-*.md` files** — each represents an interrupted fix cycle. Resume by launching an implementer for each. Also check `.devline/tasks/*/partial.patch`: a task with a patch and no running agent is relaunched fresh with the patch named in its brief. +8. **Read `.devline/agent-log.md`** if it exists — the SubagentStop hook logs agent completions here. Cross-reference with state.md to identify agents that completed but weren't processed (e.g., due to compaction between completion and processing). +9. **Recompute active agent count** from TaskList and update state.md. +10. **Recompute elapsed times** from absolute timestamps in state.md's Task Progress table. Resume health monitoring escalation based on actual elapsed time. +11. Resume orchestration from the recovered state. diff --git a/skills/devline/references/worktree-protocol.md b/skills/devline/references/worktree-protocol.md index 1ac0d80..58e8f3f 100644 --- a/skills/devline/references/worktree-protocol.md +++ b/skills/devline/references/worktree-protocol.md @@ -22,6 +22,17 @@ Before launching ANY agent with `isolation: "worktree"`, run these checks in ord ``` If there are uncommitted changes, commit or stash them before launching agents. +4. **Disk check** — a parallel wave fills `/tmp` and the repo disk quickly: + ```bash + df -h /tmp "$(git rev-parse --show-toplevel)" + ``` + If either has less than about 5 GB free, warn the user and ask before launching. + +5. **Record the base SHA** — pass it in every agent brief so the agent can verify its worktree starts from it: + ```bash + git rev-parse HEAD + ``` + ## Launching Agents in Worktrees All implementer agents use `isolation: "worktree"` for parallel safety. The worktree is automatically created from the current branch HEAD by the Agent tool — there is no manual branch specification needed. **If the pre-launch checklist passes (correct CWD, correct branch, clean state), the worktree will have the correct base.** @@ -32,20 +43,22 @@ Agent(subagent_type="devline:implementer", isolation="worktree", run_in_backgrou Fix-cycle and deferred-findings batch-fix implementers also use worktree isolation. -If the pre-launch checklist shows you're inside a worktree and cannot `cd` out: launch implementers **sequentially without isolation** (they commit directly to the current branch). Skip the merge-back protocol. +If the pre-launch checklist shows you're inside a worktree and cannot `cd` out: launch implementers **sequentially without isolation** (they never commit; see Non-Isolated Agent Rules). Skip the merge-back protocol. ## Non-Isolated Agent Rules -When agents run without worktree isolation (e.g., after a conflict-triggered relaunch), they write directly to the feature branch. This creates critical constraints: +When agents run without worktree isolation (sequential fallback, quick lane, or a conflict-triggered relaunch), they write to the feature branch working tree. They never commit. -1. **NEVER run non-isolated agents in parallel.** They will write uncommitted changes to the same directory simultaneously, causing compilation failures, file corruption, and mixed-task commits. Launch one, wait for it to complete and commit, then launch the next. -2. **Never batch-commit mixed agent work.** If multiple agents left uncommitted changes, do NOT `git add -A && git commit`. Each task must have its own commit. Stash the mess, relaunch agents one at a time. -3. **Never use `git add -A` or `git add .`** — always stage specific files by name. Broad staging commits build caches, IDE files, and other artifacts. +1. **NEVER run non-isolated agents in parallel.** They write to the same directory simultaneously, causing compilation failures and file corruption. Launch one, wait for it to stop, then launch the next. +2. **The orchestrator commits** after the task is reviewed, once every agent has stopped and `git status --short` shows only the intended files. One commit per task. +3. **Never use `git add -A` or `git add .`** — stage specific files by name. Broad staging commits build caches, IDE files, and other artifacts. ## Merge-Back Protocol After each worktree agent completes (result includes worktree path and branch name), **first verify your CWD is the main repo root** (not inside a worktree). Run `pwd` — if it contains `.claude/worktrees/`, `cd` back to the main repo root before merging. +0. **Isolation check:** `git -C
status --short` must show nothing new. New changes or untracked files mean the agent wrote to the wrong tree: treat it as an isolation failure (see below) and do not merge. + 1. **Squash-merge** the branch (one clean commit per task, no merge commits): ```bash git merge --squash @@ -59,9 +72,13 @@ After each worktree agent completes (result includes worktree path and branch na **Handling failures:** - **Conflict:** abort the squash-merge state (`git reset HEAD -- . && git checkout -- .`), clean up the worktree (step 2), and relaunch the implementer **without isolation** on the feature branch. Do NOT resolve conflicts yourself — not with `checkout --ours`, not with `checkout --theirs`, not by editing conflict markers. Note: `git merge --abort` does NOT work after `git merge --squash` because squash-merge doesn't create a MERGE_HEAD — use `git reset HEAD -- . && git checkout -- .` instead. **Root cause:** A same-wave conflict means two tasks modified the same file (usually shared resources like translation files, global CSS, route configs). After relaunching, flag this to the user and note in `.devline/state.md` that the plan has a shared-resource overlap. - - **"Already up to date" / nothing staged after squash:** the agent committed to the feature branch directly instead of its worktree branch. Check `git log --oneline -3` — if the task's commit appears on the feature branch, it's already merged (skip squash-merge, proceed to reviewer). Clean up the worktree (step 2). **This is a worktree isolation failure** — note it in state.md so future waves are aware the branch moved. + - **"Already up to date" / nothing staged after squash:** the agent worked in the main checkout instead of its worktree. Check `git status --short` and `git log --oneline -3`. **This is a worktree isolation failure** — note it in state.md, clean up the worktree (step 2), and do not merge or commit that work; relaunch the task without isolation. -2. **Clean up** (after commit succeeds OR on failure before relaunch): +2. **Clean up** (after commit succeeds OR on failure before relaunch). First `TaskStop` any agent still running for this worktree; a running agent keeps the worktree locked and can edit files after removal starts. Then copy the evidence out, since it dies with the worktree: + ```bash + mkdir -p .devline/tasks/N && cp -r /.devline/out/. .devline/tasks/N/ 2>/dev/null + ``` + Then remove: ```bash git worktree remove --force 2>/dev/null rm -rf 2>/dev/null @@ -82,28 +99,30 @@ If the agent result says no changes were made, the worktree is auto-cleaned — ## Killed-Agent Recovery -When you TaskStop a stuck agent or an agent completes without committing: +When you TaskStop a stuck agent or an agent stops without committing: -1. **Clean up** the worktree and branch — don't try to salvage uncommitted work: +1. **Save the partial work as a patch**, without reading it: ```bash - git worktree remove --force 2>/dev/null - rm -rf 2>/dev/null - git branch -D 2>/dev/null + mkdir -p .devline/tasks/N + git -C diff HEAD > .devline/tasks/N/partial.patch + git -C ls-files --others --exclude-standard > .devline/tasks/N/partial-untracked.txt ``` -2. **Relaunch** a fresh implementer for the same task. The new agent starts clean from the current branch state. + Append each untracked file to `partial.patch` as a new-file hunk, or keep the list. Copy `/.devline/out/` to `.devline/tasks/N/` too. +2. **Clean up** the worktree and branch (Merge-Back step 2). +3. **Relaunch** a fresh implementer for the same task. Its brief points at `partial.patch` as work to evaluate, not trust: it may reuse what holds up and must redo the rest. -Do NOT inspect the worktree's diff, commit on behalf of the agent, or try to merge partial work. A failed agent means a fresh start. +Never merge, apply or commit the partial work yourself. ## Wrong-Base Recovery If an agent's worktree branched from the wrong commit (e.g., an old branch instead of the current HEAD): 1. **Do NOT extract diffs and apply them manually.** The agent's work was done against stale code — field mappings, imports, and logic may all be wrong even if the diff "looks right." -2. Clean up the worktree and branch (same as killed-agent recovery). +2. Clean up the worktree and branch (Merge-Back step 2). 3. Run the pre-launch checklist to fix whatever caused the wrong base (usually: cwd was inside a worktree, or uncommitted changes on the branch). 4. Relaunch a fresh implementer. ## Build Isolation Instructions -When launching implementers, include in the prompt: -> Use `--no-daemon` for all build tool commands (Gradle, Maven, etc.) to avoid daemon contention. Since you are in a worktree, isolate Gradle caches by running this as your FIRST command before any build: `export GRADLE_USER_HOME="$(pwd)/.gradle-home"`. This MUST resolve to your worktree path (e.g., `/home/user/repo/.claude/worktrees/abc123/.gradle-home`), NOT the main repo path. Verify with `echo $GRADLE_USER_HOME` — if it points to the main repo, parallel builds will corrupt each other's caches. +Each agent keeps its caches and toolchain root inside its own worktree. When launching implementers, include in the prompt: +> Use `--no-daemon` for all build tool commands (Gradle, Maven, etc.) to avoid daemon contention. Keep caches in your worktree: as your FIRST command, run `export GRADLE_USER_HOME="$(pwd)/.gradle-home"` (or the equivalent for your build tool) and verify with `echo $GRADLE_USER_HOME` that it points inside your worktree, not the main repo; parallel builds corrupt each other's caches otherwise. Run heavy builds and full suites through `nice -n 19 flock /tmp/-build.lock `. Builds write to the worktree or `~/.cache/`, not `/tmp`. From a319815689c7b88c9ab4569bafd2b40508da1bb7 Mon Sep 17 00:00:00 2001 From: Marlon Kranz Date: Tue, 17 Nov 2026 23:36:23 +0100 Subject: [PATCH 11/17] feat(devline): stage menu composed by reach A new stages reference lists every stage with what pulls it in, the quick, implement and full presets, and how a run is shown and recorded. kb-blast-radius gains a Reach section: seven categories with request and code signals, run on seed files before code exists. Reach only adds stages to a preset. --- skills/devline/references/stages.md | 61 +++++++++++++++++++++++++++++ skills/kb-blast-radius/SKILL.md | 29 +++++++++++++- 2 files changed, 89 insertions(+), 1 deletion(-) create mode 100644 skills/devline/references/stages.md diff --git a/skills/devline/references/stages.md b/skills/devline/references/stages.md new file mode 100644 index 0000000..51d3db9 --- /dev/null +++ b/skills/devline/references/stages.md @@ -0,0 +1,61 @@ +# Stages + +The menu a run is composed from. The orchestrator picks a preset, adds the stages that the change's reach pulls in, shows the result and records it. Reach categories and their signals are in `kb-blast-radius` (`## Reach`). + +## Stages + +| Stage | What runs | Pulled in by | +|---|---|---| +| `brainstorm` | brainstorm skill, with grilling rounds | `full` preset; an unclear or open-ended request | +| `design` | design skill with designer agents (Stage 1.5) | reach: UI with a new or changed visible surface | +| `planner` | planner agent, plan approval | `full` preset; more than one implementer | +| `preparatory refactor` | implementer on the planner's refactor-first task | the planner offers one and the user accepts it at plan approval | +| `implementers` | implementer agents: 1, or N parallel; N > 1 requires planner | every preset | +| `per-task review` | reviewer `scope: task` after each task | every preset | +| `branch review` | reviewer `scope: branch` on sonnet | `full` preset; a large change with no reach category | +| `deep review` | reviewer `scope: branch` on opus | `full` preset; reach: security surface, public contract, persisted data, concurrency | +| `security scan` | reviewer `focus: security` | reach: security surface | +| `resource profiling` | reviewer `focus: resources` | reach: resource use | +| `optimization pass` | reviewer `focus: optimization` | reach: resource use on a hot path; a request about speed or size | +| `best-practices review` | reviewer `focus: best-practices` | reach: UI, build/release; a new stack or framework in the project | +| `docs` | docs-keeper | `implement` and `full` presets; reach: public contract | +| `final gate` | merged-tree gate, final commit, merge/PR question | every preset | + +## Presets + +- **quick**: `implementers`, `per-task review`, `final gate` +- **implement**: `implementers`, `per-task review`, `docs` +- **full**: `brainstorm`, `design`, `planner`, `preparatory refactor`, `implementers`, `per-task review`, `branch review`, `deep review`, `docs`, `final gate` + +`quick` runs one implementer in place, and its final gate is the commit plus the merge/PR question. `implement` starts from an existing plan. In `full`, `design` runs only with UI reach and `preparatory refactor` only when the user accepts one; the specialists come only from reach. + +## Composing a run + +1. **Preset** from the command: + - `/devline:quick` → `quick` + - `/devline:implement` → `implement` + - `/devline` → the devline config's `fast_lane`: `auto` lets the orchestrator start from `quick` for a change of about one file with no reach category; `always` → `quick`; `off` → `full`. +2. **Reach:** run the `kb-blast-radius` Reach steps on the request and add every stage its categories pull in. Reach only adds stages; it never removes one from the preset. An explicit preset wins over size, so `quick` on a new endpoint stays `quick` plus what reach adds. +3. **Bug fixes** start from the debugger route plus `per-task review`, then reach adds. + +Examples: a one-line change to auth input validation is security surface, so it gets `security scan` and `deep review` even under `quick`. An isolated refactor with no reach category gets none of the specialists. + +## Showing the run + +Show a short table, one line per chosen stage: + +| Stage | Reason | +|---|---| +| `implementers` | preset `quick` | +| `security scan` | reach: security surface (auth input parsing) | + +Then, by the devline config's `stage_menu` (lookup in `${CLAUDE_PLUGIN_ROOT}/skills/setup/references/config.md`): + +- `ask` (default): AskUserQuestion with "Run as shown", "Change stages", "Stop". On "Change stages" the user names adds and removes in free text; apply them and show the table again. +- `auto`: print the table and proceed. + +An explicit preset with no reach additions prints the table and proceeds, whatever `stage_menu` says. + +## Recording + +Write the chosen stages and their reasons to `.devline/state.md` under `## Stages` (schema in `recovery.md`). Run only the recorded stages. Stages added at plan approval, from plan tasks' `**Reach:**` lines, are appended with their reason and shown again before implementation starts. diff --git a/skills/kb-blast-radius/SKILL.md b/skills/kb-blast-radius/SKILL.md index 04527a8..ee1775b 100644 --- a/skills/kb-blast-radius/SKILL.md +++ b/skills/kb-blast-radius/SKILL.md @@ -1,6 +1,6 @@ --- name: kb-blast-radius -description: Grep-based reverse dependency analysis — injected into the planner and reviewer agents. Computes which files are affected by changes to a set of seed files. Not invoked directly. +description: Grep-based reverse dependency analysis plus reach classification — injected into the planner and reviewer agents and read by the devline orchestrator before Stage 1. Computes which files are affected by changes to a set of seed files and which kinds of risk (reach) a change has, which decides the stages a run gets. Not invoked directly. user-invocable: false disable-model-invocation: false --- @@ -14,6 +14,7 @@ Lightweight, zero-dependency reverse dependency analysis using grep-based import - **Planner:** Before task decomposition — identify coupled files so tasks have correct boundaries and file ownership. - **Reviewer:** After implementation — verify the implementer considered all dependents of changed files. - **Reviewer (scope: branch):** During the cross-task integration sweep — structurally validate that all dependents were covered across the full changeset. +- **Orchestrator:** before Stage 1, to compose the run (see devline references/stages.md) ## How It Works @@ -26,6 +27,32 @@ Lightweight, zero-dependency reverse dependency analysis using grep-based import Supports: TypeScript, JavaScript, Python, Go, Rust, Java, Kotlin, Ruby, PHP, C/C++, Vue, Svelte. +## Reach + +Reach is what a change can affect beyond the lines it touches. Each category pulls stages into the run (mapping in devline `references/stages.md`). A one-line change can have reach; a large change can have none. + +### Before code exists + +1. Guess seed files from the request: `git grep -l -i ''` for the nouns it names (feature, endpoint, flag, table, component). +2. Run `--target` on them (`--depth 1` is enough here). +3. Check the request text, the seeds and their dependents against the signals below. Every category with a match applies; name the matching signal as the reason. + +After implementation, the reviewer can repeat step 3 on `--changed` output. + +### Categories + +| Category | Signals in the request | Signals in seeds and dependents | Related reference | +|---|---|---|---| +| Security surface | auth, login, token, permission, password, secret, upload, input validation, shell out, URL fetch | paths or imports with `auth`, `session`, `crypto`, `acl`; request handlers that read input; `exec`/`subprocess`/`spawn`; file path handling; dependency manifest changes | kb-engineering `security.md` | +| Resource use | slow, memory, CPU, large files, batch, cache, startup, polling | loops over I/O, queries in loops, caches, workers, schedulers, long-running processes, new dependencies | kb-engineering `performance.md` | +| Public contract | API, endpoint, CLI flag, config key, file format, rename, deprecate | exported symbols with many dependents, route definitions, argument parsers, config loaders, serializers, OpenAPI/proto/schema files | kb-engineering `backend.md` (and the stack checklist) | +| Persisted data | schema, migration, column, table, stored format, backup | `migrations/`, ORM models, SQL files, on-disk formats, serialization of saved state | kb-engineering `reliability.md` | +| UI | page, screen, component, layout, theme, style, accessibility | component and style files, templates, design tokens, assets | kb-engineering `web.md` or `desktop.md`; the design skill's references; `kb-m3e` for Material 3 | +| Concurrency / shared state | parallel, async, race, lock, queue, retry, cache invalidation | threads, goroutines, async tasks, locks, global or module state, shared files, message brokers | kb-engineering `reliability.md`, `distributed.md` | +| Build / release / CI | build, deploy, release, CI, package, version, Docker | build and CI config (`.github/workflows/`, `Dockerfile`, `package.json` scripts, `Makefile`), lockfiles, version files | kb-engineering stack checklist `## Verify it` | + +No match in any category means no reach: the preset's stages are enough. + ## Running the Script The script is at `${CLAUDE_SKILL_DIR}/scripts/blast-radius.sh`. Invoke it from the project's working directory. From 48889157e90317e22f744983740482abf58b42dc Mon Sep 17 00:00:00 2001 From: Marlon Kranz Date: Tue, 17 Nov 2026 23:36:23 +0100 Subject: [PATCH 12/17] feat(devline): agent briefs and merged-tree gates Briefs carry facts only (base SHA, owned files, env files, scratch dir, build lock, integration notes, partial patch, focus) and never a report format. The main session runs typecheck, build and the full suite once per wave and before the final commit. In-place agents never commit; the main session commits once every agent has stopped. --- .../references/implementation-protocol.md | 60 +++++++++++++------ 1 file changed, 42 insertions(+), 18 deletions(-) diff --git a/skills/devline/references/implementation-protocol.md b/skills/devline/references/implementation-protocol.md index 84a4a06..1978a2f 100644 --- a/skills/devline/references/implementation-protocol.md +++ b/skills/devline/references/implementation-protocol.md @@ -17,7 +17,7 @@ Execution proceeds in **waves** as defined in the `## Dependency Graph` section **Wave barrier validation (mandatory before launching any wave):** Before launching tasks for Wave N (where N > 1), read `.devline/state.md` and verify that EVERY task from waves 1 through N-1 has status `done`. If any prior-wave task is not `done`, do NOT launch Wave N — wait for the incomplete tasks to finish first. This is a programmatic check, not a judgment call. 1. Launch all Wave 1 tasks in parallel (background, worktree isolation — see `references/worktree-protocol.md`) -2. As each task completes: squash-merge its worktree branch (`git merge --squash` + `git commit -m "task-N: "`), launch reviewer +2. As each task completes: merge it back per `references/worktree-protocol.md` (stop the agent first), append its `### Integration notes` to `.devline/integration-notes.md` under the task, launch reviewer 3. **Wait until ALL Wave 1 tasks are done** (implemented + reviewed + merged). Do NOT launch any Wave 2 task early, even if its specific dependencies are met. 4. Run the wave barrier validation, then launch all tasks in the next wave. Repeat. @@ -40,6 +40,8 @@ Reviewer returns one of: - **DEFERRED_ONLY** — append findings to deferred file, mark done, check for newly unblocked tasks - **HAS_BLOCKING** — append any deferrable findings, write blocking findings to `.devline/fix-task-{N}.md`, launch implementer to fix +Specialist reviews: after per-task review is CLEAN or DEFERRED_ONLY, a task whose `**Reach:**` names categories also gets the matching `focus:` reviewer (`security scan` → `security`, `resource profiling` → `resources`, `optimization pass` → `optimization`, `best-practices review` → `best-practices`). Which categories pull in which stages is defined in `references/stages.md`. The task is done after the specialist verdicts too; their findings follow the same loop. + Fix cycle escalation: 1. **Attempt 1-2:** implementer fixes → reviewer re-reviews 2. **Attempt 3:** escalate to **planner** (foreground) with all findings and attempts — it rewrites the task approach @@ -59,27 +61,49 @@ After ALL waves are complete (every task implemented + reviewed + merged) for th The deep review is the final quality gate — it cannot defer findings. All deferrable work must be resolved before it runs. +## Agent Briefs + +The agent's own definition owns how it works and what it reports. A brief carries facts only: + +- plan path and task name (for quick, the task text) +- base SHA the worktree was created from +- owned files, and files owned by other tasks in the same wave +- env files to symlink into the worktree +- scratch directory `/task-N/` +- the build lock command from `references/worktree-protocol.md` +- integration notes from the tasks it depends on, copied from `.devline/integration-notes.md` +- the path of `.devline/tasks/N/partial.patch`, if a killed predecessor left one +- for a specialist review, `focus: ` + +A brief never prescribes TDD steps, a report format or "report X and Y": the agent's own output format stands. Fix briefs (`fix-task-N.md`) for UI tasks also name the reduced-motion, no-JS and keyboard-focus paths to recheck. + +A workaround added mid-wave (a shim, a changed helper, a renamed file) is sent to every running agent it affects. + +## Merged-Tree Gates + +After a wave's merges and before the final commit, the main session runs typecheck, build and the full suite once on the merged tree, through the build lock. Red: launch a debugger; do not run a second build or diagnose yourself. Record the results in `.devline/state.md`. + ## Agent Health Monitoring See `references/agent-health.md`. Key rule: hard kill at 45 minutes, salvage work, relaunch fresh. -## Orchestrator Scope — What You Do and Don't Do - -The orchestrator's job is: launch agents, merge worktree branches, launch reviewers, track state, and communicate with the user. That's it. -- **DO:** run the pre-launch checklist (see `references/worktree-protocol.md`), squash-merge worktree branches (`git merge --squash` + `git commit`), clean up worktrees, launch reviewer after merge, update state.md, relaunch failed agents -- **DON'T:** The following are violations — if you catch yourself doing any of these, stop and launch the appropriate agent instead: - - **Assign multiple tasks to one agent** — never "complete 2.6 + 2.7 + 2.9" or "fix the remaining gaps." One agent, one task. - - **Investigate errors beyond one build** — run the build once to see what's broken. Do NOT run a second build, filter output, run individual tests, or read source files to diagnose. Launch a debugger. - - **Multi-line code changes** — if the fix is more than one line, delegate it. - - **Commit on behalf of agents** — if the agent didn't commit, it failed. Relaunch it. - - **Batch-commit mixed agent work** — if multiple agents left uncommitted changes, do NOT `git add -A && git commit`. Stash the mess, relaunch agents one at a time. - - **Use `git add -A` or `git add .`** — always stage specific files. Broad staging commits build caches and artifacts. - - **Resolve merge conflicts** — no `checkout --ours`, no `checkout --theirs`, no editing conflict markers. Reset the squash-merge state (`git reset HEAD -- . && git checkout -- .` — note: `git merge --abort` does not work after `git merge --squash`), clean up the worktree, and relaunch the agent without isolation so it works against the current branch state (which now includes the conflicting task's code). A merge conflict between two same-wave tasks means the dependency graph has a shared-resource file overlap (usually translation files, global CSS, or route configs). After relaunching, flag this to the user so the plan can be corrected for future runs. - - **Inspect diffs to extract/apply fixes** — if the worktree is on the wrong base, the agent's work is invalid. Clean up and relaunch. - - **Run `git diff` to "check what the agent did"** — the reviewer does this, not you. - - **Run tests to "verify" a merge** — the reviewer does this. Not you. Not "just a quick check." Launch the reviewer. - - **Run non-isolated agents in parallel** — agents without worktree isolation write to the same directory. They MUST run one at a time: launch, wait for commit, then launch the next. See `references/worktree-protocol.md` for details. - - **Skip reviews** — every task gets a reviewer, no exceptions. A task is not "done" until the reviewer returns a verdict. Do not rationalize skipping reviews for "trivial" tasks, "clean" implementations, or tasks that "obviously" work because tests passed during implementation. +## Orchestrator Discipline + +The orchestrator launches agents, merges worktree branches, launches reviewers, tracks state and talks to the user. +- **DO:** run the pre-launch checklist and merge-back per `references/worktree-protocol.md`, run the merged-tree gates, launch reviewers after each merge, update state.md, relaunch failed agents +- **DON'T:** each of these is a violation; stop and launch the appropriate agent instead: + - **Assign multiple tasks to one agent.** One agent, one task. + - **Diagnose errors yourself.** A red gate goes to a debugger, not to a second build, filtered output, single tests or source reading. + - **Make multi-line code changes.** More than one line: delegate. + - **Commit for a worktree agent.** One that left no commit failed: relaunch it. Agents running in place never commit; the main session commits after review, once every launched agent has stopped. + - **Commit while an agent may still be running.** Every agent is finished or stopped, and `git status --short` shows only the intended change, immediately before a commit. Run `git status --short` in the main checkout after each agent too. + - **Batch-commit mixed agent work or use `git add -A` / `git add .`.** Stage specific files; stash mixed leftovers and relaunch agents one at a time. + - **Resolve merge conflicts.** Follow the conflict step in `references/worktree-protocol.md` and flag the shared-resource overlap to the user so the plan can be corrected. + - **Inspect diffs to extract or apply fixes.** If the worktree is on the wrong base, its work is invalid: clean up and relaunch. + - **Run `git diff` to see what an agent did.** The reviewer does that. + - **Review code yourself or skip reviews.** The reviewer reviews; the merged-tree gates are a separate, required check. + - **Run non-isolated agents in parallel.** They run one at a time; see `references/worktree-protocol.md`. + - **Publish an agent's claim unchecked.** A count or "this test does X" from a report is reproduced by a command in the main session before it enters a summary or PR body. ## Bash Discipline From df855fee16d836659f23199e68a5e5c8b9e5d7f5 Mon Sep 17 00:00:00 2001 From: Marlon Kranz Date: Tue, 17 Nov 2026 23:39:39 +0100 Subject: [PATCH 13/17] feat(devline): assess and compose the run before Stage 1 The orchestrator reads the reach categories and the stage menu, shows the composed stages (asking first when stage_menu is ask) and runs only those. The fast lane becomes the quick preset. Plan approval shows the plan's Summary for approval and any stages its tasks add, and the final gate runs the merged-tree gate with every agent stopped. Adds the stage_menu key to the config reference. --- skills/devline/SKILL.md | 78 ++++++++++++------------------- skills/setup/references/config.md | 1 + 2 files changed, 32 insertions(+), 47 deletions(-) diff --git a/skills/devline/SKILL.md b/skills/devline/SKILL.md index cdece8d..ae24fba 100644 --- a/skills/devline/SKILL.md +++ b/skills/devline/SKILL.md @@ -8,47 +8,27 @@ disable-model-invocation: false # Devline — Full Development Pipeline -You are a senior engineering manager orchestrating the full development lifecycle from idea to merge-ready code. Follow the pipeline stages exactly — do not alter or skip stages unless the user explicitly instructs it. You coordinate agents, present results, and manage pipeline flow. +You are a senior engineering manager orchestrating the development lifecycle from idea to merge-ready code. You coordinate agents, present results, and manage pipeline flow. Run exactly the stages recorded at assess time; add or drop one only when the user says so. -**Triage, don't fix.** You may run a build/test command **once** to see what's broken. That's your triage. Then delegate: +**Triage, don't fix.** The build and test runs you own are the merged-tree gate (`references/implementation-protocol.md`, `## Merged-Tree Gates`) and, on the bug-fix route, one build to see what's broken. Each runs once. Then delegate: - 0 errors → proceed - Errors you can fix with a single obvious line change (stray conflict marker, missing comma) → fix it directly - Anything else → launch a debugger agent That's it. Do NOT read source files to understand errors. Do NOT run a second build "to check." Do NOT filter test output to categorize failures. Do NOT investigate individual failing tests. Do NOT edit code beyond a one-line fix. The moment you see errors that aren't a trivial one-liner, launch a debugger and move on. -## Change Classification (before Stage 1) +## Assess and Compose (before Stage 1) -Resolve `fast_lane` from the config (see Defaults). Classify the request before starting Stage 1: +1. Read the `## Reach` section of `/../kb-blast-radius/SKILL.md` (its script is `/../kb-blast-radius/scripts/blast-radius.sh`) and `references/stages.md`. +2. Follow stages.md: pick the preset (`/devline` starts from `fast_lane`), add the stages reach pulls in, show the table per `stage_menu`, and record the result in `.devline/state.md` under `## Stages`. +3. Run only the recorded stages. A section below that starts "Runs when `` is in the run" is skipped otherwise. -- **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). -- **Otherwise** → the full pipeline (Stages 1-5) below. - -### Fast Lane - -A single task, run in place — no worktrees, no waves, no gates. - -1. **Branch setup** (Stage 0). -2. **Implement** — one implementer agent, TDD at the right level (unit for pure logic, integration for persistence/endpoints; see `kb-tdd-workflow`). -3. **ONE `reviewer` (scope=task)** — the standard per-task review. Run a fix cycle if it returns blocking findings. -4. **Commit** with the `git` skill (commit mode). Then auto-proceed and ask only: merge, open a PR (`git` pr mode), or leave it. - -The fast lane SKIPS: brainstorm + its approval gate; design (Stage 1.5); the full plan doc + plan approval gate; the mandatory Feature E2E task; worktree/wave machinery (the single task runs in place); the deferred-findings batch-fix cycle (Stage 3.5); the docs-keeper full documentation scan (Stage 4); `reviewer scope=branch` / deep review (Stage 5); and the final approval gate (it auto-proceeds, asking only whether to merge or open a PR). +- **Bug fix** (compile error, test failure, stack trace; not a new feature): run the build once, launch a **debugger**, then a **reviewer** (`scope: task`). Reach adds stages as usual. +- **`quick` preset:** Stage 0, one implementer run in place (no worktrees, waves or plan; TDD at the right level per `kb-tdd-workflow`), one `reviewer` (`scope: task`) with a fix cycle on blocking findings, then Complete with only the merge/PR question. ## Progress Tracking -Before starting any work, create these tasks using TaskCreate: - -1. "Brainstorm — Refine idea into feature spec" (activeForm: "Brainstorming feature idea") -2. "Design — Explore and pick the UI design" (activeForm: "Designing the UI") — only if UI impact detected -3. "Plan — Design architecture and tasks" (activeForm: "Planning implementation") -4. "Implement — Build and review tasks" (activeForm: "Implementing tasks") -5. "Documentation — Update project docs" (activeForm: "Updating documentation") -6. "Deep Review — Final quality and security audit" (activeForm: "Running deep review") -7. "Final Gate — User approval" (activeForm: "Awaiting user approval") - -Mark each `in_progress` when starting and `completed` when done. **Do not render a separate stage-level progress table** — the built-in task list already displays stage progress to the user. The implementation task table during Stage 3 is separate and should still be displayed after each status change: +After Assess and Compose, create one TaskCreate entry per chosen stage, e.g. "Brainstorm — Refine idea into feature spec" (activeForm: "Brainstorming feature idea"). Mark each `in_progress` when starting and `completed` when done. **Do not render a separate stage-level progress table** — the built-in task list already displays stage progress to the user. The implementation task table during Stage 3 is separate and should still be displayed after each status change: ``` | # | Wave | Task | Implement | Review | Status | Time | Deferred | @@ -70,7 +50,8 @@ The devline config files override these; lookup and precedence: `${CLAUDE_PLUGIN - **`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) +- **`fast_lane`** (default: `auto`; `auto|always|off`) — Which preset `/devline` starts from (see `references/stages.md`) +- **`stage_menu`** (default: `ask`; `ask|auto`) — Whether the composed stages wait for confirmation or are printed and run ## Pipeline Stages @@ -84,28 +65,28 @@ The devline config files override these; lookup and precedence: `${CLAUDE_PLUGIN ### Stage 1: Brainstorm (Interactive — main context) -Focus on the grand scheme — what we're building, architecture, and scope. +Runs when `brainstorm` is in the run. Focus on the grand scheme — what we're building, architecture, and scope. 1. Read user input. Optionally explore codebase for context (keep shallow). -2. Clarify with **AskUserQuestion** (1-4 questions, structured options, scale to ambiguity). Focus on scope, behavior, platform, aesthetics. Always ask about platform when UI is involved. +2. Grill in rounds per the brainstorm skill: each round asks the whole open decision frontier via **AskUserQuestion** (at most 4 per call), every question with a recommended answer; facts come from Explore subagents, not the user. A clear idea gets zero rounds. Always ask about platform when UI is involved. 3. Write `.devline/brainstorm.md` (see brainstorm skill for format). **Approval gate:** Present brainstorm with AskUserQuestion (Approve / Needs changes / Stop here / Other). Only proceed on explicit approval or `auto_approve_brainstorm: true`. ### Stage 1.5: Design (Interactive — foreground, conditional) -**Trigger:** `.devline/brainstorm.md` shows "UI touched: yes" AND the changes are design-level (new pages, components, visual redesign). Skip for cosmetic tweaks (spacing, single color, alignment) and non-UI features. +Runs when `design` is in the run and the UI change is design-level (new pages, components, visual redesign). Skip it for cosmetic tweaks (spacing, single color, alignment). Read the design skill (`/../design/SKILL.md`) and run it from here; it launches **designer** agents and runs the capture scripts. Facts and taste come from `.devline/brainstorm.md` and the project; `docs/design-system/MASTER.md`, if present, is binding. - **Existing mockup:** if the user points to a mockup (e.g. one made with `/devline:design mockup`, usually `.devline/mockups/*.html`) or the brainstorm names one, confirm via AskUserQuestion that it is the design input and skip exploration. - **Otherwise the exploration loop** (seeds, sketches, cull, pick, build, refine). At the pick step, show the gallery serve command and ask via AskUserQuestion (multi-select, the culled sketches as options) unless the request or `design_pick: auto` delegates the choice. At the report, ask via AskUserQuestion which final to take forward. -**On approval** of the chosen design or mockup: write `docs/design-system/MASTER.md` from it (format in the design skill's `references/design-system.md`; extend the existing one instead of replacing it). Output: MASTER.md plus the chosen HTML file. Inform user and proceed to Stage 2. +**On approval** of the chosen design or mockup: write `docs/design-system/MASTER.md` from it (format in the design skill's `design-system.md` reference; extend the existing one instead of replacing it). Output: MASTER.md plus the chosen HTML file. Inform user and proceed to Stage 2. ### Stage 2: Plan and Implement (Phase-Aware) -After Stage 1 (brainstorm approval) and Stage 1.5 (design, if applicable), detect whether the pipeline is single-phase or multi-phase before launching the planner. +Runs when `planner` is in the run. After Stage 1 and Stage 1.5 (if they ran), detect whether the pipeline is single-phase or multi-phase before launching the planner. #### Phase Detection @@ -118,15 +99,15 @@ Read the approved `.devline/brainstorm.md` and check for a `## Phases` heading ( Launch **planner** in foreground. It reads `.devline/brainstorm.md` and `docs/design-system/MASTER.md` (if exists) with the chosen design file from Stage 1.5. -**Interactive loop:** The planner may return `STATUS: NEEDS_INPUT` with design questions, code issues, and proactive improvements the planner is unsure about including. Present all sections via AskUserQuestion (recommendations marked "(Recommended)", code issues and improvements as include/skip choices). Resume with answers. Repeat until complete. +**Interactive loop:** The planner may return `STATUS: NEEDS_INPUT` with design questions, code issues, and proactive improvements the planner is unsure about including. Present all sections via AskUserQuestion (recommendations marked "(Recommended)", code issues and improvements as include/skip choices). Resume with answers, plus any requirement the user stated since brainstorm approval; the planner sees only what you pass it. Repeat until complete. Output: `.devline/plan.md` + summary in conversation. -**Approval gate:** Present plan with AskUserQuestion (Approve / Needs changes / Stop here / Other). Only proceed on explicit approval or `auto_approve_plan: true`. +**Approval gate:** Show the plan's `## Summary for approval` verbatim, plus the stages its tasks' `**Reach:**` lines and an offered preparatory refactor add, then ask with AskUserQuestion (Approve / Needs changes / Stop here / Other). Only proceed on explicit approval or `auto_approve_plan: true`. Append the accepted stages to `## Stages` in `.devline/state.md`. - If the user selects "Stop here", delete `.devline/plan.md`, `.devline/plan-phase-*.md`, `.devline/brainstorm.md`, `.devline/state.md`, `.devline/deferred-findings.md`, `.devline/fix-task-*.md`, and `.devline/design/` (if present), then end the pipeline gracefully. -After approval, proceed to Stage 3 (Implement) with `.devline/plan.md` as the plan file. Then continue to Stage 4 (Documentation) and Stage 5 (Deep Review) as normal. +After approval, proceed to Stage 3 with `.devline/plan.md` as the plan file, then the remaining recorded stages. #### Multi-Phase Path (`## Phases` detected in brainstorm) @@ -136,19 +117,21 @@ Multi-phase = the single-phase path repeated per phase, with a barrier between p **Pass 1 — plan all phases.** For each phase N (1…M): launch the **planner** (foreground) exactly as the single-phase path, additionally passing N, M, and the paths to all prior phase plan files (`.devline/plan-phase-1.md`…`plan-phase-{N-1}.md`) so it can scope to just this phase; it writes `.devline/plan-phase-N.md`. Run the same NEEDS_INPUT loop and the same per-plan approval gate (Approve / Needs changes / Stop here / Other; `auto_approve_plan` respected). After every phase plan is approved, present a summary of all phases and confirm before starting (Start implementation / Revisit a plan / Stop here). -**Pass 2 — implement phases sequentially.** For each phase N (1…M): run Stage 3 (Implement) using `.devline/plan-phase-N.md`, identical to single-phase — including Stage 3.5 (deferred-findings batch fix) at the end of the phase. **Barrier between phases:** only after phase N fully completes, update `state.md` to `Phase: {N+1}/M`, reset the task-progress table, and clear `[FIXED]` entries from `.devline/deferred-findings.md`; then start phase N+1. After the last phase, proceed to Stage 4 and Stage 5 (once, across all phases). +**Pass 2 — implement phases sequentially.** For each phase N (1…M): run Stage 3 (Implement) using `.devline/plan-phase-N.md`, identical to single-phase — including Stage 3.5 (deferred-findings batch fix) at the end of the phase. **Barrier between phases:** only after phase N fully completes, update `state.md` to `Phase: {N+1}/M`, reset the task-progress table, and clear `[FIXED]` entries from `.devline/deferred-findings.md`; then start phase N+1. After the last phase, run the remaining recorded stages once, across all phases. ### Stage 3: Implement (Autonomous — background, dependency-driven) -Follow the full implementation protocol in `references/implementation-protocol.md`. It covers wave execution, agent selection, mandatory reviews, review loops, fix cycle escalation, runtime dependency discovery, deferred findings batch fix, agent health monitoring, and orchestrator scope rules. +At the start, read the "Orchestrator only" group of `/../kb-engineering/checklists/agent-process.md`. Then follow `references/implementation-protocol.md`: waves, briefs (`## Agent Briefs`), reviews and fix cycles, merged-tree gates, deferred-findings batch fix, agent health, and your scope (`## Orchestrator Discipline`). Under `quick`, the single task runs in place as in Assess and Compose. + +**Specialist stages** (`security scan`, `resource profiling`, `optimization pass`, `best-practices review`) are reviewer runs with `focus:` set. They run after the per-task review of each task whose `**Reach:**` names a category that pulls them in, and once at branch level, before Stage 5, when chosen at assess time. Their findings go through the normal fix loop. ### Stage 4: Documentation (Autonomous — background) -Launch **docs-keeper** agent. Tell it which plan file(s) to read for context (`.devline/plan.md` or all `.devline/plan-phase-*.md` files in multi-phase mode). The docs-keeper proactively scans all documentation — README, CLAUDE.md, and everything in `docs/` — to find and fix anything stale, incomplete, or inconsistent with the code changes on this branch. It does not need a list of what to update; it finds what needs updating on its own. +Runs when `docs` is in the run. Launch **docs-keeper** agent. Tell it which plan file(s) to read for context (`.devline/plan.md` or all `.devline/plan-phase-*.md` files in multi-phase mode). The docs-keeper proactively scans all documentation — README, CLAUDE.md, and everything in `docs/` — to find and fix anything stale, incomplete, or inconsistent with the code changes on this branch. It does not need a list of what to update; it finds what needs updating on its own. -### Stage 5: Deep Review (Autonomous — background) +### Stage 5: Branch and Deep Review (Autonomous — background) -Launch the **reviewer** agent with `scope: branch` (model **opus**) for the final comprehensive review. The agent MUST return a structured verdict (APPROVED / HAS_FINDINGS). If the agent runs out of time, fails to produce a verdict, or produces partial/unstructured output: **relaunch it.** Do not read the agent's partial output to decide whether it "probably found no issues." Do not mark the deep review as done based on your own assessment. Do not skip to the final gate. Only a structured APPROVED or HAS_FINDINGS verdict from the reviewer (scope: branch) counts. +Runs when `deep review` or `branch review` is in the run. Launch the **reviewer** agent with `scope: branch`: model **opus** for `deep review`, **sonnet** for `branch review` alone. The agent MUST return a structured verdict (APPROVED / HAS_FINDINGS). If the agent runs out of time, fails to produce a verdict, or produces partial/unstructured output: **relaunch it.** Do not read the agent's partial output to decide whether it "probably found no issues." Do not mark the deep review as done based on your own assessment. Do not skip to the final gate. Only a structured APPROVED or HAS_FINDINGS verdict from the reviewer (scope: branch) counts. **The deep review cannot defer findings.** All deferred findings were already resolved in Stage 3.5. Every finding the deep review reports — minor or major — must be fixed before merge. @@ -160,10 +143,11 @@ Launch the **reviewer** agent with `scope: branch` (model **opus**) for the fina ### Complete -When deep review approves: -1. Mark the active plan file(s) status as `completed` (`.devline/plan.md` for single-phase, or all `.devline/plan-phase-*.md` files for multi-phase) -2. Report summary (what was built, files, test results) -3. Ask user via AskUserQuestion: +Runs as the `final gate`, when the last chosen review approves: +1. Run the merged-tree gate. Before any commit, every launched agent is finished or stopped and `git status --short` shows only the intended change. Reproduce any headline number from an agent's report with a command before it enters the summary or a PR body. +2. Mark the active plan file(s) status as `completed` (`.devline/plan.md` for single-phase, or all `.devline/plan-phase-*.md` files for multi-phase) +3. Report summary (what was built, files, test results) +4. Ask user via AskUserQuestion (under `quick`: commit with the `git` skill first, then ask only whether to merge, open a PR, or leave it): - "I found a mistake / want to add something" → route to debugger (runtime bugs) or planner (everything else), restart from Stage 2 - "Merge to main and exit" → commit with the `git` skill, then `git merge --squash` into the target branch (confirm it first) and write the single commit's message per the git skill's Commit message rules; the branch guard does not apply because the user confirmed the target. Then cleanup - "Commit and exit" → commit with the `git` skill, cleanup diff --git a/skills/setup/references/config.md b/skills/setup/references/config.md index 8e9c31e..ec17768 100644 --- a/skills/setup/references/config.md +++ b/skills/setup/references/config.md @@ -45,6 +45,7 @@ The first time in a session you read a legacy file, tell the user once: "Read se | `auto_approve_brainstorm` | `false` | devline | user | | `auto_approve_plan` | `false` | devline | user | | `fast_lane` | `auto` (`auto`, `always`, `off`) | devline | user | +| `stage_menu` | `ask` (`ask`, `auto`) | 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 | From 71addc5ce2d94cb58b43a088bb00b0294c8f4efd Mon Sep 17 00:00:00 2001 From: Marlon Kranz Date: Tue, 17 Nov 2026 23:39:39 +0100 Subject: [PATCH 14/17] feat(quick): run quick and implement as presets of the stage menu /devline:quick no longer bounces a new endpoint to the full pipeline: the command sets the preset and reach can only add stages. It passes the implementer a facts-only brief and commits in the main session after review. /devline:implement points at the shared protocols instead of repeating merge and commit rules. --- skills/implement/SKILL.md | 15 +++++++-------- skills/quick/SKILL.md | 21 +++++++++------------ 2 files changed, 16 insertions(+), 20 deletions(-) diff --git a/skills/implement/SKILL.md b/skills/implement/SKILL.md index 6c4e469..3952e4b 100644 --- a/skills/implement/SKILL.md +++ b/skills/implement/SKILL.md @@ -6,9 +6,9 @@ user-invocable: true disable-model-invocation: false --- -# Implement — TDD Implementation +# Implement — Implementation Preset -Launch **implementer** agents to execute tasks using test-driven development. +Run preset `implement` from [stages.md](../devline/references/stages.md): implementers from an existing plan, per-task review, docs. Reach can add stages. ## Progress Tracking @@ -26,15 +26,14 @@ The plan file may be either `.devline/plan.md` (single-phase) or `.devline/plan- 1. **Validate the plan first:** Read the plan file (`.devline/plan.md` or the specified `.devline/plan-phase-N.md`) and check the `**Branch:**` and `**Status:**` headers. If the branch doesn't match the current git branch or the status is `completed`, warn the user and ask whether to proceed — do not silently implement a stale plan. 2. Parse the tasks and their dependency graph -3. **Pre-launch checklist:** Before launching agents, verify you are in the main repo root (not inside a worktree), on the correct branch, with no uncommitted changes. See `references/worktree-protocol.md` for the full checklist. Launch implementer agents for all tasks that can run in parallel, each with `isolation: "worktree"`. **Exception:** if inside a worktree, launch **one at a time without isolation** — wait for each to complete and commit before launching the next. Never run non-isolated agents in parallel. -4. When each worktree agent completes: squash-merge with `git merge --squash `, then `git commit -m "task-N: "`. This keeps a linear history — one commit per task, no merge commits. **If conflicts:** `git merge --abort`, clean up, relaunch without isolation. **If nothing staged:** agent didn't commit in its worktree — clean up, relaunch. **After commit:** clean up (`git worktree remove --force`, then `git branch -D ` as separate commands — force delete needed after squash). -5. Wait for dependent tasks to complete before launching their dependents -6. Each implementer follows strict TDD: write tests → implement → verify +3. Run the tasks as `implementation-protocol.md` and `worktree-protocol.md` describe (links below): pre-launch checklist, parallel worktree agents or one at a time inside a worktree, briefs, merging, and merged-tree gates. +4. Wait for dependent tasks to complete before launching their dependents. + +Rules live in [implementation-protocol.md](../devline/references/implementation-protocol.md) (`## Agent Briefs`, `## Merged-Tree Gates`) and [worktree-protocol.md](../devline/references/worktree-protocol.md). Implementers don't commit in place; the main session commits. ## Without a Plan (Single Task) If the user provides a single task description: -1. Launch one implementer agent with the task -2. The implementer will write tests first, then implement +1. Launch one implementer agent with a brief per `## Agent Briefs`, passing the task text ## After Implementation For each completed task: diff --git a/skills/quick/SKILL.md b/skills/quick/SKILL.md index 1743208..30e6df4 100644 --- a/skills/quick/SKILL.md +++ b/skills/quick/SKILL.md @@ -1,22 +1,19 @@ --- name: quick -description: Fast-lane a small change — branch, implement (TDD), one review, commit. Skips brainstorm, planning, design-system, deep review, and all approval gates. Use for bugfixes, typos, tweaks, or any change that touches ~1 file / ≲30 lines with no new component, schema, endpoint, or UI surface. +description: The small-change preset — branch, implement, per-task review, commit, without brainstorm, planning or approval gates. Use for bugfixes, typos, tweaks and other small changes. Reach (what the change can affect) can still add stages. argument-hint: "" user-invocable: true disable-model-invocation: false --- -# Quick — Devline Fast Lane +# Quick — Small-Change Preset -Force the devline **fast lane** for the given task, regardless of `fast_lane` config. This is the same fast lane described in the `devline` skill — skip the classification step and run it directly. +Run preset `quick` from [stages.md](../devline/references/stages.md). The command picks the preset, so there is no lane question and the task never moves to another pipeline. -Steps (single task, run in place — no worktrees, no waves, no gates): +1. **Branch setup** — Stage 0 of the `devline` skill. +2. **Assess and Compose** — as in the `devline` skill, starting from preset `quick`. Reach can add stages (for example a security scan); it never removes any. +3. **Implement** — launch ONE **implementer** agent in place, with a brief per `## Agent Briefs` in [implementation-protocol.md](../devline/references/implementation-protocol.md). Pass the task text; add no report format and no TDD steps. The implementer does not commit. +4. **Review** — per-task review, plus any specialist reviews that reach added. Run a fix cycle on blocking findings. +5. **Commit** — once the agent has stopped, the main session commits with the `git` skill (commit mode), then asks whether to merge, open a PR (`git` pr mode), or leave it. -1. **Branch setup** — Stage 0 of the `devline` skill (branch off protected branches, create `.devline/`). -2. **Implement** — launch ONE **implementer** agent with the task. It writes tests first (TDD at the right level: unit for pure logic, integration for persistence/endpoints — see `kb-tdd-workflow`), then implements. The fast lane runs at `focused` depth — small changes don't warrant deep, so skip exhaustive per-method units for trivial code; cover behavior plus any genuinely hard logic. -3. **Review** — launch ONE **reviewer** agent (scope=task). Run a fix cycle if it returns blocking findings. -4. **Commit** with the `git` skill (commit mode), then ask only whether to merge, open a PR (`git` pr mode), or leave it (auto-proceed otherwise). - -Explicitly SKIP: brainstorm + its gate, design-system, the full plan doc + plan gate, the Feature E2E task, worktree/wave machinery, the deferred-findings batch-fix cycle, the docs-keeper full scan, `reviewer scope=branch` (deep review), and the final approval gate. - -If the task turns out to be larger than a fast-lane change (new component, schema/migration, new endpoint, UI surface, or clearly multi-file), stop and hand off to the full `/devline` pipeline instead. +Skipped: brainstorm, design, planner, worktrees and waves, branch and deep review, docs, and approval gates, unless reach added them. From 045712f9dd796aeded4ba1cfbd4e0aff903d6c64 Mon Sep 17 00:00:00 2001 From: Marlon Kranz Date: Tue, 17 Nov 2026 23:39:39 +0100 Subject: [PATCH 15/17] test(devline): check the pipeline's cross-file links Stage names in presets, reviewer focus values, the handoff command against the compaction summary, plan format, state schema and reference paths. Runs in CI. --- .github/workflows/validate.yml | 2 + skills/devline/tests/test_structure.py | 142 +++++++++++++++++++++++++ 2 files changed, 144 insertions(+) create mode 100644 skills/devline/tests/test_structure.py diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml index cc23811..4a9c6f8 100644 --- a/.github/workflows/validate.yml +++ b/.github/workflows/validate.yml @@ -47,3 +47,5 @@ jobs: 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 + - name: Test devline pipeline (structure) + run: python3 -m unittest discover -s skills/devline/tests -v diff --git a/skills/devline/tests/test_structure.py b/skills/devline/tests/test_structure.py new file mode 100644 index 0000000..ca5a007 --- /dev/null +++ b/skills/devline/tests/test_structure.py @@ -0,0 +1,142 @@ +"""Cross-file links of the devline pipeline: stage names, presets, focus values, handoff parts.""" +import re +import unittest +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[3] +DEVLINE = ROOT / "skills/devline" +STAGES = DEVLINE / "references/stages.md" +PRESETS = {"quick", "implement", "full"} + + +def read(rel): + return (ROOT / rel).read_text(encoding="utf-8") + + +def section(text, heading): + """Body of the H2 `heading` up to the next H2.""" + m = re.search(rf"(?m)^## {re.escape(heading)}.*$", text) + assert m, f"no '## {heading}' section" + rest = text[m.end():] + end = re.search(r"(?m)^## ", rest) + return rest[: end.start()] if end else rest + + +def stage_table(): + """{stage: pulled-in-by} from the Stages table.""" + rows = re.findall(r"(?m)^\| `([^`]+)` \|(.*)\|\s*$", section(read(STAGES), "Stages")) + return {name: cells.split("|")[-1].strip() for name, cells in rows} + + +def presets(): + """{preset: [stage, ...]} from lines like '- **quick**: `a`, `b`'.""" + lines = re.findall(r"(?m)^- \*\*(\w+)\*\*:(.*)$", section(read(STAGES), "Presets")) + return {name: re.findall(r"`([^`]+)`", rest) for name, rest in lines} + + +def focus_values(text): + return set(re.findall(r"focus: ?([a-z-]+)", text)) + + +def frontmatter(rel): + m = re.match(r"---\n(.*?)\n---\n", read(rel), re.S) + assert m, f"{rel}: no frontmatter" + return {k.strip(): v.strip() for k, v in (l.split(":", 1) for l in m.group(1).splitlines() if ":" in l)} + + +class Stages(unittest.TestCase): + def test_every_stage_has_a_trigger(self): + table = stage_table() + self.assertGreaterEqual(len(table), 10) + for name, trigger in table.items(): + with self.subTest(stage=name): + self.assertTrue(trigger, f"{name} has no 'Pulled in by'") + + def test_presets_name_only_table_stages(self): + table, found = stage_table(), presets() + self.assertLessEqual(PRESETS, set(found)) + for name, stages in found.items(): + with self.subTest(preset=name): + self.assertTrue(stages) + self.assertLessEqual(set(stages), set(table)) + + def test_commands_name_an_existing_preset(self): + for skill, preset in (("quick", "quick"), ("implement", "implement")): + with self.subTest(skill=skill): + text = read(f"skills/{skill}/SKILL.md") + self.assertIn("stages.md", text) + self.assertRegex(text, rf"preset `?{preset}`?|`{preset}` preset") + self.assertNotIn("hand off to the full", read("skills/quick/SKILL.md")) + + def test_reviewer_focus_matches_stage_menu(self): + reviewer = re.findall(r"(?m)^- `([a-z-]+)`:", section(read("agents/reviewer.md"), "Focus")) + self.assertEqual(set(reviewer), focus_values(read("skills/devline/references/stages.md"))) + self.assertEqual(len(reviewer), 4) + + +class Handoff(unittest.TestCase): + def test_frontmatter_is_explicit_only(self): + fm = frontmatter("skills/handoff/SKILL.md") + self.assertEqual(fm.get("name"), "handoff") + self.assertEqual(fm.get("disable-model-invocation"), "true") + + def test_carries_every_precompact_part(self): + # a title is the first words of each numbered line, before its colon + lines = re.findall(r"(?m)^\d\. ([^:\n]+)", read("hooks/scripts/pre-compact.sh")) + titles = [" ".join(line.rstrip(".").split()[:5]) for line in lines] + self.assertEqual(len(titles), 7) + skill = read("skills/handoff/SKILL.md") + for title in titles: + with self.subTest(title=title): + self.assertIn(title, skill) + + +class Agents(unittest.TestCase): + def test_plan_opens_with_summary_for_approval(self): + text = read("agents/references/plan-format.md") + self.assertEqual(re.findall(r"(?m)^## .*$", text)[0], "## Summary for approval") + self.assertIn("**Reach:**", text) + self.assertIn("Summary for approval", read("agents/planner.md").split("### 7.")[1].split("\n### ")[0]) + + def test_implementer_reports_red_run_and_integration_notes(self): + text = read("agents/implementer.md") + for needle in ("- Red:", "### Integration notes", "Committed:"): + with self.subTest(needle=needle): + self.assertIn(needle, text) + + def test_brainstorm_credits_its_source(self): + self.assertIn("MIT", section(read("skills/brainstorm/SKILL.md"), "Credits")) + + +class Orchestrator(unittest.TestCase): + def test_referenced_files_exist(self): + text = read("skills/devline/SKILL.md") + refs = set(re.findall(r"(\$\{CLAUDE_PLUGIN_ROOT\}/[\w/-]+/)?references/([\w-]+\.md)", text)) + self.assertIn(("", "stages.md"), refs) + for prefix, name in refs: + with self.subTest(ref=prefix + name): + if prefix: + self.assertTrue((ROOT / prefix.split("}/", 1)[1] / "references" / name).is_file()) + else: + # bare paths are devline's own, or another skill's when the text names that skill + self.assertTrue(any(ROOT.glob(f"skills/*/references/{name}"))) + + def test_defaults_list_stage_menu(self): + self.assertIn("`stage_menu`", section(read("skills/devline/SKILL.md"), "Defaults")) + self.assertNotRegex(read("skills/devline/SKILL.md"), r"(?m)^#+ Fast Lane") + + def test_protocol_sections(self): + text = read("skills/devline/references/implementation-protocol.md") + for heading in ("Agent Briefs", "Merged-Tree Gates", "Orchestrator Discipline"): + with self.subTest(heading=heading): + self.assertRegex(text, rf"(?m)^## {heading}\s*$") + self.assertNotIn('Run tests to "verify" a merge', text) + + def test_state_schema_has_stages(self): + text = read("skills/devline/references/recovery.md") + self.assertIn("## Stages", text) + self.assertRegex(text, r"(?m)^\| # \| Status \|.*\bAgent\b.*\bWorktree\b") + + +if __name__ == "__main__": + unittest.main() From be41bb96aaf85cfdd0670e870dc1e5988fb54319 Mon Sep 17 00:00:00 2001 From: Marlon Kranz Date: Tue, 17 Nov 2026 23:39:39 +0100 Subject: [PATCH 16/17] docs(readme): stage menu, grilling, handoff and merged-tree gates --- README.md | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index b5cdd1d..4136e03 100644 --- a/README.md +++ b/README.md @@ -101,8 +101,9 @@ Optional, but they make devline leaner and more capable — `/devline:setup` off | `/devline ` | Full pipeline -- brainstorm through deep review | | `/devline:brainstorm ` | Refine an idea into a feature spec | | `/devline:plan ` | Create a TDD implementation plan | -| `/devline:implement` | Implement tasks from an existing plan | -| `/devline:quick ` | Fast lane -- implement, review, and commit a small change | +| `/devline:implement` | Implementation preset -- run the tasks of an existing plan | +| `/devline:quick ` | Small-change preset -- implement, review, and commit, plus any stages the change's reach adds | +| `/devline:handoff [focus]` | Write `.devline/handoff.md` and print the line that starts a fresh session from it | | `/devline:git [commit\|push\|pr]` | Commit with a Conventional Commit message, push, or write a PR body to an editable file and open the PR | | `/devline:review` | Code review of recent changes | | `/devline:debug ` | Systematic root cause analysis | @@ -120,13 +121,13 @@ Optional, but they make devline leaner and more capable — `/devline:setup` off ## How the Pipeline Works -Stage 0 through Stage 5, plus a final gate. You approve twice — after brainstorm and after plan — then make the final merge-or-iterate call; the rest runs autonomously. Small changes take the fast lane straight to implement → review → commit. +Stage 0 through Stage 5, plus a final gate. You approve twice — after brainstorm and after plan — then make the final merge-or-iterate call; the rest runs autonomously. Before Stage 1 it assesses the change's reach (security surface, resource use, public contract, persisted data, UI, concurrency, build/release) and composes the run from a stage menu: a preset (`quick`, `implement` or `full`) plus the stages reach pulls in, such as a security scan or deep review. It shows the stages with a reason each and, with `stage_menu: ask` (the default), lets you add or remove some. A small change runs the quick preset: implement → review → commit. ```mermaid %%{init: {'theme': 'neutral'}}%% flowchart LR - start(["/devline"]) --> triage{"Classify\nchange"} - triage -->|small| fast["Fast lane\nimplement · review · commit"] + start(["/devline"]) --> triage{"Assess reach\ncompose stages"} + triage -->|quick preset| fast["Quick\nimplement · review · commit"] fast --> done(["Done"]) triage -->|feature| s0["Stage 0\nBranch setup"] @@ -168,11 +169,11 @@ If a previous pipeline left artifacts behind, it detects them and asks whether t
Stage 1: Brainstorm (interactive) -Focuses on what you're building and where it fits -- not implementation details. Asks 1-4 structured questions with selectable options (scope, behavior, platform, aesthetics), then writes `.devline/brainstorm.md` capturing scope, architecture impact, UI impact, and key decisions. +Focuses on what you're building and where it fits -- not implementation details. Grills you in rounds: each round asks every open decision whose prerequisites are settled, each with a recommended answer, and looks facts up in the code instead of asking. A clear idea gets zero rounds. Then it writes `.devline/brainstorm.md` capturing scope, architecture impact, UI impact, and key decisions. For larger features, the brainstorm detects natural phase boundaries and splits the work into sequential phases. Each phase gets its own plan later. -You approve the spec before anything else happens. +You approve the spec before anything else happens. The grilling rounds are adapted from Matt Pocock's [`grilling` skill](https://github.com/mattpocock/skills) (MIT).
@@ -237,6 +238,8 @@ flowchart LR **Deferred findings** (minor code quality issues) are collected across all tasks and batch-fixed by a single implementer after the last wave completes. +**Merged-tree gates.** Agents commit only on their own worktree branch; run in place, they leave changes for the main session to commit. After each wave and before the final commit, the main session runs typecheck, build and the full suite once on the merged tree; a red run goes to a debugger. +
@@ -506,7 +509,7 @@ Captures (stills, scroll or scripted recordings, frame-change report, page error ## Commits, Pushes and Pull Requests -`/devline:git` handles the final commit, push and PR at the end of a pipeline or fast lane, or whenever you ask. Each mode includes the one before it, and the default is `commit`. +`/devline:git` handles the final commit, push and PR at the end of a pipeline or quick run, or whenever you ask. Each mode includes the one before it, and the default is `commit`. - **`commit`** -- stages the files that belong to the change and writes a Conventional Commit. - **`push`** -- commits anything pending, then pushes the current branch. @@ -557,7 +560,7 @@ Every setting is optional; the defaults work out of the box. Two files can overr - **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. -Each key comes from the first place that sets it: your request, then the repo file, then the user file, then the plugin default. +Each key comes from the first place that sets it: your request, then the repo file, then the user file, then the plugin default. For example, `stage_menu: auto` runs the composed stages without asking, and `fast_lane` (`auto`, `always`, `off`) picks the preset `/devline` starts from. ```yaml --- From 928d25d7f16fac9aaa626c7489f897e4e63e74d2 Mon Sep 17 00:00:00 2001 From: Marlon Kranz Date: Tue, 17 Nov 2026 23:47:35 +0100 Subject: [PATCH 17/17] fix(devline): print the stage table, ask in text without AskUserQuestion In a non-interactive dry run the orchestrator recorded the composed stages only in state.md and, with stage_menu ask and no AskUserQuestion tool, started the run without asking. It now prints the table before any agent starts and, when the tool is missing, asks in plain text and ends its turn. The quick brief also forbids Report and Verify lines, which one run still added. --- skills/devline/references/stages.md | 4 ++-- skills/quick/SKILL.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/skills/devline/references/stages.md b/skills/devline/references/stages.md index 51d3db9..ab4c9b2 100644 --- a/skills/devline/references/stages.md +++ b/skills/devline/references/stages.md @@ -42,7 +42,7 @@ Examples: a one-line change to auth input validation is security surface, so it ## Showing the run -Show a short table, one line per chosen stage: +Print a short table as text, one line per chosen stage, before launching any agent. Writing it only to state.md doesn't count: | Stage | Reason | |---|---| @@ -51,7 +51,7 @@ Show a short table, one line per chosen stage: Then, by the devline config's `stage_menu` (lookup in `${CLAUDE_PLUGIN_ROOT}/skills/setup/references/config.md`): -- `ask` (default): AskUserQuestion with "Run as shown", "Change stages", "Stop". On "Change stages" the user names adds and removes in free text; apply them and show the table again. +- `ask` (default): AskUserQuestion with "Run as shown", "Change stages", "Stop". On "Change stages" the user names adds and removes in free text; apply them and show the table again. If AskUserQuestion isn't available (a non-interactive run), ask the same question in plain text and end your turn; don't start the run. - `auto`: print the table and proceed. An explicit preset with no reach additions prints the table and proceeds, whatever `stage_menu` says. diff --git a/skills/quick/SKILL.md b/skills/quick/SKILL.md index 30e6df4..bdeb185 100644 --- a/skills/quick/SKILL.md +++ b/skills/quick/SKILL.md @@ -12,7 +12,7 @@ Run preset `quick` from [stages.md](../devline/references/stages.md). The comman 1. **Branch setup** — Stage 0 of the `devline` skill. 2. **Assess and Compose** — as in the `devline` skill, starting from preset `quick`. Reach can add stages (for example a security scan); it never removes any. -3. **Implement** — launch ONE **implementer** agent in place, with a brief per `## Agent Briefs` in [implementation-protocol.md](../devline/references/implementation-protocol.md). Pass the task text; add no report format and no TDD steps. The implementer does not commit. +3. **Implement** — launch ONE **implementer** agent in place, with a brief per `## Agent Briefs` in [implementation-protocol.md](../devline/references/implementation-protocol.md). Pass the task text as the user wrote it plus the brief's facts; no "Report:" or "Verify:" lines, no TDD steps and no design choices of your own. The implementer does not commit. 4. **Review** — per-task review, plus any specialist reviews that reach added. Run a fix cycle on blocking findings. 5. **Commit** — once the agent has stopped, the main session commits with the `git` skill (commit mode), then asks whether to merge, open a PR (`git` pr mode), or leave it.