oh-my-opencode-lite 0.1.0

package/src/skills/executing-plans/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: executing-plans
+description: Execute SDD task lists with real-time progress tracking, sub-agent dispatch, and verification checkpoints.
+metadata:
+  author: oh-my-opencode-lite
+  version: '1.0'
+---
+
+# Executing Plans Skill
+
+Use this skill to execute an existing SDD task list end to end while keeping
+task progress durable, ordered, and verifiable.
+
+## Shared Conventions
+
+- `~/.config/opencode/skills/_shared/openspec-convention.md`
+- `~/.config/opencode/skills/_shared/persistence-contract.md`
+- `~/.config/opencode/skills/_shared/thoth-mem-convention.md`
+
+## Ownership Model
+
+The orchestrator owns task progress tracking.
+
+- The orchestrator marks `- [ ]` to `- [~]` before dispatching execution work.
+- The orchestrator marks `- [~]` to `- [x]` only after successful results are
+  received and verified.
+- The orchestrator marks `- [-]` with a clear reason when a task is skipped or
+  fails after escalation.
+- `openspec/` files are coordination artifacts, not source code. The
+  orchestrator may read and edit them directly for progress tracking and state
+  management.
+
+Sub-agents execute assigned work and return structured results. They do not own
+checkbox updates.
+
+## When to Use
+
+- Executing an SDD task list
+- Resuming work from a previous session
+- Multi-task implementation with an existing change already defined
+
+## Workflow
+
+### Phase 1: Load
+
+1. Scan `openspec/changes/` for active changes.
+2. Read `tasks.md` and find the first unchecked task in state `- [ ]` or
+   `- [~]`.
+3. Build a mental model of the plan: total tasks, remaining work,
+   parallelizable work, and dependency order.
+4. Load SDD context from the change directory plus thoth-mem fallback using the
+   retrieval protocol in
+   `~/.config/opencode/skills/_shared/persistence-contract.md`.
+5. Determine the artifact store mode from config before reading or writing any
+   SDD artifacts.
+
+### Phase 2: Execute Each Task
+
+#### A. Mark In-Progress
+
+Before dispatching a task:
+
+1. Edit the canonical tasks artifact and change the current task from
+   `- [ ]` to `- [~]`.
+2. If the mode is `thoth-mem` or `hybrid`, re-persist the updated tasks
+   artifact with topic key `sdd/{change-name}/tasks`.
+3. Re-read `tasks.md` after the edit to confirm the change persisted.
+
+#### B. Dispatch
+
+Choose the execution agent based on task type:
+
+| Need | Agent |
+| --- | --- |
+| Broad codebase discovery | `@explorer` |
+| External docs or APIs | `@librarian` |
+| Architecture or debugging | `@oracle` |
+| UI or UX work | `@designer` |
+| Simple, precise changes | `@quick` |
+| Complex, multi-file changes | `@deep` |
+
+Every dispatch prompt MUST include these 6 parts:
+
+1. `TASK` — exact task number and title
+2. `CONTEXT` — relevant proposal, spec, design, and prior-task state
+3. `REQUIREMENTS` — concrete outcomes and constraints
+4. `BOUNDARIES` — files, scope limits, and non-goals
+5. `VERIFICATION` — checks the sub-agent must run or report
+6. `RETURN ENVELOPE` — the exact structured response contract in this skill
+
+#### C. Receive and Verify
+
+Read the sub-agent return envelope and respond by status:
+
+- `completed`: inspect the reported file changes, run verification checks, and
+  confirm the task acceptance criteria were actually met.
+- `failed`: assess the blocker, decide whether to retry with sharper guidance,
+  switch agents, or escalate.
+- `partial`: assess what is already done, preserve that context, and dispatch a
+  focused follow-up for the remainder.
+
+#### D. Mark Complete
+
+After verified completion:
+
+1. Edit the canonical tasks artifact and change the task from `- [~]` to
+   `- [x]`.
+2. If the mode is `thoth-mem` or `hybrid`, re-persist the updated tasks
+   artifact under `sdd/{change-name}/tasks`.
+3. Persist a progress checkpoint under `sdd/{change-name}/apply-progress` when
+   the mode includes thoth-mem.
+4. Re-read `tasks.md` after the edit to confirm the completed state persisted.
+
+#### E. Auto-Continue
+
+Immediately proceed to the next task.
+
+Do not ask the user whether execution should continue unless one of these is
+true:
+
+- the work is truly blocked
+- a critical failure prevents safe continuation
+- the current task has failed 3 consecutive times
+
+### Phase 3: Between Tasks
+
+Between every task:
+
+1. Re-read `tasks.md` because later tasks may depend on earlier outputs.
+2. Re-check that assumptions still hold.
+3. If a prior task introduced breakage, fix that before starting the next task.
+
+### Phase 4: Escalation Policy
+
+- Attempt 1: re-dispatch the same task with explicit fix instructions and the
+  missing evidence called out.
+- Attempt 2: switch to a different agent or fix directly when appropriate.
+- Attempt 3: make one final targeted attempt with narrowed scope.
+- After 3 consecutive failures, mark the task `- [-]` with a clear reason and
+  escalate to the user.
+
+### Phase 5: Completion
+
+After the task list is complete:
+
+1. Run full verification: build, typecheck, tests, and lint using the project's
+   configured commands.
+2. Report a completion summary with evidence.
+3. If the work is SDD-backed, suggest `sdd-verify` as the next step.
+
+## Return Envelope Contract
+
+Every execution sub-agent MUST return this exact structure:
+
+```markdown
+## Task Result
+
+**Status**: completed | failed | partial
+**Task**: {task number and name}
+
+### What was done
+- {concrete change 1}
+- {concrete change 2}
+
+### Files changed
+- `path/to/file.ts` — {what changed}
+
+### Verification
+- {check 1}: passed | failed
+- {check 2}: passed | failed
+
+### Issues (if any)
+- {issue description} — {severity: critical | important | minor}
+
+### Failure reason (if failed)
+{Why it failed, what was attempted, what blocked progress}
+
+### Skip reason (if skipped)
+{Why it was skipped, what prerequisite is missing}
+```
+
+Treat missing sections or vague summaries as incomplete execution results.
+
+## Recovery Protocol
+
+To resume safely:
+
+1. Read `openspec/changes/` to identify active changes.
+2. Read `openspec/changes/{change-name}/tasks.md` and inspect checkbox state.
+3. If the mode includes thoth-mem, recover `sdd/{change-name}/apply-progress`
+   and `sdd/{change-name}/tasks` with the exact topic-key protocol.
+4. Resume from the first task marked `- [ ]` or `- [~]`.
+
+## Progress Tracking Rules
+
+1. Before dispatching, change `- [ ]` to `- [~]`.
+2. After verified completion, change `- [~]` to `- [x]`.
+3. After 3 retries, change the task to `- [-]` and add the explicit reason.
+4. Never batch-update multiple checkboxes at once.
+5. Never proceed without updating the current task state first.
+6. Re-read `tasks.md` after each edit to confirm persistence.
+
+## Guardrails
+
+- Do not execute tasks out of dependency order.
+- Do not mark a task complete without verification evidence.
+- Do not skip SDD context recovery.
+- Do not modify task-list structure; only update checkbox state and explicit skip
+  reasons.
+- Do not continue past a blocked task without escalation.
+- Do not claim completion without evidence.

