@kynetic-ai/spec 0.11.0 → 0.12.0

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

@@ -1,13 +1,13 @@
 ---
 name: task-work
-description: Structured task lifecycle — start, work, note, submit, complete.
-  Fix cycle handling, scope management, loop mode for automation, and quality
-  gates.
+description: Structured task lifecycle — start, work, note, submit, complete. AC
+  annotations, fix cycle handling via review records, scope management, and
+  quality checks.
 ---
 <!-- kspec-managed -->
 # Task Work
 
-Structured workflow for working on tasks. Full lifecycle from start through PR merge.
+Structured workflow for working on tasks. Full lifecycle from start through completion.
 
 ## When to Use
 
@@ -44,8 +44,8 @@ pending → in_progress → pending_review → completed
 | 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 submit @ref` | → pending_review | Work done, ready for review |
+| `kspec task complete @ref --reason "..."` | → completed | Reviewed and merged |
 | `kspec task block @ref --reason "..."` | → blocked | External blocker |
 
 ## CLI Lookups
@@ -62,6 +62,7 @@ Use CLI commands to find information. **Do NOT search `.kspec/` YAML files manua
 | All traits | `kspec trait list` |
 | Task's linked spec | `kspec task get @ref` → read `spec_ref` field |
 | Task's linked plan | `kspec task get @ref` → if `plan_ref` is non-null, run `kspec plan get @plan-ref` |
+| Reviews for a task | `kspec review for-task @ref` |
 
 **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.
 
@@ -71,7 +72,7 @@ Use CLI commands to find information. **Do NOT search `.kspec/` YAML files manua
 
 ```bash
 kspec tasks ready                # All ready tasks
-kspec tasks ready --eligible     # Automation-eligible only (loop mode)
+kspec tasks ready --eligible     # Automation-eligible only
 ```
 
 ### 2. Verify Work Is Needed
@@ -104,21 +105,24 @@ kspec plan get @plan-ref
 kspec task start @ref
 ```
 
-### 3.5 Branch Isolation (Required Before Edits)
+### 4. Branch Isolation (Required Before Edits)
 
-Immediately after `kspec task start` and before any file edits, create or switch to a dedicated branch for that task. Do not keep implementing on a branch that is tied to another pending-review task.
+Immediately after starting and before any file edits, create or switch to a dedicated branch.
 
 ```bash
-# Example naming from task intent/slug
-TASK_BRANCH="fix/<task-slug>"
-
-# Create the branch if missing, otherwise switch to it
-git checkout -b "$TASK_BRANCH" 2>/dev/null || git checkout "$TASK_BRANCH"
+# Preferred: deterministic dispatch-compatible branch
+kspec task branch @ref
 ```
 
-This keeps each task's commits scoped to its own PR and prevents cross-task contamination.
+`kspec task branch` creates or resumes the branch `dispatch/task/<normalized-slug>/<short-task-ref>`. This ensures:
+
+- **Dispatch continuity** — reviewer and fix-cycle agents can find and resume the branch
+- **No naming collisions** — the branch name is deterministic from the task identity
+- **Remote rehydration** — if the branch exists only on the remote, the command fetches it
+
+If you need a non-dispatch branch (e.g., for work not tied to a task), use conventional prefixes (`feat/`, `fix/`, etc.) instead.
 
-### 4. Work and Note
+### 5. Work and Note
 
 Read all ACs (own + trait) before implementing:
 
@@ -142,17 +146,58 @@ 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:
+### 6. AC Test Annotations
 
