@kynetic-ai/spec 0.4.0 → 0.6.0

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.

package/templates/skills/review/SKILL.md

@@ -10,6 +10,43 @@ Kspec-specific review concerns for verifying spec alignment, AC coverage, and tr
 
 **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 Context Discovery
+
+If a spec ref is not explicitly provided, discover it before proceeding with AC checks:
+
+```bash
+# 1. Check commit messages for Task: or Spec: trailers
+git log --format='%B' main..HEAD | grep -E '^(Task|Spec):'
+
+# 2. Check changed files for // AC: annotations pointing to specs
+git diff main..HEAD | grep '// AC: @'
+
+# 3. If a task ref is found, get its spec_ref
+kspec task get @task-ref --json | jq '.spec_ref'
+
+# 4. Search recent tasks matching the scope of changes
+kspec tasks list | grep -i "<keywords from changed files>"
+```
+
+If a spec is found through any method, proceed with full AC validation below.
+If no spec context is found after all discovery steps, skip AC coverage checks and focus on code quality and regression checks.
+
+**Principle:** The absence of a trailer is a signal to look harder, not permission to skip validation.
+
+## CLI Lookups
+
+Use CLI commands to resolve specs and traits. **Do NOT search `.kspec/` YAML files manually.**
+
+| Need | Command |
+|------|---------|
+| Spec + all ACs (own + inherited) | `kspec item get @spec-ref` |
+| Trait definition + ACs | `kspec item get @trait-slug` |
+| All traits on a spec | shown in `kspec item get @spec-ref` output |
+| Search by keyword | `kspec search "keyword"` |
+| All traits | `kspec trait list` |
+
+**Resolving inherited traits:** When `kspec item get` shows "Inherited from @trait-slug", run `kspec item get @trait-slug` to see the full trait ACs. This is one command — never grep through `.kspec/modules/*.yaml` files.
+
 ## Spec Alignment
 
 Implementation must match spec intent, not just pass tests.

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

@@ -41,6 +41,22 @@ pending → in_progress → pending_review → completed
 | `kspec task complete @ref --reason "..."` | → completed | PR merged |
 | `kspec task block @ref --reason "..."` | → blocked | External blocker |
 
+## CLI Lookups
+
+Use CLI commands to find information. **Do NOT search `.kspec/` YAML files manually** — it wastes time and misses context that CLI commands provide (like inherited trait ACs).
+
+| Need | Command |
+|------|---------|
+| Task details | `kspec task get @ref` |
+| Spec + all ACs (own + inherited) | `kspec item get @ref` |
+| Trait definition + ACs | `kspec item get @trait-slug` |
+| Search by keyword | `kspec search "keyword"` |
+| List by type | `kspec item list --type feature` |
+| All traits | `kspec trait list` |
+| Task's linked spec | `kspec task get @ref` → read `spec_ref` field |
+
+**Key pattern:** When `kspec item get` output shows "Inherited from @trait-slug", run `kspec item get @trait-slug` to see the trait's ACs. One command — do not grep YAML files.
+
 ## Workflow Steps
 
 ### 1. Choose Task

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

@@ -111,7 +111,7 @@ kspec triage act @triage-ref
 
 For behavior changes, check spec coverage before promoting:
 
-1. **Check coverage**: `kspec item list | grep <relevant>`
+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

package/templates/skills/writing-specs/SKILL.md

@@ -12,6 +12,20 @@ Create and maintain specification items — the source of truth for what to buil
 
 **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