package/src/skills/plan-reviewer/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: plan-reviewer
+description: Review SDD task plans for execution blockers and return [OKAY] or [REJECT].
+metadata:
+  author: oh-my-opencode-lite
+  version: '1.0'
+---
+
+# Plan Reviewer Skill
+
+Verify that an SDD task plan is executable, references valid files, and is safe
+to hand to implementation.
+
+## Shared Conventions
+
+- `~/.config/opencode/skills/_shared/openspec-convention.md`
+- `~/.config/opencode/skills/_shared/persistence-contract.md`
+- `~/.config/opencode/skills/_shared/thoth-mem-convention.md`
+
+## Purpose
+
+Review `openspec/changes/{change-name}/tasks.md` for true execution blockers.
+Focus on whether the plan can be executed as written, not whether you would have
+designed it differently.
+
+## Inputs
+
+- `change-name`
+- `openspec/changes/{change-name}/tasks.md`
+- Related proposal, spec, and design artifacts when needed for dependency checks
+
+## Task State Awareness
+
+Recognize these checklist states in `tasks.md`:
+
+- `- [ ]` pending
+- `- [~]` in progress
+- `- [x]` completed
+- `- [-]` skipped with reason
+
+Review executability of the remaining work. If a task is marked `- [-]`, ensure
+the skip reason is explicit and does not hide a blocker.
+
+## Review Checklist
+
+Check only what affects executability:
+
+1. Referenced file paths exist when they are supposed to already exist.
+2. New-file tasks use exact intended paths.
+3. Tasks reference exact file paths instead of vague areas.
+4. Each task includes a `Verification` section.
+5. Each `Verification` section includes both:
+   - `Run:`
+   - `Expected:`
+6. Dependency order is valid.
+7. The sequence is workable without hidden prerequisite steps.
+
+## Decision Rules
+
+- Default to `[OKAY]`.
+- Use `[REJECT]` only for true blockers.
+- A rejection may list at most 3 issues.
+- Do not reject for style preferences or optional improvements.
+
+## Output Format
+
+If the plan is executable:
+
+```text
+[OKAY]
+- Brief confirmation that the plan is executable.
+- Optional note on any non-blocking caution.
+```
+
+If the plan has blockers:
+
+```text
+[REJECT]
+1. <blocking issue>
+2. <blocking issue>
+3. <blocking issue>
+```
+
+For each rejected issue, include:
+
+- why it blocks execution
+- the smallest concrete fix
+
+## Anti-Patterns
+
+- No nitpicking.
+- No style opinions.
+- No design questioning.
+- No expanding the scope of review beyond blockers.
+- Do not return more than 3 rejection issues.
+
+## Review Standard
+
+Approve when a competent implementer can execute the plan without guessing about
+critical paths, missing files, or missing verification instructions.

