busya/ss-tools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

agents

Browse Source
This commit is contained in:
busya
2026-05-11 22:58:01 +03:00
parent 2abba06e52
commit fefdee98d0
30 changed files with 1681 additions and 1222 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
.opencode/command/read_semantics.md
View File

@@ -1,4 +1,4 @@
---
description: read semantic protocol
description: Load semantic protocol context for ss-tools
---
MANDATORY USE `skill({name="semantics-core"})`, `skill({name="semantics-contracts"})`, `skill({name="semantics-belief"})`, `skill({name="semantics-frontend"})`
MANDATORY USE `skill({name="semantics-core"})`, `skill({name="semantics-contracts"})`, `skill({name="semantics-belief"})`, `skill({name="semantics-python"})`, `skill({name="semantics-svelte"})`

7
.opencode/command/speckit.analyze.md
View File

@@ -1,5 +1,5 @@
---
description: Perform a read-only consistency analysis across spec.md, plan.md, tasks.md, and ADR sources for the active Python/Svelte feature.
description: Perform a read-only consistency analysis across spec.md, plan.md, tasks.md, and ADR sources for the active ss-tools feature.
---
## User Input
@@ -31,7 +31,6 @@ Identify inconsistencies, ambiguities, coverage gaps, and decision-memory drift
- `tasks.md`
- `contracts/modules.md` when present
- `README.md`
- `docs/SEMANTIC_PROTOCOL_COMPLIANCE.md`
- `.specify/memory/constitution.md`
- relevant `docs/adr/*.md`
@@ -49,7 +48,7 @@ Identify inconsistencies, ambiguities, coverage gaps, and decision-memory drift
- constitution conflicts
- coverage gaps
- terminology drift
- repository-structure mismatches
- repository-structure mismatches (e.g., Rust/MCP paths in a Python/Svelte project)
- decision-memory drift and rejected-path scheduling
5. Produce a compact Markdown report with:
@@ -68,5 +67,5 @@ Identify inconsistencies, ambiguities, coverage gaps, and decision-memory drift
- Treat stale Rust/MCP assumptions in plan/tasks as real defects for this Python/Svelte repository.
- Treat missing ADR propagation as a real defect, not a documentation nit.
- Prefer repository-real expectations (`backend/src/**/*.py`, `frontend/src/**/*.svelte`, `backend/tests/`, `frontend/tests/`, `pytest`, `vitest`, `ruff check`, static semantic verification).
- Prefer repository-real expectations (`backend/src/**/*.py`, `frontend/src/**/*.svelte`, `backend/tests/`, `frontend/src/lib/**/__tests__/`).
- Do not treat `.kilo/plans/*` as feature artifacts for consistency analysis.

24
.opencode/command/speckit.checklist.md
View File

@@ -149,19 +149,18 @@ You **MUST** consider the user input before proceeding (if not empty).
- "Are error handling requirements defined for all API failure modes? [Gap]"
- "Are accessibility requirements specified for all interactive elements? [Completeness]"
- "Are mobile breakpoint requirements defined for responsive layouts? [Gap]"
- "Are WebSocket reconnection requirements defined for real-time features? [Gap]"
Clarity:
- "Is 'fast loading' quantified with specific timing thresholds? [Clarity, Spec §NFR-2]"
- "Are 'related dashboards' selection criteria explicitly defined? [Clarity, Spec §FR-5]"
- "Are 'related episodes' selection criteria explicitly defined? [Clarity, Spec §FR-5]"
- "Is 'prominent' defined with measurable visual properties? [Ambiguity, Spec §FR-4]"
Consistency:
- "Do navigation requirements align across all pages? [Consistency, Spec §FR-10]"
- "Are component requirements consistent between list and detail views? [Consistency]"
- "Are card component requirements consistent between landing and detail pages? [Consistency]"
Coverage:
- "Are requirements defined for zero-state scenarios (no dashboards)? [Coverage, Edge Case]"
- "Are requirements defined for zero-state scenarios (no episodes)? [Coverage, Edge Case]"
- "Are concurrent user interaction scenarios addressed? [Coverage, Gap]"
- "Are requirements specified for partial data loading failures? [Coverage, Exception Flow]"
@@ -172,7 +171,7 @@ You **MUST** consider the user input before proceeding (if not empty).
Decision Memory:
- "Do all repo-shaping technical choices have explicit rationale before tasks are generated? [Decision Memory, Plan]"
- "Are rejected alternatives documented for architectural branches that would materially change implementation scope? [Decision Memory, Gap]"
- "Can a developer determine from the planning artifacts which tempting shortcut is forbidden? [Decision Memory, Clarity]"
- "Can a coder determine from the planning artifacts which tempting shortcut is forbidden? [Decision Memory, Clarity]"
**Scenario Classification & Coverage** (Requirements Quality Focus):
- Check if requirements exist for: Primary, Alternate, Exception/Error, Recovery, Non-Functional scenarios
@@ -189,8 +188,8 @@ You **MUST** consider the user input before proceeding (if not empty).
Ask questions about the requirements themselves:
- Ambiguities: "Is the term 'fast' quantified with specific metrics? [Ambiguity, Spec §NFR-1]"
- Conflicts: "Do navigation requirements conflict between §FR-10 and §FR-10a? [Conflict]"
- Assumptions: "Is the assumption of 'always available API' validated? [Assumption]"
- Dependencies: "Are external API requirements documented? [Dependency, Gap]"
- Assumptions: "Is the assumption of 'always available podcast API' validated? [Assumption]"
- Dependencies: "Are external podcast API requirements documented? [Dependency, Gap]"
- Missing definitions: "Is 'visual hierarchy' defined with measurable criteria? [Gap]"
- Decision-memory drift: "Do tasks inherit the same rejected-path guardrails defined in planning? [Decision Memory, Conflict]"
@@ -255,7 +254,6 @@ Sample items:
- "Are authentication requirements consistent across all endpoints? [Consistency]"
- "Are retry/timeout requirements defined for external dependencies? [Coverage, Gap]"
- "Is versioning strategy documented in requirements? [Gap]"
- "Are WebSocket message schemas documented for all event types? [Completeness, Gap]"
**Performance Requirements Quality:** `performance.md`
@@ -291,20 +289,20 @@ Sample items:
**❌ WRONG - These test implementation, not requirements:**
```markdown
- [ ] CHK001 - Verify landing page displays 3 dashboard cards [Spec §FR-001]
- [ ] CHK001 - Verify landing page displays 3 episode cards [Spec §FR-001]
- [ ] CHK002 - Test hover states work correctly on desktop [Spec §FR-003]
- [ ] CHK003 - Confirm logo click navigates to home page [Spec §FR-010]
- [ ] CHK004 - Check that related dashboards section shows 3-5 items [Spec §FR-005]
- [ ] CHK004 - Check that related episodes section shows 3-5 items [Spec §FR-005]
```
**✅ CORRECT - These test requirements quality:**
```markdown
- [ ] CHK001 - Are the number and layout of featured dashboards explicitly specified? [Completeness, Spec §FR-001]
- [ ] CHK001 - Are the number and layout of featured episodes explicitly specified? [Completeness, Spec §FR-001]
- [ ] CHK002 - Are hover state requirements consistently defined for all interactive elements? [Consistency, Spec §FR-003]
- [ ] CHK003 - Are navigation requirements clear for all clickable brand elements? [Clarity, Spec §FR-010]
- [ ] CHK004 - Is the selection criteria for related dashboards documented? [Gap, Spec §FR-005]
- [ ] CHK005 - Are loading state requirements defined for asynchronous dashboard data? [Gap]
- [ ] CHK004 - Is the selection criteria for related episodes documented? [Gap, Spec §FR-005]
- [ ] CHK005 - Are loading state requirements defined for asynchronous episode data? [Gap]
- [ ] CHK006 - Can "visual hierarchy" requirements be objectively measured? [Measurability, Spec §FR-001]
- [ ] CHK007 - Do planning artifacts state why the accepted architecture was chosen and which alternative is rejected? [Decision Memory, ADR]
```

