thoth-agents 0.1.0

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

@@ -0,0 +1,87 @@
+---
+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/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
+
+- 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`
+- `pipeline-type` (`accelerated` or `full`)
+- Tasks artifact
+- Verify report artifact
+- Spec artifact (full pipeline only)
+- Design artifact (full pipeline only)
+- Proposal artifact (always — used for audit trail)
+
+## Workflow
+
+1. Read the shared conventions.
+2. Recover artifacts through the retrieval protocol in
+   the persistence contract:
+   - **Always**: recover `proposal`, `tasks`, and `verify-report`
+   - **Full pipeline only**: recover `spec` and `design`
+3. Refuse to archive if the verification report still contains unresolved
+   critical failures.
+4. If the selected mode includes OpenSpec and the pipeline is full, merge
+   every change spec from
+   `openspec/changes/{change-name}/specs/{domain}/spec.md` into
+   `openspec/specs/{domain}/spec.md`. In accelerated pipeline, skip the
+   spec merge (no delta specs exist).
+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:
+
+   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`.
+
+## 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.
+- In full pipeline, merge delta specs before moving the change folder.
+  In accelerated pipeline, skip the spec merge (no delta specs exist).
+- 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 the persistence contract for every dependency.

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

@@ -0,0 +1,92 @@
+---
+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/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
+
+- 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
+   the persistence contract.
+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:
+
+   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`.
+
+## 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 the persistence contract.

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

@@ -0,0 +1,148 @@
+---
+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/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 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
+   Use the memory tool binding for `mem_save` with the canonical topic key and
+   required metadata fields: `title`, `topic_key`, `type`, `project`,
+   `scope`, and `content`.
+
+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

@@ -0,0 +1,89 @@
+---
+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/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 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 from the persistence contract.
+3. Review relevant main specs under the active OpenSpec path 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:
+
+   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. 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`: `sdd-spec` (full pipeline) or `sdd-tasks` (accelerated pipeline)
+
+## 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 compact 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

