oh-my-opencode-lite 0.1.0

package/src/skills/_shared/openspec-convention.md

@@ -0,0 +1,92 @@
+# OpenSpec Convention
+
+## Mode Scope
+
+This convention applies only when the artifact store mode includes OpenSpec:
+`openspec` and `hybrid`.
+
+- In `thoth-mem` mode, skip canonical `openspec/` file writes.
+- In `thoth-mem` mode, skip filesystem artifact recovery.
+
+## Directory Structure
+
+```text
+openspec/
+├── config.yaml
+├── specs/
+│   └── {domain}/spec.md
+└── changes/
+    ├── archive/
+    └── {change-name}/
+        ├── proposal.md
+        ├── specs/
+        │   └── {domain}/spec.md
+        ├── design.md
+        ├── tasks.md
+        └── verify-report.md
+```
+
+## Canonical Artifacts
+
+| Artifact | Canonical path | Notes |
+| --- | --- | --- |
+| Proposal | `openspec/changes/{change-name}/proposal.md` | Intent, scope, approach |
+| Delta specs | `openspec/changes/{change-name}/specs/{domain}/spec.md` | Use one file per domain |
+| Main specs | `openspec/specs/{domain}/spec.md` | Source of truth after archive |
+| Design | `openspec/changes/{change-name}/design.md` | Architecture and file plan |
+| Tasks | `openspec/changes/{change-name}/tasks.md` | Checkbox checklist updated by apply |
+| Verify report | `openspec/changes/{change-name}/verify-report.md` | Compliance matrix and evidence |
+
+`apply-progress` and `archive-report` are durable SDD artifacts, but they are
+primarily persisted through thoth-mem topic keys when the mode includes
+thoth-mem.
+
+## Writing Rules
+
+- Preserve canonical filenames and locations.
+- Read an existing artifact before rewriting it.
+- Keep change-specific artifacts under
+  `openspec/changes/{change-name}/...`.
+- Keep long-lived specs under `openspec/specs/{domain}/spec.md`.
+- Archive completed changes under
+  `openspec/changes/archive/YYYY-MM-DD-{change-name}/`.
+
+## Artifact Content Rules
+
+- `proposal.md` explains why the change exists.
+- `spec.md` uses RFC 2119 keywords and Given/When/Then scenarios.
+- `design.md` explains how the change will be implemented.
+- `tasks.md` is phase-based and uses Markdown checkboxes.
+- `verify-report.md` maps spec scenarios to executed evidence.
+
+## `config.yaml` Shape
+
+```yaml
+schema: spec-driven
+
+context: |
+  Project background, stack, and constraints.
+
+rules:
+  proposal:
+    - Proposal-specific guidance
+  specs:
+    - Require RFC 2119 keywords
+    - Require Given/When/Then scenarios
+  design:
+    - Document architecture decisions with rationale
+  tasks:
+    - Use phased checklists with hierarchical numbering
+  apply:
+    - Match repository conventions
+    tdd: false
+    test_command: ''
+  verify:
+    test_command: ''
+    build_command: ''
+    coverage_threshold: 0
+  archive:
+    - Warn before destructive merges
+```
+
+Treat `rules` entries as mandatory phase-specific constraints whenever present.

package/src/skills/_shared/persistence-contract.md

