File size: 2,976 Bytes
5dd1bb4 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 | # Project Map (AGENTS.md)
This file is a navigation map for agents. Durable knowledge lives in `docs/`.
## Start Here
- Docs index: [docs/README.md](docs/README.md)
- Architecture: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
- Operations: [docs/RUNBOOK.md](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](docs/guides/README.md) | how-to | Practical procedures |
| Design docs | [docs/design-docs/index.md](docs/design-docs/index.md) | explanation | Feature design, ADRs |
| Core beliefs | [docs/design-docs/core-beliefs.md](docs/design-docs/core-beliefs.md) | explanation | Agent-first principles |
| Learnings | [docs/learnings/README.md](docs/learnings/README.md) | reference | Durable patterns |
| Exec plans | [docs/exec-plans/README.md](docs/exec-plans/README.md) | how-to | Complex work tracking |
| Discovery | [docs/discovery/index.md](docs/discovery/index.md) | explanation | Validate + Taste |
| Delivery specs | [docs/delivery-specs/index.md](docs/delivery-specs/index.md) | reference | Engineering handoff |
| References | [docs/references/README.md](docs/references/README.md) | reference | External docs |
| Exploration | [docs/exploration/README.md](docs/exploration/README.md) | exploration | Ideas, scratchpad |
| Taxonomy | [docs/DOCS_TAXONOMY.md](docs/DOCS_TAXONOMY.md) | reference | Where to put new docs |
| Quality | [docs/QUALITY_SCORE.md](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.
<!-- GUIDELINES-BEGIN -->
<!-- Managed by: opencode-ctx guidelines apply --packs python,testing,delivery-safety -->
<!-- Run the command above to populate this section -->
<!-- GUIDELINES-END -->
|