@kynetic-ai/spec 0.1.2 → 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/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 `/kspec:triage`
+- **Learning/friction?** → `kspec meta observe friction "..."` → review during reflection
+
+### 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. **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
+- All review comments addressed
+- All review threads resolved
+- AC coverage verified
+
+**After merge:** `kspec task complete @ref --reason "Merged in PR #N. Summary..."`

package/templates/agents-sections/05-commit-convention.md

@@ -0,0 +1,27 @@
+## Commit Convention
+
+```
+feat: Feature description
+
+Task: @task-slug
+Spec: @spec-ref
+```
+
+Trailers enable `kspec log @ref` to find commits by task or spec.
+
+## Code Annotations
+
+Link tests to acceptance criteria using language-appropriate comment syntax:
+
+```javascript
+// AC: @spec-item ac-N
+it('should validate input', () => { ... });
+```
+
+```python
+# AC: @spec-item ac-N
+def test_validates_input():
+    ...
+```
+
+Every AC SHOULD have at least one test with this annotation.

package/templates/agents-sections/06-ralph-loop.md

@@ -0,0 +1,45 @@
+## Ralph Loop Mode
+
+When running in automated loop mode (ralph):
+
+### The Loop
+
+```
+for each iteration:
+  1. Ralph checks eligible tasks — if none, exits loop
+  2. Agent works on tasks, may create PR(s)
+  3. Agent stops responding (turn complete)
+  4. Ralph sends reflection prompt
+  5. Ralph processes pending_review via subagent
+  6. Continue
+```
+
+**When you stop responding, ralph continues automatically.** Do NOT call `end-loop` after creating a PR.
+
+### Task Inheritance
+
+Priority: `needs_work` > `in_progress` > `pending`. Always inherit existing work before starting new tasks. (`pending_review` tasks are handled by the review subagent, not the worker.)
+
+### Blocking Rules
+
+**Block only for genuine external blockers:**
+- Requires human architectural decision
+- Needs spec clarification
+- Depends on external API/service not available
+- Formally blocked by `depends_on`
+
+**Do NOT block for:**
+- Task seems complex (do the work)
+- Tests are failing (fix them)
+- Service needs running (start it)
+- Another task's PR is in CI (not a formal dependency)
+
+**After blocking a task:**
+```bash
+kspec task block @task --reason "Reason..."
+kspec tasks ready --eligible
+# If tasks returned: work on next one
+# If empty: stop responding — ralph auto-exits
+```
+
+**One blocked task is NOT "no more work."** `kspec tasks ready --eligible` output is authoritative.

package/templates/hooks/pre-commit

@@ -0,0 +1,34 @@
+#!/bin/sh
+#
+# kspec-meta branch protection hook
+#
+# This hook prevents direct commits to the kspec-meta shadow branch.
+# All modifications to spec/task files should go through the kspec CLI,
+# which will set KSPEC_SHADOW_COMMIT=1 to authorize commits.
+#
+# Installation: This hook is automatically installed during 'kspec init'
+# into .git/hooks/pre-commit
+
+# Get current branch name
+BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
+
+# Check if we're on kspec-meta branch
+if [ "$BRANCH" = "kspec-meta" ]; then
+  # Allow if KSPEC_SHADOW_COMMIT is set (authorized by CLI)
+  if [ "$KSPEC_SHADOW_COMMIT" != "1" ]; then
+    echo "ERROR: Direct commits to kspec-meta branch are not allowed."
+    echo ""
+    echo "The kspec-meta branch is managed by the kspec CLI."
+    echo "Use kspec commands to modify specs and tasks:"
+    echo ""
+    echo "  kspec task start @ref"
+    echo "  kspec task note @ref \"description\""
+    echo "  kspec task complete @ref --reason \"done\""
+    echo "  kspec item add --title \"New item\""
+    echo ""
+    echo "All kspec operations automatically commit to the shadow branch."
+    exit 1
+  fi
+fi
+
+exit 0