oh-my-opencode-lite 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,2 @@
1
1
  import type { RemoteMcpConfig } from './types';
2
- /**
3
- * Exa AI web search - real-time web search
4
- * @see https://exa.ai
5
- */
6
2
  export declare const websearch: RemoteMcpConfig;
@@ -499,43 +499,6 @@
499
499
  }
500
500
  }
501
501
  },
502
- "clarificationGate": {
503
- "type": "object",
504
- "properties": {
505
- "mode": {
506
- "default": "auto",
507
- "type": "string",
508
- "enum": [
509
- "off",
510
- "explicit-only",
511
- "auto",
512
- "auto-for-planning"
513
- ]
514
- },
515
- "min_scope_signals": {
516
- "default": 2,
517
- "type": "number",
518
- "minimum": 0
519
- },
520
- "hard_complex_signal_threshold": {
521
- "default": 3,
522
- "type": "number",
523
- "minimum": 0
524
- },
525
- "explicit_keywords": {
526
- "type": "array",
527
- "items": {
528
- "type": "string"
529
- }
530
- },
531
- "planning_keywords": {
532
- "type": "array",
533
- "items": {
534
- "type": "string"
535
- }
536
- }
537
- }
538
- },
539
502
  "artifactStore": {
540
503
  "type": "object",
541
504
  "properties": {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "oh-my-opencode-lite",
3
- "version": "0.1.0",
3
+ "version": "0.1.2",
4
4
  "description": "Delegate-first OpenCode plugin with seven agents, thoth-mem persistence, and bundled SDD skills.",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",
@@ -54,13 +54,13 @@
54
54
  "dependencies": {
55
55
  "@ast-grep/cli": "^0.40.0",
56
56
  "@modelcontextprotocol/sdk": "^1.26.0",
57
- "@opencode-ai/plugin": "^1.2.6",
58
- "@opencode-ai/sdk": "^1.2.6",
57
+ "@opencode-ai/plugin": "^1.3.3",
58
+ "@opencode-ai/sdk": "^1.3.3",
59
59
  "unique-names-generator": "^4.7.1",
60
60
  "vscode-jsonrpc": "^8.2.0",
61
61
  "vscode-languageserver-protocol": "^3.17.5",
62
62
  "which": "^6.0.0",
63
- "zod": "^4.3.6"
63
+ "zod": "^4.1.8"
64
64
  },
65
65
  "devDependencies": {
66
66
  "@biomejs/biome": "2.4.2",
@@ -8,6 +8,23 @@ This convention applies only when the artifact store mode includes OpenSpec:
8
8
  - In `thoth-mem` mode, skip canonical `openspec/` file writes.
9
9
  - In `thoth-mem` mode, skip filesystem artifact recovery.
10
10
 
11
+ ## Pre-flight Validation
12
+
13
+ When the selected persistence mode includes OpenSpec (`openspec` or `hybrid`),
14
+ every SDD skill must verify this structure before proceeding:
15
+
16
+ 1. `openspec/config.yaml` exists
17
+ 2. `openspec/specs/` exists
18
+ 3. `openspec/changes/` exists
19
+
20
+ If any required item is missing:
21
+
22
+ - STOP and inform the orchestrator that `openspec/` is not initialized.
23
+ - Recommend running the `sdd-init` skill first.
24
+ - Do NOT attempt to create the structure in that skill.
25
+
26
+ If all required items exist, continue normally.
27
+
11
28
  ## Directory Structure
12
29
 
13
30
  ```text
@@ -7,6 +7,7 @@
7
7
  | `thoth-mem` | thoth-mem only | thoth-mem only | The user wants no repo artifact changes |
8
8
  | `openspec` | filesystem only | OpenSpec files only | The user wants visible repo artifacts without memory overhead |
9
9
  | `hybrid` | thoth-mem, then filesystem fallback | thoth-mem and OpenSpec files | The change should survive compaction and exist in the repo |
10
+ | `none` | orchestrator prompt context only | nowhere (inline response only) | Ephemeral exploration, privacy-sensitive work, or no persistence backend available |
10
11
 
11
12
  SDD skills MUST obey the selected artifact store mode. Do not reference or rely
12
13
  on engram.
@@ -25,6 +26,15 @@ on engram.
25
26
  2. Write SDD artifacts to canonical OpenSpec paths only.
26
27
  3. Do not call thoth-mem save or recovery tools.
27
28
 
29
+ ### `none`
30
+
31
+ 1. Read SDD artifacts from orchestrator prompt context only.
32
+ 2. Do not persist artifacts to any external store.
33
+ 3. Return all artifacts as inline text in the response.
34
+ 4. Do not call thoth-mem save tools.
35
+ 5. Do not create or modify OpenSpec files.
36
+ 6. Recommend enabling `thoth-mem` or `openspec` for persistent work.
37
+
28
38
  ## Hybrid Rules
29
39
 
30
40
  When running in `hybrid` mode:
@@ -35,24 +45,63 @@ When running in `hybrid` mode:
35
45
  4. If filesystem and memory diverge, repair them immediately by rewriting the
36
46
  stale copy from the freshest full artifact.
37
47
 
48
+ ## Memory Ownership
49
+
50
+ Memory responsibilities are split between orchestrator and sub-agents:
51
+
52
+ **Orchestrator owns general memory:**
53
+ - Decisions, discoveries, bug fixes, session summaries
54
+ - Progress checkpoints (SDD task state updates)
55
+ - User preferences and configuration notes
56
+
57
+ **Sub-agents write deterministic SDD artifacts:**
58
+ - Canonical SDD artifacts with topic_key matching `sdd/{change}/{artifact}`
59
+ - Includes: proposal, spec, design, tasks, apply-progress, verify-report,
60
+ archive-report, state
61
+ - Sub-agents persist these directly when the active mode includes thoth-mem
62
+ - Sub-agents do NOT write general memory observations
63
+
64
+ This split preserves artifact nuance (sub-agents have full context when writing)
65
+ while keeping general memory centralized under orchestrator control.
66
+
38
67
  ## Retrieval Protocol
39
68
 
40
- Always recover SDD dependencies in this order:
69
+ ### 3-Layer Recall for thoth-mem and hybrid modes
41
70
 
42
- 1. If the mode is `thoth-mem`, use `thoth_mem_mem_search` with the exact SDD
43
- topic key, then `thoth_mem_mem_get_observation` using the returned
44
- observation ID.
71
+ Always complete the full 3-layer recall before using content as source material:
72
+
73
+ 1. **Layer 1 (Compact Index):** `thoth_mem_mem_search(..., mode: "compact")` —
74
+ scan the compact index of observation IDs and titles. This is the most
75
+ token-efficient entry point.
76
+ 2. **Layer 2 (Timeline Context):** `thoth_mem_mem_timeline(observation_id: {id})`
77
+ — retrieve chronological context (before/after observations) to disambiguate
78
+ or verify the correct artifact.
79
+ 3. **Layer 3 (Full Body):** `thoth_mem_mem_get_observation(id: {id})` — retrieve
80
+ the complete artifact body for use as source material.
81
+
82
+ **Mode guidance:**
83
+ - Use `mode: "compact"` (default) for most queries; it returns only IDs and
84
+ titles.
85
+ - Use `mode: "preview"` only when compact results are insufficient to
86
+ disambiguate between multiple candidates.
87
+
88
+ **Never treat `mem_search` output—compact or preview—as the artifact body.**
89
+ Always complete the 3-layer recall before using content as source material.
90
+
91
+ ### Mode-specific retrieval
92
+
93
+ 1. If the mode is `thoth-mem`, apply the 3-layer recall with the exact SDD
94
+ topic key.
45
95
  2. If the mode is `openspec`, read the canonical OpenSpec path from the
46
96
  filesystem only.
47
- 3. If the mode is `hybrid`, use `thoth_mem_mem_search` with the exact SDD topic
48
- key, then `thoth_mem_mem_get_observation` using the returned observation ID.
97
+ 3. If the mode is `hybrid`, apply the 3-layer recall with the exact SDD topic
98
+ key.
49
99
  4. In `hybrid`, if nothing is found in thoth-mem, read the canonical OpenSpec
50
100
  path from the filesystem.
51
101
  5. In `hybrid`, if filesystem recovery succeeds, re-save the artifact to
52
102
  thoth-mem so the two stores converge again.
53
-
54
- Never treat the preview returned by `thoth_mem_mem_search` as full source
55
- material.
103
+ 6. If the mode is `none`, read artifacts from the orchestrator prompt context
104
+ only. Do not attempt to retrieve from thoth-mem or filesystem.
56
105
 
57
106
  ## Artifact Ownership
58
107
 
@@ -64,12 +113,15 @@ material.
64
113
  updated `sdd/{change-name}/tasks`
65
114
  - `sdd-verify` persists `sdd/{change-name}/verify-report`
66
115
  - `sdd-archive` persists `sdd/{change-name}/archive-report`
116
+ - `state` persists `sdd/{change-name}/state`
67
117
 
68
118
  ## Recovery Notes
69
119
 
70
120
  - Prefer exact topic-key queries over fuzzy natural-language search.
71
- - If multiple observations match, choose the exact topic-key match for the
72
- current project.
121
+ - Always use the 3-layer recall (`mem_search` `mem_timeline`
122
+ `mem_get_observation`) before treating an artifact as source material.
123
+ - If multiple observations match in `mem_search`, use `mem_timeline` to inspect
124
+ chronological context and disambiguate.
73
125
  - In `openspec` mode, repair missing or stale artifacts by rewriting the
74
126
  canonical OpenSpec file only.
75
127
  - In `thoth-mem` mode, repair missing or stale artifacts by re-saving the full
@@ -14,6 +14,7 @@ This convention applies only when the artifact store mode includes thoth-mem:
14
14
  Use the thoth-mem tool names exactly as exposed by the plugin:
15
15
 
16
16
  - `thoth_mem_mem_search`
17
+ - `thoth_mem_mem_timeline`
17
18
  - `thoth_mem_mem_get_observation`
18
19
  - `thoth_mem_mem_save`
19
20
  - `thoth_mem_mem_update` (optional when you already have an observation ID)
@@ -36,32 +37,89 @@ Supported artifact names:
36
37
  - `apply-progress`
37
38
  - `verify-report`
38
39
  - `archive-report`
40
+ - `state`
39
41
 
40
42
  Use the same value for `title` and `topic_key` unless there is a strong reason
41
43
  not to.
42
44
 
43
- ## Two-Step Recovery
45
+ ## State Artifact Format
46
+
47
+ The orchestrator persists a lightweight state checkpoint after each SDD phase
48
+ transition to enable recovery:
49
+
50
+ ```yaml
51
+ change: {change-name}
52
+ phase: {last-completed-phase}
53
+ mode: {thoth-mem|openspec|hybrid|none}
54
+ artifacts:
55
+ proposal: true
56
+ spec: false
57
+ design: false
58
+ tasks: false
59
+ apply-progress: false
60
+ verify-report: false
61
+ archive-report: false
62
+ last_updated: {ISO 8601 timestamp}
63
+ ```
44
64
 
45
- 1. Search by exact topic key:
65
+ Save with:
66
+
67
+ ```text
68
+ thoth_mem_mem_save(
69
+ title: "sdd/{change-name}/state",
70
+ topic_key: "sdd/{change-name}/state",
71
+ type: "architecture",
72
+ project: "{project}",
73
+ scope: "project",
74
+ content: "{YAML state content}"
75
+ )
76
+ ```
77
+
78
+ Recovery: `thoth_mem_mem_search("sdd/{change-name}/state")` → `thoth_mem_mem_get_observation(id)` → parse YAML → restore phase state.
79
+
80
+ ## Three-Layer Recall Protocol
81
+
82
+ 1. **Scan compact index** by exact topic key:
46
83
 
47
84
  ```text
48
85
  thoth_mem_mem_search(
49
- query: "sdd/{change-name}/{artifact}",
50
- project: "{project}"
86
+ query: "topic_key:sdd/{change-name}/{artifact}",
87
+ project: "{project}",
88
+ mode: "compact"
89
+ )
90
+ ```
91
+
92
+ Use `mode: "compact"` (the default) for token efficiency. Switch to `mode: "preview"`
93
+ only when compact results are insufficient to disambiguate between multiple results.
94
+
95
+ 2. **Get chronological context** around the found observation:
96
+
97
+ ```text
98
+ thoth_mem_mem_timeline(
99
+ observation_id: {id},
100
+ before: 5,
101
+ after: 5
51
102
  )
52
103
  ```
53
104
 
54
- 2. Retrieve the full artifact:
105
+ This shows related observations in the same session, helping you understand the
106
+ artifact's evolution and dependencies.
107
+
108
+ 3. **Retrieve full artifact content**:
55
109
 
56
110
  ```text
57
111
  thoth_mem_mem_get_observation(id: {observation-id})
58
112
  ```
59
113
 
60
- `thoth_mem_mem_search` returns previews only. Full SDD dependencies require the
61
- second call.
114
+ Search returns compact results (IDs + titles) by default. Neither compact nor
115
+ preview mode returns the full artifact body. Always complete the 3-layer recall
116
+ to get the actual content.
62
117
 
63
118
  ## Save Contract
64
119
 
120
+ **CRITICAL:** The orchestrator MUST persist the state artifact after each SDD
121
+ phase transition. This is the canonical checkpoint for resume/recovery.
122
+
65
123
  Persist SDD artifacts with a stable topic key so repeated saves upsert instead
66
124
  of creating duplicates:
67
125
 
@@ -1,160 +1,160 @@
1
- ---
2
- name: cartography
3
- description: Repository understanding and hierarchical codemap generation
4
- ---
5
-
6
- # Cartography Skill
7
-
8
- You help users understand and map repositories by creating hierarchical codemaps.
9
-
10
- ## When to Use
11
-
12
- - User asks to understand/map a repository
13
- - User wants codebase documentation
14
- - Starting work on an unfamiliar codebase
15
-
16
- ## Workflow
17
-
18
- ### Step 1: Check for Existing State
19
-
20
- **First, check if `.lite/cartography.json` exists in the repo root.**
21
-
22
- If it **exists**: Skip to Step 3 (Detect Changes) - no need to re-initialize.
23
-
24
- If it **doesn't exist**: Continue to Step 2 (Initialize).
25
-
26
- ### Step 2: Initialize (Only if no state exists)
27
-
28
- 1. **Analyze the repository structure** - List files, understand directories
29
- 2. **Infer patterns** for **core code/config files ONLY** to include:
30
- - **Include**: `src/**/*.ts`, `package.json`, etc.
31
- - **Exclude (MANDATORY)**: Do NOT include tests, documentation, or translations.
32
- - Tests: `**/*.test.ts`, `**/*.spec.ts`, `tests/**`, `__tests__/**`
33
- - Docs: `docs/**`, `*.md` (except root `README.md` if needed), `LICENSE`
34
- - Build/Deps: `node_modules/**`, `dist/**`, `build/**`, `*.min.js`
35
- - Respect `.gitignore` automatically
36
- 3. **Run cartographer.py init**:
37
-
38
- ```bash
39
- python3 ~/.config/opencode/skills/cartography/scripts/cartographer.py init \
40
- --root ./ \
41
- --include "src/**/*.ts" \
42
- --exclude "**/*.test.ts" --exclude "dist/**" --exclude "node_modules/**"
43
- ```
44
-
45
- This creates:
46
- - `.lite/cartography.json` - File and folder hashes for change detection
47
- - Empty `codemap.md` files in all relevant subdirectories
48
-
49
- 4. **Delegate to Explorer agents** - Spawn one explorer per folder to read code and fill in its specific `codemap.md` file.
50
-
51
- ### Step 3: Detect Changes (If state already exists)
52
-
53
- 1. **Run cartographer.py changes** to see what changed:
54
-
55
- ```bash
56
- python3 ~/.config/opencode/skills/cartography/scripts/cartographer.py changes \
57
- --root ./
58
- ```
59
-
60
- 2. **Review the output** - It shows:
61
- - Added files
62
- - Removed files
63
- - Modified files
64
- - Affected folders
65
-
66
- 3. **Only update affected codemaps** - Spawn one explorer per affected folder to update its `codemap.md`.
67
- 4. **Run update** to save new state:
68
-
69
- ```bash
70
- python3 ~/.config/opencode/skills/cartography/scripts/cartographer.py update \
71
- --root ./
72
- ```
73
-
74
- ### Step 4: Finalize Repository Atlas (Root Codemap)
75
-
76
- Once all specific directories are mapped, the Orchestrator must create or update the root `codemap.md`. This file serves as the **Master Entry Point** for any agent or human entering the repository.
77
-
78
- 1. **Map Root Assets**: Document the root-level files (e.g., `package.json`, `index.ts`, `plugin.json`) and the project's overall purpose.
79
- 2. **Aggregate Sub-Maps**: Create a "Repository Directory Map" section. For every folder that has a `codemap.md`, extract its **Responsibility** summary and include it in a table or list in the root map.
80
- 3. **Cross-Reference**: Ensure that the root map contains the absolute or relative paths to the sub-maps so agents can jump directly to the relevant details.
81
-
82
- ### Step 5: Register Codemap in AGENTS.md
83
-
84
- **OpenCode auto-loads `AGENTS.md` into agent context on every session.** To ensure agents automatically discover and use the codemap, update (or create) `AGENTS.md` at the repo root:
85
-
86
- 1. If `AGENTS.md` already exists and already contains a `## Repository Map` section, **skip this step** — the reference is already set up.
87
- 2. If `AGENTS.md` exists but has no `## Repository Map` section, **append** the section below.
88
- 3. If `AGENTS.md` doesn't exist, **create** it with the section below.
89
-
90
- ```markdown
91
- ## Repository Map
92
-
93
- A full codemap is available at `codemap.md` in the project root.
94
-
95
- Before working on any task, read `codemap.md` to understand:
96
- - Project architecture and entry points
97
- - Directory responsibilities and design patterns
98
- - Data flow and integration points between modules
99
-
100
- For deep work on a specific folder, also read that folder's `codemap.md`.
101
- ```
102
-
103
- This is idempotent — repeated cartography runs will detect the existing section and skip. No duplication.
104
-
105
-
106
- ## Codemap Content
107
-
108
- Explorers are granted write permissions for `codemap.md` files during this workflow. Use precise technical terminology to document the implementation:
109
-
110
- - **Responsibility** - Define the specific role of this directory using standard software engineering terms (e.g., "Service Layer", "Data Access Object", "Middleware").
111
- - **Design Patterns** - Identify and name specific patterns used (e.g., "Observer", "Singleton", "Factory", "Strategy"). Detail the abstractions and interfaces.
112
- - **Data & Control Flow** - Explicitly trace how data enters and leaves the module. Mention specific function call sequences and state transitions.
113
- - **Integration Points** - List dependencies and consumer modules. Use technical names for hooks, events, or API endpoints.
114
-
115
- Example codemap:
116
-
117
- ```markdown
118
- # src/agents/
119
-
120
- ## Responsibility
121
- Defines agent personalities and manages their configuration lifecycle.
122
-
123
- ## Design
124
- Each agent is a prompt + permission set. Config system uses:
125
- - Default prompts (orchestrator.ts, explorer.ts, etc.)
126
- - User overrides from ~/.config/opencode/oh-my-opencode-lite.json
127
- - Permission wildcards for skill/MCP access control
128
-
129
- ## Flow
130
- 1. Plugin loads → calls getAgentConfigs()
131
- 2. Reads user config preset
132
- 3. Merges defaults with overrides
133
- 4. Applies permission rules (wildcard expansion)
134
- 5. Returns agent configs to OpenCode
135
-
136
- ## Integration
137
- - Consumed by: Main plugin (src/index.ts)
138
- - Depends on: Config loader, skills registry
139
- ```
140
-
141
- Example **Root Codemap (Atlas)**:
142
-
143
- ```markdown
144
- # Repository Atlas: oh-my-opencode-lite
145
-
146
- ## Project Responsibility
147
- A high-performance, low-latency agent orchestration plugin for OpenCode, focusing on specialized sub-agent delegation and background task management.
148
-
149
- ## System Entry Points
150
- - `src/index.ts`: Plugin initialization and OpenCode integration.
151
- - `package.json`: Dependency manifest and build scripts.
152
- - `oh-my-opencode-lite.json`: User configuration schema.
153
-
154
- ## Directory Map (Aggregated)
155
- | Directory | Responsibility Summary | Detailed Map |
156
- |-----------|------------------------|--------------|
157
- | `src/agents/` | Defines agent personalities (Orchestrator, Explorer) and manages model routing. | [View Map](src/agents/codemap.md) |
158
- | `src/features/` | Core logic for tmux integration, background task spawning, and session state. | [View Map](src/features/codemap.md) |
159
- | `src/config/` | Implements the configuration loading pipeline and environment variable injection. | [View Map](src/config/codemap.md) |
160
- ```
1
+ ---
2
+ name: cartography
3
+ description: Repository understanding and hierarchical codemap generation
4
+ ---
5
+
6
+ # Cartography Skill
7
+
8
+ You help users understand and map repositories by creating hierarchical codemaps.
9
+
10
+ ## When to Use
11
+
12
+ - User asks to understand/map a repository
13
+ - User wants codebase documentation
14
+ - Starting work on an unfamiliar codebase
15
+
16
+ ## Workflow
17
+
18
+ ### Step 1: Check for Existing State
19
+
20
+ **First, check if `.lite/cartography.json` exists in the repo root.**
21
+
22
+ If it **exists**: Skip to Step 3 (Detect Changes) - no need to re-initialize.
23
+
24
+ If it **doesn't exist**: Continue to Step 2 (Initialize).
25
+
26
+ ### Step 2: Initialize (Only if no state exists)
27
+
28
+ 1. **Analyze the repository structure** - List files, understand directories
29
+ 2. **Infer patterns** for **core code/config files ONLY** to include:
30
+ - **Include**: `src/**/*.ts`, `package.json`, etc.
31
+ - **Exclude (MANDATORY)**: Do NOT include tests, documentation, or translations.
32
+ - Tests: `**/*.test.ts`, `**/*.spec.ts`, `tests/**`, `__tests__/**`
33
+ - Docs: `docs/**`, `*.md` (except root `README.md` if needed), `LICENSE`
34
+ - Build/Deps: `node_modules/**`, `dist/**`, `build/**`, `*.min.js`
35
+ - Respect `.gitignore` automatically
36
+ 3. **Run cartographer.py init**:
37
+
38
+ ```bash
39
+ python3 ~/.config/opencode/skills/cartography/scripts/cartographer.py init \
40
+ --root ./ \
41
+ --include "src/**/*.ts" \
42
+ --exclude "**/*.test.ts" --exclude "dist/**" --exclude "node_modules/**"
43
+ ```
44
+
45
+ This creates:
46
+ - `.lite/cartography.json` - File and folder hashes for change detection
47
+ - Empty `codemap.md` files in all relevant subdirectories
48
+
49
+ 4. **Delegate discovery to explorer agents** Spawn one explorer per folder to read code and gather findings. Then **delegate to quick** to write each folder's `codemap.md` based on explorer findings.
50
+
51
+ ### Step 3: Detect Changes (If state already exists)
52
+
53
+ 1. **Run cartographer.py changes** to see what changed:
54
+
55
+ ```bash
56
+ python3 ~/.config/opencode/skills/cartography/scripts/cartographer.py changes \
57
+ --root ./
58
+ ```
59
+
60
+ 2. **Review the output** - It shows:
61
+ - Added files
62
+ - Removed files
63
+ - Modified files
64
+ - Affected folders
65
+
66
+ 3. **Only update affected codemaps** Spawn one explorer per affected folder to gather updated findings, then dispatch quick to write the updated `codemap.md`.
67
+ 4. **Run update** to save new state:
68
+
69
+ ```bash
70
+ python3 ~/.config/opencode/skills/cartography/scripts/cartographer.py update \
71
+ --root ./
72
+ ```
73
+
74
+ ### Step 4: Finalize Repository Atlas (Root Codemap)
75
+
76
+ Once all specific directories are mapped, the Orchestrator must dispatch quick to create or update the root `codemap.md`. This file serves as the **Master Entry Point** for any agent or human entering the repository.
77
+
78
+ 1. **Map Root Assets**: Document the root-level files (e.g., `package.json`, `index.ts`, `plugin.json`) and the project's overall purpose.
79
+ 2. **Aggregate Sub-Maps**: Create a "Repository Directory Map" section. For every folder that has a `codemap.md`, extract its **Responsibility** summary and include it in a table or list in the root map.
80
+ 3. **Cross-Reference**: Ensure that the root map contains the absolute or relative paths to the sub-maps so agents can jump directly to the relevant details.
81
+
82
+ ### Step 5: Register Codemap in AGENTS.md
83
+
84
+ **OpenCode auto-loads `AGENTS.md` into agent context on every session.** To ensure agents automatically discover and use the codemap, dispatch quick to update (or create) `AGENTS.md` at the repo root:
85
+
86
+ 1. If `AGENTS.md` already exists and already contains a `## Repository Map` section, **skip this step** — the reference is already set up.
87
+ 2. If `AGENTS.md` exists but has no `## Repository Map` section, **append** the section below.
88
+ 3. If `AGENTS.md` doesn't exist, **create** it with the section below.
89
+
90
+ ```markdown
91
+ ## Repository Map
92
+
93
+ A full codemap is available at `codemap.md` in the project root.
94
+
95
+ Before working on any task, read `codemap.md` to understand:
96
+ - Project architecture and entry points
97
+ - Directory responsibilities and design patterns
98
+ - Data flow and integration points between modules
99
+
100
+ For deep work on a specific folder, also read that folder's `codemap.md`.
101
+ ```
102
+
103
+ This is idempotent — repeated cartography runs will detect the existing section and skip. No duplication.
104
+
105
+
106
+ ## Codemap Content
107
+
108
+ Explorer agents gather the technical findings; quick agents write the `codemap.md` files. Use precise technical terminology to document the implementation:
109
+
110
+ - **Responsibility** - Define the specific role of this directory using standard software engineering terms (e.g., "Service Layer", "Data Access Object", "Middleware").
111
+ - **Design Patterns** - Identify and name specific patterns used (e.g., "Observer", "Singleton", "Factory", "Strategy"). Detail the abstractions and interfaces.
112
+ - **Data & Control Flow** - Explicitly trace how data enters and leaves the module. Mention specific function call sequences and state transitions.
113
+ - **Integration Points** - List dependencies and consumer modules. Use technical names for hooks, events, or API endpoints.
114
+
115
+ Example codemap:
116
+
117
+ ```markdown
118
+ # src/agents/
119
+
120
+ ## Responsibility
121
+ Defines agent personalities and manages their configuration lifecycle.
122
+
123
+ ## Design
124
+ Each agent is a prompt + permission set. Config system uses:
125
+ - Default prompts (orchestrator.ts, explorer.ts, etc.)
126
+ - User overrides from ~/.config/opencode/oh-my-opencode-lite.json
127
+ - Permission wildcards for skill/MCP access control
128
+
129
+ ## Flow
130
+ 1. Plugin loads → calls getAgentConfigs()
131
+ 2. Reads user config preset
132
+ 3. Merges defaults with overrides
133
+ 4. Applies permission rules (wildcard expansion)
134
+ 5. Returns agent configs to OpenCode
135
+
136
+ ## Integration
137
+ - Consumed by: Main plugin (src/index.ts)
138
+ - Depends on: Config loader, skills registry
139
+ ```
140
+
141
+ Example **Root Codemap (Atlas)**:
142
+
143
+ ```markdown
144
+ # Repository Atlas: oh-my-opencode-lite
145
+
146
+ ## Project Responsibility
147
+ A high-performance, low-latency agent orchestration plugin for OpenCode, focusing on specialized sub-agent delegation and background task management.
148
+
149
+ ## System Entry Points
150
+ - `src/index.ts`: Plugin initialization and OpenCode integration.
151
+ - `package.json`: Dependency manifest and build scripts.
152
+ - `oh-my-opencode-lite.json`: User configuration schema.
153
+
154
+ ## Directory Map (Aggregated)
155
+ | Directory | Responsibility Summary | Detailed Map |
156
+ |-----------|------------------------|--------------|
157
+ | `src/agents/` | Defines agent personalities (Orchestrator, Explorer) and manages model routing. | [View Map](src/agents/codemap.md) |
158
+ | `src/features/` | Core logic for tmux integration, background task spawning, and session state. | [View Map](src/features/codemap.md) |
159
+ | `src/config/` | Implements the configuration loading pipeline and environment variable injection. | [View Map](src/config/codemap.md) |
160
+ ```