@kynetic-ai/spec 0.3.0 → 0.4.0

package/plugin/plugins/kspec/skills/writing-specs/SKILL.md

@@ -0,0 +1,340 @@
+---
+name: writing-specs
+description: Create and maintain specification items — modules, features,
+  requirements, acceptance criteria, and traits. The source of truth for what to
+  build.
+---
+<!-- kspec-managed -->
+# Writing Specs
+
+Create and maintain specification items — the source of truth for what to build. This skill covers spec structure, writing good acceptance criteria, using traits, and organizing specs in the hierarchy.
+
+## When to Use
+
+- Creating a new feature, requirement, or constraint spec
+- Adding or refining acceptance criteria
+- Applying traits for cross-cutting behaviors
+- Organizing specs under the right module/parent
+- Reviewing spec quality before deriving tasks
+
+**Not for:** Task management (use `/kspec:task-work`), plan-to-spec translation (use `/kspec:plan`), or triage (use `/kspec:triage`).
+
+## Core Principles
+
+1. **Spec defines WHAT, not HOW** — Describe the desired behavior, not the implementation
+2. **Every spec needs AC** — A spec without acceptance criteria is incomplete
+3. **Given/When/Then is testable** — Each AC should map to at least one test
+4. **Traits eliminate duplication** — Cross-cutting concerns belong in traits, not copied across specs
+5. **Use CLI, not YAML** — All changes through `kspec` commands for auto-commit
+
+## Spec Hierarchy
+
+Specs live in modules and form a tree:
+
+```
+module (organizational grouping)
+├── feature (user-facing capability)
+│   ├── requirement (specific testable behavior)
+│   └── constraint (limitation or boundary)
+├── feature
+│   └── requirement
+└── decision (architectural choice, ADR-style)
+```
+
+### Choosing the Right Type
+
+| Type | Use when | Example |
+|------|----------|---------|
+| `module` | Grouping related features | "CLI Commands", "Web UI", "Schema" |
+| `feature` | User-facing capability | "JSON Export", "Inbox Triage", "Shadow Sync" |
+| `requirement` | Specific testable behavior within a feature | "Export validates output format", "Triage records audit trail" |
+| `constraint` | Non-functional limit or boundary | "Response time < 200ms", "Max 1000 items per module" |
+| `decision` | Architectural choice with rationale | "Use YAML over JSON for spec files" |
+| `trait` | Reusable AC bundle for cross-cutting behaviors | "JSON output mode", "Confirmation prompts" |
+
+**Rule of thumb:** If it has acceptance criteria that a user could verify, it's a feature or requirement. If it constrains how something works, it's a constraint. If multiple specs need the same behavior, extract a trait.
+
+## Writing Acceptance Criteria
+
+AC are the heart of a spec. They define what "done" means.
+
+### Format
+
+```
+Given: precondition (state before the action)
+When:  action (what triggers the behavior)
+Then:  outcome (observable, verifiable result)
+```
+
+### Good AC Patterns
+
+**Specific and testable:**
+```bash
+kspec item ac add @json-export \
+  --given "user has 3 tasks in project" \
+  --when "user runs 'kspec tasks list --json'" \
+  --then "stdout contains valid JSON array with 3 task objects"
+```
+
+**Covers error cases:**
+```bash
+kspec item ac add @json-export \
+  --given "project has no tasks" \
+  --when "user runs 'kspec tasks list --json'" \
+  --then "stdout contains empty JSON array []"
+```
+
+**Boundary behavior:**
+```bash
+kspec item ac add @bulk-delete \
+  --given "user passes 50 refs (maximum supported)" \
+  --when "user runs bulk delete" \
+  --then "all 50 items deleted in single operation"
+```
+
+### AC Anti-patterns
+
+| Anti-pattern | Problem | Better |
+|-------------|---------|--------|
+| "System works correctly" | Not testable | Describe specific observable outcome |
+| "User is happy" | Subjective | Describe what they can do or see |
+| "Fast performance" | Not measurable | "Response returns within 200ms" |
+| "Handles errors" | Vague | Specific error scenario + expected behavior |
+| Duplicating trait AC | Maintenance burden | Apply the trait instead |
+
+### AC Naming Convention
+
+AC IDs are auto-generated (`ac-1`, `ac-2`, ...) or can be explicit:
+
+```bash
+# Auto-generated
+kspec item ac add @feature --given "..." --when "..." --then "..."
+
+# Explicit ID for clarity
+kspec item ac add @feature --id ac-json-valid --given "..." --when "..." --then "..."
+```
+
+### How Many ACs?
+
+- **Minimum 1** — Every spec needs at least one
+- **Typical: 2-5** — Happy path + key error cases
+- **If 8+** — Consider splitting the spec into smaller requirements
+- **Each AC = one behavior** — Don't combine multiple verifiable outcomes
+
+## Working with Traits
+
+Traits are reusable bundles of acceptance criteria. When a spec implements a trait, it inherits all the trait's ACs.
+
+### When to Use Traits
+
+Apply a trait when a spec needs a standard cross-cutting behavior:
+
+```bash
+# Discover available traits
+kspec trait list
+
+# View trait details (shows ACs that will be inherited)
+kspec trait get @trait-json-output
+
+# Apply trait to spec
+kspec item trait add @my-command @trait-json-output
+
+# Apply multiple traits
+kspec item trait add @my-command @trait-json-output @trait-dry-run
+```
+
+### Common Traits
+
+| Trait | When to apply |
+|-------|---------------|
+| `@trait-json-output` | Command produces machine-readable output |
+| `@trait-dry-run` | Command supports preview before execution |
+| `@trait-confirmation-prompt` | Command is destructive |
+| `@trait-filterable-list` | Command lists items with filter options |
+| `@trait-shadow-commit` | Command modifies `.kspec/` data |
+| `@trait-semantic-exit-codes` | Command exit code carries meaning |
+| `@trait-error-guidance` | Command gives recovery suggestions on errors |
+| `@trait-multi-ref-batch` | Command accepts multiple references |
+| `@trait-priority-parameter` | Command accepts priority option |
+
+### Creating New Traits
+
+If 3+ specs need the same behavior, consider extracting a trait:
+
+```bash
+# Create the trait
+kspec trait add "Pagination Support" --description "Commands that paginate large result sets" --slug trait-pagination
+
+# Add ACs to the trait
+kspec item ac add @trait-pagination --given "result set > page size" --when "command runs" --then "first page shown with pagination indicator"
+kspec item ac add @trait-pagination --given "user requests next page" --when "user passes --page 2" --then "second page of results shown"
+```
+
+### Trait AC Coverage
+
+When implementing specs with traits, all inherited ACs must be covered by tests:
+
+```javascript
+// AC: @trait-json-output ac-1
+it('should output valid JSON with --json flag', () => { ... });
+```
+
+Run `kspec validate` to check for uncovered trait ACs.
+
+## Creating Specs
+
+### New Feature Under a Module
+
+```bash
+# 1. Find the right parent module
+kspec item list --type module
+
+# 2. Create the feature
+kspec item add --under @cli-module --title "Bulk Operations" --type feature --slug bulk-ops
+
+# 3. Add description
+kspec item set @bulk-ops --description "Support batch operations on multiple items in a single command"
+
+# 4. Add acceptance criteria
+kspec item ac add @bulk-ops \
+  --given "user provides 3 item refs" \
+  --when "user runs bulk delete" \
+  --then "all 3 items deleted and confirmation shown"
+
+kspec item ac add @bulk-ops \
+  --given "one of 3 refs is invalid" \
+  --when "user runs bulk delete" \
+  --then "error reported for invalid ref, valid refs still processed"
+
+# 5. Apply relevant traits
+kspec item trait add @bulk-ops @trait-confirmation-prompt @trait-dry-run
+
+# 6. Validate
+kspec validate
+```
+
+### Requirement Under a Feature
+
+```bash
+kspec item add --under @bulk-ops --title "Ref validation in batch mode" --type requirement --slug bulk-ref-validation
+kspec item ac add @bulk-ref-validation \
+  --given "batch contains mix of valid and invalid refs" \
+  --when "batch executes" \
+  --then "report lists each ref with success/failure status"
+```
+
+### Updating Existing Specs
+
+```bash
+# View current state
+kspec item get @feature-slug
+
+# Update description
+kspec item set @feature-slug --description "Updated description"
+
+# Add missing AC
+kspec item ac add @feature-slug --given "..." --when "..." --then "..."
+
+# Update existing AC
+kspec item ac set @feature-slug ac-2 --then "updated expected outcome"
+
+# Mark implementation status
+kspec item set @feature-slug --status implemented
+
+# Add relationships
+kspec item set @feature-slug --depends-on @other-feature
+kspec item set @feature-slug --relates-to @related-item
+```
+
+## Spec Quality Checklist
+
+Before deriving a task from a spec, verify:
+
+- [ ] **Description** — Explains what and why (not how)
+- [ ] **AC coverage** — At least happy path + primary error case
+- [ ] **AC testability** — Each AC maps to a concrete test
+- [ ] **Traits applied** — Cross-cutting behaviors use traits, not duplicated AC
+- [ ] **Correct parent** — Placed under the right module/feature
+- [ ] **No implementation details** — AC describes behavior, not code structure
+- [ ] **Validation passes** — `kspec validate` reports no errors for this item
+
+## Validation
+
+```bash
+# Full validation
+kspec validate
+
+# Completeness check
+kspec validate --completeness
+
+# Spec-task alignment
+kspec validate --alignment
+
+# Strict mode (warnings → errors)
+kspec validate --strict
+```
+
+**Exit codes:** `0` = success, `4` = errors, `6` = warnings only.
+
+Validation catches:
+- Missing acceptance criteria
+- Broken references (`@slug` pointing to nonexistent items)
+- Missing descriptions
+- Orphaned specs (no linked tasks)
+- Uncovered trait ACs
+
+## Command Reference
+
+### Item Management
+
+```bash
+kspec item list [--type <type>]        # List items
+kspec item get <ref>                   # Get item details with ACs and traits
+kspec item add --under <parent> --title "..." --type <type> [--slug <slug>]
+kspec item set <ref> --title "..."     # Update fields
+kspec item set <ref> --description "..."
+kspec item set <ref> --status <status> # implementation status
+kspec item set <ref> --depends-on <ref>
+kspec item set <ref> --relates-to <ref>
+kspec item patch <ref> --data '{...}'  # Complex updates
+kspec item delete <ref> [--force]
+```
+
+### Acceptance Criteria
+
+```bash
+kspec item ac list <ref>               # List ACs for item
+kspec item ac add <ref> --given "..." --when "..." --then "..."
+kspec item ac add <ref> --id <id> --given "..." --when "..." --then "..."
+kspec item ac set <ref> <ac-id> --then "updated"
+kspec item ac remove <ref> <ac-id> [--force]
+```
+
+### Traits
+
+```bash
+kspec trait list                       # All traits with AC counts
+kspec trait get <ref>                  # Trait details
+kspec trait add "Name" --description "..." [--slug <slug>]
+kspec item trait add <spec> <trait> [<trait2> ...]
+kspec item trait remove <spec> <trait> [<trait2> ...]
+```
+
+### Deriving Tasks
+
+Once a spec is ready, derive a task to track implementation:
+
+```bash
+kspec derive @feature-slug             # Create task linked to spec
+kspec derive @feature-slug --priority 2
+```
+
+The derived task gets `spec_ref: @feature-slug` automatically.
+
+## Integration
+
+- **`/kspec:plan`** — Plans create specs via import or manual creation
+- **`/kspec:task-work`** — Tasks reference specs; AC guides implementation
+- **`/kspec:triage`** — Inbox items may reveal spec gaps
+- **`/kspec:observations`** — Friction may indicate missing specs
+- **`/kspec:review`** — Reviews check AC coverage

