thoth-agents 0.1.0

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

@@ -0,0 +1,245 @@
+---
+name: executing-plans
+description: Execute SDD task lists with real-time progress tracking, sub-agent dispatch, and verification checkpoints.
+metadata:
+  author: thoth-agents
+  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
+
+- [../_shared/openspec-convention.md](../_shared/openspec-convention.md)
+- [../_shared/persistence-contract.md](../_shared/persistence-contract.md)
+- [../_shared/thoth-mem-convention.md](../_shared/thoth-mem-convention.md)
+
+## Progress Tracking Invariants
+
+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.
+- Sub-agents execute assigned work and return structured results. They do not
+  own checkbox updates.
+- Same-agent execution batches are allowed when consecutive ready tasks share
+  dependencies, scope, and verification context.
+- For a same-agent batch, keep checkbox state per task: mark each batched task
+  `- [~]` before dispatch, and later mark each task `- [x]` or `- [-]` only
+  from task-specific evidence in the returned result.
+- 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.
+- The artifact governance validator is outside this skill's responsibility.
+  If present, it is a report-only checkpoint after `sdd-tasks` and before a
+  future `sdd-apply` entrypoint; it does not change checkbox state or task
+  ownership.
+- `openspec/` files are coordination artifacts, not source code. The
+  orchestrator may read and edit them directly for progress tracking and state
+  management only when the active mode includes openspec artifacts.
+- Keep visible task state on the active progress tracking surface while
+  preserving the canonical task artifact. Use the visible progress surface
+  when available, plus the same canonical `tasks.md` and/or thoth-mem 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 updates
+  are a protocol violation, and batch dispatches must still record each task's
+  state transition before and after the delegated work.
+
+## 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. 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.
+5. Load remaining SDD context using mode-aware retrieval in
+   [../_shared/persistence-contract.md](../_shared/persistence-contract.md).
+
+### Phase 2: Execute Ready Work
+
+#### A. Mark In-Progress
+
+Before dispatching a task or same-agent batch:
+
+1. Select the next ready task, or the next consecutive ready tasks that target
+   the same execution agent and can safely be handled in one dispatch.
+2. Edit the canonical tasks artifact and change each selected task from
+   `- [ ]` to `- [~]`.
+3. If the mode is `thoth-mem` or `hybrid`, re-persist the updated tasks
+   artifact with topic key `sdd/{change-name}/tasks`.
+4. Re-read `tasks.md` after the edit to confirm the change persisted.
+
+#### B. Dispatch
+
+Choose the semantic execution role based on task type. Preserve the role
+boundary even when the active harness uses different invocation syntax:
+
+| Need | Semantic role |
+| --- | --- |
+| 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 |
+
+Prefer one dispatch for consecutive ready tasks assigned to the same execution
+role, especially repeated UI/UX work for designer, repeated narrow edits for
+quick, or related implementation tasks for deep.
+
+Every dispatch prompt MUST include these 6 parts:
+
+1. `TASKS` — exact task number(s) and title(s)
+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 every task's 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 each verified task from
+   `- [~]` to `- [x]`. If a batched result only completed some tasks, update
+   only those tasks and keep the rest in progress, skipped, or retryable based
+   on evidence.
+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 or batch has failed 3 consecutive times
+
+### Phase 3: Between Tasks
+
+Between every task or same-agent batch:
+
+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 final verification using the project's configured instructions and the
+   smallest sufficient checks: typecheck, tests, lint, and build when
+   appropriate.
+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
+**Tasks**: {task number(s) and name(s)}
+
+### What was done
+- {concrete change 1}
+- {concrete change 2}
+
+### Per-task outcome
+- `{task number}` — completed | failed | partial: {task-specific evidence}
+
+### 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. 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
+
+- 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,115 @@
+---
+name: plan-reviewer
+description: Review SDD task plans for execution blockers and return [OKAY] or [REJECT].
+metadata:
+  author: thoth-agents
+  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
+
+- [../_shared/openspec-convention.md](../_shared/openspec-convention.md)
+- [../_shared/persistence-contract.md](../_shared/persistence-contract.md)
+- [../_shared/thoth-mem-convention.md](../_shared/thoth-mem-convention.md)
+
+## Purpose
+
+Review the tasks artifact for true execution blockers. Retrieve it according to
+the persistence mode: read `openspec/changes/{change-name}/tasks.md` for
+openspec/hybrid modes, use thoth-mem 3-layer recall for thoth-mem/hybrid modes,
+or read from inline context for none mode.
+
+The artifact governance validator is not part of this review. Plan-reviewer is
+only the pre-execution approval gate for the task plan; it does not run the
+validator, enforce its findings, or manage the future pre-`sdd-apply` handoff.
+Invoke the semantic oracle role through the available role dispatch surface.
+
+Focus on whether the plan can be executed as written, not whether you would have
+designed it differently.
+
+## Inputs
+
+- `change-name`
+- `pipeline-type` (`accelerated` or `full`)
+- `persistence-mode` (`thoth-mem`, `openspec`, `hybrid`, or `none`)
+- Tasks artifact (retrieved per persistence mode: filesystem for openspec/hybrid,
+  thoth-mem for thoth-mem/hybrid, inline for none)
+- **Full pipeline**: related spec and design artifacts when needed for dependency checks
+- **Accelerated pipeline**: proposal artifact 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.
+- Preserve the exact `[OKAY]` and `[REJECT]` tokens across every runtime; they
+  are portable review semantics, not runtime-specific syntax.
+
+## 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/requirements-interview/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: requirements-interview
+description: Mandatory step-0 requirements discovery for non-trivial work before any implementation or SDD routing decisions.
+metadata:
+  author: thoth-agents
+  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
+
+- [../_shared/openspec-convention.md](../_shared/openspec-convention.md)
+- [../_shared/persistence-contract.md](../_shared/persistence-contract.md)
+- [../_shared/thoth-mem-convention.md](../_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.
+
+## Root Session Bootstrap
+
+This skill is normally loaded by the root/main orchestrator at the start of a
+new root session. When thoth-mem tools are available, the root/main
+orchestrator MUST also load `thoth-mem-agents`, call `mem_session_start` with
+the active project and session identity, and save the real user prompt with
+`mem_save_prompt` before later delegation.
+
+If thoth-mem tools or the required identity values are unavailable, disclose
+that memory bootstrap could not run and continue without claiming memory was
+saved. Do not save subagent prompts, generated handoffs, or interview
+scaffolding as user prompts.
+
+## Blocking User Input Surface Requirement
+
+- The interview flow MUST use the active harness blocking user input surface
+  for user-input prompts.
+- Do not embed interview questions as plain prose in normal response text when
+  a blocking user input surface exists.
+- Prefer one focused blocking input 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 when the active harness already adds or
+  supports custom input. Use the equivalent runtime option unless custom input
+  must be disabled.
+- Use multi-select only when multiple simultaneous selections are genuinely
+  valid. Use the equivalent runtime option if one exists.
+
+## Workflow
+
+### Phase 1: Discovery Context Gathering
+
+1. Always use the semantic explorer role for codebase context. Use the
+   semantic librarian role for 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 blocking user input surface.
+2. Ask 1 blocking input 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 active harness blocking user input surface 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 active harness blocking user input surface 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 active blocking user input surface 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 the
+`sdd-init` skill before proceeding.
+
+Once route, persistence mode, and initialization are confirmed, hand off to the
+corresponding SDD pipeline phase. The handoff MUST include:
+- `pipeline-type`: `accelerated` or `full` (matching the confirmed route)
+- `persistence-mode`: the user's chosen artifact store mode
+- `change-name`: derived from the approved scope
+
+Hand off to:
+
+- **Propose**: [../sdd-propose/SKILL.md](../sdd-propose/SKILL.md)
+- **Spec** (full SDD only): [../sdd-spec/SKILL.md](../sdd-spec/SKILL.md)
+- **Design** (full SDD only): [../sdd-design/SKILL.md](../sdd-design/SKILL.md)
+- **Tasks**: [../sdd-tasks/SKILL.md](../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 blocking input 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 blocking input prompts with plain-text interview questions
+  when the harness exposes a blocking user input surface.
+
+## 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

@@ -0,0 +1,89 @@
+---
+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/openspec-convention.md](../_shared/openspec-convention.md)
+- [../_shared/persistence-contract.md](../_shared/persistence-contract.md)
+- [../_shared/thoth-mem-convention.md](../_shared/thoth-mem-convention.md)
+
+## Persistence Mode
+
+The orchestrator passes the artifact store mode (`thoth-mem`, `openspec`, or
+`hybrid`). Follow the persistence contract 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`
+- `pipeline-type` (`accelerated` or `full`)
+- Assigned task numbers or phase range
+- Task artifact
+- Spec and design artifacts (full pipeline only)
+- Proposal artifact (accelerated pipeline — used as the acceptance reference)
+
+## Workflow
+
+1. Read the shared conventions.
+2. Recover artifacts with the retrieval protocol in
+   the persistence contract:
+   - **Always**: recover `tasks`
+   - **Full pipeline**: recover `spec` and `design`
+   - **Accelerated pipeline**: recover `proposal` (used as the acceptance reference)
+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:
+
+   Use the memory tool binding for `mem_save` with the canonical SDD topic key
+   and required metadata fields: `title`, `topic_key`, `type`, `project`,
+   `scope`, and `content`.
+
+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 using the Task Result envelope:
+
+**Status**: completed | failed | partial
+**Task**: {task reference}
+
+**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 harness-bound progress workflow in the `executing-plans` skill. Do not
+update task checkboxes yourself.
+
+## Rules
+
+- Read the acceptance contract before implementing: specs in full pipeline,
+  proposal in accelerated pipeline.
+- 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 the
+  persistence contract.
+- Return structured execution evidence to the orchestrator so it can manage task
+  state correctly.