feat(skill): add builtin task skill for CLI-driven lifecycle/debug progress tracking

.ai-devkit.json

@@ -45,6 +45,10 @@
       "registry": "codeaholicguy/ai-devkit",
       "name": "structured-debug"
     },
+    {
+      "registry": "codeaholicguy/ai-devkit",
+      "name": "task"
+    },
     {
       "registry": "codeaholicguy/ai-devkit",
       "name": "document-code"

packages/cli/src/constants.ts

@@ -26,6 +26,7 @@ export const BUILTIN_SKILL_NAMES = [
   'structured-debug',
   'document-code',
   'memory',
+  'task',
   'simplify-implementation',
   'verify',
   'tdd'

skills/dev-lifecycle/SKILL.md

@@ -22,6 +22,7 @@ Supporting skills:
 - `memory` for reusable project knowledge during clarification.
 - `tdd` for implementation tasks.
 - `verify` before completing implementation, implementation checks, testing claims, and review readiness.
+- `task` for optional progress tracing when the task plugin is installed.
 
 ## Startup Validation
 
@@ -92,3 +93,4 @@ Not every phase moves forward. When a phase reveals problems, route back:
 - Existing feature docs are the paths reported or validated by `npx ai-devkit@latest lint --feature <name>`. If you must infer manually, first resolve the configured docs directory from `.ai-devkit.json` `paths.docs`, falling back to `docs/ai`.
 - After each phase, summarize output and suggest the next phase.
 - Do not claim completion without fresh verification evidence.
+- When task tracing is available: create the feature task once, set `phase` on phase transitions, record `progress`/`next` after meaningful task updates, add `evidence` after verification, and `close` at lifecycle end.

skills/structured-debug/SKILL.md

@@ -38,6 +38,12 @@ For each hypothesis, include:
 - Summarize remaining risks and follow-ups.
 - Store root cause and fix for future sessions: `npx ai-devkit@latest memory store --title "<root cause>" --content "<diagnosis and fix>" --tags "debug,root-cause"`
 
+## Task Tracing
+
+If `ai-devkit task --help` succeeds, use `$task` optionally: record repro/final
+results as `evidence`, the current hypothesis as `next`, and blockers only when
+they materially affect progress. Never block debugging because task tracing is unavailable.
+
 ## Red Flags and Rationalizations
 
 | Rationalization | Why It's Wrong | Do Instead |

skills/task/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: task
+description: AI DevKit · Track dev-lifecycle / structured-debug progress on a durable task with the ai-devkit task CLI. Use to record phase, progress, next step, blockers, and validation evidence.
+---
+
+# Task Progress Tracking
+
+Record development progress on a durable task: phase, progress, next step,
+blockers, and validation evidence.
+
+Requires the optional task command. First try `ai-devkit task --help`; if that
+fails, try `npx ai-devkit@latest task --help`. If both fail, continue the user
+workflow without task logging.
+
+## Core idea
+
+- **One task per feature.** Create it once; advance its `phase` field as work
+  moves through the lifecycle.
+- **`<id>` can be a feature key.** Every command below accepts the feature
+  key in place of a task id, resolving to the latest non-terminal task. Prefer
+  `<feature>` so agents do not track task ids.
+- **Emit at checkpoints, not streaming.** Phase transitions, task toggles, fresh
+  evidence, blockers discovered/resolved. A handful of calls per session.
+- **Attribution is explicit.** Identify self once, then pass actor flags on
+  mutation commands.
+
+## Identify self
+
+Use `agent-management` when attribution is needed:
+
+1. Run `ai-devkit agent list --json`.
+2. Match the current session id to an agent entry.
+3. Build actor flags:
+   `--agent <name> --agent-type <type> --pid <pid> --session <sessionId>`.
+4. If identity is ambiguous, do not guess; skip task mutation logging.
+
+## Canonical commands
+
+Add `<actor-flags>` to mutation commands when self identity is known.
+
+```bash
+# Create the feature task once (capture taskId from --json if needed)
+ai-devkit task create --title "<title>" --feature <feature> --phase requirements --json
+
+# Advance phase as the lifecycle moves on
+ai-devkit task phase <feature> implementation
+
+# Progress (use --text; positional text is ignored)
+ai-devkit task progress <feature> --text "Implementing task CLI" --percent 60
+
+# Next step
+ai-devkit task next <feature> "Run validation"
+
+# Blockers
+ai-devkit task blocker <feature> add "Waiting for review"
+ai-devkit task blocker <feature> resolve <blocker-id>
+
+# Validation evidence - record after a fresh verify/tdd/test run
+ai-devkit task evidence <feature> --passed --command "npm test" --exit-code 0 --summary "tests passed"
+
+# Reference an artifact (never copies the file)
+ai-devkit task artifact <feature> docs/ai/testing/foo.md --kind test-report --description "Testing notes"
+
+# Read current status / list
+ai-devkit task show <feature> --json
+ai-devkit task list --feature <feature> --json
+
+# Close at lifecycle end
+ai-devkit task close <feature>
+```
+
+## When to emit (by workflow)
+
+- **dev-lifecycle** - `create` at start; `phase` on every phase transition;
+  `progress` after planning/implementation task toggles; `show` at resume.
+- **verify / tdd / dev-testing** - `evidence` after fresh proof (this is what
+  makes "last validation" trustworthy). Use `--failed` when it fails.
+- **structured-debug** - reuse the same commands: `evidence` for repro results,
+  `next` for the next hypothesis, `blocker add`/`resolve`, `progress`.
+- **Any phase** - `blocker add` when blocked, `resolve` when clear; `next` to
+  state the immediate next step.
+
+## Tips
+
+- Add `--json` when an agent must parse output (create/show/list). Omit for
+  human-readable checks.
+- Don't restate obvious nearby files or transient state; keep summaries short.

skills/task/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Task Progress"
+  short_description: "AI DevKit · Track lifecycle/debug progress with the task CLI"
+  default_prompt: "Use $task to record phase, progress, next step, blockers, and validation evidence on the feature's durable task via ai-devkit task commands."

skills/verify/SKILL.md

@@ -65,3 +65,9 @@ If step 4 passes, the test is wrong. Rewrite it.
 ## Memory Integration
 
 After a failed verification, store the failure pattern: `npx ai-devkit@latest memory store --title "<failure pattern>" --content "<what failed and how to avoid>" --tags "verify,failure-pattern"`
+
+## Task Tracing
+
+If `ai-devkit task --help` succeeds and a task/feature is known, record task
+`evidence` after the report with command, exit code, pass/fail, and concise
+summary. Never block verification because task logging is unavailable.