intuitive-init - SKILL.md Agent Skill

name: intuitive-init description: Initialize, audit, aggressively slim, merge, and refresh project-local AGENTS.md and CLAUDE.md files from existing repo guidance, agent /init suggestions, stdin-bundled Codex init-style discovery, and intuitive workflow defaults, including target-repo LSP and agent-facing Serena MCP setup. Use when setting up a repo for Claude Code/Codex, replacing symlinked agent files with local guidance, rerunning agent init after weeks of drift, cleaning overgrown root agent files, or aligning a repo to intuitive-doc, intuitive-tests, intuitive-flow, intuitive-refactor, and intuitive-reduce-entropy without overwriting project-specific hints. When the user asks to "setup LSP" for a coding-agent repo, treat Serena MCP as the preferred agent-facing LSP path unless it is already configured or concretely blocked.

Intuitive Init

Set up repo-local AI agent guidance without turning shared defaults into a symlinked source of truth. Shared skills should travel across projects; AGENTS.md and CLAUDE.md should preserve the local repo's commands, constraints, workflow choices, and hard-won mistakes.

In Claude Code and Codex work, a repo harness is the infrastructure that lets an agent enter an existing project without guessing: root and nested instruction files, reusable skills, hooks, MCP configuration, target-repo LSP setup, and local verification commands. $intuitive-init builds or refreshes that harness from repo evidence, official tool guidance, and init-style suggestions.

