@kynetic-ai/spec 0.3.0 → 0.4.0

package/dist/triage/actions.d.ts

@@ -0,0 +1,27 @@
+import type { KspecContext } from "../parser/yaml.js";
+import type { LoadedTriageRecord } from "../parser/index.js";
+/**
+ * Result of executing a triage action.
+ */
+export interface TriageActionResult {
+    resultRef?: string;
+}
+/**
+ * Options for executeTriageAction.
+ * - dryRun: If true, describe what would happen without executing.
+ * - onInfo: Optional callback for informational messages (used by CLI for logging).
+ */
+export interface ExecuteTriageActionOptions {
+    dryRun?: boolean;
+    onInfo?: (message: string) => void;
+}
+/**
+ * Execute a triage action against the kspec context.
+ *
+ * Shared between CLI and daemon. The CLI passes dryRun and onInfo for
+ * user-facing output; the daemon calls with no options for silent execution.
+ *
+ * AC: @triage-cli-commands ac-4, ac-5, ac-6, ac-7, ac-8
+ */
+export declare function executeTriageAction(record: LoadedTriageRecord, ctx: KspecContext, options?: ExecuteTriageActionOptions): Promise<TriageActionResult>;
+//# sourceMappingURL=actions.d.ts.map

package/dist/triage/actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../../src/triage/actions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAe7D;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,0BAA0B;IACzC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACpC;AAED;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,kBAAkB,EAC1B,GAAG,EAAE,YAAY,EACjB,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,kBAAkB,CAAC,CAyF7B"}

package/dist/triage/actions.js

@@ -0,0 +1,95 @@
+import { createObservation, createTask, deleteInboxItem, findInboxItemByRef, loadAllItems, loadAllTasks, loadInboxItems, ReferenceIndex, saveObservation, saveTask, } from "../parser/index.js";
+import { truncateText } from "../export/triage.js";
+/**
+ * Execute a triage action against the kspec context.
+ *
+ * Shared between CLI and daemon. The CLI passes dryRun and onInfo for
+ * user-facing output; the daemon calls with no options for silent execution.
+ *
+ * AC: @triage-cli-commands ac-4, ac-5, ac-6, ac-7, ac-8
+ */
+export async function executeTriageAction(record, ctx, options = {}) {
+    const { dryRun = false, onInfo } = options;
+    const action = record.action;
+    if (!action) {
+        throw new Error("Record has no action to execute");
+    }
+    switch (action) {
+        case "promote": {
+            // AC: @triage-cli-commands ac-4
+            if (dryRun) {
+                onInfo?.(`Would create task from inbox item snapshot: "${truncateText(record.item_snapshot)}"`);
+                return {};
+            }
+            const task = createTask({
+                title: record.item_snapshot.split("\n")[0].slice(0, 100),
+                type: "task",
+                priority: 3,
+                spec_ref: null,
+                tags: [],
+                description: record.item_snapshot,
+            });
+            await saveTask(ctx, task);
+            const tasks = await loadAllTasks(ctx);
+            const items = await loadAllItems(ctx);
+            const index = new ReferenceIndex(tasks, items);
+            const taskRef = `@${index.shortUlid(task._ulid)}`;
+            onInfo?.(`Created task: ${taskRef} - ${task.title}`);
+            return { resultRef: taskRef };
+        }
+        case "delete": {
+            // AC: @triage-cli-commands ac-5
+            if (dryRun) {
+                onInfo?.(`Would delete inbox item: ${record.inbox_ref.slice(0, 8)}`);
+                return {};
+            }
+            const inboxItems = await loadInboxItems(ctx);
+            const inboxItem = findInboxItemByRef(inboxItems, record.inbox_ref);
+            if (inboxItem) {
+                await deleteInboxItem(ctx, inboxItem._ulid);
+                onInfo?.(`Deleted inbox item: ${record.inbox_ref.slice(0, 8)}`);
+            }
+            return {};
+        }
+        case "defer": {
+            // AC: @triage-cli-commands ac-6
+            if (dryRun) {
+                onInfo?.(`Would defer: no side effects beyond recording the deferral`);
+                return {};
+            }
+            return {};
+        }
+        case "spec-gap": {
+            // AC: @triage-cli-commands ac-7
+            if (dryRun) {
+                onInfo?.(`Would create spec-gap observation from: "${truncateText(record.item_snapshot)}"`);
+                return {};
+            }
+            const content = `[spec-gap] ${record.item_snapshot}\n\nReasoning: ${record.reasoning || ""}`;
+            const observation = createObservation("question", content, {
+                configAuthor: ctx.config?.identity?.author,
+            });
+            await saveObservation(ctx, observation);
+            const obsRef = `@${observation._ulid.slice(0, 8)}`;
+            onInfo?.(`Created spec-gap observation: ${obsRef}`);
+            return { resultRef: obsRef };
+        }
+        case "duplicate": {
+            // AC: @triage-cli-commands ac-8
+            if (dryRun) {
+                onInfo?.(`Would delete duplicate inbox item: ${record.inbox_ref.slice(0, 8)}`);
+                return {};
+            }
+            const dupItems = await loadInboxItems(ctx);
+            const dupItem = findInboxItemByRef(dupItems, record.inbox_ref);
+            if (dupItem) {
+                await deleteInboxItem(ctx, dupItem._ulid);
+                onInfo?.(`Deleted duplicate inbox item: ${record.inbox_ref.slice(0, 8)}`);
+            }
+            return {};
+        }
+        default:
+            return {};
+    }
+}
+//# sourceMappingURL=actions.js.map

