docs: add "How your Roxy's teams work" user guide#24
Merged
Conversation
Covers the manager/team tier split (ADR 0055), how portfolio_spinup_team
clones a team-template ({{REPO}}/{{TEAM_NAME}}/{{GATE}} sentinels) and
team_archetypes, and the two-axis coder escalation (model-tier ladder,
live today, vs execution-grounded search per ADR 0064, landing as the
coder plugin) with a worked spin-up + dispatch example. Linked from
README.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- {{GATE}} sentinel: empty doesn't mean "no gate" — portfolio_spinup_team
auto-detects one from the repo's build files (ruff for Python, docs:build
for VitePress, npm test otherwise) and only leaves it truly empty when
none of those match (_detect_gate).
- Archetypes preset repo/gate/template, not lifecycle. auto_dispose still
defaults to True regardless of archetype, so the worked example's
"standing" api-team/docs-team need auto_dispose=False explicitly, and
portfolio_autodispose()'s behavior in that example follows from the flag,
not from "being an archetype."
- portfolio_rollup() actually returns a JSON array of per-board
{board, total, counts, blocked, critical_path} dicts (_rollup_one), not a
dict keyed by team name with flat ready/in_progress fields — fixed the
worked example's sample output to match.
Verified all three against the live portfolio-plugin/projectBoard-plugin
source (_spinup_team, _archetypes, _detect_gate, _rollup_one) rather than
against the prose. No behavior change — docs only; re-ran
scripts/verify_bundle.py, still green.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
…25.0) The escalation ladder section described a `fast → smart → reasoning [→ opus]` tier ladder, both in prose and in the worked `coders:` YAML example (with `fast: proto` annotated "first attempt"). The pinned project_board plugin (v0.25.0, commit 1e40213284) has no `fast` tier: store.py's TIER_LADDER is `["smart", "reasoning", "opus"]`, and the initial tier is chosen from a feature's `difficulty` (DIFFICULTY_TIER), defaulting to `smart` — not a config-declared "first attempt" rung. A `fast:` key in `coders:` is dead configuration; loop.py never looks it up. Corrected the prose and example to the real ladder (smart → reasoning → opus) and explained that the entry tier follows from feature difficulty rather than always starting at the bottom rung. Re-ran scripts/verify_bundle.py from a synced protoAgent checkout — still green, same pin set (project_board@1e40213284). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/teams.md, a user-facing guide covering how a Roxy-style Portfolio Manager (this bundle's archetype) relates to the teams it spins up: the board-less PM tier vs. the per-repoproject_boardteam tier (ADR 0055), howportfolio_spinup_teamclones a team-template ({{REPO}}/{{TEAM_NAME}}/{{GATE}}sentinels) andteam_archetypes, and the two-axis coder escalation — the model-tier ladder (fast → smart → reasoning, live today inproject_board) vs. execution-grounded search (greedy → best-of-k → tree-search → fusion, gated on tests, landing as the standalonecoderplugin per ADR 0064) — plus a worked spin-up + dispatch example.protoagent.bundle.yaml(what the gate validates) is untouched.Test plan
README.mdandprotoagent.bundle.yamlto match tone/structure and confirm what the bundle ships.portfolio-plugin(README,protoagent.plugin.yaml,examples/team-template) andprojectBoard-plugin(README,loop.py) checkouts, and ADR 0055 / 0064 inprotoAgent.Passes — expected, since this PR doesn't touch the manifest the gate validates.
🤖 Generated with Claude Code