ai-project-init

AI Project Init

Thin orchestrator. Three subagents do the substantive work; this file wires them together with the staging/marker/promote infrastructure.

The skill ships no project opinions. There are no pre-built packs, no atomic-design vocabulary, no template variables that pretend a project's organization. Whatever rules, slash commands, agents, and MANIFEST schema land in the user's project, the rules-author wrote from scratch on top of evidence the project-analyzer surfaced from this specific codebase.

Pipeline

Phase 0  Mode + marker check          (orchestrator only)
Phase 1  project-analyzer subagent →  analysis JSON
Phase 2  Plan review with user        (orchestrator only)
Phase 3  Copy generic shared assets   (orchestrator + substitute.py)
Phase 4  rules-author subagent     →  staging tree
Phase 5  realism-verifier subagent →  pass / fail report
         ↓ fail → Phase 4 again with corrections (max 2 retries)
Phase 6  validate.py structural gate  (orchestrator)
Phase 7  Atomic promote to project    (orchestrator)

The subagents live as installed agent definitions under .claude/agents/ once the skill itself is on the user's machine; before that, the orchestrator can locate them under <this-skill>/assets/shared/claude/agents/{project-analyzer,rules-author,realism-verifier}.md and invoke them with the Agent tool.

Inputs

Before invoking the analyzer, gather:

Input	How to get it
Target project root	Folder must be mounted. Use request_cowork_directory if not yet mounted.
Mode	Auto-detected in Phase 0; user confirms.
Language preference	If the user spoke Serbian, the rules-author writes descriptive prose in Serbian. If English, English. Pull from this conversation.
Existing AI configs	Listed by the analyzer — surfaced to the user before promote.

Never guess paths, package names, or stack details. Those come from the analyzer.

Phase 0 — Mode + marker

1. Confirm the workspace is mounted. If not, request_cowork_directory.

2. Marker check. If <root>/.claude/.installed exists, the skill has run before. Read the marker JSON (version, installed_at, mode, analysis_summary, files_written) and offer upgrade / reinstall / verify-only / abort via AskUserQuestion. Default: upgrade. See references/idempotency-and-rollback.md.

3. Mode detection.

   • New project — package.json (or equivalent) has only framework deps, no source folders, no existing .claude/, no AGENTS.md → likely new.
   • Existing (retrofit) — meaningful source already present, OR existing .claude/, OR existing AGENTS.md/MANIFEST.md → retrofit.
   • The analyzer will refine this later; the orchestrator just picks the user-facing label.

4. Collision check on un-marked files. If AGENTS.md, CLAUDE.md, MANIFEST.md, or .mcp.json exist outside any marker's files_written list (or there's no marker), stop and ask per file. The user may have hand-edited.

5. Confirm the detected mode + outline the next phases. Match the user's language.

Phase 1 — project-analyzer

Spawn the project-analyzer subagent. Pass:

• target_root = absolute project path
• output_path = /tmp/ai-init-<random>/analysis.json (or any temp path outside the project)
• The user's language preference (so the analyzer notes it for rules-author)

The analyzer is read-only. It walks manifests, configs, README, sample sources, existing AI configs, and emits a single JSON describing the project + its recommendations. See assets/shared/claude/agents/project-analyzer.md for the full contract.

When the analyzer finishes:

1. Read its JSON.
2. If analysis.warnings includes a hard problem (no manifest at all, unparseable configs, no source code), surface to user and ask how to proceed.
3. If analysis.open_questions is non-empty, ask the user the most load-bearing 1–3 questions before continuing. Patch the analysis JSON with the answers.

Optional research patch. When analysis.open_questions involves an unfamiliar framework version or library convention, run the 4-tier fallback chain in references/research-best-practices.md (Tavily MCP → Context7 → curated WebFetch allow-list → WebSearch → skip + record gap). Distill any findings into 2–5 bullets and append them to the analysis JSON under external_research. The skill never blocks waiting for research.

Phase 2 — Plan review

Show the user a concise digest:

• One-paragraph project summary (analysis.summary).
• Detected stack (one line).
• Mode + language.
• Recommended rules (count + filenames).
• Recommended slash commands (count + names + trigger phrases).
• Recommended agents (count + names).
• MANIFEST schema (layer count + names).
• Existing AI configs found (with one-line each).
• Open questions still unresolved.

AskUserQuestion with options:

• Approve plan — proceed to authoring.
• Refine — user lists rules/commands/agents to drop or add, plus any preferences (different MANIFEST schema, additional command, alternative naming). Patch the analysis JSON; re-display.
• Abort — stop without writing anything.

Repeat until approve or abort.

Phase 3 — Copy generic shared assets to staging

All writes go to <root>/.claude/.staging/ first. See references/idempotency-and-rollback.md.

The shared assets (assets/shared/) are truly generic — no atomic-design vocabulary, no UI-specific framing, no project-specific paths. They are:

Source	Target	Purpose
assets/shared/CLAUDE.md	<root>/CLAUDE.md	Re-export pointing at AGENTS.md
assets/shared/mcp.json	<root>/.mcp.json	MCP servers (Context7 + optional research servers)
assets/shared/claude/settings.json	<root>/.claude/settings.json	Minimal generic baseline — model, env, neutral permissions, statusline. No project-specific Bash/WebFetch entries; rules-author appends per-project allow-list entries derived from analysis.project.scripts and analysis.stack.
assets/shared/gitignore-patches.txt	appended to <root>/.gitignore	Adds .claude/plans/, .claude/.cache/, .claude/.staging/, .claude/.staging-old/
assets/shared/claude/scripts/statusline.sh	<root>/.claude/scripts/statusline.sh	Status line script (chmod +x)

These are the only files the orchestrator copies directly. Everything else (rules, commands, agents, AGENTS.md, MANIFEST.md) is authored by the rules-author.

The shared assets contain a small number of generic placeholders that substitute.py fills:

• {{PROJECT_NAME}} — from analysis.project.name
• {{PACKAGE_MANAGER}} — from analysis.project.package_manager
• {{CLAUDE_MODEL}} — defaults to claude-sonnet-4-6 unless the user overrides

After substitute, grep -r '{{[A-Z_]\+}}' over staging must return empty for the shared subset.

Phase 4 — rules-author

Spawn the rules-author subagent. Pass:

• analysis_path — the analysis JSON from Phase 1 (with any user refinements + research notes)
• staging_root — <root>/.claude/.staging/
• target_root — the project root (read-only access for sample re-reads)

The rules-author writes AGENTS.md, MANIFEST.md, .claude/rules/<topic>.md per recommended rule, .claude/commands/<name>.md per recommended command, .claude/agents/<name>.md per recommended agent. Every file is written from scratch with real paths, aliases, and packages — no template substitution. See assets/shared/claude/agents/rules-author.md for the full contract.

When rules-author finishes:

1. Read its summary (file count + bytes + dropped recommendations + reasoning).
2. Skim 2–3 of the staged rule files to confirm they read like a senior engineer wrote them, not a templating engine. If they look templated, abort and reinvoke with stricter guidance.

Phase 5 — realism-verifier

Spawn the realism-verifier subagent. Pass:

• staging_root — <root>/.claude/.staging/
• target_root — the project root
• analysis_path — same JSON from Phase 1
• output_path — /tmp/ai-init-<random>/verification.json

The verifier is read-only. It walks every staged file and checks: paths exist (test -e), aliases resolve (against tsconfig.json or equivalent), packages exist in the project's manifest, command targets are realistic, no contamination vocabulary (literal blocklist + allowlist diff), no {{VAR}} leftovers, no broken cross-refs. See assets/shared/claude/agents/realism-verifier.md for the full contract.

Verdict handling:

• verdict: "pass" — proceed to Phase 6.
• verdict: "fail" — re-spawn rules-author with the verifier's report attached as corrections_path. Allow up to 2 retries. After the second failure, abort the install and surface the remaining issues to the user; staging stays in .claude/.staging/ for inspection but nothing is promoted.

The verifier may also surface warn-severity issues. Show those to the user before promote and let them choose proceed / re-author / abort.

Phase 6 — validate.py (structural)

Run scripts/validate.py against the staging directory:

python <skill>/scripts/validate.py --root <project-root> --staging --json

The script handles mechanical checks the verifier doesn't:

• Required files present (AGENTS.md, CLAUDE.md, .mcp.json, .claude/settings.json)
• Required directories present (.claude/{commands,rules,agents})
• Hook scripts are executable
• settings.json and .mcp.json are valid JSON
• No {{VAR}} placeholders remaining anywhere (including subagent-authored files)
• CLAUDE.md references @AGENTS.md
• Install marker plan is well-formed

If exit code is non-zero, surface failing checks. If reparable (e.g. forgot chmod +x), fix in place; otherwise re-author.

