fix(skills): add task preview, verification comment, checks template, and local test step

saltbo · saltbo · commit d98e852e73ef · 2026-04-13T22:25:09.000-04:00
- ak-task/ak-plan: require task preview with user confirmation before creation
- ak-task/ak-plan: replace Patterns section with Checks (verifiable acceptance criteria)
- ak-task/ak-plan: post verification comment on PR before merging
- ak-task/ak-plan: add cleanup step for local review artifacts
- ak-task/ak-plan: re-read CONTRIBUTING.md at Gate 2, fail-first ordering
- agent-kanban: add local test step before pushing, replace ak wait pr with gh pr checks
diff --git a/skills/agent-kanban/SKILL.md b/skills/agent-kanban/SKILL.md
@@ -12,9 +12,10 @@ You are an agent. Use the `ak` CLI to work on tasks. Your identity is initialize
 
 1. **Claim** your assigned task → `ak task claim <id>`
 2. **Log** progress as you work → `ak create note --task <id> "doing X..."`
-3. **PR** → push branch, `gh pr create`
-4. **Wait for CI** → `ak wait pr <pr-number>` — fix failures, push, re-wait until green
-5. **Submit for review** once CI passes → `ak task review <id> --pr-url <url>`
+3. **Local test** → run the project's test suite and type check before pushing. Fix all failures locally. Skip only if tests cannot run locally.
+4. **PR** → push branch, `gh pr create`
+5. **Wait for CI** → `gh pr checks <pr-number> --watch` — fix failures, push, re-check until green
+6. **Submit for review** once CI passes → `ak task review <id> --pr-url <url>`
 
 ## Commands
 
@@ -99,6 +100,7 @@ ak create task --board <id> --title "Title" \
 
 - **If claim fails, stop immediately** — do not write any code or make any changes. Report the error and wait.
 - **Never call `task complete`** — only humans complete tasks.
+- **Test before pushing** — run the project's test suite and type check locally. All tests must pass before `git push`. Skip only if tests cannot run locally. Do not rely on CI to catch failures you could have caught locally.
 - Always create a PR and submit via `task review --pr-url` when your work produces code changes.
 - Log progress frequently — humans monitor the board.
 - **Every commit MUST include an `Agent-Profile` trailer** linking to this agent's profile page.
diff --git a/skills/ak-plan/SKILL.md b/skills/ak-plan/SKILL.md
@@ -93,7 +93,34 @@ Use `AskUserQuestion` to interactively confirm the plan with the user. For each
 - **Approach** — when multiple implementation strategies exist, present them with trade-off descriptions
 - **Task granularity** — whether to split a large piece into subtasks or keep it as one
 
-Keep iterating until all uncertainties are resolved. Only proceed to create tasks after the user confirms the final scope and approach.
+Keep iterating until all uncertainties are resolved.
+
+Before creating any tasks, show the user a **task summary table** using `AskUserQuestion`:
+
+```
+📋 Task Plan Preview
+
+| # | Title | Repo | Priority | Labels | Depends on | Agent |
+|---|-------|------|----------|--------|------------|-------|
+| 1 | <title> | <repo> | high | backend | — | <agent> |
+| 2 | <title> | <repo> | medium | frontend | #1 | <agent> |
+| ...
+
+Per-task description summary:
+
+### Task 1: <title>
+Goal: <one sentence>
+Files: <file list>
+Spec: <key points — not the full description, but enough to judge scope>
+
+### Task 2: <title>
+...
+
+---
+Create all tasks? (y/n)
+```
+
+The user must confirm before any `ak create task` calls are made. If the user requests changes, adjust and re-preview.
 
 ## Phase 3: Create Board & Tasks
 
@@ -138,10 +165,13 @@ One sentence: what this task produces.
 POST /api/items — create item
   Request: { "name": string }
   Response: 201 { "id": 1, "name": "..." }
+  Empty name → 400 validation error
 
