opensddrag 0.1.2 → 0.2.0

package/src/templates/skills/spec.js

@@ -0,0 +1,94 @@
+import { harnessChecklistBlock } from "./_shared.js";
+
+export const specSkill = {
+  name: "opensddrag-spec",
+  description:
+    "Write capability specs with SHALL/MUST requirements and WHEN/THEN scenarios",
+  body: (slug, note) => `# OpenSddRag — Spec
+${note}## When to use
+After a proposal exists, to formalize each capability into a spec artifact with SHALL/MUST
+requirements and WHEN/THEN scenarios. Each capability in the proposal gets its own spec.
+
+## Inputs
+$ARGUMENTS = change name. If not provided, list proposals and ask which one.
+
+## Workflow
+
+### Step 1 — Read the proposal
+\`list_artifacts(type="proposal", project_slug="${slug}")\`
+\`read_artifact(name="<change-name>-proposal", project_slug="${slug}")\`
+
+### Step 2 — Identify capabilities
+Parse "## Capabilities". Every capability in "New Capabilities" and "Modified Capabilities" needs a spec.
+- **New capability** → full spec (Purpose + Requirements + Scenarios).
+- **Modified capability** → check for an existing main spec: \`search_semantic(query="<capability> spec", project_slug="${slug}", limit=3)\`.
+  - If a main spec exists → create a DELTA spec (ADDED/MODIFIED/REMOVED/RENAMED).
+  - If no main spec → create BOTH the main spec (is_delta=false) and the delta spec (is_delta=true).
+
+### Step 3 — Write spec content for each capability
+
+Full spec structure (new capabilities):
+\`\`\`markdown
+# <capability> Specification
+
+## Purpose
+[High-level description]
+
+## Requirements
+
+### Requirement: REQ-001 <Name>
+[Description using SHALL/MUST language]
+
+#### Scenario: <Happy path>
+- **WHEN** [condition]
+- **THEN** [expected outcome]
+
+#### Scenario: <Edge case>
+- **WHEN** [edge condition]
+- **THEN** [expected outcome]
+\`\`\`
+
+Delta spec structure (modified capabilities):
+\`\`\`markdown
+# <capability> Specification — Delta
+
+## ADDED Requirements
+### Requirement: <New name>
+[Full requirement with scenarios]
+
+## MODIFIED Requirements
+### Requirement: <Existing name>
+[Full updated text with all scenarios]
+
+## REMOVED Requirements
+### Requirement: <Removed name>
+**Reason:** [why] · **Migration:** [how consumers migrate]
+
+## RENAMED Requirements
+- FROM: \`### Requirement: Old Name\`
+- TO: \`### Requirement: New Name\`
+\`\`\`
+
+### Step 4 — Save each spec
+\`create_artifact(name="<change-name>-<capability>-spec", type="spec", content="<full spec markdown>", metadata={"change_name": "<change-name>", "capability": "<capability>", "is_delta": true|false}, project_slug="${slug}")\`
+
+### Step 5 — Link each spec to the proposal
+\`link_artifacts(source_name="<spec>", target_name="<change-name>-proposal", relationship_type="implements", project_slug="${slug}")\`
+
+### Step 6 — Validate each spec
+\`validate_artifact(name="<spec>", project_slug="${slug}")\` — fix any validation errors before continuing.
+
+${harnessChecklistBlock(slug, "on_spec", "Saving specs to the database")}
+### Step 7 — Record the action
+\`record_trace(action="spec", result_summary="Created specs for: <capability-list>", project_slug="${slug}")\`
+
+## Output
+- One spec artifact per capability (full and/or delta) linked to the proposal.
+- **Unlocks:** /opsr:design once all capabilities have specs.
+
+## Important rules
+- Every requirement MUST have at least one WHEN/THEN scenario.
+- Delta specs MUST carry metadata.is_delta=true so /opsr:sync can merge them later.
+- Run the harness checklist (on_spec) before declaring specs done.
+`,
+};

package/src/templates/skills/status.js

