Skip to content

docs(agents): triage groups, git conventions - #498

Open
chiptus wants to merge 26 commits into
mainfrom
docs/triage-labels-git-conventions
Open

chiptus wants to merge 26 commits into
mainfrom
docs/triage-labels-git-conventions

Conversation

@chiptus

@chiptus chiptus commented Sep 13, 2026

Copy link
Copy Markdown
Owner

Groups the five triage-role labels into a mutually-exclusive Linear label group (team UPL), consolidates branch/commit conventions into docs/git-conventions.md, and fixes pr-review-fixer to fall back to the MCP GitHub tools when gh isn't installed.
Linear now enforces one triage state at a time instead of relying on discipline alone.

Verification

  • npx linearis labels list --team UPL --limit 100 shows the five triage-role labels with parent pointing at the triage group.
  • In a session without the gh CLI, running pr-review-fixer fetches/resolves/replies via mcp__github__* tools instead of failing on command not found.
  • Links in docs/git-conventions.md, docs/agents/*.md, and CLAUDE.md resolve to real files in this repo.

🤖 Generated with Claude Code

https://claude.ai/code/session_01HFNqcr5d2EN6T6TkTc8WBd

Documents the five canonical triage-role labels as a mutually-exclusive
Linear label group, separates lifecycle markers (agent:wip/agent:pr/epic)
from that group, and consolidates branch-naming + commit/PR title format
into docs/git-conventions.md, linked from CLAUDE.md and autonomic-issues.md.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HFNqcr5d2EN6T6TkTc8WBd
Reorders git-conventions.md so the shared <type> is defined once, before
its first use; front-loads the CLAUDE.md pointer's trigger word; and adds
the missing label-group setup step to the autonomic pipeline's setup
checklist (single source of truth, referenced from triage-labels.md).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HFNqcr5d2EN6T6TkTc8WBd
New user-invoked skill that runs setup-matt-pocock-skills to pick this
repo's issue tracker (and its triage labels/domain docs), then reuses
that same tracker choice to scaffold docs/agents/autonomic-issues.md
from a GitHub- or Linear-shaped template — never asking the tracker
question twice.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HFNqcr5d2EN6T6TkTc8WBd
Replaces the two lifecycle labels with a single `agent` label whose
stage is read off the issue's native Linear status (In Progress while
claimed, In Review once the PR is open) instead of a second label.
Retired agent:wip/agent:pr in Linear (team UPL) and migrated the one
live issue carrying agent:pr (UPL-7, open PR #463) to
the new scheme. Also updates the setup-chiptus-env Linear template to
match; the GitHub template is unchanged since GitHub issues have no
native per-issue status to borrow.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HFNqcr5d2EN6T6TkTc8WBd
Copilot AI lite review requested due to automatic review settings September 13, 2026 07:36
@vercel

vercel Bot commented Sep 13, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
upline Ready Ready Preview Sep 14, 2026 8:51am UTC

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Unresolved critical and moderate workflow, skill-path, and template-configuration issues block approval.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Documents Linear triage-label lifecycle changes, centralizes Git conventions, and adds tracker-specific setup templates.

Changes:

  • Replaces separate agent stage labels with agent plus native Linear status.
  • Adds Git branch and commit/PR conventions.
  • Adds Linear and GitHub autonomic pipeline setup templates.
File summaries
File Description
docs/git-conventions.md Centralized Git conventions
docs/agents/triage-labels.md Triage label groups and lifecycle
docs/agents/autonomic-issues.md Updated Linear pipeline lifecycle
CLAUDE.md Links Git conventions
.claude/skills/setup-chiptus-env/SKILL.md Cross-tracker setup workflow
.claude/skills/setup-chiptus-env/autonomic-issues-linear.md Linear pipeline template
.claude/skills/setup-chiptus-env/autonomic-issues-github.md GitHub pipeline template
Review details

Suppressed comments (8)

.claude/skills/setup-chiptus-env/SKILL.md:29

  • The GitHub template still contains the <PRIORITY_SIGNAL> placeholder (line 35), but this step only asks for/fills repository identifiers, cap, cadence, and models. A GitHub setup will therefore write an unresolved priority expression into the generated playbook; include the priority-label policy in discovery/confirmation and fill this placeholder before writing.
Fill the chosen template's placeholders (repo/team identifiers, PR cap, routine cadence and models) from what step 1 already learned plus one round of questions for anything it didn't — routine cadence, PR-cap number, which models to run triage vs. fix on. Show the filled draft before writing; let the user edit it.

.claude/skills/setup-chiptus-env/SKILL.md:19

  • The generated playbooks require create-pr in step 6 and code-review in quality gate 4, but this prerequisite check only verifies triage and implement. On a repo missing either required skill, setup will proceed and produce a pipeline that cannot complete; check all four skills (or equivalents) before scaffolding.
The autonomic pipeline needs the `triage` skill (fires the rubric) and an `implement` skill or equivalent (does the fix-firing work) already installed. If either is missing, tell the user which is missing and stop — nothing to scaffold without them.

.claude/skills/setup-chiptus-env/SKILL.md:29

  • The Linear template hardcodes In Progress/In Review as workflow statuses, but the setup flow never discovers or asks for the target team's status names. A valid Linear team using different names would receive a playbook whose claim, cap, and PR-transition instructions cannot run; inspect the team's workflow states and substitute them (or ask for them) when filling this template.
Fill the chosen template's placeholders (repo/team identifiers, PR cap, routine cadence and models) from what step 1 already learned plus one round of questions for anything it didn't — routine cadence, PR-cap number, which models to run triage vs. fix on. Show the filled draft before writing; let the user edit it.

.claude/skills/setup-chiptus-env/SKILL.md:24

  • setup-matt-pocock-skills explicitly treats Linear as the “Other” tracker and records that workflow as freeform, so the generated tracker document will not reliably have a heading exactly equal to Linear. A fresh Linear setup can therefore fall through to the manual-adaptation branch instead of selecting this template; detect Linear from the recorded workflow (or make the tracker value canonical).
- Tracker is **Linear** → [`autonomic-issues-linear.md`](./autonomic-issues-linear.md).

.claude/skills/setup-chiptus-env/autonomic-issues-linear.md:7

  • This template is advertised for any Linear team, but it hard-codes the workflow states In Progress, In Review, and Todo. setup-chiptus-env's fill step only asks for cadence, cap, and models; it never discovers or confirms those status names. A team with different Linear states will therefore get invalid transitions and stale-claim instructions. Make the states placeholders and have setup confirm them, or explicitly restrict this template to teams using these names.
In-flight state lives on **Linear issues** as one label (`agent`) plus the issue's native status; a fresh firing reads both to know where an issue sits in the pipeline. `agent` marks "an agent currently owns this issue or has an open PR for it" — the stage within that is the status, not a second label: `In Progress` while claimed, `In Review` once the PR is open. `agent` and `epic` are lifecycle markers, standalone (not part of the mutually-exclusive triage-role label group) — see `docs/agents/triage-labels.md`. The PR title/body carries the Linear identifier (e.g. `<TEAM>-123`) so Linear's GitHub integration transitions the linked issue when the PR merges — that transition happens outside the routine (merging is the maintainer's), so don't treat it as something the fix firing itself performs.

docs/agents/autonomic-issues.md:50

  • .claude/skills/create-pr/SKILL.md does not exist in this checkout; the installed skill is .agents/skills/create-pr/SKILL.md. Since this changed line is the routine's PR-opening step, the worker cannot follow the playbook as written. Update this path and the analogous triage/implement references (or make setup materialize them in .claude).
6. **Open the PR** following `.claude/skills/create-pr/SKILL.md` exactly, with the Linear identifier (e.g. `UPL-123`) in the PR title or body per `docs/agents/issue-tracker.md` — not `Closes #N`, which only works for GitHub issues. Move the issue's status from `In Progress` to `In Review` (`npx linearis issues update <identifier> --status "In Review"`); `agent` stays applied. One PR per firing — done.

docs/agents/triage-labels.md:7

  • The triage skill requires an existing conflict between state labels to be surfaced to the maintainer before changing anything (.agents/skills/triage/SKILL.md:41). With this group, applying a new state silently clears the previous state, so the routine can erase evidence of a conflict instead of asking. Add a pre-update conflict check and leave issues with multiple state labels untouched; group exclusivity should not replace that safeguard.
The skills speak in terms of five canonical triage roles. In Linear these five live together in a single **label group** (Linear's mutually-exclusive label set): applying one automatically clears any other member of the group from the issue, so an issue can never carry two triage-role labels at once. Group setup: `docs/agents/autonomic-issues.md`'s setup checklist.

docs/agents/triage-labels.md:23

  • This blanket statement says pipeline labels coexist with a triage-role label, but the pipeline below explicitly says that applying epic drops its state role (docs/agents/autonomic-issues.md:37). Leaving both labels would violate the documented state machine. Restrict the coexistence claim to agent and document that epic replaces the state role.
Repo-specific labels the autonomic pipeline (`docs/agents/autonomic-issues.md`) uses outside the five canonical roles above — not part of the mattpocock/skills vocabulary, so a skill invocation won't look for them here. These are lifecycle markers, not triage roles: they stay standalone (not in the label group above) because they track pipeline progress alongside a triage-role label, not instead of one — an issue can be `ready-for-agent` and `agent` at the same time.
  • Files reviewed: 7/7 changed files
  • Comments generated: 7
  • Review effort level: Lite

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment thread .claude/skills/setup-chiptus-env/autonomic-issues-github.md Outdated
Comment thread .claude/skills/setup-chiptus-env/autonomic-issues.md Outdated
Comment thread docs/agents/autonomic-issues.md
Comment thread docs/agents/autonomic-issues.md
Comment thread docs/agents/autonomic-issues.md
Comment thread docs/agents/autonomic-issues.md Outdated
Comment thread docs/git-conventions.md
@github-actions

github-actions Bot commented Sep 13, 2026

Copy link
Copy Markdown

Playwright test results

passed  65 passed

Details

stats  65 tests across 21 suites
duration  1 minute, 27 seconds
commit  cbca638

…arity

Removes a leftover "PR-side label" mention in autonomic-issues.md now
that GitHub PRs carry no mirrored label. Adds a note to the
setup-chiptus-env Linear template (not the repo docs, which are
tracker-specific) explaining that GitHub's native PR state
(draft/ready/merged/closed) already parities Linear's issue status, so
future setups shouldn't invent a matching status label on the PR side.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HFNqcr5d2EN6T6TkTc8WBd
The PR-cap paragraph claimed counting stayed correct "even if the label
is forgotten" — true under the old agent:pr-only count, false now that
the count requires both --label agent and --status "In Review" together
(a forgotten label does drop the issue from the count; this is
intentional, since it's what lets a maintainer's own manually-opened PR
skip the cap). Also corrects issue-tracker.md's `issues update --state`
to the actual verified CLI flag, `--status`, which is what the new
claim/PR-review steps already used correctly.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HFNqcr5d2EN6T6TkTc8WBd
setup-chiptus-env now checks for setup-matt-pocock-skills before
invoking it, installing the mattpocock/skills set via `npx skills`
when missing, instead of assuming it's already there. Also adds a step
to redirect domain docs (CONTEXT.md, ADRs) to an external folder for
repos that can't keep them in-repo (e.g. Portainer, where architecture/
customer docs must stay out of the public repo) — rewriting
docs/agents/domain.md's pointer rather than touching
setup-matt-pocock-skills' own templates.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HFNqcr5d2EN6T6TkTc8WBd
… docs

Generalizes the external-docs step from just CONTEXT.md/ADRs to the
entire docs/agents/ folder (issue tracker, triage labels, autonomic
pipeline, domain consumer rules), matching the Portainer pattern: the
external root mirrors the in-repo layout exactly, so the docs' own
mutual cross-references need no rewriting — only CLAUDE.md/AGENTS.md's
entry pointers and the Routine prompts need to resolve a .git/-local
pointer file to the external root. Also flags the real gap this
creates for cloud Routine firings, which work off a fresh clone with
no access to this machine's .git/ contents.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HFNqcr5d2EN6T6TkTc8WBd
…only

An env var (e.g. AGENTS_DOCS_REPO) holding a separate docs repo's git
URL is now the default pointer mechanism, since it's settable in a
Routine's own environment_variables and so actually solves the cloud-
portability gap the .git/-local file couldn't. The .git/ file stays as
a lighter option for a solo local setup with no Routines involved, but
the skill now asks the user to choose explicitly between the two
rather than defaulting silently, since the choice decides whether the
autonomic pipeline can read the docs at all.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HFNqcr5d2EN6T6TkTc8WBd
…nsumers

CLAUDE.md's pointers stay plain ("See docs/agents/X.md", no conditional
phrasing) since it's always read locally regardless of where docs live
and per-pointer resolution text would duplicate the same logic at every
call site. Instead, step 3 now has the skill grep for whichever
mattpocock skills actually read CONTEXT.md/docs/adr/docs/agents
directly (domain-modeling, triage, code-review, etc.) and prepend the
external-docs check to each of those, plus the two Routine prompts —
the actual code paths that need to know, once, in one place per file.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HFNqcr5d2EN6T6TkTc8WBd
autonomic-issues-github.md and autonomic-issues-linear.md were ~90%
identical (triage bar, quality gates, guardrails, notifications, both
routine prompts verbatim) with only the label/status mechanism, CLI
commands, and a few paragraphs differing per tracker — real
duplication of a single source of truth. Merged into one
autonomic-issues.md with the differing paragraphs wrapped in
<!-- tracker:github --> / <!-- tracker:linear --> marker pairs,
positioned right next to their counterpart; filling the template is
now "delete the blocks for the tracker you didn't pick."

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HFNqcr5d2EN6T6TkTc8WBd
… fragments

The interleaved-marker design didn't scale: every section grew another
block per tracker, so a third tracker would mean editing every section
of an already-written file. Replaces it with a skeleton
(autonomic-issues.md, 100% tracker-invariant prose) plus small
per-tracker fragment files (tracker-github.md, tracker-linear.md) that
each supply the same five named slots (INTRO, SHARED_STATE,
INTAKE_QUERY, FIX_FIRING_STEPS, SETUP_ITEMS). Adding a tracker is now
"write one new fragment file against these five slots" — the skeleton
never changes.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HFNqcr5d2EN6T6TkTc8WBd
The Setup checklist's items 3-4 lived in the skeleton after the
fragment-supplied items 1-2, relying on markdown list continuation
across a template substitution boundary — fragile in general, and
prettier's markdown reflow already collapsed it into one broken
paragraph on the prior commit. SETUP_ITEMS now owns the whole 1-4 list
in each fragment (2 short duplicated lines) instead.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HFNqcr5d2EN6T6TkTc8WBd
…l table

Both prior designs (interleaved markers, then skeleton+fragments) kept
duplicating full paragraphs per tracker when only a handful of facts
actually differ: how "claimed"/"in review" are represented, how
priority works, how a PR declares its issue link. Rewrites the whole
doc in tracker-agnostic language (triage rubric, quality gates,
guardrails, bail/fail handling, notifications, routine prompts never
mention a tracker) referring back to one small "Tracker specifics"
table for the load-bearing facts only — not a CLI reference, which the
agent already gets from the tracker's own usage/--help. Adding a
tracker is now one new table column, not a new file.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HFNqcr5d2EN6T6TkTc8WBd
GitHub and Linear are columns in the table, not rows; a new tracker
adds a column. Matches the wording already used in SKILL.md.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HFNqcr5d2EN6T6TkTc8WBd
Comment thread .claude/skills/setup-chiptus-env/autonomic-issues.md Outdated
Comment thread .claude/skills/setup-chiptus-env/tracker-github.md Outdated
Missed applying the earlier agent-label-plus-native-state decision to
GitHub's own column: it still described the old agent:wip -> agent:pr
swap. A GitHub PR's own draft/ready-for-review/merged state already
tells you claimed vs in-review once a PR exists, same reasoning as
Linear's native status — so GitHub gets one `agent` label too, applied
at claim and never swapped. Updated the two callers that assumed a
literal marker-move action (Fix firing step 6, the manual-PR
coexistence note) to describe the inferred state instead.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HFNqcr5d2EN6T6TkTc8WBd
The "don't add a matching status label on the GitHub PR side" note was
sitting in the Linear cell even though its subject is GitHub's own PR
state; moved to the GitHub cell (referencing the Linear cell for
contrast) instead of being explained from the other tracker's row.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HFNqcr5d2EN6T6TkTc8WBd
…s missing

The skill's fetch/resolve/reply steps hard-depended on the gh CLI,
which isn't installed in this remote session (GitHub access here goes
through mcp__github__* tools instead) — confirmed by the failed
fetch-review-threads.sh run. Adds an explicit gh-availability check at
the top of Phase 1 and an MCP-based path alongside each gh-dependent
step (fetch via pull_request_read, resolve via resolve_review_thread,
reply via add_reply_to_pull_request_comment / add_issue_comment) that
reconstructs the same data shape, so the rest of the skill is
unaffected by which path ran.

Note: this file is npx skills-managed (mattpocock/skills) — a future
bare reinstall would overwrite this fix back out.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HFNqcr5d2EN6T6TkTc8WBd
Linear's mutual-exclusivity feature kept the five canonical triage-role
labels enforced structurally, but nothing said what covers that on
GitHub, which has no equivalent group feature. Adds a table row and a
setup-checklist clause: GitHub relies on the triage skill's own
discipline (remove any other triage-role label before applying a new
one) instead of the tracker enforcing it.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HFNqcr5d2EN6T6TkTc8WBd
…r's grouped look

Confirmed via linearis that Linear's own label names stay plain
(ready-for-agent, not triage/ready-for-agent) — the grouped display
comes from each label's parent pointing at the triage group label,
which Linear's UI renders hierarchically. GitHub has nothing
equivalent, so the closest substitute is naming the five labels with
a literal triage/ prefix. Documented in the Tracker specifics table
(with the Linear cell clarifying the contrast) and suggested as a
default during setup-matt-pocock-skills' own label-naming question.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HFNqcr5d2EN6T6TkTc8WBd
Comment thread .agents/skills/pr-review-fixer/SKILL.md Outdated
- Disclosed step 3's external-docs mechanics (pointer options, layout,
  the grep-and-patch recipe for consumer skills) into a new
  external-docs.md, reached only on the "external" branch most repos
  never take, instead of sitting inline in the main procedural flow
  every reader sees.
- Trimmed a duplicated explanation in the Tracker specifics table: the
  GitHub "Lifecycle labels" row restated the draft/ready/merged
  mapping the "Claimed / in review" row above it already gives: now
  points back at it instead.
- Fixed a stale "the templates generate" (plural, left over from the
  since-collapsed multi-file design).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HFNqcr5d2EN6T6TkTc8WBd
This session iterated the autonomic-issues.md template through four
different shapes reactively; worth a slower discussion session before
more incremental edits. Captures the open questions (tracker-table
generality, external-docs relocation being unvalidated, npx skills
unverified, the triage/ prefix suggestion being unvalidated) rather
than restating the diffs, which live in this branch's commit history.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HFNqcr5d2EN6T6TkTc8WBd
Split out to #499, since it still needs a discussion
pass before it's done (see that PR's handoff doc) and shouldn't hold
up these settled repo-docs changes.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HFNqcr5d2EN6T6TkTc8WBd
@chiptus chiptus changed the title docs(agents): Linear triage-label group + git conventions docs(agents): triage groups, git conventions Sep 14, 2026
The previous fix wrapped the fetch script in "gh available: run ...",
but that used the !`command` auto-exec markdown syntax, which the
harness pre-executes unconditionally at skill-load time -- before the
model ever reads the conditional prose around it. That's exactly what
the reported /pr-review-fixer failure showed: the script still ran
(and failed on gh: command not found) despite the branch text saying
to check first. Removes the auto-exec syntax so the agent runs the
check and the script itself via the Bash tool, where the branch can
actually take effect.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HFNqcr5d2EN6T6TkTc8WBd
…ts own file

Per review feedback on PR #498: the "gh missing" branch (Phase 1's MCP
fetch recipe, Phase 4's resolve/reply mechanics) was inline in every
reader's path even though only some sessions need it. Split into
gh-missing.md, pointed to from Phase 1 and Phase 4 only where the gh
CLI turns out to be unavailable -- same progressive-disclosure move
already applied to setup-chiptus-env.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HFNqcr5d2EN6T6TkTc8WBd
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.

3 participants