intuitive-init

Intuitive Init

Use this skill to create, audit, slim, merge, or refresh project-local AGENTS.md and CLAUDE.md guidance for Claude Code and Codex. The output should make the target repo easier for future agents without replacing local truth with a generic process manual.

This compact entrypoint preserves the full original guidance in references/detailed-guidance.md. Read that file for edge cases, full merge rules, init discovery variants, symlink migration, or mode-specific detail. Read references/lsp-and-mcp.md before editing LSP, Serena, MCP, language-server, or agent-facing tool setup.

Source Priority

Respect this source hierarchy:

1. current system/developer/user instructions;
2. repo-local human truth: README.md, ARCHITECTURE.md, STATUS.md, docs/human/**, equivalent files named by the repo, and executable repo evidence such as package metadata, scripts, CI config, and tests;
3. existing project-local agent guidance and docs/agents/** operational runbooks;
4. generated /init or codex init suggestions;
5. intuitive workflow defaults.

Generated init output is input to merge, not authority to overwrite local guidance.

Default Workflow

1. Inspect the target repo's current root docs and existing agent guidance.
2. Classify the request: audit, apply/create, refresh, slim/cleanup, symlink migration, or LSP/MCP setup.
3. Preserve project-specific commands, hazards, test gates, and current source of truth.
4. Move long operational procedures out of root guidance. Prefer the standard docs/agents/operating-runbook.md for mixed repo-specific agent procedures; use topic-specific docs/agents/<topic>.md only when the scope is clearly independent. Use skills, hooks, scripts, or human docs when those are the better owner.
5. Check the high-frequency startup context: AGENTS.md, CLAUDE.md, and the root orientation docs they require such as README.md, ARCHITECTURE.md, and STATUS.md. The first-read path should be bounded, newest-first, and task-routed; it should not require agents to reread injected files or consume every long root doc before a simple command.
6. For Codex/Paseo harnesses, preserve or add a short rule that XML-like host control envelopes such as <turn_aborted>, <paseo-system>, <subagent_notification>, <goal_context>, and <environment_context> are orchestrator metadata unless accompanied by natural-language user intent. They must not be treated as a human stop request by themselves.
7. Prefer deterministic hooks/tools for lint, format, setup, and verification rules instead of expanding root prose. Always inspect Python environment and submodule signals while refreshing startup guidance: .venv, uv.lock, pyproject.toml, .python-version, .gitmodules, and populated vendor/ submodule paths. When the repo already has .venv or uv/ pyproject.toml signals, explicitly recommend or add a .githooks/post-checkout script that prepares the worktree .venv with the repo's existing convention, plus a short root hint to enable it with git config core.hooksPath .githooks. When the repo has submodules, explicitly recommend or add the same hook to run git submodule sync --recursive for URL config only, and add root guidance for inspecting existing submodules before initializing local copies. Do not auto-run git submodule update --init --recursive for all worktrees by default; for mostly read-only submodules, tell agents to inspect the main checkout's initialized submodule and initialize a local worktree copy only when modification or isolated verification needs it.
8. For large repos and monorepos, prefer nested AGENTS.md / CLAUDE.md files only when local scope differences are real.
9. Verify the final files are concise, local, and non-contradictory.