Skip to content

Commit 19df94f

Browse files
committed
feat(teams): a project manager per team, and a page to manage them
Routing a correction ticket by language is the right first answer and the wrong second one. When the same defect comes back, language routing hands it to the agent that just failed at it, carrying a ticket whose only new content is that it failed again — the loop that made gate failures feel like noise. A repeat ticket now goes past a project manager before it goes back to work. This already happened on the reviewer path when the ladder was spent; it now happens on the tester path too, which is where most gate failures come from. The manager does the two things the router cannot: pick somebody else, and say what to do differently — and its direction lands above the evidence, since it is the only thing in the ticket the last attempt did not already have. A first ticket is never sent to it: the obvious choice has not been tried yet and a model call to confirm it is pure latency. The verdict is validated before it is applied — naming an unregistered agent, or re-picking the agent that just failed, both fall through to the deterministic route. Each team can carry its own manager. A run-wide manager answering for a specific team picks from a roster it has no reason to understand: the agents who can fix a failing Go handler are not the ones staffing the React half. The request now names the team and its staff, and lists the team's own people first — first, not exclusively, because the reason a delivery was rejected may be that the team lacks the skill the fix needs. Only agents that answer the triage contract may be nominated. An agent's decoding grammar comes from its own system prompt, so one that answers a different contract replies with something the reassignment step cannot read, after a full model call has been spent. Also here: - A Teams page. The rail's Teams tab answers "how are the teams doing right now"; this answers "are the teams right at all" — a different question, and a team structure outlives the run that proposed it. It sends only the fields you touched, and on an ownership collision names which teams collide rather than refusing bare. Nothing is saved in that case. - A correction attempt now counts tickets for that defect rather than every correction on the board, which made a first attempt at a third defect announce itself as a third. - Reading a ticket's dedupe key back is trim-safe. The marker carries a leading newline so it cannot match mid-line, but a stamp landing at the start of an empty notes field loses it to any caller that trims — after which dedupe stops seeing the ticket and the board grows a duplicate. - Triage declines instead of panicking when no executor is wired. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UiLDxnEu1Gf8Q5hWAFhaAd
1 parent 077a969 commit 19df94f

39 files changed

Lines changed: 2854 additions & 23 deletions

‎docs/changelog.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -140,6 +140,65 @@ an agent that cannot be dispatched — a task nobody can staff would sit in
140140
guessing at work two others could not do is a scoping problem, which is exactly
141141
what the human is being asked to look at.
142142

143+
### Added — a project manager decides who takes a rejected delivery
144+
145+
Routing a correction ticket by language is the right *first* answer and the
146+
wrong *second* one: when the same defect comes back, language routing hands it
147+
to the agent that just failed at it, carrying a ticket whose only new content is
148+
that it failed again.
149+
150+
- **A repeat ticket goes past a project manager** before it goes back to work —
151+
on the reviewer path when the ladder is spent, and now on the tester path too,
152+
which is where most gate failures come from. The manager does the two things
153+
the router cannot: pick somebody else, and say what to do differently. Its
154+
direction lands *above* the evidence in the ticket, since it is the only thing
155+
there the last attempt did not already have.
156+
- **A first ticket is never sent to it.** The obvious choice has not been tried
157+
yet, and a model call to confirm it is pure latency.
158+
- **The verdict is validated before it is applied.** Naming an unregistered
159+
agent (the ticket then sits unassigned) and re-picking the agent that just
160+
failed (the loop this exists to end) both fall through to the deterministic
161+
route rather than being applied.
162+
- **Each team can carry its own manager.** A run-wide manager answering for a
163+
specific team picks from a roster it has no reason to understand — the agents
164+
who can fix a failing Go handler are not the ones staffing the React half. The
165+
request now names the team and its staff, and lists the team's own people
166+
first. First, not exclusively: the reason a delivery was rejected may be that
167+
the team lacks the skill the fix needs.
168+
- **Only agents that answer the triage contract may be nominated.** An agent's
169+
decoding grammar comes from its own system prompt, so one that answers a
170+
different contract replies with something the reassignment step cannot read —
171+
after a full model call has been spent. Both the approval card and the Teams
172+
page offer only the eligible list.
173+
174+
### Added — a Teams page
175+
176+
The rail's Teams tab answers "how are the teams doing right now". The new
177+
**Teams** page answers "are the teams right at all" — a different question, at a
178+
different time, with a consequence the rail does not have: a team structure
179+
outlives the run that proposed it, so the boundaries and staffing edited here
180+
are what the next run inherits.
181+
182+
It edits names, owned globs, acceptance commands and each team's project
183+
manager, sends only the fields you touched, and — when an edit would make two
184+
teams share a path — shows *which* teams collide instead of a bare refusal.
185+
Nothing is saved in that case: a half-applied org chart is worse than the one it
186+
replaced, because you believe you fixed it.
187+
188+
### Fixed — a correction attempt counted the board, not the defect
189+
190+
A ticket's "correction attempt N" came from a count of every correction on the
191+
board, so two unrelated failures made a first attempt at a third defect announce
192+
itself as a third — telling its worker that approaches it had never tried were
193+
already ruled out. It now counts tickets for *that* defect, finished ones
194+
included.
195+
196+
Reading a ticket's dedupe key back is also trim-safe now. The marker carries a
197+
leading newline so it cannot match mid-line, but a stamp that lands at the start
198+
of an empty notes field loses that newline to any caller that trims — after
199+
which dedupe stops seeing the ticket and the board grows a second one for the
200+
same failure.
201+
143202
### Fixed — greenfield scaffolding could not scope its own tasks
144203

