opensddrag 0.1.2 → 0.2.2

package/src/templates/skills/_shared.js

@@ -0,0 +1,35 @@
+/**
+ * Shared helpers for OpenSddRag skill templates.
+ *
+ * Each skill lives in its own module (propose.js, spec.js, …) and exports an
+ * object: { name, description, body(slug, note) }. The aggregator in index.js
+ * wraps `body` with the Claude Code or OpenCode header (`note`) and the YAML
+ * frontmatter, so the workflow is authored exactly once and the CC/OC pair is
+ * always in sync (command-skill-separation-contract REQ-001).
+ */
+
+/**
+ * Renders the reusable harness phase-gate checklist block, inlined into the
+ * spec/apply/verify/archive skills at the point just before the phase gate.
+ * Mirrors the legacy harnessChecklistStep() that used to live in the command
+ * templates.
+ */
+export function harnessChecklistBlock(slug, trigger, gateLabel) {
+  return `### Step — Harness checklist (${trigger})
+Call the MCP tool to load all enabled harness rules for the \`${trigger}\` trigger:
+\`get_harness_checklist(trigger="${trigger}", project_slug="${slug}")\`
+
+Process the response:
+- **If the result is an empty array \`[]\`** → output "No harness rules for this trigger." and continue.
+- **If any rule has \`severity="error"\`** → present it as:
+  \`\`\`
+  MUST complete before proceeding (${gateLabel}):
+  - [<name>] <instruction>
+  \`\`\`
+  Then \`STOP\` and wait until each error-severity rule is confirmed satisfied before continuing.
+- **If any rule has \`severity="warning"\`** → present it as "SHOULD complete: [<name>] <instruction>" (advisory; proceed if satisfied).
+- **If any rule has \`severity="info"\`** → present inline as "Info: [<name>] <instruction>" and proceed.
+- Rules are returned sorted error-first then by name; preserve that order when displaying.
+- This step MUST run BEFORE ${gateLabel.toLowerCase()}.
+`;
+}

package/src/templates/skills/apply.js

@@ -0,0 +1,73 @@
+import { harnessChecklistBlock } from "./_shared.js";
+
+export const applySkill = {
+  name: "opensddrag-apply",
+  description:
+    "Implement the next pending task against spec acceptance criteria",
+  body: (slug, note) => `# OpenSddRag — Apply
+${note}## When to use
+To implement tasks one at a time, validating each against its spec acceptance criteria before
+marking it done. Read the design (and, per task, the spec it implements) as context — the
+proposal is not re-read during apply, since the design already encodes its decisions.
+
+## Inputs
+$ARGUMENTS = change name, or a specific task name.
+
+## Workflow
+
+### Step 1 — Load implementation context
+1. Load the working context:
+   \`get_working_context(project_slug="${slug}")\`
+2. Fetch the list of all artifacts to serve as the freshness oracle:
+   \`list_artifacts(project_slug="${slug}")\`
+3. Retrieve the change's design content (\`<change-name>-design\`):
+   - Locate the design artifact in the \`list_artifacts\` results to get its \`id\` and \`updated_at\`.
+   - If no design exists, output "Design missing for change '<change-name>'. Run /opsr:design before /opsr:apply." and STOP.
+   - Look up the design's \`id\` in the working context's \`context.content_cache\` (if present):
+     - **CACHE HIT:** If the cache entry exists and its \`updated_at\` matches the oracle's \`updated_at\`, use the cached design content. Do not call \`read_artifact\`.
+     - **CACHE MISS/STALE:** If the cache entry is missing or its \`updated_at\` does not match, call \`read_artifact(name="<change-name>-design", project_slug="${slug}")\`. Then, update the working context cache by calling \`update_working_context\` with \`context.content_cache[<artifact_id>] = {type: "design", content: "<content>", updated_at: "<updated_at>"}\`.
+4. Do NOT read the proposal during apply — its rationale is already captured in the design.
+5. Read the specific spec a task implements pointwise at validation time (Step 6) using the same caching logic (check cache, hit → use, miss/stale → read and cache). Tasks themselves are never cached.
+
+### Step 2 — List pending tasks
+\`list_artifacts(type="task", status="active", project_slug="${slug}")\`
+\`list_artifacts(type="task", status="draft", project_slug="${slug}")\`
+Combine both; filter by metadata.change_name. Prioritize \`active\` (resuming) then \`draft\` in dependency order.
+
+### Step 3 — Select the next task
+If $ARGUMENTS names a task, use it. Otherwise:
+1. Prefer any task with status="active" (interrupted session).
+2. Else pick the first draft task whose dependencies are all archived.
+\`read_artifact(name="<task-name>", project_slug="${slug}")\`
+
+### Step 4 — Mark the task active
+\`update_artifact(name="<task-name>", status="active", project_slug="${slug}")\`
+\`update_working_context(context={"current_task": "<task-name>"}, project_slug="${slug}")\`
+
+### Step 5 — Implement the task
+Write the code changes required by the task using Edit/Write/Bash (local files — this is expected).
+The implementation MUST satisfy every acceptance criterion. Pause and ask if anything is unclear — do not guess.
+
+### Step 6 — Validate against spec requirements
+For each acceptance criterion (REQ-NNN): confirm the implementation satisfies it and no spec scenario is broken.
+
+${harnessChecklistBlock(slug, "on_apply", "Marking the task archived")}
+### Step 7 — Mark the task done
+\`update_artifact(name="<task-name>", status="archived", project_slug="${slug}")\`
+
+### Step 8 — Record and check remaining work
+\`record_trace(action="apply_task", result_summary="Completed task: <task-name>", artifact_id="<artifact-id>", project_slug="${slug}")\`
+\`list_artifacts(type="task", status="draft", project_slug="${slug}")\`
+- If tasks remain: "Task complete. Run /opsr:apply <change-name> for the next task."
+- If all done: "All tasks complete. Run /opsr:verify <change-name>, then /opsr:archive <change-name>."
+
+## Output
+- Code changes on disk satisfying the task's acceptance criteria.
+- Task status advanced draft → active → archived in the database.
+
+## Important rules
+- Read the design and the task's spec before implementing — never code from the task alone. Do not re-read the proposal during apply.
+- Run the harness checklist (on_apply) BEFORE marking a task archived; STOP on any error-severity rule.
+- One task at a time; do not batch-archive tasks.
+`,
+};