-## Patterns
-- Follow existing project conventions (read CLAUDE.md)
-
+## Checks
+- [ ] POST /api/items returns 201 with { id, name }
+- [ ] Empty name returns 400 with validation error
+- [ ] New item appears on the list page without refresh
+- [ ] Empty state shows "No items yet" placeholder
 ```
 
 Vague descriptions produce vague code. Be specific.
@@ -190,35 +220,72 @@ ak task reject <task-id> --reason "CI not green — wait for CI to pass before s
 Two gates — both must pass before merging. Reject as soon as either fails.
 
 **Gate 1: Code Review**
-- Read the diff: `gh pr diff <pr-number> --repo <owner>/<repo>`
-- Check implementation matches spec, code quality, tests
-- **Fails → reject immediately**, don't proceed to Gate 2
+
+Read the full PR diff and review against the task spec:
+```bash
+gh pr view <pr-number> --repo <owner>/<repo> --json title,body,additions,deletions,changedFiles
+gh pr diff <pr-number> --repo <owner>/<repo>
+```
+
+Check:
+- Does the implementation match the task spec?
+- Code quality — logic errors, bad abstractions, security issues
+- Boundary awareness — CLI user-facing output vs internal logging, public API vs private
+- Missing or broken test updates
+- Dropped functionality (lost stack traces, removed useful info, etc.)
+
+**Fails → reject immediately**, don't proceed to Gate 2.
 
 **Gate 2: Functional Acceptance**
-- Follow the target repo's CONTRIBUTING.md review process
-- Visit preview/staging deployment and verify the feature works end-to-end
-- Test golden path and edge cases from the task spec
+- Re-read the target repo's CONTRIBUTING.md before testing — don't rely on memory from Phase 1
+- Walk through every item in the task's `## Checks` section — each must pass
+- Visit preview/staging deployment and verify end-to-end
 - Check for regressions in related features
 - **Fails → reject with specific repro steps**
 
-**Both gates pass → Merge.**
-CI was already verified by the worker agent before submitting for review.
+**Either gate fails → Reject.** List all issues in the reason.
 ```bash
-gh pr merge <pr-number> --repo <owner>/<repo> --squash --delete-branch
+ak task reject <task-id> --reason "<all issues, specific and actionable>"
 ```
-The daemon's PR Monitor will automatically complete the task — do NOT manually `ak task complete`.
 
-**Either gate fails → Reject with all issues.**
+**Both gates pass → Post verification comment, then merge.**
+
+Post evidence on the PR before merging:
 ```bash
-ak task reject <task-id> --reason "<all issues, specific and actionable>"
+gh pr comment <pr-number> --repo <owner>/<repo> --body "$(cat <<'EOF'
+## Verification
+
+### Functional Test
+- Visited: <staging/preview URL tested>
+- Golden path: <what was tested and result>
+- Edge cases: <what was tested and result>
+
+### Test Suite
+<test commands run and pass/fail summary>
+
+### Conclusion
+All checks pass — merging.
+EOF
+)"
 ```
 
-### Handle merge conflicts:
-If a PR can't merge cleanly, reject — the worker agent will rebase, fix, and resubmit:
+If the PR has merge conflicts, reject instead of merging — the worker agent will rebase, fix, and resubmit:
 ```bash
 ak task reject <task-id> --reason "merge conflicts with main — rebase and resubmit"
 ```
 
+Then merge:
+```bash
+gh pr merge <pr-number> --repo <owner>/<repo> --squash --delete-branch
+```
+The daemon's PR Monitor will automatically complete the task — do NOT manually `ak task complete`.
+
+#### Cleanup after merge
+Remove local review artifacts from the repo root:
+```bash
+rm -rf /tmp/ak-review-* playwright-report/ test-results/
+```
+
 ### Completion:
 When all tasks are done, report the final summary to the user.
 
diff --git a/skills/ak-task/SKILL.md b/skills/ak-task/SKILL.md
@@ -57,15 +57,49 @@ Use `AskUserQuestion` to interactively resolve any uncertainties before creating
 
 Keep iterating — each answer may reveal new questions. Only proceed to create when all points are resolved and the user has confirmed the final task spec.
 
-If nothing is ambiguous (simple, clear-cut request), skip straight to presenting a summary and asking for a single confirmation.
+If nothing is ambiguous (simple, clear-cut request), skip straight to the task preview below.
 
-### Step 4: Create Task
+### Step 4: Preview & Create Task
 
-Write a detailed description with:
-- Goal (one sentence)
-- Files to modify
-- Specific behavior/spec
-- Patterns to follow
+Before creating, show the user the **exact task that will be created** using `AskUserQuestion`. Format the preview as:
+
+```
+📋 Task Preview
+
+Title: <concise action phrase>
+Board: <board-name>
+Repo: <repo-name>
+Agent: <agent-name>
+Priority: <priority>
+Labels: <labels>
+Depends on: <task-ids or "none">
+
+## Goal
+<one sentence>
+
+## Files
+- <file path> — <what changes>
+
+## Spec
+<concrete behavior: inputs, outputs, edge cases, error handling>
+
+## Checks
+- [ ] <verifiable condition — reviewer will check each one in Gate 2>
+
+Examples by task type:
+- API: "POST /api/items returns 201 with { id, name }"
+- API: "empty name returns 400 with validation error"
+- UI: "clicking Submit creates the item and navigates to detail page"
+- UI: "empty form shows inline validation, submit button stays disabled"
+- CLI: "ak get task --board xxx prints task table with status column"
+
+---
+Create this task? (y/n)
+```
+
+Everything from `## Goal` through `## Checks` is the exact text that will be passed to `--description`. The header fields above it (Title, Board, Agent, etc.) are metadata for display only — do not include them in `--description`. The user must see the full description before it's sent to the agent.
+
+**On confirmation**, create the task:
 
 ```bash
 ak create task \
@@ -86,14 +120,14 @@ Report to user: task ID, title, assigned agent.
 
 ## Phase 2: Monitor & Review
 
-### Step 6: Monitor
+### Step 5: Monitor
 
 **Block on `ak wait` instead of writing polling loops.** Exit codes: 0 condition met, 2 task cancelled, 124 timeout.
 
 ```bash
 ak wait task <task-id> --until in_review --timeout 1h
 case $? in