3
.opencode/command/speckit.clarify.md
View File

@@ -46,7 +46,6 @@ Execution steps:
- Critical user journeys / sequences
- Error/empty/loading states
- Accessibility or localization notes
- Svelte 5 runes reactivity expectations ($state, $derived, $effect, $props)
Non-Functional Quality Attributes:
- Performance (latency, throughput targets)
@@ -67,7 +66,7 @@ Execution steps:
- Conflict resolution (e.g., concurrent edits)
Constraints & Tradeoffs:
- Technical constraints (Python 3.13+, Svelte 5, PostgreSQL)
- Technical constraints (language, storage, hosting)
- Explicit tradeoffs or rejected alternatives
Terminology & Consistency:

14
.opencode/command/speckit.constitution.md
View File

@@ -1,5 +1,5 @@
---
description: Create or update the local workflow constitution and propagate principle changes into dependent speckit artifacts.
description: Create or update the local workflow constitution and propagate principle changes into dependent speckit artifacts for ss-tools.
handoffs:
- label: Build Specification
agent: speckit.specify
@@ -21,16 +21,16 @@ You are updating the local constitution at `.specify/memory/constitution.md`. Th
- `.opencode/skills/semantics-core/SKILL.md`
- `.opencode/skills/semantics-contracts/SKILL.md`
- `.opencode/skills/semantics-belief/SKILL.md`
- `.opencode/skills/semantics-python/SKILL.md`
- `.opencode/skills/semantics-svelte/SKILL.md`
- `.opencode/skills/semantics-testing/SKILL.md`
- `.opencode/skills/semantics-frontend/SKILL.md`
- `README.md`
- `docs/SEMANTIC_PROTOCOL_COMPLIANCE.md`
- `docs/adr/*`
Execution flow:
1. Load the existing constitution at `.specify/memory/constitution.md`.
2. Identify placeholders, stale assumptions, or principles that conflict with the current Python/Svelte repository.
2. Identify placeholders, stale assumptions, or principles that conflict with the current ss-tools repository (Python/Svelte, not Rust/MCP).
3. Derive concrete constitutional text from user input and repository reality.
4. Version the constitution using semantic versioning:
- MAJOR: incompatible governance/principle change
@@ -43,11 +43,6 @@ Execution flow:
- `.specify/templates/tasks-template.md`
- `.specify/templates/test-docs-template.md`
- `.specify/templates/ux-reference-template.md`
- `.opencode/command/speckit.plan.md`
- `.opencode/command/speckit.tasks.md`
- `.opencode/command/speckit.implement.md`
- `.opencode/command/speckit.test.md`
- `.opencode/command/speckit.analyze.md`
7. Prepend a sync impact report as an HTML comment at the top of the constitution.
8. Validate:
- no unexplained placeholders remain
@@ -58,7 +53,6 @@ Execution flow:
## Output
Summarize:
- new version and bump rationale
- affected templates/workflows
- any deferred follow-ups

28
.opencode/command/speckit.implement.md
View File

