@kynetic-ai/spec 0.8.0 → 0.9.1

package/plugin/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "kspec",
       "description": "kspec agent skills",
-      "version": "0.8.0",
+      "version": "0.9.1",
       "source": "./plugins/kspec",
       "category": "development"
     }

package/plugin/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "kspec",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "description": "kspec agent skills"
 }

package/plugin/plugins/kspec/skills/create-workflow/SKILL.md

@@ -133,6 +133,16 @@ git add templates/skills/<name>/SKILL.md
 git commit -m "feat: add <name> skill for workflow integration"
 ```
 
+### Cross-Skill Consistency Check (When Updating Existing Skills)
+
+If your workflow or wording change is cross-cutting, run this quick consistency pass before committing:
+
+1. List related skills/templates that describe the same concept (for example: `codex`, `pr-review`, `local-review`, review templates).
+2. Verify each related file is either updated in the same PR or explicitly noted as intentionally unchanged.
+3. Add a short checklist in PR notes showing which related files were reviewed.
+
+This prevents partial updates where one skill changes but sibling skills keep outdated guidance.
+
 ## Step Design Guidelines
 
 ### Action Steps
@@ -231,5 +241,5 @@ kspec agents generate
 ## Integration
 
 - **`/kspec:reflect`** — Session reflections surface patterns worth formalizing
-- **`/kspec:observations`** — Friction observations may reveal missing workflows
+- **`/kspec:observe`** — Friction observations may reveal missing workflows
 - **`kspec agents generate`** — Regenerate after creating workflows

package/plugin/plugins/kspec/skills/{observations → observe}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: observations
+name: observe
 description: Capture and act on systemic patterns — friction, successes,
   questions, and ideas. The feedback loop that drives process improvement.
 ---

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

@@ -281,6 +281,16 @@ kspec task set @task-slug --depends-on @other-task
 kspec plan get @plan-slug
 ```
 
+If derived tasks are too generic to execute without chat history, add a structured task note immediately:
+
+```bash
+kspec task note @task-slug "Execution context:
+- Background: why this task exists
+- Scope: concrete boundaries for this task
+- Files: exact files/areas to touch
+- Verification: commands/tests to run"
+```
+
 ## Plan Lifecycle
 
 ```
@@ -340,4 +350,4 @@ kspec validate --alignment
 - **`/kspec:writing-specs`** — Spec authoring details (types, AC format, traits)
 - **`/kspec:task-work`** — After specs are created, work on derived tasks
 - **`/kspec:triage`** — Inbox items may trigger plan creation
-- **`/kspec:observations`** — Friction during planning becomes observations
+- **`/kspec:observe`** — Friction during planning becomes observations

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

@@ -109,6 +109,7 @@ grep -rn "// AC: @spec-ref" tests/
 ```
 
 Each AC listed in the spec output must have a corresponding annotation. Missing annotations are MUST-FIX.
+Before accepting coverage, confirm each annotation matches the AC text from `kspec item get @spec-ref` (not only the `ac-N` label).
 
 ## Trait AC Coverage
 
@@ -149,6 +150,7 @@ If a trait AC genuinely doesn't apply to this spec, annotate it with a reason:
 ```
 
 The annotation must exist so coverage tooling can track it.
+Annotations must be standalone line comments (`// AC:` or `# AC:`), not embedded inside block/JSDoc comments.
 
 ### No Traits?
 

package/plugin/plugins/kspec/skills/task-work/SKILL.md

@@ -120,6 +120,16 @@ Note when you:
 - Encounter a blocker
 - Complete a significant piece
 
+For tasks that are missing standalone context (for example, generic derived notes), add one structured note before deep implementation work:
+
+```bash
+kspec task note @ref "Execution context:
+- Background: why this task matters
+- Scope: what is in/out for this task
+- Files: exact files expected to change
+- Verification: tests/commands that prove completion"
+```
+
 ### 5. Commit
 
 Include task and spec trailers:
@@ -315,5 +325,5 @@ kspec session start
 - **`/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:observe`** — Capture friction found during task work
 - **`/kspec:reflect`** — Session reflection after completing tasks

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

@@ -67,6 +67,7 @@ For each task shown:
   - Is the spec appropriate for this task?
   - Are the ACs adequate and testable?
   - Does the task have sufficient context?
+  - Can the task be executed from task data alone (without hidden chat/session context)?
 - If yes: `kspec task set @ref --automation eligible`
 - If no: Fix issues or mark `needs_review` with specific reason
 

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

@@ -228,5 +228,5 @@ At session end, provide summary:
 ## Integration
 
 - **`/kspec:reflect`** — Session reflection may generate inbox items for triage
-- **`/kspec:observations`** — Captures systemic patterns found during triage
+- **`/kspec:observe`** — Captures systemic patterns found during triage
 - **`kspec session start`** — Shows inbox count for triage awareness

package/plugin/plugins/kspec/skills/writing-specs/SKILL.md

@@ -350,5 +350,5 @@ The derived task gets `spec_ref: @feature-slug` automatically.
 - **`/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:observe`** — Friction may indicate missing specs
 - **`/kspec:review`** — Reviews check AC coverage

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

@@ -20,3 +20,4 @@ Verify shadow branch health with `kspec shadow status` if you encounter issues.
 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`.
+8. **Edit skill sources, not rendered output** — Do not edit `.agents/skills/` directly. Core skills live in `templates/skills/` (+ `templates/skills/manifest.yaml`), while project/local skills live in `.kspec/skills/`. Regenerate rendered files with `kspec skill render`/`kspec setup`.

package/templates/skills/create-workflow/SKILL.md

@@ -126,6 +126,16 @@ git add templates/skills/<name>/SKILL.md
 git commit -m "feat: add <name> skill for workflow integration"
 ```
 
