Setup Codebase

Create context with repository-reading, not a static file template. Existing context belongs to the project: never overwrite or shorten it.

Pick the mode before step 1; this guard runs before any write.

1. Check the exact status of AGENTS.md, CLAUDE.md, CONVENTIONS.md, docs/llm/, and .gitignore. Read every existing context or conventions file before writing anything. If the repository has no application source and an approved design exists as design.md in a docs/agent-devkit/changes/ folder (or a legacy spec under docs/agent-devkit/specs/), read it before writing context.
2. If context is missing, inspect only enough evidence to ground it: README*, root/workspace manifests, task scripts, environment examples, CI/config, top-level source layout, and any approved design from the previous step. Do not install dependencies, start services, or infer facts from filenames alone.

3. Write only missing files from that evidence:

   • AGENTS.md: concise purpose, relevant layout, verified commands, explicit conventions/gotchas, and verification. Omit unknown sections. For a source-less new project, the approved design establishes intended purpose and planned layout only; do not claim unimplemented behavior or commands as verified. If a skills/ or .agents/skills folder exists in the repository, add a ## Skills section listing each skill by name with its SKILL.md path so every agent platform can discover them. If docs/llm/ exists or is created, add a ## Documentation section:

     ## Documentation
     
     The verified codebase wiki is at `docs/llm/INDEX.md`.
     
     For behavior, workflow, or domain questions:
     1. Read `docs/llm/INDEX.md`.
     2. Open the relevant wiki page.
     3. Verify important claims against current source and tests.
     
     The wiki describes verified behavior only; source and tests remain authoritative.

   • CLAUDE.md: a short repository-specific pointer to AGENTS.md; include extra instructions only when local evidence establishes them.
   • docs/llm/: for direct setup or wiki-only inline calls, create the wiki skeleton with AGENTS.md and INDEX.md; skip for a code-task call without an explicit wiki-setup request. The generated AGENTS.md must match document-wiki's current-source verification rules, distinguish verification limits from confirmed content gaps, and state that any existing log is legacy, not read or written and not used for freshness. It must also state that feature pages use document-wiki's requirement format and the ## Requirement prefixes registry in INDEX.md, without restating the format. Do not create LOG.md. If a legacy LOG.md already exists, preserve it byte-for-byte without reading or updating it. Create wiki category folders (architecture/, domains/, workflows/, integrations/, operations/, or decisions/) only when document-wiki has a real page to place there; do not add placeholder pages just to preserve empty directories.

   Every claim must have a repository source. If evidence is insufficient, state an open question instead of inventing a rule.

4. In a direct setup-codebase invocation, inspect both AGENTS.md and the root CONVENTIONS.md before deriving anything:

   • First compare both files for populated convention sources. A populated conventions section in AGENTS.md plus a populated CONVENTIONS.md is a source-of-truth conflict; report both paths, ask the user how to resolve it, and write nothing.
   • Recognize Read CONVENTIONS.md before editing. as the exact split-storage pointer. A missing pointer target, an empty target, a populated CONVENTIONS.md without that pointer, or any other existing-file collision is a conflict; report the exact paths, ask the user how to resolve it, and write nothing.
   • A valid pointer plus a populated CONVENTIONS.md is already canonical and must be skipped without writing.
   • Otherwise, a heading matching, case-insensitively, convention|working rules|standards|style|guidelines|change shape whose content contains at least one repository-specific rule means conventions are already present; report the match and skip capture.
   • If no stored convention is found, read references/convention-capture.md before capturing conventions after evidence gathering.
5. Check whether OpenEZ is available (openez command or MCP server). If it is available, note it in AGENTS.md under a ## Code intelligence section as the optional Locate → Expand → Confirm → Read path below. If AGENTS.md was created in this run, include the section there. If it already existed, present the exact proposed lines and wait for approval before adding them. If it is not available, continue without it. Mention optional setup-openez only when direct search cannot establish a needed semantic or cross-module relationship. Do not recommend it by repository size, or install or run openez setup silently. Use the section in setup-openez's ## Code intelligence block.

6. Keep local Obsidian and OpenEZ state out of Git. Create .gitignore when it is missing, or append only these missing lines without reordering, normalizing, or duplicating existing content:

   /docs/.obsidian/
   /docs/Untitled*.md
   /docs/Untitled*.canvas
   .openez/

   Check whether matching files are already tracked. If they are, report their paths; never run git rm --cached or otherwise untrack them.

7. Preserve existing context files byte-for-byte. The additive .gitignore update in step 6 is the only automatic edit to an existing file. A Code intelligence section may be included in a new AGENTS.md created during this run or added to an existing one only after user approval. The conventions section or AGENTS.md pointer from step 4 may also be written only after user approval. Do not restore files from Git. Read back every created or changed file before reporting it.
8. Use standard relative Markdown links for internal wiki links, following the shared link rule in using-devkit. Use ## Sources for evidence and ## Related when a related page exists. Do not document features here; document-wiki owns that.
9. Run git diff --check. Report distinct created, updated, and kept lists, tracked local artifacts, and the evidence paths used.

Quick reference