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/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 --- 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) ``` 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:** 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) 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 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/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/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 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/stages.md b/skills/devline/references/stages.md new file mode 100644 index 0000000..ab4c9b2 --- /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 + +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 | +|---|---| +| `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. 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. + +## 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/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`. 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() 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.` 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/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. diff --git a/skills/quick/SKILL.md b/skills/quick/SKILL.md index 1743208..bdeb185 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 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. -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. 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 |