145204
Found by running the squad path end to end against a fake model, and it is the

‎docs/squads.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -182,6 +182,61 @@ A failing tester or reviewer does not produce a red notification and a generic
182182
look like it was losing ground.
183183

184184
A repeat correction says which attempt it is and not to repeat the last one.
185+
The attempt count is per **defect**, not per board: two unrelated failures used
186+
to make a first attempt at a third defect announce itself as a third, telling
187+
its worker that approaches it never tried had already been ruled out.
188+
189+
### The project manager decides who takes it next
190+
191+
Routing a ticket by language is the right *first* answer and the wrong *second*
192+
one. When the same defect comes back, language routing hands it to the agent
193+
that just failed at it, carrying a ticket whose only new content is that it
194+
failed again — which is the loop that made gate failures feel like noise rather
195+
than progress.
196+
197+
So a **repeat** ticket goes past a project manager before it goes back to work.
198+
The manager does the two things the router cannot: pick somebody else, and say
199+
what to do differently. Its direction is written *above* the evidence in the
200+
ticket, because it is the only thing there the last attempt did not already
201+
have.
202+
203+
Its verdict is validated before it is applied. Two answers are worse than no
204+
manager at all — naming an agent that cannot be dispatched (the ticket then sits
205+
unassigned) and re-picking the agent that just failed (the loop triage exists to
206+
end) — and either one falls through to the deterministic route rather than being
207+
applied.
208+
209+
The same manager decides when the review ladder runs out of retries, one handoff
210+
before a human is asked.
211+
212+
### Each team can have its own manager
213+
214+
A run-wide manager answering for a specific team picks from a roster it has no
215+
reason to understand: the agents who can fix a failing Go handler are not the
216+
ones staffing the React half. So a squad may carry its own `manager`, and the
217+
triage request tells it which team it answers for and who staffs it.
218+
219+
The team's own people are listed **first** in the roster, not exclusively — the
220+
whole reason a delivery was rejected may be that the team lacks the skill the
221+
fix needs, and a manager forbidden from looking outside could only choose
222+
between agents that have already failed.
223+
224+
Only an agent that answers the triage contract may be nominated. An agent's
225+
decoding grammar is derived from its own system prompt, so one that answers a
226+
different contract replies with something the reassignment step cannot read —
227+
after a full model call has already been spent. Nominate a built-in `triage`, or
228+
write your own agent with a `-triage` suffix in its id:
229+
230+
```yaml
231+
# .slmcode/agents/backend-triage.yaml
232+
id: backend-triage
233+
title: Backend project manager
234+
system_prompt: |
235+
You decide who takes a rejected delivery next...
236+
```
237+
238+
Attach one on the plan-approval card or on the **Teams** page; leaving it empty
239+
hands the team back to the run's default manager.
185240
186241
---
187242

‎pkg/agents/factory.go‎

Lines changed: 72 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ package agents
22