Phase 7 — Promote staging to final paths (atomic)

Only after Phase 5 + Phase 6 both pass:

1. For each file in <root>/.claude/.staging/, compute its final destination.
2. If the destination exists and is not in the install marker's files_written, the user has hand-edited; ask before clobbering.
3. Otherwise back up the existing file to <root>/.claude/.staging-old/<rel-path> and move the staged file into place.
4. Patch <root>/.gitignore if not already patched (idempotent — only add lines not already present).
5. Write <root>/.claude/.installed with version, installed_at, mode, analysis_summary (a short slice of the analysis), files_written, template_hashes. See references/idempotency-and-rollback.md.
6. Leave .claude/.staging-old/ for one run cycle so the user can compare; clean up on the next successful run.

Final reply to the user: a short summary of what landed (rule count, command count, agent count, MANIFEST schema), the marker contents, and a ready-to-use trigger phrase from one of the slash commands.

Optional Phase 8 — Seed MANIFEST (retrofit only)

For projects with existing source, scripts/seed_manifest.py can scan the layers the rules-author chose and propose entries to populate MANIFEST.md. This is after promote and opt-in — ask the user.

python <skill>/scripts/seed_manifest.py --root <project> --layers <layer-paths-from-analysis> --output /tmp/manifest-seed.json

The script is regex-based (TS/TSX export scanner; safe defaults for other languages). Surface entries in batches of ~10 via AskUserQuestion; the user approves/edits/skips per entry; the orchestrator appends approved entries under the right layer in MANIFEST.md. See references/manifest-seeding.md.

If the project's MANIFEST schema is non-TypeScript (Python, Go, Rust, etc.), seed_manifest.py reports it can't help and the user populates the manifest manually or via a future seed-script.

Upgrade mode (re-running on a marker'd project)

When Phase 0 finds an existing .installed marker and the user picked upgrade:

1. Re-run analyzer fresh — the project may have grown new layers since last install.
2. Diff the new analysis against the marker's stored analysis_summary. Surface what changed to the user (new layers, new dependencies, new sample patterns).
3. For each previously-installed file, run scripts/upgrade.py to compute three-way diff:
   • unchanged — skip.
   • user_edited_only — preserve user copy; report.
   • template_changed_only — propose overwrite.
   • three_way — show diff and ask.
   • added (new recommendation) — write to staging, run verifier on it.
   • removed (no longer recommended) — propose deletion.

See references/idempotency-and-rollback.md for the full upgrade contract.

Notes on language and tone

Match the user's language. Serbian (Latin) and English mix freely; both are fine. Keep technical terms and identifiers in English (MANIFEST.md, staging, analyzer, verifier, tsconfig.json).

Match the user's brevity. The substantive content is in the rule files the rules-author wrote; the orchestrator's job is to install them, not re-explain them.

Reference files

• references/idempotency-and-rollback.md — install marker, staging directory, rollback contract, upgrade three-way diff.
• references/manifest-seeding.md — auto-scan algorithm + seed_manifest.py contract.
• references/research-best-practices.md — 4-tier fallback chain (Tavily → Context7 → WebFetch → WebSearch → skip).
• references/research-fallback-urls.md — curated WebFetch allow-list per stack.
• references/manifest-shape-example.md — one example of how a populated MANIFEST might look. Labelled as illustrative; not a template.

Scripts

The skill is intentionally script-light. Subagents do the substantive authoring; scripts handle only the mechanical, testable parts.

• scripts/substitute.py — Phase 3 parameter substitution + <!-- if FLAG --> conditional fences. Used only for the small set of generic shared assets.
• scripts/seed_manifest.py — Optional Phase 8 retrofit MANIFEST seeding (regex TS/TSX scanner).
• scripts/validate.py — Phase 6 mechanical checks.
• scripts/upgrade.py — Upgrade-mode three-way diff per file.

Subagent definitions

• assets/shared/claude/agents/project-analyzer.md — read-only project introspector. Emits the analysis JSON.
• assets/shared/claude/agents/rules-author.md — staging-only authoring agent. Writes rules, commands, agents, AGENTS.md, MANIFEST.md from scratch using analyzer evidence.
• assets/shared/claude/agents/realism-verifier.md — read-only gate. Confirms paths exist, aliases resolve, packages are real, no contamination, no leftover placeholders.

Asset files

assets/shared/ holds the truly generic files that ship verbatim into every install. Anything project-specific is authored by the rules-author at install time.