otto-onboard-project

name	otto-onboard-project
description	Onboard a repository into Otto project knowledge by bootstrapping the `.otto` Markdown store, researching the codebase, documentation, Git history, active initiatives, and external references, and recording evidence-backed draft pages for review. Use when a user asks to onboard, initialize, seed, or build project knowledge for a new or existing repository.

Otto project onboarding

Build a small, evidence-backed first map of a repository's durable knowledge. Compose $otto-setup-project-knowledge for initialization, $otto-project-knowledge for safe operations, and $otto-ingest-project-knowledge when a discrete document, conversation, or research source needs to be captured. Keep setup and seeding separate: setup creates the empty store; this workflow researches the project and records proposals that a human can review in Manage knowledge.

Workflow

1. Read docs/project-knowledge.md when it exists. Treat it as the contract for Otto's knowledge store. Do not create a parallel BRAIN.md, brain/, database, or ad-hoc Markdown system.
2. Check whether the repository is already onboarded. Query/list project knowledge if available and inspect the store's KNOWLEDGE.md and knowledge/ through normal file-reading tools. The store is in the repository under .otto/ or host-local under $OTTO_HOME, so read the paths Otto reports rather than assuming either. Preserve existing pages and never duplicate a fact that already has a current page.
3. Call bootstrap_project_knowledge for the current repository. This operation is idempotent and creates the root-page skeleton and generated index. It preserves optional project-specific KNOWLEDGE.md guidance and does not discover facts.
4. Gather evidence before writing proposals. Inspect, as applicable:
   • the root README and package manifests;
   • entry points, major directories, configuration, CI, and deployment files;
   • project documentation and contributor guidance;
   • existing project charters, initiative ledgers, and reference bibliographies;
   • recent and foundational git log entries, including important reverts or migrations;
   • tests that demonstrate behavior or compatibility requirements.
5. Synthesize only durable facts that are hard to reconstruct from code alone and likely to matter in six months. Prefer a few strong pages over a page for every implementation detail. Classify each proposal as architecture, decision, constraint, or requirement.
6. Populate all six project-map roots with update_project_knowledge_root: background, architecture, flow, mindmap, stack, and roadmap. Use rich Markdown and [[wiki links]] only to the atomic pages planned in the next step; refer to roots by their fixed slugs. A root may state that evidence is not yet available, but onboarding must not leave the generated placeholder in place.
7. Record each proposal with record_project_knowledge, including:
   • a readable kebab-case id;
   • a precise title;
   • a concise current-truth statement;
   • evidence naming concrete files, tests, docs, commits, or user decisions;
   • useful tags such as architecture, compatibility, workflow, or security. Leave new pages proposed; never confirm them on the user's behalf. Record durable initiatives with record_project_charter, including delivery state and only evidence-backed progress. Record important outside sources with record_project_reference, including URL, evaluation, and exactly how the source shaped or failed to shape the project.
8. Run lint_project_knowledge_links, then check for obvious overlap and stale signals using the returned knowledge view. Merge or skip duplicate proposals rather than creating competing pages.
9. Report what was created, what evidence supports it, what remains uncertain, and how the user can review or confirm the proposals in Manage knowledge. Give the store's KNOWLEDGE.md and page paths as Otto reports them, so the Markdown stays discoverable wherever it lives.

Greenfield projects

If there is little or no code, do not invent architecture. Ask a short interview covering the project's purpose, users, runtime, persistence, deployment target, non-negotiable constraints, and the first milestone. Record only answers the user explicitly confirms, as proposed pages.

Safety and review rules

• Never claim a fact from an unverified convention or an agent guess.
• Separate observed facts from recommendations. Recommendations belong in the proposal wording and must be clearly labeled.
• Optional KNOWLEDGE.md guidance may be edited or removed directly. Do not hand-edit the generated index, root pages, or atomic record pages; use Otto's project-knowledge tools so current truth and provenance remain atomic.
• Do not confirm or supersede pages without explicit user agreement.
• Do not add routine coding details, temporary TODOs, secrets, credentials, or copied source code.
• Do not create a second project ledger or references file. Import existing sources through daemon tools, verify parity, then recommend retiring the old files or instructions.
• Leave people and team relationships to team or personality memory.
• If the daemon lacks the project-knowledge capability, explain that the host must be updated; do not create a degraded fallback store.