@kynetic-ai/spec 0.3.0 → 0.5.0

package/plugin/plugins/kspec/skills/triage-inbox/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: triage-inbox
+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.
+---
+<!-- kspec-managed -->
+# Inbox Triage
+
+Systematically process inbox items using the **record → act** pattern. Records decisions with audit trail, then executes actions.
+
+## When to Use
+
+- Processing accumulated inbox items
+- During a triage session (`kspec workflow start @inbox-triage`)
+- When inbox count is growing and needs attention
+
+## Core Concept: Record → Act
+
+Triage separates **decision-making** from **execution**:
+
+1. **Record** the decision (what to do + why)
+2. **Act** on the decision (execute it)
+
+This enables review, override, and audit trails.
+
+```bash
+# Step 1: Record what you want to do
+kspec triage record @inbox-ref --action promote --reasoning "Clear feature request"
+
+# Step 2: Execute the decision
+kspec triage act @triage-ref
+```
+
+### Actions
+
+| Action | What `act` does |
+|--------|-----------------|
+| `promote` | Creates task from inbox item snapshot |
+| `delete` | Deletes the inbox item |
+| `defer` | Records deferral, no side effect |
+| `spec-gap` | Creates observation tagged spec-gap |
+| `duplicate` | Deletes the inbox item |
+
+### Lifecycle
+
+```
+record (with action)     override (optional)     act
+    → triaged        →       triaged         →  acted_on
+```
+
+## Workflow
+
+### 1. Gather Context
+
+```bash
+kspec session start --full
+kspec inbox list
+```
+
+### 2. Categorize Items
+
+Group inbox items by type:
+- **Bugs** — implementation issues, errors
+- **Spec gaps** — missing or incomplete specs
+- **Quick wins** — small, well-defined improvements
+- **Larger features** — need plan mode to design
+- **Process/workflow** — meta improvements
+- **Delete candidates** — outdated, duplicates, already done
+
+Present categories to user for alignment.
+
+### 3. Triage Each Item
+
+**Interactive mode** (recommended for multiple items):
+
+```bash
+kspec triage start
+# Presents untriaged items one by one
+# Prompts for action + reasoning
+# Ctrl+C preserves all previously committed records
+```
+
+**Individual recording** (for targeted decisions):
+
+```bash
+kspec triage record @ref --action promote --reasoning "Clear feature request with spec coverage"
+kspec triage record @ref --action delete --reasoning "Already implemented in PR #123"
+kspec triage record @ref --action defer --reasoning "Depends on auth system redesign"
+kspec triage record @ref --action spec-gap --reasoning "No spec covers error handling for this flow"
+kspec triage record @ref --action duplicate --reasoning "Covered by @existing-spec"
+```
+
+### 4. Review and Execute Decisions
+
+```bash
+# Review what was recorded
+kspec triage list --status triaged
+
+# Preview before executing
+kspec triage act @triage-ref --dry-run
+
+# Execute decisions
+kspec triage act @triage-ref
+```
+
+### 5. Override If Needed
+
+```bash
+# Override changes the action while preserving the audit trail
+kspec triage override @triage-ref --action defer --reasoning "Reconsidered - not ready"
+
+# Then act on the updated decision
+kspec triage act @triage-ref
+```
+
+## Spec-First Processing
+
+For behavior changes, check spec coverage before promoting:
+
+1. **Check coverage**: `kspec search "<relevant keyword>"` or `kspec item get @ref`
+2. **Identify gaps**: Does spec have description AND acceptance criteria?
+3. **Update spec**:
+   ```bash
+   kspec item set @ref --description "..."
+   kspec item ac add @ref --given "..." --when "..." --then "..."
+   ```
+4. **Record and act**:
+   ```bash
+   kspec triage record @inbox-ref --action promote --reasoning "Spec updated" --evidence @spec-ref
+   kspec triage act @triage-ref
+   ```
+
+## Plan Mode for Larger Items
+
+When an item needs design work:
+
+1. Enter plan mode
+2. Explore codebase for patterns/context
+3. Design spec structure and implementation approach
+4. Write plan, exit for approval
+5. Execute: create spec, add AC, derive task
+
+## Observation Processing
+
+During triage sessions, you may also process pending observations:
+
+```bash
+kspec meta observations --pending-resolution
+```
+
+For each observation:
+
+| Type | How to Process |
+|------|----------------|
+| **friction** | Reveals spec gap? → Create spec or inbox item. Already addressed? → Resolve |
+| **success** | Document in relevant spec or AGENTS.md if broadly useful → Resolve |
+| **question** | Answer if you can. Needs investigation? → Promote to task |
+| **idea** | Clear scope? → Inbox or task. Unclear? → Leave or delete if stale |
+
+```bash
+# Promote observation to task
+kspec meta promote @ref --title "Add bulk AC command" --priority 2
+
+# Resolve observation
+kspec meta resolve @ref "Resolution notes"
+kspec meta resolve --refs @ref1 @ref2 --resolution "Batch resolution"
+
+# Convert inbox item to observation (if it's a pattern, not a task)
+kspec meta observe --from-inbox @ref
+```
+
+## Export for Context
+
+Share triage decisions with other agents or sessions:
+
+```bash
+# Markdown context blocks (for agent handoff)
+kspec triage export --format context
+
+# Full structured data
+kspec triage export --format json
+```
+
+## Bulk Operations with Batch
+
+When triaging many items, use `kspec batch` for atomic operations:
+
+```bash
+kspec batch --commands '[
+  {"command":"triage record","args":{"ref":"@ref1","action":"delete","reasoning":"Stale"}},
+  {"command":"triage record","args":{"ref":"@ref2","action":"promote","reasoning":"Clear scope"}}
+]'
+```
+
+Use `--dry-run` to preview. See `/kspec:help` for full batch documentation.
+
+## Common Patterns
+
+| Pattern | Action |
+|---------|--------|
+| Already implemented | Verify impl exists → check spec gaps → record delete |
+| Duplicate of existing | Verify original covers scope → record duplicate |
+| Small flag/option | Update spec + AC → record promote |
+| New command | Plan mode → design spec → record promote with evidence |
+| Bug report | Check spec coverage → update spec → record promote |
+| Vague idea | Record defer, or leave untriaged for later |
+| Missing spec | Record spec-gap → creates observation for follow-up |
+
+## Key Principles
+
+- **Record before act** — Separate decisions from execution for audit trail
+- **Ask one question at a time** — Don't batch decisions in interactive mode
+- **Spec before task** — Fill spec gaps before promoting to tasks
+- **AC is required** — Specs without acceptance criteria are incomplete
+- **Use CLI, not YAML** — All changes through kspec commands
+- **Delete freely** — Outdated or duplicate items should go
+
+## Progress Tracking
+
+At session end, provide summary:
+- Items triaged (recorded decisions)
+- Actions executed (promoted, deleted, deferred, spec-gap, duplicate)
+- Tasks created/updated
+- Observations resolved
+- Remaining items
+
+## Integration
+
+- **`/kspec:reflect`** — Session reflection may generate inbox items for triage
+- **`/kspec:observations`** — Captures systemic patterns found during triage
+- **`kspec session start`** — Shows inbox count for triage awareness

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