@@ -0,0 +1,78 @@
+# Persistence Contract
+
+## Supported Persistence Modes
+
+| Mode | Read order | Write targets | Use when |
+| --- | --- | --- | --- |
+| `thoth-mem` | thoth-mem only | thoth-mem only | The user wants no repo artifact changes |
+| `openspec` | filesystem only | OpenSpec files only | The user wants visible repo artifacts without memory overhead |
+| `hybrid` | thoth-mem, then filesystem fallback | thoth-mem and OpenSpec files | The change should survive compaction and exist in the repo |
+
+SDD skills MUST obey the selected artifact store mode. Do not reference or rely
+on engram.
+
+## Mode Rules
+
+### `thoth-mem`
+
+1. Read SDD artifacts from thoth-mem only.
+2. Write SDD artifacts to thoth-mem only.
+3. Do not create or modify canonical `openspec/` artifacts.
+
+### `openspec`
+
+1. Read SDD artifacts from canonical OpenSpec paths only.
+2. Write SDD artifacts to canonical OpenSpec paths only.
+3. Do not call thoth-mem save or recovery tools.
+
+## Hybrid Rules
+
+When running in `hybrid` mode:
+
+1. Write the canonical OpenSpec artifact to the filesystem.
+2. Persist the same full artifact to thoth-mem with a deterministic `topic_key`.
+3. Treat the operation as complete only when both writes succeed.
+4. If filesystem and memory diverge, repair them immediately by rewriting the
+   stale copy from the freshest full artifact.
+
+## Retrieval Protocol
+
+Always recover SDD dependencies in this order:
+
+1. If the mode is `thoth-mem`, use `thoth_mem_mem_search` with the exact SDD
+   topic key, then `thoth_mem_mem_get_observation` using the returned
+   observation ID.
+2. If the mode is `openspec`, read the canonical OpenSpec path from the
+   filesystem only.
+3. If the mode is `hybrid`, use `thoth_mem_mem_search` with the exact SDD topic
+   key, then `thoth_mem_mem_get_observation` using the returned observation ID.
+4. In `hybrid`, if nothing is found in thoth-mem, read the canonical OpenSpec
+   path from the filesystem.
+5. In `hybrid`, if filesystem recovery succeeds, re-save the artifact to
+   thoth-mem so the two stores converge again.
+
+Never treat the preview returned by `thoth_mem_mem_search` as full source
+material.
+
+## Artifact Ownership
+
+- `sdd-propose` persists `sdd/{change-name}/proposal`
+- `sdd-spec` persists `sdd/{change-name}/spec`
+- `sdd-design` persists `sdd/{change-name}/design`
+- `sdd-tasks` persists `sdd/{change-name}/tasks`
+- `sdd-apply` persists `sdd/{change-name}/apply-progress` and re-persists
+  updated `sdd/{change-name}/tasks`
+- `sdd-verify` persists `sdd/{change-name}/verify-report`
+- `sdd-archive` persists `sdd/{change-name}/archive-report`
+
+## Recovery Notes
+
+- Prefer exact topic-key queries over fuzzy natural-language search.
+- If multiple observations match, choose the exact topic-key match for the
+  current project.
+- In `openspec` mode, repair missing or stale artifacts by rewriting the
+  canonical OpenSpec file only.
+- In `thoth-mem` mode, repair missing or stale artifacts by re-saving the full
+  artifact to thoth-mem only.
+- In `hybrid` mode, use the filesystem copy only as fallback or repair input,
+  then converge both stores.

package/src/skills/_shared/thoth-mem-convention.md

@@ -0,0 +1,80 @@
+# thoth-mem Convention
+
+## Mode Scope
+
+This convention applies only when the artifact store mode includes thoth-mem:
+`thoth-mem` and `hybrid`.
+
+- In `openspec` mode, skip thoth-mem saves.
+- In `openspec` mode, skip thoth-mem recovery and use filesystem artifacts
+  instead.
+
+## Tool Names
+
+Use the thoth-mem tool names exactly as exposed by the plugin:
+
+- `thoth_mem_mem_search`
+- `thoth_mem_mem_get_observation`
+- `thoth_mem_mem_save`
+- `thoth_mem_mem_update` (optional when you already have an observation ID)
+
+## Topic Key Format
+
+All SDD artifacts use this deterministic pattern:
+
+```text
+sdd/{change-name}/{artifact}
+```
+
+Supported artifact names:
+
+- `proposal`
+- `spec`
+- `design`
+- `design-brief`
+- `tasks`
+- `apply-progress`
+- `verify-report`
+- `archive-report`
+
+Use the same value for `title` and `topic_key` unless there is a strong reason
+not to.
+
+## Two-Step Recovery
+
+1. Search by exact topic key:
+
+```text
+thoth_mem_mem_search(
+  query: "sdd/{change-name}/{artifact}",
+  project: "{project}"
+)
+```
+
+2. Retrieve the full artifact:
+
+```text
+thoth_mem_mem_get_observation(id: {observation-id})
+```
+
+`thoth_mem_mem_search` returns previews only. Full SDD dependencies require the
+second call.
+
+## Save Contract
+
+Persist SDD artifacts with a stable topic key so repeated saves upsert instead
+of creating duplicates:
+
+```text
+thoth_mem_mem_save(
+  title: "sdd/{change-name}/{artifact}",
+  topic_key: "sdd/{change-name}/{artifact}",
+  type: "architecture",
+  project: "{project}",
+  scope: "project",
+  content: "{full artifact markdown}"
+)
+```
+
+For `sdd-apply`, save the progress report under `apply-progress` and re-save the
+updated task list under `tasks` after checkboxes change.