@@ -1,5 +1,5 @@
---
description: Execute the implementation plan by processing the active tasks.md for the Python/Svelte repository.
description: Execute the implementation plan by processing the active tasks.md for the ss-tools repository (Python backend + Svelte frontend).
handoffs:
- label: Audit & Verify (Tester)
agent: qa-tester
@@ -32,45 +32,41 @@ You **MUST** consider the user input before proceeding (if not empty).
- `research.md`, `data-model.md`, `quickstart.md` when present
- `.specify/memory/constitution.md`
- `README.md`
- `docs/SEMANTIC_PROTOCOL_COMPLIANCE.md`
- relevant `docs/adr/*.md`
4. Parse tasks by phase, dependencies, story ownership, and guardrails.
5. Execute implementation phase-by-phase with strict semantic and verification discipline.
## Repository Reality Rules
- Default source paths are `backend/src/**/*.py`, `frontend/src/**/*.svelte`, `backend/tests/`, and `frontend/tests/`.
- Source paths: `backend/src/**/*.py` and `frontend/src/**/*.svelte`.
- Active feature docs always live under `specs/<feature>/...` and are discovered via the `.specify/scripts/bash/*` helpers.
- Default verification stack is Python/Svelte-native and repository-real:
- `cd backend && pytest` (backend tests)
- `cd frontend && npm run test` (frontend vitest)
- `ruff check backend/` (Python linting)
- `cd frontend && npm run build` (Svelte build check)
- `python3 scripts/static_verify.py` (semantic static verification when available)
- Do not fall back to `cargo`, `cargo test`, `cargo clippy`, `src/**/*.rs`, or Rust/MCP conventions unless the active feature genuinely introduces such a surface.
- Default verification stack:
- Backend: `cd backend && source .venv/bin/activate && python -m pytest -v`
- Backend lint: `python -m ruff check backend/src/ backend/tests/`
- Frontend: `cd frontend && npm run test`
- Frontend build: `cd frontend && npm run build`
- Do not fall back to Rust `cargo`/`src/server/` conventions — this is a Python/Svelte project.
## Semantic Execution Rules
- Preserve and extend canonical `[DEF]` anchors and metadata.
- Use correct comment-anchor syntax: `# [DEF:...]` for Python, `<!-- [DEF:...] -->` for Svelte markup, `// [DEF:...]` for Svelte script blocks.
- Preserve and extend canonical anchor regions.
- Match contract density to effective complexity.
- Keep accepted-path and rejected-path memory intact.
- Do not silently restore an ADR- or contract-rejected branch.
- For C4/C5 Python orchestration flows, account for the belief runtime where required by repository norms and local contracts.
- For C4/C5 Svelte components, ensure `@UX_STATE`, `@UX_FEEDBACK`, `@UX_RECOVERY`, `@UX_REACTIVITY` tags are satisfied.
- For C4/C5 Python orchestration flows, account for the belief runtime (JSON structured logging via `reason()`, `reflect()`, `explore()`).
- For C4/C5 Svelte components, account for belief runtime (console markers `[ComponentID][MARKER]`).
- Treat pseudo-semantic markup as invalid.
## Progress and Acceptance
- Mark tasks complete only after local verification succeeds.
- Handoff to the tester must include touched files, declared complexity, contract expectations, ADR guardrails, and executed verifiers.
- Final acceptance requires explicit evidence that the `speckit.test` workflow-equivalent verification was executed.
- Final acceptance requires explicit evidence that verification was executed.
- `.kilo/plans/*` may exist as internal assistant scratch context, but it is not part of the speckit feature output surface and must not replace `specs/<feature>/...` artifacts.
## Completion Gate
No task batch is complete if any of the following remain in the touched scope:
- broken or unclosed anchors
- missing complexity-required metadata
- unresolved critical contract gaps

101
.opencode/command/speckit.plan.md
View File