package/src/skills/sdd-apply/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: sdd-apply
+description: Execute assigned SDD tasks and return structured implementation results.
+---
+
+# SDD Apply Skill
+
+Implement assigned SDD tasks and return durable execution results to the
+orchestrator.
+
+## Shared Conventions
+
+- Shared references:
+- `~/.config/opencode/skills/_shared/openspec-convention.md`
+- `~/.config/opencode/skills/_shared/persistence-contract.md`
+- `~/.config/opencode/skills/_shared/thoth-mem-convention.md`
+
+## Persistence Mode
+
+The orchestrator passes the artifact store mode (`thoth-mem`, `openspec`, or
+`hybrid`). Follow
+`~/.config/opencode/skills/_shared/persistence-contract.md` for read/write
+rules per mode.
+
+- `thoth-mem`: persist to thoth-mem only — do NOT create or modify
+  `openspec/` files.
+- `openspec`: write files only — do NOT call thoth-mem save tools.
+- `hybrid`: persist to both (default).
+
+## When to Use
+
+- A change has a task plan and implementation should begin or resume
+- A batch of checklist items must be executed and reported back to the
+  orchestrator
+
+## Prerequisites
+
+- `change-name`
+- Assigned task numbers or phase range
+- Spec, design, and task artifacts
+
+## Workflow
+
+1. Read the shared conventions.
+2. Recover `spec`, `design`, and `tasks` with the retrieval protocol in
+   `~/.config/opencode/skills/_shared/persistence-contract.md`.
+3. Read the affected code before editing anything.
+4. Execute only the assigned checklist items.
+5. In modes that include thoth-mem, persist an implementation progress report
+   with:
+
+   ```text
+   thoth_mem_mem_save(
+     title: "sdd/{change-name}/apply-progress",
+     topic_key: "sdd/{change-name}/apply-progress",
+     type: "architecture",
+     project: "{project}",
+     scope: "project",
+     content: "{progress report markdown}"
+   )
+   ```
+
+6. If the orchestrator requests it, include enough detail for it to update the
+   canonical tasks artifact and memory checkpoints accurately.
+
+## Response Format
+
+Return a structured result to the orchestrator:
+
+**Status**: completed | failed | partial
+**Task**: {task reference}
+**What was done**: {list of concrete changes}
+**Files changed**: {paths with descriptions}
+**Verification**: {check results}
+**Issues**: {any problems encountered}
+**Failure/Skip reason**: {if applicable}
+
+Progress tracking (checkbox state updates) is managed by the orchestrator
+via the `executing-plans` skill. Do not update task checkboxes yourself.
+
+## Output Format
+
+Return:
+
+- `Change`
+- `Completed Tasks`: assigned items completed or partially completed
+- `Files Changed`: concise table or bullets
+- `Progress Topic Key`: `sdd/{change-name}/apply-progress` when applicable
+- `Remaining Work`: next known pending work or blockers
+
+## Rules
+
+- Read specs before implementing; they are the acceptance contract.
+- Follow the design unless you explicitly report a justified deviation.
+- Update only the tasks assigned in the current batch.
+- Persist the progress artifact whenever the selected mode includes thoth-mem.
+- Retrieve every SDD dependency with the mode-aware protocol in
+  `~/.config/opencode/skills/_shared/persistence-contract.md`.
+- Return structured execution evidence to the orchestrator so it can manage task
+  state correctly.
+- Never reference engram.

