@llipe.com/dev-tasks 0.6.5 → 0.6.7

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/CHANGELOG.md CHANGED
@@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/).
7
7
 
8
+ ## [0.6.7] - 2026-07-31
9
+
10
+ ### Changed
11
+
12
+ - docs(readme): simplify installation and setup instructions
13
+
14
+ ## [0.6.6] - 2026-07-30
15
+
16
+ ### Fixed
17
+
18
+ - fix(cli): support --flag=value syntax for all value-bearing flags The parser only matched exact '--profile' followed by a separate argument. Passing '--profile=kiro' was treated as an unknown flag and the profile defaulted to 'both'. Now all value flags (--profile, --pin, --meta-repo, --db-url, --strategy) correctly handle both '--flag value' and '--flag=value' syntax.
19
+
20
+ ### Changed
21
+
22
+ - Merge pull request #95 from llipe:fix/91-profile-equals-syntax
23
+
8
24
  ## [0.6.5] - 2026-07-30
9
25
 
10
26
  ### Added
package/README.md CHANGED
@@ -2,390 +2,174 @@
2
2
 
3
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
4
 
5
- ## Quick Start
6
-
7
- ### Agent workflow (skills + instructions)
5
+ ---
8
6
 
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
- ```
7
+ ## Getting Started
32
8
 
33
- ### `dt` CLI (multi-repo context)
9
+ ### 1. Install the package
34
10
 
35
11
  ```bash
36
- # 1. Install the npm package
37
12
  pnpm add -g @llipe.com/dev-tasks
38
-
39
- # 2. Extract your repo's metadata
40
- dt extract all --interactive
41
-
42
- # 3. Review the generated component.json and extraction_report.json
43
- cat component.json
44
- cat extraction_report.json
45
-
46
- # 4. Keep distribution up to date with hash-based reconciliation
47
- dev-tasks update
48
13
  ```
49
14
 
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
15
+ This gives you two binaries:
93
16
 
94
- - macOS / Linux (or WSL on Windows)
95
- - `git`
96
- - `curl`
97
- - `tar`
98
- - `shasum` (or `sha256sum`)
17
+ | Binary | Purpose |
18
+ | ----------- | ------------------------------------------------------- |
19
+ | `dev-tasks` | Bootstrap: install agent files, update, status, migrate |
20
+ | `dt` | Runtime: extract repo metadata, build context |
99
21
 
100
- ### Option A: Install `dev-tasks` into any repository (recommended)
101
-
102
- Run this in the repository where you want to use the workflow:
22
+ ### 2. Install agent workflow files into your repo
103
23
 
104
24
  ```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
25
+ cd your-project
26
+ dev-tasks install
108
27
  ```
109
28
 
110
- ### Option B: Set up this repository locally (contributors)
29
+ This installs agent definitions, skills, instructions, and prompts into your project for the AI platforms you use. By default it installs for Copilot + Claude Code (`--profile both`).
30
+
31
+ **Choose your platform profile:**
111
32
 
112
33
  ```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
34
+ dev-tasks install --profile copilot # .github/ only
35
+ dev-tasks install --profile claude # .claude/ only
36
+ dev-tasks install --profile kiro # .kiro/ only
37
+ dev-tasks install --profile all # all platforms
118
38
  ```
119
39
 
120
- ### Verify the installation
40
+ ### 3. Initialize your project context
121
41
 
122
- After install, confirm these paths exist in your target repo:
42
+ Invoke the `product-engineer` agent in Init Mode (via `@product-engineer` or the `product-engineer-init` prompt). This creates:
123
43
 
124
- - `.github/agents/`
125
- - `.github/skills/`
126
- - `.github/instructions/`
127
- - `.github/prompts/`
128
- - `.dev-tasks-version`
44
+ - `docs/product-context.md` — what your product is and who it's for
45
+ - `docs/technical-guidelines.md` — stack, conventions, and constraints
129
46
 
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:
47
+ Run this once per project.
131
48
 
132
- - `.kiro/agents/`
133
- - `.kiro/skills/`
134
- - `.kiro/steering/`
135
- - `.kiro/hooks/`
49
+ ### 4. Build a feature
136
50
 
137
- ---
138
-
139
- ## Getting Started
51
+ ```text
52
+ a) Invoke @product-engineer with a feature description or GitHub issue number
53
+ → creates PRD → spec → stories → task list
140
54
 
141
- ### 1. Install with the single-script installer
55
+ b) Invoke @developer with the task list path
56
+ → implements, tests, and opens a PR
57
+ ```
142
58
 
143
- Bootstrap from any repository with one command:
59
+ ### 5. Keep files up to date
144
60
 
145
61
  ```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
62
+ dev-tasks update # reconcile with hash-based conflict detection
63
+ dev-tasks update --force # accept all upstream changes
64
+ dev-tasks status # compare installed vs latest version
149
65
  ```
150
66
 
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.
67
+ ---
152
68
 
153
- **Pin to a specific version:**
69
+ ## Using `dt` for Multi-Repo Context
154
70
 
155
- ```bash
156
- ./dev-tasks.sh install v1.2.0
157
- ```
71
+ `dt` extracts repository metadata (schema, OpenAPI, AsyncAPI), derives a `component.json` manifest with provenance and confidence tracking, and builds cross-repo context for agent sessions.
158
72
 
159
- **Check for updates:**
73
+ ### Extract metadata from a repo
160
74
 
161
75
  ```bash