@@ -0,0 +1,66 @@
+export const statusSkill = {
+  name: "opensddrag-status",
+  description: "Show current state of all in-progress changes",
+  body: (slug, note) => `# OpenSddRag — Status
+${note}## When to use
+To show the current state of all in-progress changes for this project: artifact completion,
+task progress, and recent activity. Reads from the MCP server — no local files involved.
+
+## Inputs
+$ARGUMENTS = optional change name to show details for a single change. If absent, show all.
+
+## Workflow
+
+### Step 1 — Load working context
+\`get_working_context(project_slug="${slug}")\`
+This also surfaces any \`trigger="always"\` harness rules — read them first.
+
+### Step 2 — List artifacts by type and status
+\`list_artifacts(type="proposal", status="active", project_slug="${slug}")\`
+\`list_artifacts(type="proposal", status="draft", project_slug="${slug}")\`
+\`list_artifacts(type="spec", status="active", project_slug="${slug}")\`
+\`list_artifacts(type="design", status="active", project_slug="${slug}")\`
+\`list_artifacts(type="task", status="active", project_slug="${slug}")\`
+\`list_artifacts(type="task", status="draft", project_slug="${slug}")\`
+
+### Step 3 — Recall recent activity
+\`recall_episodes(query="recent actions in this project", project_slug="${slug}", limit=5)\`
+
+### Step 4 — Present a structured status
+For each active change, show:
+\`\`\`
+## Change: <change-name>
+| Artifact | Status |
+|----------|--------|
+| Proposal | ✓ done |
+| Specs    | ✓ 2/2  |
+| Design   | ✓ done |
+| Tasks    | 3/5 done |
+
+Current task: <task-name>
+Next step: /opsr:apply <change-name>
+\`\`\`
+Then show recent activity (last 5 episodes) and a suggested next command based on the state.
+
+### Step 5 — Suggest the next command
+Map the change's state to the next action:
+- proposal only → /opsr:spec
+- specs but no design → /opsr:design
+- design but no tasks → /opsr:tasks
+- tasks with drafts remaining → /opsr:apply
+- all tasks archived → /opsr:verify then /opsr:archive
+
+## Reading the working context
+\`get_working_context\` returns \`current_task\` and the ordered \`tasks\` list — use them to compute
+"N/M done" and to name the in-flight task. It also returns always-trigger harness rules; show
+those at the top so the user starts every session aware of the project's constraints.
+
+## Output
+- A per-change status table, recent activity, and the recommended next command.
+
+## Important rules
+- Read-only — never modify artifacts from status.
+- If a specific change is requested, scope all lists to that change via metadata.change_name.
+- Always surface always-trigger harness rules from the working context.
+`,
+};

package/src/templates/skills/sync.js