@@ -0,0 +1,354 @@
+---
+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`).
+
+## Finding Things
+
+Use CLI commands to discover and inspect specs. **Do NOT search `.kspec/` YAML files manually.**
+
+| Need | Command |
+|------|---------|
+| View spec + all ACs | `kspec item get @ref` |
+| Search by keyword | `kspec search "keyword"` |
+| List by type | `kspec item list --type feature` |
+| All modules | `kspec item list --type module` |
+| All traits | `kspec trait list` |
+| Trait details + ACs | `kspec item get @trait-slug` |
+| Items under a parent | `kspec item list --under @parent` |
+
+## 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/agents-sections/05-commit-convention.md

@@ -25,3 +25,17 @@ def test_validates_input():
 ```
 
 Every AC SHOULD have at least one test with this annotation.
+
+### N/A Trait ACs
+
+When a trait AC doesn't apply to a specific spec, annotate it as N/A with a reason:
+
+```javascript
+// AC: @trait-slug ac-N — N/A: reason why it doesn't apply
+```
+
+```python
+# AC: @trait-slug ac-N — N/A: reason why it doesn't apply
+```
+
+Group N/A annotations together in a dedicated test or at the top of the test file. The `AC:` annotation marker with language-appropriate comment prefix is required — do not use prose comments or bullet lists. The annotation must be machine-parseable.