thoth-agents 0.2.11 → 0.3.0

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

@@ -1,232 +0,0 @@
----
-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. **Reuse settled evidence before validating**: Reuse settled proposal, design, exploration, and handoff evidence first. Treat accepted scope, success
-   criteria, recorded assumptions, and surfaced `handoffHints` as preservation
-   constraints. Do not repeat broad discovery merely because the accelerated
-   pipeline has no design artifact or because an available artifact omits a
-   path.
-5. **Run bounded validation**: Validate only the accepted affected areas, the
-   authoritative command source, task-referenced existing files, and neighboring relevant tests needed to make the plan executable.
-   - Identify the authoritative command source from project instructions and
-     existing conventions (for example `package.json`, `Makefile`, `Cargo.toml`,
-     `.csproj`, or `pyproject.toml`). Use only commands confirmed there in
-     `Run:` fields; never invent commands or imply that an unchecked command
-     exists.
-   - For every task that modifies an existing file, verify that path within the
-     accepted affected areas. Check neighboring relevant tests only where they
-     support a planned task or its Verification block. Never present an unverified path, command, or test reference as confirmed.
-   - Do not expand this pass into repository-wide discovery. If a required
-     reference remains unresolved, defer or omit the dependent task, add a
-     bounded discovery or coordination task when appropriate, and record the
-     unresolved reference once under `## Validation Gaps`.
-   - Emit one entry per unresolved reference using this exact structure:
-
-     ```md
-     ## Validation Gaps
-
-     | Target | Checks performed | Impact / task disposition | Next action |
-     | --- | --- | --- | --- |
-     | {unverified path, command, or test} | {bounded checks completed} | {blocked, deferred, omitted, or follow-up task} | {specific discovery, owner, or decision needed} |
-     ```
-
-   - Escalate a gap that prevents an executable plan. If the accumulated gaps or
-     cross-area validation exceed bounded mechanical planning, recommend
-     escalation or complexity-based routing; do not use role changes as generic
-     failure recovery.
-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.
-7. 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/`
-      **[USN-1]** | Priority: P1
-      **Spec:** `config-domain/Project Structure`
-      **Independent Test:** Inspect `src/config/` exists and typechecks in isolation.
-      **Verification**:
-      - Run: `pnpm run typecheck`
-      - Expected: No TypeScript errors in config files
-
-    ## Phase 2: Core Implementation
-    - [ ] 2.1 Author core-logic tests — `src/core/handler.test.ts`
-      **[USN-2]** | Priority: P1
-      **Spec:** `core-domain/Core Logic`
-      **Independent Test:** Run the new handler test file; it is red before 2.2.
-      **Verification**:
-      - Run: `pnpm test -- -t "core handler"`
-      - Expected: New tests run (red before 2.2)
-    - [ ] 2.2 Implement core logic — `src/core/handler.ts`
-      **[USN-2]** | Priority: P1
-      **Spec:** `core-domain/Core Logic`
-      **Independent Test:** Run the handler tests; they pass against the impl.
-      **Verification**:
-      - Run: `pnpm test -- -t "core handler"`
-      - Expected: All handler tests pass
-
-    ## Phase 3: Integration
-    - [ ] 3.1 [P] Integrate with API — `src/api/client.ts`
-      **[USN-3]** | Priority: P2
-      **Spec:** `api-domain/Client Integration`
-      **Independent Test:** Run the API client lint in isolation.
-      **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`
-
-8. Reference concrete file paths and specific spec scenarios in the tasks.
-9. 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`.
-
-10. 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.
-11. 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.
-12. The orchestrator handles the `[OKAY]` / `[REJECT]` review loop and any
-     necessary fixes before proceeding to execution.
-
-## Traceability, TDD Ordering, and Handoff Hints
-    
-    Canonical definitions live in `_shared/openspec-convention.md`. These fields are
-    ADDITIVE to the existing `Verification` block, not a replacement, and they are
-    optional for back-compat (legacy `tasks.md` without them still executes).
-    
-    - **`[USN-<n>]`** — a user-story-number grouping label (a coarse story/epic
-      bucket). It is NOT the requirement linkage.
-    - **Priority** — one of `P1`, `P2`, `P3`.
-    - **`Spec:` trace tag** — names the exact requirement the task implements, in
-      `{domain}/{Requirement Name}` format (optionally `#{Scenario Name}`). This is
-      the requirement linkage `plan-reviewer` counts for coverage %; keep it
-      greppable and one requirement per tag.
-    - **`Independent Test`** — how the task's outcome is verified in isolation,
-      without depending on other tasks being complete.
-    
-    ### `tasks.tdd` ordering
-    
-    When `rules.tasks.tdd` is enabled in `config.yaml`, sequence test-authoring
-    tasks BEFORE their corresponding implementation tasks within the same phase (see
-    the Phase 2 example: 2.1 authors tests, 2.2 implements). When `tasks.tdd` is
-    disabled, impose no test-first ordering constraint. `plan-reviewer` enforces
-    this ordering when the flag is enabled.
-    
-    ### `[P]` parallel markers
-
-    When `rules.tasks.parallel_markers` is enabled in `config.yaml`, an optional
-    `[P]` marker MAY be placed AFTER the `N.M` number (`- [ ] 2.1 [P] Title`),
-    never before it (`[P] 2.1` would break the task-numbering validator). Emit
-    `[P]` ONLY on tasks that are intra-phase, dependency-free of every other task
-    in the same phase, and assigned to the SAME execution agent — never across
-    phases and never on tasks with intra-phase dependencies. `[P]` is
-    back-compatible: when `parallel_markers` is disabled or the marker is absent,
-    the plan executes exactly as it does today (absence = today's behavior). It
-    annotates an explicit parallel batch; it does not change `N.M`, `[USN]`, the
-    `Spec:` tag, or introduce flat `T001` ids.
-
-    ### Consume upstream handoffHints
-    
-    At task-generation start, surface the spec/design phases' `handoffHints` and
-    treat them as preservation constraints (coverage decisions, architecture
-    constraints, recorded Assumptions). When no hints were declared, surface
-    nothing. Surfacing is gated by `rules.handoffs.surface_hints`.
-    
-    ## 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.
-- Preserve accepted proposal or spec scope and success criteria in tasks.
-- Use boundaries and non-goals to express phase, file, or ownership limits,
-  not to shrink the accepted goal.
-- Convert deferred or unresolved affected areas into discovery,
-  coordination, or follow-up tasks, or emit an explicit warning when follow-up
-  cannot be planned yet.
-- 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.

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

@@ -1,131 +0,0 @@
----
-name: sdd-verify
-description: Verify implementation against specs and persist a compliance report.
----
-
-# SDD Verify Skill
-
-Act as the quality gate for a change by turning specs and test evidence into a
-verification report.
-
-## 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
-
-- Implementation work is complete enough to validate
-- A prior verification report must be refreshed after more code changes
-
-## Prerequisites
-
-- `change-name`
-- Tasks artifact
-- `pipeline-type` (`accelerated` or `full`)
-- Spec artifact (full pipeline only)
-- Design artifact (full pipeline only)
-- Proposal artifact (accelerated pipeline — used as the verification reference)
-- Ability to run the relevant checks or tests
-- Expected `round N` from the dispatch envelope (the verify-loop round counter; defaults to round 1 for the first verify after apply)
-
-## 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 verification reference)
-3. Optionally recover `apply-progress` with the same mode-aware rules if it
-   exists and helps explain task coverage.
-4. Read the changed code and run the required verification commands.
-5. If the selected mode includes OpenSpec, create
-   `openspec/changes/{change-name}/verify-report.md` with at least:
-
-   In `thoth-mem` mode, produce the same report content without creating the
-   file:
-
-    ```md
-    # Verification Report: {Change Title}
-
-    ## Round
-    round N  <!-- stamped from the dispatch envelope's expected round; source of truth for the loop counter -->
-
-    ## Completeness
-    ## Build and Test Evidence
-    ## Compliance Matrix
-    <!-- Full pipeline: map Given/When/Then scenarios from spec -->
-    <!-- Accelerated pipeline: map success criteria from proposal -->
-    ## Design Coherence (full pipeline only)
-
-    ## Issues Found
-
-    ### Critical
-    - **[C1]** {one-line problem statement}
-      - file: `path/to/file.ts:LINE` (or `path/to/file.ts` when line is N/A)
-      - scenario: `{Requirement title} › {Scenario name}` (full pipeline) OR
-        criterion: `{proposal success-criterion id/text}` (accelerated pipeline)
-      - fix: {imperative remediation instruction}
-
-    ### Warnings
-    - **[W1]** {one-line problem statement}
-      - file: `path/to/file.ts:LINE`
-      - scenario / criterion: {anchor}
-      - fix: {imperative remediation instruction}
-
-    ## Verdict
-    ```
-
-6. Build a compliance matrix: in full pipeline, map each Given/When/Then
-   scenario to evidence; in accelerated pipeline, map each proposal success
-   criterion to evidence.
-7. If the selected mode includes thoth-mem, persist the 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`.
-8. Stamp the expected `round N` from the dispatch envelope into the report's
-   `## Round` field and the `Round` return field. The orchestrator treats this
-   `round N` marker as the source of truth for the verify-loop round counter
-   when enforcing the round bound across iterations.
-9. Apply the governance-touched heuristic from
-   `_shared/openspec-convention.md` > Constitution Governance > Amendment
-   Auto-Suggest. When it matches, surface the shared report-only
-   `sdd-constitution` suggestion. This is advisory and MUST NOT change the
-   verdict or block verification.
-
-## Output Format
-
-Return:
-
-- `Change`
-- `Artifact`: `openspec/changes/{change-name}/verify-report.md`
-- `Topic Key`: `sdd/{change-name}/verify-report`
-- `Round`: `round N` (mirrors the report's `## Round` marker)
-- `Verdict`: pass, pass with warnings, or fail
-- `Compliance Summary`: compliant vs total scenarios
-- `Critical Issues`: anchored compact lines (`id — file:line — scenario/criterion — fix`), one per issue, or `None`
-- `Constitution Suggestion`: surfaced or none
-
-## Rules
-
-- Verification requires real evidence, not only static inspection.
-- Every acceptance criterion must appear in the compliance matrix: spec
-  scenarios in full pipeline, proposal success criteria in accelerated pipeline.
-- Distinguish blockers from warnings clearly.
-- Do not fix issues inside this phase; report them.
-- Every Critical Issue MUST carry at least one remediation anchor (file: and/or scenario:/criterion:); prose-only Critical Issues are invalid output.
-- Stamp the `round N` marker from the dispatch envelope into `## Round`.
-- Recover full artifacts with the protocol in the persistence contract.

package/src/skills/thoth-mem-agents/SKILL.md

@@ -1,210 +0,0 @@
----
-name: thoth-mem-agents
-description: Mandatory thoth-mem workflow contract for orchestrator/subagent memory ownership, parent session_id/project dispatch, prompt-save prohibitions, project-scoped read tools, session-summary ownership, and durable observation rules. Use whenever work mentions thoth-mem, persistent memory, orchestrator/subagents, session_id, project, saved prompts, session summaries, or project-level memory context.
-metadata:
-  author: thoth-agents
-  version: '1.0'
----
-
-# thoth-mem Agents Skill
-
-Use this skill whenever memory work crosses the orchestrator/subagent boundary.
-It prevents prompt pollution, implicit fallback sessions such as
-`manual-save-{project}`, and session-level writes from the wrong agent.
-
-## Shared References
-
-Read these first:
-
-- [../_shared/persistence-contract.md](../_shared/persistence-contract.md)
-- [../_shared/thoth-mem-convention.md](../_shared/thoth-mem-convention.md)
-
-## Active MCP Surface
-
-Use thoth-mem through these MCP tools:
-
-- `mem_recall` for fused retrieval and search
-- `mem_save` for observations, prompts, session summaries, and passive learnings
-- `mem_context` for recent session/project continuity
-- `mem_get` for full memory content and optional timeline context
-- `mem_project` for project summaries, graph facts, topics, and topic context
-- `mem_session` for root-owned session lifecycle and checkpoints
-
-Admin/export/import/sync/migration/rebuild/index/trace operations are CLI/HTTP/dashboard operations, not MCP tools.
-
-## Hard Ownership Split
-
-### Root/main orchestrator identity
-
-The initial/root agent in the harness is the orchestrator owner for this
-session, even when the runtime does not label it `orchestrator`.
-
-### Root-only session and prompt ownership
-
-At new root session start, when tools and identity are available, the root:
-
-1. Loads `thoth-mem-agents` and `requirements-interview`.
-2. Calls `mem_session(action="start")` with root session identity.
-3. Saves real user intent with `mem_save(kind="prompt")`.
-
-Root owns these operations:
-
-- `mem_session(action="start")`
-- `mem_session(action="checkpoint")` when used for root progress checkpoints
-- `mem_session(action="summary")`
-- `mem_save(kind="prompt")`
-- root-owned session summaries/checkpoints, including `mem_save(kind="session_summary")` when used as the summary carrier
-
-Subagents must never start/checkpoint/summarize sessions or save prompts.
-
-If tools or required identity are missing, report that bootstrap/compaction
-could not be persisted and continue without claiming memory was saved.
-
-## Root Recall and Save Protocol
-
-### Durable saves
-
-Root should persist durable outcomes with `mem_save`:
-
-- decisions and architecture constraints
-- bug fixes and root cause
-- non-obvious discoveries and patterns
-- configuration changes
-- durable preferences/constraints
-
-Keep content structured:
-
-```text
-What: concise description
-Why: reason or problem solved
-Where: files, paths, systems, or artifacts
-Learned: caveats or edge cases
-```
-
-### Recall funnel (canonical)
-
-1. `mem_recall(mode="compact")`
-2. `mem_recall(mode="context")`
-3. `mem_get(id=...)`
-
-Use `mem_get(id=..., include_timeline=true)` when chronology matters.
-Set `mem_recall` `limit` from 1 to 20. Use `mem_get` with `kind="observation"|"prompt"`, `include_timeline=true` plus `before`/`after`, and `offset`/`max_length` for large content.
-Use `mem_context(..., recall_query="...")` only as optional fused context, not
-as a replacement for the recall funnel.
-
-### Project navigation
-
-Use `mem_project` for project-level navigation:
-
-- `action="list"`
-- `action="summary"`
-- `action="graph"`
-- `action="topics"`
-- `action="topic"`
-
-`mem_project(action="graph")` relations are `HAS_TYPE`, `IN_PROJECT`, `HAS_TOPIC_KEY`, `HAS_WHAT`, `HAS_WHY`, `HAS_WHERE`, and `HAS_LEARNED`.
-
-### Session close and compaction
-
-Before ending meaningful work, root records continuity with either:
-
-- `mem_session(action="summary")`, or
-- root-owned `mem_save(kind="session_summary")`
-
-Before delegation after meaningful context changes, root may refresh a
-checkpoint/summary context using root-owned session tools. Subagent prompts must
-carry recovery instructions, never the raw handoff body.
-
-## Project-Scoped Context Rules
-
-`mem_context` and `mem_project(...)` are bounded context reads, not ownership
-transfers.
-
-Rules:
-
-- Use only with parent `session_id` and `project` when delegated.
-- Keep calls bounded to the task scope.
-- Do not use them to bypass the recall funnel.
-- Do not use them to create session summaries or save prompts.
-
-Operational note: semantic lanes can be pending/degraded; lexical/KG fallback is
-valid and expected. Treat fallback metadata as state, not failure.
-
-## Dispatch Contract
-
-When subagents may use thoth-mem, dispatch MUST include:
-
-- parent `session_id`
-- `project`
-- persistence mode
-- memory permissions (read-only vs delegated write)
-- bounded recall instructions
-
-Without both `session_id` and `project`, subagents must not call thoth-mem.
-
-## Capability Split by Agent Type
-
-### Read-only subagents
-
-Roles: explorer, librarian, oracle.
-
-Allowed:
-
-- recall funnel: `mem_recall(mode="compact")` -> `mem_recall(mode="context")` -> `mem_get`
-- optional bounded context: `mem_context`, `mem_project`
-
-Not allowed:
-
-- `mem_save`
-- any root session ownership action (`mem_session(...)`)
-- `mem_save(kind="prompt")`
-
-### Write-capable subagents
-
-Roles: deep, quick, designer.
-
-Allowed:
-
-- same recall funnel as read-only roles
-- optional bounded context via `mem_context`/`mem_project`
-- delegated durable saves via `mem_save(kind="observation")`
-- deterministic SDD artifact saves only when explicitly delegated
-
-Rules:
-
-- every thoth-mem call uses parent `session_id` and `project`
-- never start/checkpoint/summarize sessions
-- never save prompts
-- report missing/stale/contradictory/insufficient recall context
-
-## Topic-Key Rules
-
-General durable observations must stay outside `sdd/*`.
-SDD artifacts use deterministic keys only:
-
-`sdd/{change}/{artifact}`
-
-Examples: `sdd/add-user-auth/spec`, `sdd/add-user-auth/design`,
-`sdd/add-user-auth/tasks`.
-
-## Anti-Patterns
-
-Reject immediately:
-
-- asking a subagent to save a generated dispatch prompt
-- subagent use of root session operations (`mem_session(...)`)
-- subagent save of `kind="prompt"`
-- inventing thoth-mem tools outside the six-tool MCP surface
-- treating `mem_context` as a substitute for recall funnel
-- saving general notes under `sdd/*`
-
-## Response Standard
-
-When applying this skill, state clearly:
-
-- memory owner for each operation (root vs subagent)
-- allowed tools for the task
-- whether parent `session_id` and `project` are present
-- whether context reads are bounded and explicitly allowed
-- whether topic keys collide with `sdd/*`
-- whether any rule is instruction-level due to runtime enforcement limits