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

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