package/src/skills/brainstorming/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: brainstorming
+description: Clarify ambiguous work, assess scope, and choose the right planning path before implementation.
+metadata:
+  author: oh-my-opencode-lite
+  version: '1.0'
+---
+
+# Brainstorming Skill
+
+Use this skill to understand what should be built before implementation starts.
+The goal is clarity, scope calibration, and a user-approved handoff.
+
+## Shared Conventions
+
+- `~/.config/opencode/skills/_shared/thoth-mem-convention.md`
+- `~/.config/opencode/skills/_shared/persistence-contract.md`
+
+## HARD GATE
+
+- Do not implement during brainstorming.
+- Do not write code.
+- Do not patch files.
+- Do not create formal SDD artifacts until the user approves the route.
+
+## Workflow
+
+### Phase 1: Context Gathering
+
+1. Dispatch `@explorer` and `@librarian` in parallel for codebase and external
+   context.
+2. Collect only the minimum context needed to improve questions and reduce user
+   repetition.
+3. Prefer facts from the codebase and known references over asking the user for
+   information the environment can answer.
+
+### Phase 2: Interview
+
+1. Ask 1 question at a time.
+2. Ask at most 5 total questions.
+3. Prefer multiple-choice questions when practical.
+4. Stop early when clarity is already sufficient.
+5. Do not ask for details that the codebase, task artifacts, or gathered
+   context already answer.
+
+### Phase 3: Scope Assessment
+
+Evaluate these 7 scope signals:
+
+1. Multiple views, pages, or user flows
+2. New or modified API endpoints, queries, or data models
+3. Restructuring existing functionality
+4. Affects multiple layers such as frontend and backend, or UI and logic and
+   data
+5. Described in business or UX terms instead of specific code changes
+6. Scope is ambiguous or open-ended
+7. Would likely touch 3 or more files across different directories
+
+Signal mapping:
+
+- `0-1` = trivial
+- `2-4` = medium
+- `5+` = complex
+
+### Phase 4: Approach Proposal
+
+1. Present 2-3 viable options.
+2. For each option, give the main trade-offs.
+3. Mark one option as the recommendation.
+4. Ask the user to confirm the preferred approach before moving on.
+
+### Phase 5: User Approval
+
+Present:
+
+- Summary of understanding
+- Scope classification and why
+- Recommended approach
+- Proposed handoff path
+
+Then wait for explicit user approval.
+
+The user is the sole approver during brainstorming. Do not request oracle
+review here.
+
+### Phase 6: Handoff
+
+Recommend a route based on complexity, then wait for the user to confirm it:
+
+- Trivial (`1-2` files): direct implementation
+- Medium (`3-7` files): accelerated SDD (`propose -> tasks`)
+- Complex (`8+` files): full SDD (`propose -> spec -> design -> tasks`)
+
+Before any SDD generation starts, present the artifact store policy choice:
+
+```text
+How would you like to persist planning artifacts?
+1. thoth-mem — Memory only. Lightest token cost. No repo files.
+2. openspec — Repo files only. Visible and reviewable.
+3. hybrid — Both. Maximum durability, higher token cost.
+Default: hybrid
+```
+
+Do not silently choose the handoff route or artifact store mode. Recommend, ask,
+and wait.
+
+## Guardrails
+
+- Maximum 5 interview questions.
+- Ask only one question at a time.
+- Do not ask what codebase context can answer.
+- Do not skip explicit user approval.
+- Do not auto-select the handoff route.
+
+## Anti-Patterns
+
+- Question dumping
+- Option inflation
+- Premature implementation
+- Silent route selection