package/dist/triage/actions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.js","sourceRoot":"","sources":["../../src/triage/actions.ts"],"names":[],"mappings":"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"}

package/dist/triage/constants.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Valid triage actions derived from the Zod schema.
+ * Single source of truth — use this instead of hardcoding action strings.
+ */
+export declare const VALID_ACTIONS: readonly string[];
+//# sourceMappingURL=constants.d.ts.map

package/dist/triage/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/triage/constants.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,SAAS,MAAM,EAA+B,CAAC"}

package/dist/triage/constants.js

@@ -0,0 +1,7 @@
+import { TriageActionSchema } from "../schema/triage.js";
+/**
+ * Valid triage actions derived from the Zod schema.
+ * Single source of truth — use this instead of hardcoding action strings.
+ */
+export const VALID_ACTIONS = TriageActionSchema.options;
+//# sourceMappingURL=constants.js.map

package/dist/triage/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/triage/constants.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAsB,kBAAkB,CAAC,OAAO,CAAC"}

package/dist/triage/index.d.ts

@@ -0,0 +1,3 @@
+export { VALID_ACTIONS } from "./constants.js";
+export { executeTriageAction, type ExecuteTriageActionOptions, type TriageActionResult, } from "./actions.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/triage/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/triage/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EACL,mBAAmB,EACnB,KAAK,0BAA0B,EAC/B,KAAK,kBAAkB,GACxB,MAAM,cAAc,CAAC"}

package/dist/triage/index.js

@@ -0,0 +1,3 @@
+export { VALID_ACTIONS } from "./constants.js";
+export { executeTriageAction, } from "./actions.js";
+//# sourceMappingURL=index.js.map

package/dist/triage/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/triage/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EACL,mBAAmB,GAGpB,MAAM,cAAc,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kynetic-ai/spec",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Kynetic Spec - Structured specification format for human-AI collaboration",
   "type": "module",
   "workspaces": [

package/plugin/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "kspec",
       "description": "kspec agent skills",
-      "version": "0.3.0",
+      "version": "0.4.0",
       "source": "./plugins/kspec",
       "category": "development"
     }

package/plugin/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "kspec",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "kspec agent skills"
 }