-```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"
+Every acceptance criterion should have at least one test annotated with a comment linking it to the AC. Use the comment syntax appropriate for the language:
+
+```javascript
+// AC: @spec-ref ac-1
+it('should validate input when given invalid data', () => { ... });
 ```
 
-### 5. Commit
+```python
+# AC: @spec-ref ac-1
+def test_validates_input():
+    ...
+```
+
+```sql
+-- AC: @spec-ref ac-1
+```
+
+```html
+<!-- AC: @spec-ref ac-1 -->
+```
+
+The pattern is always: language-appropriate comment + `AC: @spec-ref ac-N`.
+
+For **inherited trait ACs**, use the trait's ref, not the spec's ref:
+
+```javascript
+// AC: @trait-json-output ac-1
+it('should output valid JSON with --json flag', () => { ... });
+```
+
+If a trait AC genuinely doesn't apply, annotate it with a reason:
+
+```javascript
+// AC: @trait-json-output ac-3 — N/A: this command has no tabular output to format
+```
+
+Annotations must be standalone line comments, not embedded inside block comments or docstrings.
+
+### 7. Regenerate Derived Files
+
+If your task modified any of these source files, regenerate before committing:
+
+| Modified | Regenerate with |
+|----------|----------------|
+| `templates/skills/` or `.kspec/skills/` | `kspec skill render` |
+| `templates/agents-sections/`, conventions, or workflows | `kspec agents generate` |
+
+Commit the regenerated output alongside your source changes.
+
+### 8. Commit
 
 Include task and spec trailers:
 
@@ -167,12 +212,12 @@ Spec: @auth-feature
 
 Trailers enable `kspec log @ref` to find related commits.
 
-### 6. Local Review
+### 9. Quality Check
 
-Run quality checks before submitting. Verify:
+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`
+- **Own AC coverage** — Each spec AC has an annotated test
+- **Trait AC coverage** — Each inherited trait AC has an annotated test (or N/A annotation)
 - **Tests pass** — Full test suite, not just new tests
 - **Code quality** — Matches existing patterns, no duplicated utilities
 - **No regressions** — Existing tests still pass
@@ -181,43 +226,41 @@ Run quality checks before submitting. Verify:
 kspec validate  # Reports uncovered trait ACs as warnings
 ```
 
-### 7. Submit Task
+### 10. Submit
+
+Submit transitions the task to `pending_review`. This signals that work is complete and ready for review.
 
 ```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."
-```
+The reviewer (human or agent) takes over from here. See `/kspec:review` for the review process and `/kspec:merge` for the merge process.
 
 ## Fix Cycle
 
-When inheriting a `needs_work` task:
+When inheriting a `needs_work` task, the review feedback lives in kspec review records. Each fix cycle creates a new review record — the reviewer does not reopen the prior review.
 
-1. **Find the PR** — Check for review comments
+1. **Read the review** — Find and read review threads
    ```bash
-   gh pr list --search "Task: @task-ref" --json number,url
-   gh api repos/{owner}/{repo}/pulls/{number}/comments --jq '.[] | {path, line, body}'
+   kspec review for-task @ref              # Find all reviews (current + historical)
+   kspec review get @review-ref            # Read full review with threads
    ```
 
-2. **Fix findings** — Address MUST-FIX and SHOULD-FIX items
+2. **Address blocker threads** — Blockers must be resolved before re-approval. Questions and nits are non-blocking but should be addressed.
 
 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)
+4. **Note what changed** — Before resubmitting, add a task note summarizing what was fixed and why. This note becomes a key entry in the activity timeline and gives the next reviewer context on what changed since the prior review.
+   ```bash
+   kspec task note @ref "Fixed auth token validation: added null check before decode, updated test to cover expired token edge case. Addresses blocker thread on missing error handling."
+   ```
+
+5. **Re-submit** — `kspec task submit @ref` (back to pending_review, reviewer creates a new review record)
 
 You do NOT merge in a fix cycle. The reviewer handles merge decisions.
 
@@ -244,56 +287,7 @@ Tasks describe expected outcomes, not rigid boundaries:
 
 **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)
-- Create/switch to a dedicated task branch before making code edits
-- Decisions auto-resolve without prompts
-- PR review handled externally (not this workflow)
-- All actions are logged and auditable
-
-### Blocking Rules
+## Blocking Rules
 
 **Block only for genuine external blockers:**
 - Human architectural decision needed
@@ -314,17 +308,12 @@ kspec tasks ready --eligible  # Check for other work
 # If empty: stop responding (agent dispatch exits automatically)
 ```
 
