---
title: "Repo Bootstrapper"
description: "Generates and maintains the full mdb-tam file standard for any repository."
---

# 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

| User says | Invoke |
|---|---|
| "bootstrap", "initialize", "create from scratch" | `create_ideal_repo` |
| "audit", "check against standard", "what's missing" | `audit_repo` |
| "bring to ideal state", "modernize", "update" | `update_to_ideal_repo` |
| "add operations registry" | `create_operations_registry` |
| "update CLAUDE.md" / any specific file | `update_file` |
| "clean up", "commit all", "get repo current and clean" | `cleanup_and_commit` |
| "register with hub", "add to global-ai-hub", "sync with project manager" | `register_with_hub` |
| "run the bootstrap prompt" | `run_bootstrap` |
| Ambiguous | Run `audit_repo` first, then ask whether to proceed with `update_to_ideal_repo` |

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

**Bootstrap prompt fallback:** if `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 `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
| File | Purpose |
|---|---|
| `.github/copilot-instructions.md` | Copilot CLI global rules; must start with `## Default Execution Strategy` |
| `CLAUDE.md` | Claude Code equivalent; includes workflow log rule |
| `AGENTS.md` | Catalog of repo-local agents with name, scope, when-to-use, tools |
| `GEMINI.md` | Gemini CLI equivalent — present even if minimal |
| `memory.md` | Versioned operator log of active task / completed work / next steps |
| `prompts.md` | Versioned record of every user request, in order |
| `docs/archive/` + `scripts/rotate-workflow-logs.mjs` | Size control for the append-forever logs: rotate older version sections to `docs/archive/` when a log crosses ~200 KB; tool must refuse while an editor swap file is live |

### Dotfile Meta (editor, toolchain, CI, repo hygiene)
| File | Purpose |
|---|---|
| `.editorconfig` | Cross-editor formatting rules |
| `.gitignore` | Repository-specific ignore rules |
| `.gitattributes` | Line-ending normalization, binary markers |
| `.nvmrc` or `.node-version` | Pinned Node version (Node repos) |
| `.tool-versions` | asdf/mise pin (optional) |
| `.env.example` | Documents every env var with safe placeholder values |
| `.vscode/settings.json` | Project-specific editor settings |
| `.vscode/extensions.json` | Recommended extensions |
| `.vscode/launch.json` | Debug configurations |
| `.vscode/mcp.json` | MCP servers for development |
| `.mcp.json` | Repo-level MCP server configuration |
| `.github/workflows/*.yml` | CI workflows (build, test, lint, type-check, security, release) |
| `.github/dependabot.yml` | Dependency-update bot configuration |
| `.github/CODEOWNERS` | Path-based reviewer mapping |
| `.github/PULL_REQUEST_TEMPLATE.md` | PR description template |
| `.github/ISSUE_TEMPLATE/bug_report.md` | Bug report template |
| `.github/ISSUE_TEMPLATE/feature_request.md` | Feature request template |
| `.github/SECURITY.md` | How to report security issues |
| `LICENSE` | License file |
| `CONTRIBUTING.md` | How to contribute |
| `CODE_OF_CONDUCT.md` | Code of conduct |

### Documentation Suite (`docs/`)
| File | Purpose |
|---|---|
| `docs/ARCHITECTURE.md` | System context, container diagram, data flows, ADRs |
| `docs/DEVELOPMENT.md` | Setup, commands, workflow, env vars, troubleshooting |
| `docs/COMPONENTS.md` | All major modules — purpose, API, dependencies |
| `docs/SECURITY.md` | Threat model, auth, secrets, STRIDE mitigations |
| `docs/MCP.md` | MCP servers, tools, auth, usage examples |
| `docs/TESTING.md` | Test strategy, suites, coverage targets, CI gates. Coverage target = **meaningful coverage of important and changed/risky paths** with real assertions on behavior and observable effects (including logs per `docs/logging.md`) — explicitly **not a blanket 100% line mandate** (rewards assertion-free coverage-gaming). State the numeric target and CI gate the repo actually enforces. (Writing the tests is code-fix work → route to `code-deep-optimizer` pass T1.) |
| `README.md` | Project overview, quick start, links to all docs |