package/plugin/plugins/kspec/skills/create-workflow/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: create-workflow
+description: Formalize repeatable patterns into trackable kspec workflows.
+  Design steps, choose triggers, create loop variants, and integrate with
+  skills.
+---
+<!-- kspec-managed -->
+# Create Workflow
+
+Formalize repeatable patterns into trackable kspec workflows. A meta-workflow for building new workflows with consistent structure.
+
+## When to Use
+
+- Formalizing a repeated process into a trackable workflow
+- Converting step-by-step documentation into executable steps
+- Adding quality gates that are easy to skip without structure
+
+**Not for:** Running existing workflows (use `kspec workflow start @id`), one-off processes, or tasks that don't repeat.
+
+## Identifying Good Candidates
+
+Look for processes that are:
+
+| Signal | Example |
+|--------|---------|
+| Step-by-step instructions in docs | "To release: bump version, tag, push, create release" |
+| Checklists that get skipped | "Before merge: check CI, resolve threads, verify AC" |
+| Repeated command sequences | "Start daemon, run tests, check output, stop daemon" |
+| Quality gates with multiple criteria | "Review: AC coverage, test quality, code style, regressions" |
+
+Good sources: AGENTS.md, existing skills, task notes, session reflections.
+
+## Workflow Structure
+
+Every workflow has:
+
+```yaml
+id: kebab-case-name
+description: What this workflow does
+trigger: when-it-starts
+mode: interactive  # or loop
+steps:
+  - id: step-1
+    type: action    # action, check, or decision
+    content: What to do in this step
+```
+
+### Triggers
+
+| Trigger | When |
+|---------|------|
+| `manual` | Invoked explicitly |
+| `session-start` | Beginning of work session |
+| `session-end` | End of work session |
+| `task-complete` | After completing a task |
+| `behavior-change` | Before implementing changes |
+| `pre-release` | Before creating a release |
+| `pr-merge` | Before merging a PR |
+
+### Step Types
+
+| Type | Purpose | Example |
+|------|---------|---------|
+| `action` | Do something | "Run tests and verify all pass" |
+| `check` | Verify a condition | "All CI checks passing?" |
+| `decision` | Choose a path | "Import or manual path?" |
+
+### Modes
+
+- **interactive** — Pauses for user input at each step
+- **loop** — Auto-resolves decisions, no user prompts (for automated agents)
+
+Loop mode workflows typically have a `based_on` field referencing the interactive version.
+
+## Creating a Workflow
+
+### Step 1: Design the Steps
+
+Before creating, outline your steps on paper:
+
+1. What's the trigger?
+2. What steps are needed?
+3. Which are actions vs checks vs decisions?
+4. What inputs does each step need?
+5. What's the exit criteria?
+
+### Step 2: Create the Workflow
+
+```bash
+kspec meta add workflow \
+  --id my-workflow \
+  --trigger manual \
+  --description "Description of what this workflow does" \
+  --tag category \
+  --steps '[
+    {"id":"step-1","type":"action","content":"First action to take"},
+    {"id":"step-2","type":"check","content":"Verify the condition"},
+    {"id":"step-3","type":"decision","content":"Choose path A or B"}
+  ]'
+```
+
+### Step 3: Test the Workflow
+
+Run through it end-to-end:
+
+```bash
+kspec workflow start @my-workflow
+kspec workflow next --notes "Testing step 1"
+kspec workflow next --input decision="path-a" --notes "Chose A because..."
+# Continue through all steps
+kspec workflow show  # Verify inputs and notes captured
+```
+
+### Step 4: Consider a Matching Skill
+
+A workflow may benefit from a matching skill when:
+
+| Create a skill when | Skip the skill when |
+|---------------------|---------------------|
+| Steps need detailed context | Workflow is self-contained |
+| Multiple sub-documents help | Context exists elsewhere |
+| Users need a `/command` entrypoint | Workflow is internal/automated |
+| Complex decision logic | Simple sequential steps |
+
+If creating a skill, write it to `templates/skills/<name>/SKILL.md` and add a manifest entry.
+
+### Step 5: Commit
+
+```bash
+# Workflow definition auto-committed to shadow branch by kspec
+# Skill files (if created) need manual commit to main branch
+git add templates/skills/<name>/SKILL.md
+git commit -m "feat: add <name> skill for workflow integration"
+```
+
+## Step Design Guidelines
+
+### Action Steps
+
+Clear, specific instructions:
+
+```yaml
+- id: run-tests
+  type: action
+  content: |
+    Run the full test suite. Fix any failures before proceeding.
+    Verify both unit and integration tests pass.
+```
+
+### Check Steps
+
+Binary yes/no verification:
+
+```yaml
+- id: ci-passing
+  type: check
+  content: |
+    Verify all CI checks are passing on the current HEAD.
+    If not, wait for CI or fix failures.
+```
+
+### Decision Steps
+
+Clear options with guidance:
+
+```yaml
+- id: choose-path
+  type: decision
+  content: |
+    Choose execution path:
+    - Import: 3+ specs, structured document, batch creation
+    - Manual: 1-2 specs, incremental, quick additions
+```
+
+### Tips
+
+- Keep steps atomic — one action per step
+- Include the "why" when it's not obvious
+- Decision steps should list all options
+- Check steps should describe what to do on failure
+- Use `content` for detailed multi-line instructions
+
+## Loop Mode Variants
+
+For automated agents, create a loop variant:
+
+```bash
+kspec meta add workflow \
+  --id my-workflow-loop \
+  --trigger manual \
+  --mode loop \
+  --based-on @my-workflow \
+  --description "Automated variant of my-workflow" \
+  --steps '[...]'
+```
+
+Loop variants typically:
+- Auto-resolve decisions (pick the most common path)
+- Skip user confirmation steps
+- Add higher confidence thresholds
+- Include automated exit conditions
+
+## Workflow Lifecycle
+
+```bash
+# Create
+kspec meta add workflow --id ... --steps '[...]'
+
+# Run
+kspec workflow start @id
+kspec workflow next --notes "..."
+kspec workflow next --input key=value
+
+# Manage
+kspec workflow show        # Check progress
+kspec workflow pause       # Pause for later
+kspec workflow resume      # Resume paused run
+
+# Update (edit the meta YAML)
+kspec meta set workflow @id --steps '[...]'
+```
+
+## Regenerate Agent Instructions
+
+After creating a workflow, regenerate agent instructions so the workflow appears in the available workflows list:
+
+```bash
+kspec agents generate
+```
+
+## Integration
+
+- **`/kspec:reflect`** — Session reflections surface patterns worth formalizing
+- **`/kspec:observations`** — Friction observations may reveal missing workflows
+- **`kspec agents generate`** — Regenerate after creating workflows

