MxInitProject

---
name: mxInitProject
description: Use when the user says "/mxInitProject", "bootstrap project", "init project", "setup ai config", "initialize claude config", "scaffold project", or otherwise wants to bootstrap a new repository with the mxLore AI-documentation structure (CLAUDE.md, docs/ layout, optional MCP project registration). Idempotent — safe to re-run. Detects MCP mode vs local fallback. NEVER overwrites existing content.
allowed-tools: Read, Write, Edit, Bash, Glob, Grep
---

# mxInitProject — Repository AI-Config Bootstrap (AI-Steno: !=forbidden ->=use CRITICAL ?=ask)

Repo bootstrap agent. Set up a scalable AI-documentation structure in the current repository without breaking existing content.

## Trigger phrases

This skill fires on:
- `/mxInitProject`
- Natural language: "bootstrap project", "init project", "setup ai config", "initialize claude config", "scaffold the repo", "add CLAUDE.md + docs structure"
- Programmatic: mxOrchestrate auto-detect can suggest this when a project lacks CLAUDE.md

## Idempotency Guarantee ⚡

This skill is **safe for repeated invocation**. Pre-flight check BEFORE all steps:

1. Glob: `CLAUDE.md` in project root → exists?
2. Glob: `docs/status.md` → exists?
3. Glob: `docs/decisions/`, `docs/specs/`, `docs/plans/`, `docs/ops/`, `docs/reference/` → exist?
4. If CLAUDE.md exists: Grep `AI Start Here` → block present?
5. If MCP mode: `mx_briefing(project)` → project registered?

**Decision matrix:**
| CLAUDE.md | AI-Start-Here | Directories | MCP-Project | status.md | Result |
|-----------|---------------|-------------|-------------|-----------|--------|
| Y | Y | Y | Y | Y | "Everything present — no changes needed." -> ABORT IMMEDIATELY |
| Y | N | Y | Y | Y | Only insert AI-Start-Here block |
| N | - | N | N | N | Full bootstrap (all steps) |
| Y | Y | Y | N | Y | Only MCP registration (section 2a MCP path) |
| any | any | any | any | any | Only create missing parts, skip existing ones |

⚡ **Section 2 contains TWO paths:** 2a is the MCP-project-registration path (runs in MCP mode), 2b is the non-MCP local-index-files path. The decision matrix row "Only MCP registration" maps to the 2a sub-path only; do NOT skip section 2 entirely in MCP mode.

⚡ **Each step individually checks whether its artifact exists → skip if yes.**
⚡ **Never overwrite, delete, or duplicate existing content.**

## Project Context / MCP Detection

MCP availability is checked as follows (in this order):

1. ⚡ Tools deferred? → load first per `~/.claude/skills/_shared/mcp-tools-load.md` (tool-missing ≠ server-down). **Call `mx_ping()`** — if successful: MCP mode (server configured globally or per project)
2. If mx_ping fails: check `.mcp.json` in project directory (fallback)
3. If both negative: non-MCP mode (local files)

**MCP mode:** Do not create local index files — the Knowledge-DB is the source of truth.
**Non-MCP mode:** Create local index files (decisions/index.md, specs/index.md, plans/index.md).

## 0. Project-specific MCP Server (optional)

Enables multi-team scenarios: different projects can use different mxLore servers.

**When to ask:** Only during initial setup (CLAUDE.md does NOT exist yet) and MCP is globally available (mx_ping OK).
**Do not ask:** On idempotency skip, in non-MCP mode, or for already configured projects.

?user: "MCP server for this project? (Enter=use global server, or enter custom URL)"

⚡ **Prompt parser robustness:** treat any of `""` (empty) / `"skip"` / `"no"` / `"n"` / `"cancel"` / EOF as "use global server" (default path). Only a non-empty string matching the URL pattern is treated as a custom URL. Never loop on ambiguous input.

**If Enter (default/global):** Continue as before — global user-scope MCP is used. Do not write `.mcp.json`, no local proxy.