package/src/skills/sdd-archive/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: sdd-archive
+description: Merge completed deltas into main specs and archive the change.
+---
+
+# SDD Archive Skill
+
+Close the SDD loop by promoting verified change specs into main specs and
+recording an audit trail.
+
+## Shared Conventions
+
+- Shared references:
+- `~/.config/opencode/skills/_shared/openspec-convention.md`
+- `~/.config/opencode/skills/_shared/persistence-contract.md`
+- `~/.config/opencode/skills/_shared/thoth-mem-convention.md`
+
+## Persistence Mode
+
+The orchestrator passes the artifact store mode (`thoth-mem`, `openspec`, or
+`hybrid`). Follow
+`~/.config/opencode/skills/_shared/persistence-contract.md` for read/write
+rules per mode.
+
+- `thoth-mem`: persist to thoth-mem only — do NOT create or modify
+  `openspec/` files.
+- `openspec`: write files only — do NOT call thoth-mem save tools.
+- `hybrid`: persist to both (default).
+
+## When to Use
+
+- The change has an acceptable verification report and is ready to close
+- An archive attempt must be retried after an interrupted move or merge
+
+## Prerequisites
+
+- `change-name`
+- Spec artifact
+- Design artifact
+- Tasks artifact
+- Verify report artifact
+
+## Workflow
+
+1. Read the shared conventions.
+2. Recover `spec`, `design`, `tasks`, and `verify-report` through the
+   retrieval protocol in
+   `~/.config/opencode/skills/_shared/persistence-contract.md`.
+3. Refuse to archive if the verification report still contains unresolved
+   critical failures.
+4. If the selected mode includes OpenSpec, merge every change spec from
+   `openspec/changes/{change-name}/specs/{domain}/spec.md` into
+   `openspec/specs/{domain}/spec.md`.
+5. If the selected mode includes OpenSpec, move the completed change directory
+   to `openspec/changes/archive/YYYY-MM-DD-{change-name}/`.
+6. Create an audit trail report summarizing merged domains, archive location,
+   verification lineage, and any mode-based skips.
+7. In `thoth-mem` mode, do not create or move `openspec/` artifacts; record the
+   archive result only in the audit trail.
+8. If the selected mode includes thoth-mem, persist the audit trail with:
+
+   ```text
+   thoth_mem_mem_save(
+     title: "sdd/{change-name}/archive-report",
+     topic_key: "sdd/{change-name}/archive-report",
+     type: "architecture",
+     project: "{project}",
+     scope: "project",
+     content: "{full archive report markdown}"
+   )
+   ```
+
+## Output Format
+
+Return:
+
+- `Change`
+- `Archive Path`: `openspec/changes/archive/YYYY-MM-DD-{change-name}/`
+- `Topic Key`: `sdd/{change-name}/archive-report`
+- `Merged Specs`: list of domains updated in `openspec/specs/`
+- `Audit Summary`: concise bullets
+- `Status`: archived or blocked
+
+## Rules
+
+- Archive only after verification is acceptable.
+- Merge delta specs before moving the change folder.
+- Preserve canonical spec structure and untouched requirements.
+- Persist the final audit trail through thoth-mem when the selected mode
+  includes it.
+- Use the retrieval protocol in
+  `~/.config/opencode/skills/_shared/persistence-contract.md` for every
+  dependency.
+- Never reference engram.

