dotfiles/.config/opencode/commands/init.md

description

description
Initialize or update a project with scaffold, docs, and knowledge graph — adapts to both new and existing projects.

You are initializing or updating a project. Follow these steps in order.

Project hint (may be empty): $ARGUMENTS

Step 1 — Explore current project state (delegate to explorer)

Delegate to the explorer subagent first, before any questions, to determine whether this is a new or existing project.

• Ask explorer to inspect the working tree for project-defining artifacts, including:
  • source files and source directories
  • README.md, AGENTS.md, docs/
  • stack markers such as package.json, pyproject.toml, go.mod, Cargo.toml, composer.json
  • git markers such as .git/
  • any similar files that strongly indicate an existing project
• Ask explorer to return:
  • classification: new_project or existing_project
  • inferred project name, purpose, and tech stack (with confidence)
  • which required scaffold files already exist vs are missing
  • whether .git/ exists

Step 2 — Clarify (Lead, one round max)

Use the question tool for at most one round, adapting to Step 1 findings.

• If explorer's classification confidence is low (e.g., directory has only a few ambiguous files), include the classification itself as a question to confirm.
• If classification is existing_project:
  • confirm or correct explorer inferences (name, one-sentence purpose, stack)
  • ask only for unknown or low-confidence fields
  • do not ask whether to initialize git if .git/ already exists
  • do not ask for files/details that are already present and clear
• If classification is new_project:
  • ask:
    • project name and one-sentence purpose
    • primary language / framework / tech stack
    • whether to initialize a git repository

Step 3 — Scaffold (delegate to coder)

Delegate to the coder subagent with explicit mode (new_project or existing_project) and the file existence map from Step 1.

• Required scaffold targets:
  • README.md — title, purpose, tech stack, quick-start, project structure overview
  • AGENTS.md — project-specific workflow notes (code style, test commands, linting, build commands, commit conventions); do not duplicate global AGENTS.md policies — only add project-specific details
  • docs/architecture.md — stub with title + purpose
  • .gitignore — must include .megamemory/ entry; add stack-appropriate ignores (e.g., node_modules/, __pycache__/, target/)
  • other stack-specific scaffold files if clearly implied (e.g., package.json, pyproject.toml)
• If new_project:
  • create all required scaffold files/directories
• If existing_project:
  • create or fill in only missing pieces
  • do not overwrite existing files
  • explicitly instruct coder to check existence before creating each target
  • if .gitignore exists, instruct coder to append .megamemory/ if not already present
  • examples:
    • if README.md exists and AGENTS.md is missing, create only AGENTS.md
    • if docs/ is missing, create it and add docs/architecture.md

Step 4 — Documentation review (delegate to librarian)

Always delegate to the librarian subagent, for both new and existing projects.

• Ensure README.md is accurate and complete for the current project state.
• Ensure AGENTS.md captures project-specific workflow decisions from Step 2.
• Ensure stubs are explicitly marked for later completion.
• Keep edits additive and non-destructive for existing projects.

Step 5 — Initialize or update knowledge graph (Lead)

Always update megamemory for this project.

• First call megamemory:understand to check whether a project root concept already exists.
• If an appropriate concept exists, call megamemory:update_concept.
• If none exists, call megamemory:create_concept with:
  • Kind: module
  • Name: <project name>
  • Summary: purpose, stack, key files, and notable init/update decisions
  • File refs: include whichever exist among README.md, AGENTS.md, docs/architecture.md
• Create links (megamemory:link) from this concept to related existing concepts when applicable. If no related concepts exist yet (brand new knowledge graph), skip linking.

Step 6 — Git handling (delegate to coder)

Delegate git operations to coder based on discovered state.

• If .git/ already exists:
  • skip git init
  • ensure .megamemory/ is in .gitignore (if not already handled in Step 3)
  • stage only newly created or modified files from this init/update flow
  • create a commit
• If .git/ does not exist:
  • use Step 2 answer to decide whether to run git init
  • if initialized, ensure .megamemory/ is in .gitignore, then stage only newly created or modified files and create a commit
• Commit message should be concise and conventional, e.g.:
  • chore: initialize project scaffold (new project)
  • chore: add missing project scaffolding (existing project)

Completion report

Summarize:

• Files created and files updated, with purpose.
• Decisions made and decisions deferred.
• What the user should fill in next (stubs, open questions, follow-up documentation).