162
- ./dev-tasks.sh check
163
- ```
76
+ cd my-service
164
77
 
165
- **List installed files and directories:**
78
+ # Run the full extraction pipeline
79
+ dt extract all --interactive
166
80
 
167
- ```bash
168
- ./dev-tasks.sh list
81
+ # Or run individual extractors
82
+ dt extract detect # stack, framework, ORM, messaging
83
+ dt extract schema # database schema from ORM definitions
84
+ dt extract openapi # OpenAPI spec (copy existing or AST inference)
85
+ dt extract asyncapi # AsyncAPI spec from Kafka topic patterns
86
+ dt extract component # derive component.json manifest
169
87
  ```
170
88
 
171
- **Update (with automatic backup):**
89
+ ### Review outputs
172
90
 
173
91
  ```bash
174
- ./dev-tasks.sh update --backup
92
+ cat component.json # manifest with _provenance metadata
93
+ cat extraction_report.json # coverage, confidence, unresolved items
175
94
  ```
176
95
 
177
- **Preview what would change without writing any files:**
96
+ ### Typical workflow
178
97
 
179
98
  ```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
99
+ dt extract all --interactive
100
+ git add component.json contracts/ docs/schema.md extraction_report.json
101
+ git commit -m "feat: add component manifest via dt extract"
220
102
  ```
221
103
 
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) |
104
+ ### Global options
242
105
 
243
- ### 4. (Optional) Add domain-specific instructions
106
+ | Flag | Description |
107
+ | -------------------- | ---------------------------- |
108
+ | `--json` | Machine-readable JSON output |
109
+ | `--meta-repo <path>` | Path or URL to the meta-repo |
110
+ | `-v` | Verbose diagnostics (stderr) |
244
111
 
245
- Create technology-specific instruction files scoped to certain file patterns via `applyTo` frontmatter:
112
+ ### Exit codes
246
113
 
247
- ```yaml
248
- ---
249
- applyTo: "apps/my-app/src/**/*.tsx"
250
- ---
251
- # Your project-specific component conventions here
252
- ```
114
+ | Code | Meaning |
115
+ | ---- | ------------------------------------------------- |
116
+ | 0 | OK |
117
+ | 1 | Unexpected error |
118
+ | 2 | Incorrect usage |
119
+ | 13 | Incomplete extraction: required fields unresolved |
120
+ | 14 | Reconciliation conflict (edited fields) |
253
121
 
254
122
  ---
255
123
 
256
- ## Workflow Chains
124
+ ## `dev-tasks` Command Reference
257
125
 
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
126
+ ```bash
127
+ dev-tasks install [--pin <version>] # Install skill files + write manifest
128
+ dev-tasks update [--force] # Reconcile with hash-based conflict detection
129
+ dev-tasks status # Compare installed/pinned/latest versions
130
+ dev-tasks pin <version> # Pin to a specific version
131
+ dev-tasks doctor # Check Node ≥20, git ≥2.37, cache writable
132
+ dev-tasks migrate # Migrate from legacy shell-script install
331
133
  ```
332
134
 
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
- ```
135
+ ### Options (install / update)
347
136
 
348
- ### Single GitHub Issue
137
+ | Option | Description |
138
+ | ------------------ | ---------------------------------------------------- |
139
+ | `--profile <name>` | `copilot` \| `claude` \| `kiro` \| `both` \| `all` |
140
+ | `--dry-run` | Print planned changes without writing any files |
141
+ | `--backup` | Backup managed files before replacing |
142
+ | `--yes` | Skip confirmation prompts (useful in CI) |
143
+ | `--pin <version>` | Pin to a specific release version |
144
+ | `--force` | Accept all upstream changes without conflict prompts |
349
145
 
350
- ```
351
- product-engineer: refine → plan
352
- ↓
353
- developer: implement
354
- ```
146
+ ---
355
147
 
356
- ### Multi-Story Orchestration
148
+ ## The Core Idea
357
149
 
358
- ```
359
- product-engineer: ... → plan
360
- ↓
361
- planner: orchestrate → developer: implement (per story, sequential)
362
- ```
150
+ This system brings structure and clarity to AI-assisted development by:
363
151
 
364
- ### Quick Fix
152
+ - Defining scope with Product Requirements Documents (PRDs)
153
+ - Breaking requirements into actionable, implementation-ready tasks
154
+ - Guiding the AI to tackle one task at a time with checkpoints for review
155
+ - Providing specialized **agents** that orchestrate the workflow end-to-end
156
+ - Enforcing documentation, branch discipline, and GitHub-as-source-of-truth
365
157
 
366
- ```
367
- developer: implement
368
- ```
158
+ ---
369
159
 
370
- ### UX Validation Loop
160
+ ## Taxonomy: Agent vs Skill vs Instruction
371
161
 
372
- ```
373
- product-engineer: refine → generate-spec → ux-engineer: mockups → product-engineer: update
374
- ```
162
+ | Concept | Purpose | Loaded When |
163
+ | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------- |
164
+ | **Agent** | Autonomous role with decision-making, phases, and handoff discipline. Owns a workflow end-to-end. | Invoked by name (`@agent`) |
165
+ | **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) |
166
+ | **Instruction** | Always-loaded rule scoped via `applyTo` frontmatter. Enforced automatically for every matching context. | Always (auto-applied by runtime) |
375
167
 
