@kynetic-ai/spec 0.1.2 → 0.4.0

package/templates/skills/plan/SKILL.md

@@ -0,0 +1,336 @@
+# Plan to Spec Translation
+
+Translate approved plans into specs and tasks. Plans are durable artifacts — they persist in the shadow branch, link to derived work, and provide auditable planning history across sessions.
+
+## When to Use
+
+- After plan mode approval — turning an approved plan into trackable specs and tasks
+- Creating specs for new features or multi-spec capabilities
+- Translating design documents into the spec hierarchy
+
+**Not for:** Raw ideas (use `kspec inbox add`), single spec creation (use `/kspec:writing-specs`), or triage (use `/kspec:triage`).
+
+## Two Paths
+
+### Import Path (Recommended for 3+ Specs)
+
+Write a structured markdown document, then import it. All specs, tasks, and notes created atomically.
+
+```bash
+kspec plan import ./plan.md --module @target-module --dry-run  # Preview
+kspec plan import ./plan.md --module @target-module             # Execute
+```
+
+### Manual Path (1-2 Specs)
+
+Create plan record and specs incrementally via CLI.
+
+```bash
+kspec plan add --title "Plan Title" --content "Description" --status approved
+kspec item add --under @parent --title "Feature" --type feature --slug slug
+kspec item ac add @slug --given "..." --when "..." --then "..."
+kspec derive @slug
+```
+
+### When to Use Which
+
+| Situation | Path |
+|-----------|------|
+| Plan mode just approved, complex feature | Import |
+| Adding a requirement to existing feature | Manual |
+| Multiple related specs with parent/child | Import |
+| Quick bug fix that needs spec coverage | Manual |
+| Translating design doc with many specs | Import |
+| Iterating on previously imported plan | Import (`--update`) |
+
+## Three-Phase Workflow
+
+### Phase 1: Design
+
+Always start here — never skip research.
+
+```bash
+kspec workflow start @spec-plan-design
+```
+
+1. **Explore** — Read relevant code, understand current state
+2. **Clarify** — Identify ambiguities, resolve with user
+3. **Design** — Spec structure, AC coverage, trait selection
+4. **Review** — Check for completeness and gaps
+
+Design concludes by choosing import or manual path.
+
+### Phase 2: Execute
+
+Run the chosen workflow:
+
+```bash
+# Import path
+kspec workflow start @spec-plan-import
+
+# Manual path
+kspec workflow start @spec-plan-manual
+```
+
+### Phase 3: Validate
+
+After creating specs:
+
+```bash
+kspec validate              # Check spec quality
+kspec validate --alignment  # Verify spec-task links
+```
+
+## Plan Document Format
+
+The import parser extracts specs, tasks, and notes from this markdown structure:
+
+````markdown
+# Plan Title
+
+## Specs
+
+```yaml
+- title: OAuth Provider Support
+  slug: oauth-provider
+  type: feature
+  parent: "@auth"
+  description: Support third-party OAuth providers for authentication
+  traits:
+    - trait-error-guidance
+  acceptance_criteria:
+    - id: ac-1
+      given: User clicks sign-in with Google
+      when: OAuth flow completes successfully
+      then: User session is created with provider metadata
+    - id: ac-2
+      given: OAuth provider returns an error
+      when: Error callback is received
+      then: User sees descriptive error with retry option
+  implementation_notes: |
+    Use passport.js for OAuth. Per-spec notes go to this spec's derived task.
+
+- title: Token Refresh
+  slug: token-refresh
+  type: requirement
+  parent: "@oauth-provider"
+  acceptance_criteria:
+    - id: ac-1
+      given: Access token is within 5 minutes of expiry
+      when: User makes an API request
+      then: Token is silently refreshed before the request proceeds
+```
+
+## Tasks
+
+derive_from_specs: true
+
+```yaml
+- title: Write migration guide
+  slug: migration-guide
+  priority: 2
+  tags:
+    - docs
+```
+
+## Implementation Notes
+
+General architecture notes. Attached to the plan record.
+Use passport.js for OAuth, following existing auth patterns.
+````
+
+### Section Reference
+
+| Section | Content | Notes |
+|---------|---------|-------|
+| `## Specs` | YAML code block — array of spec objects | **Must** use fenced code block (triple-backtick yaml) |
+| `## Tasks` | `derive_from_specs: true` + optional manual tasks | Manual tasks get `plan_ref` but no `spec_ref` |
+| `## Implementation Notes` | Plain text | Attached to plan record; per-spec notes use `implementation_notes` field |
+
+### Spec Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `title` | Yes | Spec title |
+| `slug` | No | Human-friendly ID (auto-generated if omitted) |
+| `type` | No | `feature`, `requirement`, `constraint`, `decision` (default: `feature`) |
+| `parent` | No | Parent ref (e.g., `"@parent-slug"`) |
+| `description` | No | What and why |
+| `acceptance_criteria` | No | Array of `{id, given, when, then}` |
+| `traits` | No | Array of trait slugs (e.g., `trait-json-output`) |
+| `implementation_notes` | No | Scoped to this spec's derived task |
+
+## Trait Selection
+
+Before writing specs, review available traits:
+
+```bash
+kspec trait list
+kspec trait get @trait-json-output  # See inherited ACs
+```
+
+### Common Trait Applications
+
+| Building... | Consider these traits |
+|-------------|---------------------|
+| CLI command with output | `@trait-json-output`, `@trait-semantic-exit-codes` |
+| Destructive operation | `@trait-confirmation-prompt`, `@trait-dry-run` |
+| List/search command | `@trait-filterable-list`, `@trait-json-output` |
+| Shadow branch mutation | `@trait-shadow-commit` |
+| User-facing error paths | `@trait-error-guidance` |
+| Batch operations | `@trait-multi-ref-batch` |
+| API endpoint | `@trait-api-endpoint`, `@trait-localhost-security` |
+| WebSocket feature | `@trait-websocket-protocol` |
+
+### Trait Naming in Plan Documents
+
+Use the **full trait slug** — import only auto-prefixes `@`, not `@trait-`:
+
+```yaml
+# Wrong — resolves to nonexistent item
+traits:
+  - json-output
+
+# Correct — full slug
+traits:
+  - trait-json-output
+```
+
+## YAML Pitfalls
+
+Plan documents embed YAML that is parsed as structured data. Common issues:
+
+### Block Scalars for Complex Text
+
+Use `|` (literal block scalar) when AC text contains quotes, colons, or special characters:
+
+```yaml
+# Problem — mixed quoting breaks parser
+acceptance_criteria:
+  - id: ac-1
+    when: "kspec foo" is run
+
+# Solution — block scalar preserves content literally
+acceptance_criteria:
+  - id: ac-1
+    when: |
+      "kspec foo" is run
+```
+
+### Colons in Values
+
+YAML treats `: ` (colon-space) as a key-value separator:
+
+```yaml
+# Problem — parsed as nested key
+then: output shows time: 10:30
+
+# Solution — quote the value
+then: "output shows time: 10:30"
+```
+
+### Best Practice
+
+Use block scalars (`|`) for ALL given/when/then text. This avoids every quoting issue:
+
+```yaml
+acceptance_criteria:
+  - id: ac-1
+    given: |
+      user has an existing session
+    when: |
+      user runs "kspec session start"
+    then: |
+      session context shows: active tasks, recent notes, inbox count
+```
+
+## Always Dry-Run First
+
+```bash
+kspec plan import ./plan.md --module @target --dry-run
+```
+
+Dry-run catches:
+- YAML syntax errors before partial state is created
+- Missing parent refs
+- Invalid trait references
+- Duplicate slugs
+
+## Post-Import Checklist
+
+After importing, verify the results:
+
+```bash
+# Verify each spec has ACs
+kspec item get @spec-slug
+
+# Check trait coverage
+kspec validate
+
+# Set task dependencies (import doesn't infer these)
+kspec task set @task-slug --depends-on @other-task
+
+# Review plan record
+kspec plan get @plan-slug
+```
+
+## Plan Lifecycle
+
+```
+draft → approved → active → completed
+                     ↓
+                  rejected
+```
+
+- **Import** auto-creates plan as `active`
+- **Manual** creates plan as `approved`
+- Mark completed when all derived work is done:
+
+```bash
+kspec plan set @plan --status completed
+```
+
+## Programmatic Alternative: Batch
+
+For fully programmatic creation (scripts, agent pipelines):
+
+```bash
+kspec batch --commands '[
+  {"command":"item add","args":{"under":"@parent","title":"Feature X","type":"feature","slug":"feature-x"}},
+  {"command":"item ac add","args":{"ref":"@feature-x","given":"...","when":"...","then":"..."}},
+  {"command":"derive","args":{"ref":"@feature-x"}}
+]'
+```
+
+Atomic — all succeed or all roll back. Use `--dry-run` to preview.
+
+## Command Reference
+
+```bash
+# Design phase
+kspec workflow start @spec-plan-design
+
+# Import path
+kspec plan import <path> --module @module --dry-run   # Preview
+kspec plan import <path> --module @module             # Create
+kspec plan import <path> --module @module --update    # Re-import
+
+# Manual path
+kspec plan add --title "..." --content "..." --status approved
+kspec plan get <ref>
+kspec plan set <ref> --status <status>
+kspec plan note <ref> "..."
+kspec plan list
+
+# Validation
+kspec validate
+kspec validate --completeness
+kspec validate --alignment
+```
+
+## Integration
+
+- **`/kspec:writing-specs`** — Spec authoring details (types, AC format, traits)
+- **`/kspec:task-work`** — After specs are created, work on derived tasks
+- **`/kspec:triage`** — Inbox items may trigger plan creation
+- **`/kspec:observations`** — Friction during planning becomes observations