package/src/templates/skills/archive.js

@@ -0,0 +1,52 @@
+import { harnessChecklistBlock } from "./_shared.js";
+
+export const archiveSkill = {
+  name: "opensddrag-archive",
+  description: "Finalize a completed change by archiving all its artifacts",
+  body: (slug, note) => `# OpenSddRag — Archive
+${note}## When to use
+To finalize a completed change: run completion checks, sync delta specs into main specs, then
+archive all the change's artifacts.
+
+## Inputs
+$ARGUMENTS = change name. If not provided, list active changes and ask.
+
+## Workflow
+
+### Step 1 — Load the change bundle
+\`read_change_bundle(change_name="<change-name>", project_slug="${slug}")\`
+Archiving sweeps every artifact of the change, so load them all in one call. The
+response carries the proposal, design, specs, and the task list
+(\`tasks[] = {name, status}\`) with \`task_count\`. Proceed to Step 2.
+
+### Step 2 — Validate artifact completion
+From the bundle's \`tasks[]\`, treat any task whose \`status\` is not \`archived\` as pending.
+If pending tasks exist → warn the user and ask for confirmation to archive anyway.
+
+### Step 3 — Validate task completion
+Count pending vs archived tasks from the bundle. If any non-archived tasks remain → warn and confirm.
+
+### Step 4 — Check for delta specs that need syncing
+From the bundle's \`specs[]\`, filter for metadata.change_name = "<change-name>" AND metadata.is_delta = true.
+If deltas exist: show the affected capabilities and ask "Sync delta specs to main specs now? (recommended)".
+- If yes → run the /opsr:sync workflow (load the opensddrag-sync skill) for each delta.
+- If no → archive without syncing.
+
+${harnessChecklistBlock(slug, "on_archive", "Archiving change artifacts")}
+### Step 5 — Archive all change artifacts
+For each artifact (proposal, all specs, design, all tasks):
+\`update_artifact(name="<artifact>", status="archived", metadata={"archived_at": "<ISO timestamp>", "change_name": "<change-name>"}, project_slug="${slug}")\`
+
+### Step 6 — Record and show a summary
+\`record_trace(action="archive", result_summary="Archived change: <change-name> (<N> artifacts)", project_slug="${slug}")\`
+Show: artifacts archived, specs synced (if any), and "Change <change-name> is complete."
+
+## Output
+- Every artifact of the change set to status=archived; deltas merged into main specs.
+
+## Important rules
+- Run the harness checklist (on_archive) BEFORE archiving; STOP on any error-severity rule.
+- Never archive over pending tasks without explicit user confirmation.
+- Sync delta specs before archiving so the main specs stay authoritative.
+`,
+};