### Reference and Index
| File | Purpose |
|---|---|
| `docs/codebase-overview.md` | Human-readable file map grouped by directory — must cover EVERY workspace component (a missing component section is a major finding) |
| `docs/high_signal_file_index.json` | Machine-readable per-file index for LLM retrieval |
| `scripts/semantic_indexer.py` | Local semantic embedding pipeline (Ollama + ChromaDB) triggered by file watcher |
| `scripts/watch_and_index.sh` | Filesystem hook to trigger semantic indexing on file creation/modification |
| `scripts/check-doc-indexes.mjs` (or equivalent) | Path-validates every entry in the retrieval indexes; `--prune` removes dead entries; wired into CI so index rot fails the build |
| `docs/integrations-and-assumptions.md` | External services, hardcoded assumptions, env differences |
| `docs/known-issues.md` | Active bugs, workarounds, inferred from TODO/FIXME |
| `docs/onboarding.md` | New-contributor walkthrough |

### Installation and Requirements
| File | Purpose |
|---|---|
| `docs/INSTALLATION.md` | Prerequisites, install steps, verification, upgrade/uninstall |
| `docs/requirements.md` | Functional/non-functional requirements, dependencies |

### Operational Reference
| File | Purpose |
|---|---|
| `docs/logging.md` | Logging approach, levels, sensitive data rules. Audit that **important code paths emit useful, structured, tested logs** — error/catch branches, every external call (request + outcome), security events, and state transitions. Unlogged error paths and silent failures are a **major** finding; secrets/PII in log output are **blocking**. (Adding the missing logs in code is code-fix work → route to `code-deep-optimizer` pass S5.) |
| `docs/caching-and-optimization.md` | Cache layers, invalidation, performance patterns |
| `docs/runbooks/*.md` | One file per recurring operational procedure |
| `docs/external-calls.md` | Inventory of every external call with logger, test, doc, retry policy |

### Operations Infrastructure
| File | Purpose |
|---|---|
| `server/src/lib/operations-registry.js` (canonical; older repos may use `mcp-server/src/operations-registry.ts`) | Declarative registry of every external call. Entry `transport`/`target` must match what the source file actually calls — a feed that hits Google APIs declared as `transport: 'local'` is a major finding |
| `scripts/generate-ops-registry-doc.mjs` | Sole writer of the registry doc; deterministic output; `ops:doc` / `ops:doc:check` npm scripts |
| `docs/operations-registry.json` | Generated artifact — never hand-edit; CI runs `ops:doc:check` |
| `docs/tool-inventory.json` | Tool/route inventory. In `mdb-tam` this is the server's HTTP routes with human-curated descriptions — a faithful drift check is a route-name set diff and requires a `createApp()` entry-point refactor (pending); until then treat as curated, verify counts manually |

**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

| Behavior | Trigger phrase examples |
|---|---|
| `audit_repo` | "audit this repo", "check against mdb-tam standard", "what's missing?" |
| `update_file` | "update CLAUDE.md", "refresh the architecture doc" |
| `create_ideal_repo` | "bootstrap this repo from scratch", "initialize mdb-tam standard" |
| `update_to_ideal_repo` | "bring this repo to ideal state", "modernize this repo" |
| `create_operations_registry` | "add operations registry", "create ops-registry.ts" |
| `create_skill_for_context` | "create a skill for this context file" |
| `sync_memory` | "update memory.md", "log completed work" |
| `cleanup_and_commit` | "clean up this repo", "commit all changes", "finalize the repo state", "get the repo current and clean" |
| `register_with_hub` | "register this repo with the hub", "add to global-ai-hub", "update hub registry", "sync with project manager" |
| `run_bootstrap` | "run the bootstrap prompt", "initialize from bootstrap" |

### `audit_repo(path)` → gap report

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

| File | Exists | Missing Sections | Action Required |
|---|---|---|---|

### `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 `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 `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 `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 `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`