@kynetic-ai/spec 0.3.0 → 0.4.0

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

package/templates/skills/task-work/SKILL.md

@@ -0,0 +1,296 @@
+# Task Work
+
+Structured workflow for working on tasks. Full lifecycle from start through PR merge.
+
+## When to Use
+
+- Starting work on a ready task
+- Continuing in-progress or needs_work tasks
+- Ensuring consistent task lifecycle with notes and audit trail
+
+**Not for:** Spec creation (use `/kspec:writing-specs`), plan translation (use `/kspec:plan`), or triage (use `/kspec:triage`).
+
+## Inherit Existing Work First
+
+Before starting new work, check for existing work:
+
+```bash
+kspec session start  # Shows active work at the top
+```
+
+Priority order:
+1. **needs_work** — Fix cycle: address review feedback (highest priority)
+2. **in_progress** — Continue work already started
+3. **ready (pending)** — New work to start
+
+Always inherit existing work unless explicitly told otherwise. This prevents orphaned tasks.
+
+## Task Lifecycle
+
+```
+pending → in_progress → pending_review → completed
+              ↓              ↓
+          blocked        needs_work
+                     (→ in_progress → pending_review)
+```
+
+| Command | Transition | When |
+|---------|-----------|------|
+| `kspec task start @ref` | → in_progress | Beginning work |
+| `kspec task submit @ref` | → pending_review | Code done, PR created |
+| `kspec task complete @ref --reason "..."` | → completed | PR merged |
+| `kspec task block @ref --reason "..."` | → blocked | External blocker |
+
+## Workflow Steps
+
+### 1. Choose Task
+
+```bash
+kspec tasks ready                # All ready tasks
+kspec tasks ready --eligible     # Automation-eligible only (loop mode)
+```
+
+### 2. Verify Work Is Needed
+
+Before starting, check if work is already done:
+
+```bash
+# Check git history
+git log --oneline --grep="feature-name"
+git log --oneline -- path/to/relevant/files
+
+# Check existing implementation
+kspec item get @spec-ref  # View spec and ACs
+```
+
+If already implemented: verify tests pass, AC coverage exists, then `kspec task complete @ref --reason "Already implemented"`.
+
+**Notes are context, not proof.** If a task has notes saying "already done" — verify independently. Run tests, check code, validate against ACs. If a task is in the ready queue, there's a reason.
+
+### 3. Start Task
+
+```bash
+kspec task start @ref
+```
+
+### 4. Work and Note
+
+Read all ACs (own + trait) before implementing:
+
+```bash
+kspec item get @spec-ref  # Shows own ACs AND inherited trait ACs
+```
+
+Add notes during work, not just at the end:
+
+```bash
+# Good: explains decisions and context
+kspec task note @ref "Using retry with exponential backoff. Chose 3 max retries based on API rate limits."
+
+# Bad: no context
+kspec task note @ref "Done"
+```
+
+Note when you:
+- Discover something unexpected
+- Make a design decision
+- Encounter a blocker
+- Complete a significant piece
+
+### 5. Commit
+
+Include task and spec trailers:
+
+```
+feat: add user authentication
+
+Implemented JWT-based auth with refresh tokens.
+
+Task: @task-add-auth
+Spec: @auth-feature
+```
+
+Trailers enable `kspec log @ref` to find related commits.
+
+### 6. Local Review
+
+Run quality checks before submitting. Verify:
+
+- **Own AC coverage** — Each spec AC has a test annotated `// AC: @spec-ref ac-N`
+- **Trait AC coverage** — Each inherited trait AC has a test annotated `// AC: @trait-slug ac-N`
+- **Tests pass** — Full test suite, not just new tests
+- **Code quality** — Matches existing patterns, no duplicated utilities
+- **No regressions** — Existing tests still pass
+
+```bash
+kspec validate  # Reports uncovered trait ACs as warnings
+```
+
+### 7. Submit Task
+
+```bash
+kspec task submit @ref
+```
+
+Moves task to `pending_review`. Create PR after submitting.
+
+### 8. Complete Task
+
+After PR is merged:
+
+```bash
+kspec task complete @ref --reason "Merged in PR #N. Summary of what was done."
+```
+
+## Fix Cycle
+
+When inheriting a `needs_work` task:
+
+1. **Find the PR** — Check for review comments
+   ```bash
+   gh pr list --search "Task: @task-ref" --json number,url
+   gh api repos/{owner}/{repo}/pulls/{number}/comments --jq '.[] | {path, line, body}'
+   ```
+
+2. **Fix findings** — Address MUST-FIX and SHOULD-FIX items
+
+3. **Push fixes** — Commit with descriptive message
+   ```bash
+   git add <files> && git commit -m "fix: address review feedback
+
+   Task: @task-slug"
+   git push
+   ```
+
+4. **Re-submit** — `kspec task submit @ref` (back to pending_review)
+
+You do NOT merge in a fix cycle. The reviewer handles merge decisions.
+
+## Scope Management
+
+### What's In Scope
+
+Tasks describe expected outcomes, not rigid boundaries:
+
+- **Tests need implementation?** Implementing missing functionality is in scope — the goal is verified behavior
+- **Implementation needs tests?** Proving it works is always in scope
+
+### When to Expand vs Escalate
+
+**Expand** (do it yourself):
+- Additional work is clearly implied by the goal
+- Proportional to the original task
+- You have the context
+
+**Escalate** (capture separately):
+- Scope expansion is major
+- Uncertain about the right approach
+- Outside your task's domain
+
+**When you notice something outside your task:** Capture it separately (`kspec inbox add` or `kspec task note`). Don't fix it inline — even small detours compound into drift.
+
+## AC Test Annotations
+
+Link tests to acceptance criteria:
+
+```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.
+
+## Implementation Quality
+
+Before submitting:
+
+- **Search for existing utilities** — Don't duplicate helpers that already exist
+- **Match neighboring file style** — Naming conventions, error handling, imports
+- **Run full test suite** — Not just your new tests
+- **Validate** — `kspec validate` for spec alignment
+
+## Loop Mode
+
+Autonomous task execution without human confirmation.
+
+```bash
+kspec tasks ready --eligible  # Only automation-eligible tasks
+```
+
+### Task Selection Priority
+
+1. `needs_work` — Fix review feedback
+2. `in_progress` — Continue existing work
+3. Tasks that unblock others
+4. Highest priority ready task
+
+### Key Behaviors
+
+- Verify work is needed before starting (prevent duplicates)
+- Decisions auto-resolve without prompts
+- PR review handled externally (not this workflow)
+- All actions are logged and auditable
+
+### Blocking Rules
+
+**Block only for genuine external blockers:**
+- Human architectural decision needed
+- Spec clarification required
+- External dependency unavailable
+- Formal `depends_on` blocker
+
+**Do NOT block for:**
+- Task seems complex (do the work)
+- Tests are failing (fix them)
+- Service needs running (start it)
+
+After blocking:
+```bash
+kspec task block @ref --reason "Reason..."
+kspec tasks ready --eligible  # Check for other work
+# If tasks exist: work on the next one
+# If empty: stop responding (ralph auto-exits)
+```
+
+### Turn Completion
+
+After creating a PR, **stop responding**. Ralph continues automatically — it checks for remaining eligible tasks and exits the loop when none remain.
+
+**Do NOT call `end-loop`** after creating a PR. That ends ALL remaining iterations. It's a rare escape hatch for when work is stalling across multiple iterations.
+
+## Command Reference
+
+```bash
+# Task lifecycle
+kspec task start @ref
+kspec task note @ref "..."
+kspec task submit @ref
+kspec task complete @ref --reason "..."
+kspec task block @ref --reason "..."
+
+# Task discovery
+kspec tasks ready
+kspec tasks ready --eligible
+kspec task get @ref
+
+# Validation
+kspec validate
+kspec validate --alignment
+
+# Session context
+kspec session start
+```
+
+## Integration
+
+- **`/kspec:writing-specs`** — Create specs before deriving tasks
+- **`/kspec:plan`** — Plans create specs that become tasks
+- **`/kspec:review`** — Review checks AC coverage and code quality
+- **`/kspec:observations`** — Capture friction found during task work
+- **`/kspec:reflect`** — Session reflection after completing tasks

package/templates/skills/triage-automation/SKILL.md

@@ -0,0 +1,134 @@
+# Automation Triage
+
+Assess and prepare tasks for automation eligibility. Goal: make tasks self-contained so they can be worked on by automated agents.
+
+## When to Use
+
+- During a triage session focused on automation readiness
+- When new tasks need eligibility assessment
+- Before starting an automated work loop (to ensure eligible tasks exist)
+
+## 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 a 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)
+
+## Commands Reference
+
+```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
+- **Task type is not destiny** — Any non-spike task can be eligible
+
+## Integration
+
+- **`/kspec:triage-inbox`** — Inbox triage may promote items to tasks needing assessment
+- **`kspec tasks ready --eligible`** — Used by task-work loop to find automatable work
+- **Ralph loop** — Consumes eligible tasks; automation assessment feeds the pipeline