-### Turn Completion
-
-After creating a PR, **stop responding**. The agent dispatch engine continues automatically — it checks for remaining eligible tasks and exits 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 branch @ref               # Create/resume dispatch-compatible branch
 kspec task note @ref "..."
 kspec task submit @ref
 kspec task complete @ref --reason "..."
@@ -335,18 +324,19 @@ kspec tasks ready
 kspec tasks ready --eligible
 kspec task get @ref
 
+# Review integration
+kspec review for-task @ref           # Find linked reviews
+kspec review get @review-ref         # Read review details
+
 # Validation
 kspec validate
 kspec validate --alignment
-
-# Session context
-kspec session start
 ```
 
 ## Integration
 
+- **`/kspec:review`** — Review process for submitted work
+- **`/kspec:merge`** — Merge approved work into integration branch
 - **`/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:observe`** — Capture friction found during task work
-- **`/kspec:reflect`** — Session reflection after completing tasks

package/templates/agents-sections/04-pr-workflow.md

@@ -1,17 +1,20 @@
-## PR Workflow
+## Work and Review Lifecycle
 
-Before creating a PR, mark the task: `kspec task submit @ref` (transitions to `pending_review`).
+Before submitting work for review: `kspec task submit @ref` (transitions to `pending_review`).
 
-The full PR lifecycle has three steps — **all required, in order:**
+The full lifecycle:
 
-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`.
+1. **Work** — Implement, test, annotate ACs. See the kspec task-work skill.
+2. **Submit** — `kspec task submit @ref` signals work is ready for review.
+3. **Review** — Reviewer creates a kspec review record, investigates, submits verdict. See the kspec review skill.
+4. **Merge** — After review approval, merge to integration branch. See the kspec merge skill.
 
-**Quality gates (never skip without explicit approval):**
-- All CI checks passing
-- All review comments addressed
-- All review threads resolved
-- AC coverage verified
+**Review gates (from kspec review disposition):**
+- Review disposition = `approved`
+- All required checks passing
+- No unresolved blocker threads
+- AC coverage verified (own + trait)
 
-**After merge:** `kspec task complete @ref --reason "Merged in PR #N. Summary..."`
+**After merge:** `kspec task complete @ref --reason "Merged. Summary..."`
+
+**Fix cycle:** If review requests changes, task transitions to `needs_work`. Worker reads review threads via `kspec review for-task @ref`, addresses blockers, resubmits.

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

@@ -23,7 +23,7 @@ kspec agent dispatch stop
 `kspec setup` ensures default worker/reviewer agent definitions exist in `kynetic.meta.yaml`:
 
 - `task-worker` — handles automation-eligible `task.ready`, `task.in_progress`, and `task.needs_work`
-- `pr-reviewer` — handles `task.pending_review`
+- `pr-reviewer` — handles `task.pending_review` (review and local merge)
 
 Inspect current definitions with:
 
@@ -38,7 +38,7 @@ kspec agent list
 | `task.ready` | `task-worker` | Worker picks up newly ready automation-eligible tasks |
 | `task.in_progress` | `task-worker` | Worker can continue existing automation-eligible tasks |
 | `task.needs_work` | `task-worker` | Fix-cycle tasks return to worker |
-| `task.pending_review` | `pr-reviewer` | Review/merge workflow runs in separate invocation |
+| `task.pending_review` | `pr-reviewer` | Review and local merge in separate invocation |
 
 ### One-Shot Invocation
 
@@ -60,18 +60,23 @@ Common flags:
 ```
 for each dispatched invocation:
   1. Agent runtime checks eligible tasks — if none, invocation ends
-  2. Agent works on tasks, may create PR(s)
-     - Before editing files on a selected task, create/switch to a dedicated task branch
-  3. Agent stops responding (turn complete)
-  4. pr-reviewer agent handles pending_review tasks via separate dispatch
-  5. Continue
+  2. Agent works on tasks
+     - Before editing files, use `kspec task branch @ref` for the deterministic
+       dispatch-compatible branch (dispatch/task/<slug>/<short-id>)
+  3. Agent submits task (kspec task submit @ref) when work is complete
+  4. Agent stops responding (turn complete)
+  5. Reviewer agent picks up pending_review tasks: creates kspec review,
+     investigates, submits verdict, merges locally if approved
+  6. Continue
 ```
 
