diff --git a/.ai-devkit.json b/.ai-devkit.json index 7c2ff3b2..b0583f9b 100644 --- a/.ai-devkit.json +++ b/.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" diff --git a/packages/cli/src/constants.ts b/packages/cli/src/constants.ts index 8bb34d42..982d7381 100644 --- a/packages/cli/src/constants.ts +++ b/packages/cli/src/constants.ts @@ -26,6 +26,7 @@ export const BUILTIN_SKILL_NAMES = [ 'structured-debug', 'document-code', 'memory', + 'task', 'simplify-implementation', 'verify', 'tdd' diff --git a/skills/dev-lifecycle/SKILL.md b/skills/dev-lifecycle/SKILL.md index 482e3d92..32575dd0 100644 --- a/skills/dev-lifecycle/SKILL.md +++ b/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 `. 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. diff --git a/skills/structured-debug/SKILL.md b/skills/structured-debug/SKILL.md index 12cef370..0353dc30 100644 --- a/skills/structured-debug/SKILL.md +++ b/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 "" --content "" --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 | diff --git a/skills/task/SKILL.md b/skills/task/SKILL.md new file mode 100644 index 00000000..9a9c0c5f --- /dev/null +++ b/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. +- **`` 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 + `` 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 --agent-type --pid --session `. +4. If identity is ambiguous, do not guess; skip task mutation logging. + +## Canonical commands + +Add `` 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 "" --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. diff --git a/skills/task/agents/openai.yaml b/skills/task/agents/openai.yaml new file mode 100644 index 00000000..82e04911 --- /dev/null +++ b/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." diff --git a/skills/verify/SKILL.md b/skills/verify/SKILL.md index 2294b46d..292d4f84 100644 --- a/skills/verify/SKILL.md +++ b/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.