idev-init

name	idev-init
description	Scaffolds the per-project .codex/idev/ state directory (caches, journal, lessons, config templates) for the idev plugin. Use when starting idev in a new project, when the SessionStart hook reports the state directory is missing, or when the user runs $idev:idev-init or asks to 'set up idev'.
argument-hint	[--with-codex-agents-snippet]
tools	["Bash","Read","Write","Edit","Glob"]

idev Init — Scaffold Per-Project State

Initialize the .codex/idev/ state directory in the current project. All idev skills read and write their per-project state (caches, indexes, journal, lessons, session state) here — never inside the plugin install directory.

Steps

1. Check for existing state: If .codex/idev/ already exists with content, report what's there and ask before overwriting anything. Never overwrite an existing journal.md, lessons.md, or any cache file.

2. Create the directory layout:

   mkdir -p .codex/idev/{smart-context,backend-patterns,frontend-patterns,architecture-scanner,build-check,api-contract-validation,post-creation-verify,file-index,import-graph,test-map,lessons-learned,task-journal,session-resume,project-map,api-contracts/contracts,browser-tests/{scripts,artifacts,reports}}
   

3. Copy templates (only where the destination does not exist):

   • ${PLUGIN_ROOT}/templates/journal.md → .codex/idev/task-journal/journal.md
   • ${PLUGIN_ROOT}/templates/lessons.md → .codex/idev/lessons-learned/lessons.md
   • ${PLUGIN_ROOT}/templates/project-config.json → .codex/idev/project-config.json
   • ${PLUGIN_ROOT}/templates/commands.json → .codex/idev/commands.json
   • ${PLUGIN_ROOT}/templates/watcher_config.json → .codex/idev/project-map/watcher_config.json
   • ${PLUGIN_ROOT}/templates/rules.md → .codex/idev/rules.md
   • ${PLUGIN_ROOT}/templates/commit-style.md → .codex/idev/commit-style.md

4. Initialize session state: Write .codex/idev/session-resume/last-session.json with:

   { "lastTask": null, "modifiedFiles": [], "openIssues": [], "savedAt": null }
   

   Also stamp the plugin version into .codex/idev/.idev-version (read it from ${PLUGIN_ROOT}/.codex-plugin/plugin.json) — $idev:upgrade uses this to detect drift after plugin updates.

5. Offer the AGENTS.md snippet (or do it directly if the user passed --with-codex-agents-snippet): append the contents of ${PLUGIN_ROOT}/templates/codex-agents-snippet.md to the project's AGENTS.md (create the file if missing). It contains the idev operating guide (cache-first context rules, skill workflow chain, agent delegation map) plus per-project policies (protected branches, migration policy, API config) — tell the user to review the FILL IN / KEEP ONLY IF sections. If an older idev snippet already exists in AGENTS.md (look for the ===== idev plugin marker), replace it instead of appending a duplicate.

6. Offer the low-prompt permissions preset: Ask whether to allowlist the plugin's read-only scripts and read-only git commands in the project's .codex/config.toml, so they run without permission prompts. If yes: add to the project's .codex/config.toml under [permissions] or add command allowlists as needed.

   [
     "Bash(python3 <abs-plugin-root>/skills/smart-context/scanner.py:*)",
     "Bash(python3 <abs-plugin-root>/skills/auto-learning/scripts/instinct-cli.py:*)",
     "Bash(python3 <abs-plugin-root>/skills/project-map/ai_map_updater.py:*)",
     "Bash(git status:*)",
     "Bash(git diff:*)",
     "Bash(git log:*)",
     "Bash(git branch:*)"
   ]
   

   These are exact path prefixes — only the plugin's own read-only scripts are covered, nothing broader (never add Bash(python3:*)). Note for the user: the bundled agents' Read/Grep/Glob tools never prompt; prompts come from Bash invocations, which is what this preset removes.

7. Offer team git hooks: Ask whether to install the commit-message hooks (prepare-commit-msg auto-prefixes the ticket from the branch name; commit-msg validates the subject format). If yes, follow the install-git-hooks procedure in the $idev:hooks command (never overwrite non-idev hooks without asking). Point the user at .codex/idev/commit-style.md to tune the team format.

8. Optionally trigger first scans: Ask whether to run the initial project scans now (smart-context index, file-index, pattern caches). If yes, generate .codex/idev/smart-context/index.json first by running the scanner from the project root:

   python3 "${PLUGIN_ROOT}/skills/smart-context/scanner.py"
   

   If python3 is unavailable, build the index manually per the idev:smart-context skill (detect the stack, feature names, and naming patterns, and write the same JSON shape by hand).

9. Report: List what was created, what was skipped (already existed), and remind the user that caches regenerate automatically as the skills run. Mention $idev:hooks for enabling the optional observer/compact hooks later.