Repo Bootstrapper

Repo Bootstrapper & Standards Maintainer

Generates and maintains the full mdb-tam file standard for any repository.

When to use this skill

• Create an ideal repository from scratch using the full mdb-tam standard (includes code quality optimization and LLM doc generation)
• Upgrade an existing repository toward that same ideal state (runs cdo and crawl-repo-to-llms automatically)
• Initialize a brand-new repository to the mdb-tam documentation and workflow standard
• Audit an existing repo against the standard and fill any gaps
• Update stale documentation sections (architecture, commands, known-issues, etc.)
• Create or update the docs/ suite, memory.md, prompts.md, CLAUDE.md, .github/copilot-instructions.md
• Keep docs/high_signal_file_index.json and docs/codebase-overview.md current after large changes (regenerated by crawl-repo-to-llms)
• Optimize code quality and generate LLM-friendly documentation as part of standard repo modernization

When NOT to use this skill

• Pure code review or bug hunting — use the /code-review command
• Pure security audit — use security-reviewer
• Code-pattern extraction without meta-doc work — use repo-pattern-scanner
• Production-log / runtime-error triage — review prod logs, root-cause a live error, verify a fix, open a remediation PR → the error-monitor-remediator agent (rule book: docs/error-monitoring-guide.md). This skill is a static meta-doc/standards maintainer with no telemetry access; it audits whether logging and test docs meet the standard, it does not read production logs or open PRs from runtime errors.
• Repo not following mdb-tam conventions — surface what the standard would require and ask before writing
• Read-only or locked repo — report findings only; do not write any files
• No clean working tree — verify git status is clean or operator has acknowledged the risk before writing

Entry point

Input: expects a local git repository path (absolute or CWD). If not a git repo, stop and report.

Bootstrap prompt fallback: if 10gen/mdb-tam/docs/repo-bootstrap-prompt.md cannot be loaded, stop and ask for the path to the local mdb-tam checkout. Do not proceed with run_bootstrap or create_ideal_repo without it.

Top-level output after any write phase:

Files written: <count> (<list of paths>)
Files updated: <count> (<list of paths>)
Remaining gaps (TODO): <list, or "none">
Next recommended action: <behavior name> or "done"

Skill guidance

• This skill’s canonical bootstrap prompt lives in 10gen/mdb-tam at docs/repo-bootstrap-prompt.md.
• When auditing, check each file in the Standard File Manifest below.
• Read the audit ledger first. Before any new audit, read existing docs/repo-bootstrap-audit-*.md files. Never re-raise a finding marked RETRACTED there without new evidence — fresh LLM passes reliably re-discover plausible-but-wrong findings (e.g. demanding DATASTORE_VERIFY_FAILED on kind: check/report ops when the gate only applies to kind: sync).
• Verify subagent findings against the artifact before acting. Parallel audit agents over-report: “row has missing-coverage marks” gets reported as “call is undocumented”, and per-block entry counts get reported as totals. Grep/read the target yourself before writing a remediation.
• Always infer from the actual codebase — never invent commands or paths.
• Full rewrites are appropriate when they materially improve clarity and maintainability.
• Use parallel agents for independent work phases: file-manifest audit, external-call inventory, extended checks, and skill-coverage gap analysis can all run concurrently.
• Never write real credentials, tokens, API keys, or env var values into any generated file.
• .env / .env.example may be read+write denied by Claude Code permission settings. Fall back to grep -rE "process\.env\.[A-Z_]+" for the var inventory and emit the missing-var list as a copy-paste TODO block instead of editing the file.

Standard File Manifest

Every repo that meets this standard must have ALL of the following files.

Workflow Infrastructure

Dotfile Meta (editor, toolchain, CI, repo hygiene)

Documentation Suite (docs/)

Reference and Index

Installation and Requirements

Operational Reference

Operations Infrastructure

Auto-remediation contract: a repo passes the audit only when every external call in docs/external-calls.md satisfies all five standards (CLI trigger, centralized error log, auto-remediation map, dashboard card, datastore verification). See references/coding-standards.md for full requirements.

Audit

The detailed per-file audit checklist lives in references/audit-checklist.md. Run it against every file in the manifest. Severity rubric: blocking, major, medium, minor.

Auto-remediation workflow

When the audit finds gaps, update_to_ideal_repo runs these passes in order:

1. Drift pass — compare every manifest file against current state; update commands, paths, versions, agent inventories; drop sections that no longer apply.
2. External-call inventory pass — grep for every external call, populate docs/external-calls.md, emit a per-call task for each missing standard.
3. Code quality pass — run code-deep-optimizer (cdo) to audit source code for bugs, efficiency, and maintainability; apply all Medium+ findings automatically.
4. LLM documentation pass — run crawl-repo-to-llms to generate machine-readable LLM-friendly documentation indexes (docs/high_signal_file_index.json, llms.txt metadata, semantic embeddings).
5. Convergence loop — re-run the drift pass after each change set. Stop when the audit returns zero medium-or-higher findings. Hard cap: 3 iterations. After 3, surface remaining findings as a TODO list and stop.
6. Repo hygiene pass — commit all changes, stage untracked files, clean up dangling work, and leave repo in a clean state with no shadow branches or uncommitted changes.
7. Hub registration pass — register or update the project in ~/.global-ai-hub project registry; sync metadata (paths, tags, languages, description) if already registered.
8. No-invention rule — never fabricate a command, path, env var, or external service. Surface unknowns as TODO with where-to-find.