@@ -1,13 +1,13 @@
---
description: Execute the Python/Svelte implementation planning workflow and generate research, design, contracts, and quickstart artifacts.
description: Execute the implementation planning workflow for ss-tools (Python backend + Svelte frontend) and generate research, design, contracts, and quickstart artifacts.
handoffs:
- label: Create Tasks
agent: speckit.tasks
prompt: Break the Python/Svelte plan into executable tasks
prompt: Break the plan into executable tasks for Python/Svelte implementation
send: true
- label: Create Checklist
agent: speckit.checklist
prompt: Create a requirements-quality checklist for the active Python/Svelte feature
prompt: Create a requirements-quality checklist for the active feature
---
## User Input
@@ -27,20 +27,20 @@ You **MUST** consider the user input before proceeding (if not empty).
2. **Load canonical planning context**:
- `README.md`
- `backend/pyproject.toml` and `backend/requirements.txt`
- `frontend/package.json` and `frontend/svelte.config.js`
- `docs/SEMANTIC_PROTOCOL_COMPLIANCE.md`
- `docs/adr/*.md` (Architecture Decision Records)
- `requirements.txt` (backend dependencies)
- `frontend/package.json` (frontend dependencies)
- `.specify/memory/constitution.md`
- `.opencode/skills/semantics-core/SKILL.md`
- `.opencode/skills/semantics-contracts/SKILL.md`
- `.opencode/skills/semantics-python/SKILL.md`
- `.opencode/skills/semantics-svelte/SKILL.md`
- `.opencode/skills/semantics-testing/SKILL.md`
- `.opencode/skills/semantics-frontend/SKILL.md`
- `.specify/templates/plan-template.md`
- relevant `docs/adr/*.md`
3. **Execute the planning workflow** using the template structure:
- Fill `Technical Context` for the current repository reality: Python 3.13+ backend (FastAPI, SQLAlchemy), Svelte 5 frontend (SvelteKit, Vite, Tailwind CSS), PostgreSQL storage, Docker deployment.
- Fill `Constitution Check` using the local constitution, semantic protocol compliance doc, and ADR set.
- Fill `Technical Context` for the current repository reality: Python 3.9+/FastAPI backend, SvelteKit 5/Tailwind frontend, PostgreSQL, Docker, semantic contracts, belief runtime.
- Fill `Constitution Check` using the local constitution.
- ERROR if a blocking constitutional or semantic conflict is discovered and cannot be justified.
- Phase 0: generate `research.md` in `FEATURE_DIR`, resolving all material unknowns.
- Phase 1: generate `data-model.md`, `contracts/modules.md`, optional machine-readable contract artifacts, and `quickstart.md` in `FEATURE_DIR`.
@@ -51,19 +51,17 @@ You **MUST** consider the user input before proceeding (if not empty).
## Phase 0: Research
Research must resolve only implementation-shaping unknowns that matter for this Python/Svelte repository, such as:
- backend module placement under `backend/src/` (api/, core/, models/, services/, schemas/)
- frontend component placement under `frontend/src/` (routes/, lib/components/, lib/stores/, lib/api/)
- `backend/tests/` and `frontend/tests/` strategy and required fixture coverage
- FastAPI endpoint / WebSocket schema design
- Svelte 5 runes reactivity model ($state, $derived, $effect, $props)
- PostgreSQL schema and migration strategy
- belief-state runtime coverage for C4/C5 Python flows
Research must resolve only implementation-shaping unknowns that matter for this repository, such as:
- module placement under `backend/src/` or `frontend/src/`
- API endpoint design (REST routes, WebSocket channels)
- database schema changes (SQLAlchemy models, migrations)
- Svelte component hierarchy and store topology
- async task orchestration patterns
- test strategy (pytest + vitest) and required fixture coverage
- belief runtime instrumentation for C4/C5 flows
- semantic validation boundaries and static verification workflow
Write `research.md` with concise sections:
- Decision
- Rationale
- Alternatives Considered
@@ -75,54 +73,47 @@ Use `[NEED_CONTEXT: target]` instead of inventing relation targets, DTO names, o
### UX / Interaction Validation
Validate the proposed design against `ux_reference.md` as an **interaction reference** for:
- API callers (REST endpoints, WebSocket messages)
- CLI/operator flows
- Svelte UI flows (when the feature introduces frontend components)
- Result envelopes, warnings, and recovery guidance
Validate the proposed design against `ux_reference.md` as an **interaction reference** for operators, API callers, CLI/operator flows, result envelopes, warnings, recovery guidance, and (when applicable) browser-based UI flows.
If the planned architecture degrades the promised interaction model, deterministic recovery path, or context-budget behavior, stop and warn the user.
### Data Model Output
Generate `data-model.md` for Python/Svelte domain entities such as:
- FastAPI request/response schemas (Pydantic models)
- SQLAlchemy ORM entities
- Svelte store shapes and component props
- WebSocket message envelopes
- Task/report/artifact entities
Generate `data-model.md` for ss-tools domain entities such as:
- Pydantic request/response schemas
- SQLAlchemy models and relationships
- WebSocket message formats
- Task state transitions
- Git operation entities
- Plugin configuration schemas
- Frontend TypeScript types (when feature is fullstack)
### Global ADR Continuity
Before task decomposition, planning must identify any repo-shaping decisions this feature depends on or extends:
- Python module layout and decomposition (`backend/src/api/`, `backend/src/core/`, etc.)
- Frontend component architecture (Svelte 5 runes, SvelteKit routing)
- Belief-state runtime behavior for C4/C5 flows
- Semantic comment-anchor rules for Python and Svelte
- RBAC/security constraints (local auth, ADFS SSO)
- Plugin system lifecycle
- Python module layout and decomposition
- FastAPI route organization
- SvelteKit routing and component hierarchy
- belief-state runtime behavior (JSON structured logging / console markers)
- semantic comment-anchor rules
- payload/schema stability decisions
For each durable choice, ensure the plan references the relevant ADR and explicitly records accepted and rejected paths.
### Contract Design Output
Generate `contracts/modules.md` as the primary design contract for implementation. Contracts must:
- use short semantic IDs
- classify each planned module/component with `@COMPLEXITY` 1-5
- use canonical relation syntax `@RELATION PREDICATE -> TARGET_ID`
- preserve accepted-path and rejected-path memory via `@RATIONALE` and `@REJECTED` where needed
- describe Python backend modules (api routes, core services, models, plugins) and Svelte frontend components instead of inventing Rust/MCP layers
- use appropriate comment-anchor syntax: `# [DEF:...]` for Python, `<!-- [DEF:...] -->` for Svelte markup, `// [DEF:...]` for Svelte script blocks
- describe Python modules, FastAPI routes, Svelte components, stores, and services instead of inventing MCP/backend layers
Complexity guidance for this repository:
- **Complexity 1**: anchors only (DTOs, simple constants)
- **Complexity 2**: `@PURPOSE` (utility functions, pure helpers)
- **Complexity 3**: `@PURPOSE`, `@RELATION` (multi-step flows with dependencies); Svelte components also `@UX_STATE`
- **Complexity 4**: `@PURPOSE`, `@RELATION`, `@PRE`, `@POST`, `@SIDE_EFFECT`; Python orchestration paths should account for belief runtime markers (`belief_scope`, `reason`, `reflect`, `explore`); Svelte also `@UX_FEEDBACK`, `@UX_RECOVERY`, `@UX_REACTIVITY`
- **Complexity 1**: anchors only (DTOs, simple Pydantic schemas)
- **Complexity 2**: `@PURPOSE` (pure functions, utility helpers)
- **Complexity 3**: `@PURPOSE`, `@RELATION` (service modules, route handlers)
- **Complexity 4**: `@PURPOSE`, `@RELATION`, `@PRE`, `@POST`, `@SIDE_EFFECT`; orchestration paths should account for belief runtime markers before mutation or return
- **Complexity 5**: level 4 plus `@DATA_CONTRACT`, `@INVARIANT`, and explicit decision-memory continuity
If a planned contract depends on unknown schema, relation target, or ADR identity, emit `[NEED_CONTEXT: target]` instead of fabricating placeholders.
@@ -130,19 +121,15 @@ If a planned contract depends on unknown schema, relation target, or ADR identit
### Quickstart Output
Generate `quickstart.md` using real repository verification paths:
- start or exercise the FastAPI backend entrypoint: `cd backend && python -m uvicorn src.app:app --reload`
- start or exercise the SvelteKit frontend: `cd frontend && npm run dev`
- invoke relevant API endpoints or CLI commands
- validate expected response envelopes, WebSocket messages, and recovery flows
- run `cd backend && pytest` for backend tests
- run `cd frontend && npm run test` for frontend tests
- run `ruff check backend/` for Python linting
- Backend: `cd backend && source .venv/bin/activate && python -m pytest -v`
- Frontend: `cd frontend && npm run test`
- Lint: `python -m ruff check backend/src/ backend/tests/`
- Docker: `docker compose up --build`
## Key Rules
- Use absolute paths in workflow execution.
- Planning must reflect the current repository structure (`backend/src/`, `frontend/src/`, `docs/adr/`) rather than legacy Rust/MCP examples.
- Do not reference `.ai/*` or `.kilocode/*` paths as feature artifacts.
- Planning must reflect the current repository structure (`backend/src/**/*.py`, `frontend/src/**/*.svelte`, `backend/tests/`, `docs/adr/*`).
- Do not reference `.ai/*` or `.kilocode/*` paths (use `.opencode/` for skills).
- Do not write any feature planning artifact outside `specs/<feature>/...`.
- Do not hand off to `speckit.tasks` until blocking ADR continuity and rejected-path guardrails are explicit.

