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

description

description
Initialize or update a project with scaffold, docs, and .memory files — 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
  • CLAUDE.md — project instructions for Claude Code (same core content as AGENTS.md, adapted for Claude)
  • .github/copilot-instructions.md — project instructions for GitHub Copilot
  • .cursorrules — project instructions for Cursor
  • docs/architecture.md — stub with title + purpose
  • .gitignore — add stack-appropriate ignores (e.g., node_modules/, __pycache__/, target/)
  • .memory/ — create and/or update knowledge.md, decisions.md, plans/, research/
  • 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 any cross-tool instruction files are missing (AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .cursorrules), create them
  • if they exist, verify they are in sync with AGENTS.md for core project knowledge (purpose, stack, conventions, commands, structure)
  • if .memory/ is missing, create the full .memory/ directory structure
  • 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.
• Verify cross-tool instruction files are consistent with each other (AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .cursorrules).
• Ensure stubs are explicitly marked for later completion.
• Keep edits additive and non-destructive for existing projects.

Step 5 — Initialize or update .memory project overview (Lead)

Always create or update .memory/knowledge.md for this project.

• Read existing .memory/knowledge.md (if present) to avoid duplicate sections.
• Create or update a project overview section with:
  • Project name
  • Purpose and stack
  • Key files (README.md, AGENTS.md, docs/architecture.md when present)
  • Notable init/update decisions
• Add markdown cross-references to related sections in .memory/decisions.md when applicable.

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).