@kynetic-ai/spec 0.1.2 → 0.4.0

package/templates/skills/create-workflow/SKILL.md

@@ -0,0 +1,228 @@
+# 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/templates/skills/help/SKILL.md

@@ -0,0 +1,37 @@
+# kspec Help
+
+Get help with kspec commands and workflows.
+
+## When to Use
+
+Use this skill when:
+- You need to understand kspec commands
+- You want to learn about task and spec workflows
+- You need help with CLI syntax
+
+## Quick Reference
+
+```bash
+# Core commands
+kspec help                    # Show all commands
+kspec help <command>          # Show command help
+kspec task list               # List tasks
+kspec tasks ready             # Show ready tasks
+kspec item list               # List spec items
+
+# Task lifecycle
+kspec task start @ref         # Start working
+kspec task note @ref "..."    # Add note
+kspec task submit @ref        # Submit for review
+kspec task complete @ref      # Mark complete
+
+# Spec management
+kspec item add --title "..."  # Create spec item
+kspec item ac add @ref --given "..." --when "..." --then "..."
+```
+
+## Key Concepts
+
+- **Spec items**: Define WHAT to build (requirements, features)
+- **Tasks**: Track the WORK of building
+- **Shadow branch**: Separate branch for spec/task state

package/templates/skills/manifest.yaml

@@ -0,0 +1,60 @@
+# Core Skills Manifest
+# This file defines the metadata for core skills shipped with kspec.
+# The skill content is in ./<skill-id>/SKILL.md
+
+skills:
+  - id: help
+    name: Kspec Help
+    description: Get help with kspec commands and workflows
+    platforms:
+      - claude-code
+  - id: observations
+    name: Observations
+    description: Capture and act on systemic patterns — friction, successes, questions, and ideas. The feedback loop that drives process improvement.
+    platforms:
+      - claude-code
+  - id: reflect
+    name: Session Reflection
+    description: Structured reflection at the end of work sessions. Identifies learnings, friction points, and improvements for system evolution.
+    platforms:
+      - claude-code
+  - id: triage
+    name: Triage
+    description: Triage inbox items systematically. Records decisions with audit trail, then executes actions. Supports inbox, observations, and automation eligibility triage.
+    platforms:
+      - claude-code
+  - id: triage-inbox
+    name: Inbox Triage
+    description: Process inbox items using the record-act pattern. Categorize, promote to spec/task, merge duplicates, defer, or delete stale items with full audit trail.
+    platforms:
+      - claude-code
+  - id: triage-automation
+    name: Automation Triage
+    description: Assess and prepare tasks for automation eligibility. Verify spec coverage, acceptance criteria, and task readiness for automated agents.
+    platforms:
+      - claude-code
+  - id: writing-specs
+    name: Writing Specs
+    description: Create and maintain specification items — modules, features, requirements, acceptance criteria, and traits. The source of truth for what to build.
+    platforms:
+      - claude-code
+  - id: plan
+    name: Plan to Spec
+    description: Translate approved plans into specs and tasks. Import structured documents or create incrementally. Plans persist as durable artifacts with audit trail.
+    platforms:
+      - claude-code
+  - id: task-work
+    name: Task Work
+    description: Structured task lifecycle — start, work, note, submit, complete. Fix cycle handling, scope management, loop mode for automation, and quality gates.
+    platforms:
+      - claude-code
+  - id: create-workflow
+    name: Create Workflow
+    description: Formalize repeatable patterns into trackable kspec workflows. Design steps, choose triggers, create loop variants, and integrate with skills.
+    platforms:
+      - claude-code
+  - id: review
+    name: Review
+    description: Kspec-specific review gates — spec alignment, own AC coverage, trait AC coverage, and validation integration. Building block for project-specific review workflows.
+    platforms:
+      - claude-code

package/templates/skills/observations/SKILL.md

@@ -0,0 +1,137 @@
+# 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