package/src/templates/skills/continue.js

@@ -0,0 +1,63 @@
+export const continueSkill = {
+  name: "opensddrag-continue",
+  description: "Create the next single artifact in the SDD dependency chain",
+  body: (slug, note) => `# OpenSddRag — Continue
+${note}## When to use
+To create the NEXT SINGLE artifact in the dependency chain for a change and then stop. Unlike
+/opsr:flow (which creates everything), this advances exactly one step per invocation.
+
+Dependency order: proposal → specs → design → tasks.
+
+## Inputs
+$ARGUMENTS = change name.
+
+## Workflow
+
+### Step 1 — Get the current status
+\`list_artifacts(type="proposal", project_slug="${slug}")\`
+\`get_relationships(name="<change-name>-proposal", project_slug="${slug}")\`
+Gather all existing artifacts for this change.
+
+### Step 2 — Find the next artifact to create
+Walk the dependency order and find the first gap:
+1. proposal → if missing, stop and tell the user to run /opsr:propose first.
+2. specs → if any capability has no spec → the next artifact is ONE spec.
+3. design → if missing and all specs exist → the next artifact is the design.
+4. tasks → if missing and the design exists → the next artifacts are the tasks.
+
+If every artifact already exists → tell the user "All planning artifacts complete. Run /opsr:apply."
+
+### Step 3 — Create the NEXT artifact only, by delegating to the matching skill
+Do NOT inline the workflow here — load the corresponding skill and follow it for a single artifact:
+- next = spec → load the \`opensddrag-spec\` skill and create ONE capability's spec.
+- next = design → load the \`opensddrag-design\` skill and create the design.
+- next = tasks → load the \`opensddrag-tasks\` skill and create the tasks.
+Then STOP — do not proceed to the following artifact in this invocation.
+
+### Step 4 — Show progress
+- Show what was created.
+- Show what is now unlocked (next in the dependency chain).
+- Suggest: "Run /opsr:continue <change-name> to create the next artifact."
+
+## Worked example
+Given a change with a proposal and 2 of 3 capabilities specced:
+1. Step 2 detects the gap: one capability still has no spec.
+2. Step 3 loads \`opensddrag-spec\` and creates ONLY that capability's spec, then stops.
+3. Step 4 reports "spec created (3/3). Next: design. Run /opsr:continue <change-name>."
+
+Next invocation detects all specs exist but no design → creates the design and stops. And so on
+until tasks exist, at which point it directs the user to /opsr:apply.
+
+## Why one step at a time
+/opsr:continue is for reviewing each artifact before the next is generated. When you want the
+whole chain produced in one pass without pausing, use /opsr:flow instead.
+
+## Output
+- Exactly one new artifact (or one batch of tasks), advancing the change by a single step.
+
+## Important rules
+- Create ONE artifact (or the single tasks batch) per invocation, then stop.
+- Delegate the actual artifact creation to the matching skill — never duplicate its steps here.
+- Respect dependency order; never skip a missing upstream artifact.
+`,
+};

package/src/templates/skills/design.js

