peer-notebook-delivery-guard
Skill64 starsChanged 5 months agoMITView on GitHub
Govern ADR-022 MCP peer notebook implementation units. Use before or during durable control-plane, manifest lifecycle, web app inspection, runtime provider, or isolation/policy hardening work to prevent mock substitution, scope drift, and incomplete acceptance evidence.
In this repository102 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- assumptionsSkill
- capture-learningSkill
- Codex-opus-4-6-promptingSkill
- Codex-promptSkill
- mcp-code-modeSkill
- deploy-team-hubSkill
- diagramSkill
- distillSkill
- effect-tsSkill
- escalateSkill
- evalSkill
- experimentSkill
- hddSkill
- hub-auditSkill
- hub-collabSkill
- implementSkill
- knowledgeSkill
- research-taskSkill
- session-reviewSkill
- source-command-hdd-decideSkill
- source-command-hdd-hddSkill
- source-command-hdd-researchSkill
- source-command-hdd-stage-adrSkill
- source-command-hdd-validateSkill
- statusSkill
- supabaseSkill
- synthesizeSkill
- tasteSkill
- teamSkill
- test-suiteSkill
- theseus-protocolSkill
- thoughtbox:debugSkill
- thoughtbox:decisionSkill
- thoughtbox:evolutionSkill
- thoughtbox:knowledge-querySkill
- thoughtbox:onboardSkill
- thoughtbox:refactorSkill
- thoughtbox:researchSkill
- thoughtbox:session-reviewSkill
- thoughtbox-teamSkill
- ulc-loopSkill
- ulysses-protocolSkill
- workflow-brainstormingSkill
- workflow-ideationSkill
- workflow-reflectionSkill
- workflow-revisionSkill
- workflows-compoundSkill
- workflowSkill
- workflows-planSkill
- workflows-reviewSkill
- workflows-workSkill
- workflow-tournamentSkill
- assumptionsSkill
- capture-learningSkill
- claude-opus-4-6-promptingSkill
- claude-promptSkill
- mcp-code-modeSkill
- deploy-team-hubSkill
- The first 60 shown.
The file
Show its rules and text
We split this skill into the rules it gives an agent
18 rules. About 0 are common, 12 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈12
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 28
Use this skill whenever work touches .specs/mcp-peer-notebooks/, .specs/mcp-peer-notebooks/SPEC-CONTROL-PLANE.md, src/peer-notebook/, peer …
- Distinctive: line 34
Read these before planning or editing:
- Very specific: line 42
If the work touches app UI, also read apps/web/AGENTS.md.
- Distinctive: line 52
Before any unit is complete, every mocked or in-memory component touched must be either:
- Distinctive: line 59
If a mock fulfills the function of the thing it mocks in a final acceptance claim, the unit is not complete.
- Distinctive: line 75
If work crosses a unit boundary, stop and record/link follow-up work in the user-selected tracker or handoff artifact before proceeding.
- Distinctive: line 81
Write a short classification before editing:
- Distinctive: line 93
If there is no tracker reference and tracker writes are in scope, create or request one.
- Distinctive: line 97
Every unit must have observable acceptance criteria before implementation:
- Distinctive: line 106
Avoid acceptance phrased only as "implemented support for X."
- Distinctive: line 110
Before code review or completion, produce this table:
- Very specific: line 121
If Deferred, the follow-up issue is mandatory.
- Very specific: line 122
If the unit claims final acceptance for a capability, the corresponding row cannot be mock, in-memory, or stub.
- Distinctive: line 211
Add real implementations beside mocks.
- Distinctive: line 213
Keep deferred surfaces deferred unless this unit explicitly owns them.
- Very specific: line 214
Update .specs/ and ADR artifacts in the same commit as behavior changes.
- Distinctive: line 215
Do not touch unrelated dirty files.
- Very specific: line 236
If Ready for PR/merge is yes, there must be no untracked mock replacement work hidden in prose.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Guard MCP peer notebook delivery for: $ARGUMENTS
Purpose
This skill is the delivery guardrail for ADR-022. It keeps large implementation units aligned with the brokered peer notebook end state:
- governed peer identities
- approved manifests
- brokered inbound invocation
- broker-proxied outbound access
- durable invocations, traces, and artifacts
- web-app inspection
- real runtime providers behind explicit contracts
Use this skill whenever work touches .specs/mcp-peer-notebooks/,
.specs/mcp-peer-notebooks/SPEC-CONTROL-PLANE.md, src/peer-notebook/, peer notebook Supabase
migrations, peer notebook web app routes, or runtime providers.
Required Reads
Read these before planning or editing:
AGENTS.md.specs/mcp-peer-notebooks/SPEC-CONTROL-PLANE.md.specs/mcp-peer-notebooks/SPEC-CONTROL-PLANE.md.specs/mcp-peer-notebooks/README.md.specs/mcp-peer-notebooks/NEXT-IMPLEMENTATION-HANDOFF.md
If the work touches app UI, also read apps/web/AGENTS.md.
Hard Rule
Mocks are contract fixtures, not final substitutes.
A mock, in-memory store, stubbed provider, fake broker target, or local-only stand-in may prove shape, schema, trace semantics, and client reachability. It does not satisfy the production requirement for the capability it represents.
Before any unit is complete, every mocked or in-memory component touched must be either:
- replaced by a real implementation behind the same contract,
- narrowed to test-only/non-production use by code and docs, or
- explicitly deferred in the user-selected tracker or handoff artifact with the real replacement named.
If a mock fulfills the function of the thing it mocks in a final acceptance claim, the unit is not complete.
Large Unit Boundaries
Pick exactly one primary unit unless the user explicitly asks for a larger combined effort.
| Unit | Capability Produced | Explicit Non-Goals |
| Durable Control Plane | Supabase-backed peers, manifests, invocations, traces, and artifacts while runtime remains mock-capable | Web app pages, real runtime isolation |
| Manifest Lifecycle And Notebook Graduation | Compile peer.manifest.json from real notebook source, store drafts, approve/activate/retire manifests | Runtime provider expansion, UI beyond minimal admin/read APIs |
| Web App Inspection Surface | Peer registry/detail, invocation list/detail, trace timeline, artifact preview from durable rows | New runtime providers, migration redesign |
| Real Runtime Provider Path | local-process integration provider behind runtime contract, marked development-only | Production isolation claims |
| Production Isolation And Policy Hardening | Isolated execution provider, enforced network/filesystem/secrets/budget policy, adversarial acceptance | Treating local-process or mock as production |
If work crosses a unit boundary, stop and record/link follow-up work in the user-selected tracker or handoff artifact before proceeding.
Workflow
1. Classify The Unit
Write a short classification before editing:
Unit:
ADR claims advanced:
Spec sections touched:
Production capability expected:
Mocks/in-memory components involved:
Explicit non-goals:
Tracker/handoff reference:If there is no tracker reference and tracker writes are in scope, create or request one. If tracker writes are unavailable, record the gap in the handoff and do not create a fallback tracker.
2. Define Acceptance Before Code
Every unit must have observable acceptance criteria before implementation:
- positive path
- negative path
- workspace scoping path where relevant
- trace/artifact/read-model evidence where relevant
- mock accountability outcome
Acceptance must name concrete files, rows, API responses, UI states, or tests. Avoid acceptance phrased only as "implemented support for X."
3. Mock Accountability Gate
Before code review or completion, produce this table:
| Component | Real Capability It Stands In For | Current Scope | Replaced/Narrowed/Deferred | Tracker/Handoff Follow-Up |
MockPeerRuntimeProvider | Runtime execution provider | test/pilot | deferred | thoughtbox-... |
Rules:
Current Scopemust betest-only,pilot-only,development-only, orproduction.productionis allowed only for real implementations.- If
Deferred, the follow-up issue is mandatory. - If the unit claims final acceptance for a capability, the corresponding row
cannot be
mock,in-memory, orstub.
4. Unit Failure-Mode Gates
Apply only the gate for the active unit.
Durable Control Plane
Reject the unit if:
- schema names drift from
SPEC-CONTROL-PLANE.mdwithout a spec update - workspace scoping is not tested
- in-memory repository remains the only implementation
- trace or artifact writes can partially succeed without visible status/error
- durable seed -> invoke -> trace -> artifact flow is untested
Required evidence:
- migration files
- repository contract tests against Supabase-shaped storage
- verification query or test proving invocation, trace, and artifact rows exist
Manifest Lifecycle And Notebook Graduation
Reject the unit if:
- compiling a manifest executes notebook code
- draft manifests can be invoked
- notebook edits silently change active capabilities
- manifest hash is unstable across equivalent JSON
- approval/activation can be bypassed
Required evidence:
- malformed JSON, duplicate manifest, draft, active, retired, and expansion denial tests
- active manifest hash asserted during invocation
Web App Inspection Surface
Reject the unit if:
- UI reads mock/local state instead of durable rows
- denied calls are hidden
- artifact previews fetch unbounded full payloads
- workspace filtering is not represented in query tests or fixtures
src/observatorybecomes a deployed dependency
Required evidence:
- browser or component tests for peer detail, invocation detail, denied event, and artifact preview states
Real Runtime Provider Path
Reject the unit if:
local-processis described as production isolation- provider behavior diverges from mock contract tests
- runtime can bypass broker proxy for Thoughtbox/MCP calls
- runtime writes final artifacts outside broker-owned artifact paths
- timeout/cancel/failure transitions are ambiguous
Required evidence:
- shared provider contract tests
- explicit development-only labeling for local-process
- queued -> running -> terminal status tests
Production Isolation And Policy Hardening
Reject the unit if:
- Cloud Run becomes the privileged execution host
- network, filesystem, secrets, or outbound tool policy is doc-only
- budget counters are not enforced and traceable
- denied outbound calls can reach the target
- mock or local-process satisfies production isolation acceptance
Required evidence:
- adversarial tests for denied network/tool/filesystem/secrets access
- isolated provider end-to-end acceptance
- persisted budget and denial trace events
5. Implementation Discipline
- Preserve broker/repository/runtime contracts unless the ADR/spec changes.
- Add real implementations beside mocks; do not mutate mocks into production implementations.
- Keep deferred surfaces deferred unless this unit explicitly owns them.
- Update
.specs/and ADR artifacts in the same commit as behavior changes. - Do not touch unrelated dirty files.
6. Completion Report
End with:
Peer Notebook Delivery Guard Report
Unit:
Tracker/handoff reference:
ADR/spec alignment:
Mocks touched:
Mock accountability:
Acceptance evidence:
Tests run:
Deferred issues filed:
Known risks:
Ready for PR/merge: yes|noIf Ready for PR/merge is yes, there must be no untracked mock replacement
work hidden in prose.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