@@ -0,0 +1,65 @@
+export const syncSkill = {
+  name: "opensddrag-sync",
+  description: "Merge delta specs back into main capability specs",
+  body: (slug, note) => `# OpenSddRag — Sync
+${note}## When to use
+To merge delta specs (ADDED/MODIFIED/REMOVED/RENAMED) into the main specs stored in the database.
+Delta specs are created by /opsr:spec for MODIFIED capabilities. Runs automatically during /opsr:archive.
+
+## Inputs
+$ARGUMENTS = change name.
+
+## Workflow
+
+### Step 1 — Find delta specs for this change
+\`list_artifacts(type="spec", project_slug="${slug}")\`
+Filter where metadata.change_name = "<change-name>" AND metadata.is_delta = true.
+
+### Step 2 — For each delta, find the main spec
+\`search_semantic(query="<capability> spec", project_slug="${slug}", limit=5)\`
+Find the spec for the same capability where metadata.is_delta = false (or unset).
+
+### Step 3 — Apply delta operations to the main spec
+\`read_artifact(name="<delta-spec>", project_slug="${slug}")\`
+\`read_artifact(name="<main-spec>", project_slug="${slug}")\`
+Apply each delta section:
+- **## ADDED Requirements** → confirm the requirement does NOT exist, then append it (with scenarios).
+- **## MODIFIED Requirements** → find by name and apply ONLY the changed parts (partial update, not wholesale replace).
+- **## REMOVED Requirements** → remove the requirement block; note the Reason/Migration in a comment.
+- **## RENAMED Requirements** → change the heading FROM the old name TO the new name.
+
+### Step 4 — Save the updated main spec
+\`update_artifact(name="<main-spec>", content="<merged spec content>", project_slug="${slug}")\`
+
+### Step 5 — Archive the delta spec
+\`update_artifact(name="<delta-spec>", status="archived", metadata={"synced_at": "<ISO timestamp>", "merged_into": "<main-spec>"}, project_slug="${slug}")\`
+
+### Step 6 — Record the sync
+\`record_trace(action="sync", result_summary="Synced delta for capability: <capability> into main spec", project_slug="${slug}")\`
+Tell the user which capabilities were updated.
+
+## Worked example — a MODIFIED merge
+Delta says:
+\`\`\`markdown
+## MODIFIED Requirements
+### Requirement: REQ-002 Token issuance
+[adds a new scenario for refresh tokens]
+\`\`\`
+Main spec already has REQ-002 with two scenarios. Correct merge = keep the existing two scenarios
+and APPEND the new refresh-token scenario under the same requirement heading. Do NOT replace the
+whole REQ-002 block — that would silently drop the original scenarios.
+
+## When NOT to sync
+- The delta is still being edited (run /opsr:spec to completion first).
+- No main spec exists yet for the capability — then there is nothing to merge into; the delta
+  IS the spec until a main is created.
+
+## Output
+- Main spec artifacts updated to reflect all deltas; delta specs archived with a merge pointer.
+
+## Important rules
+- MODIFIED requirements get partial, intelligent merges — never blind whole-section replacement.
+- Always archive the delta after merging so it is not re-applied.
+- Preserve REMOVED requirements' Reason/Migration as a note for future readers.
+`,
+};

package/src/templates/skills/tasks.js

@@ -0,0 +1,70 @@
+export const tasksSkill = {
+  name: "opensddrag-tasks",
+  description: "Break a design into atomic, verifiable implementation tasks",
+  body: (slug, note) => `# OpenSddRag — Tasks
+${note}## When to use
+After the design exists, to decompose specs + design into atomic, verifiable task artifacts.
+Each task maps to one or more spec requirements (REQ-NNN) and is completable in under 4 hours.
+
+## Inputs
+$ARGUMENTS = change name.
+
+## Workflow
+
+### Step 1 — Read all planning artifacts
+\`read_artifact(name="<change-name>-proposal", project_slug="${slug}")\`
+\`read_artifact(name="<change-name>-design", project_slug="${slug}")\`
+\`get_relationships(name="<change-name>-proposal", project_slug="${slug}")\`
+Read each linked spec artifact.
+
+### Step 2 — Plan task groups
+Group tasks by logical phase. Each task MUST have:
+- A clear **Goal** (what it accomplishes).
+- **Acceptance criteria** referencing spec REQ-NNN items (not vague).
+- **Dependencies** on other tasks (if any).
+- Estimated effort: < 4 hours.
+
+### Step 3 — Create each task artifact
+Name each as \`<change-name>-task-<group>-<N>\`:
+\`create_artifact(name="<change-name>-task-<group>-<N>", type="task", content="## Goal\\n<what this task accomplishes>\\n\\n## Acceptance Criteria\\n- [ ] REQ-NNN: <criterion>\\n- [ ] <criterion>\\n\\n## Dependencies\\n- <other task name or 'none'>", metadata={"change_name": "<change-name>", "group": "<group>", "order": <N>}, project_slug="${slug}")\`
+
+### Step 4 — Link each task to its spec(s)
+\`link_artifacts(source_name="<task-name>", target_name="<spec-name>", relationship_type="implements", project_slug="${slug}")\`
+
+### Step 5 — Update working context with the task list
+\`update_working_context(context={"change_name": "<change-name>", "tasks": ["<task-1>", "<task-2>", "..."], "current_task": null}, project_slug="${slug}")\`
+
+### Step 6 — Record and show next steps
+\`record_trace(action="tasks", result_summary="Created <N> tasks for <change-name>", project_slug="${slug}")\`
+Show the full task list with names and goals, then tell the user:
+"Tasks saved. Run /opsr:apply <change-name> to start implementing."
+
+## Example task artifact
+\`\`\`markdown
+## Goal
+Add a POST /sessions endpoint that issues a JWT for valid credentials.
+
+## Acceptance Criteria
+- [ ] REQ-002: Endpoint returns 200 + token for valid credentials
+- [ ] REQ-003: Endpoint returns 401 for invalid credentials
+- [ ] Unit tests cover both scenarios
+
+## Dependencies
+- <change>-task-db-1 (users table migration)
+\`\`\`
+
+Ordering tip: number tasks within a group (\`-task-<group>-<N>\`) so /opsr:apply can walk them
+in dependency order. Put migrations and shared scaffolding first, feature work next, tests last
+(or alongside, if the team writes tests with the code).
+
+## Output
+- One task artifact per unit of work, each linked to its spec(s).
+- Working context updated with the ordered task list.
+- **Unlocks:** /opsr:apply.
+
+## Important rules
+- Acceptance criteria MUST reference concrete REQ-NNN items — never "implement the feature".
+- Keep each task < 4 hours; split anything larger.
+- Tasks are individual database artifacts — NOT a single markdown checklist file.
+`,
+};