14
.opencode/command/speckit.semantics.md
View File

@@ -1,5 +1,5 @@
---
description: Maintain semantic integrity by reindexing, auditing, and reviewing the Python/Svelte repository through AXIOM MCP tools.
description: Maintain semantic integrity by reindexing, auditing, and reviewing the ss-tools repository through AXIOM MCP tools.
---
## User Input
@@ -21,21 +21,22 @@ Ensure the repository adheres to the active GRACE semantic protocol using AXIOM
3. **STRICT ADHERENCE** — follow the local semantic authorities:
- `.opencode/skills/semantics-core/SKILL.md`
- `.opencode/skills/semantics-contracts/SKILL.md`
- `.opencode/skills/semantics-python/SKILL.md`
- `.opencode/skills/semantics-svelte/SKILL.md`
- `.opencode/skills/semantics-testing/SKILL.md`
- `.opencode/skills/semantics-frontend/SKILL.md`
- `docs/SEMANTIC_PROTOCOL_COMPLIANCE.md`
- `docs/adr/*`
- relevant `docs/adr/*`
4. **NON-DESTRUCTIVE** — do not remove business logic; only add or correct semantic markup unless the user requested implementation changes.
5. **NO PSEUDO-CONTRACTS** — do not mechanically inject fake semantic boilerplate.
6. **ID NAMING** — use short domain-driven IDs, never language import paths or filesystem-shaped IDs as the semantic primary key.
6. **ID NAMING** — use short domain-driven IDs, never full file paths or import paths as the semantic primary key.
7. **DECISION-MEMORY CONTINUITY** — audit ADRs, preventive task guardrails, and local `@RATIONALE` / `@REJECTED` as a single chain.
8. **LANGUAGE-AWARE** — Python uses `# #region` / `# #endregion`; Svelte HTML uses `<!-- #region -->` / `<!-- #endregion -->`; Svelte script uses `// #region` / `// #endregion`.
## Execution Steps
1. Reindex the semantic workspace.
2. Measure workspace semantic health.
3. Audit top issues:
- broken anchors or malformed DEF regions
- broken anchors or malformed regions
- missing complexity-required metadata
- unresolved relations
- isolated critical contracts
@@ -49,7 +50,6 @@ Ensure the repository adheres to the active GRACE semantic protocol using AXIOM
## Output
Return:
- health metrics
- PASS/FAIL status
- top issues

34
.opencode/command/speckit.specify.md
View File

