--- title: Repo Foundations --- # Repo Foundations ## What it is Repo Foundations gives any repository the foundations that make it ## Where to find it You can reach it two ways. In any session, run the repo-foundations skill; it is on by default, and its on/off switch lives in Settings under Features and in the Dev Pipeline panel's Setup tab. Or open the Dev Pipeline panel, go to the Setup tab, and use the Repo Foundations section there. It explains what good foundations are, lets you pick a repository and choose which of the two instruction files is the canonical one, and starts setup without leaving the panel. Because setup spawns a real agent session that costs money, it asks you to confirm first. productive for AI agents: a **documentation system** an agent can navigate from a cold start, a **Claude-rules baseline** that keeps its work safe and consistent, and a **cross-tool setup** so those foundations reach every AI tool you use (not just Claude Code). It inspects the repo, tailors everything to the actual stack, shows you a full preview, and writes nothing until you approve. ## How it behaves ### How you use it - **As a skill:** run `/repo-foundations` in any session. The Repo Foundations skill is on by default (shipped), so it's available out of the box — Omniscio installs the bundled skill into your Claude Code skills folder while the toggle is on and removes it when off. The toggle lives in **Settings → Features** and in the **Dev Pipeline panel → Setup** tab (below); it's on by default and there if you ever want to turn it off. - **From the Dev Pipeline panel:** a **Repo Foundations** section in the panel's **Setup** tab explains what good foundations are, lets you turn the skill on or off, and — while on — lets you pick a repository, choose your **canonical instructions file** (CLAUDE.md ⇄ AGENTS.md — the file the docs are written into and mirrored from), and start setup without leaving the panel. It's visible to everyone (no Lab flag needed); because it spawns a real Claude session that costs money, it asks you to confirm first. ### What it does, step by step 1. **Inspect** — reads the repo's language, framework, test runner, package manager, and any existing `CLAUDE.md` / `.claude/memory/` docs. 2. **Propose** — generates, tailored to that stack: a right-sized `CLAUDE.md` routing core + a `.claude/memory/MEMORY.md` index + a few starter topic files (the documentation system), and a portable Claude-rules baseline (worktree hygiene, no-AI-attribution, tests-required, security, simplicity, root-cause bug-fixing) folded into `CLAUDE.md`. 3. **Preview** — shows every file it will add or change, with a rationale, and **stops**. You approve, tweak, or cancel. 4. **Install** — writes the approved files into the working tree, left uncommitted for you to review and commit. It **never** commits, pushes, or touches a remote. 5. **Manifest** — writes `.claude/foundations.json` last, recording which modules are installed and whether each is `amc-default` (a maintaining pipeline keeps it in sync) or `custom` (you own it — the pipeline leaves it alone). When setup also configured cross-tool reach, it records that in an optional `crossTool` field (the chosen canonical + its mirrors, and where skills mirror to). ### Cross-tool reach When you run the **Set up this repo** action, the foundations don't stay Claude-only: - **Instructions flow to every tool.** Setup turns on **Agent Instructions Sync** with your chosen canonical, so the same instructions are mirrored to the other file of the `CLAUDE.md`/`AGENTS.md` pair (and any other tools you enable — Cursor, Codex, Gemini, Copilot, Windsurf, Cline). This uses a cheap single-file watcher, so editing the canonical keeps the mirrors live. Note this is a **global** setting: once on, your other repos also mirror their canonical on the next edit. - **Skills reach Cursor.** Setup scaffolds a `.claude/skills/` folder (the project's skills home, read by Claude Code) and mirrors it to `.cursor/skills/` (read by Cursor). The generated Cursor copy is git-ignored and never clobbers a `.cursor/skills/` you authored yourself. Only Claude Code and Cursor read _project-local_ skills; Codex/Gemini use user-level skills, handled separately by the provider-config-sync feature. - **No lag.** The skills mirror is deliberately **not** watched — it reconciles one-shot at setup, when you view a set-up repo, and via an explicit "Re-sync skills" button. Skills are only read when a tool starts, and watching a skills folder is what previously caused machine slowdowns, so it is structurally forbidden here. ### Safety Nothing is written before you approve the preview. It never blind-overwrites an existing file (existing docs are handled by a refresh-merge) and never rewrites a module you've marked `custom`. It scales the output to the repo's size — a tiny script gets a small setup, not a huge generic one. ### Testing regime module A third module — a tailored testing regime — is designed but not installed in this version; it is a fast-follow. ### Documentation-system playbook The skill ships with a portable, repo-agnostic _documentation-system playbook_ — a companion reference that spells out the full method the foundations are based on: the tiered docs system, the feature-contract skeleton, the postmortem discipline, and the enforcement guards that keep docs from silently going stale. It is the deeper reference behind what "Set up this repo" installs, and it can be handed to an AI in any repository to stand the same system up there. ## For agents ### Relationship to the dev-pipeline The manifest is the seam: the dev-pipeline reads `.claude/foundations.json` to know what a repo has and keeps the `amc-default` modules in sync on future runs. ## Related This page names no sibling library page, so the way onward is [INDEX.md](INDEX.md), the library index.