package/src/skills/cartography/README.md

@@ -0,0 +1,57 @@
+# Cartography Skill
+
+Repository understanding and hierarchical codemap generation.
+
+## Overview
+
+Cartography helps orchestrators map and understand codebases by:
+
+1. Selecting relevant code/config files using LLM judgment
+2. Creating `.lite/cartography.json` for change tracking
+3. Generating empty `codemap.md` templates for explorers to fill in
+
+## Commands
+
+```bash
+# Initialize mapping
+python3 cartographer.py init --root /repo --include "src/**/*.ts" --exclude "node_modules/**"
+
+# Check what changed
+python3 cartographer.py changes --root /repo
+
+# Update hashes
+python3 cartographer.py update --root /repo
+```
+
+## Outputs
+
+### .lite/cartography.json
+
+```json
+{
+  "metadata": {
+    "version": "1.0.0",
+    "last_run": "2026-01-25T19:00:00Z",
+    "include_patterns": ["src/**/*.ts"],
+    "exclude_patterns": ["node_modules/**"]
+  },
+  "file_hashes": {
+    "src/index.ts": "abc123..."
+  },
+  "folder_hashes": {
+    "src": "def456..."
+  }
+}
+```
+
+### codemap.md (per folder)
+
+Empty templates created in each folder for explorers to fill with:
+- Responsibility
+- Design patterns
+- Data/control flow
+- Integration points
+
+## Installation
+
+Installed automatically via oh-my-opencode-lite installer when custom skills are enabled.