+### Cross-Skill Consistency Check (When Updating Existing Skills)
+
+If your workflow or wording change is cross-cutting, run this quick consistency pass before committing:
+
+1. List related skills/templates that describe the same concept (for example: `codex`, `pr-review`, `local-review`, review templates).
+2. Verify each related file is either updated in the same PR or explicitly noted as intentionally unchanged.
+3. Add a short checklist in PR notes showing which related files were reviewed.
+
+This prevents partial updates where one skill changes but sibling skills keep outdated guidance.
+
 ## Step Design Guidelines
 
 ### Action Steps
@@ -224,5 +234,5 @@ kspec agents generate
 ## Integration
 
 - **`{skill:reflect}`** — Session reflections surface patterns worth formalizing
-- **`{skill:observations}`** — Friction observations may reveal missing workflows
+- **`{skill:observe}`** — Friction observations may reveal missing workflows
 - **`kspec agents generate`** — Regenerate after creating workflows

package/templates/skills/manifest.yaml

@@ -9,7 +9,7 @@ skills:
     platforms:
       - claude-code
       - codex
-  - id: observations
+  - id: observe
     name: Observations
     description: Capture and act on systemic patterns — friction, successes, questions, and ideas. The feedback loop that drives process improvement.
     platforms:

package/templates/skills/plan/SKILL.md

@@ -274,6 +274,16 @@ kspec task set @task-slug --depends-on @other-task
 kspec plan get @plan-slug
 ```
 
+If derived tasks are too generic to execute without chat history, add a structured task note immediately:
+
+```bash
+kspec task note @task-slug "Execution context:
+- Background: why this task exists
+- Scope: concrete boundaries for this task
+- Files: exact files/areas to touch
+- Verification: commands/tests to run"
+```
+
 ## Plan Lifecycle
 
 ```
@@ -333,4 +343,4 @@ kspec validate --alignment
 - **`{skill:writing-specs}`** — Spec authoring details (types, AC format, traits)
 - **`{skill:task-work}`** — After specs are created, work on derived tasks
 - **`{skill:triage}`** — Inbox items may trigger plan creation
-- **`{skill:observations}`** — Friction during planning becomes observations
+- **`{skill:observe}`** — Friction during planning becomes observations

package/templates/skills/review/SKILL.md

@@ -102,6 +102,7 @@ grep -rn "// AC: @spec-ref" tests/
 ```
 
 Each AC listed in the spec output must have a corresponding annotation. Missing annotations are MUST-FIX.
+Before accepting coverage, confirm each annotation matches the AC text from `kspec item get @spec-ref` (not only the `ac-N` label).
 
 ## Trait AC Coverage
 
@@ -142,6 +143,7 @@ If a trait AC genuinely doesn't apply to this spec, annotate it with a reason:
 ```
 
 The annotation must exist so coverage tooling can track it.
+Annotations must be standalone line comments (`// AC:` or `# AC:`), not embedded inside block/JSDoc comments.
 
 ### No Traits?
 

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

@@ -113,6 +113,16 @@ Note when you:
 - Encounter a blocker
 - Complete a significant piece
 
+For tasks that are missing standalone context (for example, generic derived notes), add one structured note before deep implementation work:
+
+```bash
+kspec task note @ref "Execution context:
+- Background: why this task matters
+- Scope: what is in/out for this task
+- Files: exact files expected to change
+- Verification: tests/commands that prove completion"
+```
+
 ### 5. Commit
 
 Include task and spec trailers:
@@ -308,5 +318,5 @@ kspec session start
 - **`{skill:writing-specs}`** — Create specs before deriving tasks
 - **`{skill:plan}`** — Plans create specs that become tasks
 - **`{skill:review}`** — Review checks AC coverage and code quality
-- **`{skill:observations}`** — Capture friction found during task work
+- **`{skill:observe}`** — Capture friction found during task work
 - **`{skill:reflect}`** — Session reflection after completing tasks

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

@@ -61,6 +61,7 @@ For each task shown:
   - Is the spec appropriate for this task?
   - Are the ACs adequate and testable?
   - Does the task have sufficient context?
+  - Can the task be executed from task data alone (without hidden chat/session context)?
 - If yes: `kspec task set @ref --automation eligible`
 - If no: Fix issues or mark `needs_review` with specific reason
 

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

@@ -221,5 +221,5 @@ At session end, provide summary:
 ## Integration
 
 - **`{skill:reflect}`** — Session reflection may generate inbox items for triage
-- **`{skill:observations}`** — Captures systemic patterns found during triage
+- **`{skill:observe}`** — Captures systemic patterns found during triage
 - **`kspec session start`** — Shows inbox count for triage awareness

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

@@ -343,5 +343,5 @@ The derived task gets `spec_ref: @feature-slug` automatically.
 - **`{skill:plan}`** — Plans create specs via import or manual creation
 - **`{skill:task-work}`** — Tasks reference specs; AC guides implementation
 - **`{skill:triage}`** — Inbox items may reveal spec gaps
-- **`{skill:observations}`** — Friction may indicate missing specs
+- **`{skill:observe}`** — Friction may indicate missing specs
 - **`{skill:review}`** — Reviews check AC coverage