Named Behaviors

audit_repo(path) → gap report

Run the audit checklist from references/audit-checklist.md against all files in path. Produce:

update_file(file, repo_context) → updated file content

1. Read the current content
2. Read relevant source files in the codebase
3. Extend, restructure, or fully rewrite to meet the ideal repo standard while preserving correct repo-specific facts

create_ideal_repo(path) → ideal repo baseline

1. Read the repo and identify canonical version file, runtime model, commands, docs, integration boundaries
2. Create the full standard file manifest
3. Rewrite weak top-level docs so the repo has a clear entry point, workflow rules, and maintenance baseline
4. Run code-deep-optimizer (cdo) to audit and optimize source code from the start
5. Run crawl-repo-to-llms to generate LLM-friendly documentation and semantic indexes for the new repo
6. Repo hygiene & commit — stage all new files, commit bootstrap changes, ensure clean working tree
7. Hub registration — register project in ~/.global-ai-hub registry with metadata (path, languages, tags, description)

update_to_ideal_repo(path) → modernization plan + execution

1. Check git status — stop and ask if working tree is dirty and operator has not acknowledged the risk
2. Audit every standard file for correctness, completeness, and clarity
3. Upgrade stale docs, indexes, workflow files, and skills
4. Run code-deep-optimizer (cdo) to audit and fix source code — auto-applies all Medium+ findings
5. Run crawl-repo-to-llms to generate LLM-friendly documentation indexes and semantic metadata
6. Re-run audit after code and doc passes to validate no regressions
7. Repo hygiene & commit — stage all untracked files, commit all changes (with descriptive message), clean up any shadow branches or dangling work, ensure clean git status
8. Hub registration — register or update project in ~/.global-ai-hub registry; sync repo metadata (paths, tags, languages, description)
9. Prefer clean rewrites over incremental patching when a file has duplication, drift, or low-signal structure

create_operations_registry(path) → operations-registry.js + MCP tools + tests + CI check

1. Grep for every external call (fetch, http.request, execFile, exec, spawn, child_process, fs.watch, SDK client calls)
2. Extract: file:line, target, transport type, error handling, retry logic
3. Generate server/src/lib/operations-registry.js with one OperationEntry per call
4. Generate buildToolInventory() and writeToolInventory() functions
5. Generate scripts/generate-ops-registry-doc.mjs as the sole writer of docs/operations-registry.json; add ops:doc and ops:doc:check npm scripts to package.json
6. Register MCP tools: tam_ops_list, tam_ops_get, tam_ops_run, tam_ops_history, tam_ops_status, tam_ops_audit, tam_ops_remediation, tam_ops_write_doc, tam_tool_inventory, tam_write_tool_inventory
7. Add tests and CI drift check (ops:doc:check step in .github/workflows/ci.yml)
8. Update docs/external-calls.md and docs/tool-inventory.json

create_skill_for_context(context_file_path) → SKILL.md + .skillfish.json

Produce both skill files following the format in Phase 6 of the bootstrap prompt (loaded from 10gen/mdb-tam/docs/repo-bootstrap-prompt.md).

sync_memory(version, completed_items, next_steps) → memory.md entry

Produce a new versioned entry for memory.md in the correct format.

cleanup_and_commit(path) → clean repo state

1. Get the repo current — pull latest from remote if applicable
2. Stage all untracked files in the repo
3. Commit all uncommitted changes with a descriptive message (format: “repo: modernization & cleanup” or similar)
4. Identify and clean up any shadow branches or dangling work (stashed changes, detached HEAD, leftover branches)
5. Verify git status returns clean — no uncommitted changes, no untracked files
6. Report final state: commit shas, branches cleaned, files committed

register_with_hub(path) → hub registry entry

1. Check if project exists in ~/.global-ai-hub/registry.json (or equivalent project manager)
2. If NOT registered: create new entry with metadata (absolute path, project name, languages, primary tags from package.json/docs, description from README)
3. If already registered: update metadata (sync paths, update tags, refresh description, update last-modified timestamp)
4. Validate entry against hub schema
5. Write/update registry and report final state: entry ID, metadata synced, timestamp

run_bootstrap(repo_path) → full task prompt

1. Load docs/repo-bootstrap-prompt.md from 10gen/mdb-tam (not from the target repo)
2. Substitute the actual repo_path, current branch name, and current HEAD sha into the prompt
3. Return the full customized prompt for the operator to run

Bundled Context

The full bootstrap prompt lives at docs/repo-bootstrap-prompt.md in 10gen/mdb-tam. Load it when the user asks to initialize, modernize, or turn a repository into an ideal repo. Do not hard-code local filesystem paths — resolve the file at runtime from the 10gen/mdb-tam checkout on the current machine.

References

• Full per-file audit checklist: references/audit-checklist.md
• 5-standard coding requirements for external calls: references/coding-standards.md