Skip to content

feat(devline): stage menu by reach, presets, grilling and handoff - #10

Merged
Conava merged 18 commits into
mainfrom
feat/orchestration
Nov 17, 2026
Merged

Conava merged 18 commits into
mainfrom
feat/orchestration

Conversation

@Conava

@Conava Conava commented Nov 17, 2026

Copy link
Copy Markdown
Owner

Builds on #9 (layered config). Merge that first; this diff then shrinks to the orchestration commits.

Summary

  • Stage menu:
    • Before Stage 1, devline assesses the request's reach with a new Reach section in kb-blast-radius (security, resources, public contract, persisted data, UI, concurrency, build/release).
    • It composes the run from a stage menu and prints the stages with one reason each.
    • New key stage_menu: ask|auto (default ask). Without AskUserQuestion it asks in plain text and ends the turn.
  • Presets: /devline:quick and /devline:implement are presets of the menu. An explicit preset wins over size, and reach can only add stages.
  • Specialist reviews: the reviewer gets a focus: option (security, resources, optimization, best-practices) for the specialist stages. It also checks that changes fit the existing structure and that the red run is visible.
  • Implementer:
    • commits only on its own worktree branch, never in place;
    • reports the failing test (- Red:) before the fix.
  • Orchestrator:
    • runs typecheck, build and the full suite on the merged tree after each wave and before the final commit;
    • briefs agents with facts only, never a report format;
    • saves a killed agent's partial work as a patch for the next agent to evaluate.
  • Planner:
    • plans open with a "Summary for approval";
    • a preparatory refactor is offered as its own earlier task;
    • tasks carry a Reach line.
  • Brainstorm: grills in rounds over the open decisions, each question with a recommended answer. Adapted from Matt Pocock's grilling skill (MIT), credited.
  • New /devline:handoff: writes .devline/handoff.md with the same parts as the PreCompact summary and prints the line that starts the next session.
  • Protocols: disk and base checks, evidence copied out of worktrees, a shared low-priority build lock.

Tests

  • New skills/devline/tests/test_structure.py (13 tests), added to CI. It checks that:
    • preset names match the stage table;
    • reviewer focus values match;
    • handoff matches PreCompact;
    • reference paths exist;
    • the plan format starts with the summary.
  • All suites pass.
  • A headless dry run on a sample service: quick with reach, stage menu ask and auto, and handoff. The three issues it found are fixed and re-tested.

Try it

cd <small repo> && claude --plugin-dir <this branch>
  • /devline:quick <one-line change to input validation>:
    • a Stage | Reason table appears, with security scan added for reach;
    • the implementer report has a - Red: line;
    • only the main session commits.
  • /devline:handoff: writes .devline/handoff.md and prints the start line.

Settings lived in one per-repo devline.local.md (plus a user copy that
only the design skill read), so personal preferences had to be repeated
in every repo and project rules sat next to them in an ignored file.

Each key now resolves from the first layer that sets it: the request,
the committed repo file .claude/devline.md, the user file
${CLAUDE_CONFIG_DIR:-~/.claude}/devline/config.md, then the owner
skill's Defaults section. Both files use flat YAML frontmatter plus
optional prose for rules no key can say, such as squash merges.

One shared reference holds the lookup rules, the legacy fallback and
the key table; skills and agents point to it instead of naming a file.
A missing new file falls back to the old devline.local.md, with a
one-time hint to move it.

Keys that nothing read are dropped from the documented set:
frontend_framework, the cve_ branch, commit and push keys, and the
migrate_ keys.
Setup wrote only the per-repo devline.local.md, walking four fixed
batches. It now asks which config file to write, lists the keys that
usually belong in that layer with their defaults, asks for prose rules,
and writes only what differs from the defaults.

When a legacy devline.local.md exists without its replacement, setup
offers to move it and flags personal settings before they land in the
committed repo file. The output-token check moves into the
prerequisites step.
The full key tables duplicated the skills and drifted from them. The
README now explains the two files and the precedence, shows one
example, and links the shared key table.
Fails when a key in the shared table is missing from its owner's
Defaults section, when an owner stops pointing to the shared reference,
or when any file other than the migration note names the legacy config
file. Runs in the validate workflow.
The planner offers a preparatory refactor as its own earlier task and
bakes small local cleanups in silently. Plans open with a Summary for
approval that the planner returns verbatim, every task names its Reach,
and owner requirements must appear in plan text.
In place, the implementer leaves changes uncommitted for the main
session. It checks its worktree base, links env files, keeps scratch and
evidence where they survive, steps back before appending special cases,
and reports the first failing run and integration notes.
A focus parameter (security, resources, optimization, best-practices)
runs the specialist stages without new agents. Builds go through the
launcher's shared lock, in-place changes are reviewed against the base,
and missing red-run evidence blocks bug fixes.
Each round asks every open decision whose prerequisites are settled,
with a recommended answer, and sends facts to Explore subagents. A clear
idea runs zero rounds. Adapted from Matt Pocock's grilling skill (MIT).
Writes .devline/handoff.md with the seven parts of the compaction
summary plus a read-next list, and prints the first message for a fresh
session. Runs only when typed.
Worktree launches record the base SHA and check disk space, evidence is
copied out before removal, running agents are stopped first, and a
killed agent's work is saved as a patch for its successor to evaluate.
In-place agents never commit. The state file gains a Stages table and
Agent and Worktree columns.
A new stages reference lists every stage with what pulls it in, the
quick, implement and full presets, and how a run is shown and recorded.
kb-blast-radius gains a Reach section: seven categories with request
and code signals, run on seed files before code exists. Reach only
adds stages to a preset.
Briefs carry facts only (base SHA, owned files, env files, scratch dir,
build lock, integration notes, partial patch, focus) and never a report
format. The main session runs typecheck, build and the full suite once
per wave and before the final commit. In-place agents never commit; the
main session commits once every agent has stopped.
The orchestrator reads the reach categories and the stage menu, shows
the composed stages (asking first when stage_menu is ask) and runs only
those. The fast lane becomes the quick preset. Plan approval shows the
plan's Summary for approval and any stages its tasks add, and the final
gate runs the merged-tree gate with every agent stopped. Adds the
stage_menu key to the config reference.
/devline:quick no longer bounces a new endpoint to the full pipeline:
the command sets the preset and reach can only add stages. It passes
the implementer a facts-only brief and commits in the main session
after review. /devline:implement points at the shared protocols
instead of repeating merge and commit rules.
Stage names in presets, reviewer focus values, the handoff command
against the compaction summary, plan format, state schema and
reference paths. Runs in CI.
In a non-interactive dry run the orchestrator recorded the composed
stages only in state.md and, with stage_menu ask and no AskUserQuestion
tool, started the run without asking. It now prints the table before
any agent starts and, when the tool is missing, asks in plain text and
ends its turn. The quick brief also forbids Report and Verify lines,
which one run still added.
@Conava
Conava merged commit 7bc843d into main Nov 17, 2026
1 check passed
@Conava
Conava deleted the feat/orchestration branch November 17, 2026 23:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant