@codewizard-dt/bootstrap 2.10.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.github/workflows/build.yml +88 -0
- package/.github/workflows/security.yml +24 -0
- package/.gitleaks.toml +15 -0
- package/README.md +472 -0
- package/bin/cli.js +47 -0
- package/lib/README.md +27 -0
- package/lib/hooks/README.md +316 -0
- package/lib/hooks/env-file-guard.js +45 -0
- package/lib/hooks/git-protected-ops-block.js +77 -0
- package/lib/hooks/lib/serena-languages.js +158 -0
- package/lib/hooks/lib/serena.js +787 -0
- package/lib/hooks/mv-absolute-path-block.js +53 -0
- package/lib/hooks/serena-bash-grep-block.js +501 -0
- package/lib/hooks/serena-edit-guard.js +74 -0
- package/lib/hooks/serena-first-glob-guard.js +94 -0
- package/lib/hooks/serena-first-guard.js +74 -0
- package/lib/hooks/serena-first-read-guard.js +167 -0
- package/lib/hooks/serena-pre-delegation.js +117 -0
- package/lib/hooks/serena-session-reset.js +45 -0
- package/lib/hooks/serena-usage-tracker.js +186 -0
- package/lib/hooks/serena-write-guard.js +58 -0
- package/lib/prompts/README.md +16 -0
- package/lib/prompts/migrate-wiki.md +111 -0
- package/lib/prompts/setup-deployment.md +322 -0
- package/lib/prompts/setup-design-system.md +162 -0
- package/lib/prompts/setup-strict-typechecks.md +139 -0
- package/lib/scripts/README.md +49 -0
- package/lib/scripts/bootstrap-serena.sh +145 -0
- package/lib/scripts/build-mcp-guide.sh +108 -0
- package/lib/scripts/install-global.sh +78 -0
- package/lib/scripts/install-mcps.sh +131 -0
- package/lib/scripts/lib.sh +154 -0
- package/lib/scripts/merge-gitignore.sh +65 -0
- package/lib/scripts/migrate-project.sh +273 -0
- package/lib/scripts/setup-deployment.sh +104 -0
- package/lib/scripts/setup-project.sh +55 -0
- package/lib/scripts/setup-runner.sh +99 -0
- package/lib/scripts/setup-strict-typechecks.sh +29 -0
- package/lib/scripts/startup.sh +42 -0
- package/lib/scripts/sync-wiki-scaffold.sh +104 -0
- package/lib/scripts/templates/CLAUDE-env-safety.md +3 -0
- package/lib/scripts/templates/CLAUDE-wiki.md +60 -0
- package/lib/scripts/templates/gitignore +136 -0
- package/lib/scripts/templates/guides/stubs/00-header.md +15 -0
- package/lib/scripts/templates/guides/stubs/brave-search.md +20 -0
- package/lib/scripts/templates/guides/stubs/context7.md +26 -0
- package/lib/scripts/templates/guides/stubs/playwright.md +26 -0
- package/lib/scripts/templates/guides/stubs/serena.md +219 -0
- package/lib/scripts/templates/wiki/conventions.md +100 -0
- package/lib/scripts/templates/wiki/dashboard.html +1733 -0
- package/lib/scripts/templates/wiki/hot.md +21 -0
- package/lib/scripts/templates/wiki/index.md +46 -0
- package/lib/scripts/templates/wiki/knowledge/concepts/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/entities/components/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/entities/organisations/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/entities/people/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/entities/tools/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/sources/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/log.md +14 -0
- package/lib/scripts/templates/wiki/work/bugs/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/bugs/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/bugs/index.md +12 -0
- package/lib/scripts/templates/wiki/work/bugs/lifecycle.md +39 -0
- package/lib/scripts/templates/wiki/work/decisions/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/decisions/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/decisions/index.md +12 -0
- package/lib/scripts/templates/wiki/work/decisions/lifecycle.md +42 -0
- package/lib/scripts/templates/wiki/work/requirements/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/requirements/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/requirements/index.md +12 -0
- package/lib/scripts/templates/wiki/work/requirements/lifecycle.md +34 -0
- package/lib/scripts/templates/wiki/work/roadmaps/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/roadmaps/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/roadmaps/index.md +12 -0
- package/lib/scripts/templates/wiki/work/roadmaps/lifecycle.md +32 -0
- package/lib/scripts/templates/wiki/work/tasks/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/tasks/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/tasks/index.md +12 -0
- package/lib/scripts/templates/wiki/work/tasks/lifecycle.md +39 -0
- package/lib/scripts/templates/wiki/work/uat/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/uat/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/uat/index.md +12 -0
- package/lib/scripts/templates/wiki/work/uat/lifecycle.md +48 -0
- package/lib/scripts/templates/wiki/work/uat/screenshots/.gitkeep +0 -0
- package/lib/scripts/update-project.sh +75 -0
- package/lib/scripts/wiki-dashboard-server.js +146 -0
- package/lib/skills/README.md +146 -0
- package/lib/skills/anti-slop/SKILL.md +183 -0
- package/lib/skills/bug-close/SKILL.md +136 -0
- package/lib/skills/bug-file/SKILL.md +114 -0
- package/lib/skills/bug-triage/SKILL.md +140 -0
- package/lib/skills/company-align/SKILL.md +203 -0
- package/lib/skills/debug-logs/SKILL.md +129 -0
- package/lib/skills/decision-create/SKILL.md +220 -0
- package/lib/skills/decision-finalize/SKILL.md +181 -0
- package/lib/skills/decision-next/SKILL.md +129 -0
- package/lib/skills/decision-walkthrough/SKILL.md +169 -0
- package/lib/skills/demo/SKILL.md +183 -0
- package/lib/skills/elevator-pitch/SKILL.md +125 -0
- package/lib/skills/eval-create/SKILL.md +344 -0
- package/lib/skills/eval-gap/SKILL.md +150 -0
- package/lib/skills/eval-run/SKILL.md +214 -0
- package/lib/skills/extract-feature/SKILL.md +344 -0
- package/lib/skills/flashcard/SKILL.md +513 -0
- package/lib/skills/frontend-taste/SKILL.md +184 -0
- package/lib/skills/gap-assess/SKILL.md +97 -0
- package/lib/skills/git-commit/SKILL.md +164 -0
- package/lib/skills/lint/SKILL.md +99 -0
- package/lib/skills/marp-slideshow/SKILL.md +212 -0
- package/lib/skills/mermaid-flowchart/SKILL.md +194 -0
- package/lib/skills/now/SKILL.md +36 -0
- package/lib/skills/port-feature/SKILL.md +315 -0
- package/lib/skills/power-mode/SKILL.md +184 -0
- package/lib/skills/primer/SKILL.md +84 -0
- package/lib/skills/project-readme/SKILL.md +166 -0
- package/lib/skills/req-compile/SKILL.md +131 -0
- package/lib/skills/req-create/SKILL.md +124 -0
- package/lib/skills/req-extract-decisions/SKILL.md +241 -0
- package/lib/skills/req-finalize/SKILL.md +251 -0
- package/lib/skills/req-retire/SKILL.md +185 -0
- package/lib/skills/req-update/SKILL.md +265 -0
- package/lib/skills/research/SKILL.md +250 -0
- package/lib/skills/research-company/SKILL.md +345 -0
- package/lib/skills/roadmap-add/SKILL.md +238 -0
- package/lib/skills/roadmap-create/SKILL.md +223 -0
- package/lib/skills/roadmap-next/SKILL.md +132 -0
- package/lib/skills/security-audit/SKILL.md +246 -0
- package/lib/skills/serena-config/SKILL.md +92 -0
- package/lib/skills/simplify/SKILL.md +227 -0
- package/lib/skills/tackle/SKILL.md +156 -0
- package/lib/skills/task-add/SKILL.md +208 -0
- package/lib/skills/task-audit/SKILL.md +294 -0
- package/lib/skills/task-trash/SKILL.md +115 -0
- package/lib/skills/task-update/SKILL.md +136 -0
- package/lib/skills/uat-auto/SKILL.md +69 -0
- package/lib/skills/uat-auto-plus/SKILL.md +115 -0
- package/lib/skills/uat-generate/SKILL.md +289 -0
- package/lib/skills/uat-skip/SKILL.md +169 -0
- package/lib/skills/uat-walk/SKILL.md +164 -0
- package/lib/skills/uat-walk/UAT-CORE.md +140 -0
- package/lib/skills/update-docs/SKILL.md +75 -0
- package/lib/skills/wiki-archive/SKILL.md +96 -0
- package/lib/skills/wiki-ingest/SKILL.md +139 -0
- package/lib/skills/wiki-lint/SKILL.md +131 -0
- package/lib/skills/wiki-query/SKILL.md +71 -0
- package/lib/skills/wiki-rotate-log/SKILL.md +90 -0
- package/lib/skills/wiki-tidy/SKILL.md +107 -0
- package/package.json +32 -0
- package/raw/.gitkeep +0 -0
- package/raw/design-principles.md +65 -0
- package/raw/guides/command-anti-patterns.md +79 -0
- package/raw/guides/deployment-strategy.md +448 -0
- package/raw/guides/evals-framework.md +452 -0
- package/raw/guides/mcp-tools.md +335 -0
- package/raw/guides/task-spec.md +79 -0
- package/raw/guides/type-checking-templates/README.md +112 -0
- package/raw/guides/type-checking-templates/eslint/eslint.config.ts +105 -0
- package/raw/guides/type-checking-templates/python/mypy.ini +69 -0
- package/raw/guides/type-checking-templates/python/pyproject.toml +164 -0
- package/raw/guides/type-checking-templates/python/pyrightconfig.json +67 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.app.jsonc +45 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.lib.jsonc +44 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.node-esm.jsonc +40 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.node.jsonc +34 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.vite-root.json +8 -0
- package/raw/harness-notes.md +20 -0
- package/raw/house-style/components/Badge.tsx +16 -0
- package/raw/house-style/components/Button.tsx +32 -0
- package/raw/house-style/components/Card.tsx +26 -0
- package/raw/house-style/components/Chip.tsx +57 -0
- package/raw/house-style/components/IconButton.tsx +67 -0
- package/raw/house-style/components/Modal.tsx +18 -0
- package/raw/house-style/components/Stepper.tsx +141 -0
- package/raw/house-style/components/icons.tsx +128 -0
- package/raw/house-style/preview/src/index.css +46 -0
- package/raw/house-style/tokens/tailwind.preset.ts +49 -0
- package/raw/house-style/tokens/tokens.json +62 -0
- package/raw/llm-wiki-2.md +162 -0
- package/raw/llm-wiki.md +75 -0
- package/raw/research/dark-mode-theme/index.md +85 -0
- package/raw/research/dark-mode-theme/sources.md +49 -0
- package/raw/research/serena-mcp-disconnect/index.md +81 -0
- package/raw/research/serena-mcp-disconnect/sources.md +87 -0
- package/raw/research/wiki-tooling-improvements/index.md +126 -0
- package/raw/research/wiki-tooling-improvements/sources.md +73 -0
- package/raw/software-factory-case-study.pdf +0 -0
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: tackle
|
|
3
|
+
description: Execute an outlined task file step-by-step with subagent delegation
|
|
4
|
+
category: executing
|
|
5
|
+
model: claude-sonnet-4-6
|
|
6
|
+
argument-hint: <path/to/task.md, number-slug, or description>
|
|
7
|
+
disable-model-invocation: false
|
|
8
|
+
user-invocable: true
|
|
9
|
+
---
|
|
10
|
+
**Prereqs:** obey `.docs/guides/mcp-tools.md` + `wiki/work/tasks/lifecycle.md`; run /primer if not done this session.
|
|
11
|
+
|
|
12
|
+
# Tackle Outline
|
|
13
|
+
|
|
14
|
+
Execute a pre-planned task file step-by-step. **The task file IS the plan — no re-planning.** Each `### N.` step names its agent via a `<!-- agent: TYPE -->` annotation (default `general-purpose`). This command is a pure executor: read → execute next step → update, one step per cycle.
|
|
15
|
+
|
|
16
|
+
**Outline File**: $ARGUMENTS
|
|
17
|
+
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
## Step 0: Resolve the task file
|
|
21
|
+
|
|
22
|
+
Resolve `$ARGUMENTS` (use Serena `find_file`/`list_dir`):
|
|
23
|
+
|
|
24
|
+
| Input | Action |
|
|
25
|
+
|-------|--------|
|
|
26
|
+
| File path (`wiki/work/tasks/3-user-auth.md`) | confirm exists; else fall through |
|
|
27
|
+
| Number-slug (`3-user-auth`) | match in `wiki/work/tasks/`; else fall through |
|
|
28
|
+
| Number / description (`3`, `user auth`) | search `wiki/work/tasks/`; ambiguous → list + ask; no match → fall through |
|
|
29
|
+
| Empty | run **Roadmap Auto-Discovery** (0a) first; only then the task survey |
|
|
30
|
+
| Non-empty but unresolved | task survey — recommend, never auto-pick |
|
|
31
|
+
|
|
32
|
+
Use the resolved path as the outline for all later steps.
|
|
33
|
+
|
|
34
|
+
**Mark work started:** if the resolved task's frontmatter `status` is `todo`, `Edit` it to `in-progress` now (main agent, not delegated) — this is the signal that implementation has begun, distinct from not-yet-started. Sync `wiki/work/tasks/index.md`'s `· status` suffix for this task in the same cycle (one `Edit`, skip if already `in-progress`).
|
|
35
|
+
|
|
36
|
+
### Step 0a: Roadmap Auto-Discovery (empty `$ARGUMENTS` only)
|
|
37
|
+
|
|
38
|
+
Zero-click: find the first actionable roadmap item and tackle it, **no prompts**.
|
|
39
|
+
|
|
40
|
+
1. `mcp__serena__list_dir("wiki/work/roadmaps/", recursive=false)` — root `.md` files only (exclude `archive/`, `README.md`). None → task survey.
|
|
41
|
+
2. `Read` each roadmap (markdown). Select the one with the most `[x]` items (furthest along); tie/single → use it. No prompt.
|
|
42
|
+
3. Scan top-to-bottom for the first `## Phase N` (or flat list) containing a `- [ ]` item. None unchecked → roadmap done → task survey.
|
|
43
|
+
4. Take the first `- [ ]` line in that phase:
|
|
44
|
+
- **Task link** (markdown link into `wiki/work/tasks/`) → extract path, use as outline. Announce: `Roadmap auto-selected: <roadmap> → Phase <N>: <name> → <link text>`.
|
|
45
|
+
- **Inline item** (plain text) → treat text as a description, fall through to the task survey. Announce the inline item and that no task file exists.
|
|
46
|
+
|
|
47
|
+
### Task survey (empty OR unresolved)
|
|
48
|
+
|
|
49
|
+
Recommend from the index; **do not auto-pick**.
|
|
50
|
+
- **Read only `wiki/work/tasks/index.md`** (canonical active list: bullet lines `- [TASK-NNN — Title](TASK-NNN-slug.md) — one-line summary · status`). Do NOT read individual task files, `grep`, `bash`, or aggregate across `wiki/work/tasks/` — the index exists to prevent exactly that. The only per-file read is the chosen task in Step 1.
|
|
51
|
+
- Missing `index.md` / no active-item bullets → STOP: `Task index at wiki/work/tasks/index.md is empty or missing. Add tasks with /task-add, or invoke /tackle <path-or-slug> directly.` Do not scan every file.
|
|
52
|
+
- `index.md` carries no progress columns — it lists title + one-line summary + `status` only, and `status` now directly distinguishes `todo` / `in-progress` / `pending-uat` (see [lifecycle](../tasks/lifecycle.md)) — no need to infer UAT-awaiting state from file existence. If a bullet points at a task file that no longer exists (moved/archived), note the drift in one sentence and skip it — don't pre-emptively fix the index.
|
|
53
|
+
- Empty active list → STOP: "No active tasks to tackle".
|
|
54
|
+
- Present the active items as a compact table (`TASK-NNN` · title · status). Below it, a **Recommendation** ranking top 1–3 by priority, using `status` alone:
|
|
55
|
+
1. `status: in-progress` — finish what's started.
|
|
56
|
+
2. `status: todo`, lowest-numbered first.
|
|
57
|
+
- Tasks at `status: pending-uat` are excluded from recommendations and listed under `**Awaiting UAT**:` — `mcp__serena__list_dir` on `wiki/work/uat/` for the matching `UAT-NNN-*` file; if found, suggest `/uat-walk wiki/work/uat/UAT-NNN-<slug>.md`; if none found (implementation finished but `/uat-generate` never ran), suggest `/uat-generate wiki/work/tasks/TASK-NNN-<slug>.md` instead.
|
|
58
|
+
- Progress counts, `[BLOCKED]`/`[FAILED]` flags, and per-step state are **not** in `index.md` by design — they live in the task files. This no-args survey deliberately ranks on `status` + UAT presence alone rather than re-reading every task file; use `/task-audit` when the full progress/blocker picture is needed. (Design note: the survey was simplified to `index.md`'s real bullet schema rather than expanding `index.md` with Progress/UAT/Flags columns, which would violate the "active items only, flat list" convention in `wiki/conventions.md`.)
|
|
59
|
+
- Use `AskUserQuestion` (top rec first, labelled `(Recommended)`; up to 2 more; `header` = number-slug). If input was unresolved, prefix one line noting it. Do NOT proceed to Step 1 until the user chooses.
|
|
60
|
+
|
|
61
|
+
---
|
|
62
|
+
|
|
63
|
+
## MANDATORY: Serena for all code operations
|
|
64
|
+
|
|
65
|
+
Every delegated sub-agent **MUST** use Serena, non-negotiable:
|
|
66
|
+
|
|
67
|
+
| Operation | Use | Never |
|
|
68
|
+
|-----------|-----|-------|
|
|
69
|
+
| Explore structure | `get_symbols_overview` | `Read` on code |
|
|
70
|
+
| Find symbol | `find_symbol` | `Grep` on code |
|
|
71
|
+
| Edit code | Serena symbolic / file-line tools | native `Edit` on code |
|
|
72
|
+
| Search code | `search_for_pattern` | `Grep` |
|
|
73
|
+
| Find files / dirs | `find_file`, `list_dir` | `Glob`, `find`, `ls`, `cat` |
|
|
74
|
+
| Library docs | Context7 | `WebSearch`/`WebFetch` |
|
|
75
|
+
|
|
76
|
+
Standard Read/Edit/Write are allowed for markdown and config (JSON, YAML, `.env`) only. **Every** sub-agent prompt must include: *"Use Serena for all code exploration/editing and all file/directory exploration. Standard Read/Edit/Write for markdown and config only. Never bash `ls`/`cat`/`find`/`grep`/`sed`. See `.docs/guides/mcp-tools.md`."*
|
|
77
|
+
|
|
78
|
+
**Verification scope: static gates only** (`bash -n`, typecheck, lint, unit tests). Runtime/E2E is the UAT phase's job — see `.docs/guides/command-anti-patterns.md#verification-belongs-to-the-right-phase`.
|
|
79
|
+
|
|
80
|
+
---
|
|
81
|
+
|
|
82
|
+
## Step 1: Read & parse the outline
|
|
83
|
+
|
|
84
|
+
**Delegate to an `Explore` sub-agent** (main agent does NOT read the outline directly). It reads via Serena and returns: ordered `### N.` sections, each with status and agent type. Missing/empty file → STOP + report. Status parsing: complete = `[x]`/`[DONE]`/`~~strikethrough~~`; in-progress = `[ ]`/`[WIP]`; not-started = unmarked; blocked = `[BLOCKED]`. Agent type from `<!-- agent: TYPE -->` (default `general-purpose`).
|
|
85
|
+
|
|
86
|
+
**Completion check:** all items complete → report "All tasks in outline complete!" and STOP.
|
|
87
|
+
|
|
88
|
+
## Step 2: Execute the next incomplete step
|
|
89
|
+
|
|
90
|
+
**Delegate to the agent type named in that section's annotation.** All implementation runs in a sub-agent, never the main context. Next-step priority: (1) fix blockers, (2) continue WIP, (3) start first incomplete section.
|
|
91
|
+
|
|
92
|
+
**Delegate directly — no re-planning.** Pass the step's checkboxes and sub-details verbatim. Do not research, re-plan, or ask questions (that was `/task-add`'s job).
|
|
93
|
+
|
|
94
|
+
**CRITICAL:** max **3** sub-processes at a time; **always terminate** processes when done (dev servers, type checkers, long-running commands).
|
|
95
|
+
|
|
96
|
+
Every sub-agent prompt MUST include:
|
|
97
|
+
1. The Serena mandate (above).
|
|
98
|
+
2. The exact checkboxes + sub-details from the section, verbatim.
|
|
99
|
+
3. **Static gates only** after the work: `bash -n` for shell scripts; the project typecheck (`pnpm typecheck`, `make types-backend`, `mypy`, …); lint and unit tests allowed. **Do NOT** run runtime/E2E: no scratch dirs, helper scripts against real paths, curl, rsync dry-runs, spawned servers, fixture seeding, or asserting on files the code just produced. If a step calls for runtime verification, mark it `[DEFERRED-TO-UAT]` and move on. **All type errors are caused by your changes — no exceptions** (the codebase is committed clean before every cycle; zero pre-existing errors). **NEVER `git stash` to "verify" if errors are pre-existing — banned.**
|
|
100
|
+
4. Report completion status (success / partial / failure + reason).
|
|
101
|
+
|
|
102
|
+
## Step 3: Update the outline
|
|
103
|
+
|
|
104
|
+
**Do this directly in the main agent — do NOT delegate** (simple text replacement).
|
|
105
|
+
|
|
106
|
+
⛔ **HARD RULE — update immediately, never batch.** The moment a Step 2 sub-agent returns, the *next thing you do* is flip that step's checkboxes on disk. Do not dispatch the next sub-agent, continue the cycle, or defer updates. Step N's update lands before step N+1 begins.
|
|
107
|
+
|
|
108
|
+
1. Use **`Edit`** — one call per checkbox line. **Never** `sed`/`awk`/`perl -i`/`echo` on task files, however many flip (ten `Edit`s right; one `sed` wrong + triggers approval). Markers: `[x]` done · `[WIP]` partial · `[BLOCKED: reason]` · `[FAILED: reason]`.
|
|
109
|
+
2. Add `<!-- Updated: YYYY-MM-DD HH:MM -->`.
|
|
110
|
+
3. Add any subtasks discovered during execution.
|
|
111
|
+
4. **Keep `wiki/work/tasks/index.md` in sync** — `index.md` has no progress or flags columns, so there is nothing to recount there. The one thing to maintain is the `· status` suffix on this task's bullet line: if this cycle flips the task's frontmatter `status` (e.g. `todo` → `in-progress`), update the matching `· status` on its `index.md` line with a single `Edit` (skip if unchanged). Progress and flags live only in the task file.
|
|
112
|
+
|
|
113
|
+
## Step 4: Repeat
|
|
114
|
+
|
|
115
|
+
Step 1 → 2 → 3 → 2 → 3 … **One step per cycle; never run Step 2 twice in a row.** The outline must visibly progress between every dispatch (so the user and any interrupting `/tackle` resumption see real-time state). Continue until all complete or interrupted.
|
|
116
|
+
|
|
117
|
+
---
|
|
118
|
+
|
|
119
|
+
## Important rules
|
|
120
|
+
|
|
121
|
+
- **Process management** — max 3 concurrent sub-agents; **always terminate all processes/sub-agents when done**, verify termination after each; a hung sub-agent → terminate + mark `[BLOCKED]`. The main agent NEVER runs implementation commands directly.
|
|
122
|
+
- **Error handling** — a failed sub-agent → `[FAILED: reason]`; do not auto-retry, continue with the next available task; all remaining blocked/failed → STOP + report.
|
|
123
|
+
- **Progress reporting** — each cycle: what completed, what's next, X of Y done.
|
|
124
|
+
- **Stopping** — all `[x]`; user interrupt; all remaining blocked/failed; outline invalid/unreadable.
|
|
125
|
+
- **No re-planning** — executor not planner. Don't research, re-plan, break down further, or ask questions. A step too vague to execute → `[BLOCKED: step needs more detail]` and move on. Agent annotations + step details are authoritative.
|
|
126
|
+
- **Mandatory delegation** — all steps except Step 3 (outline update) go to sub-agents; the main agent only orchestrates (receive → decide → delegate), never reads source, edits, or runs commands directly. Preserves the main context window.
|
|
127
|
+
|
|
128
|
+
---
|
|
129
|
+
|
|
130
|
+
## Completion (after all steps done)
|
|
131
|
+
|
|
132
|
+
### Step 5: Mark implementation pending UAT
|
|
133
|
+
|
|
134
|
+
Before anything else: `Edit` the task's frontmatter `status` → `pending-uat` (main agent, not delegated) — every `## Steps` checkbox is now checked, so there's nothing left to implement, only to verify. Sync `wiki/work/tasks/index.md`'s `· status` suffix for this task in the same cycle (one `Edit`).
|
|
135
|
+
|
|
136
|
+
This is a real state, not a formality — `/roadmap-next` uses it to recommend `/uat-walk`/`/uat-auto` instead of `/tackle` for this task going forward. Do this even if you're about to immediately answer "No" to the UAT-generation gate below — a task with no UAT still needs `pending-uat` recorded (an explicit skip is `/uat-skip`'s job, not silence).
|
|
137
|
+
|
|
138
|
+
### Step 6: UAT generation gate — ⛔ HARD STOP (never skip or reorder)
|
|
139
|
+
Ask via `AskUserQuestion`: **"Generate UAT tests for this task?"** — **Yes** → run `/uat-generate wiki/work/tasks/<filename>` (creates the matching UAT file); **No** → skip. **Wait** for the answer (and for `/uat-generate` to finish, if invoked) before Step 6b.
|
|
140
|
+
|
|
141
|
+
### Step 6b: Type-check gate
|
|
142
|
+
Try in order, stop at the first that runs (exit 0 or type errors); skip to next only if not found / target missing: (1) `Skill(typecheck)`, (2) `make typecheck`. Suppress output from not-found/missing-target commands — surface only real type errors. None available → skip silently.
|
|
143
|
+
- **On type errors** → report them, mark the relevant step `[FAILED: type errors]`, and **do not** proceed to the banner. The user must resolve (or explicitly say skip) first.
|
|
144
|
+
- **On pass/skip** → banner.
|
|
145
|
+
|
|
146
|
+
### Banner (output verbatim)
|
|
147
|
+
```
|
|
148
|
+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
149
|
+
TACKLE COMPLETED — all steps done
|
|
150
|
+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
### Step 7: Suggest UAT
|
|
154
|
+
If UAT was generated, suggest `/uat-walk wiki/work/uat/<file>.uat.md`.
|
|
155
|
+
|
|
156
|
+
**Start now — read the outline and begin the first cycle.**
|
|
@@ -0,0 +1,208 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: task-add
|
|
3
|
+
description: Create a structured, execution-ready task file in wiki/work/tasks/
|
|
4
|
+
category: planning
|
|
5
|
+
model: claude-sonnet-4-6
|
|
6
|
+
argument-hint: <task description> [--decision DEC-NNNN#DM] [--roadmap ROADMAP-NNN]
|
|
7
|
+
disable-model-invocation: false
|
|
8
|
+
user-invocable: true
|
|
9
|
+
---
|
|
10
|
+
**Prereqs:** obey `.docs/guides/mcp-tools.md`; run /primer if not done this session.
|
|
11
|
+
|
|
12
|
+
$ARGUMENTS
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
**Instructions:**
|
|
17
|
+
|
|
18
|
+
### Step 1: Summarize the user input
|
|
19
|
+
|
|
20
|
+
Extract the core task objective, scope, and any specific requirements from `$ARGUMENTS`.
|
|
21
|
+
|
|
22
|
+
### Step 2: Parse and validate decision reference (only if `$ARGUMENTS` contains `--decision` or a `DEC-` token)
|
|
23
|
+
|
|
24
|
+
Detect a decision reference in any of these forms:
|
|
25
|
+
- `DEC-NNNN#DM` (e.g. `DEC-0007#D2`) — specific decision
|
|
26
|
+
- `NNNN#DM` (e.g. `0007#D2`) — specific decision
|
|
27
|
+
- `--decision DEC-NNNN#DM` or `--decision NNNN#DM` — flag form
|
|
28
|
+
- `DEC-NNNN` (no `#DM`) — **auto-detect** first accepted decision without a task
|
|
29
|
+
|
|
30
|
+
Strip the decision token and any `--decision` flag from `$ARGUMENTS` to get the clean task description.
|
|
31
|
+
|
|
32
|
+
Locate the decision file: use `mcp__serena__find_file` to find `NNNN-*.md` in `wiki/work/decisions/`.
|
|
33
|
+
|
|
34
|
+
**If no `#DM` was given (auto-detect)**: walk `## D1.`, `## D2.`, … blocks in order; find the first where `status: accepted` and the `### Links` section has no `Source task(s):` line. If every accepted decision already has a task reference, STOP and tell the user. If no accepted decisions exist, STOP and tell the user to run `/decision-finalize` first.
|
|
35
|
+
|
|
36
|
+
**Refuse if the resolved decision is not `accepted`**: STOP and tell the user to run `/decision-finalize <file>#DM` first.
|
|
37
|
+
|
|
38
|
+
Store `(decision_file_path, decision_id, decision_anchor)` for later steps.
|
|
39
|
+
|
|
40
|
+
If no decision reference: skip this step entirely.
|
|
41
|
+
|
|
42
|
+
### Step 3: Parse and validate roadmap reference (only if `$ARGUMENTS` contains `--roadmap` or a `ROADMAP-` token)
|
|
43
|
+
|
|
44
|
+
Detect:
|
|
45
|
+
- `ROADMAP-NNN` — bare token
|
|
46
|
+
- `--roadmap ROADMAP-NNN` or `--roadmap NNN` — flag form
|
|
47
|
+
|
|
48
|
+
Strip the roadmap token from `$ARGUMENTS`.
|
|
49
|
+
|
|
50
|
+
Locate: `mcp__serena__find_file` for `NNN-*.md` in `wiki/work/roadmaps/`. If not found, STOP and report.
|
|
51
|
+
|
|
52
|
+
Confirm the file has `status: active` in its frontmatter. If `status: done`, warn the user and ask whether to proceed.
|
|
53
|
+
|
|
54
|
+
Store `(roadmap_file_path, roadmap_number)` for Step 9.
|
|
55
|
+
|
|
56
|
+
If no roadmap reference: skip this step entirely.
|
|
57
|
+
|
|
58
|
+
### Step 4: Determine the next task number
|
|
59
|
+
|
|
60
|
+
Scan **all** task locations to find the next available number:
|
|
61
|
+
- `mcp__serena__list_dir` on `wiki/work/tasks/` and `wiki/work/tasks/archive/` (skip either that doesn't exist).
|
|
62
|
+
- Collect every `TASK-NNN` prefix from filenames across **both** directories. Take `max + 1`, zero-pad to 3 digits. The first task is `TASK-001`.
|
|
63
|
+
- Also scan `wiki/work/tasks/index.md` for any reserved IDs not yet on disk.
|
|
64
|
+
- Never re-use a number — IDs are immutable references, and archived tasks keep their original number forever (terminal tasks move to `archive/`; they don't stay in `wiki/work/tasks/`).
|
|
65
|
+
|
|
66
|
+
This number is a preview for planning; re-verify immediately before writing (Step 7a).
|
|
67
|
+
|
|
68
|
+
### Step 5: Identify dependencies
|
|
69
|
+
|
|
70
|
+
Review active tasks by listing `wiki/work/tasks/` and reading the index at `wiki/work/tasks/index.md`. For each active task, determine whether the new task:
|
|
71
|
+
- **depends_on** it (requires it to complete first)
|
|
72
|
+
- **blocks** it (must complete before that task can start)
|
|
73
|
+
- **parallel_safe_with** it (can run concurrently without conflict)
|
|
74
|
+
|
|
75
|
+
Present a compact table and confirm with the user via `AskUserQuestion` before proceeding.
|
|
76
|
+
|
|
77
|
+
### Step 6: Research and clarify approach
|
|
78
|
+
|
|
79
|
+
Investigate relevant code via Serena, consult Context7 for library docs if needed, use Brave Search for best practices. If multiple valid approaches exist, present a comparison and ask via `AskUserQuestion` before committing.
|
|
80
|
+
|
|
81
|
+
### Step 7: Present the plan and confirm
|
|
82
|
+
|
|
83
|
+
Before writing, present:
|
|
84
|
+
- Core objective
|
|
85
|
+
- Key design decisions
|
|
86
|
+
- High-level step breakdown
|
|
87
|
+
|
|
88
|
+
Confirm with the user via `AskUserQuestion`.
|
|
89
|
+
|
|
90
|
+
### Step 7a: Re-verify next task number — IMMEDIATELY before writing
|
|
91
|
+
|
|
92
|
+
Re-run the scan from Step 4. If the number planned in Step 7 is now taken, silently bump to the new next-available number. **Never call `Write` before completing this re-scan.**
|
|
93
|
+
|
|
94
|
+
### Step 8: Create the task file
|
|
95
|
+
|
|
96
|
+
Create `wiki/work/tasks/TASK-NNN-slug.md` using the `Write` tool.
|
|
97
|
+
|
|
98
|
+
**Frontmatter** (required):
|
|
99
|
+
```yaml
|
|
100
|
+
---
|
|
101
|
+
id: TASK-NNN
|
|
102
|
+
title: "<task title>"
|
|
103
|
+
status: todo
|
|
104
|
+
created: YYYY-MM-DD
|
|
105
|
+
updated: YYYY-MM-DD
|
|
106
|
+
depends_on: []
|
|
107
|
+
blocks: []
|
|
108
|
+
parallel_safe_with: []
|
|
109
|
+
uat: ""
|
|
110
|
+
tags: []
|
|
111
|
+
---
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
Populate `depends_on`, `blocks`, and `parallel_safe_with` from Step 5 as lists of `TASK-NNN` IDs (empty list if none).
|
|
115
|
+
|
|
116
|
+
**Body structure**:
|
|
117
|
+
|
|
118
|
+
```markdown
|
|
119
|
+
# TASK-NNN — Task Title
|
|
120
|
+
|
|
121
|
+
implements::[[DEC-NNNN#DM]] ← only when a decision reference was provided
|
|
122
|
+
|
|
123
|
+
## Objective
|
|
124
|
+
|
|
125
|
+
<one paragraph describing what this task achieves>
|
|
126
|
+
|
|
127
|
+
## Approach
|
|
128
|
+
|
|
129
|
+
<design decisions, trade-offs, chosen solution>
|
|
130
|
+
|
|
131
|
+
## Steps
|
|
132
|
+
|
|
133
|
+
### 1. Section Name <!-- agent: general-purpose -->
|
|
134
|
+
|
|
135
|
+
- [ ] Step detail
|
|
136
|
+
- Sub-detail: specific file paths, function names, etc.
|
|
137
|
+
|
|
138
|
+
### 2. Next Section <!-- agent: general-purpose -->
|
|
139
|
+
|
|
140
|
+
- [ ] Step detail
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
**The task file IS the plan.** `/tackle` executes steps verbatim. Every step must include specific file paths, function/component names, and enough implementation detail that an agent can execute without ambiguity.
|
|
144
|
+
|
|
145
|
+
Agent type annotations: valid types are `general-purpose`, `Explore`, `Plan`.
|
|
146
|
+
|
|
147
|
+
**Decision link** (only when Step 2 found an accepted decision reference): Insert `implements::[[DEC-NNNN#DM]]` as a typed link on the line immediately after the H1, before `## Objective`.
|
|
148
|
+
|
|
149
|
+
### Step 9: Update the family index
|
|
150
|
+
|
|
151
|
+
Append to `wiki/work/tasks/index.md`:
|
|
152
|
+
|
|
153
|
+
```
|
|
154
|
+
- [TASK-NNN — Title](TASK-NNN-slug.md) — one-line objective · todo
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
If the file does not exist, create it with a `# Tasks` heading and the list entry. Insert in numeric order.
|
|
158
|
+
|
|
159
|
+
### Step 10: Update the decision file (only when Step 2 found a decision reference)
|
|
160
|
+
|
|
161
|
+
In the decision's `### Links` section, add or append a `Source task(s):` line:
|
|
162
|
+
|
|
163
|
+
```
|
|
164
|
+
- Source task(s): [[TASK-NNN]] — **WIP** (added YYYY-MM-DD)
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
If no `### Links` section exists, create one before the closing `---` separator of that decision block. Use `Read` then `Edit` — never shell redirection.
|
|
168
|
+
|
|
169
|
+
### Step 11: Update the roadmap file (only when Step 3 found a roadmap reference)
|
|
170
|
+
|
|
171
|
+
Read the roadmap file. Identify the last `## Phase N:` section (or any checklist section). Append a new `- [ ]` line:
|
|
172
|
+
|
|
173
|
+
```
|
|
174
|
+
- [ ] [[TASK-NNN: <task title>]]
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
Update the roadmap's `updated:` frontmatter field to today's date. Use `Read` then `Edit`.
|
|
178
|
+
|
|
179
|
+
### Step 12: Append to wiki/log.md
|
|
180
|
+
|
|
181
|
+
Append:
|
|
182
|
+
|
|
183
|
+
```
|
|
184
|
+
## [YYYY-MM-DD] task | TASK-NNN <task title>
|
|
185
|
+
Created task TASK-NNN: <one sentence summarising the objective>.
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
### Step 13: Refresh the hot cache
|
|
189
|
+
|
|
190
|
+
The new task is durable, cross-session-relevant wiki state. Run the **Hot Cache Refresh** procedure — defined in `/wiki-ingest` Step 8 (`lib/skills/wiki-ingest/SKILL.md`) — to regenerate `wiki/hot.md` in full, surfacing this task under Recent Changes (and Active Threads if it belongs to an in-flight roadmap). Do not restate the procedure here; follow it as written.
|
|
191
|
+
|
|
192
|
+
### Step 14: Confirm completion
|
|
193
|
+
|
|
194
|
+
Report:
|
|
195
|
+
- Created file: `wiki/work/tasks/TASK-NNN-slug.md`
|
|
196
|
+
- Task ID: `TASK-NNN`
|
|
197
|
+
- Status: `todo`
|
|
198
|
+
- Next steps:
|
|
199
|
+
|
|
200
|
+
```
|
|
201
|
+
To implement: /tackle wiki/work/tasks/TASK-NNN-slug.md
|
|
202
|
+
To generate tests: /uat-generate TASK-NNN
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
If linked to a roadmap, mention which roadmap was updated and suggest:
|
|
206
|
+
```
|
|
207
|
+
To see what's next: /roadmap-next wiki/work/roadmaps/NNN-slug.md
|
|
208
|
+
```
|
|
@@ -0,0 +1,294 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: task-audit
|
|
3
|
+
description: Generate a dependency graph of active tasks showing which block others and which can run in parallel; also checks for unannotated implementations and auto-completes tasks
|
|
4
|
+
category: researching
|
|
5
|
+
model: claude-sonnet-4-6
|
|
6
|
+
argument-hint: [--json]
|
|
7
|
+
disable-model-invocation: false
|
|
8
|
+
user-invocable: true
|
|
9
|
+
---
|
|
10
|
+
**Prereqs:** obey `.docs/guides/mcp-tools.md` + `wiki/work/tasks/lifecycle.md`.
|
|
11
|
+
|
|
12
|
+
# Task Audit
|
|
13
|
+
|
|
14
|
+
Analyse all active tasks: verify implementation completeness, auto-check unannotated finished steps, move fully-completed tasks, parse dependency blocks, build a directed dependency graph, and surface which tasks block others and which can be safely parallelised.
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
**Flags**: $ARGUMENTS
|
|
19
|
+
|
|
20
|
+
- `--json` — also emit a raw JSON adjacency list (useful for scripting)
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## Step 1: Load the Task Index
|
|
25
|
+
|
|
26
|
+
Read `wiki/work/tasks/index.md` using the `Read` tool.
|
|
27
|
+
|
|
28
|
+
- Parse every active-item bullet line — format `- [TASK-NNN — Title](TASK-NNN-slug.md) — one-line summary · status`. Extract the `TASK-NNN` ID and the linked file path (e.g. `wiki/work/tasks/TASK-001-project-registry-push.md`) for each.
|
|
29
|
+
- `index.md` lists active items only and carries no progress or flags columns — those are computed from each task file in Step 2.
|
|
30
|
+
- If the list is empty, report "No active tasks — nothing to audit." and STOP.
|
|
31
|
+
|
|
32
|
+
Do **not** scan the directory directly. The index is authoritative for active tasks.
|
|
33
|
+
|
|
34
|
+
---
|
|
35
|
+
|
|
36
|
+
## Step 2: Read Each Task File — Check Completeness and Parse Dependencies
|
|
37
|
+
|
|
38
|
+
For each task file path collected in Step 1, **read the file once** using the `Read` tool (or Serena's `find_symbol`/`get_symbols_overview` for structured markdown traversal). Do all of 2a–2e in a single pass per file to avoid re-reading.
|
|
39
|
+
|
|
40
|
+
### 2a. Extract All Steps
|
|
41
|
+
|
|
42
|
+
Scan every checklist item in the file — lines matching `- [ ] …` (incomplete) or `- [x] …` / `- [X] …` (complete). Record:
|
|
43
|
+
|
|
44
|
+
- `unchecked`: list of step descriptions without a checkmark
|
|
45
|
+
- `checked`: list of step descriptions already checked
|
|
46
|
+
- `total`: count of all steps
|
|
47
|
+
|
|
48
|
+
### 2b. Verify Unannotated Implementations
|
|
49
|
+
|
|
50
|
+
For each unchecked step, determine whether the work it describes is **actually implemented** in the codebase:
|
|
51
|
+
|
|
52
|
+
1. Extract the key noun/verb from the step description (e.g. "Add `foo()` helper", "Write migration for `users` table").
|
|
53
|
+
2. Use Serena's `find_symbol` or `search_for_pattern` to look for the relevant symbol, file, or pattern.
|
|
54
|
+
3. If evidence of a complete implementation is found (the symbol exists, the file is present, the migration exists, etc.), mark the step as **auto-completable**.
|
|
55
|
+
|
|
56
|
+
Be conservative: only mark a step auto-completable when the evidence is unambiguous. When the step is vague or the search returns nothing definitive, leave it unchecked and note it as **unverified**.
|
|
57
|
+
|
|
58
|
+
### 2c. Apply Checkmarks
|
|
59
|
+
|
|
60
|
+
For every step confirmed as auto-completable in 2b, update the task file using `Edit` (or Serena's `replace_content`): change `- [ ]` → `- [x]` for that line.
|
|
61
|
+
|
|
62
|
+
After applying all updates, recount `checked` and `total`. Track which tasks had checkmarks added (include them in the Step 4 report as **auto-completed steps**).
|
|
63
|
+
|
|
64
|
+
### 2d. Move Fully-Completed Tasks
|
|
65
|
+
|
|
66
|
+
If `checked == total` (all steps are now checked) after 2c:
|
|
67
|
+
|
|
68
|
+
1. Set `status: done` in the task file's frontmatter using `Edit`, then move it from `wiki/work/tasks/` to `wiki/work/tasks/archive/` using `Bash` (`git mv` only).
|
|
69
|
+
2. Delete its line from `wiki/work/tasks/index.md` and append it to `wiki/work/tasks/archive/index.md`.
|
|
70
|
+
3. Scan all other active task files for references to this task's ID (e.g. in their dependency blocks). For each reference found, note it in the Step 4 report as a **now-resolved dependency** — do not auto-edit those files, but suggest `/task-update <NNN>` to clean them up.
|
|
71
|
+
4. Mark the task as `completed: true` in its node record so Step 3 treats it as resolved.
|
|
72
|
+
|
|
73
|
+
### 2e. Parse the Dependency Block
|
|
74
|
+
|
|
75
|
+
In the same file read, locate the dependency blockquote appearing **immediately after the `# NNN —` title line** and **before `## Objective`**:
|
|
76
|
+
|
|
77
|
+
```markdown
|
|
78
|
+
> **Depends on**: [002-foo](002-foo.md), [003-bar](003-bar.md)
|
|
79
|
+
> **Blocks**: [008-baz](008-baz.md)
|
|
80
|
+
> **Parallel-safe with**: [005-qux](005-qux.md), [006-quux](006-quux.md)
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
- Values may be `none` if the field is empty.
|
|
84
|
+
- Links follow the pattern `[NNN-slug](NNN-slug.md)` — extract the NNN-slug identifier from each link.
|
|
85
|
+
- A task with no dependency block at all is treated as having `Depends on: none`, `Blocks: none`, `Parallel-safe with: none`.
|
|
86
|
+
|
|
87
|
+
### 2f. Build the Node Record
|
|
88
|
+
|
|
89
|
+
For each task (skipping any moved to completed in 2d), produce a record:
|
|
90
|
+
|
|
91
|
+
```
|
|
92
|
+
{
|
|
93
|
+
id: "NNN-slug",
|
|
94
|
+
num: NNN,
|
|
95
|
+
depends_on: ["NNN-slug", ...], # tasks that must complete before this one
|
|
96
|
+
blocks: ["NNN-slug", ...], # tasks this one must complete before they can start
|
|
97
|
+
parallel_safe: ["NNN-slug", ...], # tasks explicitly marked safe to run alongside
|
|
98
|
+
progress: "X/Y", # updated count after auto-checkmarks
|
|
99
|
+
flags: "[WIP]" | "—" | etc,
|
|
100
|
+
missing_block: true/false, # true if the dependency block was absent entirely
|
|
101
|
+
auto_checked: ["step description", ...], # steps that were auto-completed in 2c
|
|
102
|
+
unverified: ["step description", ...] # unchecked steps whose implementation could not be confirmed
|
|
103
|
+
}
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
Note tasks missing the dependency block — list them in the Step 4 issues report so the user knows to run `/task-update` on them.
|
|
107
|
+
|
|
108
|
+
---
|
|
109
|
+
|
|
110
|
+
## Step 3: Derive the Full Dependency Graph
|
|
111
|
+
|
|
112
|
+
### 3a. Validate edges
|
|
113
|
+
|
|
114
|
+
For every `depends_on` and `blocks` edge, confirm the referenced task ID appears in the active index. If a reference points to a task not in the active index (e.g. it completed or was trashed), mark it as a **stale reference** and note it in the report — do not abort.
|
|
115
|
+
|
|
116
|
+
Cross-check symmetry: if task A says it blocks task B, but task B does not list A in its `depends_on`, flag the asymmetry (don't auto-correct).
|
|
117
|
+
|
|
118
|
+
### 3b. Detect cycles
|
|
119
|
+
|
|
120
|
+
Walk the dependency graph using DFS. If a cycle is found (A → B → A), flag it as a **blocking cycle** — these tasks cannot proceed until the cycle is resolved. List every cycle found.
|
|
121
|
+
|
|
122
|
+
### 3c. Compute parallelism groups
|
|
123
|
+
|
|
124
|
+
A set of tasks is **parallelisable** if no task in the set has a directed dependency on any other task in the set (directly or transitively). Use topological sort to group tasks into execution waves:
|
|
125
|
+
|
|
126
|
+
- **Wave 1**: tasks with no unresolved `depends_on` (all prerequisites already completed or none listed)
|
|
127
|
+
- **Wave 2**: tasks whose only blockers are Wave 1 tasks
|
|
128
|
+
- **Wave N**: and so on
|
|
129
|
+
|
|
130
|
+
Within a wave, all tasks are parallelisable with each other unless an explicit `parallel_safe` field contradicts it (i.e. two tasks in the same wave where neither lists the other in `parallel_safe` — treat that as unknown/untested rather than unsafe unless a flag says otherwise).
|
|
131
|
+
|
|
132
|
+
---
|
|
133
|
+
|
|
134
|
+
## Step 4: Output the Audit Report
|
|
135
|
+
|
|
136
|
+
Print the full report in this order:
|
|
137
|
+
|
|
138
|
+
### 4a. Dependency Graph (Mermaid — also persisted to `wiki/work/tasks/dependency-graph.md` in Step 5)
|
|
139
|
+
|
|
140
|
+
```
|
|
141
|
+
## Dependency Graph
|
|
142
|
+
|
|
143
|
+
\`\`\`mermaid
|
|
144
|
+
graph TD
|
|
145
|
+
001["001-project-registry-push<br/>0/18"]
|
|
146
|
+
007["007-publish-npm-package<br/>0/43 [DEFERRED-TO-UAT]"]
|
|
147
|
+
001 --> 007
|
|
148
|
+
005["005-command-anti-patterns<br/>26/29 [DEFERRED-TO-UAT]"]
|
|
149
|
+
006["006-migrate-commands-to-skills<br/>55/55"]
|
|
150
|
+
009["009-audit-skills-vs-sdlc<br/>0/10"]
|
|
151
|
+
\`\`\`
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
- Node label: `NNN-slug\nProgress [Flags]` — use `<br/>` for line breaks inside Mermaid labels.
|
|
155
|
+
- Solid arrow `-->` for `depends_on` / `blocks` edges (direction: prerequisite → dependent).
|
|
156
|
+
- Dashed arrow `-.->` for `parallel_safe` edges (bidirectional, draw once).
|
|
157
|
+
- Tasks with `[BLOCKED]` or `[FAILED]` flags use a distinct node shape: `001[["001-slug"]]` (double bracket = stadium shape).
|
|
158
|
+
|
|
159
|
+
### 4b. Execution Waves Table
|
|
160
|
+
|
|
161
|
+
```
|
|
162
|
+
## Execution Waves (Parallelism)
|
|
163
|
+
|
|
164
|
+
| Wave | Tasks | Can run in parallel |
|
|
165
|
+
|------|-------|---------------------|
|
|
166
|
+
| 1 | 001-project-registry-push, 005-command-anti-patterns | Yes — no shared dependencies |
|
|
167
|
+
| 2 | 007-publish-npm-package | Waits for Wave 1 |
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
For each wave, note any tasks within it that have an **unknown parallel-safety** (no `parallel_safe` entries exist between them) with a ⚠️ marker.
|
|
171
|
+
|
|
172
|
+
### 4c. Blocking Summary
|
|
173
|
+
|
|
174
|
+
```
|
|
175
|
+
## Blocking Chains
|
|
176
|
+
|
|
177
|
+
- 001 → 007 (001 must complete before 007 can start)
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
If no blocking chains exist: "No blocking dependencies found — all tasks are independent."
|
|
181
|
+
|
|
182
|
+
### 4d. Completion Findings
|
|
183
|
+
|
|
184
|
+
Report what Step 2 discovered and changed:
|
|
185
|
+
|
|
186
|
+
```
|
|
187
|
+
## Completion Findings
|
|
188
|
+
|
|
189
|
+
### Auto-Completed Steps
|
|
190
|
+
| Task | Step | Evidence |
|
|
191
|
+
|------|------|----------|
|
|
192
|
+
| 005-command-anti-patterns | "Add mcp-tools.md guide" | File found at .docs/guides/mcp-tools.md |
|
|
193
|
+
|
|
194
|
+
### Fully-Completed Tasks Moved
|
|
195
|
+
| Task | Action |
|
|
196
|
+
|------|--------|
|
|
197
|
+
| 005-command-anti-patterns | Moved to wiki/work/tasks/archive/ — update references: /task-update 007 |
|
|
198
|
+
|
|
199
|
+
### Unverified Steps (implementation unclear)
|
|
200
|
+
| Task | Step |
|
|
201
|
+
|------|------|
|
|
202
|
+
| 009-audit-skills-vs-sdlc | "Configure CI gate for audit output" |
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
Omit any section whose table would be empty.
|
|
206
|
+
|
|
207
|
+
### 4e. Issues Found
|
|
208
|
+
|
|
209
|
+
```
|
|
210
|
+
## Issues
|
|
211
|
+
|
|
212
|
+
| Task | Issue |
|
|
213
|
+
|------|-------|
|
|
214
|
+
| 006-migrate-commands-to-skills | Missing dependency block — run `/task-update 006` to add one |
|
|
215
|
+
| 009-audit-skills-vs-sdlc | Stale reference: depends_on "003-deleted-task" not in active index |
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
Categories:
|
|
219
|
+
- **Missing dependency block** — task file has no `> **Depends on**:` block
|
|
220
|
+
- **Stale reference** — referenced task ID not found in active index
|
|
221
|
+
- **Asymmetric edge** — A blocks B but B doesn't list A in depends_on
|
|
222
|
+
- **Cycle** — dependency cycle detected (list all members)
|
|
223
|
+
- **Now-resolved dependency** — a task was moved to completed; other tasks still reference it in their dependency blocks
|
|
224
|
+
|
|
225
|
+
If no issues: "No issues found."
|
|
226
|
+
|
|
227
|
+
### 4f. Suggested Next Actions
|
|
228
|
+
|
|
229
|
+
Based on the graph, suggest actionable next steps:
|
|
230
|
+
|
|
231
|
+
```
|
|
232
|
+
## Suggested Next Steps
|
|
233
|
+
|
|
234
|
+
Wave 1 tasks are unblocked and can start immediately:
|
|
235
|
+
/tackle wiki/work/tasks/001-project-registry-push.md
|
|
236
|
+
/tackle wiki/work/tasks/005-command-anti-patterns.md ← run in parallel
|
|
237
|
+
|
|
238
|
+
Fix missing dependency blocks:
|
|
239
|
+
/task-update 006
|
|
240
|
+
/task-update 009
|
|
241
|
+
|
|
242
|
+
Clean up now-resolved dependency references:
|
|
243
|
+
/task-update 007 (005 was moved to completed)
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
---
|
|
247
|
+
|
|
248
|
+
## Step 5: Persist the Dependency Graph
|
|
249
|
+
|
|
250
|
+
**Always run this step** (regardless of flags).
|
|
251
|
+
|
|
252
|
+
Write the generated graph to its own file, `wiki/work/tasks/dependency-graph.md` — do **not** inline it into `index.md`. `index.md`'s contract is "active items only, as a flat bullet list" (see `wiki/conventions.md`); a large auto-generated Mermaid section would violate that. A dedicated file also lets the graph be regenerated wholesale each run without disturbing the active list.
|
|
253
|
+
|
|
254
|
+
1. Overwrite `wiki/work/tasks/dependency-graph.md` using `Write` with this content:
|
|
255
|
+
|
|
256
|
+
```markdown
|
|
257
|
+
---
|
|
258
|
+
title: Task Dependency Graph
|
|
259
|
+
updated: YYYY-MM-DD
|
|
260
|
+
---
|
|
261
|
+
|
|
262
|
+
# Task Dependency Graph
|
|
263
|
+
|
|
264
|
+
> Auto-generated by `/task-audit` on YYYY-MM-DD. Re-run to refresh. Do not edit by hand.
|
|
265
|
+
|
|
266
|
+
<paste the Mermaid block from Step 4a>
|
|
267
|
+
|
|
268
|
+
<paste the Execution Waves table from Step 4b>
|
|
269
|
+
|
|
270
|
+
<paste the Blocking Chains section from Step 4c>
|
|
271
|
+
```
|
|
272
|
+
|
|
273
|
+
2. Ensure `wiki/work/tasks/index.md` carries a one-line cross-link to the graph, directly under its `Entry format:` line: `Dependency graph: [dependency-graph.md](dependency-graph.md) — regenerated by /task-audit.` If that line is already present, leave it; if absent, add it with a single `Edit`.
|
|
274
|
+
|
|
275
|
+
There must be **exactly one** `dependency-graph.md` file after this step, and it holds the only copy of the graph. Never write the graph into `index.md` or a `README.md`.
|
|
276
|
+
|
|
277
|
+
**Only if `--json` flag is present in `$ARGUMENTS`:**
|
|
278
|
+
|
|
279
|
+
Print the raw adjacency list as a fenced JSON block:
|
|
280
|
+
|
|
281
|
+
```json
|
|
282
|
+
{
|
|
283
|
+
"tasks": [
|
|
284
|
+
{
|
|
285
|
+
"id": "001-project-registry-push",
|
|
286
|
+
"depends_on": [],
|
|
287
|
+
"blocks": ["007-publish-npm-package"],
|
|
288
|
+
"parallel_safe": ["005-command-anti-patterns"],
|
|
289
|
+
"progress": "0/18",
|
|
290
|
+
"flags": "—"
|
|
291
|
+
}
|
|
292
|
+
]
|
|
293
|
+
}
|
|
294
|
+
```
|