**If custom URL:**
1. Validate URL (case-insensitive): must start with `https://` (or `http://` for localhost only) and end with `/mcp`. Lowercase the scheme/suffix before comparing; treat `HTTPS://...`, `https://...`, `Https://...` as equivalent.
2. Request API key: ?user: "API key for this server? (starts with mxk_)"
3. **Create proxy INI** at `.claude/mxMCPProxy.ini` in the project directory using the template at the absolute path `~/.claude/skills/mxInitProject/assets/project-mcp-ini.md`. Substitute `<URL without /mcp suffix>` and `<API-KEY>`. Fallback if asset is unreadable: write the minimal skeleton `[Server]\nBaseUrl=<URL>\nApiKey=<KEY>\nMcpEndpoint=/mcp\n\n[Agent]\nPolling=1\nPollInterval=15\n`.
4. **Proxy EXE:** Link global `~/.claude/mxMCPProxy.exe` or note the path.
5. **Create/update `.mcp.json`** in the project directory using the template at `~/.claude/skills/mxInitProject/assets/project-mcp-json.md`. Substitute the absolute proxy + INI paths. ⚡ If `.mcp.json` already exists: only add/replace the `mxai-knowledge` key, keep the rest. Fallback if asset is unreadable: write a minimal `{ "mcpServers": { "mxai-knowledge": { "command": "<exe>", "args": ["<ini>"] } } }`.
6. **Test:** Call `mx_ping()` — must reach the project-specific server.
   - Success: "Project MCP configured: <URL>"
   - Failure: Check URL/key, abort with notice.
7. Add `.claude/` to `.gitignore` (INI contains API key).

⚡ **Transparency:** After this step, all mx*-skills automatically communicate with the project server instead of the global one. No further changes needed.

## 1. Create directories (if missing)

Create these directories if they do not already exist:
- docs/decisions
- docs/specs
- docs/plans
- docs/ops
- docs/reference

## 1b. Workflow Log (non-MCP projects only)

If non-MCP mode (mx_ping failed) AND `docs/ops/workflow-log.md` does not exist, create:

```markdown
# Workflow Log

<!-- Entries are added automatically via /mxOrchestrate. Do not edit manually. -->
```

For MCP projects, workflows are stored in the DB.

## 2. Index files (non-MCP projects only)

**If MCP mode (mx_ping successful):** Do not create index files. Instead check if the project is registered in the DB:
1. Read slug from CLAUDE.md (`**Slug:**` line). If no slug: derive from directory name. Read `~/.claude/skills/_shared/slug-normalization.md` for the canonical algorithm (lowercase, `[^a-z0-9-]`->`-`, collapse, trim, ClampSlug=100). Then ask the user: "Suggested project slug: `<slug>` — does that work? (Enter=yes, or enter alternative)". Reject `..` or any path-traversal segment — fall back to "project" + random suffix and warn.
2. Call `mx_briefing(project='<slug>')`
3. If "Project not found":
   - **STOP — MUST ask the user!** Question: "Project name for `<slug>`? (e.g. 'My Project — Short description')"
   - **Wait for response.** Only THEN call `mx_init_project(slug='<slug>', project_name='<response>')`. ⚡ The `slug` parameter is REQUIRED — the server raises `EMxValidation('Parameter "slug" is required')` at `mx.Tool.Write.Meta.pas:46-47` if omitted. The server param name is literally `slug` (NOT `project_slug`).
   - **NEVER** use the slug or a self-invented name as the project name!
4. Add slug to CLAUDE.md if not already present

CRITICAL **ClampVarchar when calling mx_init_project:** `project_name` and `project_slug` are both VARCHAR-clamped server-side. Limits: `project_name` max ~200 chars (the mx_init_project server handler applies ClampTitle), `project_slug` max 100 chars (ClampSlug). Trim locally before the call and warn the user if the input would be truncated. Long values are silently clamped without error.

CRITICAL **MCP-down fallback during bootstrap:** if `mx_ping` succeeded in Phase "Project Context / MCP Detection" but then `mx_briefing` or `mx_init_project` fails mid-bootstrap (network blip, server restart), do NOT abort the whole skill. Instead:
- Continue creating local directories and docs/status.md
- Log the registration failure to docs/status.md under "Open Items": "TODO: register project in MCP (call /mxInitProject again or /mxMigrateToDb)"
- Report the partial success in the Summary Report so the user knows registration is pending