package/templates/agents-sections/03-task-lifecycle.md

@@ -35,8 +35,8 @@ See `kspec help task` for transition commands and options.
 ### Creating Work
 
 - **Clear scope?** → Create task directly
-- **Unclear scope?** → `kspec inbox add "idea"` → triage later with `/triage`
-- **Learning/friction?** → `kspec meta observe friction "..."` → review with `/reflect`
+- **Unclear scope?** → `kspec inbox add "idea"` → triage later with `/kspec:triage`
+- **Learning/friction?** → `kspec meta observe friction "..."` → review during reflection
 
 ### Staying Aligned During Work
 

package/templates/agents-sections/04-pr-workflow.md

@@ -4,9 +4,9 @@ Before creating a PR, mark the task: `kspec task submit @ref` (transitions to `p
 
 The full PR lifecycle has three steps — **all required, in order:**
 
-1. **`/local-review`** — Quality gates: AC coverage, test quality, test isolation. Run this FIRST.
-2. **`/pr`** — Create the pull request.
-3. **`/pr-review`** — Review and merge. Or `kspec workflow start @pr-review-merge`.
+1. **Local review** — Quality gates: AC coverage, test quality, test isolation. Run this FIRST.
+2. **Create PR** — Push branch and open pull request.
+3. **Review and merge** — `kspec workflow start @pr-review-merge`.
 
 **Quality gates (never skip without explicit approval):**
 - All CI checks passing

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/manifest.yaml

@@ -8,8 +8,53 @@ skills:
     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