@@ -0,0 +1,82 @@
+export const designSkill = {
+  name: "opensddrag-design",
+  description:
+    "Document technical decisions, architecture, and trade-offs for a change",
+  body: (slug, note) => `# OpenSddRag — Design
+${note}## When to use
+After the specs exist, to capture the technical decisions, architecture, trade-offs, and open
+questions for a change. The design is grounded in the proposal and spec artifacts already saved.
+
+## Inputs
+$ARGUMENTS = change name.
+
+## Workflow
+
+### Step 1 — Read proposal and all specs
+\`read_artifact(name="<change-name>-proposal", project_slug="${slug}")\`
+\`list_artifacts(type="spec", project_slug="${slug}")\`
+\`get_relationships(name="<change-name>-proposal", project_slug="${slug}")\`
+Read each spec linked to this change.
+
+### Step 2 — Search for related prior designs
+\`search_semantic(query="<change topic> design decisions", project_slug="${slug}", limit=3)\`
+Use findings as context — do not duplicate prior work.
+
+### Step 3 — Write the design content
+\`\`\`markdown
+# Design: <change-name>
+
+## Context
+[Background, current state, constraints that shaped this design]
+
+## Goals / Non-Goals
+**Goals:**
+- [What this design achieves]
+
+**Non-Goals:**
+- [What this design deliberately does NOT address]
+
+## Decisions
+
+### Decision: <Title>
+**Chosen:** [What was chosen and why]
+**Alternatives considered:**
+- [Alternative 1] — rejected because [reason]
+- [Alternative 2] — rejected because [reason]
+
+## Architecture
+[Components, data flow, integration points — ASCII diagrams if helpful]
+
+## Risks / Trade-offs
+| Risk | Mitigation |
+|------|------------|
+| [Risk] | [Mitigation] |
+
+## Migration Plan
+[Deployment steps, backward compatibility, rollback plan]
+
+## Open Questions
+- [ ] [Question that still needs resolution]
+\`\`\`
+
+### Step 4 — Save the design
+\`create_artifact(name="<change-name>-design", type="design", content="<full design markdown>", metadata={"change_name": "<change-name>"}, project_slug="${slug}")\`
+If a draft design skeleton already exists, use \`update_artifact\` instead of creating a duplicate.
+
+### Step 5 — Link the design to the proposal
+\`link_artifacts(source_name="<change-name>-design", target_name="<change-name>-proposal", relationship_type="depends_on", project_slug="${slug}")\`
+
+### Step 6 — Record and show next steps
+\`record_trace(action="design", result_summary="Created design: <change-name>-design", project_slug="${slug}")\`
+Tell the user: "Design saved. Run /opsr:tasks <change-name> to decompose into tasks."
+
+## Output
+- A \`<change-name>-design\` artifact linked to the proposal.
+- **Unlocks:** /opsr:tasks.
+
+## Important rules
+- Every Decision MUST list the chosen approach AND the alternatives considered with reasons.
+- DO NOT write application code — this phase is design only.
+- If a design already exists, amend it (update_artifact) rather than creating a second one.
+`,
+};

package/src/templates/skills/explore.js

@@ -0,0 +1,62 @@
+export const exploreSkill = {
+  name: "opensddrag-explore",
+  description: "Investigate a problem or idea without writing any code",
+  body: (slug, note) => `# OpenSddRag — Explore
+${note}## When to use
+Thinking mode — to investigate a problem, idea, or question and build understanding BEFORE
+committing to a proposal. You may capture insights as artifacts, but you NEVER write code here.
+
+## Inputs
+$ARGUMENTS = topic, question, or idea to explore.
+
+## Stance
+You are in THINKING MODE. Your role is to:
+- Ask clarifying questions.
+- Surface at least two options with trade-offs.
+- Investigate the codebase (read-only).
+- Create ASCII diagrams to illustrate ideas.
+- Challenge assumptions and reference existing specs for context.
+
+You MUST NOT:
+- Write application code.
+- Create implementation files.
+- Make changes to the codebase.
+
+## Workflow
+
+### Step 1 — Check for existing related work
+\`search_semantic(query="$ARGUMENTS", project_slug="${slug}", limit=5)\`
+\`recall_episodes(query="$ARGUMENTS", project_slug="${slug}", limit=3)\`
+Share any existing specs or past decisions that are relevant.
+
+### Step 2 — Investigate and think
+- Read relevant codebase files (read-only).
+- Identify constraints and dependencies.
+- Surface at least two different approaches; for each, list trade-offs.
+
+### Step 3 — Capture insights (only if the user asks)
+\`create_artifact(name="explore-<topic>-<date>", type="proposal", content="<exploration notes, options, trade-offs>", metadata={"explore": true}, project_slug="${slug}")\`
+If amending an existing design/proposal, use \`update_artifact\` instead.
+
+### Step 4 — Transition when ready
+Summarize the key findings and a recommendation, then ask:
+"Ready to create a formal proposal? Run /opsr:propose <name>."
+
+## Example prompts this skill handles well
+- "Is it coherent to refactor X this way?" → validate the premise against the code, surface risks.
+- "Two ways to model Y — which is better here?" → compare approaches with trade-offs and a pick.
+- "What would it take to add Z?" → scope the work, list constraints and dependencies, no code.
+
+## Output shape
+A short written analysis: premise check → 2+ options with trade-offs → a recommendation →
+optional follow-up actions (amend a design, create an explore-* artifact, or move to /opsr:propose).
+
+## Output
+- Shared analysis and a recommendation; optionally an \`explore-*\` artifact capturing the decision.
+
+## Important rules
+- NEVER write application code or create implementation files in this phase.
+- Only create/update OpenSddRag artifacts when the user explicitly asks to capture something.
+- Prefer presenting trade-offs and a recommendation over an exhaustive survey.
+`,
+};