**If non-MCP mode:** Create index files from these absolute-path asset templates:
- `docs/decisions/index.md` <- `~/.claude/skills/mxInitProject/assets/index-templates/decisions.md`
- `docs/specs/index.md` <- `~/.claude/skills/mxInitProject/assets/index-templates/specs.md`
- `docs/plans/index.md` <- `~/.claude/skills/mxInitProject/assets/index-templates/plans.md`

If any asset is unreadable, fall back to a minimal `# Index\n` header so the file still exists.

## 3. Adjust CLAUDE.md

If CLAUDE.md exists: Insert an "AI Start Here" block at the TOP (after the first H1 line). Do NOT overwrite anything — insert only.

If CLAUDE.md does not exist: Create a minimal CLAUDE.md using the following template.
**IMPORTANT:** ONLY project-specific info. No global rules (security, encoding, etc.) — those are in `~/.claude/CLAUDE.md`.

### Assembly when newly creating CLAUDE.md

Templates live at absolute paths (subagent CWD trap — always use these absolute references, never relative):

- Body skeleton: `~/.claude/skills/mxInitProject/assets/claude-md-template.md`
- AI-Start-Here block (MCP mode): `~/.claude/skills/mxInitProject/assets/ai-start-here-mcp.md`
- AI-Start-Here block (non-MCP mode): `~/.claude/skills/mxInitProject/assets/ai-start-here-local.md`

Steps:
1. Detect MCP mode (mx_ping success = MCP, otherwise non-MCP).
2. Read the body skeleton and the matching AI-Start-Here block.
3. Substitute the literal `[INSERT AI-START-HERE BLOCK]` placeholder in the body with the block verbatim. Never write the placeholder string to disk.
4. Write the assembled content to `CLAUDE.md`.

⚡ Inline-skeleton fallback if any asset is unreadable: write a minimal CLAUDE.md containing only `# <ProjectName>\n\n## Project\n- **Slug:** <slug>\n- **Status:** Initialized\n` and skip the AI-Start-Here block. Report the missing asset in the Summary so the user can re-run later.

If CLAUDE.md exists: insert ONLY the matching AI-Start-Here block (after the first H1 line). Do NOT overwrite anything else.

## 4. Create docs/status.md (if missing)

If `docs/status.md` does not exist, create a minimal file:

```markdown
# Project Status

_Created via /mxInitProject_

## Implemented Features

- (none yet)

## Open Items

- (none yet)
```

## 5. Summary Report

Output a table with all created/modified files and the respective action (created / modified / already present / skipped (MCP)).

## 6. Migration (MCP projects)

If MCP mode and project registered in DB:
- Check if `docs/status.md` contains migratable task lists (backlog, ToDo, open tasks, etc.)
  - If yes: emit a recommendation in the Summary Report: `Recommendation: run /mxMigrateToDb --extract-backlog to migrate the N legacy backlog entries detected in docs/status.md.` Do NOT auto-invoke — this skill runs as a subagent and cannot spawn nested subagents, plus the user should see the migration report separately.
  - If no task lists: "No legacy backlogs found — extraction skipped."
- Check if `docs/` contains local .md files (PLAN-*, SPEC-*, ADR-*, session-notes-*)
  - If yes: emit a recommendation: `Recommendation: run /mxMigrateToDb --sync to import N local documents into the Knowledge-DB.`
  - If no migratable files: "No local documents found for migration."

## Important Rules

- **Never** overwrite or delete existing content
- **Never** create files that already exist (only check and report "already present")
- For CLAUDE.md ONLY insert the "AI Start Here" block if it is not already present
- All files in UTF-8 without BOM
- **Idempotency:** On repeated invocation, abort immediately if everything is present (pre-flight check)
- **Summary report ALWAYS:** Even on immediate abort, output the table with status "already present"
- CRITICAL **Mirror sync:** Read `~/.claude/skills/_shared/mirror-sync.md` for the canonical 3-mirror cp + md5 verify protocol.