package/templates/skills/reflect/SKILL.md

@@ -0,0 +1,155 @@
+# Session Reflection
+
+Structured reflection at the end of a work session. Identifies learnings, friction points, and improvements — the raw material for system evolution.
+
+## When to Use
+
+- End of a work session (interactive or automated)
+- After completing a significant piece of work
+- When you notice recurring patterns worth capturing
+
+## Workflow
+
+### Interactive Mode
+
+```bash
+kspec workflow start @session-reflect
+```
+
+Six steps, guided by the workflow engine:
+
+1. **What Worked Well** — Identify effective practices
+2. **Friction Points** — Where things were harder than needed
+3. **Check Coverage** — Search for existing tracking before proposing new items
+4. **Propose Improvements** — Concrete ideas for untracked friction
+5. **Discussion** — Present to user, get approval one at a time
+6. **Capture** — Add approved items to inbox/observations
+
+Use `kspec workflow show` to see progress, `kspec workflow next --notes "..."` to advance.
+
+### Loop Mode (Automated)
+
+```bash
+kspec workflow start @session-reflect-loop
+```
+
+Key differences from interactive:
+- **High confidence only** — Only capture what you're certain about
+- **Search first** — MUST search before capturing anything
+- **No user prompts** — Skip discussion, auto-resolve
+- **Lower volume** — Better to capture nothing than capture noise
+- **Higher bar for tasks** — Prefer `inbox add` over `task add` without user confirmation
+
+## Gate: Is There Anything to Reflect On?
+
+Before starting, check if the session had meaningful work:
+
+1. **Tasks completed recently** — Any `completed_at` timestamps from the current session?
+2. **Code changes** — Any staged, unstaged, or untracked files?
+3. **Recent commits** — Any commits from the current session?
+
+**Skip reflection if** no tasks completed, working tree is clean, and no commits made. Don't manufacture reflection from nothing.
+
+## The Reflection Process
+
+### Step 1: What Worked Well
+
+Be specific — "categorizing items first" not "good planning."
+
+- Workflows that flowed smoothly
+- Tools or commands that helped
+- Decisions that proved correct
+- Patterns worth replicating
+
+### Step 2: Friction Points
+
+Focus on systemic issues, not one-off mistakes.
+
+- Repetitive manual steps
+- Missing commands or options
+- Context loss or re-explanation needed
+- Workarounds used
+
+### Step 3: Check Existing Coverage
+
+**Before proposing anything, search ALL sources:**
+
+```bash
+kspec search "<keyword>"  # Searches specs, tasks, AND inbox
+```
+
+For each friction point:
+- **Already tracked** — Reference the existing item, don't duplicate
+- **Partially covered** — Note what's missing
+- **Not tracked** — Candidate for capture
+
+### Step 4: Propose Improvements
+
+For untracked friction, propose:
+- What it would do
+- How it would help
+- Rough scope (small/medium/large)
+
+### Step 5: Discussion (Interactive Only)
+
+Present findings one at a time:
+- Is this worth capturing?
+- Any refinements?
+- Related ideas from user perspective?
+
+### Step 6: Capture
+
+Route each item to the right destination:
+
+| What you found | Where | Why |
+|----------------|-------|-----|
+| Clear scope (know what and where) | `task add` | Ready to implement |
+| Unclear scope (vague, needs triage) | `inbox add` | Will be triaged later |
+| Systemic friction pattern | `meta observe friction` | Informs process improvement |
+| Success pattern | `meta observe success` | Worth documenting |
+| Behavior change needing spec work | Ask user | May need spec-first workflow |
+
+**Inbox vs Task:** Can you describe the change and where it goes? Use `task add`. Only use inbox when scope is genuinely unclear.
+
+When capturing 2+ items, use `kspec batch`:
+
+```bash
+kspec batch --commands '[
+  {"command":"inbox add","args":{"text":"Improvement idea","tag":["reflection"]}},
+  {"command":"meta observe","args":{"type":"friction","content":"Friction pattern"}},
+  {"command":"meta observe","args":{"type":"success","content":"Success pattern"}}
+]'
+```
+
+## Reflection Prompts
+
+Use these to surface insights:
+
+- **Process:** What did I repeat 3+ times? What workarounds did I use?
+- **Tools:** What command or flag did I wish existed?
+- **Communication:** Where was the user surprised? What should I have asked earlier?
+- **Learning:** What do I know now that I didn't at session start?
+
+## Key Principles
+
+- **Specific over general** — "No bulk AC add" not "CLI could be better"
+- **Systemic over incidental** — Focus on repeatable friction
+- **Ask don't assume** — User decides what's worth capturing (interactive mode)
+- **Brief on successes** — Friction points are the primary value
+- **Search before capture** — Never duplicate existing tracking
+
+## Workflow Commands
+
+```bash
+kspec workflow show           # Check current step
+kspec workflow next --notes "..."   # Advance with notes
+kspec workflow next --skip --notes "reason"  # Skip a step
+kspec workflow pause          # Pause for later
+kspec workflow resume         # Resume
+```
+
+## Integration
+
+- Observations created during reflection feed into `/kspec:triage observations`
+- Friction observations may be promoted to tasks via `kspec meta promote @ref`
+- Success patterns may inform AGENTS.md or convention updates