Default posture: keep root agent files aggressively small. Correct but lengthy procedures should usually move out of AGENTS.md and CLAUDE.md into docs/agents/**, reusable skills, or scripts, with the root files keeping only the rule, trigger, and pointer.

Use these size signals:

Target: each root agent file is short enough to skim before work starts, usually under 120 lines.
Warning: over 180 lines means audit should report bloat and propose deletes or extraction.
Strong cleanup signal: over 250 lines, duplicated sections between AGENTS.md and CLAUDE.md, or long numbered procedures in root files.

These are signals, not hard limits. Keep a longer root file only when the content is a critical safety rule that agents must see before any other read.

Official Reference Sources

Prefer current official docs when refreshing a repo harness:

Claude Code best practices: https://code.claude.com/docs/en/best-practices
Claude Code memory and CLAUDE.md loading: https://code.claude.com/docs/en/memory
Claude Code docs map: https://code.claude.com/docs/en/claude_code_docs_map
Claude blog guide for CLAUDE.md: https://claude.com/blog/using-claude-md-files
Codex best practices: https://developers.openai.com/codex/learn/best-practices
Codex AGENTS.md guide: https://developers.openai.com/codex/guides/agents-md
Codex advanced configuration: https://developers.openai.com/codex/config-advanced
Open AGENTS.md format: https://agents.md/

Use those sources as references, not as replacement text. Local repo evidence still wins when the docs and the actual project disagree.

Human/Agent Surface Rule

The default human-facing source of truth is intentionally small:

README.md
ARCHITECTURE.md
STATUS.md
docs/human/**

AGENTS.md and CLAUDE.md are agent-operational docs. Use them for startup rules, local hazards, command pointers, and skill routing, but do not treat them as human-authoritative project truth by default.

Agent planning, generated evidence, history, and working notes belong in explicit agent/process surfaces such as .planning/**, docs/plans/**, docs/retrospectives/**, docs/status/active/**, and output/** unless a human doc intentionally promotes a specific artifact into current truth.

AI coding docs are agent/process-facing docs that help future coding agents but do not need to be human project truth. Prefer docs/agents/** for durable agent runbooks, repo-specific coding procedures, tool quirks, and long harness notes. Prefer .planning/**, docs/plans/**, docs/retrospectives/**, docs/status/active/**, and output/** for execution state, plans, retrospectives, generated evidence, and proof artifacts.

Agent files may point to human-authoritative docs and say how agents should react when those docs conflict with a request. Do not copy milestone goals, non-goals, steering policy, documentation taxonomy, or other human-facing project state into agent files. Those copied blocks drift after $intuitive-doc cleans or reorganizes the human surface.

Agent Reference File Boundary

Use docs/agents/** for repo-specific agent reference material that is too long for the root files but still useful to coding agents.

Good candidates for docs/agents/**:

release procedures
CI failure investigation runbooks
dependency/bootstrap playbooks
GPU, simulator, cloud, or hardware setup notes
PR review/fix workflows
model/tool-specific caveats
long examples and copy/paste command checklists

Prefer a reusable skill when the procedure applies across repos. Prefer a script, Makefile target, or just recipe when the procedure is mostly commands. Prefer human docs when the information is project truth for humans, not agent operation.

Root AGENTS.md and CLAUDE.md should contain only:

the first docs to read
critical local hazards and permissions
canonical install/test/verify commands or the pointer to them
source-of-truth boundaries
short skill routing
pointers to longer docs/agents/** runbooks when needed

Compatibility Posture

Prefer live-at-HEAD behavior and forward migration over backward compatibility. Treat legacy, compatibility, old command aliases, stale transitional docs, and preserved historical surfaces as cleanup signals, not as things to keep automatically.

When the change is scoped, remove or replace obsolete paths and update their tests/docs in the same pass. If removing obsolete paths would touch a broad command surface, install/update behavior, generated outputs, public docs, or many files, propose the forward migration/removal plan; do not preserve a compatibility layer as the architecture default.

Use a practical WHY / WHAT / HOW shape for the root files:

WHY: the project purpose and why the main modules exist
WHAT: the tech stack, package layout, and important directory map
HOW: install, build, test, verification, and safe change workflow

Keep lint and format policy out of root guidance unless there is a local hazard agents cannot infer. Put deterministic enforcement in formatter/linter config, scripts, CI, or hooks, and point agents to the command or hook instead.

For large repos, prefer nested CLAUDE.md and AGENTS.md files near specialized areas such as src/api/, services/payments/, or individual packages. The root file should explain the layering rule and the local override convention, not carry every package's full procedure.

When MCP servers are part of the team workflow, prefer a checked-in .mcp.json or equivalent project-scoped config so new clones get the same tool wiring. Never put secrets in committed MCP config; point to environment variables or local setup docs for credentials.

Target-Repo LSP Setup

Set up language server support as part of repo harness initialization when the task reaches Apply, Refresh, or Symlink Migration mode, or when the user asks for coding-agent LSP/MCP setup directly. Read references/lsp-and-mcp.md before editing LSP, Serena, MCP, language-server, or related dependency/config surfaces.

The short rule: verify the repo-local language-server config first, then verify, configure, or propose an agent-facing MCP symbol surface, preferably Serena, unless it is already covered or concretely blocked. Stop and report instead of editing when setup would require paid services, local-only hardware, broad toolchain migration, heavy installs, global secrets, or uncertain global state.

Core Rule

Treat generated init output and Intuitive Flow defaults as reviewers, not authority.

Authoritative inputs, in order:

System/developer/user instructions for the current session.
Existing project-local AGENTS.md and CLAUDE.md.
Root orientation docs such as README.md, ARCHITECTURE.md, STATUS.md, docs/agents/**, and command docs.
Actual repo commands, scripts, package metadata, CI config, and tests.
Agent /init, codex init when available, or stdin-bundled init-style discovery from a read-only Codex run.
Intuitive Flow defaults and skill-routing conventions.

/init, codex init when the installed Codex interface exposes it, and similar generated discovery are starting points, not finished harnesses. Expect them to find package manifests, build systems, tests, and obvious directory structure; then prune generic output, add local hazards, and move repeated or lengthy work into the right harness surface.

Default Workflow

Use this workflow unless the user asks for report-only or a specific file.

Read the repo orientation surface:
- README.md
- ARCHITECTURE.md and STATUS.md when present
- existing AGENTS.md and CLAUDE.md
- nearby agent docs such as docs/agents/** when present
Inspect the files, commands, and config that make guidance testable:
- package metadata
- justfile, Makefile, scripts, CI workflows, test config
- language manifests, lockfiles, compiler config, virtualenv/toolchain files, and existing language-server config
- skill folders or command folders
Use init-style discovery when it is available and worth the extra evidence:
- Prefer /init, codex init when available, or the tool's equivalent in suggestion/refactor mode.
- If /init refuses because AGENTS.md or CLAUDE.md already exists, prompt it to "help refactor the current file" rather than overwrite.
- Capture useful suggestions only. Do not treat init output as final text.
- If native slash commands are not exposed, either continue from repo evidence or use the stdin-bundled Codex CLI discovery below when the host supports it. Missing nested-agent support is not a blocker.
Classify current guidance:
- Preserve: project commands, env setup, permissions, local hazards, workflow source-of-truth rules, domain vocabulary, test gates.
- Merge: concise shared behavior that still fits this repo.
- Replace: stale setup steps, symlink-first instructions for root agent files, generic advice duplicated by system behavior.
- Extract: correct but lengthy procedures that belong in docs/agents/**, a reusable skill, or a script instead of root guidance.
- Collapse: verbose but necessary root guidance that can become one rule plus a pointer.
- Remove: obsolete commands, absolute paths from another project, generic best practices, duplicated Claude/Codex sections, copied human project state, process notes that belong in skills instead of root guidance, or compatibility shims that are no longer the live path.
Add or refresh a short preferred-skills block when relevant:
- $intuitive-init for agent guidance initialization and periodic refresh.
- $intuitive-doc for human-facing docs and doc drift.
- $intuitive-tests for test-suite structure and behavior-focused cleanup.
- $intuitive-flow as the default build/change entrypoint that routes by scope.
- $intuitive-preflight before plan or vague-task execution when approval should cover context package, scope, definition of done, verification, route, and main-session /goal wording.
- $intuitive-refactor before broad architecture or refactor work.
- $intuitive-reduce-entropy for periodic repo maintenance when the user does not already know which surface needs cleanup.
- $intuitive-squash for cleaning local agent commit history before handoff. Keep this block as routing guidance only. Do not use it to define the human documentation surface; $intuitive-doc owns that split.
Check harness-specific surfaces:
- nested CLAUDE.md / AGENTS.md files for monorepos or package-local rules
- .claude/skills/**, .codex/skills/**, .agents/skills/**, or project-owned skills/** for repeated workflows
- .claude/settings.json, .codex/hooks/**, or equivalent hook config for deterministic checks that must run after edits
- checked-in .mcp.json or project-scoped MCP docs for shared external tools
Set up or verify target-repo LSP:
- Detect the repo's primary language stack from manifests and lockfiles.
- Verify or create the repo-local language-server config first.
- Then verify, configure, or propose Serena MCP as the agent-facing symbol tool unless it is already covered or concretely blocked.
- Prefer repo-local dev dependencies and checked-in config over global-only tools, but do not let editor-only LSP config replace agent-facing MCP.
- Apply the setup automatically when it is recognized and scoped to the target repo.
- If LSP is already configured, verify and summarize both the underlying language-server path and the agent-facing MCP path.
- If setup is unsafe or ambiguous, stop with a concrete proposal and command instead of guessing.
Produce a merged proposal first:
- Summarize the source inputs used.
- Report root file sizes and whether cleanup pressure is low, medium, or high.
- Explain what was preserved, collapsed, extracted, replaced, and removed.
- Name any new docs/agents/**, skill, script, or human-doc destination for extracted content.
- Call out any nested instruction files, hooks, skills, or MCP config that should be created, left alone, or moved out of the root files.
- Call out the target-repo LSP status separately for: underlying language-server config and agent-facing Serena/MCP setup. Mark Serena/MCP as configured, refreshed, already covered, skipped with a concrete blocker, or needing user approval.
- Show the diff or proposed file contents.
Apply changes only when the user has asked for direct implementation or approves the proposal. When applying, update both AGENTS.md and CLAUDE.md if both exist and the rule applies to both agents. Also apply recognized repo-local LSP setup changes in the same pass when they are safe and scoped to the target repo.

Agent-Init Discovery

Use init-style discovery as an optional reviewer, not as the source of truth. The durable requirement is that repo evidence wins and generated suggestions are merged deliberately. Skip discovery when the host cannot run it cheaply or reliably.

Native slash command

Use this when the host exposes /init, codex init, or an equivalent tool. Some Codex CLI builds may not expose codex init; in that case, skip directly to the stdin-bundled Codex CLI discovery fallback.

/init

codex init

If root agent files already exist, ask for suggestion/refactor mode rather than overwrite mode:

Help refactor the current AGENTS.md and CLAUDE.md. Produce suggestions only;
do not overwrite files.

Default Codex CLI discovery

Use this when a second-opinion review is useful, native /init is not exposed, and the codex CLI is installed. This is not a file-editing pass. It should only produce suggestions to merge into the proposal. Build a context bundle with the host tools and pipe it into Codex so Codex does not need to run nested read commands through its own sandbox.

Use this as an adaptable example from the repository root. Equivalent read-only evidence is acceptable when the host CLI, sandbox, or flags differ:

{
  printf '# AGENTS.md\n'
  sed -n '1,260p' AGENTS.md 2>/dev/null || true
  printf '\n# CLAUDE.md\n'
  sed -n '1,260p' CLAUDE.md 2>/dev/null || true
  printf '\n# pyproject.toml selected sections\n'
  awk '
    /^\[project.optional-dependencies\]/ {p=1}
    /^\[tool.pytest.ini_options\]/ {p=1}
    /^\[tool.coverage.run\]/ {p=1}
    /^\[/ && !/^\[project.optional-dependencies\]/ && !/^\[tool.pytest.ini_options\]/ && !/^\[tool.coverage.run\]/ {if (p) p=0}
    p {print}
  ' pyproject.toml 2>/dev/null || true
  printf '\n# Orientation and automation files present\n'
  rg --files -g 'README.md' -g 'ARCHITECTURE.md' -g 'STATUS.md' -g 'Makefile' -g 'justfile' -g '.github/workflows/*.yml' -g '.github/workflows/*.yaml' -g 'docs/agents/**' 2>/dev/null | sort || true
} | codex --ask-for-approval never exec --ephemeral --skip-git-repo-check --sandbox read-only -C "$PWD" \
  "Act like Codex /init in suggestion-only mode for this repository. Analyze only the context bundle provided on stdin; do not run shell commands and do not edit files. Prefer aggressively small root agent files. Return: source inputs inspected, root file bloat signals, project-specific guidance to preserve, correct-but-lengthy guidance to extract into docs/agents/** or skills/scripts, stale or duplicated guidance to remove, missing operational rules, and concise suggested edits for AGENTS.md and CLAUDE.md."

If the host does not support --ephemeral, remove that flag.

Optional direct Codex read

Only use this when the environment is known to support Codex's nested read-only sandbox. It may fail on ordinary hosts that restrict bubblewrap user or network namespaces.

codex --ask-for-approval never exec --ephemeral --skip-git-repo-check --sandbox read-only -C "$PWD" \
  "Act like Codex /init in suggestion-only mode for this repository. Read the local orientation, agent, package, test, and CI files. Do not edit files. Prefer aggressively small root agent files. Return: source inputs inspected, root file bloat signals, project-specific guidance to preserve, correct-but-lengthy guidance to extract into docs/agents/** or skills/scripts, stale or duplicated guidance to remove, missing operational rules, and concise suggested edits for AGENTS.md and CLAUDE.md. Do not propose a full replacement unless the current files are unusable or overgrown enough that a thin-root rebuild is safer than patching."

Treat the output as advisory. If it conflicts with repo evidence, preserve the repo evidence and mention the disagreement in the proposal.

If codex is missing, exits non-zero, or the environment cannot run external agents, say so briefly and continue from repo evidence.

Modes

Audit

Use when the user asks what should change, or when broad edits would be risky.

Report:

Agent files:
Init discovery:
Root file size / cleanup pressure:
Project-specific guidance to preserve:
Correct but lengthy guidance to extract:
Shared boilerplate to remove:
Missing preferred-skill routing:
Harness surfaces to add or leave alone:
Suggested edits:
Apply now? <yes/no needed unless already authorized>

Audit must name deletion and extraction candidates. Do not stop at "preserve" just because a section is true. If the section is true but too long for root guidance, classify it as Extract or Collapse.

Apply

Use when the user explicitly asks to update the repo guidance.

Steps:

Run the default workflow.
Edit only AGENTS.md, CLAUDE.md, recognized target-repo LSP config or dev-dependency files, and directly related init docs/scripts the user named.
Keep the files self-contained for critical startup rules, but allow pointers to docs/agents/** for long operational procedures.
Create or update docs/agents/** only for extracted agent runbooks that are too long for the root files and are not human-facing project truth.
Preserve differences between Claude and Codex when they matter.
Keep hooks, MCP config, skills, and nested instruction files as separate harness surfaces instead of pasting their full procedures into root guidance.
Verify or document target-repo LSP setup for the primary language stack.
Search for stale setup/init claims after editing.

Refresh

Use after several weeks, major command changes, a new subsystem, repeated agent mistakes, or a changed planning workflow.

Run the same workflow as Apply, but be stricter about removing stale commands and softer about adding new process. A refresh should reduce drift, not expand root guidance into a manual.

Also use Refresh after $intuitive-doc has created, moved, or clarified the human documentation surface. In that case, update agent files to point at the final surface and remove copied project strategy, milestone state, or doc-tier policy that now belongs in human docs.

Refresh is allowed and expected to delete root guidance that is obsolete, duplicated, generic, copied from human docs, or correct-but-better-extracted. When the root files are over the strong cleanup signal, prefer a thin-root rewrite over a patchwork edit: rebuild AGENTS.md and CLAUDE.md from the preserve list, then move long runbooks into docs/agents/**.

Slim / Cleanup

Use when the user says the root agent files are too long, asks for aggressive cleanup, asks to make them "as clean as possible", or when audit finds strong cleanup signals.

Default result:

AGENTS.md: repo-wide rules all agents must see immediately.
CLAUDE.md: Claude-specific deltas only, not a full duplicate of AGENTS.md.
docs/agents/README.md: index of longer agent-only runbooks when any exist.
docs/agents/<topic>.md: extracted procedures for release, CI triage, environment setup, GPU/simulator setup, PR workflows, or similar long tasks.

Steps:

Build a preserve list from actual repo evidence.
Mark each current root section as Preserve, Collapse, Extract, Remove, or Human-doc drift.
Draft the thin root files first using the WHY / WHAT / HOW shape when it helps agents orient quickly.
Move lint/format details, long command recipes, and repeatable operational loops to hooks, scripts, skills, or docs/agents/** as appropriate.
Draft extracted docs/agents/** runbooks only for procedures that remain useful.
Verify root files contain pointers to extracted runbooks and no long copied procedures.
Show the deletion/extraction diff unless the user already approved applying.

Symlink Migration

Use when AGENTS.md or CLAUDE.md is a symlink to a shared toolkit.

Preferred result:

Convert the symlink into a project-local regular file.
Preserve the current linked content as the starting point.
Merge in project-specific hints from repo evidence and init suggestions.
Keep reusable workflows in skills, not pasted into the root files.

Do not silently overwrite local agent files with shared templates. If a legacy bootstrap script is in scope, make it defer to this AI-native merge flow or remove it from the recommended path.

Merge Rules

Good root agent guidance is short, local, and operational:

what to read first
how to install and run this repo
which tests and verification gates matter
what workflows own planning/execution truth
which local network, API, hardware, or sandbox constraints matter
which custom skills to use for recurring work

Deletion is part of the job. Remove or extract content even when it is accurate if it makes the root files hard to scan and can be represented by a short rule plus a pointer.

Do not duplicate the same long section in both AGENTS.md and CLAUDE.md. Common repo-wide guidance belongs in AGENTS.md or docs/agents/**; Claude-only behavior belongs in CLAUDE.md.

Use stable operational bridges instead of policy copies. Prefer wording like "Before broad work, read the active status or steering doc when present; if it conflicts with the request, ask the user" over repo-specific sections that duplicate the current milestone, non-goals, review gates, or documentation taxonomy.

Move reusable procedures into skills instead of expanding root guidance. Examples: documentation audits, test suite cleanup, repo entropy scans, phase pipelines, and bounded refactor gates.

Move repo-specific long procedures into docs/agents/** instead of expanding root guidance. Examples: release process, CI log investigation, GPU setup, visual validation workflow, PR fix strategy, dependency bootstrap, and environment-specific caveats.

Stop Conditions

Stop after a proposal when:

init output and repo evidence disagree in a way that changes policy
existing root guidance contains high-risk project-specific constraints
the user asked for discussion only or report-only
updating scripts would change how other projects are bootstrapped
removing compatibility paths would touch a broad command, install, generated-output, or user-facing surface

Stop after edits when:

AGENTS.md and CLAUDE.md are project-local and aligned
target-repo underlying LSP config is configured, refreshed, already covered by existing repo tooling, or explicitly skipped with a concrete reason
agent-facing Serena/MCP LSP is configured, refreshed, already covered by an existing MCP entry, or explicitly skipped with a concrete blocker or approval request
root files are slim enough to scan, or remaining length is justified by critical first-read safety rules
stale symlink-first guidance has been removed or explicitly narrowed to shared assets
copied human-facing project state has been replaced with stable pointers to the human docs that own it
long operational procedures have been extracted to docs/agents/**, skills, scripts, or human docs as appropriate
preferred skills are routed by task, not mandated for every turn
validation/search checks show no obvious stale claims in touched files