5
Already there
Standing instructions and remembered context visible before this job begins.
What shapes your AI
Most people build this setup a rule at a time without realizing they are building a system. Here is the part this review could see.
36
How it chooses help
Skills and routes that may make specialist help eligible.
633
What joins this job
Prompts, references, and task context that may join a particular run.
100
What it can do
Tools, settings, permissions, and action boundaries.
6
What proves it is done
Checks, validators, and evidence that can test the finish line.
What is helping
These parts protect the work or give the AI useful context. The audit recommends keeping them.
Workspace instructions (CLAUDE.md)
Loads at the start of every session in this folder and pulls in the universal rules and the BiV operating manual.
Why it stays: This is the entry point of the whole instruction chain. It is short, current, and was observably supplied to the session running this review.
BiV operating manual (.claude/biv.md)
The single home for BiV-specific rules: git flow, hard stops, task capture, and how to navigate the wiki and live data.
Why it stays: One owner, one home, imported by the workspace and by each BiV repo. It carries the safety boundaries (hard stops, sensitive-path gate) that protect client-facing surfaces.
Shared tool permissions (settings.json)
Grants broad tool access (shell, read, write, edit, web) plus two plugins, so agents work without permission prompts.
Why it stays: The broad grant is a deliberate autonomy posture; the real boundaries live in the hard stops and the sensitive-path CI gate, not in per-tool prompts. Consistent with the documented autonomy model.
Local settings (settings.local.json)
Enables the MCP servers this machine uses and sets the Proactive output style.
Why it stays: Machine-local switches that match the servers actually configured; nothing stale found in it.
MCP server catalog (.mcp.json)
Declares the project MCP servers that the local settings then enable.
Why it stays: The enabled-server list in local settings matches this catalog's role; no conflict signals were observed.
biv-workspace skill (Claude copy)
The workspace rules that GSD subagents load: naming, verification, safety, commit conventions.
Why it stays: It is the accurate, current version and the source the Codex-side copy was derived from.
fact-checker agent (Claude copy)
Defines the fact-checker subagent available to sessions here.
Why it stays: It is the original; the Codex file is a format translation of the same text.
Sensitive-path approval gate (CI workflow)
Routes PRs that touch sensitive paths to a one-tap approval instead of auto-merge.
Why it stays: The operating manual names this workflow as the source of truth for the per-repo sensitive set. It is the hard check that makes the broad autonomy grant safe.
What may be getting in the way
These are not automatically bad. They are the places where old rules, duplication, early loading, or soft requirements may be making the setup harder to use.
Codex mirror entry (AGENTS.md)
A Codex-facing copy of the workspace instructions. Its import points at .Codex/biv.md, a file that does not exist, so a Codex session loads a broken chain.
biv-workspace skill (Codex copy)
A near-copy of the Claude biv-workspace skill with find-and-replace damage: it tells agents about a commands directory and process names that do not exist.
fact-checker agent (Codex translation)
A TOML translation of the Claude fact-checker agent, currently in sync apart from format.
Stale worktree: wiki-cloud-compute (715 duplicated controls)
A full second copy of the workspace lives at .claude/worktrees/wiki-cloud-compute. 715 of the 780 controls this scan found are duplicates inside it, and every future scan, search, and agent sweep pays that tax.
Shipped plan: ai-digest skill (Jun 7)
A completed implementation plan for the ai-digest skill, which now exists and runs.
Shipped spec: ai-digest design (Jun 7)
The design spec companion to the shipped ai-digest plan.
What this model needs
Claude and Codex do not expose or use the surrounding setup in exactly the same way. These recommendations are specific to the product and model this review could identify.
Run the next cleaning pass against the user-level Claude configuration, not this workspace.
On this surface the per-session token and attention cost is dominated by what auto-loads everywhere, so cleaning the user layer would touch every session in every repo, whereas this workspace is already lean once the stale worktree is gone.
Evidence: VERIFIED — This workspace contributes only a short instruction chain to each session, while the session context shows the always-loaded bulk (global instructions, memory index, and a very large skill catalog) comes from the user level, which this scan could not reach.
Keep generated references generated; never hand-edit them between regenerations.
This setup already has both patterns side by side, and the generated one stayed correct while the hand-copied one broke; extending the generator pattern to the Codex mirror is the fix this review proposes.
Evidence: VERIFIED — The Airtable schema key in this workspace regenerated the same day as this review and carries a do-not-hand-edit header, while the hand-made Codex mirror copies drifted into false statements within weeks.
What I recommend
Nothing below has been changed. Each number is a separate choice.
Give it one home
Codex mirror entry (AGENTS.md)
Declare the Claude files (CLAUDE.md and .claude/biv.md) the only owners. Regenerate this mirror from them mechanically with correct lower-case paths and a real biv.md target, or remove the mirror if Codex sessions no longer run in this folder. Rejecting this item keeps the file exactly as it is.
Why: The file was produced by a blind find-and-replace (claude to Codex) that also broke its one import; verified by reading it and confirming the imported file is absent. Two drifting copies of the operating rules is duplicated ownership.
What this protects
Must survive: The Claude-side instruction chain stays untouched; only the derived copy changes.
Risk if wrong: If a Codex workflow depends on the current text as-is, regeneration could change its behavior; the git history preserves the old text.
Undo: Restore the previous file from git history.
Give it one home
biv-workspace skill (Codex copy)
Same treatment as the Codex mirror entry: regenerate mechanically from the Claude copy (translating only what Codex genuinely needs), or remove it with the rest of the mirror if Codex is unused here. Rejecting keeps it as-is.
Why: A line-by-line comparison against the Claude copy shows only mechanical claude-to-Codex substitutions, several of which produced false statements (a .Codex commands path, killing Codex processes).
What this protects
Must survive: The Claude copy remains the single accurate source.
Risk if wrong: A Codex agent might currently rely on the file despite the errors; git history preserves it.
Undo: Restore the previous file from git history.
Give it one home
fact-checker agent (Codex translation)
Record the Claude file as owner and regenerate this translation from it whenever the owner changes, instead of editing both by hand. No text change is needed today.
Why: The two files carry the same agent text in two formats; without a declared owner they will drift the first time one is edited alone.
What this protects
Must survive: The Claude original as the single edited source.
Risk if wrong: Minimal; the proposal changes process, not content.
Undo: Not applicable today; future regenerations are reversible via git history.
Retire it safely
Stale worktree: wiki-cloud-compute (715 duplicated controls)
Remove the registered worktree with git worktree remove, and run git worktree prune to clear two other already-deleted registrations. The branch it holds is clean, fully pushed, and open as PR 181, so no work is lost. Note: PR 181 has sat open since early July even though routine PRs auto-merge; worth checking why it never merged.
Why: Verified with read-only git commands: the worktree's tree is clean, its branch is up to date with its remote, and its commit is not yet merged. The operating rules say branch work happens in ephemeral worktrees, which this one has outlived.
What this protects
Must survive: The pushed branch and PR 181 remain on the remote untouched.
Risk if wrong: If someone intended to resume work inside this exact worktree, they would need to recreate it (one command).
Undo: Recreate with: git worktree add .claude/worktrees/wiki-cloud-compute docs/86barf48x-cloud-compute
Retire it safely
Shipped plan: ai-digest skill (Jun 7)
Delete the file in a normal PR (git history is the archive). Consider sweeping the rest of docs/superpowers/plans and specs the same way: the sibling documents cover work that also appears shipped (BEF v3, client relations).
Why: The skill it plans is live in the skill catalog, and the workspace instructions say not to let planning artifacts accumulate. The operating manual's own rule is that dead artifacts are removed, not archived in folders.
What this protects
Must survive: Git history, which preserves the full document.
Risk if wrong: If the plan contains still-unshipped tail items, deleting hides them; skim before approving.
Undo: Restore the file from git history.
Retire it safely
Shipped spec: ai-digest design (Jun 7)
Delete alongside the plan in the same PR.
Why: Same evidence as the plan: the feature is live and the document is a completed planning artifact.
What this protects
Must survive: Git history, which preserves the full document.
Risk if wrong: Same as the plan; skim for unshipped tail items before approving.
Undo: Restore the file from git history.
Reply in chat: Approve 1 and 3. Leave 2. You can also approve one item at a time or leave everything alone.
What I could not see
This keeps the report honest. A missing item is a limit of the review, not proof that it does not exist.
- hidden-product-controlsHidden system instructions, product routing, account memory, and unexported settings were not visible.
- runtime-traceNo trace showed which controls were eligible, shown, consulted, acted through, checked, or accepted for a real job.
- behavioral-effectStatic presence and text signals do not prove that a control helps or harms the work.
- excluded-pathsSome paths were deliberately excluded for privacy, safety, traversal, or relevance limits.
- file-errors1 candidate file event(s) could not be fully inspected; see 00-scope-and-coverage.json.
- stale worktree duplicates714 unreviewed controls are copies inside the stale worktree at .claude/worktrees/wiki-cloud-compute (its own instruction files, planning archives, wiki, and tool configs). They were not reviewed individually because the single retirement change for that worktree addresses all of them at once.
- wiki knowledge layerAbout 38 wiki pages (mostly per-tool reference pages) were not reviewed individually. They load at the point of need by design and dedicated wiki audit tooling already exists to verify their accuracy against the live system, so a harness review adds little on top.
- planning tool artifactsMilestone archives and audit data under .planning belong to the GSD planning tool, which ships its own cleanup command for archiving completed milestones. They were inventoried but not semantically reviewed here.
- user-level Claude configurationThe scan covered this workspace only. The largest always-loaded surface actually lives at the user level outside this folder: the global instruction file, the persistent memory index, and a catalog of roughly two hundred skills whose descriptions load every session. Reviewing that layer needs a separate run against the user configuration directory.
- runtime loadingNo product trace shows which controls a real session loads or consults. The session running this review observably received the workspace instruction chain and the memory index, but per-skill and per-wiki-page loading is not exposed, so load-timing claims stay inferred.
- symlinked contentThe scanner does not follow symlinks, so the linked scripts directory and two symlinked skill files were inventoried as exclusions only. Their targets live outside this workspace and were not reviewed.