33
import (
44
"fmt"
5+
"sort"
56
"strings"
67
"sync"
78

@@ -112,7 +113,7 @@ func genericRole(id string) string {
112113
id, _ = BaseRoleID(id)
113114
for _, suffix := range []string{
114115
"worker", "tester", "reviewer", "corrector", "explorer",
115-
"planner", "splitter", "architect", "editor", "describer", "manager",
116+
"planner", "splitter", "architect", "editor", "describer", "manager", "triage",
116117
} {
117118
if id == suffix || strings.HasSuffix(id, "-"+suffix) {
118119
return suffix
@@ -154,6 +155,7 @@ func specs(coding []string) []RoleSpec {
154155
{ID: plan.RolePlaceholder, Title: "Fill placeholders / flag gaps", Description: "Detects stub code, fills real implementations, or flags precise gaps for HITL.", SystemPrompt: PromptPlaceholder, Tools: coding, MaxIter: 14, Temperature: 0.1, MaxTokens: 3072},
155156
{ID: plan.RoleEscalate, Title: "Escalate arbitrator", Description: "Decides retry/re-scope/abort/mark_done when human escalate HITL times out.", SystemPrompt: PromptEscalate, Tools: nil, MaxIter: 1, Temperature: 0.1, MaxTokens: 384},
156157
{ID: "memory", Title: "Distill MEMORY.md", Description: "Distills durable project lessons into MEMORY.md.", SystemPrompt: PromptMemory, Tools: nil, MaxIter: 2, Temperature: 0.3, MaxTokens: 768},
158+
{ID: RoleTriage, Title: "Project manager (ticket triage)", Description: "Decides who takes a rejected delivery next, and what they need to know that the last attempt did not.", SystemPrompt: PromptTriage, Tools: nil, MaxIter: 2, Temperature: 0.15, MaxTokens: 640, SchemaRole: schema.RoleTriage},
157159
{ID: "manager", Title: "Engineering manager (squad assembly)", Description: "Splits a query into parallel squads with disjoint ownership and a frozen interface contract.", SystemPrompt: PromptManager, Tools: nil, MaxIter: 3, Temperature: 0.15, MaxTokens: 2048, SchemaRole: schema.RoleSquads},
158160
{ID: "composer", Title: "Dynamic pipeline composer", Description: "Assembles the right team, tools, and skills into a task-specific pipeline.", SystemPrompt: PromptComposer, Tools: nil, MaxIter: 3, Temperature: 0.2, MaxTokens: 2048, SchemaRole: schema.RoleComposition},
159161

@@ -181,6 +183,9 @@ const (
181183
RoleDescriber = "describer"
182184
// RoleEditor is the formatting half of the architect/editor pair.
183185
RoleEditor = "editor"
186+
// RoleTriage is the run's default project manager: it decides who takes a
187+
// rejected delivery next. A squad may nominate its own instead.
188+
RoleTriage = "triage"
184189
)
185190

186191
// PublicSpecs strips prompts for API/UI (built-ins only — callers merge customs).
@@ -494,6 +499,7 @@ var lightAgents = map[string]bool{
494499
"orchestrator": true, "memory": true, "docs": true, "escalate": true,
495500
"composer": true,
496501
"manager": true,
502+
"triage": true,
497503
}
498504

499505
// isLightAgent classifies by BASE role, so an escalation rung is classified as
@@ -581,6 +587,71 @@ func (f *Factory) HasRole(id string) bool {
581587
return false
582588
}
583589

590+
// AgentsEmitting lists the agent ids that answer a given pkg/schema contract,
591+
// built-ins plus the caller's custom specs.
592+
//
593+
// The Studio needs this to offer a team a manager: only an agent that answers
594+
// the triage contract can decide who takes a rejected delivery, and the whole
595+
// registered roster is the wrong list to pick from. Package-level rather than a
596+
// Factory method because the server assembles custom specs itself and building
597+
// a factory to read a list would re-scan every agent directory.
598+
func AgentsEmitting(schemaRole string, custom []CustomSpec) []string {
599+
schemaRole = strings.TrimSpace(schemaRole)
600+
if schemaRole == "" {
601+
return nil
602+
}
603+
coding := append(workspace.ToolNames(), workspace.SpecialistToolNames()...)
604+
out := append([]RoleSpec{}, Specs()...)
605+
index := map[string]int{}
606+
for i, s := range out {
607+
index[s.ID] = i
608+
}
609+
for _, c := range custom {
610+
if i, ok := index[c.ID]; ok {
611+
ApplyOverride(&out[i], c, coding)
612+
continue
613+
}
614+
out = append(out, c.ToRoleSpec(coding))
615+
index[c.ID] = len(out) - 1
616+
}
617+
var ids []string
618+
for i := range out {
619+
NormalizeDecoding(&out[i])
620+
if strings.EqualFold(out[i].SchemaRole, schemaRole) {
621+
ids = append(ids, out[i].ID)
622+
}
623+
}
624+
sort.Strings(ids)
625+
return ids
626+
}
627+
628+
// EmitsSchema reports whether id is an agent that answers with the given
629+
// pkg/schema contract.
630+
//
631+
// Existence is not enough when a caller needs a SPECIFIC answer shape. A squad
632+
// may nominate any registered agent as its manager, but the decoding grammar is
633+
// derived from that agent's own system prompt: hand the triage question to
634+
// `go-worker` and the reply is constrained to the worker contract, so the
635+
// triage parse fails after a full model call has already been spent. Asking
636+
// first is cheaper, and falls back to a manager that can actually answer.
637+
func (f *Factory) EmitsSchema(id, schemaRole string) bool {
638+
id = strings.ToLower(strings.TrimSpace(id))
639+
schemaRole = strings.TrimSpace(schemaRole)
640+
if id == "" || schemaRole == "" {
641+
return false
642+
}
643+
specs := Specs()
644+
if f != nil {
645+
specs = f.AllSpecs()
646+
}
647+
for _, s := range specs {
648+
if strings.EqualFold(s.ID, id) {
649+
return strings.EqualFold(s.SchemaRole, schemaRole)
650+
}
651+
}
652+
return false
653+
}
654+
584655
// ArchitectEditorPair returns the role ids of the describer/editor decomposition.
585656
//
586657
// The pair exists because one model that must simultaneously solve the problem

‎pkg/agents/factory_test.go‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,13 @@
11
package agents
22

33
import (
4+
"sort"
45
"strings"
56
"testing"
67

78
"github.com/UnicoLab/slmcode/pkg/config"
9+
"github.com/UnicoLab/slmcode/pkg/plan"
10+
"github.com/UnicoLab/slmcode/pkg/schema"
811
)
912

1013
func TestSpecsRoster(t *testing.T) {
@@ -288,3 +291,85 @@ func TestPreferFastAccessorsAreNilSafeAndClearable(t *testing.T) {
288291
t.Fatal("ClearPreferFast(\"\") must drop every override")
289292
}
290293
}
294+
295+
// ── Who can be a team's project manager ──────────────────────────────────
296+
//
297+
// Existence is not enough. The decoding grammar for a request is derived from
298+
// the agent's own system prompt, so an agent that does not answer the triage
299+
// contract replies with something the reassignment step cannot read — and it
300+
// only finds that out after a full model call. Offering a choice the harness
301+
// would then refuse is worse than offering a short list.
302+
303+
func TestOnlyTriageAgentsCanManageATeam(t *testing.T) {
304+
f := NewFactory(nil, nil, "m", "p")
305+
if !f.EmitsSchema(RoleTriage, schema.RoleTriage) {
306+
t.Error("the built-in project manager must be eligible")
307+
}
308+
for _, id := range []string{plan.RoleWorker, plan.RoleReviewer, plan.RoleTester, "planner"} {
309+
if f.EmitsSchema(id, schema.RoleTriage) {
310+
t.Errorf("%q answers a different contract and must not be offered as a manager", id)
311+
}
312+
}
313+
// An agent that does not exist is not eligible either.
314+
if f.EmitsSchema("cobol-pm", schema.RoleTriage) {
315+
t.Error("an unregistered agent must never be eligible")
316+
}
317+
for _, id := range []string{"", " "} {
318+
if f.EmitsSchema(id, schema.RoleTriage) || f.EmitsSchema(RoleTriage, id) {
319+
t.Errorf("EmitsSchema accepted a blank argument (%q)", id)
320+
}
321+
}
322+
}
323+
324+
func TestAgentsEmittingListsTheEligibleManagers(t *testing.T) {
325+
got := AgentsEmitting(schema.RoleTriage, nil)
326+
if len(got) == 0 {
327+
t.Fatal("the built-in roster must offer at least one manager")
328+
}
329+
has := map[string]bool{}
330+
for _, id := range got {
331+
has[id] = true
332+
}
333+
if !has[RoleTriage] {
334+
t.Errorf("AgentsEmitting = %v, missing the built-in manager", got)
335+
}
336+
for _, unwanted := range []string{plan.RoleWorker, plan.RoleReviewer, plan.RoleTester} {
337+
if has[unwanted] {
338+
t.Errorf("AgentsEmitting offered %q, which answers a different contract", unwanted)
339+
}
340+
}
341+
if !sort.StringsAreSorted(got) {
342+
t.Errorf("AgentsEmitting = %v, want a stable sorted list", got)
343+
}
344+
if AgentsEmitting("", nil) != nil {
345+
t.Error("no contract, no candidates")
346+
}
347+
}
348+
349+
// A user who writes their own manager in the Agents page gets it offered.
350+
//
351+
// The naming convention is what makes it eligible: NormalizeDecoding derives
352+
// the contract from the id, so a `-triage` agent answers the triage schema
353+
// while an agent called "backend-pm" answers nothing in particular.
354+
func TestACustomManagerJoinsTheEligibleList(t *testing.T) {
355+
custom := []CustomSpec{{
356+
ID: "backend-triage", Title: "Backend PM", SystemPrompt: PromptTriage, MaxIter: 2,
357+
}}
358+
got := AgentsEmitting(schema.RoleTriage, custom)
359+
found := false
360+
for _, id := range got {
361+
if id == "backend-triage" {
362+
found = true
363+
}
364+
}
365+
if !found {
366+
t.Errorf("AgentsEmitting = %v, missing the user's own manager", got)
367+
}
368+
// A custom agent that answers something else stays out.
369+
other := []CustomSpec{{ID: "helper", Title: "Helper", SystemPrompt: PromptWorker, MaxIter: 2}}
370+
for _, id := range AgentsEmitting(schema.RoleTriage, other) {
371+
if id == "helper" {
372+
t.Error("a non-triage custom agent must not be offered as a manager")
373+
}
374+
}
375+
}

‎pkg/agents/prompts.go‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -213,6 +213,26 @@ Each rule below is a way this fails in production:
213213
OUTPUT — reply with this JSON object and nothing else:
214214
{"squads":[{"id":"backend","owns":["cmd/**","internal/**","go.mod"],"acceptance":"go test ./...","charter":"one line","name":"Backend","worker":"go-worker"},{"id":"frontend","owns":["web/**"],"acceptance":"npm --prefix web run build","charter":"one line","name":"Frontend","worker":"react-worker"}],"contract":{"interfaces":[{"id":"GET /api/todos","provider":"backend","consumers":["frontend"],"spec":"200 -> [{id,title,done}]"}],"summary":"how the halves meet"},"integration":{"acceptance":"go test ./... && npm --prefix web run build","notes":["the API serves web/dist at /"]},"summary":"one line"}`
215215

216+
const PromptTriage = `Project manager. One delivery was rejected. Decide who takes it next.
217+
218+
You get the rejected task, what the reviewer or tester found, every attempt
219+
already made, and the ROSTER of agents that can actually be dispatched.
220+
221+
RULES — each is a way this goes wrong:
222+
- Pick from the ROSTER, exactly as written. An agent that is not on it cannot be
223+
dispatched and the task would sit unassigned forever.
224+
- Never pick the agent that just failed. It has already spent every retry the
225+
ladder allows; handing it the same work again is the loop you are here to end.
226+
- Prefer a specialist for the language of the files over a generic one.
227+
- guidance is what the NEXT agent needs that the last one did not have: the
228+
specific thing to do differently. "Try again" and "be careful" are not
229+
guidance. If the attempts show the same fix tried twice, say what to try
230+
instead.
231+
- reason is one line explaining the choice, for the human reading the board.
232+
233+
OUTPUT — reply with this JSON object and nothing else:
234+
{"assignee":"go-corrector","reason":"compile error in Go code the worker could not resolve","guidance":"The handler returns a bare slice; encode with json.NewEncoder(w).Encode(todos) and set Content-Type before writing.","priority":"high"}`
235+
216236
// ---------------------------------------------------------------------------
217237
// Review roles (no tools, pure JSON)
218238
// ---------------------------------------------------------------------------

0 commit comments

Comments
 (0)