Process skills, /sm re-scope, /ext, and reference libraries - #61
Merged
Conversation
Cut the 5.1.0 release (2026-06-14): - CHANGELOG: convert [Unreleased] -> [5.1.0]; fold in the reference-library additions, /tw + /mlops wiring, roster + backend-naming reconciliation, and a Removed section (DART dashboard/Hub, RAG subsystem, personal migration scripts); open a fresh empty [Unreleased]. - Bump version blocks in CLAUDE.md and AGENTS.md (5.0.0 -> 5.1.0, date 2026-06-14). - Add the 5.1.0 row to the README version-history table.
Browser extensions are a platform, not a stack: the service-worker lifecycle, the permissions model, injection and isolated worlds, and the tab APIs have no analogue in web-app work, and getting them wrong fails silently rather than loudly. Same reasoning that made native mobile its own agent rather than a /fe reference. SKILL.md carries the MV3 mental model, a surface-choice table (popup vs options vs extension page vs side panel vs in-page overlay vs tab group), and the ten platform facts that account for most extension bugs — a bundled content script cannot return a value, activeTab is revoked on navigation, a pinned tab cannot be grouped, tab-strip writes are refused mid-drag, extension fetch sends cookies by default, and so on. Seven references carry the depth: mv3-architecture, surfaces-and-ui, tabs-and-groups, injection-and-extraction, permissions-and-security, long-running-work, build-and-test. Also: commands/ext.md, a roster row, and two disambiguation entries separating /ext from /fe and /e2e.
.praxis/ is per-machine evidence memory and .aidevteam/ is local config; neither belongs in version control. docs/archive/ holds internal transcripts — this repo is public, and those carry strategy and private-project detail.
Roles cover who does the work; these cover how it is decided, checked and paid for. - fid-lifecycle — Backlog → investigation → design doc/epic → tickets → Done without orphans or two disagreeing records. - verify-landed — prove a change exists and does something. A green build is not evidence: removing nothing breaks nothing, so a no-op edit compiles and passes. - review-tier — how much multi-agent review to buy and how to scope it. Free gates first; a follow-up round reviews the fix and the prior findings, not the whole PR again. - model-selection — which model tier to spend. The test is whether a cheap verifier exists downstream. - research-method — investigate so the result is trustworthy; publish so it survives a hostile reader. The rule they enforce: a ticket is Done only when its negative criteria are met and each names the symbol that enforces it. An audit of one project's 30 open tickets found 13 with an unmet criterion, nearly always the negative case. workflow-engine gains the tracking-location rule (local folder vs external tracker is a convenience call; never run both for the same thing). The roster gains a cross-cutting skills table.
The role was defined as 'conductor of the orchestra — every agent reports to you', which is unfalsifiable, so nothing ever contradicted it and in practice it was never invoked. It is now accountable for six checks with checkable answers: orphan work items, plan-vs-tracker divergence, backlog items whose work moved on, Done-without-negative-criteria, parked-without-a-trigger, and epics claiming completion over open children. Output is counts and named items, never a verdict. references/board-integrity.md also replaces the scheduled retrospective with continuous capture: ask one question at merge, distil the running page per epic. The justification is empirical — the durable lessons from a recent two-day run were all found mid-work by hitting them; a fortnightly retro would have recovered none of them. It also states what makes a lesson usable: name the mechanism, not the mistake.
Assumes a retrieval-grounded answer is wrong until each claim is proven verbatim against a source passage. Targets the failure class a grounding judge cannot see: an answer minus its qualifier is still entailed by its sources, so 'is this grounded?' passes it.
Deep material for the roles that need it, loaded on demand rather than carried in every session: Theia platform architecture (/arch), Theia design conventions (/ui), Theia frontend patterns (/fe), and Rust (/be).
Regenerated by Praxis. Drops a stale strategy note that should not have been in a public repository.
claude/CLAUDE.md gains a Process skills section so the six cross-cutting skills are reached for deliberately rather than discovered by accident, and states the rule they exist to enforce: a ticket is Done only when its negative criteria are met and each names the symbol enforcing it. CHANGELOG records the additions and the /sm re-scope. README's skill count updated for the new skills.
There was a problem hiding this comment.
🟡 Not ready to approve
Several updated/new docs conflict with the PR’s “no private-project references” claim and there’s inconsistent skill-count metadata across entrypoints (README vs CLAUDE/AGENTS/claude/CLAUDE).
Once you've addressed the issues Copilot identified, you can request another Copilot review.
This review doesn't count toward merge requirements. Sign up for the private preview to control whether Copilot approvals count.
Pull request overview
This PR expands the AI Development Team framework’s documented workflow/process layer by adding several cross-cutting “process skills”, rescoping /sm toward board integrity, introducing a new /ext (browser extension) specialist with extensive references, and wiring in additional Theia + Rust reference libraries across relevant role skills.
Changes:
- Added cross-cutting process skills (
fid-lifecycle,verify-landed,review-tier,model-selection,research-method) plusanswer-audit. - Rescoped Scrum Master guidance toward board integrity, adding a dedicated
board-integrity.mdreference. - Added
/extcommand + browser extension skill and references; added Theia references for/fe,/ui,/arch, plus a Rust reference for/be; updated.gitignoreto exclude local agent state and archives.
File summaries
| File | Description |
|---|---|
| README.md | Updates headline skill count and extends version-history table. |
| claude/skills/workflow-engine/SKILL.md | Adds guidance on choosing a single tracker-of-record (local vs Jira/Confluence). |
| claude/skills/verify-landed/SKILL.md | New process skill: verification that behavior changes truly landed. |
| claude/skills/review-tier/SKILL.md | New process skill: deterministic review scoping/tiering guidance. |
| claude/skills/research-method/SKILL.md | New process skill: experiment/investigation rigor and reporting discipline. |
| claude/skills/model-selection/SKILL.md | New process skill: model-tier selection heuristics for cost vs verification. |
| claude/skills/management/scrum-master/SKILL.md | Rescopes /sm from orchestration/ceremony to board integrity. |
| claude/skills/management/scrum-master/references/board-integrity.md | New board-integrity checks + continuous retrospection guidance. |
| claude/skills/fid-lifecycle/SKILL.md | New process skill: hygiene for backlog→FID→tickets lifecycle. |
| claude/skills/disambiguation.md | Adds /ext routing guidance and clarifies /ext vs /fe. |
| claude/skills/development/frontend/react/frontend-developer/SKILL.md | Adds Theia reference pointer for /fe. |
| claude/skills/development/frontend/react/frontend-developer/references/theia.md | New Theia extension-development playbook reference. |
| claude/skills/development/browser/browser-extension-developer/SKILL.md | New /ext skill: MV3/WebExtensions platform guidance and gates. |
| claude/skills/development/browser/browser-extension-developer/references/tabs-and-groups.md | New /ext reference: tab/group patterns and cleanup behavior. |
| claude/skills/development/browser/browser-extension-developer/references/surfaces-and-ui.md | New /ext reference: UI surfaces, lifetimes, and accessibility. |
| claude/skills/development/browser/browser-extension-developer/references/permissions-and-security.md | New /ext reference: permissions model + CSP/security review checklist. |
| claude/skills/development/browser/browser-extension-developer/references/mv3-architecture.md | New /ext reference: worker lifecycle/state/messaging patterns. |
| claude/skills/development/browser/browser-extension-developer/references/long-running-work.md | New /ext reference: long-running job ownership/state/UX rules. |
| claude/skills/development/browser/browser-extension-developer/references/injection-and-extraction.md | New /ext reference: injection strategies + “publish-and-poll” contract. |
| claude/skills/development/browser/browser-extension-developer/references/build-and-test.md | New /ext reference: bundling/testing/CI and build postconditions. |
| claude/skills/development/backend/java/backend-developer/SKILL.md | Adds Rust reference pointer for /be. |
| claude/skills/development/backend/java/backend-developer/references/rust.md | New Rust backend reference (tokio/axum patterns, RPC, SSE, cancellation). |
| claude/skills/design/ui-designer/SKILL.md | Adds Theia design reference pointer for /ui. |
| claude/skills/design/ui-designer/references/theia-design.md | New Theia design reference (tokens/layout/accessibility within Theia). |
| claude/skills/architecture/solution-architect/SKILL.md | Adds Theia platform reference pointer for /arch. |
| claude/skills/architecture/solution-architect/references/theia-platform.md | New Theia platform architecture reference (placement/upgrade/security). |
| claude/skills/answer-audit/SKILL.md | New skill: adversarial audit of retrieval-grounded answers. |
| claude/commands/ext.md | Adds /ext command wiring to the new browser-extension skill. |
| claude/commands/agents.md | Updates /sm description and lists cross-cutting skills + /ext. |
| claude/CLAUDE.md | Documents process skills and tracking-location rule in deployable instructions. |
| CLAUDE.md | Updates version/date metadata (top-level instructions). |
| AGENTS.md | Updates version/date metadata and adds embedded Praxis memory block. |
| CHANGELOG.md | Records Unreleased additions/changes/fixes and retains 5.1.0 notes. |
| .gitignore | Ignores local agent state and archives for a public repo. |
Review details
Comments suppressed due to low confidence (1)
claude/skills/development/backend/java/backend-developer/SKILL.md:102
- This line references “bumbl-dis” as an example; if the goal is to avoid private/project-specific references in public framework docs (as stated in the PR description), consider making it generic.
- `references/spring-kafka.md` — Kafka producers/consumers, DLT, transactional outbox.
- `references/hmrc-api/overview.md` — HMRC Making Tax Digital (MTD) API integration (OAuth 2.0, fraud-prevention headers, Self Assessment). Load for UK gov tax-API work.
- `references/rust.md` — Rust backend (tokio + axum HTTP/WS/SSE, JSON-RPC dispatch, dedicated-thread rusqlite, Anthropic streaming, cancellation). Load for Rust work such as bumbl-dis.
- Files reviewed: 33/34 changed files
- Comments generated: 11
- Review effort level: Low
We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.
| - **Version**: 5.1.0 (see `CHANGELOG.md`) | ||
| - **Release Date**: 2026-06-14 | ||
| - **Editors**: Claude Code, Cursor, Kiro, VS Code (universal `install.sh`) | ||
| - **Skills**: 29 (15-agent core team + optional specialists; tech stacks as references) |
| - **Version**: 5.1.0 (see `CHANGELOG.md`) | ||
| - **Release Date**: 2026-06-14 | ||
| - **Editors**: Claude Code, Cursor, Kiro, VS Code (universal `install.sh`) | ||
| - **Skills**: 29 (15-agent core team + optional specialists; tech stacks as references) |
Comment on lines
+18
to
+22
| ## Process skills — load these, they are not optional extras | ||
| Beside the role agents, six **cross-cutting process skills** cover how work is decided, checked and paid for. They self-trigger from their descriptions; know they exist so you reach for them deliberately. | ||
| - **`workflow-engine`** — the gate contract. Consult first, on every task. | ||
| - **`fid-lifecycle`** — moving work Backlog → investigation → design doc / epic → tickets → Done without orphans or two disagreeing records. Delete the backlog item once its design doc exists; one epic per design doc, titled to correspond; every ticket parented to it and listed in its registry; **the tracker is authoritative for status** when the two disagree. | ||
| - **`verify-landed`** — after any behaviour-changing edit, and before claiming a finding fixed or a criterion met. A green build is not evidence your change exists: *removing nothing breaks nothing*, so a no-op edit compiles and passes every test. |
| - `references/vue.md` — Vue 3 (Composition API, Pinia, Nuxt 3) — the full Vue playbook. | ||
| - `references/flutter.md` — Flutter/Dart cross-platform mobile — the full Flutter playbook. | ||
| - `references/javafx-desktop/overview.md` — JavaFX desktop apps (FXML, MVVM, Scene Builder, jpackage) — load for desktop UIs (not web). | ||
| - `references/theia.md` — Eclipse Theia extension development (InversifyJS DI, React widgets, JSON-RPC services, Theia AI, Open VSX, electron-builder) — load for Theia-based IDE products (e.g. bumbl-app). |
| - `references/templates.md` — design-spec, user-flow, and discovery templates. | ||
| - `references/javafx.md` — JavaFX icon/desktop solution. | ||
| - `references/javafx-design/overview.md` — JavaFX/FXML/CSS desktop UI design (design system, component library, layout patterns, Scene Builder). | ||
| - `references/theia-design.md` — designing within Eclipse Theia IDE products (VS Code-compatible color tokens, codicons, dock/panel constraints, dark/light parity). Load for Theia-based apps (e.g. bumbl-app). |
| | **Quarkus** | Quarkus deps | `references/quarkus.md` | | ||
| | **Kafka / messaging** | Kafka in the feature | `references/spring-kafka.md` | | ||
| | **HMRC MTD** (UK tax API) | HMRC / Making Tax Digital in the feature | `references/hmrc-api/overview.md` | | ||
| | **Rust** (tokio/axum daemons) | `Cargo.toml`, `.rs` sources (e.g. bumbl-dis) | `references/rust.md` | |
Comment on lines
+1
to
+4
| # Architecture Reference — Eclipse Theia Platform | ||
|
|
||
| > Loaded by /arch (Jorge) when making architecture decisions for a Theia-based IDE product (e.g. **bumbl-app**): process topology, extension model, where external service clients live, MCP integration, packaging/update, and upgrade strategy. | ||
|
|
Comment on lines
+1
to
+5
| # Design Reference — Designing within Eclipse Theia | ||
|
|
||
| > Loaded by /ui (Aura) when designing panels, widgets, chat surfaces, modals, or theming for a Theia-based IDE product (e.g. **bumbl-app**). Theia is a VS Code-workbench-style shell: design *within* its layout and token system, not against it. | ||
|
|
||
| ## Trigger |
Comment on lines
+1
to
+4
| # Backend Stack — Rust (tokio + axum) | ||
|
|
||
| > Loaded by /be for Rust backend work — above all the **bumbl-dis** intelligence daemon (`~/git/workspace/bumbl-dis`): tokio + axum HTTP/WS/SSE, JSON-RPC dispatch, rusqlite on a dedicated thread, streaming to the Anthropic Messages API. Patterns below cite the real bumbl-dis code; follow them rather than inventing parallel ones. | ||
|
|
Comment on lines
+1
to
+4
| # Frontend Stack — Eclipse Theia | ||
|
|
||
| > Loaded by /fe when the project is a Theia-based IDE product (Theia deps in package.json, `theiaExtensions` field, `applications/electron` + `extensions/*` monorepo — e.g. **bumbl-app**). The Theia extension-development playbook. | ||
|
|
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
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.
Problem
The framework had roles but no shared account of how work is decided, checked and paid for. Three consequences showed up in real use:
/smwas defined as "the conductor of the orchestra — every agent reports to you". That is unfalsifiable, so nothing ever contradicted it, and in practice it was never invoked.What changed
Five cross-cutting process skills.
fid-lifecycle,verify-landed,review-tier,model-selection,research-method. They self-trigger from their descriptions and are listed in the roster andclaude/CLAUDE.md.Two are worth calling out because they encode failures that actually happened:
verify-landed— a green build is not evidence a change exists. Removing nothing breaks nothing, so an edit that matched nothing still compiles and passes every test. Also: never cite a comment as evidence a mechanism exists.review-tier— on a follow-up review round, review the fix and the prior findings, not the whole PR again. Two consecutive rounds on one PR each found regressions introduced by the previous round's fixes; the fresh fix is the riskiest code in the repository./smre-scoped from ceremony to board integrity. Six checks with checkable answers — orphan work items, plan-vs-tracker divergence, backlog items whose work has moved on, Done-without-negative-criteria, parked-without-a-trigger, epics claiming completion over open children. Output is counts and named items, never "the board is healthy".references/board-integrity.mdalso replaces the scheduled retrospective with continuous capture, because the durable lessons are found mid-work and a fortnightly retro recovers none of them.answer-audit— adversarially verify a retrieval-grounded answer. Targets what a grounding judge structurally cannot catch: an answer minus its qualifier is still entailed by its sources./ext— Browser Extension Developer, plus Theia references for/arch,/ui,/feand a Rust reference for/be..gitignorenow covers.praxis/,.aidevteam/anddocs/archive/. This repository is public and the archived transcripts carry product strategy and private-project detail; they must not be published.Tests
Documentation and skill definitions only — no executable code. Verified: every skill has valid frontmatter with a trigger-rich
description; the roster,claude/CLAUDE.mdandCHANGELOG.mdagree on what exists; no private-project references, credentials, host addresses or commercial material in anything added (scanned before commit).