-**When you stop responding, the dispatch engine continues automatically.** Do NOT call `kspec agent end-loop` after creating a PR.
+**Do NOT create GitHub PRs for dispatched work.** Agent work is reviewed via kspec review records and merged locally to the integration branch. GitHub PRs are a human-directed activity for merging feature groups into main.
+
+**When you stop responding, the dispatch engine continues automatically.** Do NOT call `kspec agent end-loop` after submitting a task.
 
 ### Task Inheritance
 
-Priority: `needs_work` > `in_progress` > `pending`. Always inherit existing work before starting new tasks. (`pending_review` tasks are handled by the pr-reviewer agent, not the worker.)
+Priority: `needs_work` > `in_progress` > `pending`. Always inherit existing work before starting new tasks. (`pending_review` tasks are handled by the reviewer agent, not the worker.)
 
 ### Blocking Rules
 
@@ -85,7 +90,7 @@ Priority: `needs_work` > `in_progress` > `pending`. Always inherit existing work
 - 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)
+- Another task is in review (not a formal dependency)
 
 **After blocking a task:**
 ```bash

package/templates/skills/manifest.yaml

@@ -9,63 +9,81 @@ skills:
     platforms:
       - claude-code
       - codex
+      - droid
   - id: observe
     name: Observations
     description: Capture and act on systemic patterns — friction, successes, questions, and ideas. The feedback loop that drives process improvement.
     platforms:
       - claude-code
       - codex
+      - droid
   - id: reflect
     name: Session Reflection
     description: Structured reflection at the end of work sessions. Identifies learnings, friction points, and improvements for system evolution.
     platforms:
       - claude-code
       - codex
+      - droid
   - id: triage
     name: Triage
     description: Triage inbox items systematically. Records decisions with audit trail, then executes actions. Supports inbox, observations, and automation eligibility triage.
     platforms:
       - claude-code
       - codex
+      - droid
   - id: triage-inbox
     name: Inbox Triage
     description: Process inbox items using the record-act pattern. Categorize, promote to spec/task, merge duplicates, defer, or delete stale items with full audit trail.
     platforms:
       - claude-code
       - codex
+      - droid
   - id: triage-automation
     name: Automation Triage
     description: Assess and prepare tasks for automation eligibility. Verify spec coverage, acceptance criteria, and task readiness for automated agents.
     platforms:
       - claude-code
       - codex
+      - droid
   - id: writing-specs
     name: Writing Specs
     description: Create and maintain specification items — modules, features, requirements, acceptance criteria, and traits. The source of truth for what to build.
     platforms:
       - claude-code
       - codex
+      - droid
   - id: plan
     name: Plan to Spec
     description: Translate approved plans into specs and tasks. Import structured documents or create incrementally. Plans persist as durable artifacts with audit trail.
     platforms:
       - claude-code
       - codex
+      - droid
   - id: task-work
     name: Task Work
-    description: Structured task lifecycle — start, work, note, submit, complete. Fix cycle handling, scope management, loop mode for automation, and quality gates.
+    description: Structured task lifecycle — start, work, note, submit, complete. AC annotations, fix cycle handling via review records, scope management, and quality checks.
     platforms:
       - claude-code
       - codex
-  - id: create-workflow
-    name: Create Workflow
-    description: Formalize repeatable patterns into trackable kspec workflows. Design steps, choose triggers, create loop variants, and integrate with skills.
+      - droid
+  - id: review
+    name: Review
+    description: How to review work and use kspec review records. Covers both reviewer and worker perspectives — creating reviews, structuring findings, AC coverage verification, review principles, and the full review record interface.
     platforms:
       - claude-code
       - codex
-  - id: review
-    name: Review
-    description: Kspec-specific review gates — spec alignment, own AC coverage, trait AC coverage, and validation integration. Building block for project-specific review workflows.
+      - droid
+  - id: merge
+    name: Merge
+    description: Merge approved work into an integration branch. Local-first git merge with gates based on kspec review disposition — approved status, passing checks, and resolved blocker threads.
+    platforms:
+      - claude-code
+      - codex
+      - droid
+  - id: create-workflow
+    name: Create Workflow
+    description: Formalize repeatable patterns into trackable kspec workflows. Design steps, choose triggers, create loop variants, and integrate with skills.
     platforms:
       - claude-code
       - codex
+      - droid

package/templates/skills/merge/SKILL.md

@@ -0,0 +1,120 @@
+# Merge
+
+Merge approved work into an integration branch. Local-first — uses git merge directly, with merge gates based on kspec review disposition.
+
+## When to Use
+
+- After work has been reviewed and approved via `{skill:review}`
+- Merging a task branch into a dev or integration branch
+- Completing the work lifecycle after review approval
+
+**Not for:** Creating pull requests to remote repositories (that's a human-directed activity for feature-level merges into main).
+
+## Merge Gate
+
+Before merging, verify all gates pass:
+
+```bash
+# 1. Check review disposition
+kspec review for-task @ref
+kspec review get @review-ref
+# Disposition must be "approved"
+
+# 2. Required checks passing
+# Review checks should show all required checks as "pass"
+
+# 3. No unresolved blocker threads
+# Review should have no open blocker threads
+```
+
+**All three must be satisfied:**
+- Review disposition = `approved`
+- All required checks passing (not stale)
+- No unresolved blocker threads
+
+If any gate fails, do not merge. Address the issue first:
+- `changes_requested` → worker fixes issues, resubmits
+- Required check failing → fix and re-run
+- Unresolved blocker → resolve the thread or fix the issue
+
+## Merge Process
+
+### 1. Verify Branch State
+
+```bash
+# Confirm current branch
+git branch --show-current
+
+# Ensure branch is up to date with target
+git fetch origin
+git log --oneline origin/dev..HEAD  # What will be merged
+```
+
+### 2. Merge to Integration Branch
+
+```bash
+# Switch to target branch
+git checkout dev
+
+# Merge with merge commit (preserves trailers)
+git merge --no-ff <task-branch>
+
+# Verify merge succeeded
+git log --oneline -3
+```
+
+**Use merge commits, not squash.** Merge commits preserve individual commit messages with their `Task:` and `Spec:` trailers, enabling `kspec log @ref` to find related commits.
+
+### 3. Handle Conflicts
+
+If a merge conflict occurs:
+
+**Assess the conflict:**
+- Is it a simple textual conflict (parallel edits to the same lines)?
+- Or a semantic conflict (incompatible changes to behavior)?
+
+**For simple conflicts:**
+```bash
+# View conflicting files
+git diff --name-only --diff-filter=U
+
+# Resolve conflicts in each file
+# Then mark resolved
+git add <resolved-files>
+git commit  # Completes the merge
+```
+
+**For complex/semantic conflicts:**
+- Do not force-merge
+- Escalate: `kspec inbox add "Merge conflict between @task-a and @task-b — needs human review"`
+- Or block the task: `kspec task block @ref --reason "Merge conflict with ..."`
+
+### 4. Complete the Task
+
+After successful merge:
+
+```bash
+kspec task complete @ref --reason "Merged to dev. Summary of what was done."
+```
+
+### 5. Close the Review
+
+```bash
+kspec review close @review-ref
+```
+
+## Post-Merge Cleanup
+
+```bash
+# Delete the task branch locally
+git branch -d <task-branch>
+
+# Optionally delete remote branch
+git push origin --delete <task-branch>
+```
+
+## Integration
+
+- **`{skill:task-work}`** — Work lifecycle leads to merge after review
+- **`{skill:review}`** — Review disposition gates the merge
+- **`kspec task complete`** — Final step after merge