GEMINI.md

Project Map (AGENTS.md)

This file is a navigation map for agents. Durable knowledge lives in docs/.

Start Here

• Docs index: docs/README.md
• Architecture: docs/ARCHITECTURE.md
• Operations: docs/RUNBOOK.md
• Validate: opencode-ctx docs validate
• Test: uv run pytest tests/ -v

System-of-Record Documents

Category	Location	Type	Purpose
Guides	docs/guides/README.md	how-to	Practical procedures
Design docs	docs/design-docs/index.md	explanation	Feature design, ADRs
Core beliefs	docs/design-docs/core-beliefs.md	explanation	Agent-first principles
Learnings	docs/learnings/README.md	reference	Durable patterns
Exec plans	docs/exec-plans/README.md	how-to	Complex work tracking
Discovery	docs/discovery/index.md	explanation	Validate + Taste
Delivery specs	docs/delivery-specs/index.md	reference	Engineering handoff
References	docs/references/README.md	reference	External docs
Exploration	docs/exploration/README.md	exploration	Ideas, scratchpad
Taxonomy	docs/DOCS_TAXONOMY.md	reference	Where to put new docs
Quality	docs/QUALITY_SCORE.md	reference	Domain grades

Guardrails

• Testing: Use the package manager (uv run pytest ...), never bare pytest.
• Skills: Call skill({ name: "<name>" }) first when asked to use a skill.
• Config: Project config in opencode.jsonc (repo root); .opencode/ holds project agents/commands; global fallback in ~/.config/opencode/.
• Git safety: No destructive commands (reset --hard, push --force) unless explicit.
• Secrets: Never commit .env or credentials.

Quick Commands

Task	Command
Install	uv sync
Init project	opencode-ctx docs init (scaffolds docs, config, git hooks)
Docs validate	opencode-ctx docs validate
Arch snapshot	opencode-ctx docs architecture apply
Lint	uv run ruff check --fix .
Format	uv run ruff format .
Test	uv run pytest tests/ -v
Run	uv run python -m <module>

Development Workflow

• Run via package manager (uv run ...), never bare commands.
• List existing files before creating new ones (avoid naming drift).
• Prefer vertical slices over horizontal refactors.
• No premature abstraction until multiple use-cases require it.