convene-cli 1.2.0 → 1.3.0

package/dist/catalog/catalog.generated.js

@@ -0,0 +1,860 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CATALOG_VERSION = exports.CATALOG = void 0;
+exports.CATALOG = {
+    "version": "1.0.0",
+    "tiers": [
+        {
+            "id": "essentials",
+            "name": "Essentials",
+            "description": "The tight consensus core every participating repo should adopt. Confirmed by Anthropic docs, practitioner consensus, and Convene’s own production experience. Low-friction, high-signal, mostly advisory-with-one-hard-gate. Default ON. If a repo adopts nothing else, it should adopt these."
+        },
+        {
+            "id": "recommended",
+            "name": "Recommended",
+            "description": "Strong consensus practices that materially improve reliability and team coordination but carry slightly more setup or behavioral cost (verification gates, worktree isolation, small rebased branches, subagent hygiene). Default ON for teams; opt-out per repo. These are where Convene’s coordination bus adds the most leverage."
+        },
+        {
+            "id": "advanced",
+            "name": "Advanced",
+            "description": "High-leverage but higher-variance or higher-overhead practices for mature teams running many concurrent agents (merge queues, sandboxed YOLO mode, headless fan-out, adversarial review subagents, policy-as-code enforcement). Default OFF; opt-in deliberately. Several are contested or context-dependent and are marked low-confidence where the research disagrees."
+        }
+    ],
+    "categories": [
+        "Instruction Files (CLAUDE.md / AGENTS.md)",
+        "Verification & Quality Gates",
+        "Workflow Discipline (Plan / Explore / Commit)",
+        "Context Management",
+        "Parallel & Multi-Session Coordination",
+        "Git & Integration Hygiene",
+        "Permissions & Sandboxing",
+        "Subagents & Delegation",
+        "Catalog Governance & Distribution"
+    ],
+    "practices": [
+        {
+            "id": "claude-md-lean",
+            "version": "1.0.0",
+            "title": "Keep CLAUDE.md short, specific, and pruned (< ~200 lines)",
+            "category": "Instruction Files (CLAUDE.md / AGENTS.md)",
+            "tier": "essentials",
+            "what": "Cap the always-loaded CLAUDE.md at ~200 lines (start nearer 60). For each line ask \"would removing this cause a mistake? if not, cut it.\" Keep only what the agent cannot infer from code (non-guessable commands, style deltas, test runners, gotchas); link out for API docs. Write verifiable rules, pair every prohibition with a positive alternative, and reserve IMPORTANT/YOU MUST for the rare load-bearing rule.",
+            "why": "CLAUDE.md loads in full every turn and instruction-following degrades as it fills — a bloated file buries the rules that matter and makes louder emphasis useless. Unnecessary requirements measurably harm agent performance (Gloaguen et al. 2026: >20% inference-cost increase). A tight file is the single highest-signal lever.",
+            "defaultLevel": "ci",
+            "availableLevels": [
+                "advisory",
+                "ci"
+            ],
+            "optInDefault": "on",
+            "artifacts": [
+                {
+                    "kind": "claudeMd",
+                    "body": "Keep this file under ~200 lines. Before adding a line, ask \"would removing it cause a mistake?\" — if not, cut it.\nWrite verifiable rules; reserve IMPORTANT/YOU MUST for the rare load-bearing one; link out for API docs instead of inlining."
+                },
+                {
+                    "kind": "ci",
+                    "body": "Warn when CLAUDE.md / CLAUDE.local.md exceeds the line/token budget; flag overuse of IMPORTANT/YOU MUST, vague verbs (properly/cleanly/appropriately), and negation-only rules for human review. Advisory by nature — warn, do not hard-fail by default."
+                }
+            ],
+            "sourceUrls": [
+                "https://code.claude.com/docs/en/best-practices",
+                "https://code.claude.com/docs/en/memory",
+                "https://arxiv.org/abs/2602.11988"
+            ]
+        },
+        {
+            "id": "hooks-for-must-haves",
+            "version": "1.0.0",
+            "title": "Use hooks (not CLAUDE.md prose) for anything that must happen every time",
+            "category": "Verification & Quality Gates",
+            "tier": "essentials",
+            "what": "Any rule that must run at a fixed point — lint after every edit, block writes to protected paths, gate turn-completion on a passing build — becomes a hook in .claude/settings.json, not a sentence in CLAUDE.md. PreToolUse blocks before an action (exit 2 / deny); PostToolUse runs linters after edits; Stop gates turn completion. If the agent keeps violating a rule despite emphasis, convert it to a hook.",
+            "why": "CLAUDE.md and auto-memory are advisory context with no guarantee of compliance; hooks are deterministic regardless of what the agent decides. Anthropic: \"to block an action regardless of what Claude decides, use a PreToolUse hook.\" Encoding each correction as durable tooling means the same error class can’t recur after a context reset.",
+            "defaultLevel": "hook-hard",
+            "availableLevels": [
+                "advisory",
+                "hook-soft",
+                "hook-hard"
+            ],
+            "optInDefault": "on",
+            "artifacts": [
+                {
+                    "kind": "claudeMd",
+                    "body": "If a rule must run every time (lint after edits, block a path, gate turn-end on a green build), wire it as a hook in .claude/settings.json — do not restate it as prose here.\nWhen the agent keeps violating a rule despite emphasis, convert the rule to a hook."
+                },
+                {
+                    "kind": "settingsHook",
+                    "event": "PreToolUse",
+                    "matcher": "Write|Edit",
+                    "command": "convene practice-guard hooks-for-must-haves",
+                    "verb": "practice-guard"
+                }
+            ],
+            "sourceUrls": [
+                "https://code.claude.com/docs/en/hooks",
+                "https://code.claude.com/docs/en/best-practices"
+            ]
+        },
+        {
+            "id": "verify-before-ship",
+            "version": "1.0.0",
+            "title": "Always give the agent a runnable way to verify its own work",
+            "category": "Verification & Quality Gates",
+            "tier": "essentials",
+            "what": "Provide a machine-checkable pass/fail gate the agent can run and read: test suite, build exit code, linter, a fixture diff, or a screenshot compared to a design. State concrete success criteria, require the agent to run the check and iterate until green, and show evidence (command + output) rather than asserting success. Keep the verify command prominent in the instruction file; escalate the gate (in-prompt → Stop hook → CI) to fit the task.",
+            "why": "Claude stops when work \"looks done\"; without a check it can run, \"looks done\" is the only signal and you become the verification loop. This trust-then-verify gap is the most mechanically enforceable, highest-impact practice in the set — the single biggest factor in whether a session can run unattended.",
+            "defaultLevel": "hook-hard",
+            "availableLevels": [
+                "advisory",
+                "hook-soft",
+                "hook-hard",
+                "ci"
+            ],
+            "optInDefault": "on",
+            "artifacts": [
+                {
+                    "kind": "claudeMd",
+                    "body": "Before claiming work done, run the repo’s verify gate (test/build/lint) and iterate until green; show the command and its output as evidence.\nState concrete success criteria up front — do not rely on \"looks done\"."
+                },
+                {
+                    "kind": "settingsHook",
+                    "event": "Stop",
+                    "matcher": ".*",
+                    "command": "convene practice-guard verify-before-ship",
+                    "verb": "practice-guard"
+                }
+            ],
+            "sourceUrls": [
+                "https://code.claude.com/docs/en/best-practices",
+                "https://code.claude.com/docs/en/hooks",
+                "https://simonwillison.net/2026/Feb/23/agentic-engineering-patterns/"
+            ]
+        },
+        {
+            "id": "plan-mode-before-edits",
+            "version": "1.0.0",
+            "title": "Plan mode before edits (Explore → Plan → Implement → Commit)",
+            "category": "Workflow Discipline (Plan / Explore / Commit)",
+            "tier": "essentials",
+            "what": "For any non-trivial change, work read-only first: explore in plan mode (write tools blocked), produce a reviewable numbered plan, get it approved, then implement against the plan and commit with a descriptive message + PR. Skip planning only for one-sentence diffs. Plan most when the approach is uncertain, the change spans files, or the code is unfamiliar. In a multi-agent repo, post the plan to the bus before mutating the tree.",
+            "why": "Letting Claude jump straight to coding can solve the wrong problem — the costliest agentic failure is the wrong approach executed at scale. A read-only plan eliminates it cheaply and, in multi-session repos, makes intent legible to peers before any tree mutates. Production-learned at the BrightAI Opportunity Explorer; confirmed by Anthropic’s documented workflow.",
+            "defaultLevel": "hook-soft",
+            "availableLevels": [
+                "advisory",
+                "hook-soft"
+            ],
+            "optInDefault": "on",
+            "productionLearned": true,
+            "artifacts": [
+                {
+                    "kind": "claudeMd",
+                    "body": "For any multi-file or unfamiliar change, work read-only in plan mode first and get a numbered plan approved before editing.\nIn a multi-agent repo, post the plan with `convene post status` before mutating the tree."
+                },
+                {
+                    "kind": "settingsHook",
+                    "event": "PreToolUse",
+                    "matcher": "Write|Edit",
+                    "command": "convene practice-guard plan-mode-before-edits",
+                    "verb": "practice-guard"
+                }
+            ],
+            "sourceUrls": [
+                "https://code.claude.com/docs/en/best-practices",
+                "https://www.datacamp.com/tutorial/claude-code-plan-mode",
+                "https://harper.blog/2025/02/16/my-llm-codegen-workflow-atm/"
+            ]
+        },
+        {
+            "id": "manage-context-clear",
+            "version": "1.0.0",
+            "title": "Manage context aggressively: /clear between tasks; after 2 failed corrections, reset",
+            "category": "Context Management",
+            "tier": "essentials",
+            "what": "Treat the context window as the scarce resource. /clear between unrelated tasks (avoid the kitchen-sink session). If you’ve corrected the agent more than twice on the same issue, /clear and restart with a sharper prompt rather than piling corrections onto a polluted context. Use /compact or rewind for partial trims; preserve the modified-file list and test commands across compaction.",
+            "why": "Most agentic failures reduce to one constraint: context fills fast and performance degrades as it fills. A clean session with a better prompt almost always outperforms a long session with accumulated corrections.",
+            "defaultLevel": "advisory",
+            "availableLevels": [
+                "advisory"
+            ],
+            "optInDefault": "on",
+            "artifacts": [
+                {
+                    "kind": "claudeMd",
+                    "body": "Run /clear between unrelated tasks. After correcting the same issue twice, /clear and restart with a sharper prompt instead of piling on corrections."
+                }
+            ],
+            "sourceUrls": [
+                "https://code.claude.com/docs/en/best-practices",
+                "https://lucumr.pocoo.org/2025/6/12/agentic-coding/"
+            ]
+        },
+        {
+            "id": "catalog-marker-block-distribution",
+            "version": "1.0.0",
+            "title": "Distribute the catalog inside marker blocks, never via git add -A",
+            "category": "Catalog Governance & Distribution",
+            "tier": "essentials",
+            "what": "Write all catalog-managed content ONLY between stable markers (<!-- convene:begin --> … <!-- convene:end -->, with TOML/JSON equivalents) and stage ONLY the known CONVENE_PATHS in an isolated commit — never `git add -A`. Local edits outside the managed region always win; the updater edits only within markers. The protocol doc is written only if absent, never overwritten.",
+            "why": "If the updater overwrites whole files, local customizations are lost and teams stop adopting updates — the exact init-clobber footgun Convene already hit (clobbered .gitignore + protocol doc). Marked managed-regions with local-wins precedence are what make repeated automated updates safe and trusted. A hard prerequisite for everything else in the catalog.",
+            "defaultLevel": "ci",
+            "availableLevels": [
+                "advisory",
+                "ci"
+            ],
+            "optInDefault": "on",
+            "artifacts": [
+                {
+                    "kind": "ci",
+                    "body": "Fail if a catalog push would modify content outside the convene marker blocks, or stage any file not in CONVENE_PATHS. Implemented today by upsertMarkerBlock/removeMarkerBlock + the isolated CONVENE_PATHS commit; assert it in `convene doctor`."
+                }
+            ],
+            "sourceUrls": [
+                "https://docs.renovatebot.com/config-presets/",
+                "https://editorconfig.org/"
+            ]
+        },
+        {
+            "id": "worktree-per-session",
+            "version": "1.0.0",
+            "title": "One git worktree per concurrent session/agent",
+            "category": "Parallel & Multi-Session Coordination",
+            "tier": "recommended",
+            "what": "Run every concurrent agent session in its own git worktree (private HEAD/index/working files, shared object store), one per task. In Claude Code use `claude --worktree <name>`; gitignore .claude/worktrees/. Branch each worktree from fresh origin/HEAD. Copy gitignored config (.env, secrets) via a .worktreeinclude file and initialize deps/ports/test DB per worktree. Assign each session non-overlapping file boundaries before work begins.",
+            "why": "Without isolation, parallel agents in one checkout silently overwrite each other’s uncommitted edits, suffer context contamination, and hit .git/index.lock contention (confirmed work-loss in Claude Code #55724). Worktrees convert invisible runtime corruption into ordinary git conflicts. Production-learned at the BrightAI Opportunity Explorer; Convene’s session identity (member/<worktree-basename>) is built around it.",
+            "defaultLevel": "hook-soft",
+            "availableLevels": [
+                "advisory",
+                "hook-soft"
+            ],
+            "optInDefault": "on",
+            "productionLearned": true,
+            "artifacts": [
+                {
+                    "kind": "claudeMd",
+                    "body": "Run each concurrent session in its own git worktree (`convene worktree <branch>`), branched from fresh origin/HEAD, with non-overlapping file ownership.\nCopy gitignored config (.env) via .worktreeinclude; never run two agents in one checkout."
+                },
+                {
+                    "kind": "gitignore",
+                    "lines": [
+                        ".claude/worktrees/"
+                    ]
+                },
+                {
+                    "kind": "settingsHook",
+                    "event": "PreToolUse",
+                    "matcher": "Write|Edit",
+                    "command": "convene practice-guard worktree-per-session",
+                    "verb": "practice-guard"
+                }
+            ],
+            "sourceUrls": [
+                "https://code.claude.com/docs/en/worktrees",
+                "https://www.augmentcode.com/guides/git-worktrees-parallel-ai-agent-execution",
+                "https://github.com/anthropics/claude-code/issues/55724"
+            ]
+        },
+        {
+            "id": "pull-main-before-execution",
+            "version": "1.0.0",
+            "title": "Pull latest main after planning, before executing, then re-confirm the plan",
+            "category": "Git & Integration Hygiene",
+            "tier": "recommended",
+            "what": "Insert a re-sync step between Plan and Implement: once the plan exists but before the first edit, fetch and rebase onto latest origin/main (in the feature worktree, so main stays untouched), then re-validate the plan against the new HEAD — a concurrent session may have changed the files or interfaces it assumed. Re-validate again after any later sync/rebase.",
+            "why": "A plan is only valid against the tree it was formed on, and in multi-session repos that tree moves between plan and execution. Working at fresh HEAD and rebasing early converts a future merge/semantic conflict into a cheap pre-flight check. Production-learned at the BrightAI Opportunity Explorer.",
+            "defaultLevel": "hook-soft",
+            "availableLevels": [
+                "advisory",
+                "hook-soft"
+            ],
+            "optInDefault": "on",
+            "productionLearned": true,
+            "artifacts": [
+                {
+                    "kind": "claudeMd",
+                    "body": "After the plan is set but before the first edit, fetch and rebase onto origin/main, then re-validate the plan against the new HEAD.\nRe-validate again after any later rebase — the tree may have moved."
+                },
+                {
+                    "kind": "settingsHook",
+                    "event": "PreToolUse",
+                    "matcher": "Write|Edit",
+                    "command": "convene practice-guard pull-main-before-execution",
+                    "verb": "practice-guard"
+                }
+            ],
+            "sourceUrls": [
+                "https://code.claude.com/docs/en/worktrees",
+                "https://trunkbaseddevelopment.com/short-lived-feature-branches/"
+            ]
+        },
+        {
+            "id": "recheck-main-before-deploy-lane",
+            "version": "1.0.0",
+            "title": "Re-check main and reconfirm compatibility before claiming a deploy/merge lane",
+            "category": "Git & Integration Hygiene",
+            "tier": "recommended",
+            "what": "Right before merge or deploy, re-verify against current mainline and test the combined result — the change rebased onto current HEAD plus anything already ahead in the lane — not the branch in isolation. If behind, rebase (or pull --rebase) and re-run the check. In Convene, claim the deploy lane and let the gate compat-check fast-forwardability; if the bus health line says DEGRADED, re-fetch before acting.",
+            "why": "Two changes can each pass CI alone yet break main when landed back-to-back, because the second was tested against a base that no longer exists — a semantic conflict per-branch CI misses (\"A plus B can still be red\"). Rebasing repairs text but not architectural sense, so the combined state must be re-validated at claim time. Production-learned; maps onto Convene’s gate-push deploy-lane CAS + compat check.",
+            "defaultLevel": "hook-hard",
+            "availableLevels": [
+                "advisory",
+                "hook-soft",
+                "hook-hard"
+            ],
+            "optInDefault": "on",
+            "productionLearned": true,
+            "artifacts": [
+                {
+                    "kind": "claudeMd",
+                    "body": "Before merge/deploy, rebase onto current origin/main and re-run the verify gate on the combined result — not the branch in isolation.\nClaim the deploy lane via `convene deploy`; if the health line reads DEGRADED, re-fetch before acting."
+                },
+                {
+                    "kind": "settingsHook",
+                    "event": "PreToolUse",
+                    "matcher": "Bash",
+                    "command": "convene practice-guard recheck-main-before-deploy-lane",
+                    "verb": "practice-guard"
+                }
+            ],
+            "sourceUrls": [
+                "https://www.aviator.co/blog/what-is-a-merge-queue/",
+                "https://ctx.rs/blog/merge-queue-for-agents/"
+            ]
+        },
+        {
+            "id": "small-rebased-branches",
+            "version": "1.0.0",
+            "title": "Small, single-purpose, frequently-rebased branches",
+            "category": "Git & Integration Hygiene",
+            "tier": "recommended",
+            "what": "One logical change per branch, alive ~1–2 days, rebased onto trunk early and often; split larger work into a stack of small dependent diffs reviewed and merged independently. Keep trunk always-green: integrate small changes frequently, test after every commit, revert breakage immediately. Enable git rerere to auto-reapply recurring conflict resolutions.",
+            "why": "Smaller changes are lower-risk and review/integrate far faster; frequent rebasing keeps divergence small and shrinks the multi-agent conflict window. Because agents make it cheaper to produce overlapping work than to reconcile it, short-lived branches are the single best conflict-prevention lever. Production-learned at the BrightAI Opportunity Explorer, corroborated by trunk-based development.",
+            "defaultLevel": "ci",
+            "availableLevels": [
+                "advisory",
+                "ci"
+            ],
+            "optInDefault": "on",
+            "productionLearned": true,
+            "artifacts": [
+                {
+                    "kind": "claudeMd",
+                    "body": "One logical change per branch, alive ~1–2 days, rebased onto trunk often; split big work into a stack of small dependent diffs.\nKeep trunk green: test after every commit and revert breakage immediately."
+                },
+                {
+                    "kind": "ci",
+                    "body": "Require an up-to-date base + fast review; a PR-size linter warns on large diffs; a stale-branch report flags branches older than the agreed age. Set rerere.enabled in the repo. Mostly norm + CI nudge, not a hard block."
+                }
+            ],
+            "sourceUrls": [
+                "https://trunkbaseddevelopment.com/short-lived-feature-branches/",
+                "https://newsletter.pragmaticengineer.com/p/stacked-diffs"
+            ]
+        },
+        {
+            "id": "protect-shared-files",
+            "version": "1.0.0",
+            "title": "Protect shared/global files from concurrent edits; sequence dependent work",
+            "category": "Parallel & Multi-Session Coordination",
+            "tier": "recommended",
+            "what": "Treat lockfiles, migrations, root configs, and shared contracts as off-limits unless explicitly assigned to exactly one session — no concurrent dependency changes across worktrees. Sequence genuinely dependent work instead of parallelizing it: establish shared contracts (endpoint signatures, schemas) first, merge the shared utility, then fan out dependents.",
+            "why": "Worktree isolation prevents file clobbering during work but not logical/dependency conflicts. Lockfiles and migration sequences edited in parallel reliably break integration; dependent tasks run in parallel guarantee rework. Clear ownership boundaries and dependency ordering are what keep \"green individually, red together\" from happening.",
+            "defaultLevel": "hook-soft",
+            "availableLevels": [
+                "advisory",
+                "hook-soft",
+                "hook-hard"
+            ],
+            "optInDefault": "on",
+            "artifacts": [
+                {
+                    "kind": "claudeMd",
+                    "body": "Do not edit lockfiles, migrations, root configs, or shared contracts unless this session is the assigned owner.\nSequence dependent work: land the shared contract/utility first, then fan out dependents."
+                },
+                {
+                    "kind": "settingsHook",
+                    "event": "PreToolUse",
+                    "matcher": "Write|Edit",
+                    "command": "convene practice-guard protect-shared-files",
+                    "verb": "practice-guard"
+                }
+            ],
+            "sourceUrls": [
+                "https://www.aakashx.com/blog/parallel-claude-code-agents/",
+                "https://www.augmentcode.com/guides/git-worktrees-parallel-ai-agent-execution"
+            ]
+        },
+        {
+            "id": "right-scope-instruction-files",
+            "version": "1.0.0",
+            "title": "Right-scope instruction files; bridge AGENTS.md to CLAUDE.md; move sometimes-rules to skills",
+            "category": "Instruction Files (CLAUDE.md / AGENTS.md)",
+            "tier": "recommended",
+            "what": "Place instructions by scope (managed org policy > user ~/.claude > project ./CLAUDE.md committed > ./CLAUDE.local.md gitignored). Commit the project file; keep personal notes in CLAUDE.local.md. Bridge multi-tool repos by importing AGENTS.md into CLAUDE.md (@AGENTS.md) or symlinking rather than duplicating. Move only-sometimes-relevant domain knowledge to skills and file-specific rules to .claude/rules/ with paths frontmatter, keeping the root file lean.",
+            "why": "Right-scoping prevents personal preferences leaking to the team, keeps org policy enforceable, and keeps the per-turn budget small while making deep context available on demand. A single bridged source of truth keeps multi-tool repos (Convene already writes Cursor/Cline/Codex/Gemini configs) from drifting.",
+            "defaultLevel": "ci",
+            "availableLevels": [
+                "advisory",
+                "ci"
+            ],
+            "optInDefault": "on",
+            "artifacts": [
+                {
+                    "kind": "claudeMd",
+                    "body": "Commit project CLAUDE.md; keep personal notes in CLAUDE.local.md (gitignored). Bridge multi-tool repos with @AGENTS.md, don’t duplicate.\nMove sometimes-relevant knowledge to skills and file-specific rules to .claude/rules/ to keep this file lean."
+                },
+                {
+                    "kind": "ci",
+                    "body": "Assert CLAUDE.local.md is gitignored and project CLAUDE.md is committed; flag large @-imports and oversized always-loaded files."
+                }
+            ],
+            "sourceUrls": [
+                "https://code.claude.com/docs/en/memory",
+                "https://cursor.com/docs/rules",
+                "https://agentpatterns.ai/workflows/central-repo-shared-agent-standards/"
+            ]
+        },
+        {
+            "id": "push-rules-to-tools",
+            "version": "1.0.0",
+            "title": "Push deterministic rules down to tools (linters/formatters/config), don’t restate them",
+            "category": "Instruction Files (CLAUDE.md / AGENTS.md)",
+            "tier": "recommended",
+            "what": "If a constraint can be enforced deterministically by a tool already in the repo (ESLint, Prettier, tsconfig, Ruff, Biome, a hook, a CI gate), enforce it there and do NOT restate it in CLAUDE.md. Replace \"copy the style guide\" with a linter; replace \"always run X\" prose with a hook. The instruction file just points at these tools.",
+            "why": "Instruction files are probabilistic; linters/formatters/hooks are deterministic. A rule the tool already enforces is dead weight that bloats the file and is less reliable than the tool. This shrinks the always-loaded context AND makes the constraint actually hold.",
+            "defaultLevel": "ci",
+            "availableLevels": [
+                "advisory",
+                "ci"
+            ],
+            "optInDefault": "on",
+            "artifacts": [
+                {
+                    "kind": "claudeMd",
+                    "body": "If a linter, formatter, tsconfig, hook, or CI gate can enforce a rule deterministically, enforce it there and do not restate it here — just point at the tool."
+                },
+                {
+                    "kind": "ci",
+                    "body": "Run lint/format/typecheck in CI and as PostToolUse hooks. A reviewer/linter flags CLAUDE.md content that duplicates a linter-enforceable rule."
+                }
+            ],
+            "sourceUrls": [
+                "https://cursor.com/docs/rules",
+                "https://asdlc.io/practices/agents-md-spec/",
+                "https://code.claude.com/docs/en/best-practices"
+            ]
+        },
+        {
+            "id": "specific-source-grounded-prompts",
+            "version": "1.0.0",
+            "title": "Give specific, source-grounded prompts; hand over reference implementations",
+            "category": "Workflow Discipline (Plan / Explore / Commit)",
+            "tier": "recommended",
+            "what": "Scope each task (which file, which scenario, testing prefs) and point the agent at the source that answers it (@-reference files, git history, doc URLs, piped data). Prefer handing the agent an existing example to follow (\"look at HotDogWidget.php and follow the pattern\") over describing the pattern in prose. For approach-uncertain work, ask for 2–3 high-level approaches with tradeoffs before any code.",
+            "why": "Claude can infer intent but can’t read your mind. Specific context prevents solving the wrong problem and reduces the correction loop that pollutes context. Concrete reference code carries far more reliable signal than prose and keeps new code consistent with existing conventions.",
+            "defaultLevel": "advisory",
+            "availableLevels": [
+                "advisory"
+            ],
+            "optInDefault": "on",
+            "artifacts": [
+                {
+                    "kind": "claudeMd",
+                    "body": "Scope each task (file, scenario, test prefs) and @-reference the source that answers it. Hand over an existing example to follow over describing a pattern in prose.\nWhen the approach is uncertain, ask for 2–3 options with tradeoffs before any code."
+                }
+            ],
+            "sourceUrls": [
+                "https://code.claude.com/docs/en/best-practices",
+                "https://simonwillison.net/2026/Feb/23/agentic-engineering-patterns/"
+            ]
+        },
+        {
+            "id": "permissions-deny-secrets",
+            "version": "1.0.0",
+            "title": "Configure permission allowlists and a hard denylist for secrets/credentials",
+            "category": "Permissions & Sandboxing",
+            "tier": "recommended",
+            "what": "Replace click-through approval fatigue with explicit allowlists for known-safe commands (npm run lint, git commit) and hard deny rules for secrets and dangerous operations (Read(./.env), Read(./secrets/**), Bash(curl *)). Use deny for hard blocks that cannot be overridden; scope unattended/headless runs with --allowedTools.",
+            "why": "After the tenth approval you’re not really reviewing. Allowlists cut interruptions while keeping control; deny rules are hard blocks that merge across scopes and take precedence over allows — the right place for credential protection, client-enforced regardless of what the agent decides.",
+            "defaultLevel": "hook-hard",
+            "availableLevels": [
+                "advisory",
+                "hook-hard"
+            ],
+            "optInDefault": "on",
+            "artifacts": [
+                {
+                    "kind": "claudeMd",
+                    "body": "Secrets are hard-denied in .claude/settings.json (.env, .env.*, secrets/**). Allowlist known-safe commands instead of click-through approval.\nFor unattended/headless runs, scope tools with --allowedTools."
+                },
+                {
+                    "kind": "settingsJson",
+                    "merge": {
+                        "permissions": {
+                            "deny": [
+                                "Read(./.env)",
+                                "Read(./.env.*)",
+                                "Read(./**/.env)",
+                                "Read(./secrets/**)",
+                                "Read(./**/*.pem)",
+                                "Read(./**/*.key)",
+                                "Read(./**/id_rsa)",
+                                "Read(./**/credentials)",
+                                "Read(./**/*.p12)"
+                            ]
+                        }
+                    }
+                }
+            ],
+            "sourceUrls": [
+                "https://code.claude.com/docs/en/settings",
+                "https://code.claude.com/docs/en/best-practices"
+            ]
+        },
+        {
+            "id": "focused-subagents-least-privilege",
+            "version": "1.0.0",
+            "title": "Design focused, least-privilege subagents; delegate verbose work to protect context",
+            "category": "Subagents & Delegation",
+            "tier": "recommended",
+            "what": "Delegate research, high-volume output (report only the failing tests), and parallel investigations to subagents that run in isolated context and return summaries. Design each subagent for one task, write a detailed description (the delegation signal; add \"use proactively\"), and grant least-privilege tools via the tools allowlist / disallowedTools (e.g. a reviewer gets Read/Grep/Glob/Bash but no Edit/Write). Commit subagents in .claude/agents/ so the team inherits them.",
+            "why": "Context is the fundamental constraint, so subagents that explore in a separate window and return only a summary are among the most powerful tools available. Focused agents with limited tools improve security and focus; vague descriptions cause missed or wrong delegation. Frontmatter tools/disallowedTools is mechanically enforced — the subagent literally cannot use omitted tools.",
+            "defaultLevel": "hook-soft",
+            "availableLevels": [
+                "advisory",
+                "hook-soft"
+            ],
+            "optInDefault": "on",
+            "artifacts": [
+                {
+                    "kind": "claudeMd",
+                    "body": "Delegate research and high-volume output to subagents that return summaries (e.g. \"report only failing tests\"). One task per agent.\nGrant least-privilege tools via frontmatter (a reviewer gets Read/Grep/Glob, no Edit/Write); commit agents in .claude/agents/."
+                },
+                {
+                    "kind": "settingsHook",
+                    "event": "PreToolUse",
+                    "matcher": "Task",
+                    "command": "convene practice-guard focused-subagents-least-privilege",
+                    "verb": "practice-guard"
+                }
+            ],
+            "sourceUrls": [
+                "https://code.claude.com/docs/en/sub-agents",
+                "https://code.claude.com/docs/en/best-practices"
+            ]
+        },
+        {
+            "id": "capture-workflows-as-skills",
+            "version": "1.0.0",
+            "title": "Capture repeatable workflows as committed slash commands / skills",
+            "category": "Workflow Discipline (Plan / Explore / Commit)",
+            "tier": "recommended",
+            "what": "Store reusable workflows (issue-fixing, migration loops, debugging routines) as skills (SKILL.md in .claude/skills/) invoked by name or applied when relevant; use disable-model-invocation:true for side-effecting workflows you want triggered manually. Check skills/commands into git so the team gets consistent, shareable workflows.",
+            "why": "Keeps the always-loaded context lean while giving the agent deep on-demand knowledge, and standardizes team workflows so they’re reproducible. Committed skills are loaded deterministically by the harness; disable-model-invocation keeps side-effecting workflows manual-only.",
+            "defaultLevel": "advisory",
+            "availableLevels": [
+                "advisory"
+            ],
+            "optInDefault": "on",
+            "artifacts": [
+                {
+                    "kind": "claudeMd",
+                    "body": "Store reusable workflows as committed skills in .claude/skills/ so the team shares them. Use disable-model-invocation:true for side-effecting ones."
+                }
+            ],
+            "sourceUrls": [
+                "https://code.claude.com/docs/en/best-practices",
+                "https://code.claude.com/docs/en/memory"
+            ]
+        },
+        {
+            "id": "catalog-versioned-staged-rollout",
+            "version": "1.0.0",
+            "title": "Version the catalog (SemVer), let repos pin/float, and stage enforcement rollout",
+            "category": "Catalog Governance & Distribution",
+            "tier": "recommended",
+            "what": "Attach a SemVer version to each practice and let a repo’s .convene/project.json declare its update channel (pinned, minor-floating, or @latest). Communicate bump level on the bus so a session knows whether an update is auto-takeable (patch) or needs review (major). Introduce every new or tightened practice at the lowest tier (advisory) and ratchet up (advisory → hook-soft → hook-hard/ci) only as conformance data justifies it.",
+            "why": "Without a version + bump-level signal every update looks equally risky, so teams take nothing (drift) or everything (breakage). Pinning gives reproducibility; floating gives auto-propagation of fixes; staged enforcement surfaces the cost of compliance before it’s mandatory and makes the eventual hard-fail a non-event.",
+            "defaultLevel": "advisory",
+            "availableLevels": [
+                "advisory",
+                "manual"
+            ],
+            "optInDefault": "on",
+            "artifacts": [
+                {
+                    "kind": "claudeMd",
+                    "body": "Each practice is SemVer-versioned; .convene/project.json pins the (practice, version, level) it adopted. New/tightened practices land advisory-first and ratchet up only as conformance justifies."
+                }
+            ],
+            "sourceUrls": [
+                "https://developer.hashicorp.com/sentinel/docs/concepts/enforcement-levels",
+                "https://pre-commit.com/"
+            ]
+        },
+        {
+            "id": "catalog-opt-in-overridable",
+            "version": "1.0.0",
+            "title": "Per-practice opt-in with repo-level overrides and documented escape hatches",
+            "category": "Catalog Governance & Distribution",
+            "tier": "recommended",
+            "what": "Make every practice individually adoptable and individually tunable (advisory vs blocking) per repo, with org defaults a repo can extend or override (local wins, recorded in version control). Provide an explicit, attributed, sparingly-used override for soft-mandatory gates (e.g. `convene override --reason`) that the bus logs, rather than a silent bypass. Surface adoption + override frequency on the dashboard.",
+            "why": "Bundling standards as one indivisible pack forces teams to accept the strictest least-relevant rule to get the valuable one — the surest route to wholesale rejection and shadow workarounds. Per-practice opt-in + documented, attributed overrides keep deviation inside the governance framework (auditable) instead of in the shadows.",
+            "defaultLevel": "manual",
+            "availableLevels": [
+                "advisory",
+                "manual"
+            ],
+            "optInDefault": "on",
+            "artifacts": [
+                {
+                    "kind": "claudeMd",
+                    "body": "Every practice is opt-in and tunable per repo; org defaults apply unless overridden (local wins, in version control).\nBypass a soft gate only via an attributed `convene override --reason` — never a silent skip."
+                }
+            ],
+            "sourceUrls": [
+                "https://developer.hashicorp.com/sentinel/docs/concepts/enforcement-levels",
+                "https://mia-platform.eu/blog/paved-roads-golden-paths-guardrails-railroads/"
+            ]
+        },
+        {
+            "id": "adversarial-review-step",
+            "version": "1.0.0",
+            "title": "Adversarial / fresh-context review before counting work done",
+            "category": "Verification & Quality Gates",
+            "tier": "advanced",
+            "what": "Before treating a task complete, have a subagent review the diff in a fresh context seeing only the change and the criteria — not the reasoning that produced it. Use the bundled /code-review skill or a committed reviewer subagent (read-only tools). Constrain it: \"flag only gaps affecting correctness or stated requirements,\" because a reviewer asked to find gaps will report some even when the work is sound.",
+            "why": "A fresh context improves code review since Claude won’t be biased toward code it just wrote. An independent grader catches edge cases the author model rationalized away — especially valuable the longer a session runs unattended. The correctness/requirements constraint is essential to avoid the over-engineering failure mode the docs warn about.",
+            "defaultLevel": "ci",
+            "availableLevels": [
+                "advisory",
+                "ci"
+            ],
+            "optInDefault": "off",
+            "artifacts": [
+                {
+                    "kind": "claudeMd",
+                    "body": "Before counting work done, run a fresh-context reviewer (the /code-review skill or a read-only reviewer subagent) on the diff.\nConstrain it to gaps affecting correctness or stated requirements."
+                },
+                {
+                    "kind": "ci",
+                    "body": "Run /code-review or a read-only reviewer subagent (claude -p) on the diff as a CI step. Acting on findings stays advisory; default OFF (higher cost, best for mature/unattended workflows)."
+                }
+            ],
+            "sourceUrls": [
+                "https://code.claude.com/docs/en/best-practices",
+                "https://code.claude.com/docs/en/sub-agents"
+            ]
+        },
+        {
+            "id": "merge-queue-serialize-landings",
+            "version": "1.0.0",
+            "title": "Serialize landings through a merge queue (claim an integration slot)",
+            "category": "Parallel & Multi-Session Coordination",
+            "tier": "advanced",
+            "what": "Land agent branches through a FIFO merge queue rather than racing pushes to main. The queue rebases each PR onto latest main plus PRs ahead of it, runs CI against that combined (speculative) state, merges only if green, and sends entries back for revision when they no longer apply. Re-validate the integrated branch (full suite) before declaring parallel work complete.",
+            "why": "Each branch can be individually green yet collectively red; a merge queue makes integration deterministic and prevents a broken main even with many branches in flight. It is the scaled-up form of Convene’s deploy-lane discipline for high-concurrency teams.",
+            "defaultLevel": "ci",
+            "availableLevels": [
+                "advisory",
+                "ci"
+            ],
+            "optInDefault": "off",
+            "artifacts": [
+                {
+                    "kind": "ci",
+                    "body": "GitHub merge queue / Mergify with required checks on the rebased combined state. Complements Convene’s deploy-lane gate (which serializes a single deploy ref). Default OFF — only valuable at higher concurrency."
+                }
+            ],
+            "sourceUrls": [
+                "https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue",
+                "https://mergify.com/merge-queue"
+            ]
+        },
+        {
+            "id": "yolo-in-sandbox",
+            "version": "1.0.0",
+            "title": "Run auto-approval (YOLO) mode only inside a sandbox",
+            "category": "Permissions & Sandboxing",
+            "tier": "advanced",
+            "what": "If you run with broad auto-approval for throughput, do it only inside a container/VM that restricts files, secrets, and network egress, with test/staging-only credentials and budget caps. Anthropic recommends --dangerously-skip-permissions only in a container without internet; practitioners run it aliased inside Docker or Codespaces. permissions.deny still applies.",
+            "why": "Auto-approving every action is key to maximum throughput but dangerous: it exposes destructive shell commands, source/secret exfiltration (including via prompt injection), and use of your machine as a proxy to attack other targets. Sandboxing limits the blast radius so productivity gains don’t carry catastrophic downside.",
+            "defaultLevel": "manual",
+            "availableLevels": [
+                "advisory",
+                "manual"
+            ],
+            "optInDefault": "off",
+            "artifacts": [
+                {
+                    "kind": "claudeMd",
+                    "body": "Only run broad auto-approval (--dangerously-skip-permissions) inside a container/VM with no internet egress, scoped test credentials, and spend caps. permissions.deny still applies."
+                },
+                {
+                    "kind": "doc",
+                    "path": ".convene/practices/yolo-in-sandbox.md",
+                    "body": "# YOLO-in-sandbox\n\nBroad auto-approval is throughput at the cost of safety. Run it ONLY in an isolated sandbox:\n\n- Container/VM with restricted filesystem and **no network egress** (or a strict egress allowlist).\n- Test/staging-only credentials — never production secrets in scope.\n- Budget/spend caps on the session.\n- Keep `permissions.deny` (it still applies even with --dangerously-skip-permissions).\n\nConvene ships this as guidance — it cannot mechanically force a sandbox from inside the repo."
+                }
+            ],
+            "sourceUrls": [
+                "https://simonwillison.net/2025/Sep/30/designing-agentic-loops/",
+                "https://lucumr.pocoo.org/2025/6/12/agentic-coding/",
+                "https://code.claude.com/docs/en/best-practices"
+            ]
+        },
+        {
+            "id": "headless-fanout-scoped",
+            "version": "1.0.0",
+            "title": "Use headless mode (claude -p) for CI and fan-out, scoped tightly",
+            "category": "Subagents & Delegation",
+            "tier": "advanced",
+            "what": "Use claude -p non-interactively in CI, pre-commit/pre-push hooks, and large mechanical migrations (loop over a file list calling claude -p per file). Restrict capability with --allowedTools and --permission-mode auto; parse with --output-format json. Test the prompt on 2–3 files before running at scale.",
+            "why": "Headless mode is how agents integrate into automation and scale horizontally; --allowedTools bounding what the agent can do matters when running unattended, and refining the prompt on a few files first prevents costly large-scale mistakes. permissions.deny still applies in headless mode.",
+            "defaultLevel": "ci",
+            "availableLevels": [
+                "advisory",
+                "ci"
+            ],
+            "optInDefault": "off",
+            "artifacts": [
+                {
+                    "kind": "claudeMd",
+                    "body": "For CI and large mechanical migrations, drive claude -p with --allowedTools + --permission-mode auto and --output-format json. Test the prompt on 2–3 files before running at scale."
+                },
+                {
+                    "kind": "ci",
+                    "body": "Wire claude -p into CI/pre-commit as the enforcement point, bounded by --allowedTools, with structured JSON output for programmatic gating. Default OFF — for teams automating at scale."
+                }
+            ],
+            "sourceUrls": [
+                "https://code.claude.com/docs/en/best-practices"
+            ]
+        },
+        {
+            "id": "prefer-cli-over-mcp",
+            "version": "1.0.0",
+            "title": "Prefer CLI tools and scripts over MCP servers for external services",
+            "category": "Workflow Discipline (Plan / Explore / Commit)",
+            "tier": "advanced",
+            "what": "Give the agent plain command-line tools (gh, psql, aws, plain SQL) documented in AGENTS.md/CLAUDE.md rather than wrapping everything in MCP. Keep the MCP surface minimal (e.g. one for browser automation); pre-install the CLIs the agent should use in the dev image.",
+            "why": "CLI tools are the most context-efficient way to interact with external services, embed in scripts, and agents already know a huge array of them; MCP servers are an extra moving part that can be unreliable. Contested — Anthropic also promotes select MCP servers — so treat this as a default-lean preference, not an absolute.",
+            "defaultLevel": "advisory",
+            "availableLevels": [
+                "advisory"
+            ],
+            "optInDefault": "off",
+            "artifacts": [
+                {
+                    "kind": "claudeMd",
+                    "body": "Prefer documented CLI tools (gh, psql, aws, plain SQL) over wrapping external services in MCP; keep the MCP surface minimal. Pre-install those CLIs in the dev image."
+                }
+            ],
+            "sourceUrls": [
+                "https://lucumr.pocoo.org/2025/6/12/agentic-coding/",
+                "https://simonwillison.net/2025/Sep/30/designing-agentic-loops/"
+            ]
+        },
+        {
+            "id": "test-first-tdd",
+            "version": "1.0.0",
+            "title": "Test-first / Red-Green TDD for agents",
+            "category": "Verification & Quality Gates",
+            "tier": "advanced",
+            "what": "Establish test specifications before implementation: have one agent (or session) write failing tests, then write code to make them pass — optionally separating the test-writer and code-writer roles across sessions. Anthropic suggests one Claude writes tests, another writes code to pass them.",
+            "why": "A failing test is a precise, machine-checkable success criterion that constrains output and closes the verification loop, helping agents write more succinct and reliable code with minimal extra prompting. It operationalizes verify-before-ship for greenfield/feature work.",
+            "defaultLevel": "ci",
+            "availableLevels": [
+                "advisory",
+                "ci"
+            ],
+            "optInDefault": "off",
+            "artifacts": [
+                {
+                    "kind": "claudeMd",
+                    "body": "For feature work, write failing tests first, then code to make them pass; optionally split test-writer and code-writer across sessions."
+                },
+                {
+                    "kind": "ci",
+                    "body": "CI requires tests + a Stop hook gating on green; optional writer/tester session separation. Default OFF — a strong discipline but a workflow choice not every change needs (overlaps with verify-before-ship)."
+                }
+            ],
+            "sourceUrls": [
+                "https://simonwillison.net/2026/Feb/23/agentic-engineering-patterns/",
+                "https://harper.blog/2025/02/16/my-llm-codegen-workflow-atm/"
+            ]
+        },
+        {
+            "id": "cap-concurrency-to-review",
+            "version": "1.0.0",
+            "title": "Cap concurrency to review/merge capacity",
+            "category": "Parallel & Multi-Session Coordination",
+            "tier": "advanced",
+            "what": "Match the number of concurrent sessions to human review + integration bandwidth — start with two or three and scale only as review capacity allows. Don’t parallelize sub-5-minute tasks, subtle bugs with unknown root cause, architecture redesigns, or single-file refactors.",
+            "why": "Throughput is bounded by review and integration, not by how many agents you can launch; over-fanning turns a short task into long review-and-cleanup and inflates the conflict surface. (Specific tier numbers are heuristic; the bounded-by-review-capacity principle is the durable part.)",
+            "defaultLevel": "advisory",
+            "availableLevels": [
+                "advisory"
+            ],
+            "optInDefault": "off",
+            "artifacts": [
+                {
+                    "kind": "claudeMd",
+                    "body": "Run only as many concurrent sessions as you can review and integrate (start with 2–3). Don’t parallelize sub-5-minute tasks, single-file refactors, or unknown-root-cause bugs."
+                }
+            ],
+            "sourceUrls": [
+                "https://nimbalyst.com/blog/git-worktrees-for-ai-coding-agents-complete-guide/",
+                "https://www.aakashx.com/blog/parallel-claude-code-agents/"
+            ]
+        },
+        {
+            "id": "course-correct-checkpoints",
+            "version": "1.0.0",
+            "title": "Course-correct early; use cheap reversibility (checkpoints + frequent commits)",
+            "category": "Context Management",
+            "tier": "advanced",
+            "what": "Interrupt the moment the agent goes off track (Esc to stop with context preserved; Esc-Esc/rewind to restore prior state). Because every prompt is a checkpoint and files are snapshotted before edits, you can tell the agent to try something risky and rewind if it fails. Combine with frequent git commits as save-points. Caveat: checkpoints track only the agent’s changes, not external processes — not a git replacement.",
+            "why": "The best results come from tight feedback loops. Correcting quickly beats letting a flawed trajectory compound; cheap reversibility changes the cost calculus so you can explore aggressively. Frequent commits make experiments cheap to abandon.",
+            "defaultLevel": "advisory",
+            "availableLevels": [
+                "advisory"
+            ],
+            "optInDefault": "off",
+            "artifacts": [
+                {
+                    "kind": "claudeMd",
+                    "body": "Interrupt early when the agent drifts (Esc; Esc-Esc to rewind). Commit often as save-points so risky attempts are cheap to abandon."
+                }
+            ],
+            "sourceUrls": [
+                "https://code.claude.com/docs/en/best-practices",
+                "https://www.samuelliedtke.com/blog/notes-on-agentic-engineering-in-action-with-mitchell-hashimoto/"
+            ]
+        },
+        {
+            "id": "catalog-drift-detection",
+            "version": "1.0.0",
+            "title": "Detect catalog drift and surface it; evolve standards via expand→migrate→contract",
+            "category": "Catalog Governance & Distribution",
+            "tier": "advanced",
+            "what": "Add a drift check (extend `convene doctor`) that hashes each repo’s catalog-managed marker regions and compares against the declared catalog version, reporting \"N versions behind / local drift\" on the dashboard and in the fetch block — surface, don’t auto-correct. When changing or retiring a practice, use expand→migrate→contract: ship the new version advisory-first alongside the old, instrument who still uses the old, and hard-remove only after a real deprecation window.",
+            "why": "Drift is silent and cumulative — a \"fleet on latest best practices\" claim becomes false within weeks without detection; a dashboard turns invisible drift into a prioritizable backlog. Instantly failing repos that complied with the old version punishes your most compliant teams; a deprecation window lets them migrate on their own schedule.",
+            "defaultLevel": "ci",
+            "availableLevels": [
+                "advisory",
+                "ci"
+            ],
+            "optInDefault": "off",
+            "artifacts": [
+                {
+                    "kind": "ci",
+                    "body": "`convene doctor` / a CI check computes marker-region hashes vs the declared catalog version; the fetch health line reports behind/drift. Deprecate via expand→migrate→contract with instrumentation of who’s on the old version. Default OFF until catalog-versioned-staged-rollout is in place."
+                }
+            ],
+            "sourceUrls": [
+                "https://roadie.io/backstage/plugins/tech-insights/",
+                "https://docs.renovatebot.com/configuration-options/"
+            ]
+        }
+    ]
+};
+exports.CATALOG_VERSION = "1.0.0";