@llipe.com/dev-tasks 0.6.1

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.
Files changed (230) hide show
  1. package/CHANGELOG.md +104 -0
  2. package/README.md +823 -0
  3. package/bundle-manifest.json +113 -0
  4. package/dist/adapters/cli/extract-all.d.ts +31 -0
  5. package/dist/adapters/cli/extract-all.d.ts.map +1 -0
  6. package/dist/adapters/cli/extract-all.js +374 -0
  7. package/dist/adapters/cli/extract-all.js.map +1 -0
  8. package/dist/adapters/cli/extract-asyncapi.d.ts +26 -0
  9. package/dist/adapters/cli/extract-asyncapi.d.ts.map +1 -0
  10. package/dist/adapters/cli/extract-asyncapi.js +142 -0
  11. package/dist/adapters/cli/extract-asyncapi.js.map +1 -0
  12. package/dist/adapters/cli/extract-component.d.ts +24 -0
  13. package/dist/adapters/cli/extract-component.d.ts.map +1 -0
  14. package/dist/adapters/cli/extract-component.js +198 -0
  15. package/dist/adapters/cli/extract-component.js.map +1 -0
  16. package/dist/adapters/cli/extract-detect.d.ts +19 -0
  17. package/dist/adapters/cli/extract-detect.d.ts.map +1 -0
  18. package/dist/adapters/cli/extract-detect.js +98 -0
  19. package/dist/adapters/cli/extract-detect.js.map +1 -0
  20. package/dist/adapters/cli/extract-openapi.d.ts +29 -0
  21. package/dist/adapters/cli/extract-openapi.d.ts.map +1 -0
  22. package/dist/adapters/cli/extract-openapi.js +111 -0
  23. package/dist/adapters/cli/extract-openapi.js.map +1 -0
  24. package/dist/adapters/cli/extract-schema.d.ts +15 -0
  25. package/dist/adapters/cli/extract-schema.d.ts.map +1 -0
  26. package/dist/adapters/cli/extract-schema.js +39 -0
  27. package/dist/adapters/cli/extract-schema.js.map +1 -0
  28. package/dist/adapters/cli/index.d.ts +6 -0
  29. package/dist/adapters/cli/index.d.ts.map +1 -0
  30. package/dist/adapters/cli/index.js +5 -0
  31. package/dist/adapters/cli/index.js.map +1 -0
  32. package/dist/adapters/cli/parse-args.d.ts +22 -0
  33. package/dist/adapters/cli/parse-args.d.ts.map +1 -0
  34. package/dist/adapters/cli/parse-args.js +63 -0
  35. package/dist/adapters/cli/parse-args.js.map +1 -0
  36. package/dist/adapters/mcp/index.d.ts +5 -0
  37. package/dist/adapters/mcp/index.d.ts.map +1 -0
  38. package/dist/adapters/mcp/index.js +2 -0
  39. package/dist/adapters/mcp/index.js.map +1 -0
  40. package/dist/bin/dev-tasks.d.ts +7 -0
  41. package/dist/bin/dev-tasks.d.ts.map +1 -0
  42. package/dist/bin/dev-tasks.js +275 -0
  43. package/dist/bin/dev-tasks.js.map +1 -0
  44. package/dist/bin/dt.d.ts +7 -0
  45. package/dist/bin/dt.d.ts.map +1 -0
  46. package/dist/bin/dt.js +159 -0
  47. package/dist/bin/dt.js.map +1 -0
  48. package/dist/core/catalog/index.d.ts +5 -0
  49. package/dist/core/catalog/index.d.ts.map +1 -0
  50. package/dist/core/catalog/index.js +2 -0
  51. package/dist/core/catalog/index.js.map +1 -0
  52. package/dist/core/context/index.d.ts +5 -0
  53. package/dist/core/context/index.d.ts.map +1 -0
  54. package/dist/core/context/index.js +2 -0
  55. package/dist/core/context/index.js.map +1 -0
  56. package/dist/core/distribution/backup.d.ts +24 -0
  57. package/dist/core/distribution/backup.d.ts.map +1 -0
  58. package/dist/core/distribution/backup.js +37 -0
  59. package/dist/core/distribution/backup.js.map +1 -0
  60. package/dist/core/distribution/doctor.d.ts +35 -0
  61. package/dist/core/distribution/doctor.d.ts.map +1 -0
  62. package/dist/core/distribution/doctor.js +158 -0
  63. package/dist/core/distribution/doctor.js.map +1 -0
  64. package/dist/core/distribution/hash.d.ts +14 -0
  65. package/dist/core/distribution/hash.d.ts.map +1 -0
  66. package/dist/core/distribution/hash.js +21 -0
  67. package/dist/core/distribution/hash.js.map +1 -0
  68. package/dist/core/distribution/index.d.ts +18 -0
  69. package/dist/core/distribution/index.d.ts.map +1 -0
  70. package/dist/core/distribution/index.js +12 -0
  71. package/dist/core/distribution/index.js.map +1 -0
  72. package/dist/core/distribution/install.d.ts +25 -0
  73. package/dist/core/distribution/install.d.ts.map +1 -0
  74. package/dist/core/distribution/install.js +81 -0
  75. package/dist/core/distribution/install.js.map +1 -0
  76. package/dist/core/distribution/manifest.d.ts +28 -0
  77. package/dist/core/distribution/manifest.d.ts.map +1 -0
  78. package/dist/core/distribution/manifest.js +38 -0
  79. package/dist/core/distribution/manifest.js.map +1 -0
  80. package/dist/core/distribution/migrate.d.ts +54 -0
  81. package/dist/core/distribution/migrate.d.ts.map +1 -0
  82. package/dist/core/distribution/migrate.js +200 -0
  83. package/dist/core/distribution/migrate.js.map +1 -0
  84. package/dist/core/distribution/pin.d.ts +15 -0
  85. package/dist/core/distribution/pin.d.ts.map +1 -0
  86. package/dist/core/distribution/pin.js +37 -0
  87. package/dist/core/distribution/pin.js.map +1 -0
  88. package/dist/core/distribution/status.d.ts +20 -0
  89. package/dist/core/distribution/status.d.ts.map +1 -0
  90. package/dist/core/distribution/status.js +39 -0
  91. package/dist/core/distribution/status.js.map +1 -0
  92. package/dist/core/distribution/update.d.ts +41 -0
  93. package/dist/core/distribution/update.d.ts.map +1 -0
  94. package/dist/core/distribution/update.js +148 -0
  95. package/dist/core/distribution/update.js.map +1 -0
  96. package/dist/core/exit-codes.d.ts +23 -0
  97. package/dist/core/exit-codes.d.ts.map +1 -0
  98. package/dist/core/exit-codes.js +22 -0
  99. package/dist/core/exit-codes.js.map +1 -0
  100. package/dist/core/extract/asyncapi/index.d.ts +11 -0
  101. package/dist/core/extract/asyncapi/index.d.ts.map +1 -0
  102. package/dist/core/extract/asyncapi/index.js +7 -0
  103. package/dist/core/extract/asyncapi/index.js.map +1 -0
  104. package/dist/core/extract/asyncapi/payloads.d.ts +20 -0
  105. package/dist/core/extract/asyncapi/payloads.d.ts.map +1 -0
  106. package/dist/core/extract/asyncapi/payloads.js +421 -0
  107. package/dist/core/extract/asyncapi/payloads.js.map +1 -0
  108. package/dist/core/extract/asyncapi/topics.d.ts +27 -0
  109. package/dist/core/extract/asyncapi/topics.d.ts.map +1 -0
  110. package/dist/core/extract/asyncapi/topics.js +368 -0
  111. package/dist/core/extract/asyncapi/topics.js.map +1 -0
  112. package/dist/core/extract/asyncapi/types.d.ts +129 -0
  113. package/dist/core/extract/asyncapi/types.d.ts.map +1 -0
  114. package/dist/core/extract/asyncapi/types.js +5 -0
  115. package/dist/core/extract/asyncapi/types.js.map +1 -0
  116. package/dist/core/extract/asyncapi/validate.d.ts +29 -0
  117. package/dist/core/extract/asyncapi/validate.d.ts.map +1 -0
  118. package/dist/core/extract/asyncapi/validate.js +156 -0
  119. package/dist/core/extract/asyncapi/validate.js.map +1 -0
  120. package/dist/core/extract/component.d.ts +201 -0
  121. package/dist/core/extract/component.d.ts.map +1 -0
  122. package/dist/core/extract/component.js +258 -0
  123. package/dist/core/extract/component.js.map +1 -0
  124. package/dist/core/extract/detect.d.ts +35 -0
  125. package/dist/core/extract/detect.d.ts.map +1 -0
  126. package/dist/core/extract/detect.js +89 -0
  127. package/dist/core/extract/detect.js.map +1 -0
  128. package/dist/core/extract/index.d.ts +12 -0
  129. package/dist/core/extract/index.d.ts.map +1 -0
  130. package/dist/core/extract/index.js +6 -0
  131. package/dist/core/extract/index.js.map +1 -0
  132. package/dist/core/extract/openapi/index.d.ts +13 -0
  133. package/dist/core/extract/openapi/index.d.ts.map +1 -0
  134. package/dist/core/extract/openapi/index.js +9 -0
  135. package/dist/core/extract/openapi/index.js.map +1 -0
  136. package/dist/core/extract/openapi/llm-descriptions.d.ts +41 -0
  137. package/dist/core/extract/openapi/llm-descriptions.d.ts.map +1 -0
  138. package/dist/core/extract/openapi/llm-descriptions.js +36 -0
  139. package/dist/core/extract/openapi/llm-descriptions.js.map +1 -0
  140. package/dist/core/extract/openapi/route1.d.ts +36 -0
  141. package/dist/core/extract/openapi/route1.d.ts.map +1 -0
  142. package/dist/core/extract/openapi/route1.js +327 -0
  143. package/dist/core/extract/openapi/route1.js.map +1 -0
  144. package/dist/core/extract/openapi/route2.d.ts +46 -0
  145. package/dist/core/extract/openapi/route2.d.ts.map +1 -0
  146. package/dist/core/extract/openapi/route2.js +19 -0
  147. package/dist/core/extract/openapi/route2.js.map +1 -0
  148. package/dist/core/extract/openapi/route3.d.ts +26 -0
  149. package/dist/core/extract/openapi/route3.d.ts.map +1 -0
  150. package/dist/core/extract/openapi/route3.js +737 -0
  151. package/dist/core/extract/openapi/route3.js.map +1 -0
  152. package/dist/core/extract/openapi/types.d.ts +125 -0
  153. package/dist/core/extract/openapi/types.d.ts.map +1 -0
  154. package/dist/core/extract/openapi/types.js +5 -0
  155. package/dist/core/extract/openapi/types.js.map +1 -0
  156. package/dist/core/extract/openapi/validate.d.ts +29 -0
  157. package/dist/core/extract/openapi/validate.d.ts.map +1 -0
  158. package/dist/core/extract/openapi/validate.js +200 -0
  159. package/dist/core/extract/openapi/validate.js.map +1 -0
  160. package/dist/core/extract/orm/drizzle.d.ts +20 -0
  161. package/dist/core/extract/orm/drizzle.d.ts.map +1 -0
  162. package/dist/core/extract/orm/drizzle.js +283 -0
  163. package/dist/core/extract/orm/drizzle.js.map +1 -0
  164. package/dist/core/extract/orm/information-schema.d.ts +26 -0
  165. package/dist/core/extract/orm/information-schema.d.ts.map +1 -0
  166. package/dist/core/extract/orm/information-schema.js +142 -0
  167. package/dist/core/extract/orm/information-schema.js.map +1 -0
  168. package/dist/core/extract/orm/llm-descriptions.d.ts +28 -0
  169. package/dist/core/extract/orm/llm-descriptions.d.ts.map +1 -0
  170. package/dist/core/extract/orm/llm-descriptions.js +64 -0
  171. package/dist/core/extract/orm/llm-descriptions.js.map +1 -0
  172. package/dist/core/extract/orm/migration-inference.d.ts +25 -0
  173. package/dist/core/extract/orm/migration-inference.d.ts.map +1 -0
  174. package/dist/core/extract/orm/migration-inference.js +76 -0
  175. package/dist/core/extract/orm/migration-inference.js.map +1 -0
  176. package/dist/core/extract/orm/prisma.d.ts +23 -0
  177. package/dist/core/extract/orm/prisma.d.ts.map +1 -0
  178. package/dist/core/extract/orm/prisma.js +234 -0
  179. package/dist/core/extract/orm/prisma.js.map +1 -0
  180. package/dist/core/extract/orm/typeorm.d.ts +22 -0
  181. package/dist/core/extract/orm/typeorm.d.ts.map +1 -0
  182. package/dist/core/extract/orm/typeorm.js +269 -0
  183. package/dist/core/extract/orm/typeorm.js.map +1 -0
  184. package/dist/core/extract/orm/types.d.ts +97 -0
  185. package/dist/core/extract/orm/types.d.ts.map +1 -0
  186. package/dist/core/extract/orm/types.js +6 -0
  187. package/dist/core/extract/orm/types.js.map +1 -0
  188. package/dist/core/extract/prompt.d.ts +21 -0
  189. package/dist/core/extract/prompt.d.ts.map +1 -0
  190. package/dist/core/extract/prompt.js +79 -0
  191. package/dist/core/extract/prompt.js.map +1 -0
  192. package/dist/core/extract/provider.d.ts +117 -0
  193. package/dist/core/extract/provider.d.ts.map +1 -0
  194. package/dist/core/extract/provider.js +6 -0
  195. package/dist/core/extract/provider.js.map +1 -0
  196. package/dist/core/extract/providers/node-ts.d.ts +69 -0
  197. package/dist/core/extract/providers/node-ts.d.ts.map +1 -0
  198. package/dist/core/extract/providers/node-ts.js +311 -0
  199. package/dist/core/extract/providers/node-ts.js.map +1 -0
  200. package/dist/core/extract/render/schema-md.d.ts +16 -0
  201. package/dist/core/extract/render/schema-md.d.ts.map +1 -0
  202. package/dist/core/extract/render/schema-md.js +140 -0
  203. package/dist/core/extract/render/schema-md.js.map +1 -0
  204. package/dist/core/extract/report.d.ts +97 -0
  205. package/dist/core/extract/report.d.ts.map +1 -0
  206. package/dist/core/extract/report.js +47 -0
  207. package/dist/core/extract/report.js.map +1 -0
  208. package/dist/core/extract/schema.d.ts +36 -0
  209. package/dist/core/extract/schema.d.ts.map +1 -0
  210. package/dist/core/extract/schema.js +141 -0
  211. package/dist/core/extract/schema.js.map +1 -0
  212. package/dist/core/index.d.ts +15 -0
  213. package/dist/core/index.d.ts.map +1 -0
  214. package/dist/core/index.js +14 -0
  215. package/dist/core/index.js.map +1 -0
  216. package/dist/core/providers/index.d.ts +5 -0
  217. package/dist/core/providers/index.d.ts.map +1 -0
  218. package/dist/core/providers/index.js +2 -0
  219. package/dist/core/providers/index.js.map +1 -0
  220. package/dist/core/reconcile.d.ts +25 -0
  221. package/dist/core/reconcile.d.ts.map +1 -0
  222. package/dist/core/reconcile.js +36 -0
  223. package/dist/core/reconcile.js.map +1 -0
  224. package/dist/core/scope/index.d.ts +5 -0
  225. package/dist/core/scope/index.d.ts.map +1 -0
  226. package/dist/core/scope/index.js +2 -0
  227. package/dist/core/scope/index.js.map +1 -0
  228. package/package.json +77 -0
  229. package/schemas/.gitkeep +0 -0
  230. package/skills/.gitkeep +0 -0