package/src/skills/sdd-design/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: sdd-design
+description: Create `design.md` with architecture decisions and file changes.
+---
+
+# SDD Design Skill
+
+Create the technical design that explains how the approved spec will be built.
+
+## Shared Conventions
+
+- Shared references:
+- `~/.config/opencode/skills/_shared/openspec-convention.md`
+- `~/.config/opencode/skills/_shared/persistence-contract.md`
+- `~/.config/opencode/skills/_shared/thoth-mem-convention.md`
+
+## Persistence Mode
+
+The orchestrator passes the artifact store mode (`thoth-mem`, `openspec`, or
+`hybrid`). Follow
+`~/.config/opencode/skills/_shared/persistence-contract.md` for read/write
+rules per mode.
+
+- `thoth-mem`: persist to thoth-mem only — do NOT create or modify
+  `openspec/` files.
+- `openspec`: write files only — do NOT call thoth-mem save tools.
+- `hybrid`: persist to both (default).
+
+## When to Use
+
+- Proposal and specs exist and implementation planning needs technical depth
+- A prior design needs to be revised after spec changes
+
+## Prerequisites
+
+- `change-name`
+- Proposal artifact
+- Spec artifact
+- Access to the repository code that will change
+
+## Workflow
+
+1. Read the shared conventions.
+2. Recover `sdd/{change-name}/proposal` and `sdd/{change-name}/spec` using the
+   retrieval protocol in
+   `~/.config/opencode/skills/_shared/persistence-contract.md`.
+3. If revising work, recover `sdd/{change-name}/design` with the same
+   mode-aware retrieval rules.
+4. Read the actual code paths affected by the change before deciding on an
+   approach.
+5. If the selected mode includes OpenSpec, write
+   `openspec/changes/{change-name}/design.md` using this structure. In
+   `thoth-mem` mode, produce the same content without creating the file:
+
+   ```md
+   # Design: {Change Title}
+
+   ## Technical Approach
+   ## Architecture Decisions
+   ### Decision: {Title}
+   **Choice**:
+   **Alternatives considered**:
+   **Rationale**:
+   ## Data Flow
+   ## File Changes
+   ## Interfaces / Contracts
+   ## Testing Strategy
+   ## Migration / Rollout
+   ## Open Questions
+   ```
+
+6. If the selected mode includes thoth-mem, persist the design with:
+
+   ```text
+   thoth_mem_mem_save(
+     title: "sdd/{change-name}/design",
+     topic_key: "sdd/{change-name}/design",
+     type: "architecture",
+     project: "{project}",
+     scope: "project",
+     content: "{full design markdown}"
+   )
+   ```
+
+## Output Format
+
+Return:
+
+- `Change`
+- `Artifact`: `openspec/changes/{change-name}/design.md`
+- `Topic Key`: `sdd/{change-name}/design`
+- `Key Decisions`: concise bullet list
+- `Files Planned`: created, modified, deleted paths
+- `Next Step`: `sdd-tasks`
+
+## Rules
+
+- Base the design on the actual codebase, not generic assumptions.
+- Every architecture decision must include rationale.
+- Use concrete file paths and interfaces.
+- Keep implementation details aligned with the spec and repository patterns.
+- Retrieve full dependencies with the protocol in
+  `~/.config/opencode/skills/_shared/persistence-contract.md`.
+- Never reference engram.