-  0)   ;;  # ready for review → Step 7
+  0)   ;;  # ready for review → Step 6
   2)   echo "task cancelled — abort" ; exit 1 ;;
   124) echo "timed out — investigate" ;;  # fall through to investigation
 esac
@@ -107,7 +141,7 @@ Run `ak wait task --help` for the full flag list.
 3. Check agent session log for what it's doing or where it's stuck
 4. Check child processes: the agent may be stuck on a hook, install, or network call
 
-### Step 7: Review PR
+### Step 6: Review PR
 
 **Pre-check: CI status.** Before reviewing, verify CI has passed on the PR:
 ```bash
@@ -124,8 +158,8 @@ Two gates — both must pass before merging. Reject as soon as either fails.
 
 Read the full PR diff and review against the task spec:
 ```bash
-gh pr view <pr-number> --repo <owner/repo> --json title,body,additions,deletions,changedFiles
-gh pr diff <pr-number> --repo <owner/repo>
+gh pr view <pr-number> --repo <owner>/<repo> --json title,body,additions,deletions,changedFiles
+gh pr diff <pr-number> --repo <owner>/<repo>
 ```
 
 Check:
@@ -139,32 +173,58 @@ Check:
 
 #### Gate 2: Functional Acceptance
 
-Follow the target repo's CONTRIBUTING.md review process. This typically includes:
-- Visit the preview/staging deployment and manually verify the feature works end-to-end
-- Test the golden path and edge cases described in the task spec
+Re-read the target repo's CONTRIBUTING.md before testing — don't rely on memory from Step 2.
+- Walk through every item in the task's `## Checks` section — each must pass
+- Visit the preview/staging deployment and verify end-to-end
 - Check for regressions in related features
 - Run any project-specific verification steps defined in CONTRIBUTING.md
 
 **Fails → reject with specific repro steps.**
 
-### Step 8: Decide — act immediately, do not ask the user
+### Step 7: Decide — act immediately, do not ask the user
 
 **Either gate fails → Reject.** List all issues in the reason.
 ```bash
 ak task reject <task-id> --reason "<all issues, specific and actionable>"
 ```
-After reject, go back to Step 6 and keep monitoring.
+After reject, go back to Step 5 and keep monitoring.
 
-**Both gates pass → Merge the PR, daemon auto-completes the task.**
-CI was already verified by the worker agent before submitting for review.
+**Both gates pass → Post verification comment, then merge.**
+
+Post a verification comment on the PR with evidence before merging:
+```bash
+gh pr comment <pr-number> --repo <owner>/<repo> --body "$(cat <<'EOF'
+## Verification
+
+### Functional Test
+- Visited: <staging/preview URL tested>
+- Golden path: <what was tested and result>
+- Edge cases: <what was tested and result>
+
+### Test Suite
+<test commands run and pass/fail summary>
+
+### Conclusion
+All checks pass — merging.
+EOF
+)"
+```
+
+If the PR has merge conflicts, reject instead of merging — the worker agent will rebase, fix, and resubmit:
+```bash
+ak task reject <task-id> --reason "merge conflicts with main — rebase and resubmit"
+```
+
+Then merge:
 ```bash
 gh pr merge <pr-number> --repo <owner>/<repo> --squash --delete-branch
 ```
 The daemon's PR Monitor will mark the task done — do NOT manually `ak task complete`.
 
-If a PR has merge conflicts, reject the task — the worker agent will rebase, fix, and resubmit:
+#### Cleanup after merge
+Remove local review artifacts from the repo root:
 ```bash
-ak task reject <task-id> --reason "merge conflicts with main — rebase and resubmit"
+rm -rf /tmp/ak-review-* playwright-report/ test-results/
 ```
 
 ## Phase 3: Exception Handling
