# Os Init > Trigger: "set up agentic OS", "initialize agent harness", "init my project for AI agents", "retrofit repository", "upgrade project for evolution", "sync instruction files", "where do I put CLAUDE.md", "create my agent environment", "set up persistent memory". Guides users through discovery, initializes/retrofits 3-Layer Memory, mirrors multi-tool instruction files (CLAUDE/GEMINI/Copilot/AGENTS), and guides plugin installation. - Skill: `richfrem/os-init` (Agent Skill, multi-file: 30 files) - Install (CLI): `npx skillmds@latest add richfrem/os-init` - Raw SKILL.md: https://api.skillmd.com/api/skills/richfrem/os-init/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - Author: richfrem (https://skillmd.com/u/richfrem) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/richfrem/os-init --- # Agentic OS Init & Retrofit Guide Bootstrap or retrofit the Agentic OS, 3-Layer Memory architecture, and multi-tool instructions in any repository. Supports fresh setup as well as retrofitting established projects to comply with autonomous evolution standards. --- ## Execution Flow 1. **Discovery & Environment Interview**: Identify project stack, active AI tools (Claude, Copilot, Gemini, Codex), and package manager (uvx, marketplace, local). 2. **Component & Retrofit Planning**: Present plan (fresh initialization vs. retrofit of existing custom skills). 3. **Execution**: Run `init_agentic_os.py` with appropriate flags (`--retrofit`, `--sync-instructions`). 4. **Plugin Installation Guidance**: Guide installation based on user's tooling environment. 5. **Post-Init & Memory Validation**: Verify Layer 2 `wiki/`, `references/map-debt.md`, and instruction mirrors. --- ## Phase 1: Discovery & Tooling Interview Identify project status (fresh setup vs. retrofit), active AI tools (Claude Code, Copilot CLI, Gemini/Antigravity, Codex, MAF), and installation preference (`uvx`, Claude marketplace, local). --- ## Phase 2: Component & Retrofit Planning Propose a component plan before execution: - Consult [retrofit-planning.md](references/retrofit-planning.md) for the component initialization and retrofit matrix. - Verify `context/control_plane.db` SQLite initialization, Layer 2 `wiki/` playbooks, `references/map-debt.md`, and Git pre-commit evolution guards. --- ## Phase 2.5 — Mandatory Intelligent Architecture & Rule Synthesis Protocol > [!IMPORTANT] > **No Blind Overwrites**: The AI Agent MUST NEVER blindly replace existing architecture files (`architecture.md`), rules (`.agent/rules/*.md`), or instruction files (`CLAUDE.md`, `GEMINI.md`, `AGENTS.md`). This cannot be a pure rigid deterministic script — act as an **intelligent context synthesizer**, balancing Agentic OS principles with target project domain realities. Follow the protocol in [instruction-blending.md](references/instruction-blending.md): 1. **Inspect Target Context**: Read existing `architecture.md`, `.agent/rules/`, and instruction files to discover project tech stack, constraints, and domain conventions. 2. **Synthesize Architecture**: If `architecture.md` exists, review and integrate Agentic OS substrates without disturbing system design; if absent, seed a tailored architecture blueprint. 3. **Blend Instructions & Rules**: Retain 100% of domain logic, reconcile rules non-destructively, and inject 3-Layer Memory, Map Debt Ledger, and Pre-Completion Gate. 4. **Present Diff**: Present proposed architectural and rule changes for confirmation before writing. --- ## Phase 3: Execution Run `init_agentic_os.py` based on mode: - **Mode A (Fresh Setup)**: `python3 .agents/skills/os-init/scripts/init_agentic_os.py --target --sync-instructions` - **Mode B (Retrofit Existing)**: `python3 .agents/skills/os-init/scripts/init_agentic_os.py --target --retrofit` *Note: In both modes, `init_agentic_os.py` automatically initializes `context/control_plane.db` with WAL mode, installs `.git/hooks/pre-commit-evolution-guard`, and configures the `Stop` turn hook.* Retrofit mode must call every scaffolding substrate explicitly — it does not inherit them from fresh setup. The `--retrofit` branch in `_execute_action()` is a separate, independently maintained call list from `create_project_structure()`'s; when modifying either, diff their two call lists against each other explicitly rather than assuming retrofit is a subset of fresh setup. Full history and the invariant this guards against are in `references/detailed-reference.md`. --- ## Phase 4: Plugin Installation & Deployment Provide the installation command tailored to the user's environment: - **Universal `uvx` (Recommended)**: `uvx --from git+https://github.com/richfrem/agent-plugins-skills plugin-add richfrem/agent-plugins-skills` - **Claude Code Marketplace**: `claude plugin add richfrem/agent-plugins-skills` - **Local Source Reinstall**: `python3 plugins/plugin-manager/scripts/plugin_add.py --all -y` --- ## Phase 5: Verification Checklist & System Health Check 1. **Verify 3-Layer Memory & Control Plane**: Check `context/control_plane.db`, Layer 2 `wiki/index.md`, and `references/map-debt.md`. 2. **Verify Multi-Tool Instruction Mirrors**: Ensure `CLAUDE.md`, `GEMINI.md`, `.github/copilot-instructions.md`, and `AGENTS.md` are aligned. 3. **Verify Skills & Plugin Compliance**: Run `audit_skill.py` on new skills; check `references/evolution-log.md` stubs. 4. **Mandatory Post-Init Health Check**: Trigger `os-health-check` (or Phase 3.5 substrate check); if any substrate reports `MISSING`, re-run with `--retrofit`. Check commands in `references/detailed-reference.md`. ## Consumer Guidance & Upstream Contribution Protocol When a bug or gap is found in an installed skill/script: prefer **Workflow A** (fix locally, port upstream via PR); use **Workflow B** (project-specific overrides in `.agent/rules/local-*`) for domain divergence; fall back to **Workflow C** (file upstream issue) if a PR isn't feasible. Full details in `references/detailed-reference.md`.