package/README.md ADDED
@@ -0,0 +1,823 @@
1
+ # dev-tasks
2
+
3
+ A set of agents, skills, and instructions for GitHub Copilot, Claude Code, Kiro, and other AI coding agents to run structured, PRD-driven development workflows. Inspired by [snarktank/ai-dev-tasks](https://github.com/snarktank/ai-dev-tasks).
4
+
5
+ ## Quick Start
6
+
7
+ ### Agent workflow (skills + instructions)
8
+
9
+ ```bash
10
+ # 1. Bootstrap the installer into your repo
11
+ curl -fsSL https://raw.githubusercontent.com/llipe/dev-tasks/main/dev-tasks.sh \
12
+ -o dev-tasks.sh && chmod +x dev-tasks.sh
13
+
14
+ # 2. Install (default: all platforms — Copilot + Claude Code + Kiro)
15
+ ./dev-tasks.sh install
16
+
17
+ # 3. Initialize your project context (run once per project)
18
+ # Invoke @product-engineer in Init Mode — produces docs/product-context.md
19
+ # and docs/technical-guidelines.md
20
+
21
+ # 4. Build a feature
22
+ # a) Invoke @product-engineer with a feature description or GitHub issue number
23
+ # → creates PRD → spec → stories → task list
24
+ # b) Invoke @developer with the task list path
25
+ # → implements, tests, and opens a PR
26
+
27
+ # 5. Keep up to date
28
+ ./dev-tasks.sh update # update toolkit files
29
+ ./dev-tasks.sh update --backup # same, but backs up current files first
30
+ ./dev-tasks.sh check # compare installed vs latest version
31
+ ```
32
+
33
+ ### `dt` CLI (multi-repo context)
34
+
35
+ ```bash
36
+ # 1. Install the npm package
37
+ pnpm add -g @llipe/dev-tasks
38
+
39
+ # 2. Extract your repo's metadata
40
+ dt extract all --interactive
41
+
42
+ # 3. Review the generated component.yaml and extraction_report.json
43
+ cat component.yaml
44
+ cat extraction_report.json
45
+
46
+ # 4. Keep distribution up to date with hash-based reconciliation
47
+ dev-tasks update
48
+ ```
49
+
50
+ **Platform profiles** — install only what you need:
51
+
52
+ ```bash
53
+ ./dev-tasks.sh install --profile copilot # .github/ only
54
+ ./dev-tasks.sh install --profile claude # .claude/ only
55
+ ./dev-tasks.sh install --profile kiro # .kiro/ only
56
+ ./dev-tasks.sh install --profile claude,kiro # mix and match
57
+ ./dev-tasks.sh install --profile all # everything (default)
58
+ ```
59
+
60
+ ---
61
+
62
+ ## The Core Idea
63
+
64
+ This system brings structure and clarity to AI-assisted development by:
65
+
66
+ - Defining scope with Product Requirements Documents (PRDs)
67
+ - Breaking requirements into actionable, implementation-ready tasks
68
+ - Guiding the AI to tackle one task at a time with checkpoints for review
69
+ - Providing specialized **agents** that orchestrate the workflow end-to-end
70
+ - Enforcing documentation, branch discipline, and GitHub-as-source-of-truth
71
+
72
+ ---
73
+
74
+ ## Taxonomy: Agent vs Skill vs Instruction
75
+
76
+ | Concept | Purpose | Loaded When | Decision Rule |
77
+ | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------- | ------------------------------------------------------------------------------------------- |
78
+ | **Agent** | Autonomous role with decision-making, phases, and handoff discipline. Owns a workflow end-to-end. | Invoked by name (`@agent`) | "Does it make decisions, own a multi-phase workflow, and hand off to other agents?" → Agent |
79
+ | **Skill** | Reusable on-demand capability. Describes _procedures_ or _activities_ that any agent can invoke when needed. Not loaded unless referenced. | On demand (invoked by agent or prompt) | "Is this capability needed only sometimes, by one or more agents?" → Skill |
80
+ | **Instruction** | Always-loaded rule scoped via `applyTo` frontmatter. Enforced automatically for every matching context. | Always (auto-applied by runtime) | "Must this rule be enforced every time, for every matching file or context?" → Instruction |
81
+
82
+ **Key distinctions:**
83
+
84
+ - Skills save context window space — they are loaded only when invoked, unlike instructions which are always present.
85
+ - Agent files define _who_ (identity, phases, handoff rules). Skill files define _how_ (procedures, templates, steps).
86
+ - Instructions are for cross-cutting rules that must never be forgotten (e.g., implementation discipline, planning format).
87
+
88
+ ---
89
+
90
+ ## Installation
91
+
92
+ ### Prerequisites
93
+
94
+ - macOS / Linux (or WSL on Windows)
95
+ - `git`
96
+ - `curl`
97
+ - `tar`
98
+ - `shasum` (or `sha256sum`)
99
+
100
+ ### Option A: Install `dev-tasks` into any repository (recommended)
101
+
102
+ Run this in the repository where you want to use the workflow:
103
+
104
+ ```bash
105
+ curl -fsSL https://raw.githubusercontent.com/llipe/dev-tasks/main/dev-tasks.sh \
106
+ -o dev-tasks.sh && chmod +x dev-tasks.sh
107
+ ./dev-tasks.sh install
108
+ ```
109
+
110
+ ### Option B: Set up this repository locally (contributors)
111
+
112
+ ```bash
113
+ git clone https://github.com/llipe/dev-tasks.git
114
+ cd dev-tasks
115
+ chmod +x dev-tasks.sh
116
+ ./dev-tasks.sh version
117
+ ./dev-tasks.sh check
118
+ ```
119
+
120
+ ### Verify the installation
121
+
122
+ After install, confirm these paths exist in your target repo:
123
+
124
+ - `.github/agents/`
125
+ - `.github/skills/`
126
+ - `.github/instructions/`
127
+ - `.github/prompts/`
128
+ - `.dev-tasks-version`
129
+
130
+ The default `--profile both` installs Copilot (`.github/`) and Claude Code (`.claude/`) file sets only. If you installed with `--profile kiro` or `--profile all`, also confirm:
131
+
132
+ - `.kiro/agents/`
133
+ - `.kiro/skills/`
134
+ - `.kiro/steering/`
135
+ - `.kiro/hooks/`
136
+
137
+ ---
138
+
139
+ ## Getting Started
140
+
141
+ ### 1. Install with the single-script installer
142
+
143
+ Bootstrap from any repository with one command:
144
+
145
+ ```bash
146
+ curl -fsSL https://raw.githubusercontent.com/llipe/dev-tasks/main/dev-tasks.sh \
147
+ -o dev-tasks.sh && chmod +x dev-tasks.sh
148
+ ./dev-tasks.sh install
149
+ ```
150
+
151
+ This downloads the latest versioned bundle from GitHub Releases, places all managed files in `.github/agents/`, `.github/skills/`, `.github/instructions/`, and `.github/prompts/`, writes `.dev-tasks-version` for traceability, and prints an **AGENTS.md integration prompt** showing what changed.
152
+
153
+ **Pin to a specific version:**
154
+
155
+ ```bash
156
+ ./dev-tasks.sh install v1.2.0
157
+ ```
158
+
159
+ **Check for updates:**
160
+
161
+ ```bash
162
+ ./dev-tasks.sh check
163
+ ```
164
+
165
+ **List installed files and directories:**
166
+
167
+ ```bash
168
+ ./dev-tasks.sh list
169
+ ```
170
+
171
+ **Update (with automatic backup):**
172
+
173
+ ```bash
174
+ ./dev-tasks.sh update --backup
175
+ ```
176
+
177
+ **Preview what would change without writing any files:**
178
+
179
+ ```bash
180
+ ./dev-tasks.sh update --dry-run
181
+ ```
182
+
183
+ See [Distribution & Script Reference](#distribution--script-reference) below for full documentation.
184
+
185
+ After install, your repo contains (Copilot + Claude Code, the default `--profile both`):
186
+
187
+ ```text
188
+ your-repo/
189
+ ├── dev-tasks.sh # Keep this — used for future updates
190
+ ├── .dev-tasks-version # Installed version metadata (JSON)
191
+ ├── .github/
192
+ │ ├── instructions/ # Always-loaded rules
193
+ │ │ ├── plan.instructions.md
194
+ │ │ ├── implement.instructions.md
195
+ │ │ └── domain/
196
+ │ │ └── nextjs-pages-components.instructions.md
197
+ │ ├── agents/ # Agent definitions (8 agents)
198
+ │ ├── skills/ # On-demand capabilities (13 skills)
199
+ │ └── prompts/ # Ready-to-use prompt templates
200
+ ├── docs/ # Foundation docs (generated by init)
201
+ ├── workstream/ # Active feature work
202
+ └── AGENTS.md # Master registry (you own this — see integration prompt)
203
+ ```
204
+
205
+ With `--profile kiro` or `--profile all`, your repo additionally (or instead, for `kiro`) contains:
206
+
207
+ ```text
208
+ your-repo/
209
+ └── .kiro/
210
+ ├── steering/ # Kiro's "instructions" equivalent (4 files)
211
+ │ ├── plan.md # inclusion: always
212
+ │ ├── implement.md # inclusion: always
213
+ │ ├── nextjs-pages-components.md # inclusion: fileMatch, fileMatchPattern: "**/*.tsx"
214
+ │ └── git-guard-notice.md # inclusion: always — Kiro-specific hook-limitation disclosure
215
+ ├── agents/ # Agent definitions (8 agents; prompts folded in as "Invocation Modes")
216
+ ├── skills/ # On-demand capabilities (13 skills, one dir each with SKILL.md)
217
+ └── hooks/
218
+ ├── git-guard.json # PreToolUse hook definition
219
+ └── scripts/git-guard.sh
220
+ ```
221
+
222
+ ### 2. Initialize your project foundation
223
+
224
+ Run the `product-engineer` agent in **Init Mode** to establish your product context and technical guidelines:
225
+
226
+ > Use the `product-engineer-init` prompt or invoke `@product-engineer` with a project description.
227
+
228
+ This produces `docs/product-context.md` and `docs/technical-guidelines.md`. Run this once per project (or when a major pivot occurs).
229
+
230
+ ### 3. Start building
231
+
232
+ | Situation | How to start |
233
+ | ------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
234
+ | **New feature / epic** | Invoke `product-engineer` with a feature description, then `developer` to implement |
235
+ | **Single GitHub Issue** | Invoke `product-engineer` with an issue number, then `developer` to implement |
236
+ | **Already have a task list** | Invoke `developer` with a task list path |
237
+ | **Multi-story PRD batch** | Invoke `planner` with a `/workstream` task file or milestone |
238
+ | **UX prototype** | Invoke `ux-engineer` with a PRD or SPEC path |
239
+ | **Docs out of date** | Invoke `technical-writer` |
240
+ | **Lint/type/test cleanup** | Invoke `housekeeping` |
241
+ | **Verifier compliance testing** | Invoke `verifier` with a spec or story to generate test plans (Design Mode) and audit delivered fidelity (Audit Mode) |
242
+
243
+ ### 4. (Optional) Add domain-specific instructions
244
+
245
+ Create technology-specific instruction files scoped to certain file patterns via `applyTo` frontmatter:
246
+
247
+ ```yaml
248
+ ---
249
+ applyTo: "apps/my-app/src/**/*.tsx"
250
+ ---
251
+ # Your project-specific component conventions here
252
+ ```
253
+
254
+ ---
255
+
256
+ ## Workflow Chains
257
+
258
+ These diagrams show how agents hand off to one another for each type of work. Match your situation to a chain below, then invoke the first agent in the chain — it drives the rest of the flow. The per-agent details are in the [Agents](#agents) reference that follows.
259
+
260
+ ### Agent Interaction Overview
261
+
262
+ ```mermaid
263
+ flowchart TD
264
+ %% Agents
265
+ PE[product-engineer]
266
+ DEV[developer]
267
+ PL[planner]
268
+ UX[ux-engineer]
269
+ VD[verifier\nDesign Mode]
270
+ VA[verifier\nAudit Mode]
271
+ GO[github-ops]
272
+ TW[technical-writer]
273
+ HK[housekeeping]
274
+
275
+ %% Skills (grouped)
276
+ subgraph "product-engineer skills"
277
+ S_INIT[activity-init]
278
+ S_REFINE[activity-refine]
279
+ S_SPEC[activity-generate-spec]
280
+ S_STORIES[activity-generate-stories]
281
+ S_PUBLISH[activity-publish-github]
282
+ S_DRIFT[activity-drift-reconciliation]
283
+ end
284
+
285
+ subgraph "verifier skills"
286
+ S_E2E[activity-e2e-test-design]
287
+ S_CONTRACT[activity-contract-test-design]
288
+ S_EDGE[activity-edge-case-refinement]
289
+ S_RANDOM[activity-random-test-tactics]
290
+ end
291
+
292
+ subgraph "shared skills"
293
+ S_GITOPS[git-ops]
294
+ S_MEMO[memo-cli-usage]
295
+ S_MOCKUP[webapp-mockup]
296
+ end
297
+
298
+ %% Main workflow: product-engineer → developer
299
+ PE -->|"PRD → spec → stories → plan"| DEV
300
+ PE -->|"multi-story plan"| PL
301
+ PL -->|"delegates per story"| DEV
302
+
303
+ %% UX loop
304
+ PE -->|"spec"| UX
305
+ UX -->|"gap analysis & refinements"| PE
306
+
307
+ %% Verifier design mode (test-first)
308
+ PE -->|"spec/stories"| VD
309
+ VD -->|"test plan"| DEV
310
+
311
+ %% Mandatory audit before PR
312
+ DEV -->|"PR ready"| VA
313
+ VA -->|"fidelity report"| DEV
314
+
315
+ %% Drift reconciliation
316
+ VA -.->|"drift findings\n(non-blocking)"| PE
317
+
318
+ %% Skill usage
319
+ PE --- S_INIT & S_REFINE & S_SPEC & S_STORIES & S_PUBLISH & S_DRIFT
320
+ VD --- S_E2E & S_CONTRACT & S_EDGE & S_RANDOM
321
+ DEV --- S_GITOPS & S_MEMO
322
+ PL --- S_GITOPS
323
+ UX --- S_MOCKUP
324
+ TW --- S_MEMO
325
+ PE --- S_MEMO
326
+
327
+ %% GitHub-ops supports all agents
328
+ GO -.->|"issues, PRs, labels"| PE
329
+ GO -.->|"issues, PRs, labels"| DEV
330
+ GO -.->|"issues, PRs, labels"| PL
331
+ ```
332
+
333
+ **Reading the diagram:**
334
+
335
+ - Solid arrows → direct handoffs between agents
336
+ - Dashed arrows → supporting/non-blocking interactions
337
+ - Boxes at the bottom → skills invoked by each agent
338
+ - The `verifier` audit before every PR is mandatory and non-skippable
339
+
340
+ ### Full Feature (PRD-Driven)
341
+
342
+ ```
343
+ product-engineer: refine → generate-spec → generate-stories → publish-github → plan
344
+ ↓
345
+ developer: implement
346
+ ```
347
+
348
+ ### Single GitHub Issue
349
+
350
+ ```
351
+ product-engineer: refine → plan
352
+ ↓
353
+ developer: implement
354
+ ```
355
+
356
+ ### Multi-Story Orchestration
357
+
358
+ ```
359
+ product-engineer: ... → plan
360
+ ↓
361
+ planner: orchestrate → developer: implement (per story, sequential)
362
+ ```
363
+
364
+ ### Quick Fix
365
+
366
+ ```
367
+ developer: implement
368
+ ```
369
+
370
+ ### UX Validation Loop
371
+
372
+ ```
373
+ product-engineer: refine → generate-spec → ux-engineer: mockups → product-engineer: update
374
+ ```
375
+
376
+ ### Test-First Design (Verifier)
377
+
378
+ ```
379
+ product-engineer: refine → spec → stories → plan
380
+ ↓
381
+ verifier (design mode): generate test plan (from spec or stories)
382
+ ↓
383
+ developer/planner: implement (feature + tests from test plan)
384
+ ↓ (automatic, mandatory, non-skippable)
385
+ verifier (audit mode): grey-box fidelity audit → fidelity report
386
+ ↓ (drift findings, non-blocking)
387
+ product-engineer: activity-drift-reconciliation
388
+ ```
389
+
390
+ ---
391
+
392
+ ## Agents
393
+
394
+ Agents are autonomous personas that orchestrate skills and activities.
395
+
396
+ > **Available for:** Copilot (`.github/agents/`), Claude Code (`.claude/agents/`), Kiro (`.kiro/agents/`). All three platforms define the same 8 agents below. On Kiro, each agent file also embeds an "Invocation Modes" section (see [Prompts](#prompts)).
397
+
398
+ ### `product-engineer`
399
+
400
+ Preparation agent — owns the full pre-coding chain:
401
+
402
+ - **Init Mode**: `activity-init` → product-context.md + technical-guidelines.md
403
+ - **Feature Mode**: `activity-refine` → `activity-generate-spec` → `activity-generate-stories` → `activity-publish-github` → `plan`
404
+ - **Issue Mode**: `activity-refine` → `plan`
405
+
406
+ Also owns drift reconciliation: routes `verifier` drift findings handed off by `developer`/`planner` into task-list/checklist expansion, new GitHub issues, or human-confirmed PRD/spec changelog updates via `activity-drift-reconciliation`.
407
+
408
+ Hands off to `developer` or `planner` for execution.
409
+
410
+ ### `developer`
411
+
412
+ Execution agent — implements code from an existing task list. Runs `implement`, which includes a mandatory, non-skippable `verifier` audit (`audit` mode) before every PR is marked ready — this is automatic, not optional. Uses `git-ops` for branch management.
413
+
414
+ ### `planner`
415
+
416
+ Multi-story orchestration with checkpoint/resume:
417
+
418
+ | Phase | What Happens |
419
+ | ----- | ---------------------------------------------------------------------------------------------------------- |
420
+ | 0 | Discover task source |
421
+ | 0.5 | Resume detection — checks for existing checkpoint state file |
422
+ | 1 | Parse stories and infer dependencies |
423
+ | 2 | Dependency graph — **user approval required** |
424
+ | 3 | Pre-flight — creates integration branch |
425
+ | 4 | Delegate to `developer` per story (each gated on a mandatory `verifier` audit); merge and write checkpoint |
426
+ | 5 | PRD-level rollup `verifier` audit, then consolidated PR to `main` — **user must approve** |
427
+
428
+ ### Other Agents
429
+
430
+ | Agent | Purpose |
431
+ | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
432
+ | `ux-engineer` | PRD/SPEC-to-mockup — feeds refinements back to `product-engineer` |
433
+ | `technical-writer` | Documentation maintenance |
434
+ | `housekeeping` | Lint, type, and test-wiring fixes |
435
+ | `github-ops` | GitHub consistency — issues, PRs, branches, labels, milestones |
436
+ | `verifier` | Verification agent — compliance test-plan design (`design` mode) and post-implementation grey-box fidelity auditing (`audit` mode) against codebase, `/workstream`, tests, and PRD/spec intent |
437
+
438
+ ---
439
+
440
+ ## Skills
441
+
442
+ On-demand capabilities loaded only when invoked.
443
+
444
+ > **Available for:** Copilot (`.github/skills/<name>/SKILL.md`), Claude Code (`.claude/skills/<name>/SKILL.md`), Kiro (`.kiro/skills/<name>/SKILL.md`). Same 13 skills on all three platforms.
445
+
446
+ | Skill | Purpose | Consumer |
447
+ | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------- |
448
+ | `activity-init` | Product context and technical guidelines | `product-engineer` |
449
+ | `activity-refine` | Issue refinement or PRD creation | `product-engineer` |
450
+ | `activity-generate-spec` | PRD → technical specification | `product-engineer` |
451
+ | `activity-generate-stories` | Spec → user stories with coverage validation | `product-engineer` |
452
+ | `activity-publish-github` | Stories → GitHub Issues | `product-engineer` |
453
+ | `activity-drift-reconciliation` | Routes `verifier` drift findings into task-list/checklist expansion, new issues, or human-confirmed PRD/spec changelog updates | `product-engineer` |
454
+ | `git-ops` | Branch, rebase, merge, conflict resolution | `developer`, `planner` |
455
+ | `webapp-mockup` | React mockup scaffold for UX testing | `ux-engineer` |
456
+ | `activity-e2e-test-design` | E2E black-box test scenario generation from spec/stories | `verifier` |
457
+ | `activity-contract-test-design` | Consumer/provider contract and schema compatibility testing | `verifier` |
458
+ | `activity-edge-case-refinement` | Systematic edge-case discovery by category with examples | `verifier` |
459
+ | `activity-random-test-tactics` | Randomized, fuzz, and property-inspired test generation | `verifier` |
460
+ | `memo-cli-usage` | Shared architectural memory with `memo-cli` (read session context, write intent/outcome and ADR/decision rationale) | `product-engineer`, `developer`, `technical-writer` |
461
+
462
+ ---
463
+
464
+ ## Instructions (Always-Loaded)
465
+
466
+ > **Available for:** Copilot (`.github/instructions/*.instructions.md`, scoped via `applyTo`), Claude Code (`plan` and `implement` are on-demand skills instead of always-loaded instructions — see `CLAUDE.md`), Kiro (`.kiro/steering/*.md`, called "steering" and scoped via `inclusion: always|fileMatch` + `fileMatchPattern`, the Kiro analogue of `applyTo`). Kiro's steering set has a 4th file, `git-guard-notice.md` (`inclusion: always`), with no equivalent on Copilot or Claude Code — it discloses a Kiro-specific hook enforcement gap.
467
+
468
+ | Instruction | Scope | Purpose |
469
+ | ------------------------------------------------ | ---------- | -------------------------------------- |
470
+ | `plan.instructions.md` | `**` | Convert stories/issues into task lists |
471
+ | `implement.instructions.md` | `**` | Execute task list with approval gates |
472
+ | `domain/nextjs-pages-components.instructions.md` | `**/*.tsx` | Next.js + React conventions |
473
+
474
+ ---
475
+
476
+ ## Prompts
477
+
478
+ > **Available for:** Copilot (`.github/prompts/*.prompt.md`), Claude Code (`.claude/commands/*.md`, invoked with `/command-name`). Kiro has no separate "prompts" concept — the 12 invocation modes below are folded directly into the corresponding `.kiro/agents/*.md` file as an "Invocation Modes" section instead of standalone files.
479
+
480
+ | Prompt | Agent | Purpose |
481
+ | -------------------------- | ---------------- | ----------------------------------------------------------------------------------------------- |
482
+ | `product-engineer-init` | product-engineer | Initialize foundation documents |
483
+ | `product-engineer-feature` | product-engineer | Design and plan a feature |
484
+ | `product-engineer-issue` | product-engineer | Refine and plan a GitHub Issue |
485
+ | `developer-execute` | developer | Execute an existing task list |
486
+ | `planner` | planner | Orchestrate multi-story execution |
487
+ | `planner-resume` | planner | Resume from checkpoint |
488
+ | `ux-engineer` | ux-engineer | Generate UX mockups |
489
+ | `github-ops` | github-ops | GitHub consistency |
490
+ | `technical-writer` | technical-writer | Documentation maintenance |
491
+ | `housekeeping` | housekeeping | Lint, type, test fixes |
492
+ | `verifier-design` | verifier | Generate compliance test plan from spec or stories (Design Mode) |
493
+ | `verifier-audit` | verifier | Grey-box fidelity audit of delivered work against spec/stories and PRD/spec intent (Audit Mode) |
494
+
495
+ ---
496
+
497
+ ## File Organization
498
+
499
+ | Directory | Contents |
500
+ | ------------------------------ | ------------------------------------------------------------------------------------------------- |
501
+ | `/docs/` | Foundation documents — product-context, technical-guidelines, ADRs |
502
+ | `/docs/requirements/` | PRDs produced by the refine skill |
503
+ | `/workstream/` | Active feature work — specs, stories, task lists, planner state files |
504
+ | `bin/` | CLI entrypoints (`dev-tasks.ts`, `dt.ts`) |
505
+ | `core/` | Business logic library (extract, distribution, reconcile) — no CLI deps |
506
+ | `adapters/cli/` | CLI adapter — wraps core, formats stdout/JSON |
507
+ | `schemas/` | JSON Schemas for validation (`component.schema.json`) |
508
+ | `test/` | Unit and integration tests + fixture repos |
509
+ | `.github/instructions/` | Always-loaded instruction files |
510
+ | `.github/instructions/domain/` | Project-specific coding standards (auto-applied) |
511
+ | `.github/agents/` | Agent definition files |
512
+ | `.github/skills/` | On-demand skill definitions |
513
+ | `.github/prompts/` | Agent invocation prompts |
514
+ | `.kiro/steering/` | Always-loaded/file-matched steering docs (Kiro's instructions equivalent; `--profile kiro`/`all`) |
515
+ | `.kiro/agents/` | Agent definition files, with invocation modes folded in (`--profile kiro`/`all`) |
516
+ | `.kiro/skills/` | On-demand skill definitions (`--profile kiro`/`all`) |
517
+ | `.kiro/hooks/` | Guard hook definition + script (`--profile kiro`/`all`) |
518
+
519
+ ---
520
+
521
+ ## Tips
522
+
523
+ - Use `step-gated` mode (default) to review each sub-task
524
+ - Use `pre-approved autonomous batch` mode when you trust the agent to run autonomously
525
+ - Use `planner-resume` when a multi-story orchestration is interrupted
526
+ - Run `housekeeping` after major feature branches to catch regressions
527
+ - Domain instructions are auto-applied based on `applyTo` patterns
528
+
529
+ ## memo-cli Integration (Optional)
530
+
531
+ When `memo-cli` is installed and configured, this workflow supports shared context across sessions, agents, and repositories.
532
+
533
+ - `product-engineer` reads context from memo at session start and before major design choices.
534
+ - `developer` writes an `intent` entry before story implementation and an `outcome` entry after completion.
535
+ - `technical-writer` writes one memo entry per ADR and per significant technical documentation change.
536
+
537
+ Recommended startup check:
538
+
539
+ ```bash
540
+ which memo && memo setup validate
541
+ ```
542
+
543
+ If `memo` is installed but validation fails, configure the repo first:
544
+
545
+ ```bash
546
+ memo setup init --repo <repo-name> --org <org-name> --domain <domain>
547
+ ```
548
+
549
+ Use `--scope related` for cross-repo context when `relates_to` is configured in `memo.config.json`.
550
+
551
+ ### Formatting
552
+
553
+ Use the repo-local formatter wrapper for tracked Markdown, JSON, and YAML files:
554
+
555
+ ```bash
556
+ ./scripts/format.sh --check
557
+ ./scripts/format.sh --write
558
+ ```
559
+
560
+ The script uses `prettier` from your `PATH` when available and falls back to `npx --yes prettier` otherwise.
561
+
562
+ ---
563
+
564
+ ## Distribution & Script Reference
565
+
566
+ The toolkit is distributed as a versioned tarball via **GitHub Releases**. `dev-tasks.sh` is the single installer/updater — no runtime beyond standard POSIX tools (`curl`, `tar`, `shasum`) is required.
567
+
568
+ ### Commands
569
+
570
+ | Command | Description |
571
+ | ---------------------------------- | -------------------------------------------------------- |
572
+ | `./dev-tasks.sh install [version]` | Install latest or a pinned version |
573
+ | `./dev-tasks.sh update [version]` | Update managed files to the latest or a specific version |
574
+ | `./dev-tasks.sh check` | Compare installed version vs latest release |
575
+ | `./dev-tasks.sh list` | List installed directories, files, and metadata |
576
+ | `./dev-tasks.sh version` | Print installed version and script version |
577
+
578
+ ### Options (install / update)
579
+
580
+ | Option | Description |
581
+ | ------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
582
+ | `--profile <name>` | Install/update file sets: `copilot` \| `claude` \| `kiro` \| `both` \| `all` (default: `both`, meaning Copilot + Claude only) |
583
+ | `--dry-run` | Print planned changes without writing any files |
584
+ | `--backup` | Copy managed files to `.dev-tasks-backup/<timestamp>/` before replacing |
585
+ | `--yes` | Skip confirmation prompts (useful in CI) |
586
+
587
+ > **Kiro guard hook — enforcement gap disclosure:** `--profile kiro`/`all` installs `.kiro/hooks/git-guard.json` + `.kiro/hooks/scripts/git-guard.sh`, a best-effort port of `.claude/hooks/git-guard.sh` that blocks pushes/merges to `main`, non-Conventional-Commit messages, and inline `--body` on `gh issue`/`pr create|edit|comment|review` (must use `--body-file`, which prevents markdown-flattening in PR/issue bodies). **This hook is not guaranteed to be equivalent to `.claude/hooks/git-guard.sh`.** A tracked upstream Kiro defect (kirodotdev/Kiro#7375) may prevent Kiro IDE's `PreToolUse` hook from seeing command text, in which case it cannot reliably block anything; when it can't see command context it fails loud (stderr warning) rather than silently allowing. Until this is verified fixed on a live Kiro install, treat PR review as the actual enforcement backstop for these rules on Kiro. See `.kiro/steering/git-guard-notice.md` for the full disclosure.
588
+
589
+ ### Managed file surface
590
+
591
+ The script owns these paths and may overwrite them on update:
592
+
593
+ | Path | Contents |
594
+ | ------------------------------------------------- | -------------------------------------------------------------------------------- |
595
+ | `.github/agents/*.agent.md` | Agent definitions |
596
+ | `.github/skills/*/SKILL.md` | Activity and operational skills |
597
+ | `.github/instructions/*.instructions.md` | Always-loaded instructions |
598
+ | `.github/instructions/domain/` | Domain-specific instructions |
599
+ | `.github/prompts/*.prompt.md` | Prompt entry points |
600
+ | `.kiro/agents/*.md` | Agent definitions (installed with `--profile kiro`/`all`) |
601
+ | `.kiro/skills/*/SKILL.md` | Activity and operational skills (installed with `--profile kiro`/`all`) |
602
+ | `.kiro/steering/*.md` | Always-loaded/file-matched steering docs (installed with `--profile kiro`/`all`) |
603
+ | `.kiro/hooks/*.json` + `.kiro/hooks/scripts/*.sh` | Guard hook definition and script (installed with `--profile kiro`/`all`) |
604
+ | `.dev-tasks-version` | Installed version metadata |
605
+
606
+ **Never touched by the script:** `AGENTS.md` — the script prints an integration prompt instead (see below).
607
+
608
+ ### AGENTS.md integration prompt
609
+
610
+ After every install or update, the script prints a `=== AGENTS.md Integration ===` block showing the diff between the bundled reference `AGENTS.md` and your local copy. It also saves the reference to `.dev-tasks-agents-update.md`. The script **never** silently overwrites your `AGENTS.md` — you decide what to merge.
611
+
612
+ ### Version pinning and rollback
613
+
614
+ ```bash
615
+ # Pin to a specific version
616
+ ./dev-tasks.sh install v0.1.3
617
+
618
+ # Update with backup so you can roll back manually
619
+ ./dev-tasks.sh update --backup
620
+
621
+ # Roll back: restore from backup
622
+ cp -r .dev-tasks-backup/<timestamp>/. ./
623
+ ```
624
+
625
+ ### Version metadata file
626
+
627
+ `.dev-tasks-version` is written after every install/update:
628
+
629
+ ```json
630
+ {
631
+ "version": "1.2.0",
632
+ "installed_at": "2026-04-20T12:00:00Z",
633
+ "script_version": "1.0.0",
634
+ "source": "https://github.com/llipe/dev-tasks"
635
+ }
636
+ ```
637
+
638
+ ### Release publishing (maintainers)
639
+
640
+ Every git tag matching `v*.*.*` triggers `.github/workflows/release-bundle.yml`, which:
641
+
642
+ 1. Runs `scripts/build-bundle.sh` to package managed files into `dev-tasks-bundle-v<version>.tar.gz`
643
+ 2. Generates a SHA256 checksum
644
+ 3. Runs a smoke test against the bundle
645
+ 4. Creates the GitHub Release and attaches the bundle + checksum as assets
646
+
647
+ #### How to create a new release
648
+
649
+ Use the release automation script:
650
+
651
+ ```bash
652
+ git checkout main
653
+ git pull origin main
654
+ ./scripts/release.sh patch # or minor / major
655
+ ```
656
+
657
+ The script:
658
+
659
+ 1. Validates pre-flight conditions (branch, clean tree, format check).
660
+ 2. Auto-generates a CHANGELOG.md entry from commit history and merged PR metadata.
661
+ 3. Suggests an increment type based on Conventional Commit analysis.
662
+ 4. Commits the changelog, creates an annotated tag, and pushes the tag.
663
+ 5. The tag push triggers `.github/workflows/release-bundle.yml` automatically.
664
+
665
+ After the workflow completes, verify the GitHub Release contains both assets:
666
+
667
+ - `dev-tasks-bundle-v<version>.tar.gz`
668
+ - `dev-tasks-bundle-v<version>.tar.gz.sha256`
669
+
670
+ Optional post-release validation:
671
+
672
+ ```bash
673
+ ./dev-tasks.sh install v1.3.0
674
+ ```
675
+
676
+ #### Option: download assets directly from the Releases page
677
+
678
+ If you prefer manual installation, download the bundle and checksum from:
679
+
680
+ - https://github.com/llipe/dev-tasks/releases
681
+
682
+ Example for a specific version:
683
+
684
+ ```bash
685
+ VERSION=v1.3.0
686
+ BASE_URL="https://github.com/llipe/dev-tasks/releases/download/${VERSION}"
687
+
688
+ curl -fL -o "dev-tasks-bundle-${VERSION}.tar.gz" \
689
+ "${BASE_URL}/dev-tasks-bundle-${VERSION}.tar.gz"
690
+ curl -fL -o "dev-tasks-bundle-${VERSION}.tar.gz.sha256" \
691
+ "${BASE_URL}/dev-tasks-bundle-${VERSION}.tar.gz.sha256"
692
+
693
+ # Verify checksum
694
+ shasum -a 256 -c "dev-tasks-bundle-${VERSION}.tar.gz.sha256"
695
+
696
+ # Extract
697
+ tar -xzf "dev-tasks-bundle-${VERSION}.tar.gz"
698
+ ```
699
+
700
+ ---
701
+
702
+ ## `dt` — Multi-Repo Context CLI
703
+
704
+ `dt` is the runtime binary for the `@llipe/dev-tasks` npm package. It extracts repository metadata (schema, OpenAPI, AsyncAPI), derives a `component.yaml` manifest with provenance and confidence tracking, and (in later phases) builds a cross-repo catalog and resolves scoped context bundles for agent sessions.
705
+
706
+ ### Installation
707
+
708
+ ```bash
709
+ # Install globally (or as a dev dependency)
710
+ pnpm add -g @llipe/dev-tasks
711
+
712
+ # Verify
713
+ dt --version
714
+ dev-tasks --version
715
+ ```
716
+
717
+ Two binaries are provided:
718
+
719
+ | Binary | Purpose |
720
+ | ----------- | --------------------------------------------------- |
721
+ | `dev-tasks` | Bootstrap: install, update, status, pin, doctor |
722
+ | `dt` | Runtime: extract, catalog, ctx, scope, init, verify |
723
+
724
+ ### Commands
725
+
726
+ #### `dt extract` — Repository metadata extraction
727
+
728
+ ```bash
729
+ # Detect stack, framework, ORM, and messaging with evidence
730
+ dt extract detect
731
+
732
+ # Extract database schema from ORM definitions (Prisma, Drizzle, TypeORM)
733
+ dt extract schema [--db-url <url>]
734
+
735
+ # Extract OpenAPI spec (route 1: copy existing, route 3: AST inference)
736
+ dt extract openapi [--strategy auto|1|3]
737
+
738
+ # Extract AsyncAPI spec from Kafka topic patterns (kafkajs)
739
+ dt extract asyncapi
740
+
741
+ # Derive component.yaml with provenance and confidence
742
+ dt extract component [--interactive]
743
+
744
+ # Run full extraction pipeline (detect → schema → openapi → asyncapi → component → report)
745
+ dt extract all [--interactive] [--force]
746
+ ```
747
+
748
+ #### `dev-tasks` — Bootstrap and distribution
749
+
750
+ ```bash
751
+ dev-tasks install [--pin <version>] # Install skill files + write manifest
752
+ dev-tasks update [--force] # Reconcile with hash-based conflict detection
753
+ dev-tasks status # Compare installed/pinned/latest versions
754
+ dev-tasks pin <version> # Pin to a specific version
755
+ dev-tasks doctor # Check Node ≥20, git ≥2.37, cache writable
756
+ dev-tasks migrate # Migrate from legacy dev-tasks.sh
757
+ ```
758
+
759
+ ### Global options
760
+
761
+ All commands accept:
762
+
763
+ | Flag | Description |
764
+ | -------------------- | ---------------------------- |
765
+ | `--json` | Machine-readable JSON output |
766
+ | `--meta-repo <path>` | Path or URL to the meta-repo |
767
+ | `-v` | Verbose diagnostics (stderr) |
768
+
769
+ ### Exit codes
770
+
771
+ | Code | Meaning |
772
+ | ---- | ------------------------------------------------- |
773
+ | 0 | OK |
774
+ | 1 | Unexpected error |
775
+ | 2 | Incorrect usage |
776
+ | 13 | Incomplete extraction: required fields unresolved |
777
+ | 14 | Reconciliation conflict (edited fields) |
778
+
779
+ ### Typical workflow
780
+
781
+ ```bash
782
+ # 1. Run extraction in a component repo
783
+ cd my-service
784
+ dt extract all --interactive
785
+
786
+ # 2. Review outputs
787
+ cat component.yaml # manifest with _provenance
788
+ cat extraction_report.json # coverage, confidence, unresolved items
789
+
790
+ # 3. Validate
791
+ dt validate-component # (Phase 2+) checks against JSON Schema
792
+
793
+ # 4. Commit and push
794
+ git add component.yaml contracts/ docs/schema.md extraction_report.json
795
+ git commit -m "feat: add component manifest via dt extract"
796
+ ```
797
+
798
+ ### Current implementation status
799
+
800
+ Phase 0 (distribution) and Phase 1 (extraction) are implemented. The following are available:
801
+
802
+ - `dev-tasks install|update|status|pin|doctor|migrate`
803
+ - `dt extract detect|schema|openapi|asyncapi|component|all`
804
+ - Hash-based reconciliation with conflict detection
805
+ - Legacy shell-script migration shim
806
+
807
+ Phases 2-5 (catalog, context, scoping, product-engineer integration) are specified but not yet implemented.
808
+
809
+ ---
810
+
811
+ ## Known Limitations
812
+
813
+ - **Route 2 (isolated framework boot) is interface-only** — the hook exists but is not implemented; only routes 1 and 3 are functional for OpenAPI extraction.
814
+ - **LLM inference is stubbed** — no real LLM provider is wired yet; description passes produce placeholder output.
815
+ - **Only Node/TS provider** — other language stacks (Python, Go, Java, etc.) require additional extraction providers.
816
+ - **Zod extraction handles basic `z.object` patterns only** — complex Zod compositions (unions, intersections, lazy schemas) are not fully supported.
817
+ - **Only kafkajs Kafka patterns supported** — other messaging clients (confluent-kafka, rhea/AMQP, bullmq) are not detected.
818
+
819
+ ---
820
+
821
+ ## Attribution
822
+
823
+ Original idea based on [snarktank/ai-dev-tasks](https://github.com/snarktank/ai-dev-tasks)