package/plugin/plugins/kspec/skills/observations/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: observations
+description: Capture and act on systemic patterns — friction, successes,
+  questions, and ideas. The feedback loop that drives process improvement.
+---
+<!-- kspec-managed -->
+# Observations
+
+Capture and act on systemic patterns — friction, successes, questions, and ideas. Observations are the feedback loop that drives process improvement.
+
+## When to Use
+
+- You hit friction (something harder than it should be)
+- You notice a success worth replicating
+- A systemic question arises (not session-specific)
+- An improvement idea surfaces during work
+
+**Not for:** Session-local questions (use `kspec meta question`), future work items (use `kspec inbox add`), or task-specific notes (use `kspec task note`).
+
+## Observation Types
+
+| Type | When to use | Example |
+|------|-------------|---------|
+| `friction` | Something is harder than it should be | "Bulk updates require too many commands" |
+| `success` | A pattern that worked well | "Dry-run before derive prevented duplicate tasks" |
+| `question` | A systemic question about process | "When should agents use inbox vs tasks?" |
+| `idea` | An improvement opportunity | "CLI could suggest next steps after task completion" |
+
+## Capturing Observations
+
+Capture in the moment — don't wait until later. The value is in the raw context.
+
+```bash
+# Friction: something was harder than it should be
+kspec meta observe friction "Had to run 5 commands to update one spec field"
+
+# Success: a pattern worth remembering
+kspec meta observe success "Using --dry-run before derive prevented duplicate tasks"
+
+# Question: systemic, not session-local
+kspec meta observe question "When should agents enter plan mode vs just implement?"
+
+# Idea: something that could improve the system
+kspec meta observe idea "CLI could suggest next steps after task completion"
+
+# Link to a workflow for context
+kspec meta observe friction "Plan import dropped acceptance criteria" --workflow @spec-plan-import
+```
+
+## Reviewing Observations
+
+```bash
+# All unresolved observations (default)
+kspec meta observations
+
+# Only those awaiting resolution
+kspec meta observations --pending-resolution
+
+# Filter by type
+kspec meta observations --type friction
+```
+
+## Acting on Observations
+
+### Promote to Task
+
+When an observation reveals clear, actionable work:
+
+```bash
+kspec meta promote @ref --title "Add bulk AC command" --priority 2
+```
+
+### Resolve
+
+When addressed, documented, or no longer relevant:
+
+```bash
+# Single observation with resolution note
+kspec meta resolve @ref "Fixed in PR #123"
+
+# Batch resolve related observations
+kspec meta resolve --refs @ref1 @ref2 @ref3 --resolution "All addressed by new workflow"
+```
+
+### Convert from Inbox
+
+When an inbox item is really a pattern observation, not future work:
+
+```bash
+kspec meta observe --from-inbox @inbox-ref
+kspec meta observe --from-inbox @inbox-ref --type friction
+```
+
+## Decision Flow
+
+```
+When you notice something during work:
+├── Is it future work?
+│   └── Yes → kspec inbox add "..."
+├── Is it about THIS task only?
+│   └── Yes → kspec task note @task "..."
+└── Is it a systemic pattern?
+    └── Yes → kspec meta observe <type> "..."
+```
+
+```
+For each pending observation:
+├── Still relevant?
+│   ├── No → resolve with note
+│   └── Yes → Needs action?
+│       ├── No (just learning) → document and resolve
+│       └── Yes → Scope clear?
+│           ├── Yes → promote to task
+│           └── No → add to inbox for later triage
+```
+
+## Where Observations Fit
+
+| What you have | Where | Why |
+|---------------|-------|-----|
+| Vague idea for future | `inbox add` | Low-friction capture, triage later |
+| Clear actionable work | `task add` | Ready to implement |
+| Something was hard | `meta observe friction` | Informs process improvement |
+| Something worked well | `meta observe success` | Worth replicating |
+| Session-local question | `meta question add` | Track during current session |
+| Systemic process question | `meta observe question` | Broader than one session |
+
+## Batch Capture
+
+When capturing multiple observations at once (e.g., during reflection), use `kspec batch`:
+
+```bash
+kspec batch --commands '[
+  {"command":"meta observe","args":{"type":"friction","content":"Bulk updates require too many commands"}},
+  {"command":"meta observe","args":{"type":"success","content":"Dry-run before derive prevented duplicates"}}
+]'
+```
+
+## Integration
+
+- **`/kspec:triage observations`** — Processes pending observations during triage
+- **`/kspec:reflect`** — Creates observations from session learnings
+- **`kspec session start`** — Shows pending observation count