package/src/templates/skills/verify.js

@@ -0,0 +1,74 @@
+import { harnessChecklistBlock } from "./_shared.js";
+
+export const verifySkill = {
+  name: "opensddrag-verify",
+  description:
+    "Validate implementation against spec requirements and design decisions",
+  body: (slug, note) => `# OpenSddRag — Verify
+${note}## When to use
+After all tasks are implemented, to validate the implementation against spec requirements and
+design decisions. Read-only — produces a structured report and modifies no artifacts.
+
+## Inputs
+$ARGUMENTS = change name.
+
+## Workflow
+
+### Step 1 — Load all artifacts
+\`read_artifact(name="<change-name>-proposal", project_slug="${slug}")\`
+\`read_artifact(name="<change-name>-design", project_slug="${slug}")\`
+\`get_relationships(name="<change-name>-proposal", project_slug="${slug}")\`
+Read each linked spec and task artifact.
+
+### Step 2 — Verify COMPLETENESS
+\`list_artifacts(type="task", status="draft", project_slug="${slug}")\`
+- If pending tasks exist → **CRITICAL: Tasks not complete**.
+Extract every REQ-NNN from the specs and search the codebase for implementation evidence.
+- If a requirement has no evidence → **CRITICAL: Requirement not implemented**.
+
+### Step 3 — Verify CORRECTNESS
+For each spec scenario (WHEN/THEN), search for test coverage or implementation of the condition.
+- If a scenario has no coverage → **WARNING: Scenario not covered**.
+
+### Step 4 — Verify COHERENCE
+Extract decisions from the design's "## Decisions" section. For each:
+- Check the implementation follows the chosen approach.
+- If it deviates → **SUGGESTION: Possible deviation from design**.
+
+${harnessChecklistBlock(slug, "on_verify", "Declaring verification complete")}
+### Step 5 — Generate the report
+\`\`\`
+## Verification Report: <change-name>
+
+### Summary
+| Dimension    | Status |
+|--------------|--------|
+| Completeness | ✓/✗   |
+| Correctness  | ✓/✗   |
+| Coherence    | ✓/✗   |
+
+### CRITICAL Issues
+- [Issue]
+
+### WARNING Issues
+- [Issue]
+
+### SUGGESTIONS
+- [Issue]
+
+### Assessment
+[READY TO ARCHIVE | ISSUES MUST BE FIXED BEFORE ARCHIVING]
+\`\`\`
+
+### Step 6 — Record the verification
+\`record_trace(action="verify", result_summary="Verification: <PASS/FAIL> — <N> critical, <N> warnings", project_slug="${slug}")\`
+
+## Output
+- A structured verification report (CRITICAL / WARNING / SUGGESTION). No artifacts are modified.
+
+## Important rules
+- This phase is READ-ONLY for artifacts — never change task or spec status here.
+- Run the harness checklist (on_verify) before declaring verification complete.
+- A change is not ready to archive while any CRITICAL issue remains.
+`,
+};