Conversation
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
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
There was a problem hiding this comment.
🟡 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
agentplus 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-prin step 6 andcode-reviewin quality gate 4, but this prerequisite check only verifiestriageandimplement. 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 Reviewas 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-skillsexplicitly 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 toLinear. 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, andTodo.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.mddoes 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
epicdrops its state role (docs/agents/autonomic-issues.md:37). Leaving both labels would violate the documented state machine. Restrict the coexistence claim toagentand document thatepicreplaces 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.
Playwright test resultsDetails
|
…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
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
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
- 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
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
Groups the five triage-role labels into a mutually-exclusive Linear label group (team
UPL), consolidates branch/commit conventions intodocs/git-conventions.md, and fixespr-review-fixerto fall back to the MCP GitHub tools whenghisn'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 100shows the five triage-role labels withparentpointing at thetriagegroup.ghCLI, runningpr-review-fixerfetches/resolves/replies viamcp__github__*tools instead of failing oncommand not found.docs/git-conventions.md,docs/agents/*.md, andCLAUDE.mdresolve to real files in this repo.🤖 Generated with Claude Code
https://claude.ai/code/session_01HFNqcr5d2EN6T6TkTc8WBd