376
- ### Test-First Design (Verifier)
168
+ **Key distinctions:**
377
169
 
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
- ```
170
+ - Skills save context window space — they are loaded only when invoked, unlike instructions which are always present.
171
+ - Agent files define _who_ (identity, phases, handoff rules). Skill files define _how_ (procedures, templates, steps).
172
+ - Instructions are for cross-cutting rules that must never be forgotten (e.g., implementation discipline, planning format).
389
173
 
390
174
  ---
391
175
 
@@ -393,7 +177,7 @@ developer/planner: implement (feature + tests from test plan)
393
177
 
394
178
  Agents are autonomous personas that orchestrate skills and activities.
395
179
 
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)).
180
+ > **Available for:** Copilot (`.github/agents/`), Claude Code (`.claude/agents/`), Kiro (`.kiro/agents/`). All three platforms define the same 8 agents below.
397
181
 
398
182
  ### `product-engineer`
399
183
 
@@ -403,37 +187,35 @@ Preparation agent — owns the full pre-coding chain:
403
187
  - **Feature Mode**: `activity-refine` → `activity-generate-spec` → `activity-generate-stories` → `activity-publish-github` → `plan`
404
188
  - **Issue Mode**: `activity-refine` → `plan`
405
189
 
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.
190
+ Also owns drift reconciliation via `activity-drift-reconciliation`.
409
191
 
410
192
  ### `developer`
411
193
 
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.
194
+ Execution agent — implements code from an existing task list. Runs `implement`, including a mandatory `verifier` audit before every PR is marked ready. Uses `git-ops` for branch management.
413
195
 
414
196
  ### `planner`
415
197
 
416
198
  Multi-story orchestration with checkpoint/resume:
417
199
 
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** |
200
+ | Phase | What Happens |
201
+ | ----- | ----------------------------------------------------------------- |
202
+ | 0 | Discover task source |
203
+ | 0.5 | Resume detection |
204
+ | 1 | Parse stories and infer dependencies |
205
+ | 2 | Dependency graph — user approval required |
206
+ | 3 | Pre-flight — creates integration branch |
207
+ | 4 | Delegate to `developer` per story; merge and write checkpoint |
208
+ | 5 | PRD-level rollup `verifier` audit, then consolidated PR to `main` |
427
209
 
428
210
  ### Other Agents
429
211
 
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 |
212
+ | Agent | Purpose |
213
+ | ------------------ | -------------------------------------------------- |
214
+ | `ux-engineer` | PRD/SPEC-to-mockup prototyping |
215
+ | `technical-writer` | Documentation maintenance |
216
+ | `housekeeping` | Lint, type, and test-wiring fixes |
217
+ | `github-ops` | GitHub consistency — issues, PRs, branches, labels |
218
+ | `verifier` | Compliance test-plan design and fidelity auditing |
437
219
 
438
220
  ---
439
221
 
@@ -441,30 +223,26 @@ Multi-story orchestration with checkpoint/resume:
441
223
 
442
224
  On-demand capabilities loaded only when invoked.
443
225
 
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` |
226
+ | Skill | Purpose | Consumer |
227
+ | ------------------------------- | ----------------------------------------------- | --------------------------------------------------- |
228
+ | `activity-init` | Product context and technical guidelines | `product-engineer` |
229
+ | `activity-refine` | Issue refinement or PRD creation | `product-engineer` |
230
+ | `activity-generate-spec` | PRD → technical specification | `product-engineer` |
231
+ | `activity-generate-stories` | Spec → user stories with coverage validation | `product-engineer` |
232
+ | `activity-publish-github` | Stories → GitHub Issues | `product-engineer` |
233
+ | `activity-drift-reconciliation` | Routes verifier drift findings into remediation | `product-engineer` |
234
+ | `git-ops` | Branch, rebase, merge, conflict resolution | `developer`, `planner` |
235
+ | `webapp-mockup` | React mockup scaffold for UX testing | `ux-engineer` |
236
+ | `activity-e2e-test-design` | E2E black-box test scenario generation | `verifier` |
237
+ | `activity-contract-test-design` | Consumer/provider contract testing | `verifier` |
238
+ | `activity-edge-case-refinement` | Systematic edge-case discovery | `verifier` |
239
+ | `activity-random-test-tactics` | Randomized, fuzz, and property-inspired tests | `verifier` |
240
+ | `memo-cli-usage` | Shared architectural memory across sessions | `product-engineer`, `developer`, `technical-writer` |
461
241
 
462
242
  ---
463
243
 
464
244
  ## Instructions (Always-Loaded)
465
245
 
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
246
  | Instruction | Scope | Purpose |
469
247
  | ------------------------------------------------ | ---------- | -------------------------------------- |
470
248
  | `plan.instructions.md` | `**` | Convert stories/issues into task lists |
@@ -475,361 +253,211 @@ On-demand capabilities loaded only when invoked.
475
253
 
476
254
  ## Prompts
