@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.
- package/CHANGELOG.md +104 -0
- package/README.md +823 -0
- package/bundle-manifest.json +113 -0
- package/dist/adapters/cli/extract-all.d.ts +31 -0
- package/dist/adapters/cli/extract-all.d.ts.map +1 -0
- package/dist/adapters/cli/extract-all.js +374 -0
- package/dist/adapters/cli/extract-all.js.map +1 -0
- package/dist/adapters/cli/extract-asyncapi.d.ts +26 -0
- package/dist/adapters/cli/extract-asyncapi.d.ts.map +1 -0
- package/dist/adapters/cli/extract-asyncapi.js +142 -0
- package/dist/adapters/cli/extract-asyncapi.js.map +1 -0
- package/dist/adapters/cli/extract-component.d.ts +24 -0
- package/dist/adapters/cli/extract-component.d.ts.map +1 -0
- package/dist/adapters/cli/extract-component.js +198 -0
- package/dist/adapters/cli/extract-component.js.map +1 -0
- package/dist/adapters/cli/extract-detect.d.ts +19 -0
- package/dist/adapters/cli/extract-detect.d.ts.map +1 -0
- package/dist/adapters/cli/extract-detect.js +98 -0
- package/dist/adapters/cli/extract-detect.js.map +1 -0
- package/dist/adapters/cli/extract-openapi.d.ts +29 -0
- package/dist/adapters/cli/extract-openapi.d.ts.map +1 -0
- package/dist/adapters/cli/extract-openapi.js +111 -0
- package/dist/adapters/cli/extract-openapi.js.map +1 -0
- package/dist/adapters/cli/extract-schema.d.ts +15 -0
- package/dist/adapters/cli/extract-schema.d.ts.map +1 -0
- package/dist/adapters/cli/extract-schema.js +39 -0
- package/dist/adapters/cli/extract-schema.js.map +1 -0
- package/dist/adapters/cli/index.d.ts +6 -0
- package/dist/adapters/cli/index.d.ts.map +1 -0
- package/dist/adapters/cli/index.js +5 -0
- package/dist/adapters/cli/index.js.map +1 -0
- package/dist/adapters/cli/parse-args.d.ts +22 -0
- package/dist/adapters/cli/parse-args.d.ts.map +1 -0
- package/dist/adapters/cli/parse-args.js +63 -0
- package/dist/adapters/cli/parse-args.js.map +1 -0
- package/dist/adapters/mcp/index.d.ts +5 -0
- package/dist/adapters/mcp/index.d.ts.map +1 -0
- package/dist/adapters/mcp/index.js +2 -0
- package/dist/adapters/mcp/index.js.map +1 -0
- package/dist/bin/dev-tasks.d.ts +7 -0
- package/dist/bin/dev-tasks.d.ts.map +1 -0
- package/dist/bin/dev-tasks.js +275 -0
- package/dist/bin/dev-tasks.js.map +1 -0
- package/dist/bin/dt.d.ts +7 -0
- package/dist/bin/dt.d.ts.map +1 -0
- package/dist/bin/dt.js +159 -0
- package/dist/bin/dt.js.map +1 -0
- package/dist/core/catalog/index.d.ts +5 -0
- package/dist/core/catalog/index.d.ts.map +1 -0
- package/dist/core/catalog/index.js +2 -0
- package/dist/core/catalog/index.js.map +1 -0
- package/dist/core/context/index.d.ts +5 -0
- package/dist/core/context/index.d.ts.map +1 -0
- package/dist/core/context/index.js +2 -0
- package/dist/core/context/index.js.map +1 -0
- package/dist/core/distribution/backup.d.ts +24 -0
- package/dist/core/distribution/backup.d.ts.map +1 -0
- package/dist/core/distribution/backup.js +37 -0
- package/dist/core/distribution/backup.js.map +1 -0
- package/dist/core/distribution/doctor.d.ts +35 -0
- package/dist/core/distribution/doctor.d.ts.map +1 -0
- package/dist/core/distribution/doctor.js +158 -0
- package/dist/core/distribution/doctor.js.map +1 -0
- package/dist/core/distribution/hash.d.ts +14 -0
- package/dist/core/distribution/hash.d.ts.map +1 -0
- package/dist/core/distribution/hash.js +21 -0
- package/dist/core/distribution/hash.js.map +1 -0
- package/dist/core/distribution/index.d.ts +18 -0
- package/dist/core/distribution/index.d.ts.map +1 -0
- package/dist/core/distribution/index.js +12 -0
- package/dist/core/distribution/index.js.map +1 -0
- package/dist/core/distribution/install.d.ts +25 -0
- package/dist/core/distribution/install.d.ts.map +1 -0
- package/dist/core/distribution/install.js +81 -0
- package/dist/core/distribution/install.js.map +1 -0
- package/dist/core/distribution/manifest.d.ts +28 -0
- package/dist/core/distribution/manifest.d.ts.map +1 -0
- package/dist/core/distribution/manifest.js +38 -0
- package/dist/core/distribution/manifest.js.map +1 -0
- package/dist/core/distribution/migrate.d.ts +54 -0
- package/dist/core/distribution/migrate.d.ts.map +1 -0
- package/dist/core/distribution/migrate.js +200 -0
- package/dist/core/distribution/migrate.js.map +1 -0
- package/dist/core/distribution/pin.d.ts +15 -0
- package/dist/core/distribution/pin.d.ts.map +1 -0
- package/dist/core/distribution/pin.js +37 -0
- package/dist/core/distribution/pin.js.map +1 -0
- package/dist/core/distribution/status.d.ts +20 -0
- package/dist/core/distribution/status.d.ts.map +1 -0
- package/dist/core/distribution/status.js +39 -0
- package/dist/core/distribution/status.js.map +1 -0
- package/dist/core/distribution/update.d.ts +41 -0
- package/dist/core/distribution/update.d.ts.map +1 -0
- package/dist/core/distribution/update.js +148 -0
- package/dist/core/distribution/update.js.map +1 -0
- package/dist/core/exit-codes.d.ts +23 -0
- package/dist/core/exit-codes.d.ts.map +1 -0
- package/dist/core/exit-codes.js +22 -0
- package/dist/core/exit-codes.js.map +1 -0
- package/dist/core/extract/asyncapi/index.d.ts +11 -0
- package/dist/core/extract/asyncapi/index.d.ts.map +1 -0
- package/dist/core/extract/asyncapi/index.js +7 -0
- package/dist/core/extract/asyncapi/index.js.map +1 -0
- package/dist/core/extract/asyncapi/payloads.d.ts +20 -0
- package/dist/core/extract/asyncapi/payloads.d.ts.map +1 -0
- package/dist/core/extract/asyncapi/payloads.js +421 -0
- package/dist/core/extract/asyncapi/payloads.js.map +1 -0
- package/dist/core/extract/asyncapi/topics.d.ts +27 -0
- package/dist/core/extract/asyncapi/topics.d.ts.map +1 -0
- package/dist/core/extract/asyncapi/topics.js +368 -0
- package/dist/core/extract/asyncapi/topics.js.map +1 -0
- package/dist/core/extract/asyncapi/types.d.ts +129 -0
- package/dist/core/extract/asyncapi/types.d.ts.map +1 -0
- package/dist/core/extract/asyncapi/types.js +5 -0
- package/dist/core/extract/asyncapi/types.js.map +1 -0
- package/dist/core/extract/asyncapi/validate.d.ts +29 -0
- package/dist/core/extract/asyncapi/validate.d.ts.map +1 -0
- package/dist/core/extract/asyncapi/validate.js +156 -0
- package/dist/core/extract/asyncapi/validate.js.map +1 -0
- package/dist/core/extract/component.d.ts +201 -0
- package/dist/core/extract/component.d.ts.map +1 -0
- package/dist/core/extract/component.js +258 -0
- package/dist/core/extract/component.js.map +1 -0
- package/dist/core/extract/detect.d.ts +35 -0
- package/dist/core/extract/detect.d.ts.map +1 -0
- package/dist/core/extract/detect.js +89 -0
- package/dist/core/extract/detect.js.map +1 -0
- package/dist/core/extract/index.d.ts +12 -0
- package/dist/core/extract/index.d.ts.map +1 -0
- package/dist/core/extract/index.js +6 -0
- package/dist/core/extract/index.js.map +1 -0
- package/dist/core/extract/openapi/index.d.ts +13 -0
- package/dist/core/extract/openapi/index.d.ts.map +1 -0
- package/dist/core/extract/openapi/index.js +9 -0
- package/dist/core/extract/openapi/index.js.map +1 -0
- package/dist/core/extract/openapi/llm-descriptions.d.ts +41 -0
- package/dist/core/extract/openapi/llm-descriptions.d.ts.map +1 -0
- package/dist/core/extract/openapi/llm-descriptions.js +36 -0
- package/dist/core/extract/openapi/llm-descriptions.js.map +1 -0
- package/dist/core/extract/openapi/route1.d.ts +36 -0
- package/dist/core/extract/openapi/route1.d.ts.map +1 -0
- package/dist/core/extract/openapi/route1.js +327 -0
- package/dist/core/extract/openapi/route1.js.map +1 -0
- package/dist/core/extract/openapi/route2.d.ts +46 -0
- package/dist/core/extract/openapi/route2.d.ts.map +1 -0
- package/dist/core/extract/openapi/route2.js +19 -0
- package/dist/core/extract/openapi/route2.js.map +1 -0
- package/dist/core/extract/openapi/route3.d.ts +26 -0
- package/dist/core/extract/openapi/route3.d.ts.map +1 -0
- package/dist/core/extract/openapi/route3.js +737 -0
- package/dist/core/extract/openapi/route3.js.map +1 -0
- package/dist/core/extract/openapi/types.d.ts +125 -0
- package/dist/core/extract/openapi/types.d.ts.map +1 -0
- package/dist/core/extract/openapi/types.js +5 -0
- package/dist/core/extract/openapi/types.js.map +1 -0
- package/dist/core/extract/openapi/validate.d.ts +29 -0
- package/dist/core/extract/openapi/validate.d.ts.map +1 -0
- package/dist/core/extract/openapi/validate.js +200 -0
- package/dist/core/extract/openapi/validate.js.map +1 -0
- package/dist/core/extract/orm/drizzle.d.ts +20 -0
- package/dist/core/extract/orm/drizzle.d.ts.map +1 -0
- package/dist/core/extract/orm/drizzle.js +283 -0
- package/dist/core/extract/orm/drizzle.js.map +1 -0
- package/dist/core/extract/orm/information-schema.d.ts +26 -0
- package/dist/core/extract/orm/information-schema.d.ts.map +1 -0
- package/dist/core/extract/orm/information-schema.js +142 -0
- package/dist/core/extract/orm/information-schema.js.map +1 -0
- package/dist/core/extract/orm/llm-descriptions.d.ts +28 -0
- package/dist/core/extract/orm/llm-descriptions.d.ts.map +1 -0
- package/dist/core/extract/orm/llm-descriptions.js +64 -0
- package/dist/core/extract/orm/llm-descriptions.js.map +1 -0
- package/dist/core/extract/orm/migration-inference.d.ts +25 -0
- package/dist/core/extract/orm/migration-inference.d.ts.map +1 -0
- package/dist/core/extract/orm/migration-inference.js +76 -0
- package/dist/core/extract/orm/migration-inference.js.map +1 -0
- package/dist/core/extract/orm/prisma.d.ts +23 -0
- package/dist/core/extract/orm/prisma.d.ts.map +1 -0
- package/dist/core/extract/orm/prisma.js +234 -0
- package/dist/core/extract/orm/prisma.js.map +1 -0
- package/dist/core/extract/orm/typeorm.d.ts +22 -0
- package/dist/core/extract/orm/typeorm.d.ts.map +1 -0
- package/dist/core/extract/orm/typeorm.js +269 -0
- package/dist/core/extract/orm/typeorm.js.map +1 -0
- package/dist/core/extract/orm/types.d.ts +97 -0
- package/dist/core/extract/orm/types.d.ts.map +1 -0
- package/dist/core/extract/orm/types.js +6 -0
- package/dist/core/extract/orm/types.js.map +1 -0
- package/dist/core/extract/prompt.d.ts +21 -0
- package/dist/core/extract/prompt.d.ts.map +1 -0
- package/dist/core/extract/prompt.js +79 -0
- package/dist/core/extract/prompt.js.map +1 -0
- package/dist/core/extract/provider.d.ts +117 -0
- package/dist/core/extract/provider.d.ts.map +1 -0
- package/dist/core/extract/provider.js +6 -0
- package/dist/core/extract/provider.js.map +1 -0
- package/dist/core/extract/providers/node-ts.d.ts +69 -0
- package/dist/core/extract/providers/node-ts.d.ts.map +1 -0
- package/dist/core/extract/providers/node-ts.js +311 -0
- package/dist/core/extract/providers/node-ts.js.map +1 -0
- package/dist/core/extract/render/schema-md.d.ts +16 -0
- package/dist/core/extract/render/schema-md.d.ts.map +1 -0
- package/dist/core/extract/render/schema-md.js +140 -0
- package/dist/core/extract/render/schema-md.js.map +1 -0
- package/dist/core/extract/report.d.ts +97 -0
- package/dist/core/extract/report.d.ts.map +1 -0
- package/dist/core/extract/report.js +47 -0
- package/dist/core/extract/report.js.map +1 -0
- package/dist/core/extract/schema.d.ts +36 -0
- package/dist/core/extract/schema.d.ts.map +1 -0
- package/dist/core/extract/schema.js +141 -0
- package/dist/core/extract/schema.js.map +1 -0
- package/dist/core/index.d.ts +15 -0
- package/dist/core/index.d.ts.map +1 -0
- package/dist/core/index.js +14 -0
- package/dist/core/index.js.map +1 -0
- package/dist/core/providers/index.d.ts +5 -0
- package/dist/core/providers/index.d.ts.map +1 -0
- package/dist/core/providers/index.js +2 -0
- package/dist/core/providers/index.js.map +1 -0
- package/dist/core/reconcile.d.ts +25 -0
- package/dist/core/reconcile.d.ts.map +1 -0
- package/dist/core/reconcile.js +36 -0
- package/dist/core/reconcile.js.map +1 -0
- package/dist/core/scope/index.d.ts +5 -0
- package/dist/core/scope/index.d.ts.map +1 -0
- package/dist/core/scope/index.js +2 -0
- package/dist/core/scope/index.js.map +1 -0
- package/package.json +77 -0
- package/schemas/.gitkeep +0 -0
- 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)
|