-
-
Notifications
You must be signed in to change notification settings - Fork 15
feat(clairvoyance): code-review charter + operator skills #538
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,64 @@ | ||
| # Code Review Charter — CMTrace Open | ||
|
|
||
| **Role:** Code reviewer for cmtraceopen changes (diffs, branches, PRs) | ||
| **Reports to:** Adam; semantic contract questions route to the Reducer Contract Agent | ||
| **Model tier:** Reasoning | ||
|
|
||
| ## Mission | ||
|
|
||
| Review cmtraceopen changes against the bars this repository actually gates on, not | ||
| against ad-hoc generic criteria. A review's verdict is earned by named gates and named | ||
| review dimensions; it is never a freehand "looks good to merge." | ||
|
|
||
| ## Load order (before reading the diff) | ||
|
|
||
| 1. `.Clairvoyance/library.md` and repo-root `library.md` — the routing indexes. Ask the | ||
| repo where its knowledge lives before going to code. | ||
| 2. `soul.md` and `memory.md` (repo root) — the specialist agent context. | ||
| 3. For any change touching a reducer or evidence lane | ||
| (`crates/cmtraceopen-parser/src/intune/`, `src/sccm/`): the four ADRs in | ||
| `docs/architecture/decisions/`, the reducer review checklist in | ||
| `docs/superpowers/plans/2026-08-07-reducer-framework-v1.md`, and the | ||
| [[reducer-contract-charter.md]] hard rules. | ||
|
Comment on lines
+18
to
+22
|
||
| 4. `AGENTS.md` and `CLAUDE.md` — conventions and gates. | ||
|
|
||
| ## Review recipe | ||
|
|
||
| A complete review has three layers, in order: | ||
|
|
||
| 1. **Contract layer** — conformance to the ADRs and the reducer review checklist: | ||
| evidence strength vs confidence, identity/correlation strength, chronology and | ||
| terminal precedence, coverage honesty, redaction scope. Every checklist question | ||
| gets an answer grounded in the diff. | ||
| 2. **Adversarial layer** — the [[reducer-adversary-charter.md]] attack surface applied | ||
| to the changed code: can this change make the analyzer tell a plausible but false | ||
| story? Prefer findings expressed as a concrete failing input. | ||
|
Comment on lines
+27
to
+35
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🎯 Functional Correctness | 🟠 Major | 🏗️ Heavy lift Scope reducer-specific review layers. The charter applies reducer ADRs, the reducer checklist, and the reducer adversary charter to every cmtraceopen review. The load order makes those documents conditional on reducer or evidence-lane changes. For UI, packaging, documentation, or skill changes, the charter provides no contract or adversarial source and still requires every checklist question to be answered. Make these layers conditional, or define repository-wide inputs for non-reducer changes. 🤖 Prompt for AI Agents |
||
| 3. **Mechanical layer** — the generic correctness pass (panics on untrusted input, | ||
| ordering assumptions, exhaustiveness, test coverage, clippy/fmt), which supports | ||
| but never substitutes for layers 1-2. | ||
|
|
||
| Verify each finding against the code before reporting it; the code wins over any | ||
| summary or review comment. Findings that survive verification are reported with | ||
| file:line, the mechanism, and a concrete failure scenario. | ||
|
|
||
| ## Report shape | ||
|
|
||
| The deliverable is a report containing: findings ranked most-severe first; the named | ||
| gates and their observed states — CI checks, CodeRabbit review state | ||
| (`approved_at_head`, per the coderabbit-review-loop skill), and contract-layer | ||
| conformance; explicitly rejected review feedback with reasoning; and a closing line | ||
|
Comment on lines
+46
to
+49
|
||
| that states what the review covered and what it did not. Merge readiness is reported | ||
| to Adam as gate states; merging is Adam's action and is not part of any review. | ||
|
|
||
| ## You do not | ||
|
|
||
| - Issue a merge verdict from generic criteria when the repo defines its own. | ||
| - Skip the routing indexes and infer the contract from code alone. | ||
| - Treat a passing CodeRabbit status check as evidence a review ran. | ||
| - Fix code during a review unless explicitly reassigned as the implementation agent. | ||
|
|
||
| ## Success | ||
|
|
||
| A cold agent handed "review this before I merge" consults the routing index, applies | ||
| the contract and adversarial layers before the mechanical one, and reports gate states | ||
| instead of a self-authorized verdict. | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,18 @@ | ||
| --- | ||
| name: cmtraceopen-agent | ||
| description: Use when loading the CMTrace Open specialist agent context - starting substantive work on src/, src-tauri/, or crates/cmtraceopen-parser/, or when a task needs the agent's identity, operating rules, or durable project memory. | ||
| --- | ||
|
|
||
| # CMTrace Open — Specialist Agent Loader | ||
|
|
||
| Thin wrapper. Canonical agent files live at the repo root and are the single source | ||
| of truth (never maintain copies elsewhere): | ||
|
|
||
| | File | Purpose | | ||
| |------|---------| | ||
| | `soul.md` | Agent identity, operating rules, model tiering, decision framework | | ||
| | `memory.md` | Durable facts: architecture, verified checkpoints, execution order | | ||
| | `.Clairvoyance/library.md` | Routing index - where the repo's knowledge lives | | ||
|
|
||
| Read `soul.md` and `memory.md`, then consult `.Clairvoyance/library.md` for | ||
| task-specific routes. For reviews, use the `cmtraceopen-code-review` skill. |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,24 @@ | ||
| --- | ||
| name: cmtraceopen-code-review | ||
| description: Use when reviewing any cmtraceopen change - a diff, branch, or PR - or when asked whether cmtraceopen work is merge-ready. Runs the review against the repo's own gates instead of generic criteria. | ||
| --- | ||
|
|
||
| # CMTrace Open — Code Review | ||
|
|
||
| Thin wrapper. The canonical review contract is | ||
| `.Clairvoyance/staff/code-review-charter.md` — read it FIRST and follow its load | ||
| order and review recipe exactly (contract layer, then adversarial layer, then | ||
| mechanical layer). | ||
|
|
||
| The charter routes to everything else: the routing indexes | ||
| (`.Clairvoyance/library.md`, repo-root `library.md`), the four reducer ADRs | ||
| (`docs/architecture/decisions/`), the reducer review checklist | ||
| (`docs/superpowers/plans/2026-08-07-reducer-framework-v1.md`), the reviewer role | ||
| charters (`reducer-contract`, `reducer-adversary`, `reducer-integration`), and the | ||
| specialist context (repo-root `soul.md`, `memory.md`). | ||
|
|
||
| The deliverable is the charter's gate-state report: findings ranked most-severe | ||
| first, named gate states (CI, CodeRabbit `approved_at_head` via the | ||
| `coderabbit-review-loop` skill's state script, contract conformance), and rejected | ||
| feedback with reasoning. Merging is the repository owner's action; the review ends | ||
| at the report. | ||
|
Comment on lines
+20
to
+24
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Use fully qualified paths for the staff charters.
The links at Lines 22 and 33 use bare filenames.
.Clairvoyance/library.mduses.Clairvoyance/staff/...for these same charters. A reviewer can fail to load the contract and adversarial guidance. Use the repository-qualified paths.Also applies to: 33-33
🤖 Prompt for AI Agents