oh-my-opencode-lite 0.1.0 → 0.1.2

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

@@ -17,7 +17,7 @@ task progress durable, ordered, and verifiable.
 - `~/.config/opencode/skills/_shared/persistence-contract.md`
 - `~/.config/opencode/skills/_shared/thoth-mem-convention.md`
 
-## Ownership Model
+## Progress Tracking Invariants
 
 The orchestrator owns task progress tracking.
 
@@ -26,12 +26,23 @@ The orchestrator owns task progress tracking.
   received and verified.
 - The orchestrator marks `- [-]` with a clear reason when a task is skipped or
   fails after escalation.
+- Sub-agents execute assigned work and return structured results. They do not
+  own checkbox updates.
+- Never batch-update multiple checkboxes at once.
+- Never proceed without updating the current task state first.
+- Re-read the canonical tasks artifact after each edit to confirm persistence.
+- Persistence mode determines target stores: `openspec` → file only,
+  `thoth-mem` → memory only, `hybrid` → both. Never skip a store that the
+  active mode requires.
 - `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.
+  management only when the active mode includes openspec artifacts.
+- Task state updates are NOT optional and NOT deferred — they happen in
+  real-time as execution proceeds.
+- Every state transition (pending→in-progress, in-progress→completed,
+  in-progress→skipped) MUST be persisted BEFORE moving on.
+- Real-time tracking is a hard invariant, not a best practice. Deferred or
+  batched updates are a protocol violation.
 
 ## When to Use
 
@@ -43,16 +54,19 @@ checkbox updates.
 
 ### 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,
+1. Determine the artifact store mode from config before reading or writing any
+   SDD artifacts.
+2. Load task artifacts using mode-aware retrieval:
+   - `openspec`/`hybrid`: scan `openspec/changes/` for active changes and read
+     `tasks.md`.
+   - `thoth-mem`: recover tasks via 3-layer recall
+     (`search` → `timeline` → `get_observation`) using topic key
+     `sdd/{change-name}/tasks`.
+3. Find the first unchecked task in state `- [ ]` or `- [~]`.
+4. 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
+5. Load remaining SDD context using mode-aware retrieval 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
 
@@ -185,20 +199,15 @@ Treat missing sections or vague summaries as incomplete execution results.
 
 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.
+1. Determine the artifact store mode from config.
+2. Recover task state using mode-aware retrieval:
+   - `openspec`: read `openspec/changes/{change-name}/tasks.md`.
+   - `thoth-mem`: recover `sdd/{change-name}/tasks` and
+     `sdd/{change-name}/apply-progress` via 3-layer recall
+     (`search` → `timeline` → `get_observation`).
+   - `hybrid`: do both recovery paths and prefer thoth-mem as the source of
+     truth if state diverges.
+3. Resume from the first task marked `- [ ]` or `- [~]`.
 
 ## Guardrails
 

package/src/skills/requirements-interview/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: requirements-interview
+description: >
+  Mandatory step-0 requirements discovery for non-trivial work before any
+  implementation or SDD routing decisions.
+metadata:
+  author: oh-my-opencode-lite
+  version: '1.0'
+---
+
+# Requirements Interview Skill
+
+Use this skill as the mandatory step-0 entry point for non-trivial requests.
+The goal is requirement clarity, scope calibration, and a user-approved
+handoff path before implementation begins.
+
+## Shared Conventions
+
+- `~/.config/opencode/skills/_shared/openspec-convention.md`
+- `~/.config/opencode/skills/_shared/persistence-contract.md`
+- `~/.config/opencode/skills/_shared/thoth-mem-convention.md`
+
+## HARD GATE
+
+- Do not implement during the requirements interview.
+- Do not write code.
+- Do not patch files.
+- Do not create formal SDD artifacts until the user approves the route.
+
+## Question Tool Requirement
+
+- The interview flow MUST use the built-in `question` tool for user-input
+  prompts.
+- Do not embed interview questions as plain prose in normal response text.
+- Prefer one focused question-tool call at a time for the core interview loop.
+- Use short headers (<=30 chars), concise option labels, and concrete
+  descriptions.
+- Put the recommended option first and include `(Recommended)` in that label.
+- Do not add an `Other` option manually; rely on `custom: true` unless custom
+  input must be disabled.
+- Use `multiple: true` only when multiple simultaneous selections are genuinely
+  valid.
+
+## Workflow
+
+### Phase 1: Discovery Context Gathering
+
+1. Always dispatch `@explorer` for codebase context. Dispatch `@librarian`
+   only when the request involves external APIs, dependency versions, library
+   migration, or public documentation.
+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: Requirements Interview
+
+1. Ask each interview question through the `question` tool.
+2. Ask 1 question-tool call at a time.
+3. Ask at most 5 total questions.
+4. Prefer multiple-choice questions when practical.
+5. Stop early when clarity is already sufficient.
+6. Focus on what the user truly needs, not only the first phrasing of the
+   request.
+7. Surface unstated assumptions and validate them with the user.
+8. Guide the user toward potentially better options when appropriate, but never
+   impose a decision.
+9. Always ask and confirm; never choose on the user's behalf.
+10. Do not ask for details that the codebase, task artifacts, or gathered
+   context already answer.
+
+### Phase 3: Complexity Assessment
+
+Evaluate these 6 dimensions. Rate each as **Low**, **Medium**, or **High**:
+
+| Dimension | Low | Medium | High |
+| --- | --- | --- | --- |
+| **Logic depth** | Copy, CSS, rename, simple wiring | Localized behavior tweak, validation, one workflow step | Algorithm, state-machine, or business-rule rewrite with many invariants |
+| **Contract sensitivity** | Presentation only, internal refactor | User-visible behavior change in one flow | API, schema, data model, migration, auth, privacy, or public contract |
+| **Context span** | Can be done in one bounded pass | Several dependent edits or choices to coordinate | Many sequential steps where earlier decisions must be remembered |
+| **Discovery need** | Request and acceptance criteria are already clear | Some ambiguity, a few viable approaches | Goal is clear but solution requires investigation or tradeoff analysis |
+| **Failure cost** | Mistakes are obvious and cheap to revert | Needs integration or regression checks | Subtle correctness bugs, customer-facing, data, or compliance impact |
+| **Concern coupling** | Single concern | Two related concerns | Multiple independent concerns that could conflict |
+
+### Phase 4: Approach Proposal
+
+1. Present 2-3 viable options as recommendations, not decisions.
+2. For each option, give the main trade-offs and when it is a good fit.
+3. Mark one option as the current recommendation and explain why.
+4. Use the `question` tool to confirm the preferred approach before moving on.
+
+### Phase 5: User Approval Gate
+
+Present:
+
+- Summary of understanding
+- Scope classification and why
+- Recommended approach options
+- Proposed handoff path
+
+Then wait for explicit user confirmation.
+
+Use the `question` tool for this approval gate.
+
+Nothing proceeds without explicit approval in this phase. The user is the sole
+approver during requirements discovery. Do not request oracle review here.
+
+### Phase 6: Handoff
+
+Recommend a route based on the complexity assessment, then wait for the
+user to confirm it:
+
+**Direct implementation** — when all of:
+- No dimensions rated High
+- At most one dimension rated Medium
+- Contract sensitivity is Low
+- Failure cost is Low
+
+**Accelerated SDD** (`propose -> tasks`) — when:
+- 2-3 dimensions are Medium, or
+- 1 dimension is High in logic depth, context span, or discovery need
+- But contract sensitivity and failure cost are not High
+
+**Full SDD** (`propose -> spec -> design -> tasks`) — when any of:
+- Contract sensitivity is High
+- Failure cost is High
+- 2 or more dimensions are High
+- Discovery need is High and at least one other dimension is
+  Medium or High
+- Concern coupling is High with risk of conflicting decisions
+
+Quick decision heuristics:
+
+1. Cosmetic work routes direct regardless of file count.
+2. Dense logic rewrites route to at least accelerated SDD regardless
+   of file count.
+3. External contracts (API, schema, migration, auth, privacy) usually
+   need full SDD.
+4. If the model must remember decisions across many steps, write them
+   down — that means SDD.
+5. Tie-breaker: unsure between direct and accelerated, choose
+   accelerated. Unsure between accelerated and full, ask: 'Do we
+   need a durable behavior contract?' If yes, full SDD.
+
+Before any SDD generation starts, present the artifact store policy choice:
+
+```text
+How would you like to persist planning artifacts?
+1. none — No persistence. Ephemeral exploration, privacy-sensitive work, or when no backend is available. Results are inline only and not saved across sessions.
+2. thoth-mem — Memory only. Lightest token cost. No repo files.
+3. openspec — Repo files only. Visible and reviewable.
+4. hybrid — Both. Maximum durability, higher token cost.
+Default: hybrid
+```
+
+Collect this choice with the `question` tool rather than plain prose.
+
+When the user selects a mode that includes OpenSpec (`openspec` or `hybrid`),
+verify that `openspec/` is initialized. If it is not, recommend running
+`sdd-init` before proceeding:
+`~/.config/opencode/skills/sdd-init/SKILL.md`
+
+Once route, persistence mode, and initialization are confirmed, hand off to the
+corresponding SDD pipeline phase:
+
+- **Propose**: `~/.config/opencode/skills/sdd-propose/SKILL.md`
+- **Spec** (full SDD only): `~/.config/opencode/skills/sdd-spec/SKILL.md`
+- **Design** (full SDD only): `~/.config/opencode/skills/sdd-design/SKILL.md`
+- **Tasks**: `~/.config/opencode/skills/sdd-tasks/SKILL.md`
+
+Do not silently choose the handoff route or artifact store mode. Recommend,
+ask, and wait.
+
+## Guardrails
+
+- Maximum 5 interview questions.
+- Ask only one question-tool call at a time.
+- Do not ask what codebase context can answer.
+- Do not skip explicit user approval.
+- Do not auto-select the handoff route.
+- Do not auto-select the persistence mode.
+- Never convert recommendations into unilateral decisions.
+- Do not replace question-tool prompts with plain-text interview questions.
+
+## Anti-Patterns
+
+- Question dumping
+- Option inflation
+- Premature implementation
+- Silent route selection
+- Silent persistence-mode selection
+- Treating discovery as optional

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

@@ -65,29 +65,20 @@ rules per mode.
 
 ## Response Format
 
-Return a structured result to the orchestrator:
+Return a structured result to the orchestrator using the Task Result envelope:
 
 **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}
+
+**What was done**: concrete list of changes
+**Files changed**: paths with descriptions
+**Verification**: check results (passed/failed)
+**Issues**: problems encountered with severity
+**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.
@@ -97,5 +88,4 @@ Return:
 - 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.
+  state correctly.

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

@@ -91,4 +91,3 @@ Return:
 - 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

@@ -101,4 +101,3 @@ Return:
 - 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-init/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: sdd-init
+description: Bootstrap OpenSpec structure and SDD context for a project.
+metadata:
+  author: gentleman-programming
+  version: "1.0"
+---
+
+# SDD Init Skill
+
+Initialize SDD for a project by detecting local conventions, creating the
+minimal OpenSpec structure when needed, and persisting startup context.
+
+## 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 initialization context to thoth-mem only — do NOT create
+  or modify `openspec/` files.
+- `openspec`: create or update OpenSpec structure only — do NOT call thoth-mem
+  save tools.
+- `hybrid`: do both (default).
+
+## When to Use
+
+- SDD is needed but `openspec/` is not initialized
+- A new project needs initial OpenSpec conventions
+- The team wants detected stack/context captured before `sdd-propose`
+
+## Prerequisites
+
+- Project root path
+- Project name
+- Selected persistence mode (default: `hybrid`)
+
+## Workflow
+
+1. Read the shared conventions before initializing.
+2. Detect project stack and conventions from repository files:
+   - Stack indicators: `package.json`, `go.mod`, `pyproject.toml`,
+     `requirements.txt`, `Cargo.toml`, `pom.xml`, `build.gradle`,
+     `composer.json`.
+   - Testing indicators: `vitest.config.*`, `jest.config.*`,
+     `playwright.config.*`, `pytest.ini`, `tox.ini`, `go test` conventions,
+     `Cargo.toml` test crates.
+   - Style indicators: `biome.json`, `.eslintrc*`, `eslint.config.*`,
+     `.prettierrc*`, `ruff.toml`, `.golangci.*`, `rustfmt.toml`.
+   - CI indicators: `.github/workflows/*`, `.gitlab-ci.yml`,
+     `azure-pipelines.yml`, `.circleci/config.yml`.
+   - Architecture hints: common layout markers such as `apps/`, `packages/`,
+     `services/`, `src/`, `cmd/`, `internal/`.
+3. Build concise config context (max 10 lines) using detected values. Use
+   `unknown` for missing signals.
+4. If the selected mode includes OpenSpec (`openspec` or `hybrid`), check
+   whether these already exist:
+   - `openspec/config.yaml`
+   - `openspec/specs/`
+   - `openspec/changes/`
+5. If all required OpenSpec paths already exist, report what exists and ask the
+   orchestrator whether `config.yaml` should be updated. Do not overwrite by
+   default.
+6. If any required OpenSpec path is missing and mode includes OpenSpec, create
+   only the minimum structure:
+
+   ```text
+   openspec/
+   ├── config.yaml
+   ├── specs/
+   └── changes/
+       └── archive/
+   ```
+
+7. Generate `openspec/config.yaml` dynamically with this shape:
+
+   ```yaml
+   schema: spec-driven
+
+   context: |
+     Tech stack: {detected}
+     Architecture: {detected}
+     Testing: {detected}
+     Style: {detected}
+
+   rules:
+     proposal:
+       - Include rollback plan for risky changes
+       - Identify affected modules/packages
+     specs:
+       - Use Given/When/Then format for scenarios
+       - Use RFC 2119 keywords (MUST, SHALL, SHOULD, MAY)
+     design:
+       - Include sequence diagrams for complex flows
+       - Document architecture decisions with rationale
+     tasks:
+       - Group tasks by phase (infrastructure, implementation, testing)
+       - Use hierarchical numbering (1.1, 1.2, etc.)
+       - Keep tasks small enough to complete in one session
+     apply:
+       - Follow existing code patterns and conventions
+       tdd: false
+       test_command: ''
+     verify:
+       test_command: ''
+       build_command: ''
+       coverage_threshold: 0
+     archive:
+       - Warn before merging destructive deltas
+   ```
+
+8. Never create placeholder SDD artifacts (`proposal.md`, `design.md`,
+   `tasks.md`, or spec files) during initialization.
+9. If the selected mode includes thoth-mem (`thoth-mem` or `hybrid`), persist
+   the detected context and initialization status with:
+
+   ```text
+   thoth_mem_mem_save(
+     title: "sdd-init/{project-name}",
+     topic_key: "sdd-init/{project-name}",
+     type: "config",
+     project: "{project-name}",
+     scope: "project",
+     content: "What: ...\nWhy: ...\nWhere: ...\nLearned: ..."
+   )
+   ```
+
+10. In `hybrid` mode, initialization is complete only when both OpenSpec setup
+    and thoth-mem persistence succeed.
+
+## Output Format
+
+Return:
+
+- `Project`
+- `Mode`
+- `Detected Context`: stack, architecture, testing, style, CI
+- `OpenSpec Status`: initialized, already initialized, or skipped by mode
+- `Created Paths`: list of directories/files created (if any)
+- `Topic Key`: `sdd-init/{project-name}` when mode includes thoth-mem
+- `Next Step`: usually `sdd-propose`
+
+## Rules
+
+- Be idempotent: if OpenSpec already exists, report and ask before updates.
+- In `thoth-mem` mode, never create `openspec/` directories or files.
+- Keep `config.yaml` context concise (max 10 lines).
+- Detect and include CI, test, and style conventions in the context summary.
+- Never create placeholder spec/change files during init.

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

@@ -95,5 +95,6 @@ Return a short report with:
 - 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.
+- Never rely on `thoth_mem_mem_search` output alone when the mode uses
+  thoth-mem. Follow the 3-layer recall protocol: `search(mode: "compact")` →
+  `timeline` → `get_observation` to retrieve the full artifact body.

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

@@ -101,5 +101,4 @@ Return:
 - Keep domain boundaries explicit.
 - Use the retrieval protocol from
   `~/.config/opencode/skills/_shared/persistence-contract.md` for every SDD
-  dependency.
-- Never reference engram.
+  dependency.

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

@@ -113,4 +113,3 @@ Return:
 - Do not create vague tasks such as “implement feature”.
 - Retrieve all dependencies through the mode-aware protocol in
   `~/.config/opencode/skills/_shared/persistence-contract.md`.
-- Never reference engram.

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

@@ -99,4 +99,3 @@ Return:
 - Do not fix issues inside this phase; report them.
 - Recover full artifacts with the protocol in
   `~/.config/opencode/skills/_shared/persistence-contract.md`.
-- Never reference engram.

package/src/skills/brainstorming/SKILL.md

@@ -1,120 +0,0 @@
----
-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