477
255
 
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`) |
256
+ > Copilot: `.github/prompts/*.prompt.md`. Claude Code: `.claude/commands/*.md`. Kiro: embedded in `.kiro/agents/*.md`.
257
+
258
+ | Prompt | Agent | Purpose |
259
+ | -------------------------- | ---------------- | --------------------------------- |
260
+ | `product-engineer-init` | product-engineer | Initialize foundation documents |
261
+ | `product-engineer-feature` | product-engineer | Design and plan a feature |
262
+ | `product-engineer-issue` | product-engineer | Refine and plan a GitHub Issue |
263
+ | `developer-execute` | developer | Execute an existing task list |
264
+ | `planner` | planner | Orchestrate multi-story execution |
265
+ | `planner-resume` | planner | Resume from checkpoint |
266
+ | `ux-engineer` | ux-engineer | Generate UX mockups |
267
+ | `github-ops` | github-ops | GitHub consistency |
268
+ | `technical-writer` | technical-writer | Documentation maintenance |
269
+ | `housekeeping` | housekeeping | Lint, type, test fixes |
270
+ | `verifier-design` | verifier | Generate compliance test plan |
271
+ | `verifier-audit` | verifier | Grey-box fidelity audit |
518
272
 
519
273
  ---
520
274
 
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
275
+ ## Workflow Chains
528
276
 
529
- ## memo-cli Integration (Optional)
277
+ Match your situation to a chain below, then invoke the first agent in the chain.
530
278
 
531
- When `memo-cli` is installed and configured, this workflow supports shared context across sessions, agents, and repositories.
279
+ ### Full Feature (PRD-Driven)
532
280
 
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.
281
+ ```
282
+ product-engineer: refine → generate-spec → generate-stories → publish-github → plan
283
+ ↓
284
+ developer: implement
285
+ ```
536
286
 
537
- Recommended startup check:
287
+ ### Single GitHub Issue
538
288
 
539
- ```bash
540
- which memo && memo setup validate
289
+ ```
290
+ product-engineer: refine → plan
291
+ ↓
292
+ developer: implement
541
293
  ```
542
294
 
543
- If `memo` is installed but validation fails, configure the repo first:
295
+ ### Multi-Story Orchestration
544
296
 
545
- ```bash
546
- memo setup init --repo <repo-name> --org <org-name> --domain <domain>
297
+ ```
298
+ product-engineer: ... → plan
299
+ ↓
300
+ planner: orchestrate → developer: implement (per story, sequential)
547
301
  ```
548
302
 
549
- Use `--scope related` for cross-repo context when `relates_to` is configured in `memo.config.json`.
303
+ ### Quick Fix
550
304
 
551
- ### Formatting
305
+ ```
306
+ developer: implement
307
+ ```
552
308
 
553
- Use the repo-local formatter wrapper for tracked Markdown, JSON, and YAML files:
309
+ ### Test-First Design (Verifier)
554
310
 
555
- ```bash
556
- ./scripts/format.sh --check
557
- ./scripts/format.sh --write
558
311
  ```
559
-
560
- The script uses `prettier` from your `PATH` when available and falls back to `npx --yes prettier` otherwise.
312
+ product-engineer: spec → stories → plan
313
+ ↓
314
+ verifier (design mode): generate test plan
315
+ ↓
316
+ developer: implement (tests first, then code)
317
+ ↓ (mandatory)
318
+ verifier (audit mode): fidelity audit → report
319
+ ↓ (drift findings, non-blocking)
320
+ product-engineer: drift-reconciliation
321
+ ```
561
322
 
562
323
  ---
563
324
 
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 |
325
+ ## File Organization
605
326
 
606
- **Never touched by the script:** `AGENTS.md` — the script prints an integration prompt instead (see below).
327
+ | Directory | Contents |
328
+ | --------------------- | ------------------------------------------------------- |
329
+ | `/docs/` | Foundation docs — product-context, technical-guidelines |
330
+ | `/docs/requirements/` | PRDs produced by the refine skill |
331
+ | `/workstream/` | Active feature work — specs, stories, task lists |
332
+ | `bin/` | CLI entrypoints (`dev-tasks.ts`, `dt.ts`) |
333
+ | `core/` | Business logic library (extract, distribution) |
334
+ | `adapters/cli/` | CLI adapter — wraps core, formats stdout/JSON |
335
+ | `schemas/` | JSON Schemas for validation |
336
+ | `test/` | Unit and integration tests + fixtures |
337
+ | `.github/` | Copilot agents, skills, instructions, prompts |
338
+ | `.kiro/` | Kiro agents, skills, steering, hooks |
607
339
 
608
- ### AGENTS.md integration prompt
340
+ ---
609
341
 
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.
342
+ ## memo-cli Integration (Optional)
611
343
 
612
- ### Version pinning and rollback
344
+ When `memo-cli` is installed and configured, agents share context across sessions and repositories.
613
345
 
614
346
  ```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>/. ./
347
+ which memo && memo setup validate
623
348
  ```
624
349
 
625
- ### Version metadata file
626
-
627
- `.dev-tasks-version` is written after every install/update:
350
+ If `memo` is installed but validation fails:
628
351
 
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
- }
352
+ ```bash
353
+ memo setup init --repo <repo-name> --org <org-name> --domain <domain>
636
354
  ```
637
355
 
638
- ### Release publishing (maintainers)
356
+ ---
639
357
 
640
- Every git tag matching `v*.*.*` triggers two workflows:
358
+ ## Known Limitations
641
359
 
642
- - `.github/workflows/release-bundle.yml` — builds the tarball bundle and creates a GitHub Release
643
- - `.github/workflows/publish-npm.yml` — publishes the `@llipe.com/dev-tasks` npm package
360
+ - **Route 2 (isolated framework boot) is interface-only** — only routes 1 and 3 are functional for OpenAPI extraction.
361
+ - **LLM inference is stubbed** — no real LLM provider is wired yet.
362
+ - **Only Node/TS provider** — other language stacks require additional extraction providers.
363
+ - **Zod extraction handles basic `z.object` patterns only** — complex compositions are not fully supported.
364
+ - **Only kafkajs patterns supported** — other messaging clients are not detected.
644
365
 
645
- #### How to create a new release
366
+ ---
646
367
 
647
- Use the release automation script:
368
+ ## Tips
648
369
 
649
- ```bash
650
- git checkout main
651
- git pull origin main
652
- ./scripts/release.sh patch # or minor / major
653
- ```
370
+ - Use `step-gated` mode (default) to review each sub-task
371
+ - Use `pre-approved autonomous batch` mode when you trust the agent to run autonomously
372
+ - Use `planner-resume` when a multi-story orchestration is interrupted
373
+ - Run `housekeeping` after major feature branches to catch regressions
374
+ - Domain instructions are auto-applied based on `applyTo` patterns
654
375
 
655
- The script:
376
+ ---
656
377
 
657
- 1. Validates pre-flight conditions (branch, clean tree, format check).
658
- 2. Auto-generates a CHANGELOG.md entry from commit history and merged PR metadata.
659
- 3. Suggests an increment type based on Conventional Commit analysis.
660
- 4. Updates `package.json` version to the new semver value.
661
- 5. Commits both CHANGELOG.md and package.json (`chore(release): v<version>`).
662
- 6. Creates an annotated git tag.
663
- 7. Pushes the commit to `main` and the tag to `origin`.
664
- 8. The tag push triggers both CI workflows automatically.
378
+ ## Contributing
665
379
 
666
- After the workflows complete, verify:
380
+ ### Prerequisites
667
381
 
668
- - GitHub Release contains `dev-tasks-bundle-v<version>.tar.gz` + `.sha256`
669
- - npm package is published: `npm view @llipe.com/dev-tasks version`
382
+ - Node.js >= 20
383
+ - pnpm (via `corepack enable`)
384
+ - git >= 2.37
670
385
 
671
- Optional post-release validation:
386
+ ### Setup
672
387
 
673
388
  ```bash
674
- ./dev-tasks.sh install v1.3.0
389
+ git clone https://github.com/llipe/dev-tasks.git
390
+ cd dev-tasks
391
+ pnpm install
675
392
  ```
676
393
 
677
- #### CI setup required
678
-
679
- The npm publish workflow uses **Trusted Publishers (OIDC)** — no npm token secret is needed. Configure once on npmjs.com:
680
-
681
- 1. Go to npmjs.com → Packages → `@llipe.com/dev-tasks` → Settings → Trusted Publisher
682
- 2. Select **GitHub Actions** and fill in:
683
- - Organization or user: `llipe`
684
- - Repository: `dev-tasks`
685
- - Workflow filename: `publish-npm.yml`
686
- - Environment name: `npm`
687
- - Allowed actions: npm publish
688
-
689
- Also create a GitHub environment named `npm` in the repo (Settings → Environments → New environment → `npm`). No secrets needed.
690
-
691
- #### Option: download assets directly from the Releases page
692
-
693
- If you prefer manual installation, download the bundle and checksum from:
694
-
695
- - https://github.com/llipe/dev-tasks/releases
696
-
697
- Example for a specific version:
394
+ ### Build
698
395
 
699
396
  ```bash
700
- VERSION=v1.3.0
701
- BASE_URL="https://github.com/llipe/dev-tasks/releases/download/${VERSION}"
702
-
703
- curl -fL -o "dev-tasks-bundle-${VERSION}.tar.gz" \
704
- "${BASE_URL}/dev-tasks-bundle-${VERSION}.tar.gz"
705
- curl -fL -o "dev-tasks-bundle-${VERSION}.tar.gz.sha256" \
706
- "${BASE_URL}/dev-tasks-bundle-${VERSION}.tar.gz.sha256"
707
-
708
- # Verify checksum
709
- shasum -a 256 -c "dev-tasks-bundle-${VERSION}.tar.gz.sha256"
710
-
711
- # Extract
712
- tar -xzf "dev-tasks-bundle-${VERSION}.tar.gz"
397
+ pnpm run build # compile TypeScript to dist/
398
+ pnpm run typecheck # type-check without emitting
713
399
  ```
714
400
 
715
- ---
716
-
717
- ## `dt` — Multi-Repo Context CLI
718
-
719
- `dt` is the runtime binary for the `@llipe.com/dev-tasks` npm package. It extracts repository metadata (schema, OpenAPI, AsyncAPI), derives a `component.json` manifest with provenance and confidence tracking, and (in later phases) builds a cross-repo catalog and resolves scoped context bundles for agent sessions.
720
-
721
- ### Installation
401
+ ### Test
722
402
 
723
403
  ```bash
724
- # Install globally (or as a dev dependency)
725
- pnpm add -g @llipe.com/dev-tasks
726
-
727
- # Verify
728
- dt --version
729
- dev-tasks --version
404
+ pnpm run test # all tests (vitest)
405
+ pnpm run test:unit # unit tests only
406
+ pnpm run test:integration # integration tests only
730
407
  ```
731
408
 
732
- Two binaries are provided:
733
-
734
- | Binary | Purpose |
735
- | ----------- | --------------------------------------------------- |
736
- | `dev-tasks` | Bootstrap: install, update, status, pin, doctor |
737
- | `dt` | Runtime: extract, catalog, ctx, scope, init, verify |
738
-
739
- ### Commands
740
-
741
- #### `dt extract` — Repository metadata extraction
409
+ ### Lint and Format
742
410
 
743
411
  ```bash
744
- # Detect stack, framework, ORM, and messaging with evidence
745
- dt extract detect
746
-
747
- # Extract database schema from ORM definitions (Prisma, Drizzle, TypeORM)
748
- dt extract schema [--db-url <url>]
749
-
750
- # Extract OpenAPI spec (route 1: copy existing, route 3: AST inference)
751
- dt extract openapi [--strategy auto|1|3]
752
-
753
- # Extract AsyncAPI spec from Kafka topic patterns (kafkajs)
754
- dt extract asyncapi
755
-
756
- # Derive component.json with provenance and confidence
757
- dt extract component [--interactive]
758
-
759
- # Run full extraction pipeline (detect → schema → openapi → asyncapi → component → report)
760
- dt extract all [--interactive] [--force]
412
+ pnpm run lint # ESLint (zero warnings)
413
+ pnpm run lint:fix # auto-fix lint issues
414
+ pnpm run format:check # Prettier check
415
+ pnpm run format # Prettier write
761
416
  ```
762
417
 
763
- #### `dev-tasks` — Bootstrap and distribution
418
+ ### Full validation (CI equivalent)
764
419
 
765
420
  ```bash
766
- dev-tasks install [--pin <version>] # Install skill files + write manifest
767
- dev-tasks update [--force] # Reconcile with hash-based conflict detection
768
- dev-tasks status # Compare installed/pinned/latest versions
769
- dev-tasks pin <version> # Pin to a specific version
770
- dev-tasks doctor # Check Node ≥20, git ≥2.37, cache writable
771
- dev-tasks migrate # Migrate from legacy dev-tasks.sh
421
+ pnpm run validate # typecheck + lint + format:check + test
772
422
  ```
773
423
 
774
- ### Global options
775
-
776
- All commands accept:
777
-
778
- | Flag | Description |
779
- | -------------------- | ---------------------------- |
780
- | `--json` | Machine-readable JSON output |
781
- | `--meta-repo <path>` | Path or URL to the meta-repo |
782
- | `-v` | Verbose diagnostics (stderr) |
783
-
784
- ### Exit codes
424
+ ### Releasing a new version
785
425
 
786
- | Code | Meaning |
787
- | ---- | ------------------------------------------------- |
788
- | 0 | OK |
789
- | 1 | Unexpected error |
790
- | 2 | Incorrect usage |
791
- | 13 | Incomplete extraction: required fields unresolved |
792
- | 14 | Reconciliation conflict (edited fields) |
793
-
794
- ### Typical workflow
426
+ Releases are automated via git tags. Use the release script:
795
427
 
796
428
  ```bash
797
- # 1. Run extraction in a component repo
798
- cd my-service
799
- dt extract all --interactive
800
-
801
- # 2. Review outputs
802
- cat component.json # manifest with _provenance
803
- cat extraction_report.json # coverage, confidence, unresolved items
804
-
805
- # 3. Validate
806
- dt validate-component # (Phase 2+) checks against JSON Schema
807
-
808
- # 4. Commit and push
809
- git add component.json contracts/ docs/schema.md extraction_report.json
810
- git commit -m "feat: add component manifest via dt extract"
429
+ git checkout main
430
+ git pull origin main
431
+ ./scripts/release.sh patch # or: minor / major
811
432
  ```
812
433
 
813
- ### Current implementation status
434
+ The script:
814
435
 
815
- Phase 0 (distribution) and Phase 1 (extraction) are implemented. The following are available:
436
+ 1. Validates pre-flight conditions (branch, clean tree, format check).
437
+ 2. Auto-generates a CHANGELOG entry from commit history.
438
+ 3. Updates `package.json` version.
439
+ 4. Commits (`chore(release): v<version>`), creates an annotated tag, and pushes.
440
+ 5. The tag push triggers CI workflows:
441
+ - `.github/workflows/release-bundle.yml` — builds the tarball and creates a GitHub Release
442
+ - `.github/workflows/publish-npm.yml` — publishes to npm as `@llipe.com/dev-tasks`
816
443
 
817
- - `dev-tasks install|update|status|pin|doctor|migrate`
818
- - `dt extract detect|schema|openapi|asyncapi|component|all`
819
- - Hash-based reconciliation with conflict detection
820
- - Legacy shell-script migration shim
444
+ After the workflows complete, verify:
821
445
 
822
- Phases 2-5 (catalog, context, scoping, product-engineer integration) are specified but not yet implemented.
446
+ ```bash
447
+ npm view @llipe.com/dev-tasks version
448
+ ```
823
449
 
824
- ---
450
+ ### CI setup (npm Trusted Publishers)
825
451
 
826
- ## Known Limitations
452
+ The npm publish workflow uses OIDC — no npm token secret needed. Configure once on npmjs.com:
827
453
 
828
- - **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.
829
- - **LLM inference is stubbed** — no real LLM provider is wired yet; description passes produce placeholder output.
830
- - **Only Node/TS provider** — other language stacks (Python, Go, Java, etc.) require additional extraction providers.
831
- - **Zod extraction handles basic `z.object` patterns only** — complex Zod compositions (unions, intersections, lazy schemas) are not fully supported.
832
- - **Only kafkajs Kafka patterns supported** — other messaging clients (confluent-kafka, rhea/AMQP, bullmq) are not detected.
454
+ 1. Go to npmjs.com → `@llipe.com/dev-tasks` → Settings → Trusted Publisher
455
+ 2. Select GitHub Actions:
456
+ - Organization/user: `llipe`
457
+ - Repository: `dev-tasks`
458
+ - Workflow: `publish-npm.yml`
459
+ - Environment: `npm`
460
+ 3. Create a GitHub environment named `npm` in the repo (Settings → Environments)
833
461
 
834
462
  ---
835
463
 
@@ -1 +1 @@
1
- {"version":3,"file":"parse-args.d.ts","sourceRoot":"","sources":["../../../adapters/cli/parse-args.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,KAAK,EAAE;QACL,IAAI,EAAE,OAAO,CAAC;QACd,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;QAC7B,OAAO,EAAE,OAAO,CAAC;QACjB,OAAO,EAAE,OAAO,CAAC;QACjB,IAAI,EAAE,OAAO,CAAC;QACd,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;QACxB,KAAK,EAAE,OAAO,CAAC;QACf,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;QAC1B,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;QAC7B,WAAW,EAAE,OAAO,CAAC;QACrB,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;KAC7B,CAAC;CACH;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CAsDpD"}
1
+ {"version":3,"file":"parse-args.d.ts","sourceRoot":"","sources":["../../../adapters/cli/parse-args.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,KAAK,EAAE;QACL,IAAI,EAAE,OAAO,CAAC;QACd,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;QAC7B,OAAO,EAAE,OAAO,CAAC;QACjB,OAAO,EAAE,OAAO,CAAC;QACjB,IAAI,EAAE,OAAO,CAAC;QACd,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;QACxB,KAAK,EAAE,OAAO,CAAC;QACf,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;QAC1B,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;QAC7B,WAAW,EAAE,OAAO,CAAC;QACrB,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;KAC7B,CAAC;CACH;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CA8DpD"}
@@ -18,24 +18,31 @@ export function parseArgs(argv) {
18
18
  };
19
19
  const positional = [];
20
20
  for (let i = 0; i < argv.length; i++) {
21
- const arg = argv[i];
21
+ let arg = argv[i];
22
+ // Handle --flag=value syntax: split into --flag and value
23
+ let inlineValue;
24
+ if (arg.startsWith("--") && arg.includes("=")) {
25
+ const eqIdx = arg.indexOf("=");
26
+ inlineValue = arg.slice(eqIdx + 1);
27
+ arg = arg.slice(0, eqIdx);
28
+ }
22
29
  if (arg === "--json") {
23
30
  flags.json = true;
24
31
  }
25
32
  else if (arg === "--meta-repo") {
26
- flags.metaRepo = argv[++i];
33
+ flags.metaRepo = inlineValue ?? argv[++i];
27
34
  }
28
35
  else if (arg === "--pin") {
29
- flags.pin = argv[++i];
36
+ flags.pin = inlineValue ?? argv[++i];
30
37
  }
31
38
  else if (arg === "--db-url") {
32
- flags.dbUrl = argv[++i];
39
+ flags.dbUrl = inlineValue ?? argv[++i];
33
40
  }
34
41
  else if (arg === "--strategy") {
35
- flags.strategy = argv[++i];
42
+ flags.strategy = inlineValue ?? argv[++i];
36
43
  }
37
44
  else if (arg === "--profile") {
38
- flags.profile = argv[++i];
45
+ flags.profile = inlineValue ?? argv[++i];
39
46
  }
40
47
  else if (arg === "--interactive" || arg === "-i") {
41
48
  flags.interactive = true;
@@ -52,12 +59,12 @@ export function parseArgs(argv) {
52
59
  else if (arg === "--help" || arg === "-h") {
53
60
  flags.help = true;
54
61
  }
55
- else if (arg.startsWith("-")) {
62
+ else if (argv[i].startsWith("-")) {
56
63
  // Unknown flag — treat as positional for now
57
- positional.push(arg);
64
+ positional.push(argv[i]);
58
65
  }
59
66
  else {
60
- positional.push(arg);
67
+ positional.push(argv[i]);
61
68
  }
62
69
  }
63
70
  const command = positional.length > 0 ? positional[0] : undefined;
@@ -1 +1 @@
1
- {"version":3,"file":"parse-args.js","sourceRoot":"","sources":["../../../adapters/cli/parse-args.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAoBH,MAAM,UAAU,SAAS,CAAC,IAAc;IACtC,MAAM,KAAK,GAAG;QACZ,IAAI,EAAE,KAAK;QACX,QAAQ,EAAE,SAA+B;QACzC,OAAO,EAAE,KAAK;QACd,OAAO,EAAE,KAAK;QACd,IAAI,EAAE,KAAK;QACX,GAAG,EAAE,SAA+B;QACpC,KAAK,EAAE,KAAK;QACZ,KAAK,EAAE,SAA+B;QACtC,QAAQ,EAAE,SAA+B;QACzC,WAAW,EAAE,KAAK;QAClB,OAAO,EAAE,SAA+B;KACzC,CAAC;IAEF,MAAM,UAAU,GAAa,EAAE,CAAC;IAEhC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QAEpB,IAAI,GAAG,KAAK,QAAQ,EAAE,CAAC;YACrB,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC;QACpB,CAAC;aAAM,IAAI,GAAG,KAAK,aAAa,EAAE,CAAC;YACjC,KAAK,CAAC,QAAQ,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;QAC7B,CAAC;aAAM,IAAI,GAAG,KAAK,OAAO,EAAE,CAAC;YAC3B,KAAK,CAAC,GAAG,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;QACxB,CAAC;aAAM,IAAI,GAAG,KAAK,UAAU,EAAE,CAAC;YAC9B,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;QAC1B,CAAC;aAAM,IAAI,GAAG,KAAK,YAAY,EAAE,CAAC;YAChC,KAAK,CAAC,QAAQ,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;QAC7B,CAAC;aAAM,IAAI,GAAG,KAAK,WAAW,EAAE,CAAC;YAC/B,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;QAC5B,CAAC;aAAM,IAAI,GAAG,KAAK,eAAe,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;YACnD,KAAK,CAAC,WAAW,GAAG,IAAI,CAAC;QAC3B,CAAC;aAAM,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;YAC7C,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC;QACrB,CAAC;aAAM,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,WAAW,EAAE,CAAC;YAC/C,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC;QACvB,CAAC;aAAM,IAAI,GAAG,KAAK,WAAW,EAAE,CAAC;YAC/B,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC;QACvB,CAAC;aAAM,IAAI,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;YAC5C,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC;QACpB,CAAC;aAAM,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YAC/B,6CAA6C;YAC7C,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACvB,CAAC;aAAM,CAAC;YACN,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED,MAAM,OAAO,GAAG,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAClE,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAEjC,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AAC9C,CAAC"}
1
+ {"version":3,"file":"parse-args.js","sourceRoot":"","sources":["../../../adapters/cli/parse-args.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAoBH,MAAM,UAAU,SAAS,CAAC,IAAc;IACtC,MAAM,KAAK,GAAG;QACZ,IAAI,EAAE,KAAK;QACX,QAAQ,EAAE,SAA+B;QACzC,OAAO,EAAE,KAAK;QACd,OAAO,EAAE,KAAK;QACd,IAAI,EAAE,KAAK;QACX,GAAG,EAAE,SAA+B;QACpC,KAAK,EAAE,KAAK;QACZ,KAAK,EAAE,SAA+B;QACtC,QAAQ,EAAE,SAA+B;QACzC,WAAW,EAAE,KAAK;QAClB,OAAO,EAAE,SAA+B;KACzC,CAAC;IAEF,MAAM,UAAU,GAAa,EAAE,CAAC;IAEhC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,IAAI,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QAElB,0DAA0D;QAC1D,IAAI,WAA+B,CAAC;QACpC,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YAC9C,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YAC/B,WAAW,GAAG,GAAG,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;YACnC,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;QAC5B,CAAC;QAED,IAAI,GAAG,KAAK,QAAQ,EAAE,CAAC;YACrB,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC;QACpB,CAAC;aAAM,IAAI,GAAG,KAAK,aAAa,EAAE,CAAC;YACjC,KAAK,CAAC,QAAQ,GAAG,WAAW,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;QAC5C,CAAC;aAAM,IAAI,GAAG,KAAK,OAAO,EAAE,CAAC;YAC3B,KAAK,CAAC,GAAG,GAAG,WAAW,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;QACvC,CAAC;aAAM,IAAI,GAAG,KAAK,UAAU,EAAE,CAAC;YAC9B,KAAK,CAAC,KAAK,GAAG,WAAW,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;QACzC,CAAC;aAAM,IAAI,GAAG,KAAK,YAAY,EAAE,CAAC;YAChC,KAAK,CAAC,QAAQ,GAAG,WAAW,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;QAC5C,CAAC;aAAM,IAAI,GAAG,KAAK,WAAW,EAAE,CAAC;YAC/B,KAAK,CAAC,OAAO,GAAG,WAAW,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;QAC3C,CAAC;aAAM,IAAI,GAAG,KAAK,eAAe,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;YACnD,KAAK,CAAC,WAAW,GAAG,IAAI,CAAC;QAC3B,CAAC;aAAM,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;YAC7C,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC;QACrB,CAAC;aAAM,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,WAAW,EAAE,CAAC;YAC/C,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC;QACvB,CAAC;aAAM,IAAI,GAAG,KAAK,WAAW,EAAE,CAAC;YAC/B,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC;QACvB,CAAC;aAAM,IAAI,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;YAC5C,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC;QACpB,CAAC;aAAM,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACnC,6CAA6C;YAC7C,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QAC3B,CAAC;aAAM,CAAC;YACN,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;IAED,MAAM,OAAO,GAAG,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAClE,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAEjC,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AAC9C,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@llipe.com/dev-tasks",
3
- "version": "0.6.5",
3
+ "version": "0.6.7",
4
4
  "description": "Multi-repo context tooling for dev-tasks",
5
5
  "type": "module",
6
6
  "imports": {