haki-skills 0.2.3 → 0.2.4
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.
|
@@ -0,0 +1,810 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: swarm-dev-team
|
|
3
|
+
description: Spawn a full software development team as parallel subagents, each with specialized roles and haki skills. Supports both greenfield and brownfield projects. Produces structured reports for tracking and review.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Swarm Dev Team
|
|
7
|
+
|
|
8
|
+
Orchestrate a complete software development team using Claude Code subagents. Each agent assumes a specialized role, leverages specific haki skills/workflows, and produces a standardized report.
|
|
9
|
+
|
|
10
|
+
**Works with:** Existing haki workflows (`/haki:*`), haki-tools CLI, and all `.agent/skills/`.
|
|
11
|
+
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## When to Use
|
|
15
|
+
|
|
16
|
+
- Starting a new feature or project that spans multiple concerns (DB, backend, frontend, testing, security, docs, DevOps)
|
|
17
|
+
- Applying structured team development to an existing codebase (brownfield)
|
|
18
|
+
- When you need traceable reports per role for review and auditing
|
|
19
|
+
|
|
20
|
+
## Prerequisites
|
|
21
|
+
|
|
22
|
+
- Haki installed in the project (`npx haki-skills --for claude`)
|
|
23
|
+
- `.haki/PROJECT.md` and `.haki/ROADMAP.md` exist (run `/haki:new-project` first)
|
|
24
|
+
- For brownfield: `.haki/codebase/` exists (run `/haki:map-codebase` first)
|
|
25
|
+
|
|
26
|
+
---
|
|
27
|
+
|
|
28
|
+
## Team Architecture
|
|
29
|
+
|
|
30
|
+
```
|
|
31
|
+
┌──────────────────────────────────────────────────────────┐
|
|
32
|
+
│ 🎯 TECH LEAD (You / Orchestrator) │
|
|
33
|
+
│ /haki:next → Discovery → Plan → Dispatch → Review │
|
|
34
|
+
└────────────────────────────┬─────────────────────────────┘
|
|
35
|
+
│
|
|
36
|
+
┌────────────────────┼─────────────────────┐
|
|
37
|
+
│ │ │
|
|
38
|
+
▼ ▼ ▼
|
|
39
|
+
┌──────────────┐ ┌──────────────┐ ┌───────────────┐
|
|
40
|
+
│ 📐 Architect │ │ 🗄️ DB Eng. │ │ 🔬 Researcher │
|
|
41
|
+
│ (Phase 1) │ │ (Phase 2) │ │ (Phase 1) │
|
|
42
|
+
└──────┬───────┘ └──────┬───────┘ └───────────────┘
|
|
43
|
+
│ │
|
|
44
|
+
▼ ▼
|
|
45
|
+
┌──────────────┐ ┌──────────────┐ ← Parallel
|
|
46
|
+
│ ⚙️ Backend │ │ 🎨 Frontend │
|
|
47
|
+
│ (Phase 3) │ │ (Phase 3) │
|
|
48
|
+
└──────┬───────┘ └──────┬───────┘
|
|
49
|
+
│ │
|
|
50
|
+
▼ ▼
|
|
51
|
+
┌──────────────┐ ┌──────────────┐ ← Parallel
|
|
52
|
+
│ 🧪 QA / Test │ │ 🔒 Security │
|
|
53
|
+
│ (Phase 4) │ │ (Phase 4) │
|
|
54
|
+
└──────┬───────┘ └──────┬───────┘
|
|
55
|
+
│ │
|
|
56
|
+
▼ ▼
|
|
57
|
+
┌──────────────┐ ┌──────────────┐ ← Parallel
|
|
58
|
+
│ 📝 Tech Docs │ │ 🚀 DevOps │
|
|
59
|
+
│ (Phase 5) │ │ (Phase 5) │
|
|
60
|
+
└──────────────┘ └──────────────┘
|
|
61
|
+
│
|
|
62
|
+
▼
|
|
63
|
+
┌──────────────────────────────────┐
|
|
64
|
+
│ 📊 DASHBOARD (auto-generated) │
|
|
65
|
+
└──────────────────────────────────┘
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
---
|
|
69
|
+
|
|
70
|
+
## Report Directory Structure
|
|
71
|
+
|
|
72
|
+
All agent reports are stored under `.haki/reports/`. This directory is created automatically.
|
|
73
|
+
|
|
74
|
+
```
|
|
75
|
+
.haki/
|
|
76
|
+
├── reports/
|
|
77
|
+
│ ├── 00-discovery.md ← Brownfield only: codebase analysis
|
|
78
|
+
│ ├── 01-architect.md ← Architecture decisions & diagrams
|
|
79
|
+
│ ├── 02-researcher.md ← Tech stack research (Context7)
|
|
80
|
+
│ ├── 03-db-engineer.md ← Schema design & migrations
|
|
81
|
+
│ ├── 04-backend-dev.md ← Backend implementation report
|
|
82
|
+
│ ├── 05-frontend-dev.md ← Frontend implementation report
|
|
83
|
+
│ ├── 06-qa-engineer.md ← Test results & coverage
|
|
84
|
+
│ ├── 07-security-engineer.md ← Security audit findings
|
|
85
|
+
│ ├── 08-tech-writer.md ← Documentation status
|
|
86
|
+
│ ├── 09-devops-engineer.md ← CI/CD & deployment report
|
|
87
|
+
│ └── DASHBOARD.md ← Aggregated team dashboard
|
|
88
|
+
├── PROJECT.md
|
|
89
|
+
├── ROADMAP.md
|
|
90
|
+
├── tasks/
|
|
91
|
+
├── research/
|
|
92
|
+
└── codebase/ ← From /haki:map-codebase
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
---
|
|
96
|
+
|
|
97
|
+
## Report Template (MANDATORY for every agent)
|
|
98
|
+
|
|
99
|
+
Every subagent MUST write its report to `.haki/reports/NN-role.md` using this exact structure:
|
|
100
|
+
|
|
101
|
+
```markdown
|
|
102
|
+
# [ICON] [ROLE NAME] Report
|
|
103
|
+
|
|
104
|
+
**Agent:** [Role name]
|
|
105
|
+
**Phase:** [Phase number]
|
|
106
|
+
**Status:** 🟢 COMPLETED | 🟡 PARTIAL | 🔴 BLOCKED
|
|
107
|
+
**Started:** [ISO 8601 timestamp]
|
|
108
|
+
**Completed:** [ISO 8601 timestamp]
|
|
109
|
+
|
|
110
|
+
---
|
|
111
|
+
|
|
112
|
+
## Input
|
|
113
|
+
|
|
114
|
+
- **Received from:** [Previous agent/phase]
|
|
115
|
+
- **Files read:** [List of files consumed]
|
|
116
|
+
- **Haki context:** [PROJECT.md, ROADMAP.md, task files, codebase maps used]
|
|
117
|
+
|
|
118
|
+
---
|
|
119
|
+
|
|
120
|
+
## Objectives
|
|
121
|
+
|
|
122
|
+
- [x] Objective 1 — completed
|
|
123
|
+
- [x] Objective 2 — completed
|
|
124
|
+
- [ ] Objective 3 — skipped (reason)
|
|
125
|
+
|
|
126
|
+
---
|
|
127
|
+
|
|
128
|
+
## Tasks Executed
|
|
129
|
+
|
|
130
|
+
### Task 1: [Name]
|
|
131
|
+
|
|
132
|
+
- **Status:** ✅ Done | ⚠️ Partial | ❌ Failed | ⏭️ Skipped
|
|
133
|
+
- **Haki skill used:** [skill name from .agent/skills/]
|
|
134
|
+
- **Haki workflow used:** [workflow name, if any]
|
|
135
|
+
- **Files changed:**
|
|
136
|
+
|
|
137
|
+
| File | Action | Description |
|
|
138
|
+
|------|--------|-------------|
|
|
139
|
+
| `path/to/file` | Created | Brief description |
|
|
140
|
+
| `path/to/file` | Modified | Brief description |
|
|
141
|
+
|
|
142
|
+
- **Details:** [What was done]
|
|
143
|
+
- **Issues found:** [Any problems discovered]
|
|
144
|
+
|
|
145
|
+
### Task 2: [Name]
|
|
146
|
+
...
|
|
147
|
+
|
|
148
|
+
---
|
|
149
|
+
|
|
150
|
+
## Metrics
|
|
151
|
+
|
|
152
|
+
| Metric | Before | After | Target |
|
|
153
|
+
|--------|--------|-------|--------|
|
|
154
|
+
| [metric] | [val] | [val] | [val] |
|
|
155
|
+
|
|
156
|
+
---
|
|
157
|
+
|
|
158
|
+
## Issues & Risks
|
|
159
|
+
|
|
160
|
+
| # | Severity | Description | Recommendation | Status |
|
|
161
|
+
|---|----------|-------------|----------------|--------|
|
|
162
|
+
| 1 | 🔴 Critical | ... | ... | Open |
|
|
163
|
+
| 2 | 🟡 Medium | ... | ... | Resolved |
|
|
164
|
+
| 3 | 🟢 Low | ... | ... | Open |
|
|
165
|
+
|
|
166
|
+
---
|
|
167
|
+
|
|
168
|
+
## Output
|
|
169
|
+
|
|
170
|
+
- **Total files created:** [N]
|
|
171
|
+
- **Total files modified:** [N]
|
|
172
|
+
- **Handoff notes:** [What the next agent needs to know]
|
|
173
|
+
|
|
174
|
+
---
|
|
175
|
+
|
|
176
|
+
## Recommendations
|
|
177
|
+
|
|
178
|
+
1. [Actionable recommendation]
|
|
179
|
+
2. [Actionable recommendation]
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
---
|
|
183
|
+
|
|
184
|
+
## Phase Execution
|
|
185
|
+
|
|
186
|
+
### Phase 0: Discovery (Brownfield Only)
|
|
187
|
+
|
|
188
|
+
**Trigger:** Project has existing source code.
|
|
189
|
+
|
|
190
|
+
**Action:** Run `/haki:map-codebase` which spawns 4 parallel mapper subagents:
|
|
191
|
+
|
|
192
|
+
| Mapper | Output | Content |
|
|
193
|
+
|--------|--------|---------|
|
|
194
|
+
| Stack | `.haki/codebase/STACK.md` | Languages, frameworks, build tools, deps |
|
|
195
|
+
| Architecture | `.haki/codebase/ARCHITECTURE.md` | System patterns, data flow, API design |
|
|
196
|
+
| Conventions | `.haki/codebase/CONVENTIONS.md` | Code style, naming, testing patterns |
|
|
197
|
+
| Structure | `.haki/codebase/STRUCTURE.md` | Directory tree, entry points, configs |
|
|
198
|
+
|
|
199
|
+
After mapping, also scan for issues:
|
|
200
|
+
|
|
201
|
+
```bash
|
|
202
|
+
# Find TODOs, FIXMEs, HACKs
|
|
203
|
+
grep -rn "TODO\|FIXME\|HACK\|XXX\|DEPRECATED" --include="*.ts" --include="*.tsx" --include="*.py" --include="*.go" . | head -50
|
|
204
|
+
|
|
205
|
+
# Count test files
|
|
206
|
+
find . -name "*.test.*" -o -name "*.spec.*" -o -name "*_test.*" | wc -l
|
|
207
|
+
|
|
208
|
+
# Check git history
|
|
209
|
+
git log --oneline -20 2>/dev/null
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
Write discovery summary to `.haki/reports/00-discovery.md` using the report template.
|
|
213
|
+
|
|
214
|
+
**Brownfield golden rules:**
|
|
215
|
+
- Do NOT refactor working code just for style preferences
|
|
216
|
+
- Do NOT change tech stack unless there is a critical reason
|
|
217
|
+
- Prioritize CONSISTENCY with existing codebase conventions
|
|
218
|
+
- Every change must have a rollback path
|
|
219
|
+
- Read `.haki/codebase/CONVENTIONS.md` before writing any code
|
|
220
|
+
|
|
221
|
+
---
|
|
222
|
+
|
|
223
|
+
### Phase 1: Architecture & Research (Parallel)
|
|
224
|
+
|
|
225
|
+
Spawn two subagents in parallel:
|
|
226
|
+
|
|
227
|
+
#### 📐 Subagent: System Architect
|
|
228
|
+
|
|
229
|
+
**Haki skills to read first:**
|
|
230
|
+
- `.agent/skills/writing-plans/SKILL.md`
|
|
231
|
+
- `.agent/skills/brainstorming/SKILL.md`
|
|
232
|
+
|
|
233
|
+
**Haki context to load:**
|
|
234
|
+
- `.haki/PROJECT.md` — project vision and constraints
|
|
235
|
+
- `.haki/ROADMAP.md` — task breakdown
|
|
236
|
+
- `.haki/codebase/ARCHITECTURE.md` — existing architecture (brownfield)
|
|
237
|
+
- `.haki/codebase/CONVENTIONS.md` — existing conventions (brownfield)
|
|
238
|
+
|
|
239
|
+
**Instructions:**
|
|
240
|
+
|
|
241
|
+
1. **Architecture design:**
|
|
242
|
+
- Choose architectural pattern (monolith / modular monolith / microservices)
|
|
243
|
+
- Define layer architecture (presentation → application → domain → infrastructure)
|
|
244
|
+
- Draw system diagrams (C4 model: context, container, component)
|
|
245
|
+
- For brownfield: map as-is → define to-be → plan migration path
|
|
246
|
+
|
|
247
|
+
2. **API contract design:**
|
|
248
|
+
- Define all API endpoints (OpenAPI spec or markdown table)
|
|
249
|
+
- Request/response schemas with TypeScript types
|
|
250
|
+
- Error response format (standardized)
|
|
251
|
+
- Pagination, filtering, sorting conventions
|
|
252
|
+
|
|
253
|
+
3. **Coding conventions (greenfield only):**
|
|
254
|
+
- Project folder structure
|
|
255
|
+
- Naming conventions
|
|
256
|
+
- Error handling strategy
|
|
257
|
+
- Logging strategy
|
|
258
|
+
- For brownfield: document EXISTING conventions, do not invent new ones
|
|
259
|
+
|
|
260
|
+
4. **Create base config files (greenfield only):**
|
|
261
|
+
- `tsconfig.json` / `pyproject.toml` / equivalent
|
|
262
|
+
- Linter config (ESLint/Biome/Ruff)
|
|
263
|
+
- `.env.example`
|
|
264
|
+
|
|
265
|
+
**Output:** Write report to `.haki/reports/01-architect.md`
|
|
266
|
+
**Also save:** `docs/ARCHITECTURE.md`, `docs/api-contract.md`
|
|
267
|
+
|
|
268
|
+
#### 🔬 Subagent: Tech Researcher
|
|
269
|
+
|
|
270
|
+
**Haki skills to read first:**
|
|
271
|
+
- `.agent/skills/context7-research/SKILL.md`
|
|
272
|
+
|
|
273
|
+
**Haki workflow:** Follow `/haki:research` protocol exactly.
|
|
274
|
+
|
|
275
|
+
**Instructions:**
|
|
276
|
+
|
|
277
|
+
1. For every library in the chosen tech stack, use Context7 MCP:
|
|
278
|
+
- Resolve library ID
|
|
279
|
+
- Query docs for latest version, install command, config format
|
|
280
|
+
- Check peer dependency compatibility
|
|
281
|
+
|
|
282
|
+
2. Research integration patterns between chosen libraries
|
|
283
|
+
|
|
284
|
+
3. Save verified stack to `.haki/research/STACK.md`
|
|
285
|
+
|
|
286
|
+
**Output:** Write report to `.haki/reports/02-researcher.md`
|
|
287
|
+
|
|
288
|
+
---
|
|
289
|
+
|
|
290
|
+
### Phase 2: Database Engineering
|
|
291
|
+
|
|
292
|
+
#### 🗄️ Subagent: Database Engineer
|
|
293
|
+
|
|
294
|
+
**Haki skills to read first:**
|
|
295
|
+
- `.agent/skills/test-driven-development/SKILL.md`
|
|
296
|
+
- `.agent/skills/subagent-driven-development/SKILL.md`
|
|
297
|
+
|
|
298
|
+
**Haki context to load:**
|
|
299
|
+
- `.haki/reports/01-architect.md` — architecture decisions
|
|
300
|
+
- `.haki/reports/02-researcher.md` — verified library versions
|
|
301
|
+
- `.haki/codebase/STACK.md` — existing DB setup (brownfield)
|
|
302
|
+
|
|
303
|
+
**Instructions:**
|
|
304
|
+
|
|
305
|
+
1. **Data modeling:**
|
|
306
|
+
- Analyze entities and relationships from ROADMAP requirements
|
|
307
|
+
- Design ERD (Entity Relationship Diagram)
|
|
308
|
+
- Normalize to 3NF; denormalize intentionally for performance
|
|
309
|
+
- Define index strategy
|
|
310
|
+
|
|
311
|
+
2. **Schema implementation:**
|
|
312
|
+
- Create migration files in dependency order
|
|
313
|
+
- Define constraints: PK, FK, UNIQUE, CHECK, NOT NULL
|
|
314
|
+
- Add audit fields: `created_at`, `updated_at`, `created_by`, `updated_by`
|
|
315
|
+
- Soft delete via `deleted_at` timestamp
|
|
316
|
+
- For brownfield: create NEW migrations only, NEVER edit existing ones
|
|
317
|
+
|
|
318
|
+
3. **Seed data:**
|
|
319
|
+
- Development seed files
|
|
320
|
+
- Test fixtures
|
|
321
|
+
|
|
322
|
+
4. **Performance:**
|
|
323
|
+
- Composite indexes for frequent query patterns
|
|
324
|
+
- Identify potential N+1 query patterns
|
|
325
|
+
|
|
326
|
+
**TDD approach:** Write migration → verify it runs → write seed → verify data integrity.
|
|
327
|
+
|
|
328
|
+
**Output:** Write report to `.haki/reports/03-db-engineer.md`
|
|
329
|
+
|
|
330
|
+
---
|
|
331
|
+
|
|
332
|
+
### Phase 3: Implementation (Parallel)
|
|
333
|
+
|
|
334
|
+
Spawn two subagents in parallel. Both MUST follow TDD.
|
|
335
|
+
|
|
336
|
+
#### ⚙️ Subagent: Backend Developer
|
|
337
|
+
|
|
338
|
+
**Haki skills to read first:**
|
|
339
|
+
- `.agent/skills/subagent-driven-development/SKILL.md` — follow the implementer prompt
|
|
340
|
+
- `.agent/skills/test-driven-development/SKILL.md` — TDD cycle is mandatory
|
|
341
|
+
- `.agent/skills/systematic-debugging/SKILL.md` — for when tests fail unexpectedly
|
|
342
|
+
- `.agent/skills/verification-before-completion/SKILL.md` — verify before marking done
|
|
343
|
+
|
|
344
|
+
**Haki workflow integration:**
|
|
345
|
+
- For each task from ROADMAP, the plan in `.haki/tasks/[task-id].md` defines the steps
|
|
346
|
+
- Follow the TDD cycle from the task plan: write test → RED → implement → GREEN → commit
|
|
347
|
+
- Update task file's "Implementation Details" and "Execution Results" sections after completion
|
|
348
|
+
|
|
349
|
+
**Haki context to load:**
|
|
350
|
+
- `.haki/reports/01-architect.md` — API contracts, architecture
|
|
351
|
+
- `.haki/reports/03-db-engineer.md` — DB schema, models
|
|
352
|
+
- `.haki/tasks/[task-id].md` — task plan with TDD steps
|
|
353
|
+
- `.haki/codebase/CONVENTIONS.md` — existing code style (brownfield)
|
|
354
|
+
|
|
355
|
+
**Instructions:**
|
|
356
|
+
|
|
357
|
+
1. **Project setup (greenfield):**
|
|
358
|
+
- Initialize project with verified tech stack from researcher report
|
|
359
|
+
- Install dependencies using exact versions from `.haki/research/STACK.md`
|
|
360
|
+
- Configure project structure per architect report
|
|
361
|
+
|
|
362
|
+
2. **Core infrastructure:**
|
|
363
|
+
- Database connection & ORM setup
|
|
364
|
+
- Authentication & authorization middleware (JWT/OAuth2)
|
|
365
|
+
- Request validation middleware (Zod/Joi/Pydantic)
|
|
366
|
+
- Global error handler with standardized error format
|
|
367
|
+
- Structured logging middleware
|
|
368
|
+
- Rate limiting, CORS, health check endpoint
|
|
369
|
+
|
|
370
|
+
3. **Business logic (per task):**
|
|
371
|
+
- Follow Clean Architecture layers:
|
|
372
|
+
- Controllers/Handlers → Services/Use Cases → Repositories → Entities
|
|
373
|
+
- Implement each API endpoint per contract from architect
|
|
374
|
+
- Transaction management for complex operations
|
|
375
|
+
- TDD: every function has a test BEFORE implementation
|
|
376
|
+
|
|
377
|
+
4. **For brownfield:**
|
|
378
|
+
- Match existing code patterns exactly
|
|
379
|
+
- Add new endpoints following existing router conventions
|
|
380
|
+
- Do NOT restructure existing code
|
|
381
|
+
|
|
382
|
+
**Quality gates:**
|
|
383
|
+
- All tests pass
|
|
384
|
+
- No linting errors
|
|
385
|
+
- No `any` types (TypeScript)
|
|
386
|
+
- Every public function has JSDoc/TSDoc
|
|
387
|
+
|
|
388
|
+
**Output:** Write report to `.haki/reports/04-backend-dev.md`
|
|
389
|
+
**Also update:** `.haki/tasks/[task-id].md` with Implementation Details + Execution Results
|
|
390
|
+
|
|
391
|
+
#### 🎨 Subagent: Frontend Developer
|
|
392
|
+
|
|
393
|
+
**Haki skills to read first:**
|
|
394
|
+
- `.agent/skills/subagent-driven-development/SKILL.md`
|
|
395
|
+
- `.agent/skills/test-driven-development/SKILL.md`
|
|
396
|
+
- Read UI skill based on config: `node .agent/bin/haki-tools.cjs config get ui_design_skill --raw`
|
|
397
|
+
- If `ui-ux-pro-max` → read `.agent/skills/ui-ux-pro-max/SKILL.md`
|
|
398
|
+
- If `taste-skill` → read `.agent/skills/taste-skill/SKILL.md` + variant skill
|
|
399
|
+
- `.agent/skills/verification-before-completion/SKILL.md`
|
|
400
|
+
|
|
401
|
+
**Haki context to load:**
|
|
402
|
+
- `.haki/reports/01-architect.md` — API contracts, component architecture
|
|
403
|
+
- `.haki/reports/02-researcher.md` — verified frontend library versions
|
|
404
|
+
- `.haki/tasks/[task-id].md` — task plan with TDD steps
|
|
405
|
+
- `.haki/codebase/CONVENTIONS.md` — existing UI patterns (brownfield)
|
|
406
|
+
|
|
407
|
+
**Instructions:**
|
|
408
|
+
|
|
409
|
+
1. **Project setup (greenfield):**
|
|
410
|
+
- Initialize frontend with verified versions
|
|
411
|
+
- Configure build tools, Tailwind/CSS, path aliases
|
|
412
|
+
- Apply chosen UI design skill for design tokens and component style
|
|
413
|
+
|
|
414
|
+
2. **Design system & components:**
|
|
415
|
+
- Create design tokens (colors, spacing, typography, shadows)
|
|
416
|
+
- Build base components: Button, Input, Select, Modal, Toast, Table, Card
|
|
417
|
+
- Each component must have: TypeScript props, variants, ARIA attributes, responsive design
|
|
418
|
+
- Loading/error/empty states for every data-fetching component
|
|
419
|
+
|
|
420
|
+
3. **Pages & features (per task):**
|
|
421
|
+
- Implement routing structure
|
|
422
|
+
- API integration using TanStack Query / SWR
|
|
423
|
+
- Form handling with validation (React Hook Form + Zod)
|
|
424
|
+
- Optimistic updates for better UX
|
|
425
|
+
|
|
426
|
+
4. **Performance & UX:**
|
|
427
|
+
- Code splitting & lazy loading
|
|
428
|
+
- Skeleton loaders, error boundaries
|
|
429
|
+
- Dark mode support (if specified)
|
|
430
|
+
|
|
431
|
+
5. **For brownfield:**
|
|
432
|
+
- Match existing component patterns
|
|
433
|
+
- Use existing design system/tokens
|
|
434
|
+
- Do NOT introduce new UI libraries unless approved
|
|
435
|
+
|
|
436
|
+
**Output:** Write report to `.haki/reports/05-frontend-dev.md`
|
|
437
|
+
**Also update:** `.haki/tasks/[task-id].md` with Implementation Details + Execution Results
|
|
438
|
+
|
|
439
|
+
---
|
|
440
|
+
|
|
441
|
+
### Phase 4: Quality & Security (Parallel)
|
|
442
|
+
|
|
443
|
+
#### 🧪 Subagent: QA / Test Engineer
|
|
444
|
+
|
|
445
|
+
**Haki skills to read first:**
|
|
446
|
+
- `.agent/skills/test-driven-development/SKILL.md`
|
|
447
|
+
- `.agent/skills/api-testing/SKILL.md`
|
|
448
|
+
- `.agent/skills/playwright-automation/SKILL.md`
|
|
449
|
+
- `.agent/skills/playwright-intent-to-spec/SKILL.md`
|
|
450
|
+
- `.agent/skills/systematic-debugging/SKILL.md`
|
|
451
|
+
- `.agent/skills/verification-before-completion/SKILL.md`
|
|
452
|
+
|
|
453
|
+
**Haki workflows to use:**
|
|
454
|
+
- `/haki:api-test init` → set up API test infrastructure
|
|
455
|
+
- `/haki:api-test generate [resource]` → generate API tests per resource
|
|
456
|
+
- `/haki:e2e init` → set up Playwright infrastructure
|
|
457
|
+
- `/haki:e2e generate [feature]` → generate E2E tests per feature
|
|
458
|
+
|
|
459
|
+
**Instructions:**
|
|
460
|
+
|
|
461
|
+
1. **Review existing tests:**
|
|
462
|
+
- Scan all `*.test.*` and `*.spec.*` files
|
|
463
|
+
- Identify untested code paths using coverage reports
|
|
464
|
+
- Check for testing anti-patterns (read `.agent/skills/test-driven-development/testing-anti-patterns.md`)
|
|
465
|
+
|
|
466
|
+
2. **Unit test gaps:**
|
|
467
|
+
- Add tests for edge cases: null inputs, boundary values, error scenarios
|
|
468
|
+
- Target: ≥ 80% code coverage
|
|
469
|
+
|
|
470
|
+
3. **API integration tests:**
|
|
471
|
+
- Use `/haki:api-test` workflow to generate tests for each API resource
|
|
472
|
+
- Test: success (200/201), validation error (400), not found (404), unauthorized (401)
|
|
473
|
+
|
|
474
|
+
4. **E2E tests:**
|
|
475
|
+
- Use `/haki:e2e` workflow to set up Playwright
|
|
476
|
+
- Generate specs for critical user journeys using `/haki:e2e-gen`
|
|
477
|
+
- Critical paths: registration → login → core feature → logout
|
|
478
|
+
|
|
479
|
+
5. **Performance baseline:**
|
|
480
|
+
- API response time benchmarks
|
|
481
|
+
- Frontend Lighthouse audit script
|
|
482
|
+
|
|
483
|
+
**Metrics to report:**
|
|
484
|
+
|
|
485
|
+
| Metric | Value | Target |
|
|
486
|
+
|--------|-------|--------|
|
|
487
|
+
| Unit test coverage | X% | ≥ 80% |
|
|
488
|
+
| API tests passing | X/Y | 100% |
|
|
489
|
+
| E2E tests passing | X/Y | 100% |
|
|
490
|
+
| Lint errors | N | 0 |
|
|
491
|
+
|
|
492
|
+
**Output:** Write report to `.haki/reports/06-qa-engineer.md`
|
|
493
|
+
|
|
494
|
+
#### 🔒 Subagent: Security Engineer
|
|
495
|
+
|
|
496
|
+
**Haki skills to read first:**
|
|
497
|
+
- `.agent/skills/systematic-debugging/SKILL.md` — root cause analysis methodology
|
|
498
|
+
- `.agent/skills/verification-before-completion/SKILL.md`
|
|
499
|
+
|
|
500
|
+
**Instructions:**
|
|
501
|
+
|
|
502
|
+
1. **OWASP Top 10 audit:**
|
|
503
|
+
- Injection (SQL, NoSQL, OS Command)
|
|
504
|
+
- Broken authentication
|
|
505
|
+
- Sensitive data exposure
|
|
506
|
+
- Broken access control
|
|
507
|
+
- XSS (Cross-Site Scripting)
|
|
508
|
+
- Security misconfiguration
|
|
509
|
+
- Using components with known vulnerabilities
|
|
510
|
+
|
|
511
|
+
2. **Authentication hardening:**
|
|
512
|
+
- Password hashing review (bcrypt/argon2 with proper rounds)
|
|
513
|
+
- JWT security (expiry, refresh rotation, blacklisting)
|
|
514
|
+
- RBAC/ABAC implementation review
|
|
515
|
+
- Brute force protection
|
|
516
|
+
|
|
517
|
+
3. **Data protection:**
|
|
518
|
+
- Input sanitization audit
|
|
519
|
+
- Output encoding
|
|
520
|
+
- File upload security
|
|
521
|
+
- PII handling
|
|
522
|
+
|
|
523
|
+
4. **Infrastructure security:**
|
|
524
|
+
- Security headers (CSP, HSTS, X-Frame-Options)
|
|
525
|
+
- CORS policy review
|
|
526
|
+
- Dependency vulnerability scan:
|
|
527
|
+
```bash
|
|
528
|
+
npm audit 2>/dev/null || bun audit 2>/dev/null || pip audit 2>/dev/null
|
|
529
|
+
```
|
|
530
|
+
- Secrets management review (.env files, hardcoded secrets)
|
|
531
|
+
|
|
532
|
+
5. **Fix critical issues immediately.** Log all findings with severity.
|
|
533
|
+
|
|
534
|
+
**Output:** Write report to `.haki/reports/07-security-engineer.md`
|
|
535
|
+
|
|
536
|
+
---
|
|
537
|
+
|
|
538
|
+
### Phase 5: Documentation & DevOps (Parallel)
|
|
539
|
+
|
|
540
|
+
#### 📝 Subagent: Technical Writer
|
|
541
|
+
|
|
542
|
+
**Haki skills to read first:**
|
|
543
|
+
- `.agent/skills/user-docs-generator/SKILL.md`
|
|
544
|
+
- `.agent/skills/output-skill/SKILL.md` — full output enforcement
|
|
545
|
+
|
|
546
|
+
**Haki workflow to use:**
|
|
547
|
+
- `/haki:docs --all` — generate user guides for all modules
|
|
548
|
+
|
|
549
|
+
**Instructions:**
|
|
550
|
+
|
|
551
|
+
1. **README.md:**
|
|
552
|
+
- Project overview, features, tech stack
|
|
553
|
+
- Quick start guide (< 5 minutes to run)
|
|
554
|
+
- Contributing guidelines
|
|
555
|
+
|
|
556
|
+
2. **Developer documentation:**
|
|
557
|
+
- `docs/GETTING_STARTED.md` — detailed setup
|
|
558
|
+
- `docs/ARCHITECTURE.md` — from architect report
|
|
559
|
+
- `docs/API.md` — API reference from contracts
|
|
560
|
+
- `docs/DATABASE.md` — schema documentation
|
|
561
|
+
- `docs/DEPLOYMENT.md` — deployment guide
|
|
562
|
+
|
|
563
|
+
3. **Code documentation:**
|
|
564
|
+
- JSDoc/TSDoc for all public functions
|
|
565
|
+
- Inline comments for complex logic
|
|
566
|
+
|
|
567
|
+
4. **User documentation:**
|
|
568
|
+
- Run `/haki:docs --all` to generate user guides with screenshots
|
|
569
|
+
- Output in `.haki/generated/docs/user-guides/`
|
|
570
|
+
|
|
571
|
+
5. **ADRs (Architecture Decision Records):**
|
|
572
|
+
- Extract decisions from `.haki/reports/01-architect.md`
|
|
573
|
+
- Write to `docs/adr/NNN-decision-title.md`
|
|
574
|
+
|
|
575
|
+
**Output:** Write report to `.haki/reports/08-tech-writer.md`
|
|
576
|
+
|
|
577
|
+
#### 🚀 Subagent: DevOps Engineer
|
|
578
|
+
|
|
579
|
+
**Haki skills to read first:**
|
|
580
|
+
- `.agent/skills/verification-before-completion/SKILL.md`
|
|
581
|
+
|
|
582
|
+
**Instructions:**
|
|
583
|
+
|
|
584
|
+
1. **Containerization:**
|
|
585
|
+
- Dockerfile (multi-stage build, non-root user, minimal base image)
|
|
586
|
+
- docker-compose.yml (app + DB + Redis + reverse proxy)
|
|
587
|
+
- `.dockerignore`
|
|
588
|
+
|
|
589
|
+
2. **CI/CD pipeline:**
|
|
590
|
+
- `.github/workflows/ci.yml`:
|
|
591
|
+
- Lint & format check
|
|
592
|
+
- Unit tests + coverage
|
|
593
|
+
- Integration tests (API tests from QA)
|
|
594
|
+
- Security scan (Trivy/Snyk)
|
|
595
|
+
- Build Docker image
|
|
596
|
+
- E2E tests
|
|
597
|
+
- Deploy (staging/production)
|
|
598
|
+
|
|
599
|
+
3. **Environment management:**
|
|
600
|
+
- `.env.example` with all variables documented
|
|
601
|
+
- Environment-specific configs (dev/staging/prod)
|
|
602
|
+
|
|
603
|
+
4. **Monitoring & observability:**
|
|
604
|
+
- Health check endpoints
|
|
605
|
+
- Structured JSON logging config
|
|
606
|
+
- Error tracking setup (Sentry config)
|
|
607
|
+
|
|
608
|
+
5. **Developer scripts:**
|
|
609
|
+
- `scripts/setup.sh` — one-command dev environment setup
|
|
610
|
+
- `scripts/seed.sh` — database seeding
|
|
611
|
+
- `Makefile` with common commands
|
|
612
|
+
|
|
613
|
+
**Output:** Write report to `.haki/reports/09-devops-engineer.md`
|
|
614
|
+
|
|
615
|
+
---
|
|
616
|
+
|
|
617
|
+
## Dashboard Generation
|
|
618
|
+
|
|
619
|
+
After ALL agents complete, generate `.haki/reports/DASHBOARD.md`:
|
|
620
|
+
|
|
621
|
+
```markdown
|
|
622
|
+
# 📊 Swarm Team Dashboard
|
|
623
|
+
|
|
624
|
+
**Project:** [from .haki/PROJECT.md]
|
|
625
|
+
**Generated:** [ISO 8601 timestamp]
|
|
626
|
+
**Overall Status:** 🟢 All Clear | 🟡 Has Warnings | 🔴 Has Blockers
|
|
627
|
+
|
|
628
|
+
---
|
|
629
|
+
|
|
630
|
+
## Team Summary
|
|
631
|
+
|
|
632
|
+
| # | Agent | Status | Tasks | Files Changed | Issues | Duration |
|
|
633
|
+
|---|-------|--------|-------|---------------|--------|----------|
|
|
634
|
+
| 0 | 🔍 Discovery | 🟢 | 4/4 | 4 created | 0 | ~2min |
|
|
635
|
+
| 1 | 📐 Architect | 🟢 | 3/3 | 5 created | 0 | ~3min |
|
|
636
|
+
| 2 | 🔬 Researcher | 🟢 | 1/1 | 1 created | 0 | ~2min |
|
|
637
|
+
| 3 | 🗄️ DB Engineer | 🟢 | 4/4 | 8 created | 1 🟡 | ~3min |
|
|
638
|
+
| 4 | ⚙️ Backend | 🟢 | N/N | X files | 0 | ~Xmin |
|
|
639
|
+
| 5 | 🎨 Frontend | 🟢 | N/N | X files | 0 | ~Xmin |
|
|
640
|
+
| 6 | 🧪 QA | 🟡 | N/N | X files | 2 🟡 | ~Xmin |
|
|
641
|
+
| 7 | 🔒 Security | 🟢 | N/N | X files | 1 🟢 | ~Xmin |
|
|
642
|
+
| 8 | 📝 Docs | 🟢 | N/N | X files | 0 | ~Xmin |
|
|
643
|
+
| 9 | 🚀 DevOps | 🟢 | N/N | X files | 0 | ~Xmin |
|
|
644
|
+
|
|
645
|
+
---
|
|
646
|
+
|
|
647
|
+
## Quality Metrics
|
|
648
|
+
|
|
649
|
+
| Metric | Value | Target | Status |
|
|
650
|
+
|--------|-------|--------|--------|
|
|
651
|
+
| Test coverage | X% | ≥ 80% | ✅/❌ |
|
|
652
|
+
| API tests | X/Y pass | 100% | ✅/❌ |
|
|
653
|
+
| E2E tests | X/Y pass | 100% | ✅/❌ |
|
|
654
|
+
| Security critical | N | 0 | ✅/❌ |
|
|
655
|
+
| Lint errors | N | 0 | ✅/❌ |
|
|
656
|
+
| Docs coverage | X% | 100% | ✅/❌ |
|
|
657
|
+
|
|
658
|
+
---
|
|
659
|
+
|
|
660
|
+
## Open Issues (aggregated from all reports)
|
|
661
|
+
|
|
662
|
+
| # | Agent | Severity | Description | Recommendation |
|
|
663
|
+
|---|-------|----------|-------------|----------------|
|
|
664
|
+
| ... | ... | ... | ... | ... |
|
|
665
|
+
|
|
666
|
+
---
|
|
667
|
+
|
|
668
|
+
## Files Changed (total)
|
|
669
|
+
|
|
670
|
+
- **Created:** [N] files
|
|
671
|
+
- **Modified:** [N] files
|
|
672
|
+
- **Deleted:** [N] files
|
|
673
|
+
|
|
674
|
+
---
|
|
675
|
+
|
|
676
|
+
## Recommendations (top priority)
|
|
677
|
+
|
|
678
|
+
1. [From security report — highest severity first]
|
|
679
|
+
2. [From QA report]
|
|
680
|
+
3. [From architect report]
|
|
681
|
+
|
|
682
|
+
---
|
|
683
|
+
|
|
684
|
+
## Next Steps
|
|
685
|
+
|
|
686
|
+
- [ ] Review all reports in `.haki/reports/`
|
|
687
|
+
- [ ] Address open issues by severity
|
|
688
|
+
- [ ] Run `/haki:next` to continue with remaining ROADMAP tasks
|
|
689
|
+
```
|
|
690
|
+
|
|
691
|
+
---
|
|
692
|
+
|
|
693
|
+
## Invocation
|
|
694
|
+
|
|
695
|
+
### Quick Start (Recommended)
|
|
696
|
+
|
|
697
|
+
For a new project:
|
|
698
|
+
```
|
|
699
|
+
/haki:new-project
|
|
700
|
+
# ... answer questions, get PROJECT.md + ROADMAP.md ...
|
|
701
|
+
# Then:
|
|
702
|
+
/swarm-team
|
|
703
|
+
```
|
|
704
|
+
|
|
705
|
+
For an existing project:
|
|
706
|
+
```
|
|
707
|
+
/haki:map-codebase
|
|
708
|
+
# ... wait for codebase analysis ...
|
|
709
|
+
/haki:new-project
|
|
710
|
+
# ... answer questions ...
|
|
711
|
+
/swarm-team
|
|
712
|
+
```
|
|
713
|
+
|
|
714
|
+
### Full Orchestration Prompt
|
|
715
|
+
|
|
716
|
+
```
|
|
717
|
+
Read `.agent/skills/swarm-dev-team/SKILL.md`.
|
|
718
|
+
|
|
719
|
+
This is a [NEW | EXISTING] project.
|
|
720
|
+
Project: [NAME]
|
|
721
|
+
Description: [DESCRIPTION]
|
|
722
|
+
Tech stack: [TECH STACK or "decide based on requirements"]
|
|
723
|
+
|
|
724
|
+
Execute the full swarm team workflow:
|
|
725
|
+
1. Phase 0: Discovery (if existing project — use /haki:map-codebase)
|
|
726
|
+
2. Phase 1: Architect + Researcher (parallel subagents)
|
|
727
|
+
3. Phase 2: DB Engineer
|
|
728
|
+
4. Phase 3: Backend + Frontend (parallel subagents)
|
|
729
|
+
5. Phase 4: QA + Security (parallel subagents)
|
|
730
|
+
6. Phase 5: Docs + DevOps (parallel subagents)
|
|
731
|
+
7. Generate DASHBOARD.md
|
|
732
|
+
|
|
733
|
+
Every agent MUST:
|
|
734
|
+
- Read its assigned haki skills BEFORE starting work
|
|
735
|
+
- Load context from previous agent reports
|
|
736
|
+
- Follow TDD (test first) for all implementation
|
|
737
|
+
- Write its report to .haki/reports/NN-role.md using the report template
|
|
738
|
+
- Update .haki/tasks/[task-id].md with Implementation Details + Execution Results
|
|
739
|
+
|
|
740
|
+
For brownfield: read .haki/codebase/CONVENTIONS.md and match existing patterns.
|
|
741
|
+
```
|
|
742
|
+
|
|
743
|
+
### Step-by-Step (Manual Control)
|
|
744
|
+
|
|
745
|
+
If you prefer to run each phase manually with review between phases:
|
|
746
|
+
|
|
747
|
+
```bash
|
|
748
|
+
# Phase 0 (brownfield only)
|
|
749
|
+
/haki:map-codebase
|
|
750
|
+
|
|
751
|
+
# Phase 1 — parallel
|
|
752
|
+
# Subagent 1: "You are SYSTEM ARCHITECT. Read .agent/skills/swarm-dev-team/SKILL.md Phase 1 Architect section. Load .haki/PROJECT.md and .haki/ROADMAP.md. Write report to .haki/reports/01-architect.md"
|
|
753
|
+
# Subagent 2: "You are TECH RESEARCHER. Run /haki:research for the full tech stack. Write report to .haki/reports/02-researcher.md"
|
|
754
|
+
|
|
755
|
+
# Review Phase 1 reports before continuing...
|
|
756
|
+
|
|
757
|
+
# Phase 2
|
|
758
|
+
# "You are DB ENGINEER. Read .agent/skills/swarm-dev-team/SKILL.md Phase 2. Load reports 01 and 02. Write report to .haki/reports/03-db-engineer.md"
|
|
759
|
+
|
|
760
|
+
# Phase 3 — parallel
|
|
761
|
+
# Subagent 1: "You are BACKEND DEVELOPER. Read .agent/skills/swarm-dev-team/SKILL.md Phase 3 Backend section..."
|
|
762
|
+
# Subagent 2: "You are FRONTEND DEVELOPER. Read .agent/skills/swarm-dev-team/SKILL.md Phase 3 Frontend section..."
|
|
763
|
+
|
|
764
|
+
# Phase 4 — parallel
|
|
765
|
+
# Subagent 1: "You are QA ENGINEER. Use /haki:api-test and /haki:e2e workflows..."
|
|
766
|
+
# Subagent 2: "You are SECURITY ENGINEER..."
|
|
767
|
+
|
|
768
|
+
# Phase 5 — parallel
|
|
769
|
+
# Subagent 1: "You are TECHNICAL WRITER. Use /haki:docs --all..."
|
|
770
|
+
# Subagent 2: "You are DEVOPS ENGINEER..."
|
|
771
|
+
|
|
772
|
+
# Generate dashboard
|
|
773
|
+
# "Read all .haki/reports/*.md and generate .haki/reports/DASHBOARD.md using the dashboard template from the skill."
|
|
774
|
+
```
|
|
775
|
+
|
|
776
|
+
---
|
|
777
|
+
|
|
778
|
+
## Integration with Haki State Machine
|
|
779
|
+
|
|
780
|
+
This skill integrates with haki's existing state machine:
|
|
781
|
+
|
|
782
|
+
| Haki State | Swarm Action |
|
|
783
|
+
|------------|-------------|
|
|
784
|
+
| No `.haki/` | Run `/haki:new-project` first |
|
|
785
|
+
| Has PROJECT.md, no ROADMAP | Run `/haki:new-project` to completion |
|
|
786
|
+
| Has ROADMAP, tasks ⏳ Pending | Run `/haki:discuss` per task, then swarm |
|
|
787
|
+
| Has ROADMAP, tasks 💬 Discussed | Run `/haki:plan` per task, then swarm |
|
|
788
|
+
| Has ROADMAP, tasks 📋 Planned | **Ready for swarm** — run `/swarm-team` |
|
|
789
|
+
| All tasks ✅ Complete | Run `/haki:new-milestone` for next phase |
|
|
790
|
+
|
|
791
|
+
The swarm skill does NOT replace haki workflows — it **orchestrates them at scale** by assigning specialized roles to subagents and adding a reporting layer.
|
|
792
|
+
|
|
793
|
+
---
|
|
794
|
+
|
|
795
|
+
## Quality Gates
|
|
796
|
+
|
|
797
|
+
Each phase must pass before the next begins:
|
|
798
|
+
|
|
799
|
+
| Phase | Gate | Criteria |
|
|
800
|
+
|-------|------|----------|
|
|
801
|
+
| 0 Discovery | ✅ Codebase Mapped | All 4 codebase docs exist in `.haki/codebase/` |
|
|
802
|
+
| 1 Architecture | ✅ Design Complete | API contracts defined, architecture documented |
|
|
803
|
+
| 1 Research | ✅ Stack Verified | All libraries verified via Context7 |
|
|
804
|
+
| 2 Database | ✅ Schema Ready | Migrations run successfully, seeds load |
|
|
805
|
+
| 3 Backend | ✅ APIs Working | All endpoints match contract, tests pass |
|
|
806
|
+
| 3 Frontend | ✅ UI Functional | Components render, responsive, accessible |
|
|
807
|
+
| 4 QA | ✅ Coverage Met | ≥ 80% unit, API tests pass, E2E pass |
|
|
808
|
+
| 4 Security | ✅ No Criticals | Zero critical/high severity findings |
|
|
809
|
+
| 5 Docs | ✅ Docs Complete | README + API docs + user guides exist |
|
|
810
|
+
| 5 DevOps | ✅ Pipeline Green | CI/CD runs end-to-end successfully |
|