/archcore:init

First-time onboarding. Detects repo scale (small / medium / large) and shape, composes a scale-appropriate seed of .archcore/ documents, shows them in one preview, and creates them on a single confirm — so the code-alignment hook injection and per-command grounding have substance and the relation graph is live from day one. The same confirm also installs host wiring (project MCP config, SessionStart hook, usage hint — the same files archcore init writes), so the repo works for CLI-only teammates. Per magic-first-day-init.adr: extractive facts are composed in full; the top hotspot modules get real specs (synthesized only after confirm); the overview is an index, never a prose blob. Nothing is written before confirm. Exact per-mode output is in the Routing Table below.

Arguments

• --depth=light|standard|deep — synthesis budget (default standard), orthogonal to --mode. See the Depth axis section below. Also settable via the depth:<tier> toggle in the preview.
• --mode=small|medium|large — force a mode, overriding auto-detection.
• --domain=<slug> — re-run focused on one domain (large repos): scopes data-model + hotspot specs to that domain's tree, tops up only its docs. Bypasses the "already seeded" early-exit.
• --refresh — re-run on an already-seeded repo to add facts that appeared since the first init (a new schema, config, or modules) — and to retrofit host wiring on repos seeded before wiring existed. Bypasses the early-exit; existing docs are skipped, missing ones composed.

When to use

• Empty .archcore/ — the SessionStart nudge points here.
• First session on a fresh clone / fresh install.
• User says: "initialize archcore", "set up archcore", "seed archcore", "first-time setup", "what should I do first".

Not init (route elsewhere):

• Recording a specific decision → /archcore:document.
• Planning a feature → /archcore:plan.
• Documenting one module → /archcore:document.
• Codifying a team standard → /archcore:document (offers rule + guide continuation).
• Reading applicable context before coding → automatic; the code-alignment hook injects it on file edits.
• Docs health audit → /archcore:review.

Routing table

Mode routing — Step 0.5 classifier, evaluated top-to-bottom, first match wins. The empty route is decided earlier in Step 0(b). Precise conditions in _shared/grounding/detect-scale.md.

Signal	Route	Seeded (composed when detected)
No manifest AND no top-level source (Step 0b)	→ empty	no content docs — host wiring only, behind its own mini-confirm
--mode=X flag	→ forced X (detected mode still reported)	per row below
domain_count ≤ 1 AND module_count ≤ 15	→ small	stack rule, run guide, data-model, integrations, config, entry points, public surface, overview + hotspot specs (coverage rate × ranked pool — see Depth axis)
domain_count ≤ 2 AND module_count ≤ 40	→ medium	small set + cross-cutting rules (every depth, every candidate clearing the recurrence threshold) + hotspot specs (coverage rate × ranked pool — see Depth axis)
domain_count ≥ 3 OR module_count > 40	→ large	medium set + top-level map + domain dialog + data-model per schema-bearing domain (all, not only selected) + hotspot specs (coverage rate × ranked pool, plus a floor of ≥ 1 spec per selected domain — see Depth axis)