@@ -0,0 +1,93 @@
+---
+name: sdd-spec
+description: Write OpenSpec delta specs with RFC 2119 language and GWT scenarios.
+---
+
+# SDD Spec Skill
+
+Write or update the change specifications for one or more affected domains.
+
+## 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 proposal is approved and must be converted into testable requirements
+- Existing change specs need to be expanded or corrected
+
+## Prerequisites
+
+- `change-name`
+- The proposal artifact must exist
+- Access to any current main specs for impacted domains
+
+## Workflow
+
+1. Read the shared conventions.
+2. Recover the proposal using the retrieval protocol in
+   the persistence contract.
+3. If the change already has spec work, recover `sdd/{change-name}/spec` with
+   the same mode-aware retrieval rules before editing.
+4. Read `openspec/specs/{domain}/spec.md` for each affected domain to determine
+   whether you are writing a delta spec or a brand-new spec.
+5. If the selected mode includes OpenSpec, write canonical change artifacts
+   under `openspec/changes/{change-name}/specs/{domain}/spec.md`. In
+   `thoth-mem` mode, produce the same canonical content without creating files.
+6. Use this structure in every spec file:
+
+   ```md
+   # Delta for {Domain}
+
+   ## ADDED Requirements
+   ### Requirement: {Name}
+   The system MUST ...
+
+   #### Scenario: {Name}
+   - GIVEN ...
+   - WHEN ...
+   - THEN ...
+
+   ## MODIFIED Requirements
+   ## REMOVED Requirements
+   ```
+
+   For a brand-new domain, write a full spec instead of a delta.
+
+7. If the selected mode includes thoth-mem, persist the complete spec payload
+   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`.
+
+## Output Format
+
+Return:
+
+- `Change`
+- `Artifacts`: list of domain spec paths written
+- `Topic Key`: `sdd/{change-name}/spec`
+- `Coverage Summary`: requirements and scenarios added or modified
+- `Next Step`: usually `sdd-design`
+
+## Rules
+
+- Every requirement must use RFC 2119 keywords.
+- Every requirement must have at least one Given/When/Then scenario.
+- Specs describe behavior, not implementation details.
+- Keep domain boundaries explicit.
+- Use the retrieval protocol from the persistence contract for every SDD
+  dependency.

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

@@ -0,0 +1,142 @@
+---
+name: sdd-tasks
+description: Generate phased `tasks.md` checklists from specs and design.
+---
+
+# SDD Tasks Skill
+
+Translate the approved spec and design into an implementation checklist.
+
+## 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
+
+- **Full pipeline**: proposal, spec, and design are ready for execution planning
+- **Accelerated pipeline**: proposal is ready and spec/design are intentionally skipped
+- A task plan must be refreshed after scope changes
+
+## Prerequisites
+
+- `change-name`
+- `pipeline-type` (`accelerated` or `full`)
+- Proposal artifact
+- Spec artifact (full pipeline only)
+- Design artifact (full pipeline only)
+
+## Workflow
+
+1. Read the shared conventions.
+2. Recover artifacts via the retrieval protocol in
+   the persistence contract:
+   - **Always**: recover `proposal`
+   - **Full pipeline only**: recover `spec` and `design`
+   - In accelerated pipeline, derive task structure directly from the proposal.
+3. If a task plan already exists, recover `sdd/{change-name}/tasks` with the
+   same mode-aware retrieval rules before rewriting it.
+4. **Validate existing-file references**: For every task that modifies an existing file (not creates a new one), verify the file actually exists on disk before including it in the task list. If a referenced "existing" file is not found, flag it as a design defect in an `> ⚠️ Warning` block at the top of the tasks artifact, and omit the task or add a note.
+5. **Codebase discovery (required when design artifact is absent or lacks file paths)**:
+   Before generating tasks, actively explore the repository to gather the concrete data needed for accurate Verification blocks:
+    1. Read the project's build manifest or task runner config (e.g., `package.json`, `Makefile`, `Cargo.toml`, `.csproj`, `pyproject.toml`) to discover available commands for testing, building, linting, and type-checking. Use the exact commands the project defines in `Run:` fields — never invent commands that don't exist in the project.
+   2. Explore the directory structure of affected areas to confirm actual file paths and module layout.
+   3. Check for existing test files (e.g., `*.test.ts`, `*.spec.ts`) to reference in Verification commands.
+   4. Use the proposal's "Affected Areas" and "Approach" as navigation hints, not as authoritative file paths.
+
+   This exploration is mandatory in accelerated pipeline. In full pipeline, prefer paths from the design artifact's `File Changes` section but still validate commands from `package.json`.
+6. Build a phased checklist for `openspec/changes/{change-name}/tasks.md`. In
+   `thoth-mem` mode, produce the same canonical checklist content without
+   creating the file.
+5. Use hierarchical numbering and Markdown checkboxes with per-task verification:
+
+    ```md
+    # Tasks: {Change Title}
+
+    ## Phase 1: Foundation
+    - [ ] 1.1 Set up project structure — `src/config/`
+      **Verification**:
+      - Run: `pnpm run typecheck`
+      - Expected: No TypeScript errors in config files
+
+    ## Phase 2: Core Implementation
+    - [ ] 2.1 Implement core logic — `src/core/handler.ts`
+      **Verification**:
+      - Run: `pnpm test -- -t "core handler"`
+      - Expected: All handler tests pass
+
+    ## Phase 3: Integration
+    - [ ] 3.1 Integrate with API — `src/api/client.ts`
+      **Verification**:
+      - Run: `pnpm run lint src/api/`
+      - Expected: No linting errors in API module
+
+     ## Phase 4: Integration & Release
+     - [ ] 4.1 Run full integration test suite and validate release artifacts — all modules
+       **Verification**:
+       - Run: `pnpm test`
+       - Expected: All tests pass with 100% coverage
+    ```
+
+    Recognized task states:
+
+     - `- [ ]` pending
+     - `- [~]` in progress
+     - `- [x]` completed
+     - `- [-]` skipped — always append a reason: `- [-] 1.2 Task name — skipped: reason here`
+
+7. Reference concrete file paths and specific spec scenarios in the tasks.
+8. If the selected mode includes thoth-mem, persist the full checklist 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`.
+
+9. After `tasks.md` is generated, the workflow proceeds to an optional oracle
+   plan review via the `plan-reviewer` skill. This is managed outside the scope
+   of this skill.
+10. The artifact governance validator may run **after** `sdd-tasks` as a
+    report-only handoff. It captures placement guidance for the future
+    pre-`sdd-apply` entrypoint, but it does not enforce execution or overlap
+    with plan review.
+11. The orchestrator handles the `[OKAY]` / `[REJECT]` review loop and any
+     necessary fixes before proceeding to execution.
+
+## Output Format
+
+Return:
+
+- `Change`
+- `Artifact`: `openspec/changes/{change-name}/tasks.md`
+- `Topic Key`: `sdd/{change-name}/tasks`
+- `Phase Summary`: task counts per phase
+- `Execution Order`: one short paragraph
+- `Next Step`: `sdd-apply`
+
+## Rules
+
+- Tasks must be small, actionable, and verifiable.
+- Order tasks by dependency.
+- Include testing and verification work explicitly.
+- Do not create vague tasks such as "implement feature".
+- The governance validator is advisory only at this stage; it documents
+  handoff placement and report findings, but it does not block task generation
+  or replace execution planning.
+- **Every task MUST include a `Verification` sub-block** with:
+  - `Run:` — the exact command(s) to verify this task (e.g., `pnpm test`, `pnpm run typecheck`, `pnpm run lint`)
+  - `Expected:` — the specific observable outcome that confirms success
+  - Tasks without a `Verification` block will be rejected by the plan-reviewer.
+  - Do NOT group verification into a single "Phase 4: Verification" — each task gets its own.
+- Retrieve all dependencies through the mode-aware protocol in the persistence
+  contract.