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

description, permalink

description	permalink
Initialize or update a project with scaffold, docs, and basic-memory notes — adapts to both new and existing projects.	opencode-config/commands/init

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 — instruction file containing shared project guidance
  • docs/architecture.md — stub with title + purpose
  • .gitignore — 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
  • ensure AGENTS.md exists as the project instruction file
  • if legacy tool-specific instruction files exist, consolidate any repo-specific guidance into AGENTS.md and stop maintaining duplicate copies
  • examples:
    • 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 exists and captures project-specific workflow decisions from Step 2.
• Ensure repo instruction guidance lives in AGENTS.md only.
• Ensure stubs are explicitly marked for later completion.
• Keep edits additive and non-destructive for existing projects.

Step 5 — Initialize or update basic-memory project notes (Lead)

Always create or update basic-memory project notes for this project.

• Ensure a dedicated per-repo basic-memory project exists. Use list_memory_projects to check. If not found, create one with create_memory_project using a short kebab-case name (e.g., my-web-app) and the repo's .memory/ subdirectory as project_path (e.g., /path/to/repo/.memory).
• All subsequent note operations in this step must pass project="<repo-project-name>".
• Use search_notes (with project) to check for existing project notes to avoid duplicates.
• Use write_note (with project) to create or update a knowledge/overview note with:
  • Project name
  • Purpose and stack
  • Key files (README.md, AGENTS.md, docs/architecture.md when present)
  • Notable init/update decisions
• Add WikiLink cross-references to related notes (e.g., [[decisions/...]]).

Step 6 — Git handling (delegate to coder)

Delegate git operations to coder based on discovered state.

• If .git/ already exists:
  • skip git init
  • 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, 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).