@@ -1,5 +1,5 @@
---
description: Create or update the feature specification from a natural-language feature description for the Python/Svelte repository.
description: Create or update the feature specification from a natural-language feature description for the ss-tools project (Python backend + Svelte frontend).
handoffs:
- label: Build Technical Plan
agent: speckit.plan
@@ -33,47 +33,36 @@ The feature description is the text passed to `/speckit.specify`.
- `.specify/templates/ux-reference-template.md`
- `.specify/memory/constitution.md`
- `README.md`
- `docs/SEMANTIC_PROTOCOL_COMPLIANCE.md`
- relevant `docs/adr/*` when the feature clearly touches an existing architectural lane
4. Create or update the following artifacts inside `FEATURE_DIR` only:
- `spec.md`
- `ux_reference.md`
- `checklists/requirements.md`
5. Generate `ux_reference.md` as an **interaction reference** for API callers, CLI/operator flows, Svelte UX states, result envelopes, warnings, and recovery behavior.
6. Write `spec.md` focused on **what** the user/operator needs and **why**, not how the Python/FastAPI backend or Svelte frontend will implement it.
5. Generate `ux_reference.md` as an **interaction reference** for operators, API callers, and (when applicable) browser-based UI flows. Capture result envelopes, warnings, and recovery behavior.
6. Write `spec.md` focused on **what** the user/operator needs and **why**, not how Python or Svelte will implement it.
7. Validate the spec against a requirements-quality checklist and iterate until major issues are resolved.
## Specification Rules
- Use domain language appropriate for this repository: API callers (REST/WebSocket), CLI operators, Svelte UI users, task runners, data migration operators, Git integration users.
- Avoid leaking implementation details such as FastAPI route names, SQLAlchemy models, Svelte component names, or exact file-level refactors.
- Use domain language appropriate for this repository: Superset dashboards, datasets, migrations, Git operations, tasks, plugins, RBAC, WebSocket logging.
- Avoid leaking implementation details such as module names, file-level refactors, Pydantic schemas, or Svelte component names.
- Use `[NEEDS CLARIFICATION: ...]` only for truly blocking product ambiguities. Maximum 3 markers.
- Prefer informed defaults grounded in repository context over unnecessary clarification.
- The default project structure is a web application with `backend/src/` (Python) and `frontend/src/` (Svelte). Assume this unless the feature explicitly changes it.
- Do not assume Rust, MCP server, cargo, or `src/*.rs` conventions unless the feature actually introduces them.
- Feature may be backend-only (Python/FastAPI), frontend-only (Svelte/Tailwind), or fullstack (both).
- Do not write feature outputs to `.kilo/plans/`, `.kilo/reports/`, or any path outside `specs/<feature>/...`.
## UX / Interaction Reference Rules
- `ux_reference.md` is mandatory. For this repository it covers both:
- **API/interaction reference** for backend callers (REST endpoints, WebSocket messages, CLI commands)
- **Svelte UX reference** for frontend flows (when the feature has a UI component)
- Capture:
- caller/operator/end-user persona
- happy-path invocation flow (API requests, CLI commands, or UI interactions)
- result envelope expectations (JSON response shapes, CLI output, UI feedback)
- warning/degraded states
- failure recovery guidance
- canonical terminology
- Include `@UX_STATE`, `@UX_FEEDBACK`, `@UX_RECOVERY`, `@UX_REACTIVITY` guidance when the feature introduces Svelte components.
- `ux_reference.md` is mandatory.
- For backend/API features: capture caller persona, happy-path invocation flow, result envelope expectations, warning/degraded states, failure recovery guidance, and canonical terminology.
- For frontend features: additionally capture UI states, navigation flows, WebSocket feedback expectations, and browser-verifiable behavior.
- Only include `@UX_*` guidance when the feature has a user interface component.
## Quality Validation
Generate `FEATURE_DIR/checklists/requirements.md` and ensure it validates:
- no implementation leakage into `spec.md`
- no stale Rust/MCP assumptions unless the feature explicitly needs them
- compatibility with the Python/FastAPI backend and Svelte frontend surface
- compatibility with the Python/Svelte ss-tools stack
- measurable success criteria
- explicit edge cases and recovery paths
- decision-memory readiness for downstream planning
@@ -83,7 +72,6 @@ If unresolved clarification markers remain, present them in a compact, high-impa
## Completion Report
Report:
- branch name
- feature directory under `specs/`
- `spec.md` path

76
.opencode/command/speckit.tasks.md
View File

