onboard-project

---

name: onboard-project description: Onboard project or init project safely: prepare the active repository with agent state, a full persistent codebase-memory index, evidence-based AGENTS.md handling, and safe check reporting.

Onboard Project

Use for literal “onboard project” or “init project” requests, and equivalent requests to prepare the active repository for agents. This is a Level 2 workflow owned by the full orchestrator; orchestrator-lite must escalate rather than run it.

Safety boundary

• The full orchestrator confirms this is a genuinely new-task boundary. If the default reset_agent_state has not already run for this onboarding task, run it once with no file selection before work. If it has run, record its result and do not run it again.
• Never reset active or continued work. If boundary status is ambiguous or .agents/ may contain active work, use question before resetting. Keep any returned backup directory and recovery actions.
• Resolve the target root to the absolute active worktree root when available; otherwise use the absolute active directory (context.worktree || context.directory). Use that same root for all following work.
• Capture pre-onboarding Git status/dirtiness when the root is Git. For a non-Git root, continue without Git/exclude checks and report that status as unavailable.
• Do not install or update dependencies; add scripts/config; change Git or other ignore rules; delete an MCP project or cache; edit an existing AGENTS.md; commit, push, deploy, publish, or run destructive/network-dependent commands. The only ignore-file action permitted is the absent-only, root .cbmignore preparation below.

Ordered workflow

1. Reset state. Perform the confirmed, once-per-task default reset above to initialize .agents/. If reset partially fails, preserve recovery data, stop dependent mutations, perform only independent read-only inspection, and mark onboarding partial.
2. Explore and inventory repository evidence. Before indexing, inspect the root structure plus project-owned instructions, AGENTS.md, nested instruction files, contribution/setup docs, manifests/lockfiles, executable declarations, CI, and documented commands. Inspect generated, build-output, dependency-cache, and vendor areas; Git ignore rules when the root is Git; and any existing root .cbmignore. Identify Git/non-Git mode and likely large/monorepo cost; do not invent a size threshold. Record only verified repository-specific paths that should not enter the graph.
3. Prepare root .cbmignore from evidence. Do this before the full index call.
   • Codebase-memory already excludes .git, node_modules, dist, target, and vendor; never duplicate those built-in exclusions or add a pattern merely because an area is generated/dependency-related.
   • If root .cbmignore exists, leave it unchanged. Assess it against the inventory for material missing exclusions and contradictory patterns (including patterns that would omit relevant project source), and report gaps rather than editing it.
   • If it is absent, create only a root .cbmignore. Add only repository-specific exclusions verified by the inventory as unsuitable for the graph. If none are evidenced, create a concise comment-only file stating that no additional repository-specific exclusions were verified; do not add placeholder patterns or built-in exclusions.
   • If the required inventory cannot be completed or an absent-file write fails, do not guess patterns or invoke the full index without this preparation; retain the error, mark onboarding partial, and continue only safe independent work.
4. Create a fresh persistent index. Select the codebase-memory project name as the final directory name of the resolved absolute root; record the root-derived source for that choice. Invoke codebase-memory-mcp_index_repository exactly once with repo_path set to the absolute root, mode: "full", persistence: true, and explicit name set to that selected name. Do not pre-delete an existing project or downgrade/fall back to another mode. Verify with codebase-memory-mcp_index_status(project) using the returned project identifier when provided, otherwise the selected name; record which identifier was used and flag a returned identifier that differs from the selected name. Report status, errors/degradation, and .codebase-memory/graph.db.zst as an expected possible generated artifact. A timeout/resource failure is partial onboarding, not permission to narrow scope or remove cache data; stop index-dependent claims/actions, not all repository mutations.
5. Handle root AGENTS.md.
   • If it exists, leave it unchanged, only add codebase-memory-mcp index name. Compare it only against repository evidence and report material missing or contradicted categories: the selected codebase-memory project name, commands/order, non-obvious architecture, conventions, setup/operational gotchas, and references to other instruction sources. A missing or contradictory MCP project name is a material gap; never edit the file to fix it.
   • If absent, create only the root file. Keep it concise and evidence-only: include a clearly labeled codebase-memory project name using the selected name, plus verified commands, non-obvious structure/conventions/gotchas, and instruction references when supported; omit unknown sections and do not infer facts from generic defaults. Existing CLAUDE.md, Cursor/Copilot rules, nested rules, and contributing docs are evidence/references, never permission to replace an existing root file.
   • If indexing fails, stop index-dependent claims/actions. Independent direct repository evidence may still support the absent-only file only when sufficient and verified; otherwise skip creation and report the evidence gap. An index failure never authorizes speculative content.
6. Validate discovered commands safely. Classify every candidate as discovered, statically-confirmed, executed-pass, executed-fail, or skipped-with-reason. Delegate execution only to test-runner, and only for documented, non-destructive commands with available toolchain and existing dependencies that neither install, fetch, update, deploy, publish, rewrite configuration, require secrets, nor require network access. Never improvise substitute commands. Static confirmation or an explicit skip is valid when those gates cannot be proven.
7. Close with an evidence report. Capture post-onboarding Git dirtiness when available. Do not revert, delete, stage, or hide pre-existing dirtiness or generated outputs.

Re-runs and failures

• Within one active onboarding task, do not reset or create a second root AGENTS.md; an existing file is always preserve-and-gap-report. A genuinely new later onboarding task may create a reset backup and refresh the full persistent index.
• Within one active onboarding task, prepare root .cbmignore only once before indexing. On a rerun, preserve the now-existing file and report any evidence-based missing or contradictory exclusions; never rewrite it. A genuinely new later onboarding task follows the same absent-only rule.
• For large repositories, vendor trees, or monorepos, report expected full-index cost and discovered generated/vendor areas, then retain the required full mode.
• On an indexing failure, retain artifacts and errors, stop index-dependent claims/actions, and label the result partial; apply the AGENTS.md rule above, while other non-index-dependent permitted steps continue under their own safety rules. If .cbmignore preparation fails before indexing, do not make the index call; retain the evidence/error and report the deferred index. On a reset, other file-write, or command-check failure, retain artifacts and errors, stop unsafe dependent work, and continue only safe independent work as applicable.

Required final report

Report all of the following with concrete status/value or unavailable/reason:

• target absolute root; Git or non-Git mode; pre/post dirtiness;
• boundary decision; reset performed/already-performed/skipped; reset backup, result, and recovery data;
• selected codebase-memory project name, its root-directory source, index call arguments, returned project, status-verification identifier/result, duration/cost concern, failures, and persistent/generated artifacts;
• .cbmignore action (preserved with gaps, created with verified exclusions, created comment-only, or failed/deferred), inventory and Git-ignore evidence, verified exclusions or the no-additional-exclusions assessment, built-in exclusions intentionally not duplicated, and material missing/contradictory gaps;
• AGENTS.md action (preserved with gaps, created, or failed), evidence sources, the included or expected codebase-memory project name, and omissions/contradictions;
• command matrix: command, evidence source, safety decision, and one required classification above;
• files changed plus generated outputs, including pre-existing versus onboarding-created when known;
• partial failures, skipped work, unresolved gaps, and safe follow-ups; and
• restart OpenCode to load this new global skill, plus any unperformed disposable-repository smoke.