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:

⚡ 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. 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: "
   • 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:

# 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 (Bug#2889) 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:

# 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.