package/templates/skills/review/SKILL.md

@@ -0,0 +1,186 @@
+# Review
+
+Kspec-specific review concerns for verifying spec alignment, AC coverage, and trait coverage. A building block that projects reference in their own review skills and workflows.
+
+## When to Use
+
+- Before creating a PR — verify implementation meets spec
+- As part of a project-specific local review workflow
+- When reviewing code changes against acceptance criteria
+
+**This is NOT a complete review workflow.** It covers kspec-specific quality gates (spec alignment, AC coverage, trait coverage, validation). Projects should wrap this in their own review skill that adds project-specific concerns (test commands, E2E patterns, coding standards).
+
+## Spec Alignment
+
+Implementation must match spec intent, not just pass tests.
+
+### How to Verify
+
+```bash
+# Read the spec — all ACs (own + inherited)
+kspec item get @spec-ref
+```
+
+For each AC, verify:
+1. **Implementation exists** — Code handles the described behavior
+2. **Test exists** — A test validates the behavior
+3. **Behavior matches** — The test actually proves the AC, not just syntactically passes
+
+### What to Flag
+
+| Issue | Severity |
+|-------|----------|
+| AC has no implementation | MUST-FIX |
+| AC has no test | MUST-FIX |
+| Implementation deviates from spec | MUST-FIX |
+| Undocumented behavior (not in any AC) | SHOULD-FIX |
+| Spec is vague, implementation chose reasonable interpretation | Note it |
+
+## Own AC Coverage
+
+Every acceptance criterion on the spec MUST have at least one annotated test.
+
+### Annotation Format
+
+```javascript
+// AC: @spec-ref ac-N
+it('should validate input when given invalid data', () => { ... });
+```
+
+```python
+# AC: @spec-ref ac-N
+def test_validates_input():
+    ...
+```
+
+### Checking Coverage
+
+```bash
+# Get all ACs for the spec
+kspec item get @spec-ref
+
+# Search for annotations in test files
+# (adapt grep path to your project's test directories)
+grep -rn "// AC: @spec-ref" tests/
+```
+
+Each AC listed in the spec output must have a corresponding annotation. Missing annotations are MUST-FIX.
+
+## Trait AC Coverage
+
+When a spec implements traits, it inherits their ACs. Every inherited trait AC must also have test coverage.
+
+### How It Works
+
+```bash
+# kspec item get shows inherited ACs under "Inherited from @trait-slug" sections
+kspec item get @spec-ref
+```
+
+Each inherited AC needs a test annotated with the **trait's** ref, not the spec's ref:
+
+```javascript
+// AC: @trait-json-output ac-1
+it('should output valid JSON with --json flag', () => { ... });
+```
+
+### Checking Coverage
+
+```bash
+# kspec validate reports uncovered trait ACs
+kspec validate
+
+# Search for specific trait annotations
+grep -rn "// AC: @trait-json-output" tests/
+```
+
+Any "inherited trait AC(s) without test coverage" warning from `kspec validate` is a MUST-FIX blocker.
+
+### When a Trait AC Doesn't Apply
+
+If a trait AC genuinely doesn't apply to this spec, annotate it with a reason:
+
+```javascript
+// AC: @trait-json-output ac-3 — N/A: this command has no tabular output to format
+```
+
+The annotation must exist so coverage tooling can track it.
+
+### No Traits?
+
+If the spec has no traits (`kspec item get` shows no "Inherited from" sections), skip this step entirely.
+
+## Validation Integration
+
+```bash
+kspec validate
+```
+
+Validation catches spec-level issues:
+- Missing acceptance criteria on specs
+- Broken references (dangling `@slug`)
+- Missing descriptions
+- Uncovered trait ACs (the most common review finding)
+- Orphaned specs (no linked tasks)
+
+**Exit codes:** `0` = clean, `4` = errors, `6` = warnings only.
+
+Treat errors as MUST-FIX. Treat warnings as SHOULD-FIX (especially trait AC warnings).
+
+## Review Checklist
+
+Use this checklist when reviewing implementation against a spec:
+
+### MUST-FIX (Blocks PR)
+
+- [ ] Every own AC has at least one annotated test
+- [ ] Every inherited trait AC has at least one annotated test (or N/A annotation)
+- [ ] `kspec validate` reports no errors for this spec
+- [ ] Implementation matches spec behavior (not just syntactically correct tests)
+- [ ] No regressions — existing tests still pass
+
+### SHOULD-FIX
+
+- [ ] `kspec validate` warnings addressed (especially trait AC coverage)
+- [ ] Undocumented behavior has spec coverage or is flagged
+- [ ] Test annotations reference correct spec/trait refs
+
+### SUGGESTION
+
+- [ ] Tests are meaningful (would fail if feature breaks)
+- [ ] Prefer E2E over unit where practical
+- [ ] Tests run in isolation (temp dirs, not project repo)
+
+## Severity Guide
+
+| Finding | Severity | Action |
+|---------|----------|--------|
+| Missing own AC test annotation | MUST-FIX | Add test with `// AC: @spec-ref ac-N` |
+| Missing trait AC test annotation | MUST-FIX | Add test with `// AC: @trait-slug ac-N` |
+| `kspec validate` error | MUST-FIX | Fix the validation error |
+| Implementation doesn't match spec | MUST-FIX | Fix implementation or update spec |
+| `kspec validate` warning | SHOULD-FIX | Address warning |
+| Undocumented behavior | SHOULD-FIX | Add AC or note deviation |
+| Test doesn't prove its AC | SHOULD-FIX | Rewrite test |
+| No E2E tests | SUGGESTION | Consider adding |
+
+## Using in Project Reviews
+
+This skill provides the kspec-specific gates. Wrap it in your project's review:
+
+```
+Project Review = kspec:review gates + project-specific gates
+```
+
+Project-specific gates to add in your own review skill:
+- **Test commands** — How to run your test suite
+- **Test patterns** — Project-specific test helpers and isolation patterns
+- **Code style** — Naming, error handling, import conventions
+- **E2E specifics** — How E2E tests work in your project
+- **Regression check** — Full suite command and expectations
+
+## Integration
+
+- **`/kspec:task-work`** — Run review before submitting tasks
+- **`/kspec:writing-specs`** — If review reveals spec gaps, update specs first
+- **`kspec validate`** — Automated validation complements manual review