@kynetic-ai/spec 0.1.2 → 0.3.0

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

@@ -0,0 +1,206 @@
+---
+name: triage
+description: Triage inbox items systematically. Records decisions with audit
+  trail, then executes actions. Supports inbox, observations, and automation
+  eligibility triage.
+---
+<!-- kspec-managed -->
+# Triage
+
+Systematically process items: inbox, observations, or automation eligibility.
+
+## Focus Modes
+
+Use `/triage <mode>` to focus on a specific area:
+
+| Mode | Purpose | Documentation |
+|------|---------|---------------|
+| `inbox` | Process inbox items → specs/tasks | [docs/inbox.md](docs/inbox.md) |
+| `observations` | Process pending observations | [docs/observations.md](docs/observations.md) |
+| `automation` | Assess task automation eligibility | [docs/automation.md](docs/automation.md) |
+
+Without a mode, follow the full triage session pattern below.
+
+## Core Concept: Record → Act
+
+Triage uses a **two-step pattern** that separates decision-making from execution:
+
+1. **Record** the decision (what to do + why)
+2. **Act** on the decision (execute it)
+
+This separation 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
+```
+
+## Full Session Pattern
+
+1. **Get context**
+   ```bash
+   kspec session start --full
+   kspec inbox list
+   kspec meta observations --pending-resolution
+   kspec tasks assess automation
+   ```
+
+2. **Present overview to user**
+   - Inbox items by category
+   - Pending observations by type
+   - Unassessed tasks needing triage
+
+3. **Ask which focus area**
+   - Inbox items
+   - Observations
+   - Automation eligibility
+
+4. **Process that focus area**
+   - Use the relevant sub-document for guidance
+
+5. **Repeat or stop** when user indicates
+
+## Quick Start by Mode
+
+### `/triage inbox`
+
+Process inbox items using the record → act pattern. See [docs/inbox.md](docs/inbox.md).
+
+```bash
+kspec inbox list
+
+# Interactive mode: triage all untriaged items one by one
+kspec triage start
+
+# Or record decisions individually
+kspec triage record @ref --action promote --reasoning "Clear feature need"
+kspec triage record @ref --action delete --reasoning "Outdated"
+kspec triage record @ref --action defer --reasoning "Not ready yet"
+kspec triage record @ref --action spec-gap --reasoning "Missing spec coverage"
+kspec triage record @ref --action duplicate --reasoning "Covered by @other-ref"
+
+# Then execute recorded decisions
+kspec triage act @triage-ref
+kspec triage act @triage-ref --dry-run  # Preview first
+```
+
+### `/triage observations`
+
+Process pending observations. See [docs/observations.md](docs/observations.md).
+
+```bash
+kspec meta observations --pending-resolution
+# For each: resolve, promote to task, or leave
+kspec meta resolve @ref "Resolution notes"
+kspec meta resolve @ref1 @ref2 "Batch resolution"
+kspec meta observations promote @ref --title "..."
+```
+
+### `/triage automation`
+
+Assess task automation eligibility. See [docs/automation.md](docs/automation.md).
+
+```bash
+kspec tasks assess automation
+# Review criteria, fix issues, or mark status
+kspec task set @ref --automation eligible
+kspec task set @ref --automation needs_review --reason "..."
+```
+
+## Triage Commands Reference
+
+### Recording Decisions
+
+```bash
+# Record a triage decision for an inbox item
+kspec triage record @inbox-ref --action <action> --reasoning "why"
+kspec triage record @inbox-ref --action promote --reasoning "..." --evidence @spec-ref
+kspec triage record @inbox-ref --action promote --reasoning "..." --json  # JSON output
+
+# Interactive mode: presents untriaged items one at a time
+kspec triage start
+# Ctrl+C preserves all previously committed records
+```
+
+### Reviewing Decisions
+
+```bash
+# List all triage records
+kspec triage list
+kspec triage list --status triaged         # Only pending execution
+kspec triage list --status acted_on        # Already executed
+kspec triage list --action promote         # Filter by action type
+
+# Get details of a specific record
+kspec triage get @triage-ref
+
+# Export for agent handoff
+kspec triage export --format context       # Markdown context blocks
+kspec triage export --format json          # Full JSON array
+```
+
+### Executing and Overriding
+
+```bash
+# Execute a recorded decision
+kspec triage act @triage-ref
+kspec triage act @triage-ref --dry-run     # Preview without executing
+
+# Override a previous decision (preserves audit trail)
+kspec triage override @triage-ref --action defer --reasoning "Not ready yet"
+# Then act on the updated decision
+kspec triage act @triage-ref
+```
+
+## Bulk Operations with Batch
+
+When processing many items at once, use `kspec batch`:
+
+```bash
+# Record multiple triage decisions atomically
+kspec batch --commands '[
+  {"command":"triage record","args":{"ref":"@ref1","action":"delete","reasoning":"Stale"}},
+  {"command":"triage record","args":{"ref":"@ref2","action":"delete","reasoning":"Duplicate"}},
+  {"command":"triage record","args":{"ref":"@ref3","action":"promote","reasoning":"Clear scope"}}
+]'
+```
+
+Use `--dry-run` to preview. See `/kspec:help` for full batch documentation.
+
+## Key Principles
+
+- **Record before act** - Separate decisions from execution for audit trail
+- **Ask one question at a time** - Don't batch decisions
+- **Spec before task** - Fill spec gaps before creating tasks
+- **AC is required** - Specs without acceptance criteria are incomplete
+- **Use CLI, not YAML** - All changes through kspec commands
+- **Delete freely** - Outdated 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

package/plugin/plugins/kspec/skills/triage/docs/automation.md

@@ -0,0 +1,120 @@
+# Automation Triage
+
+Assess and prepare tasks for automation eligibility. Goal: make tasks self-contained so they can be automated.
+
+## Philosophy
+
+- **Eligible is the goal** - Manual-only should be the exception
+- **Criteria are for visibility** - Help identify what's missing, not auto-approve
+- **Fix issues, don't just assess** - Guide toward making tasks automatable
+
+## Eligibility Criteria
+
+A task is ready for automation when:
+1. Has `spec_ref` pointing to resolvable spec
+2. Spec has acceptance criteria (testable outcomes)
+3. Task type is not `spike` (spikes output knowledge, not code)
+
+**Having spec + ACs is necessary but not sufficient** - you must also verify the spec is appropriate and ACs are adequate for the task.
+
+**Task type does not determine automation eligibility.** Any non-spike task can be `automation: eligible` — including design tasks, refactoring tasks, documentation tasks, etc. The `automation` field is the definitive source. Once a task is marked `eligible`, do not second-guess it based on type, title, or description.
+
+## Workflow
+
+### 1. Get Assessment Overview
+
+```bash
+# Show unassessed pending tasks with criteria status
+kspec tasks assess automation
+
+# See what auto mode would change
+kspec tasks assess automation --auto --dry-run
+```
+
+### 2. Process Each Task
+
+For each task shown:
+
+**If spike:**
+- Mark `manual_only` - spikes are inherently human work
+- `kspec task set @ref --automation manual_only --reason "Spike - output is knowledge"`
+
+**If missing spec_ref or no ACs:**
+- Ask: "Fix now or mark for later?"
+- **Fix now:**
+  1. Create or find appropriate spec: `kspec item add --under @parent --title "..."`
+  2. Add acceptance criteria: `kspec item ac add @spec --given "..." --when "..." --then "..."`
+  3. Link task to spec: `kspec task set @ref --spec-ref @spec`
+  4. Re-assess and mark eligible if appropriate
+- **Mark for later:**
+  - `kspec task set @ref --automation needs_review --reason "Missing spec - needs spec creation"`
+
+**If has spec + ACs:**
+- Review for eligibility:
+  - Is the spec appropriate for this task?
+  - Are the ACs adequate and testable?
+  - Does the task have sufficient context?
+- If yes: `kspec task set @ref --automation eligible`
+- If no: Fix issues or mark `needs_review` with specific reason
+
+### 3. Batch Processing with Auto Mode
+
+For fast triage of obvious cases:
+
+```bash
+# Apply auto mode (spikes → manual_only, missing → needs_review)
+kspec tasks assess automation --auto
+
+# Then manually review the "review_for_eligible" tasks
+kspec tasks ready --unassessed
+```
+
+Auto mode is conservative:
+- Spikes → `manual_only`
+- Missing spec/ACs → `needs_review`
+- Has spec + ACs → **NOT auto-marked** (requires review)
+
+## Quick Commands
+
+```bash
+# Assessment
+kspec tasks assess automation              # Show unassessed with criteria
+kspec tasks assess automation @ref         # Single task
+kspec tasks assess automation --all        # Include already-assessed
+kspec tasks assess automation --auto       # Apply obvious cases
+kspec tasks assess automation --dry-run    # Preview changes
+
+# Setting automation status
+kspec task set @ref --automation eligible
+kspec task set @ref --automation needs_review --reason "Why"
+kspec task set @ref --automation manual_only --reason "Why"
+kspec task set @ref --no-automation        # Clear to unassessed
+
+# Filtering tasks
+kspec tasks ready --unassessed             # Tasks needing assessment
+kspec tasks ready --eligible               # Automation-ready tasks
+kspec tasks ready --needs-review           # Tasks needing human triage
+```
+
+## Assessment Output
+
+```
+@task-slug  "Task title"
+  spec_ref:     ✓ @feature-slug
+  has_acs:      ✓ 3 acceptance criteria
+  not_spike:    ✓ type: task
+  → review_for_eligible (verify spec/AC adequacy)
+```
+
+| Recommendation | Meaning | Auto Mode Action |
+|----------------|---------|------------------|
+| `review_for_eligible` | Passes criteria, needs review | No change (manual review) |
+| `needs_review` | Missing spec or ACs | Sets `needs_review` with reason |
+| `manual_only` | Spike task | Sets `manual_only` |
+
+## Key Principles
+
+- **CLI doesn't auto-mark eligible** - Requires agent/human review
+- **Agents CAN mark eligible** - When reviewing based on user instruction
+- **Add notes when setting status** - Document the "why"
+- **Re-assess after fixes** - After adding spec/ACs, check again

package/plugin/plugins/kspec/skills/triage/docs/inbox.md

@@ -0,0 +1,144 @@
+# Inbox Triage
+
+Process inbox items systematically using the **record → act** pattern: record a decision with reasoning, then execute it.
+
+## 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
+
+If a decision needs changing before or after execution:
+
+```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
+```
+
+### 6. Spec-First Processing
+
+For behavior changes, check spec coverage before promoting:
+
+1. **Check coverage**: `kspec item list | grep <relevant>`
+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
+   ```
+
+### 7. 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
+
+## 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 Processing with Batch
+
+When triaging many items, use `kspec batch` to record decisions in bulk:
+
+```bash
+# Record multiple decisions atomically
+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** - Decisions are separated from execution
+- **Ask one question at a time** - Use AskUserQuestion for decisions
+- **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

package/plugin/plugins/kspec/skills/triage/docs/observations.md

@@ -0,0 +1,85 @@
+# Observations Triage
+
+Process pending observations: evaluate, resolve, or promote to tasks.
+
+## Workflow
+
+### 1. List Pending Observations
+
+```bash
+kspec meta observations --pending-resolution
+```
+
+### 2. Process by Type
+
+| Type | How to Process |
+|------|----------------|
+| **friction** | Does it reveal a spec gap? → Create spec or inbox item. If already addressed → resolve |
+| **success** | Document in relevant spec or AGENTS.md if broadly useful → resolve |
+| **question** | Answer it if you can. If needs investigation → promote to task |
+| **idea** | Evaluate scope. Clear → inbox or task. Unclear → leave or delete |
+
+### 3. Processing Commands
+
+```bash
+# Promote observation to task (when actionable work is clear)
+kspec meta observations promote @ref --title "Add bulk AC command" --priority 2
+
+# Resolve observation (when addressed or no longer relevant)
+kspec meta resolve @ref "Resolution notes"
+kspec meta resolve @ref1 @ref2 "Batch resolution"
+
+# Convert inbox item to observation (if it's friction, not a task)
+kspec meta observe --from-inbox @ref
+```
+
+## When to Use Which
+
+- **Inbox** = future work that becomes tasks
+- **Observations** = systemic patterns that inform improvements
+- **Tasks** = clear, actionable implementation work
+
+## Decision Flow
+
+```
+For each observation:
+├─ Still relevant?
+│   ├─ No → resolve with note
+│   └─ Yes → Does it need action?
+│       ├─ No (just learning) → resolve after documenting
+│       └─ Yes → Is scope clear?
+│           ├─ Yes → promote to task
+│           └─ No → add to inbox for later triage
+```
+
+## Bulk Resolution with Batch
+
+When resolving many observations at once, use `kspec batch`:
+
+```bash
+kspec batch --commands '[
+  {"command":"meta resolve","args":{"ref":"@obs1","resolution":"Fixed in PR #100"}},
+  {"command":"meta resolve","args":{"ref":"@obs2","resolution":"No longer relevant"}},
+  {"command":"meta resolve","args":{"refs":["@obs3","@obs4"],"resolution":"Addressed by new workflow"}}
+]'
+```
+
+Use `--dry-run` to preview. See `/kspec:help` for full batch documentation.
+
+## Common Patterns
+
+| Pattern | Action |
+|---------|--------|
+| Friction already fixed | Verify fix → resolve with note |
+| Friction needs work | Check spec → create if needed → promote or inbox |
+| Success pattern | Document in AGENTS.md or relevant spec → resolve |
+| Open question | Answer if possible → resolve. If needs investigation → promote |
+| Idea with clear scope | Promote to task or inbox |
+| Vague idea | Leave or delete if stale |
+
+## Key Principles
+
+- **Observations capture learning** - Not just todos
+- **Friction informs improvement** - Turn pain points into better specs
+- **Success patterns are worth documenting** - Help future sessions
+- **Questions should get answers** - Don't let them linger

package/templates/agents-sections/01-quick-start.md

@@ -0,0 +1,22 @@
+## Quick Start
+
+```bash
+# First time setup
+kspec init            # Initialize kspec in the project
+kspec setup           # Configure agent environment
+
+# Returning to work
+kspec session start   # Get session context
+```
+
+Verify shadow branch health with `kspec shadow status` if you encounter issues.
+
+## Essential Rules
+
+1. **Use CLI, not manual YAML edits** — Never manually edit files in `.kspec/`. CLI auto-commits to shadow branch.
+2. **Spec before code** — If changing behavior, check spec coverage. Update spec first if needed.
+3. **Add notes** — Document what you do in task notes for audit trail.
+4. **Check dependencies** — Tasks have `depends_on` relationships; complete prerequisites first.
+5. **Always confirm** — Ask before creating or modifying spec items.
+6. **Batch mutations** — Use `kspec batch` for 2+ sequential write operations (one atomic commit).
+7. **Regenerate agent instructions** — Run `kspec agents generate` after changing conventions, workflows, or skills. These are the inputs to `kspec-agents.md`.

package/templates/agents-sections/02-shadow-branch.md

@@ -0,0 +1,34 @@
+## Shadow Branch Architecture
+
+`.kspec/` is NOT a regular directory — it's a **git worktree** on an orphan branch (`kspec-meta`).
+
+```
+.kspec/.git → file pointing to worktree
+  ↓
+gitdir: .git/worktrees/-kspec
+  ↓
+Shadow branch (kspec-meta): orphan branch with spec/task files
+```
+
+**Why:** Spec/task changes don't clutter main branch history. Code PRs and spec changes tracked independently.
+
+**How it works:** Every `kspec` command auto-commits to `kspec-meta`. Auto-pushes to remote if tracking configured. Main branch gitignores `.kspec/`.
+
+**CRITICAL: Always run kspec from project root, never from inside `.kspec/`.** If you see "Cannot run kspec from inside .kspec/ directory", check `pwd`.
+
+### Shadow Branch Commands
+
+```bash
+kspec shadow status   # Verify health
+kspec shadow repair   # Fix broken worktree
+kspec shadow sync     # Sync with remote
+```
+
+### Troubleshooting
+
+| Issue | Fix |
+|-------|-----|
+| `.kspec/` doesn't exist | `kspec init` |
+| Worktree disconnected | `kspec shadow repair` |
+| Sync conflicts | `kspec shadow resolve` |
+| Commands seem broken | Check `pwd` — must be project root |

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

@@ -0,0 +1,48 @@
+## Task Lifecycle
+
+### Key Concepts
+
+Every item has a ULID (canonical) and slug (human-friendly). References use `@` prefix: `@task-slug` or `@01JHNKAB`.
+
+**Spec items** (`.kspec/modules/*.yaml`): Define WHAT to build
+**Tasks** (`.kspec/project.tasks.yaml`): Track the WORK of building
+
+Tasks reference specs via `spec_ref`. They don't duplicate spec content.
+
+### Task States
+
+```
+pending → in_progress → pending_review → completed
+              ↓              ↓
+          blocked ←──────────┘
+              ↓          needs_work
+          cancelled     (fix cycle: → in_progress → pending_review)
+```
+
+See `kspec help task` for transition commands and options.
+
+### Spec-First Development
+
+**Core principle**: If you're changing behavior and the spec doesn't cover it, update the spec first.
+
+| Situation | Flow |
+|-----------|------|
+| Clear behavior change | Check spec → Update/create spec → Derive task |
+| Vague idea, unclear scope | Capture in inbox → Triage later |
+| Infra/internal (no user impact) | Create task directly, no spec needed |
+| Bug revealing spec gap | Fix bug → Update spec to match reality |
+
+### 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`
+
+### Staying Aligned During Work
+
+**Watch for scope expansion:**
+- Modifying files outside your current task
+- Adding functionality the spec doesn't mention
+- "While I'm here, I should also..." thoughts
+
+**When you notice something outside your task:** Capture it separately (inbox item, new task, or observation). Add a note to your current task documenting what you found. Don't fix it inline — even small detours compound into drift. Stay on your task.

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

@@ -0,0 +1,17 @@
+## PR Workflow
+
+Before creating a PR, mark the task: `kspec task submit @ref` (transitions to `pending_review`).
+
+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`.
+
+**Quality gates (never skip without explicit approval):**
+- All CI checks passing
+- All review comments addressed
+- All review threads resolved
+- AC coverage verified
+
+**After merge:** `kspec task complete @ref --reason "Merged in PR #N. Summary..."`