Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
55187ba
feat(config): layered config with repo and user files
Conava Nov 17, 2026
2bf0a1a
feat(setup): write repo and user config from templates
Conava Nov 17, 2026
8751aa7
docs(readme): replace the settings reference with a short config section
Conava Nov 17, 2026
459204b
test(setup): check the config key table against its owners
Conava Nov 17, 2026
6253529
feat(planner): refactor first, summary for approval, task reach
Conava Nov 17, 2026
4b4a946
feat(implementer): commit only in a worktree, show the red run
Conava Nov 17, 2026
5303ed0
feat(reviewer): structure fit, focus reviews and red-run check
Conava Nov 17, 2026
f892c81
feat(brainstorm): grill in rounds over the decision frontier
Conava Nov 17, 2026
df1edf2
feat(handoff): add /devline:handoff
Conava Nov 17, 2026
4779484
feat(devline): protocols for base checks, evidence and partial work
Conava Nov 17, 2026
a319815
feat(devline): stage menu composed by reach
Conava Nov 17, 2026
4888915
feat(devline): agent briefs and merged-tree gates
Conava Nov 17, 2026
df855fe
feat(devline): assess and compose the run before Stage 1
Conava Nov 17, 2026
71addc5
feat(quick): run quick and implement as presets of the stage menu
Conava Nov 17, 2026
045712f
test(devline): check the pipeline's cross-file links
Conava Nov 17, 2026
be41bb9
docs(readme): stage menu, grilling, handoff and merged-tree gates
Conava Nov 17, 2026
928d25d
fix(devline): print the stage table, ask in text without AskUserQuestion
Conava Nov 17, 2026
e6d05aa
Merge origin/main into feat/orchestration
Conava Nov 17, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .github/workflows/validate.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
21 changes: 12 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -101,8 +101,9 @@ Optional, but they make devline leaner and more capable — `/devline:setup` off
| `/devline <idea>` | Full pipeline -- brainstorm through deep review |
| `/devline:brainstorm <idea>` | Refine an idea into a feature spec |
| `/devline:plan <spec>` | Create a TDD implementation plan |
| `/devline:implement` | Implement tasks from an existing plan |
| `/devline:quick <task>` | Fast lane -- implement, review, and commit a small change |
| `/devline:implement` | Implementation preset -- run the tasks of an existing plan |
| `/devline:quick <task>` | 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 <error>` | Systematic root cause analysis |
Expand All @@ -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"]
Expand Down Expand Up @@ -168,11 +169,11 @@ If a previous pipeline left artifacts behind, it detects them and asks whether t
<details>
<summary><strong>Stage 1: Brainstorm</strong> (interactive)</summary>

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).

</details>

Expand Down Expand Up @@ -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.

</details>

<details>
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
---
Expand Down
18 changes: 15 additions & 3 deletions agents/implementer.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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 <specific files you created/modified> && git commit -m "task-N: <short description>"
```
Expand Down Expand Up @@ -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 <base> HEAD` fails, run `git rebase <base>` (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 <main>/<file> <file>`). Never `cat` or copy its contents into output.
- **Scratch:** use the brief's scratch dir for scripts and PID files (`$!` to `<scratch>/<name>.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
Expand All @@ -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
Expand All @@ -170,13 +177,18 @@ Minimize build invocations — each cold start adds 10-15s overhead.

### Test Results
- X tests passed, Y failed, Z skipped
- Red: <command> failed with <assertion line> before the change (one line per behavior, or "not applicable: <reason>")

### 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)
```
22 changes: 13 additions & 9 deletions agents/planner.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand Down
6 changes: 6 additions & 0 deletions agents/references/plan-format.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.]

Expand Down Expand Up @@ -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:**
Expand Down Expand Up @@ -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:**
Expand Down
Loading
Loading