Kspec

Kspec - Task & Spec Management

Kspec is the task and specification management system for this project. Always use CLI commands, never manually edit YAML files.

Quick Start

# Session context (run first!)
kspec session start

# Task workflow
kspec task start @task-slug
kspec task note @task-slug "What you did..."
kspec task complete @task-slug --reason "Summary"

# View tasks
kspec tasks ready          # What can be worked on
kspec task get @task-slug  # Full details

# Capture ideas (not yet tasks)
kspec inbox add "idea or thought"
kspec inbox promote @ref --title "Task title"

# Create task directly
kspec task add --title "Title" --priority 2

Session Context

Setting Focus

When starting work on a specific area:

# Set focus
kspec meta focus "working on CLI improvements"

# Check current focus
kspec meta focus

# Clear when done
kspec meta focus --clear

Managing Threads

Track parallel work streams:

# Add thread
kspec meta thread --add "debugging test failures"

# List threads
kspec meta thread --list

# Remove when done (0-indexed)
kspec meta thread --remove 0

Open Questions

Track questions that need answers:

# Add question
kspec meta question --add "Should we validate on parse or execute?"

# List questions
kspec meta question --list

# Remove when answered
kspec meta question --remove 0

Task Lifecycle

Start -> Note -> Complete

The standard workflow:

# 1. Start the task
kspec task start @task-slug

# 2. Add notes as you work (not just at the end)
kspec task note @task-slug "Exploring approach X..."
kspec task note @task-slug "Decided to use Y because Z"

# 3. Complete with summary
kspec task complete @task-slug --reason "Implemented X with approach Y"

Blocking and Unblocking

When external dependencies appear:

# Block with reason
kspec task block @task-slug --reason "Waiting on API spec"

# Work on other tasks...

# Unblock when ready
kspec task unblock @task-slug

In loop mode: Block only for genuine external blockers (human decision needed, spec gap, external dependency). Complexity and difficulty are NOT blockers — push through. You MUST verify by running kspec tasks ready --eligible before stopping — its output is authoritative. Do not infer task eligibility; the command is the source of truth. See /task-work for detailed loop mode guidance.

Cancellation

When a task is no longer needed:

kspec task cancel @task-slug --reason "Superseded by @other-task"

Deletion

Permanent removal (use sparingly):

# Preview first
kspec task delete @task-slug --dry-run

# Delete
kspec task delete @task-slug --force

Finding Work

Ready Tasks

Tasks that can be started now (no blockers, dependencies met):

kspec tasks ready
kspec tasks ready -v        # More details
kspec tasks ready --full    # Full details including notes

Blocked Tasks

Tasks waiting on dependencies:

kspec tasks blocked

Active Work

Tasks currently in progress (should be 0-1):

kspec tasks in-progress
# or
kspec tasks active

Next Task

Highest priority ready task:

kspec tasks next

Filtered Queries

Find specific tasks:

# By status
kspec tasks list --status pending
kspec tasks list --status completed

# By tag
kspec tasks list --tag mvp
kspec tasks list --tag bug

# By type
kspec tasks list --type bug
kspec tasks list --type spike

# Combined filters
kspec tasks list --status pending --tag mvp

# Search in content
kspec tasks list --grep "authentication"

Inbox Workflow

Quick Capture

For ideas without clear scope:

kspec inbox add "maybe we need better error handling"
kspec inbox add "refactor auth flow" --tag auth --tag refactor

Triage

List oldest first (encourages processing):

kspec inbox list

# Filter by tag
kspec inbox list --tag refactor

# Newest first
kspec inbox list --newest

Promotion

Convert to task when scope is clear:

# Basic
kspec inbox promote @ref --title "Improve error handling"

# With full context
kspec inbox promote @ref \
  --title "Add retry logic to API client" \
  --priority 2 \
  --spec-ref @api-client \
  --tag reliability

Deletion

Remove if no longer relevant:

kspec inbox delete @ref

Convert to Observation

If it's a friction point rather than a task:

kspec meta observe --from-inbox @ref

Spec Operations

Viewing Specs

# Get specific item
kspec item get @spec-slug

# List with filters
kspec item list --type feature
kspec item list --tag cli
kspec item list --status implemented

# Search
kspec search "validation"

Updating Specs

# Update fields
kspec item set @spec-slug --description "Updated description"
kspec item set @spec-slug --status implemented
kspec item set @spec-slug --tag new-tag

# JSON patch for complex updates
kspec item patch @spec-slug --data '{"priority": "high"}'

# Preview changes
kspec item patch @spec-slug --data '{"priority": "high"}' --dry-run

Acceptance Criteria

# List AC
kspec item ac list @spec-slug

# Add AC
kspec item ac add @spec-slug \
  --given "User runs command with --json" \
  --when "Command succeeds" \
  --then "Output is valid JSON"

# Update AC
kspec item ac set @spec-slug ac-1 --then "Output includes error field"

# Remove AC
kspec item ac remove @spec-slug ac-1 --force

Creating Specs

# Add under parent
kspec item add \
  --under @parent-slug \
  --title "New Feature" \
  --type feature \
  --slug new-feature

# Add requirement under feature
kspec item add \
  --under @new-feature \
  --title "Specific Requirement" \
  --type requirement

Deriving Tasks

Create implementation tasks from specs:

# Preview first (recommended)
kspec derive @spec-slug --dry-run

# Recursive (default) - includes children
kspec derive @spec-slug

# Flat - only this spec
kspec derive @spec-slug --flat

# All specs without tasks
kspec derive --all

Task Updates

Setting Fields

# Update title
kspec task set @task-slug --title "New title"

# Update priority
kspec task set @task-slug --priority 1

# Add tags
kspec task set @task-slug --tag urgent --tag bug

# Add dependency
kspec task set @task-slug --depends-on @other-task

# Link to spec
kspec task set @task-slug --spec-ref @spec-item

JSON Patch

For complex updates:

# Single update
kspec task patch @task-slug --data '{"priority": 1, "tags": ["urgent"]}'

# Preview
kspec task patch @task-slug --data '{"priority": 1}' --dry-run

Creating Tasks

Minimal

kspec task add --title "Fix the bug"

Full

kspec task add \
  --title "Implement feature X" \
  --spec-ref @spec-item \
  --priority 2 \
  --slug feature-x \
  --tag feature --tag mvp

With Dependencies

kspec task add \
  --title "Build on previous work" \
  --depends-on @prerequisite-task

Validation

# Full validation
kspec validate

# References only
kspec validate --refs

# Schema only
kspec validate --schema

# Auto-fix issues
kspec validate --fix

Key Principles

1. Use CLI, not manual YAML - Commands maintain consistency
2. Add notes liberally - Future context depends on it
3. Track your work - Start tasks before working, complete when done
4. Spec is source of truth - Code implements what spec defines
5. Inbox for unclear scope - Promote to task when ready

Running kspec

For normal usage (after npm link):

kspec session start
kspec tasks ready

For testing source changes (no build needed):

npm run dev -- session start
npm run dev -- tasks ready

Use kspec for day-to-day work. Use npm run dev when modifying the CLI itself and testing changes before building.

After source changes, run npm run build to update the kspec command.

Environment

• KSPEC_AUTHOR - Attribution for notes (e.g., @claude)
• Run kspec setup to configure automatically

Related Skills

• /meta - Session context management (focus, threads, questions, observations)
• /triage - Systematic inbox processing
• /spec-plan - Translate plans to specs
• /reflect - Session reflection and learning capture