package/src/templates/skills/flow.js

@@ -0,0 +1,65 @@
+export const flowSkill = {
+  name: "opensddrag-flow",
+  description: "Run the complete SDD flow end-to-end in one session",
+  body: (slug, note) => `# OpenSddRag — Flow
+${note}## When to use
+To run the complete SDD flow end-to-end in a single session: propose → spec → design → tasks →
+apply → archive. Planning artifacts are saved to the database; implementation code is written locally.
+
+This skill is a thin **orchestrator**: each phase delegates to the matching skill, which is the
+single source of truth for that phase's workflow. Do NOT duplicate those steps here.
+
+## Inputs
+$ARGUMENTS = feature description or change name.
+
+## Workflow
+
+### Phase 1 — Propose
+Load the \`opensddrag-propose\` skill and follow it: search for duplicates, compose the proposal
+(Why / What Changes / Capabilities / Impact), and save the \`<change-name>-proposal\` artifact.
+
+### Phase 2 — Spec
+Load the \`opensddrag-spec\` skill and follow it for each capability in the proposal: compose the
+spec (Purpose / Requirements with SHALL / Scenarios with WHEN-THEN), save it, link it to the
+proposal, and validate it. Fix validation errors before continuing.
+
+### Phase 3 — Design
+Load the \`opensddrag-design\` skill and follow it: read all specs, compose the design
+(Context / Goals / Decisions / Architecture / Risks / Migration), save it, and link it to the proposal.
+
+### Phase 4 — Tasks
+Load the \`opensddrag-tasks\` skill and follow it: read proposal + specs + design, create one task
+artifact per unit of work, link each to its spec(s), and update the working context.
+
+### Phase 5 — Apply (repeat for each task in order)
+Load the \`opensddrag-apply\` skill and follow it for each task: read all planning artifacts, mark
+the task active, implement it locally (Edit/Write/Bash), run the on_apply harness checklist, then
+mark it archived and record a trace. Repeat until no draft tasks remain.
+
+### Phase 6 — Archive
+Load the \`opensddrag-archive\` skill and follow it: sync any delta specs, run the on_archive
+harness checklist, archive all change artifacts, and record the completion trace.
+
+## Resuming a partially-complete flow
+Flow is idempotent at the phase level. Before each phase, check what already exists
+(\`get_relationships(name="<change-name>-proposal", project_slug="${slug}")\`) and skip phases whose
+artifacts are already present:
+- Proposal exists → skip Phase 1.
+- All capabilities specced → skip Phase 2.
+- Design exists → skip Phase 3.
+- Tasks exist → skip Phase 4 and resume Phase 5 at the first non-archived task.
+This lets /opsr:flow pick up an interrupted change instead of recreating planning artifacts.
+
+## Pacing
+Pause for user confirmation between planning phases (1–4) when scope is ambiguous; once tasks are
+agreed, Phase 5 can run task-by-task with a trace after each.
+
+## Output
+- A fully executed change: all planning artifacts archived, deltas synced, code implemented.
+
+## Important rules
+- Delegate each phase to its skill — never inline another skill's workflow into this one.
+- Honor every phase gate (validation, harness checklists) as defined by the delegated skill.
+- Implementation code is written to local files; planning artifacts live only in the database.
+`,
+};