feat: improve boostrap speed on empty project

Author: ivklgn

.archcore/.sync-state.json

@@ -3216,6 +3216,21 @@
       "source": "plugin/codex-path-resolution.adr.md",
       "target": "plugin/codex-host-support.prd.md",
       "type": "related"
+    },
+    {
+      "source": "plugin/codex-mcp-cwd-rebase-to-user-project.idea.md",
+      "target": "plugin/codex-path-resolution.adr.md",
+      "type": "extends"
+    },
+    {
+      "source": "plugin/codex-mcp-cwd-rebase-to-user-project.idea.md",
+      "target": "plugin/codex-local-plugin-testing.guide.md",
+      "type": "related"
+    },
+    {
+      "source": "plugin/codex-mcp-cwd-rebase-to-user-project.idea.md",
+      "target": "plugin/bundled-cli-launcher.adr.md",
+      "type": "related"
     }
   ]
 }

.archcore/plugin/codex-mcp-cwd-rebase-to-user-project.idea.md

@@ -0,0 +1,50 @@
+---
+title: "Codex MCP — User-Project CWD Without Shell-Resync"
+status: draft
+tags:
+  - "codex"
+  - "multi-host"
+  - "plugin"
+---
+
+## Idea
+
+Restore the archcore MCP server's working directory to the user's project root when invoked from Codex, **without** depending on the inherited `$PWD` env var (which POSIX shells overwrite at startup).
+
+Codex spawns plugin MCP servers from the plugin install dir (via `.codex.mcp.json` `cwd: "."` rebase). The launcher itself is a `#!/bin/sh` script, so any `$PWD` value Codex inherits from the user's shell is **erased on launcher startup** — POSIX shells (sh, dash, bash --posix) resync `$PWD` to match `getcwd()` if the two diverge. That kills the obvious "follow `$PWD`" workaround.
+
+Two viable paths that survive sh's PWD-resync:
+
+1. **An explicit env var the shell does NOT resync** — e.g., `ARCHCORE_CWD` (or `CODEX_PROJECT_DIR`, if Codex ever exposes one). The launcher reads it before exec'ing the real CLI:
+
+    ```sh
+    if [ -n "${ARCHCORE_CWD:-}" ] && [ -d "$ARCHCORE_CWD" ]; then
+      cd "$ARCHCORE_CWD" 2>/dev/null || true
+    fi
+    ```
+
+    Sh's PWD-resync only touches `PWD` and `OLDPWD`. A custom name passes through untouched. The cost: someone (Codex, or the user) has to set it. Until Codex exposes a canonical name, the user opts in per-session.
+
+2. **archcore CLI argument** — `archcore --project-root=PATH mcp`. Lets Codex (or a future plugin manifest version) pass the path explicitly. Doesn't require a custom env var, but does require Codex to thread an argument through MCP `args`. As of Codex 0.130.0 there is no env substitution in `args`, so this only helps if upstream adds it (openai/codex#19582).
+
+## Value
+
+Today, calling any `mcp__archcore__*` tool from Codex creates `.archcore/` documents in `~/.codex/plugins/cache/<marketplace>/archcore/<version>/.archcore/` instead of the user's project. Observed during a Codex `/archcore:bootstrap` session against `test_project/`: two seed docs landed in the plugin cache before the agent gave up and started a manual MCP rooted at the project. ~9m41s of confused wallclock.
+
+Closing this gap turns Codex into a first-class Archcore host. Without the fix, the bundled-launcher value-prop of "no global install needed" silently degrades for Codex users — every MCP write pollutes the cache.
+
+## Possible Implementation
+
+1. **Add `ARCHCORE_CWD` support in `bin/archcore`** — guarded `cd "$ARCHCORE_CWD"` near the top of the launcher (after `SCRIPT_DIR=...` resolution), with `[ -d ]` and `cd ... || true` safety. Unit-tested via the existing Bats pattern (env var → fake `ARCHCORE_BIN` stub → assert stub's `pwd` output).
+2. **Diagnostic mode for env discovery** — `archcore mcp --debug-env` that streams a single JSON-RPC notification listing all `getenv` keys the MCP server sees at startup. Run it once from a real Codex session to identify which env vars Codex actually injects (PLUGIN_ROOT, CODEX_HOME, CODEX_CWD, ...). If a Codex-provided user-project var exists, switch the launcher to read it first; fall back to `ARCHCORE_CWD`.
+3. **Document the contract** in `codex-local-plugin-testing.guide.md` step 8 — add an assertion that an MCP `create_document` call from `mktemp -d` creates files under that tmpdir, **not** under `~/.codex/plugins/cache/...`. Pin the contract with a Bats E2E test if feasible.
+4. **Upstream issue** — file or watch openai/codex#19582 for `${PLUGIN_ROOT}` MCP substitution. Once shipped, drop `cwd: "."`, use `${PLUGIN_ROOT}/bin/archcore` directly, and Codex inherits the user's CWD by default — both legs become unnecessary.
+5. **One-time cleanup utility** — `archcore mcp cleanup-cache` that removes stray `.archcore/` directories that may have landed under `~/.codex/plugins/cache/<marketplace>/archcore/<version>/` before this fix shipped. Opt-in.
+
+## Risks and Constraints
+
+- **POSIX `$PWD`-resync is non-negotiable.** Verified across `/bin/sh`, `dash`, and `bash --posix` on macOS: each rewrites `$PWD` to match `getcwd()` on every shell startup when they disagree. Any fix that depends on the kernel-inherited `$PWD` is moot in a shell-script launcher.
+- **`ARCHCORE_CWD` is opt-in.** Users who don't set it stay in the broken state. Mitigation: surface a clear "your MCP CWD looks like a plugin cache; set `ARCHCORE_CWD` to your project" warning when archcore CLI detects `getcwd()` matches a plugin-cache pattern (e.g., contains `/plugins/cache/` or `/plugin-install/`). Don't refuse to operate — too disruptive — but make the next step obvious.
+- **Codex env vars may not exist for MCP spawns.** The existing `codex-path-resolution.adr` confirms `${PLUGIN_ROOT}` is injected for hooks but says nothing about MCP. Step 2 (diagnostic mode) is the way to find out. Do this before committing to `ARCHCORE_CWD` as the canonical name.
+- **Cross-host concern.** Claude Code uses `${CLAUDE_PLUGIN_ROOT}/bin/archcore` with no chdir, so `$PWD == $(pwd)` and the issue doesn't surface. Cursor and other hosts may behave like Codex or like Claude — verify each before extending.
+- **Naming.** If we name our env var `ARCHCORE_CWD`, that mirrors `ARCHCORE_BIN` already used by the launcher. Alternative `ARCHCORE_PROJECT_ROOT` is more explicit. Stick with `ARCHCORE_CWD` for brevity unless a survey of other plugins' conventions argues otherwise.

skills/bootstrap/SKILL.md

@@ -29,16 +29,17 @@ First-time onboarding. Detects repo scale (small / medium / large) and seeds sca
 
 ## Routing table
 
-**Mode routing** — Step 0.5 classifier, evaluated top-to-bottom, first match wins. Precise conditions in `lib/detect-scale.md`.
+**Mode routing** — Step 0.5 classifier, evaluated top-to-bottom, first match wins. The **empty** route is decided earlier in Step 0(b) and short-circuits the classifier entirely. Precise conditions for the rest in `lib/detect-scale.md`.
 
 | Signal | Route | Seeded artifacts |
 |---|---|---|
+| No manifest AND no top-level source (Step 0b) | → **empty** | none — acknowledge-only, no placeholder docs |
 | `--mode=X` flag | → forced `X` (detected mode still reported) | per row below |
 | `domain_count ≤ 1` AND `module_count ≤ 15` | → **small** | stack rule, run guide |
 | `domain_count ≤ 2` AND `module_count ≤ 40` | → **medium** | small + entry-point inventory |
 | `domain_count ≥ 3` OR `module_count > 40` | → **large** | medium + top-level map + domain dialog |
 
-Each mode additionally runs hotspot capture-candidate proposal (Step 6) and optional agent-file import (Step 8). Medium additionally runs cross-cutting rule candidate (Step 7).
+Each non-empty mode additionally runs hotspot capture-candidate proposal (Step 6) and optional agent-file import (Step 8). Medium additionally runs cross-cutting rule candidate (Step 7). The empty route exits after Step 0.
 
 **Follow-up routing** — closing-message hand-offs. Bootstrap surfaces these as todos; MUST NOT auto-invoke.
 
@@ -54,15 +55,28 @@ Each mode additionally runs hotspot capture-candidate proposal (Step 6) and opti
 
 ## Execution
 
-### Step -1: Ensure initialization
+### Pre-flight: lazy reading
 
-Call `mcp__archcore__init_project()` before any other MCP operation. It is idempotent — safe on an already-initialized project (returns existing settings). It creates `.archcore/` and the settings file if they do not exist.
+Bootstrap MUST give the user fast feedback. The detection catalogs under `skills/bootstrap/lib/` are heavy (≥ 350 lines for scale alone) and they are read **lazily**: do NOT open any `lib/*.md` file until you reach the step that explicitly tells you to read it. Step 0 finishes before any `lib/` file is opened.
+
+### Step -1: Initialize and acknowledge (fast)
+
+Call `mcp__archcore__init_project()` exactly once. It is idempotent — safe on an already-initialized project (returns existing settings). It creates `.archcore/` and `settings.json` if missing.
+
+Immediately after the call, give the user a one-line confirmation so they see something tangible without waiting for any detection:
+
+- If the response includes `initialized: true` (created now) — print: *"Archcore initialized at `.archcore/`."*
+- If `already_initialized: true` — print nothing here; the existing knowledge base will speak for itself in Step 0(a).
 
 Do NOT ask the user to run `archcore init` in the terminal — `mcp__archcore__init_project` is the correct path in a plugin session.
 
-### Step 0: Check state
+### Step 0: Check state and source signal
 
-Call `mcp__archcore__list_documents()`. Derive:
+Two cheap probes, in order. Each can short-circuit the whole skill. Neither reads anything under `lib/`.
+
+#### Step 0(a) — Existing documents
+
+Call `mcp__archcore__list_documents()` once. Derive:
 
 - `has_stack_rule` — any `rule` whose title contains "stack" in `conventions/`.
 - `has_run_guide` — any `guide` whose title contains "run" or "running" in `onboarding/`.
@@ -76,7 +90,22 @@ If `has_stack_rule` AND `has_run_guide` are both true, reply:
 
 Then stop. Per-step idempotency checks (below) handle mode-specific artifacts when the user asks for a selective refresh.
 
-Otherwise proceed to Step 0.5.
+#### 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`.
+- **`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`.
+
+If BOTH are false, take the **empty** route. Reply with exactly:
+
+> Archcore is ready at `.archcore/`. No source code detected yet — nothing to bootstrap.
+>
+> Re-run `/archcore:bootstrap` after the first manifest or source file lands. The SessionStart empty-state nudge will keep pointing here until then.
+
+Then stop. **Do NOT** create placeholder documents (no "no stack selected yet" rule, no "no run command yet" guide). They have no practical value, they cost MCP roundtrips and tokens, and they suppress the SessionStart empty-state nudge — which is the user's primary breadcrumb back to bootstrap once code actually exists.
+
+Otherwise (`has_manifest` OR `has_top_level_source`), proceed to Step 0.5.
 
 ### Step 0.5: Detect scale
 
@@ -299,8 +328,9 @@ Always end with:
 
 Mode-appropriate `.archcore/` seed:
 
+- **Empty**: 0 seeded — `.archcore/` and `settings.json` only. Fast acknowledge + early exit. No catalog files read.
 - **Small**: 2 seeded (`rule`, `guide`) + 3 hotspot proposals.
 - **Medium**: 3 seeded (`rule`, `guide`, entry-point `doc`) + 5 hotspot proposals + ≤ 1 cross-cutting rule candidate.
 - **Large**: 4 seeded (`rule`, `guide`, top-level-map `doc`, entry-point `doc`) + domain selection + 3-per-domain hotspot proposals.
 
-All seeds idempotent. Agent-file import is opt-in and previewed.
+All seeds idempotent. Agent-file import is opt-in and previewed. The empty route never creates placeholder documents — it keeps `.archcore/` functionally empty so the SessionStart nudge continues pointing the user back here.

test_project/.archcore/settings.json

@@ -0,0 +1,3 @@
+{
+  "sync": "none"
+}