Every non-empty mode also composes the architecture-overview capstone, plans relation wiring, and offers agent-file import — aggregate files (CLAUDE.md / AGENTS.md / .cursorrules) as link stubs and modular rule files (.cursor/rules/*.mdc, .github/instructions/*.md, .windsurf/rules/*.md) as rule docs by default, per lib/agent-files.md — inside the preview. Tier-1 facts (data-model, integrations, config, entry points, public surface) are seeded in any mode when detected — breadth scales with the repo, presence does not. The public-surface fact is what carries the seed for library / SPA / multi-command-CLI / agent-plugin repos, where there is no server to enumerate as entry points. The empty route exits after Step 0.

Follow-up routing — closing-message hand-offs. Init surfaces these as todos; MUST NOT auto-invoke.

User wants to...	→ Invoke
Capture another module	/archcore:document <path>
Record a decision	/archcore:document
Codify a convention as a rule	/archcore:document
Plan a feature	/archcore:plan
Drill into another domain (large)	/archcore:init --domain=<slug>
Add facts that appeared since first init	/archcore:init --refresh
Scope queries to a domain (large)	mcp__archcore__search_documents with the domain tag
See what's loaded	/archcore:review

Depth axis (--depth=light|standard|deep)

Orthogonal to scale (--mode, which measures repo size). Depth sets the synthesis budget, not the artifact checklist. Extraction is always on in every depth — Tier-1 facts, imported authored rules, and the hotspot register are cheap and the highest-value / most-durable layer. Depth scales only the expensive, staleness-prone synthesis: spec bodies, cross-cutting rules, and big-file / aggregate extraction. Default: standard — a good first-day seed, not merely the cheapest one. Init is fully gated (nothing is written before confirm, and the preview shows all three depths' costs side by side before the user commits to any of them), so there is no reason to default to the thin tier just to be safe — light is the explicit opt-down for a cost-conscious user (still never empty — Universality invariant 3); deep is the explicit opt-up for a max plan.

Depth	Hotspot specs (rate × pool, floor)	Cross-cutting synth (medium/large)	Big authored (>200) & CLAUDE.md/AGENTS.md	Authored decisions → ADR	Relations
light (opt-down)	10% of the ranked pool, floor 3	every candidate clearing the recurrence threshold — MAY narrow scan toward guard + shared-indirection primitives for cost, but MUST still surface any high-confidence hit	link	—	basic
standard (default)	25% of the ranked pool, floor 4	every candidate clearing the recurrence threshold	link	—	basic
deep (opt-up)	60% of the ranked pool, floor 6	every candidate clearing the recurrence threshold	extract + split	extract from files (Route 2), never invent from code	enriched (spec↔rule, spec↔spec)

The spec budget scales with the repo and carries no absolute maximum — budget = max(floor(depth), round(rate(depth) × pool_size)), clipped to pool_size, where pool_size is the eligible ranked hotspot pool (detect-hotspots.md "Spec budget by coverage rate"). A 214-module pool budgets ~54 specs at standard; a 12-module pool budgets 4. Large mode adds a floor of ≥ 1 spec per domain selected in Step A.0, filling the rest by repo-wide rank; a later --domain=<slug> re-run applies the same formula to that domain's narrowed pool. Cross-cutting synthesis is on at every depth — it is the highest value-per-token artifact init seeds; depth changes only its scan cost at light, never whether it runs and no longer how many candidates survive. A very large or hot hotspot (LOC > 3000 OR top-quartile churn) may compose as a flagship at any depth, which makes it eligible for decomposition into ≤ 3 sub-specs by separable sub-surface instead of one spec (detect-hotspots.md "Flagship specs"). Every spec, flagship or not, is composed under the one ≤ 120-line cap in _shared/spec-contract.md.

Cost scales with depth AND with the repo — the preview shows the computed total per depth, never a constant. On a large repo deep can budget hundreds of specs; that is the intended behavior, and the preview's per-depth estimate is where the user sees the price before confirming. Treat any fixed multiplier as illustrative only.

Universality invariants — hold in EVERY depth and for ANY codebase

1. Ceiling, not quota. A depth raises the budget; it NEVER fabricates to hit a number. If the ranked hotspot pool has 5 modules, deep produces at most those 5 specs, never a padded count; on a sparse repo deep ≈ light. Same for cross-cutting: if only 1 candidate clears the "surface nothing over a false rule" bar, that is the output at any depth. "Prefer omission over a guess" holds in every depth. The budget is a share of real evidence — an empty pool yields an empty seed, whatever the rate.
2. "When detected", never "always." No depth has a fixed artifact checklist. data-model / integrations / config / entry-points / imports / cross-cutting appear only on positive evidence, identically across depths — a depth is defined by synthesis budget, not by mandatory docs.
3. light is never empty. Its floor rests on the universal spine — stack rule + run guide + public-surface (a library's exports, a CLI's commands, a plugin's skills, a SPA's routes) + register + the budgeted specs via the test-independent fallback ranking. At least one fires for any base (library, SPA, ML, CLI, embedded, data/IaC, agent-plugin/markdown, polyglot, monorepo); light never degrades to nothing for lack of schema/tests/authored files.
4. Depth lives in Phase B (compose), not detection. No depth branch adds a stack-specific detection heuristic; detection stays high-level, evidence-first, non-exhaustive (guarded by the detect-catalog universality test).
5. deep's extra budget flows to whatever the repo affords. No authored files → nothing to extract, so the budget goes to specs/relations that DO have evidence. deep is "more of what this repo actually has," not a fixed feature list assuming a stack shape.

Selection: the --depth flag, or the depth:<tier> toggle in the preview (Phase C) — the user can flip depth after seeing the plan and its per-depth cost, then still edit individual items.

Execution

Content voice: default to architectural prose — decisions, rationale, intent. See skills/_shared/precision-rules.md Rule 6. Code blocks only where the document type requires it (rule, guide, cpat, and spec examples) or the user asks.

Pre-flight: CLI availability check

Before any init step, verify that the Archcore CLI is available on PATH. The canonical installer is documented at https://docs.archcore.ai/cli/install/ — use it as the single source of truth; do not suggest other channels (brew, go install, etc.) even if the user mentions them.

1. Run: archcore --version (via Bash tool)
2. If it succeeds → check the host-wiring version gate with the deterministic helper (never compare versions yourself — lexical comparison breaks on double-digit fields). Resolve $d in this same Bash call (each Bash invocation is a fresh shell — nothing persists from a later step), exactly as the Step -1 probe below does: run d="${CLAUDE_SKILL_DIR:-<absolute dir of this SKILL.md>}"; "$d/../../bin/cli-gte" 0.7.0. It prints exactly one token:
   • yes → proceed immediately to Step -1 (host wiring enabled).
   • __NO_CLI__ (unexpected here — --version just succeeded) → treat as no.
   • no → the seed still works, but the host-wiring step (see "Host wiring" below) needs a newer CLI. Ask the user once:

     Archcore CLI <version> is older than v0.7.0 — host wiring (project MCP config, SessionStart hook, usage hint) will be skipped. Update now via archcore update? (y/N)

     • On y → run archcore update (Bash), re-run the cli-gte 0.7.0 check, and proceed to Step -1 (host wiring enabled on yes, disabled otherwise).
     • On N / silence → proceed to Step -1 with host wiring disabled: omit the Host wiring line from the preview, skip Phase E step 0 entirely (the cascade never runs — its manual-fallback leg is NOT a substitute for this note), and in the closing message note: "Host wiring skipped (CLI < v0.7.0) — update with archcore update, then run archcore init --agent <host> --project "<root>" in a terminal to make this repo self-contained for CLI-only teammates." (<host>/<root> come from the Step -1 probe, which runs regardless of the gate.)
3. If it fails (command not found):
   • Detect the platform via uname -s (Bash). Darwin/Linux → POSIX path. Anything else (Windows native) → instruct-only path.
   • POSIX path — ask the user once:

     Archcore CLI not found. The official installer runs:

     curl -fsSL https://archcore.ai/install.sh | bash
     

     Run it now? (y/N)

   • On y → execute the command exactly as shown (Bash tool). After it returns, re-run archcore --version.
     • Success → print: "Archcore CLI installed (<version>). Proceeding with init." → apply the same v0.7.0 comparison from item 2 (a fresh install is normally current, so host wiring is enabled) → go to Step -1.
     • Still failing → print the install message below and stop.
   • On N / silence / instruct-only path → print and stop:

     Archcore CLI required. Install it, then re-run /archcore:init:

     • macOS / Linux / WSL: curl -fsSL https://archcore.ai/install.sh | bash
     • Windows (PowerShell 5.1+): irm https://archcore.ai/install.ps1 | iex
     • Verify: archcore --version
     • Full docs: https://docs.archcore.ai/cli/install/

Do not attempt brew install, go install, package-manager wrappers, or any other install command — they are not the supported path and will produce a CLI that is not version-compatible with the plugin.

Pre-flight: gating and lazy reading

Two disciplines bind the whole run:

• Gating (write boundary). init_project() and the read-only MCP calls (list_documents, get_document) are infrastructure — they run before the preview. The gated operations are create_document, add_relation, and the host-wiring writes (install_host_config / archcore init --agent — they touch files outside .archcore/, like .mcp.json and .claude/settings.json): none fire before the user types confirm. cancel therefore leaves .archcore/ content-empty and the repo's host configs untouched (the directory and settings.json may exist from init_project, which is harmless and idempotent).
• Lazy reading (two sub-phases). The detection/extraction catalogs at _shared/grounding/*.md and the composition files at lib/*.md are heavy (≥ 1000 lines combined) — read them in two ordered batches, never all at once. The Detect sub-phase (Phase A) loads the detection catalogs and, for each detector it runs, captures into working memory both the signals AND the small ## Output create-fields + body template it will reuse later. The Compose sub-phase (Phase B) loads the composition contracts (_shared/precision-rules.md, _shared/spec-contract.md, _shared/rule-contract.md, lib/compose-overview.md, _shared/grounding/extract-routing.md) and reuses the Output fields/templates already captured during Detect — it does not re-read the bulky detection heuristics. "Release the detection catalogs" at the end of Phase A means dropping their heuristic prose from focus, not the captured Output specs.

Step -1: Initialize, detect host, and acknowledge (fast)

Call mcp__archcore__init_project() exactly once (pre-gate infrastructure — idempotent, safe on an already-initialized project). It creates .archcore/ and settings.json if missing.

Immediately after, give the user a one-line confirmation:

• Response includes initialized: true (created now) — print: "Archcore initialized at .archcore/."
• already_initialized: true — print nothing here; the existing knowledge base speaks for itself in Step 0(a).

Host + project root for wiring — always run this probe, even when host wiring is disabled by the pre-flight version gate (it is one cheap Bash call, and the disabled-path closing message still needs <host>/<root>). One Bash call:

d="${CLAUDE_SKILL_DIR:-<absolute dir of this SKILL.md>}"; host=$("$d/../../bin/detect-host"); root=$(git rev-parse --show-toplevel 2>/dev/null || pwd); printf '%s\n%s\n' "$host" "$root"

${CLAUDE_SKILL_DIR} is set by Claude Code only. On other hosts (Cursor, Codex, GitHub Copilot CLI) substitute the absolute directory of this skill file — you know it from having read this file; bin/detect-host is two directories up from it (<plugin-root>/bin/detect-host).

bin/detect-host resolves the current host from environment only (never cwd or stdin — Cursor guarantees neither) and prints exactly one token: claude-code | cursor | codex-cli | __UNKNOWN__. A GitHub Copilot CLI session always lands on __UNKNOWN__ — Copilot sets no environment marker in the shell commands it runs, so it is resolved by the question below rather than by the probe (rationale in bin/detect-host). If the probe returns __UNKNOWN__ or anything else than the three host tokens (empty output, a path error — treat all the same), ask one AskUserQuestion — "Which AI host is this session running in?" with options Claude Code / Cursor / Codex (CLI or desktop app) / GitHub Copilot CLI — and map the answer to the agent id (claude-code / cursor / codex-cli / copilot). The Codex option names both surfaces on purpose: they share one binary, one ~/.codex/config.toml and one plugin install, so codex-cli is the agent id for the desktop app too and there is no codex-desktop (codex-adapter.spec). Remember host and root for the Host wiring preview line and Phase E; do not re-run the probe.

init_project initializes only .archcore/ — host wiring (MCP config, hook, usage hint) is planned in the preview and executed in Phase E, never here. Do not run archcore init yourself at this step; the terminal path is the Phase E fallback for the user, not a pre-flight action.

Step 0: Check state and source signal

Two cheap probes, in order. Each can short-circuit the whole skill. Neither reads anything under _shared/grounding/ or lib/.

Step 0(a) — Existing documents

Call mcp__archcore__list_documents() once. Derive every flag below from local documents only — skip any result carrying global: true / read_only: true / source_kind: "global". A mounted global source may already provide a stack rule or an overview, but it must not satisfy the already-seeded early-exit: init seeds THIS repo's documents, and a repo with globals mounted but no local seed is still unseeded. If any global results appear, load skills/_shared/globals.md; never modify a global document and never target one with add_relation. Derive:

• has_stack_rule — a rule whose title contains "stack" in conventions/.
• has_run_guide — a guide whose title contains "run"/"running" in onboarding/.
• has_data_model — any doc tagged data-model.
• has_integrations — any doc tagged integrations.
• has_config — any doc tagged config.
• has_entry_points — any doc tagged entry-points.
• has_surface — any doc tagged surface.
• has_top_level_map — any doc tagged top-level-map.
• has_overview — any doc tagged architecture-overview.
• has_imports — any document tagged imported.

Already-seeded early-exit. If has_stack_rule AND has_run_guide AND has_overview are all true AND neither --refresh nor --domain was passed, reply:

Init already seeded this repo. Applicable context auto-injects on file edits via the code-alignment hook; use /archcore:review for the dashboard. To add facts that appeared since (a new schema, config, or modules), re-run /archcore:init --refresh; to drill into another domain, /archcore:init --domain=<slug>. (Seeded before host wiring existed, or missing the host configs? --refresh also adds host wiring — MCP config, SessionStart hook, usage hint.)

Then stop. With --refresh or --domain, skip this early-exit and proceed — every already-present artifact is marked skip (exists) in the preview and only missing ones are composed; the Host wiring line appears as usual (its writes are idempotent — already-wired hosts show as skip/converge). (--domain additionally scopes the run to one domain; see Step A.0.)

Step 0(b) — Source-signal gate (empty-repo early exit)

Single filesystem probe — one shell call, no catalog reads. Detect whether the repository has any executable shape yet:

• has_manifest — at least one of these exists at the project root (depth ≤ 2 for monorepo workspaces): package.json, pyproject.toml, Pipfile, requirements.txt, Cargo.toml, go.mod, Gemfile, composer.json, *.csproj, *.fsproj, *.vbproj, pom.xml, build.gradle, build.gradle.kts, mix.exs, Package.swift. This list is seed examples, not exhaustive — also treat ANY project-defining manifest or build file as a manifest (e.g. CMakeLists.txt, Makefile, dune-project/*.opam, deps.edn/project.clj, pubspec.yaml, build.sbt, stack.yaml/*.cabal, *.tf/*.tfvars, Chart.yaml, project.godot, *.sln, Project.toml, and agent/LLM-plugin manifests such as marketplace.json / plugin.json / .claude-plugin/*).
• has_top_level_source — at least one file with a recognizable source extension exists anywhere under the project root, capped at depth 3, excluding .archcore/, .git/, node_modules/, vendor/, dist/, build/, out/, target/, coverage/, .venv/, __pycache__/, .next/, .turbo/. Extensions: .ts, .tsx, .js, .jsx, .mjs, .cjs, .py, .rs, .go, .rb, .php, .java, .kt, .kts, .swift, .cs, .fs, .ex, .exs, .scala, .clj, .cljs. The extension list is seed examples, not exhaustive — also count any file whose contents are plainly source (a shebang, or import/include/package/module/def/func/class/use constructs), and recognize other common code extensions (e.g. .vue, .svelte, .astro, .dart, .c, .cc, .cpp, .h, .hpp, .m, .mm, .ipynb, .hs, .ml, .mli, .tf, .sol, .lua, .jl, .r, .zig, .nim, .gd).

If BOTH are false, take the empty route. No content seed — but host wiring still applies (an empty repo is exactly where a teammate going CLI-only needs the configs).

When host wiring is disabled by the pre-flight version gate, reply with exactly this and stop (no writes):

Archcore is ready at .archcore/. No source code detected yet — no content to seed. Host wiring skipped (CLI < v0.7.0) — update with archcore update, then re-run /archcore:init. The SessionStart empty-state nudge will keep pointing here until then.

Otherwise show a mini-preview:

Archcore is ready at .archcore/. No source code detected yet — no content to seed.

One thing worth doing now — host wiring, same files archcore init writes (makes the repo work for teammates using the CLI without this plugin):

Host wiring (<host>) → <root>
  • <per-host file list — e.g. for claude-code: .mcp.json · .claude/settings.json (SessionStart hook) · CLAUDE.md + AGENTS.md (managed block)>

confirm to write these, cancel to leave the repo untouched. Re-run /archcore:init after the first manifest or source file lands — the SessionStart empty-state nudge will keep pointing here until then.

On confirm → execute the Host wiring cascade (Phase E step 0) and stop. On cancel → stop with no writes. Either way, do NOT create placeholder documents — they have no practical value, cost roundtrips and tokens, and suppress the SessionStart empty-state nudge that is the user's breadcrumb back here.

Otherwise (has_manifest OR has_top_level_source), proceed to Phase A.

---

Phase A — DETECT (no writes; detection catalogs only)