package/src/skills/sdd-propose/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: sdd-propose
+description: Create or update `proposal.md` for an OpenSpec change.
+---
+
+# SDD Propose Skill
+
+Create the proposal artifact for a change and persist it with thoth-mem.
+
+## Shared Conventions
+
+- Shared references:
+- `~/.config/opencode/skills/_shared/openspec-convention.md`
+- `~/.config/opencode/skills/_shared/persistence-contract.md`
+- `~/.config/opencode/skills/_shared/thoth-mem-convention.md`
+
+## Persistence Mode
+
+The orchestrator passes the artifact store mode (`thoth-mem`, `openspec`, or
+`hybrid`). Follow
+`~/.config/opencode/skills/_shared/persistence-contract.md` for read/write
+rules per mode.
+
+- `thoth-mem`: persist to thoth-mem only — do NOT create or modify
+  `openspec/` files.
+- `openspec`: write files only — do NOT call thoth-mem save tools.
+- `hybrid`: persist to both (default).
+
+## When to Use
+
+- A change needs its first `proposal.md`
+- An existing proposal must be refined after new requirements
+
+## Prerequisites
+
+- A `change-name`
+- User intent, problem statement, or prior exploration notes
+- Project name for thoth-mem persistence
+
+## Workflow
+
+1. Read the shared conventions before drafting.
+2. If the change already exists, recover the latest proposal using the
+   retrieval protocol in
+   `~/.config/opencode/skills/_shared/persistence-contract.md`.
+3. Review relevant main specs under `openspec/specs/` to avoid proposing
+   contradictions.
+4. If the selected mode includes OpenSpec, write
+   `openspec/changes/{change-name}/proposal.md` using this shape. In
+   `thoth-mem` mode, produce the same content without creating the file:
+
+   ```md
+   # Proposal: {Change Title}
+
+   ## Intent
+   ## Scope
+   ### In Scope
+   ### Out of Scope
+   ## Approach
+   ## Affected Areas
+   ## Risks
+   ## Rollback Plan
+   ## Success Criteria
+   ```
+
+5. If the selected mode includes thoth-mem, persist the full proposal with:
+
+   ```text
+   thoth_mem_mem_save(
+     title: "sdd/{change-name}/proposal",
+     topic_key: "sdd/{change-name}/proposal",
+     type: "architecture",
+     project: "{project}",
+     scope: "project",
+     content: "{full proposal markdown}"
+   )
+   ```
+
+6. In `hybrid` mode, both the filesystem artifact and thoth-mem save must
+   succeed.
+
+## Output Format
+
+Return a short report with:
+
+- `Change`: change name
+- `Artifact`: `openspec/changes/{change-name}/proposal.md`
+- `Topic Key`: `sdd/{change-name}/proposal`
+- `Summary`: 2-4 bullets covering intent, scope, and major risks
+- `Next Step`: usually `sdd-spec` or `sdd-design`
+
+## Rules
+
+- Use canonical OpenSpec filenames only.
+- Keep the proposal focused on why, scope, and success criteria.
+- Always include rollback guidance and explicit out-of-scope items.
+- Never reference engram.
+- Never rely on a `thoth_mem_mem_search` preview without calling
+  `thoth_mem_mem_get_observation` when the selected mode uses thoth-mem.