package/src/skills/cartography/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: cartography
+description: Repository understanding and hierarchical codemap generation
+---
+
+# Cartography Skill
+
+You help users understand and map repositories by creating hierarchical codemaps.
+
+## When to Use
+
+- User asks to understand/map a repository
+- User wants codebase documentation
+- Starting work on an unfamiliar codebase
+
+## Workflow
+
+### Step 1: Check for Existing State
+
+**First, check if `.lite/cartography.json` exists in the repo root.**
+
+If it **exists**: Skip to Step 3 (Detect Changes) - no need to re-initialize.
+
+If it **doesn't exist**: Continue to Step 2 (Initialize).
+
+### Step 2: Initialize (Only if no state exists)
+
+1. **Analyze the repository structure** - List files, understand directories
+2. **Infer patterns** for **core code/config files ONLY** to include:
+   - **Include**: `src/**/*.ts`, `package.json`, etc.
+   - **Exclude (MANDATORY)**: Do NOT include tests, documentation, or translations.
+     - Tests: `**/*.test.ts`, `**/*.spec.ts`, `tests/**`, `__tests__/**`
+     - Docs: `docs/**`, `*.md` (except root `README.md` if needed), `LICENSE`
+     - Build/Deps: `node_modules/**`, `dist/**`, `build/**`, `*.min.js`
+   - Respect `.gitignore` automatically
+3. **Run cartographer.py init**:
+
+```bash
+python3 ~/.config/opencode/skills/cartography/scripts/cartographer.py init \
+  --root ./ \
+  --include "src/**/*.ts" \
+  --exclude "**/*.test.ts" --exclude "dist/**" --exclude "node_modules/**"
+```
+
+This creates:
+- `.lite/cartography.json` - File and folder hashes for change detection
+- Empty `codemap.md` files in all relevant subdirectories
+
+4. **Delegate to Explorer agents** - Spawn one explorer per folder to read code and fill in its specific `codemap.md` file.
+
+### Step 3: Detect Changes (If state already exists)
+
+1. **Run cartographer.py changes** to see what changed:
+
+```bash
+python3 ~/.config/opencode/skills/cartography/scripts/cartographer.py changes \
+  --root ./
+```
+
+2. **Review the output** - It shows:
+   - Added files
+   - Removed files
+   - Modified files
+   - Affected folders
+
+3. **Only update affected codemaps** - Spawn one explorer per affected folder to update its `codemap.md`.
+4. **Run update** to save new state:
+
+```bash
+python3 ~/.config/opencode/skills/cartography/scripts/cartographer.py update \
+  --root ./
+```
+
+### Step 4: Finalize Repository Atlas (Root Codemap)
+
+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.
+
+1.  **Map Root Assets**: Document the root-level files (e.g., `package.json`, `index.ts`, `plugin.json`) and the project's overall purpose.
+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.
+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.
+
+### Step 5: Register Codemap in AGENTS.md
+
+**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:
+
+1. If `AGENTS.md` already exists and already contains a `## Repository Map` section, **skip this step** — the reference is already set up.
+2. If `AGENTS.md` exists but has no `## Repository Map` section, **append** the section below.
+3. If `AGENTS.md` doesn't exist, **create** it with the section below.
+
+```markdown
+## Repository Map
+
+A full codemap is available at `codemap.md` in the project root.
+
+Before working on any task, read `codemap.md` to understand:
+- Project architecture and entry points
+- Directory responsibilities and design patterns
+- Data flow and integration points between modules
+
+For deep work on a specific folder, also read that folder's `codemap.md`.
+```
+
+This is idempotent — repeated cartography runs will detect the existing section and skip. No duplication.
+
+
+## Codemap Content
+
+Explorers are granted write permissions for `codemap.md` files during this workflow. Use precise technical terminology to document the implementation:
+
+- **Responsibility** - Define the specific role of this directory using standard software engineering terms (e.g., "Service Layer", "Data Access Object", "Middleware").
+- **Design Patterns** - Identify and name specific patterns used (e.g., "Observer", "Singleton", "Factory", "Strategy"). Detail the abstractions and interfaces.
+- **Data & Control Flow** - Explicitly trace how data enters and leaves the module. Mention specific function call sequences and state transitions.
+- **Integration Points** - List dependencies and consumer modules. Use technical names for hooks, events, or API endpoints.
+
+Example codemap:
+
+```markdown
+# src/agents/
+
+## Responsibility
+Defines agent personalities and manages their configuration lifecycle.
+
+## Design
+Each agent is a prompt + permission set. Config system uses:
+- Default prompts (orchestrator.ts, explorer.ts, etc.)
+- User overrides from ~/.config/opencode/oh-my-opencode-lite.json
+- Permission wildcards for skill/MCP access control
+
+## Flow
+1. Plugin loads → calls getAgentConfigs()
+2. Reads user config preset
+3. Merges defaults with overrides
+4. Applies permission rules (wildcard expansion)
+5. Returns agent configs to OpenCode
+
+## Integration
+- Consumed by: Main plugin (src/index.ts)
+- Depends on: Config loader, skills registry
+```
+
+Example **Root Codemap (Atlas)**:
+
+```markdown
+# Repository Atlas: oh-my-opencode-lite
+
+## Project Responsibility
+A high-performance, low-latency agent orchestration plugin for OpenCode, focusing on specialized sub-agent delegation and background task management.
+
+## System Entry Points
+- `src/index.ts`: Plugin initialization and OpenCode integration.
+- `package.json`: Dependency manifest and build scripts.
+- `oh-my-opencode-lite.json`: User configuration schema.
+
+## Directory Map (Aggregated)
+| Directory | Responsibility Summary | Detailed Map |
+|-----------|------------------------|--------------|
+| `src/agents/` | Defines agent personalities (Orchestrator, Explorer) and manages model routing. | [View Map](src/agents/codemap.md) |
+| `src/features/` | Core logic for tmux integration, background task spawning, and session state. | [View Map](src/features/codemap.md) |
+| `src/config/` | Implements the configuration loading pipeline and environment variable injection. | [View Map](src/config/codemap.md) |
+```