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.
- package/README.md +48 -22
- package/dist/agents/prompt-utils.d.ts +3 -0
- package/dist/background/background-manager.d.ts +12 -6
- package/dist/cli/index.js +10 -4
- package/dist/config/loader.d.ts +2 -2
- package/dist/config/schema.d.ts +0 -31
- package/dist/delegation/delegation-manager.d.ts +8 -2
- package/dist/delegation/project-id.d.ts +10 -1
- package/dist/hooks/auto-update-checker/index.d.ts +2 -1
- package/dist/hooks/index.d.ts +0 -1
- package/dist/hooks/phase-reminder/index.d.ts +1 -1
- package/dist/hooks/thoth-mem/protocol.d.ts +2 -1
- package/dist/index.js +638 -560
- package/dist/mcp/websearch.d.ts +0 -4
- package/oh-my-opencode-lite.schema.json +0 -37
- package/package.json +4 -4
- package/src/skills/_shared/openspec-convention.md +17 -0
- package/src/skills/_shared/persistence-contract.md +63 -11
- package/src/skills/_shared/thoth-mem-convention.md +65 -7
- package/src/skills/cartography/SKILL.md +160 -160
- package/src/skills/executing-plans/SKILL.md +36 -27
- package/src/skills/requirements-interview/SKILL.md +192 -0
- package/src/skills/sdd-apply/SKILL.md +8 -18
- package/src/skills/sdd-archive/SKILL.md +0 -1
- package/src/skills/sdd-design/SKILL.md +0 -1
- package/src/skills/sdd-init/SKILL.md +157 -0
- package/src/skills/sdd-propose/SKILL.md +3 -2
- package/src/skills/sdd-spec/SKILL.md +1 -2
- package/src/skills/sdd-tasks/SKILL.md +0 -1
- package/src/skills/sdd-verify/SKILL.md +0 -1
- package/src/skills/brainstorming/SKILL.md +0 -120
package/dist/mcp/websearch.d.ts
CHANGED
|
@@ -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.
|
|
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.
|
|
58
|
-
"@opencode-ai/sdk": "^1.
|
|
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.
|
|
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
|
-
|
|
69
|
+
### 3-Layer Recall for thoth-mem and hybrid modes
|
|
41
70
|
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
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`,
|
|
48
|
-
key
|
|
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
|
-
|
|
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
|
-
-
|
|
72
|
-
|
|
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
|
-
##
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
61
|
-
|
|
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
|
|
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**
|
|
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
|
-
|
|
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
|
+
```
|