@@ -1,13 +1,13 @@
---
description: Generate an actionable, dependency-ordered tasks.md for the active Python/Svelte feature.
description: Generate an actionable, dependency-ordered tasks.md for the active ss-tools feature (Python backend + Svelte frontend).
handoffs:
- label: Analyze For Consistency
agent: speckit.analyze
prompt: Run a cross-artifact consistency analysis for the Python/Svelte feature
prompt: Run a cross-artifact consistency analysis for the feature
send: true
- label: Implement Project
agent: speckit.implement
prompt: Start implementation in phases for the Python/Svelte feature
prompt: Start implementation in phases for the feature
send: true
---
@@ -31,9 +31,9 @@ You **MUST** consider the user input before proceeding (if not empty).
3. **Build the task model**:
- Extract user stories and priorities from `spec.md`
- Extract repository structure, backend/frontend scope, verification stack, and semantic constraints from `plan.md`
- Extract repository structure, tool/resource scope, verification stack, and semantic constraints from `plan.md`
- Extract accepted-path and rejected-path memory from ADRs and `contracts/modules.md`
- Map entities, API payloads, UI components, and verification scenarios to stories
- Map entities to stories
- Generate tasks grouped by story and ordered by dependency
- Validate that no task schedules an ADR-rejected path
@@ -67,59 +67,42 @@ Every task MUST follow:
```
Rules:
1. `- [ ]` checkbox is mandatory
2. sequential task IDs (`T001`, `T002`, ...)
3. `[P]` only for truly parallelizable tasks
4. `[USx]` required only for user-story phases
5. exact file paths required in the description
### Python / Svelte Pathing
### ss-tools Pathing
Prefer real repository paths such as:
**Backend (Python):**
- `backend/src/api/*.py` (FastAPI routes)
- `backend/src/core/**/*.py` (core services, task manager, auth, migration, plugins)
- `backend/src/core/**/*.py` (business logic, plugins)
- `backend/src/models/*.py` (SQLAlchemy models)
- `backend/src/services/*.py` (business logic)
- `backend/src/services/*.py` (service layer)
- `backend/src/schemas/*.py` (Pydantic schemas)
- `backend/tests/*.py` (pytest tests)
**Frontend (Svelte):**
- `backend/tests/*.py` (pytest)
- `frontend/src/routes/**/*.svelte` (SvelteKit pages)
- `frontend/src/lib/components/**/*.svelte` (reusable Svelte 5 components)
- `frontend/src/lib/stores/*.svelte.js` (Svelte rune stores)
- `frontend/src/lib/api/*.js` (API client modules)
- `frontend/tests/**/*.test.js` (vitest tests)
- `frontend/src/lib/components/*.svelte` (UI components)
- `frontend/src/lib/stores/*.js` (Svelte stores)
- `frontend/src/lib/api/*.js` (API client)
- `frontend/src/lib/**/__tests__/*.test.js` (vitest)
- `docs/adr/*.md` (architecture decisions)
- `specs/<feature>/contracts/*.md` (design contracts)
**Shared/Infrastructure:**
- `docs/adr/*.md`
- `docker/*`
- `specs/<feature>/contracts/*.md`
Do **not** generate default tasks for:
- `src/**/*.rs` or `tests/*.rs`
- `Cargo.toml`
- `cargo` commands
- MCP server/tool/resource syntax unless the feature actually introduces them
Do NOT generate default tasks for Rust/MCP paths (`src/server/`, `*.rs`, `cargo`).
### Verification Discipline
Each story phase must end with:
- a verification task against `ux_reference.md` interpreted as the API caller, CLI operator, or Svelte UX interaction contract
- a verification task against `ux_reference.md` interpreted as the operator/caller interaction contract
- a semantic audit / verification task tied to repository validators and touched contracts
Typical verification tasks may include:
- focused `pytest backend/tests/test_<module>.py` commands
- `cd backend && pytest` (full backend suite)
- `cd frontend && npm run test` (vitest suite)
- `ruff check backend/` (Python lint)
- `cd frontend && npm run build` (Svelte build validation)
- `python3 scripts/static_verify.py` (semantic static verification)
- `cd backend && source .venv/bin/activate && python -m pytest backend/tests/test_*.py -v`
- `python -m ruff check backend/src/ backend/tests/`
- `cd frontend && npm run test`
- `cd frontend && npm run build`
Only include the commands that are truly required by the feature scope.
@@ -128,20 +111,16 @@ Only include the commands that are truly required by the feature scope.
If a task implements or depends on a guarded contract, append a concise guardrail summary derived from `@RATIONALE` and `@REJECTED`.
Examples:
- `- [ ] T021 [US1] Implement report generation endpoint in backend/src/api/reports.py (RATIONALE: unified report envelope preserves task-shaped parity; REJECTED: ad-hoc per-endpoint response shapes)`
- `- [ ] T033 [US2] Add WebSocket logging handler in backend/src/core/task_manager/ws_handler.py (RATIONALE: C4/C5 flows must expose real-time log streaming; REJECTED: polling-based log retrieval)`
- `- [ ] T040 [US3] Create DashboardCard component in frontend/src/lib/components/DashboardCard.svelte (RATIONALE: @UX_STATE must cover Idle/Loading/Error/Empty; REJECTED: single-state inline rendering without recovery)`
- `- [ ] T021 [US1] Implement dashboard migration service in backend/src/core/migration/service.py (RATIONALE: full scan ensures consistency; REJECTED: incremental-only update leaves stale entries)`
- `- [ ] T033 [US2] Add WebSocket event handler in frontend/src/lib/stores/taskDrawer.js (RATIONALE: real-time feedback prevents polling; REJECTED: interval polling for task status)`
If no safe executable task wording exists because the accepted path is still unclear, stop and emit `[NEED_CONTEXT: target]`.
### Test Tasks
Tests are optional only when the feature truly has no new verification surface. In this repository, test tasks are usually expected for:
- new FastAPI endpoints / WebSocket handlers
- new plugin or service modules
- new Svelte components with `@UX_STATE` contracts
Tests are optional only when the feature truly has no new verification surface. Test tasks are usually expected for:
- new API endpoints
- new database models or queries
- C4/C5 semantic contracts
- runtime evidence / belief-state behavior
- rejected-path regression coverage
@@ -149,8 +128,7 @@ Tests are optional only when the feature truly has no new verification surface.
### Decision-Memory Validation Gate
Before finalizing `tasks.md`, verify that:
- blocking ADRs are inherited into setup/foundational or downstream story tasks
- no task text schedules a rejected path
- story tasks remain executable within the actual Python/Svelte repository structure
- story tasks remain executable within the actual Python/Svelte project structure
- at least one explicit verification task protects against rejected-path regression

63
.opencode/command/speckit.test.md
View File

@@ -1,5 +1,5 @@
---
description: Execute semantic audit and Python/Svelte-native testing for the active feature batch.
description: Execute semantic audit and native testing for the active ss-tools feature batch (pytest + vitest).
---
## User Input
@@ -12,23 +12,20 @@ You **MUST** consider the user input before proceeding (if not empty).
## Goal
Run the verification loop for the touched Python/Svelte scope: semantic audit, decision-memory audit, executable tests (pytest + vitest), logic review, and documentation of coverage/results.
Run the verification loop for the touched ss-tools scope: semantic audit, decision-memory audit, executable tests, logic review, and documentation of coverage/results.
## Operating Constraints
1. **NEVER delete existing tests** unless the user explicitly requests removal.
2. **NEVER duplicate tests** when existing `backend/tests/` or `frontend/tests/` coverage already validates the same contract.
2. **NEVER duplicate tests** when existing test coverage already validates the same contract.
3. **Decision-memory regression guard**: tests and audits must not silently normalize any path documented as rejected.
4. **Python/Svelte-native structure**: prefer existing test organization:
- Backend: `backend/tests/` with pytest
- Frontend: `frontend/tests/` or co-located `__tests__/` with vitest + @testing-library/svelte
4. **Project-native structure**: prefer existing test organization — `backend/tests/` for Python, `frontend/src/lib/**/__tests__/` for Svelte.
## Execution Steps
### 1. Analyze Context
Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` and determine:
- `FEATURE_DIR`
- touched implementation tasks from `tasks.md`
- affected `.py` and `.svelte` files
@@ -39,14 +36,12 @@ All test documentation emitted by this workflow belongs under `FEATURE_DIR/tests
### 2. Load Relevant Artifacts
Load only the necessary portions of:
- `tasks.md`
- `plan.md`
- `contracts/modules.md` when present
- `quickstart.md` when present
- `.specify/memory/constitution.md`
- `README.md`
- `docs/SEMANTIC_PROTOCOL_COMPLIANCE.md`
- relevant `docs/adr/*.md`
### 3. Coverage Matrix
@@ -59,57 +54,48 @@ Build a compact matrix:
### 4. Semantic Audit and Logic Review
Before writing or executing tests, perform a semantic audit of the touched scope:
1. Use the AXIOM semantic validation path where available.
2. Reject malformed or pseudo-semantic markup.
3. Verify contract density matches effective complexity.
4. For C4/C5 Python flows: verify belief runtime markers (`belief_scope`, `reason`, `reflect`, `explore`).
5. For C4/C5 Svelte components: verify `@UX_STATE`, `@UX_FEEDBACK`, `@UX_RECOVERY`, `@UX_REACTIVITY` coverage.
6. Verify no touched code silently restores an ADR- or contract-rejected path.
7. Emulate the algorithm mentally to ensure `@PRE`, `@POST`, `@INVARIANT`, and declared side effects remain coherent.
1. Reject malformed or pseudo-semantic markup.
2. Verify contract density matches effective complexity.
3. Verify C4/C5 Python flows account for belief runtime markers (`reason`, `reflect`, `explore` with JSON structured logging).
4. Verify C4/C5 Svelte components account for console markers (`[ComponentID][MARKER]`).
5. Verify no touched code silently restores an ADR- or contract-rejected path.
6. Emulate the algorithm mentally to ensure `@PRE`, `@POST`, `@INVARIANT`, and declared side effects remain coherent.
If audit fails, emit `[AUDIT_FAIL: semantic_noncompliance | contract_mismatch | logic_mismatch | rejected_path_regression]` with concrete file-based reasons.
### 5. Test Writing / Updating
When test additions are needed:
- Python: prefer `backend/tests/test_*.py` with pytest
- Svelte: prefer `__tests__/*.test.js` with vitest + @testing-library/svelte
- use deterministic fixtures rather than logic mirrors
- trace tests back to semantic contracts and ADR guardrails
- add explicit rejected-path regression coverage when the touched scope has a forbidden alternative
- Backend: prefer `backend/tests/` with pytest fixtures, use `unittest.mock` / `pytest-mock` for external dependencies
- Frontend: prefer vitest with `@testing-library/svelte` for component testing, `jsdom` environment
- Use deterministic fixtures rather than logic mirrors
- Trace tests back to semantic contracts and ADR guardrails
- Add explicit rejected-path regression coverage when the touched scope has a forbidden alternative
- For Svelte UX contracts, validate `@UX_STATE` transitions, `@UX_FEEDBACK` messages, and `@UX_RECOVERY` paths
For non-UI backend features, UX verification means validating API envelopes, error responses, and recovery messaging promised by `ux_reference.md`.
For UI features, use browser validation via `chrome-devtools` MCP.
### 6. Execute Verifiers
Run the smallest truthful verifier set for the touched scope, typically chosen from:
Run the smallest truthful verifier set for the touched scope:
```bash
# Backend tests
cd backend && pytest
# Backend
cd backend && source .venv/bin/activate && python -m pytest -v
python -m ruff check backend/src/ backend/tests/
# Backend lint
ruff check backend/
# Frontend tests
# Frontend
cd frontend && npm run test
# Frontend build check (catches Svelte compilation errors)
cd frontend && npm run build
# Semantic static verification (when available)
python3 scripts/static_verify.py
npm run build
```
Use narrower test runs when they are sufficient (e.g., `pytest backend/tests/test_auth.py`) and then widen verification when finalizing the feature batch.
Use narrower test runs when sufficient, then widen verification when finalizing.
### 7. Test Documentation
Create or update `specs/<feature>/tests/` documentation using `.specify/templates/test-docs-template.md`.
Document:
- coverage summary
- semantic audit verdict
- commands run
@@ -123,7 +109,6 @@ Mark test tasks complete only after semantic audit and executable verification s
## Output
Produce a Markdown test report containing:
- coverage summary
- commands executed
- semantic audit verdict