alex/dotfiles
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

changes

Browse Source
This commit is contained in:
alex
2026-03-10 13:09:47 +00:00
parent e0c4c2ed7b
commit ffd0d31fa5
43 changed files with 532 additions and 749 deletions
Download Patch File Download Diff File Expand all files Collapse all files

243
.config/opencode/AGENTS.md
View File

@@ -1,28 +1,73 @@
## Memory System (Dual: Global + Per-Project)
---
title: AGENTS
type: note
permalink: opencode-config/agents
---
Memory is split into two complementary systems:
## Memory System (Single: basic-memory)
1. **Global Memory (basic-memory)** — cross-project knowledge via MCP server. Stores reusable patterns, conventions, tech knowledge, domain concepts, and lessons learned. Lives in `~/basic-memory/`, accessed via MCP tools.
2. **Project Memory (`.memory/`)** — per-project state committed to git. Stores plans, gates, sessions, project-specific decisions, research, and architecture. Lives in the project's `.memory/` directory.
Memory uses one persistent system: **basic-memory**.
### Global Memory (basic-memory)
- All persistent knowledge is stored in basic-memory notes, split across a **`main` project** (global/shared) and **per-repo projects** (project-specific).
- Repo-local `.memory/` files are legacy artifacts and are **not** the active source of truth.
- Do not create, update, or rely on `.memory/*` for current work tracking.
- **Migration note:** Existing repo-local `.memory/` directories (or `.memory.legacy/`) in projects are non-authoritative and should be ignored unless you are explicitly migrating historical content into basic-memory. Do not delete them automatically — they may contain useful historical context for one-time migration.
### basic-memory
[basic-memory](https://github.com/basicmachines-co/basic-memory) is an MCP server that provides persistent knowledge through structured markdown files indexed in SQLite with semantic search.
**What goes in global memory:**
- Reusable coding patterns (error handling, testing, logging)
- Technology knowledge (how libraries/frameworks/tools work)
- Convention preferences (coding style decisions that span projects)
- Domain concepts that apply across projects
- Cross-project lessons learned and retrospectives
- SME guidance that isn't project-specific
### `main` vs per-repo projects
**MCP tools (available to all agents):**
- `write_note(title, content, folder, tags)` — create/update a knowledge note
- `read_note(identifier)` — read a specific note by title or permalink
- `search_notes(query)` — semantic + full-text search across all notes
- `build_context(url, depth)` — follow knowledge graph relations for deep context
- `recent_activity(type)` — find recently added/updated notes
basic-memory organizes notes into **projects**. Two kinds exist:
1. **`main` (global/shared knowledge only)**
- Reusable coding patterns (error handling, testing, logging)
- Technology knowledge (how libraries/frameworks/tools work)
- Convention preferences (coding style decisions that span projects)
- Domain concepts that apply across projects
- Cross-project lessons learned and retrospectives
- SME guidance that isn't project-specific
- User preferences and personal workflow notes
2. **Per-repo projects (project-specific knowledge only)**
- Plans, decisions, research, gates, and session continuity for ONE repository
- Project architecture and module knowledge
- Project-specific conventions and patterns
**Hard rule:** Never store project-specific plans, decisions, research, gates, or sessions in `main`. Never store cross-project reusable knowledge in a per-repo project.
### Per-repo project setup (required)
Every code repository must have its own dedicated basic-memory project. This is non-negotiable.
**Creating a new per-repo project:**
Use `basic-memory_create_memory_project` (or the equivalent MCP tool) with:
- `project_name`: a short, kebab-case identifier for the repo (e.g., `opencode-config`, `my-web-app`, `data-pipeline`)
- `project_path`: the repo's root directory on disk
Example for this repo:
```
project_name: opencode-config
project_path: /home/alex/dotfiles/.config/opencode
```
**Checking if a project exists:**
Use `basic-memory_list_memory_projects` to see all projects. If the repo doesn't have one yet, create it before reading/writing project-specific notes.
**This repo's basic-memory project:** `opencode-config`
### MCP tools (available to all agents)
- `write_note(title, content, folder, tags, project)` — create/update a knowledge note
- `read_note(identifier, project)` — read a specific note by title or permalink
- `search_notes(query, project)` — semantic + full-text search across all notes
- `build_context(url, depth, project)` — follow knowledge graph relations for deep context
- `recent_activity(type, project)` — find recently added/updated notes
- `list_memory_projects()` — list all basic-memory projects
- `create_memory_project(project_name, project_path)` — create a new per-repo project
**The `project` parameter is critical.** Always pass `project="main"` for global notes and `project="<repo-project-name>"` for project-specific notes. Omitting the project parameter defaults to `main`.
**Note format:**
```markdown
@@ -45,104 +90,77 @@ tags:
```
**Usage rules:**
- At session start, use `search_notes` or `build_context` to find relevant global knowledge before starting work.
- After completing work with reusable lessons, use `write_note` to record them globally.
- At session start, identify the repo's basic-memory project (see Session-Start Protocol below).
- Use `project` parameter on every MCP call to target the correct project.
- After completing work with reusable lessons, use `write_note` with `project="main"` to record them.
- Use WikiLinks `[[Topic]]` to create relations between notes.
- Use tags for categorization: `#pattern`, `#convention`, `#sme`, `#lesson`, etc.
- Use observation categories: `[pattern]`, `[convention]`, `[decision]`, `[lesson]`, `[risk]`, `[tool]`.
### Project Memory (`.memory/`)
### Session-start protocol (required)
Per-project state, committed to git. This is the source of truth for active project work.
At the start of every session, before reading or writing any project-specific notes:
**Directory structure:**
1. **Identify the repo.** Determine which repository you are working in (from the working directory or user context).
2. **Select the per-repo project.** Use `basic-memory_list_memory_projects` to find the repo's basic-memory project. If it doesn't exist, create it with `basic-memory_create_memory_project`.
3. **Load project context.** Query the per-repo project (`search_notes`/`build_context` with `project="<repo-project-name>"`) for relevant prior work, pending decisions, and in-progress items.
4. **Load global context.** Query `main` (`search_notes` with `project="main"`) for relevant cross-project knowledge when the task domain may have reusable guidance.
```text
.memory/
├── manifest.yaml # Index: all files with descriptions + groups
├── system.md # One-paragraph project overview
│
├── knowledge/ # Project-specific knowledge
│ ├── overview.md # THIS project's architecture
│ └── tech-stack.md # THIS project's technologies
│
├── decisions.md # Project-specific Architecture Decision Records
│
├── plans/ # Active plans (one per feature)
│ └── <feature>.md
│
├── research/ # Project-specific research findings
│ └── <topic>.md
│
├── gates/ # Quality gate records
│ └── <feature>.md # Review + test outcomes
│
└── sessions/ # Session continuity
└── continuity.md # Rolling session notes
```
All subsequent project-specific reads/writes in the session must target the per-repo project. All global/shared reads/writes must target `main`.
**Workflow: global context → project context → work → update both**
### Project-specific note organization
1. **Session start:** Query basic-memory (`search_notes`) for relevant global context, then read `.memory/manifest.yaml` and relevant project files.
2. **Before each task:** Check global memory for reusable patterns/guidance, then read relevant `.memory/` files for project state.
3. **After each task:** Update `.memory/` for project state. If the work produced reusable knowledge, also `write_note` to basic-memory.
4. **Quality gates:** Record reviewer/tester outcomes in `.memory/gates/<feature>.md` (project-specific).
Project notes in the per-repo basic-memory project are grouped by purpose:
**Manifest schema:**
- `knowledge/` — project architecture, modules, conventions, patterns
- `plans/` — one note per feature/task with scope, tasks, acceptance criteria
- `decisions/` — ADRs, SME guidance, design choices
- `research/` — investigation findings
- `gates/` — quality gate records (reviewer/tester verdicts)
- `sessions/` — session continuity notes
```yaml
name: <project-name>
version: 1
categories:
- path: <relative-path>
description: <one-line description>
group: <knowledge|decisions|plans|research|gates|sessions>
```
Use stable identifiers so agents can pass note references between delegations.
**Recording discipline:** Only record outcomes, decisions, and discoveries — never phase transitions, status changes, or ceremony checkpoints. If an entry would only say "we started phase X", don't add it. Memory files preserve *knowledge*, not *activity logs*.
**Workflow: load context → work → update basic-memory**
1. **Session start:** Follow the session-start protocol above.
2. **Before each task:** Read relevant notes from the per-repo project (plans/decisions/research/sessions) and from `main` for reusable guidance.
3. **After each task:** Update project notes in the per-repo project (plans, decisions, research, gates, sessions). Record reusable lessons in `main`.
4. **Quality gates:** Record reviewer/tester outcomes in the per-repo project's `gates/` notes.
**Recording discipline:** Only record outcomes, decisions, and discoveries — never phase transitions, status changes, or ceremony checkpoints. If an entry would only say "we started phase X", don't add it. Memory notes preserve *knowledge*, not *activity logs*.
**Read discipline:**
- Read `manifest.yaml` first to discover what's available
- Read only the `.memory/` files relevant to the current task
- **Skip redundant reads** when `.memory/` already has no relevant content in that domain this session
- Read only the basic-memory notes relevant to the current task
- **Skip redundant reads** when the per-repo project already has no relevant content in that domain this session
- **Do not immediately re-read content you just wrote**
- Treat `.memory/` as a **tool**, not a ritual
- Treat memory as a **tool**, not a ritual
**Linking is required.** When recording related knowledge across files, add markdown cross-references (for example: `See [Decision: Auth](decisions.md#auth-approach)`). Cross-reference global memory notes with `memory://permalink` URLs when relevant.
**Manifest maintenance:** When creating new `.memory/` files, add entries to `manifest.yaml` with path, description, and group. The librarian agent verifies manifest accuracy.
**Linking is required.** When recording related knowledge across notes, add markdown cross-references and use `memory://` links where relevant.
### When to Use Which
| Knowledge type | Where to store | Why |
|---|---|---|
| Reusable pattern/convention | basic-memory (`write_note`) | Benefits all projects |
| SME guidance (general) | basic-memory (`write_note`) | Reusable across consultations |
| Project architecture | `.memory/knowledge/` | Specific to this project |
| Active plans & gates | `.memory/plans/`, `.memory/gates/` | Project lifecycle state |
| Session continuity | `.memory/sessions/` | Project-scoped session tracking |
| Project decisions (ADRs) | `.memory/decisions.md` | Specific to this project |
| Project research | `.memory/research/` | Tied to project context |
| Tech knowledge (general) | basic-memory (`write_note`) | Reusable reference |
| Lessons learned | basic-memory (`write_note`) | Cross-project value |
| Knowledge type | Where to store | Project | Why |
|---|---|---|---|
| Reusable pattern/convention | `write_note` | `main` | Benefits all projects |
| SME guidance (general) | `write_note` | `main` | Reusable across consultations |
| Tech knowledge (general) | `write_note` | `main` | Reusable reference |
| Lessons learned | `write_note` | `main` | Cross-project value |
| User preferences | `write_note` | `main` | Span all projects |
| Project architecture | `knowledge/*` notes | per-repo project | Specific to this project |
| Active plans & gates | `plans/*` and `gates/*` notes | per-repo project | Project lifecycle state |
| Session continuity | `sessions/*` notes | per-repo project | Project-scoped session tracking |
| Project decisions (ADRs) | `decisions/*` notes | per-repo project | Specific to this project |
| Project research | `research/*` notes | per-repo project | Tied to project context |
## Cross-Tool Instruction Files
## Instruction File
Use symlinks to share this instruction file across all agentic coding tools:
```text
project/
├── AGENTS.md # Real file (edit this one)
├── CLAUDE.md -> AGENTS.md
├── .cursorrules -> AGENTS.md
└── .github/
└── copilot-instructions.md -> ../AGENTS.md
```
`AGENTS.md` is the only instruction file that should be maintained in this repo.
**Rules:**
- Edit `AGENTS.md` — changes propagate automatically via symlinks
- Never edit symlinked files directly (changes would be lost)
- Symlinks are committed to git (git tracks them natively)
- Put project instructions in `AGENTS.md` only
- Do not create or maintain mirrored instruction files or symlinks for other tools
- If another tool needs repo instructions, point it at `AGENTS.md` directly
**Content of this file:**
- Project overview and purpose
@@ -151,23 +169,24 @@ project/
- Build/test/lint commands
- Project structure overview
**Do NOT duplicate `.memory/` contents** — instruction files describe how to work with the project, not active plans, research, or decisions.
**Do NOT duplicate memory project contents** — `AGENTS.md` describes how to work with the project, not active plans, research, or decisions.
**When initializing a project:**
1. Create `AGENTS.md` with project basics
2. Create symlinks: `ln -s AGENTS.md CLAUDE.md`, `ln -s AGENTS.md .cursorrules`, `ln -s ../AGENTS.md .github/copilot-instructions.md`
3. Commit the real file and symlinks to git
**When initializing or updating a project:**
1. Create or update `AGENTS.md` with project basics
2. Keep instruction maintenance centralized in `AGENTS.md`
**When joining an existing project:**
- Read `AGENTS.md` (or any of the symlinked files) to understand the project
- If instruction file is missing, create it and the symlinks
- Read `AGENTS.md` to understand the project
- If the instruction file is missing, create `AGENTS.md`
## Session Continuity
- Treat `.memory/` files as the persistent project tracking system for work across sessions.
- At session start, query basic-memory (`search_notes`) for relevant cross-project knowledge, then identify prior in-progress work items and pending decisions in `.memory/` before doing new implementation.
- After implementation, update `.memory/` files with what changed, why it changed, and what remains next.
- If the work produced reusable knowledge (patterns, conventions, lessons learned), also record it in basic-memory (`write_note`) for cross-project benefit.
- Treat the per-repo basic-memory project as the persistent tracking system for work across sessions.
- At session start, query basic-memory (`search_notes`/`build_context`) for relevant prior work, pending decisions, and in-progress items.
- After implementation, update project notes in basic-memory with what changed, why it changed, and what remains next.
- If the work produced reusable knowledge (patterns, conventions, lessons learned), also record it in reusable basic-memory notes for cross-project benefit.
**This repo's basic-memory project:** `opencode-config`
## Clarification Rule
@@ -181,16 +200,16 @@ project/
|---|---|---|
| `lead` | Primary orchestrator that decomposes work, delegates, and synthesizes outcomes. | `github-copilot/claude-opus-4` (global default) |
| `coder` | Implementation-focused coding agent for reliable code changes. | `github-copilot/gpt-5.3-codex` |
| `reviewer` | Read-only code/source review; writes `.memory/*` for verdict records. | `github-copilot/claude-opus-4.6` |
| `tester` | Validation agent for standard + adversarial testing; writes `.memory/*` for test outcomes. | `github-copilot/claude-sonnet-4.6` |
| `explorer` | Fast read-only codebase mapper; writes `.memory/*` for discovery records. | `github-copilot/claude-sonnet-4.6` |
| `researcher` | Deep technical investigator; writes `.memory/*` for research findings. | `github-copilot/claude-opus-4.6` |
| `reviewer` | Read-only code/source review; records verdicts in basic-memory project notes. | `github-copilot/claude-opus-4.6` |
| `tester` | Validation agent for standard + adversarial testing; records outcomes in basic-memory project notes. | `github-copilot/claude-sonnet-4.6` |
| `explorer` | Fast read-only codebase mapper; records discoveries in basic-memory project notes. | `github-copilot/claude-sonnet-4.6` |
| `researcher` | Deep technical investigator; records findings in basic-memory project notes. | `github-copilot/claude-opus-4.6` |
| `librarian` | Documentation coverage and accuracy specialist. | `github-copilot/claude-opus-4.6` |
| `critic` | Pre-implementation gate and blocker sounding board; writes `.memory/*` for verdicts. | `github-copilot/claude-opus-4.6` |
| `sme` | Subject-matter expert for domain-specific consultation; writes `.memory/*` for guidance cache. | `github-copilot/claude-opus-4.6` |
| `designer` | UI/UX specialist for interaction and visual guidance; writes `.memory/*` for design decisions. | `github-copilot/claude-sonnet-4.6` |
| `critic` | Pre-implementation gate and blocker sounding board; records verdicts in basic-memory project notes. | `github-copilot/claude-opus-4.6` |
| `sme` | Subject-matter expert for domain-specific consultation; records guidance in basic-memory notes. | `github-copilot/claude-opus-4.6` |
| `designer` | UI/UX specialist for interaction and visual guidance; records design decisions in basic-memory project notes. | `github-copilot/claude-sonnet-4.6` |
All agents except `lead`, `coder`, and `librarian` are code/source read-only but have `permission.edit: allow` scoped to `.memory/*` writes for their recording duties. The `lead` and `librarian` have full edit access; `coder` has full edit access for implementation.
All agents except `lead`, `coder`, and `librarian` are code/source read-only. Agents with `permission.edit: allow` may update basic-memory notes for their recording duties; they must not edit implementation source files.
## Parallelization