create-hivemind-protocol 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/CLAUDE.md +229 -0
  2. package/LICENSE +674 -0
  3. package/README.md +214 -0
  4. package/agents/01-cto.md +121 -0
  5. package/agents/02-lead-dev.md +123 -0
  6. package/agents/03-product-manager.md +127 -0
  7. package/agents/04-backend-dev.md +130 -0
  8. package/agents/05-frontend-dev.md +129 -0
  9. package/agents/06-devops.md +133 -0
  10. package/agents/07-security.md +143 -0
  11. package/agents/08-qa.md +140 -0
  12. package/agents/09-data.md +104 -0
  13. package/agents/10-docs.md +109 -0
  14. package/agents/11-mobile.md +87 -0
  15. package/agents/12-ai-ml.md +107 -0
  16. package/agents/_AGENT_TEMPLATE.md +115 -0
  17. package/assets/logo.png +0 -0
  18. package/bin/create.js +67 -0
  19. package/memory/agent-states/_STATE_TEMPLATE.md +24 -0
  20. package/memory/agent-states/ai-ml.state.md +19 -0
  21. package/memory/agent-states/backend-dev.state.md +19 -0
  22. package/memory/agent-states/cto.state.md +30 -0
  23. package/memory/agent-states/data.state.md +19 -0
  24. package/memory/agent-states/devops.state.md +19 -0
  25. package/memory/agent-states/docs.state.md +19 -0
  26. package/memory/agent-states/frontend-dev.state.md +19 -0
  27. package/memory/agent-states/lead-dev.state.md +19 -0
  28. package/memory/agent-states/mobile.state.md +19 -0
  29. package/memory/agent-states/product-manager.state.md +19 -0
  30. package/memory/agent-states/qa.state.md +19 -0
  31. package/memory/agent-states/security.state.md +19 -0
  32. package/memory/blockers.md +36 -0
  33. package/memory/decisions.log +14 -0
  34. package/memory/handoff-queue.md +17 -0
  35. package/memory/shared-context.md +65 -0
  36. package/package.json +40 -0
  37. package/project.json +298 -0
  38. package/reports/CHANGELOG.md +32 -0
  39. package/reports/audit-log.md +33 -0
  40. package/reports/sprint-report.md +63 -0
  41. package/tools/code-boundaries.md +86 -0
  42. package/tools/custom-commands.md +324 -0
  43. package/tools/mcp-catalog.md +114 -0
  44. package/tools/scaffold-templates/fastapi.md +61 -0
  45. package/tools/scaffold-templates/monorepo.md +29 -0
  46. package/tools/scaffold-templates/nextjs.md +70 -0
  47. package/tools/scaffold-templates/node-api.md +32 -0
  48. package/tools/scaffold-templates/react-native.md +30 -0
  49. package/tools/token-railguards.md +262 -0
package/tools/scaffold-templates/monorepo.md ADDED
@@ -0,0 +1,29 @@
1
+ # Scaffold Template: Monorepo (Turborepo)
2
+
3
+ > Triggered by `/scaffold monorepo --name <name>`
4
+
5
+ ## Directory Structure
6
+
7
+ ```
8
+ <name>/
9
+ ├── apps/
10
+ │ ├── web/ ← Next.js frontend
11
+ │ └── api/ ← Node.js or FastAPI backend
12
+ ├── packages/
13
+ │ ├── ui/ ← shared component library
14
+ │ ├── types/ ← shared TypeScript types
15
+ │ ├── config/ ← shared ESLint, TSConfig, etc.
16
+ │ └── utils/ ← shared utility functions
17
+ ├── turbo.json
18
+ ├── package.json ← root workspace
19
+ ├── pnpm-workspace.yaml
20
+ └── .env.example
21
+ ```
22
+
23
+ ## Conventions
24
+ - pnpm workspaces for package management
25
+ - Turborepo for build/task orchestration
26
+ - Shared types live in `packages/types` — imported by both apps
27
+ - UI components in `packages/ui` — no business logic
28
+ - Each app has its own `.env.local` (not shared)
29
+ - Run `turbo dev` to start all apps in parallel
package/tools/scaffold-templates/nextjs.md ADDED
@@ -0,0 +1,70 @@
1
+ # Scaffold Template: Next.js 14+ (App Router)
2
+
3
+ > Triggered by `/scaffold nextjs --name <name>`
4
+
5
+ ## Directory Structure
6
+
7
+ ```
8
+ <name>/
9
+ ├── app/
10
+ │ ├── layout.tsx
11
+ │ ├── page.tsx
12
+ │ ├── globals.css
13
+ │ └── (routes)/
14
+ │ └── [feature]/
15
+ │ ├── page.tsx
16
+ │ └── loading.tsx
17
+ ├── components/
18
+ │ ├── ui/ ← shadcn/ui or custom primitives
19
+ │ └── features/ ← feature-specific components
20
+ ├── lib/
21
+ │ ├── api.ts ← API client (fetch wrapper)
22
+ │ ├── auth.ts ← auth helpers
23
+ │ └── utils.ts
24
+ ├── hooks/ ← custom React hooks
25
+ ├── types/ ← shared TypeScript types
26
+ ├── public/
27
+ ├── .env.example
28
+ ├── .env.local ← gitignored
29
+ ├── next.config.ts
30
+ ├── tsconfig.json
31
+ ├── tailwind.config.ts
32
+ └── package.json
33
+ ```
34
+
35
+ ## Key Files
36
+
37
+ ### `app/layout.tsx`
38
+ ```tsx
39
+ import type { Metadata } from "next";
40
+ import { Inter } from "next/font/google";
41
+ import "./globals.css";
42
+
43
+ const inter = Inter({ subsets: ["latin"] });
44
+
45
+ export const metadata: Metadata = {
46
+ title: "<name>",
47
+ description: "",
48
+ };
49
+
50
+ export default function RootLayout({ children }: { children: React.ReactNode }) {
51
+ return (
52
+ <html lang="en">
53
+ <body className={inter.className}>{children}</body>
54
+ </html>
55
+ );
56
+ }
57
+ ```
58
+
59
+ ### `.env.example`
60
+ ```
61
+ NEXT_PUBLIC_API_URL=http://localhost:3001
62
+ AUTH_SECRET=
63
+ DATABASE_URL=
64
+ ```
65
+
66
+ ## Conventions
67
+ - Use Server Components by default; add `"use client"` only when needed
68
+ - Route handlers in `app/api/<route>/route.ts`
69
+ - Data fetching in Server Components, not in client hooks
70
+ - Forms use Server Actions or API routes — not direct client fetch
package/tools/scaffold-templates/node-api.md ADDED
@@ -0,0 +1,32 @@
1
+ # Scaffold Template: Node.js API (Express + TypeScript)
2
+
3
+ > Triggered by `/scaffold node-api --name <name>`
4
+
5
+ ## Directory Structure
6
+
7
+ ```
8
+ <name>/
9
+ ├── src/
10
+ │ ├── index.ts ← entry point
11
+ │ ├── app.ts ← Express app setup
12
+ │ ├── config/
13
+ │ ├── routes/
14
+ │ ├── controllers/
15
+ │ ├── services/
16
+ │ ├── models/
17
+ │ ├── middleware/
18
+ │ ├── utils/
19
+ │ └── types/
20
+ ├── tests/
21
+ ├── .env.example
22
+ ├── tsconfig.json
23
+ ├── package.json
24
+ └── Dockerfile
25
+ ```
26
+
27
+ ## Conventions
28
+ - Strict TypeScript — no `any`
29
+ - Zod for all request validation at route level
30
+ - Services contain business logic; controllers are thin
31
+ - Errors extend a base `AppError` class
32
+ - JWT in HttpOnly cookies, not Authorization header
package/tools/scaffold-templates/react-native.md ADDED
@@ -0,0 +1,30 @@
1
+ # Scaffold Template: React Native (Expo)
2
+
3
+ > Triggered by `/scaffold react-native --name <name>`
4
+
5
+ ## Directory Structure
6
+
7
+ ```
8
+ <name>/
9
+ ├── app/ ← Expo Router file-based routing
10
+ │ ├── (tabs)/
11
+ │ ├── _layout.tsx
12
+ │ └── index.tsx
13
+ ├── components/
14
+ ├── hooks/
15
+ ├── lib/
16
+ │ ├── api.ts
17
+ │ └── storage.ts ← expo-secure-store wrapper
18
+ ├── types/
19
+ ├── assets/
20
+ ├── app.json
21
+ ├── eas.json
22
+ └── package.json
23
+ ```
24
+
25
+ ## Conventions
26
+ - Use Expo Router for navigation
27
+ - SecureStore for sensitive data (tokens, keys) — never AsyncStorage for secrets
28
+ - expo-image for optimized image loading
29
+ - Zod for API response validation
30
+ - EAS Build for CI/CD
package/tools/token-railguards.md ADDED
@@ -0,0 +1,262 @@
1
+ # Token Railguards
2
+
3
+ > Rules and patterns to prevent token waste, infinite loops, and runaway AI costs.
4
+ > Inspired by [caveman](https://github.com/JuliusBrussee/caveman) — terse like smart caveman. Technical substance stay. Only fluff die.
5
+ >
6
+ > These rules apply to ALL agents. Violations must be logged in `memory/blockers.md`.
7
+
8
+ ---
9
+
10
+ ## Why This Matters
11
+
12
+ Token costs cascade in multi-agent systems:
13
+ - Verbose output from agent A becomes input to agent B becomes input to agent C
14
+ - Each hop multiplies cost: a 1,000-token verbose response × 10 agent hops = 10,000 tokens of overhead
15
+ - Output tokens cost ~1.25–6× input tokens depending on the model
16
+ - Brevity constraints don't sacrifice quality — they **improve accuracy** by reducing hallucination surface area (see [research](https://github.com/JuliusBrussee/caveman))
17
+
18
+ Target: **65-75% output token reduction** via compression + **~46% input reduction** via memory compression.
19
+
20
+ ---
21
+
22
+ ## 1. Output Communication Protocol (Caveman Rules)
23
+
24
+ All agent responses follow these 10 rules. Technical substance is always preserved exactly.
25
+
26
+ ### The 10 Rules
27
+
28
+ | # | Rule | Bad (wasteful) | Good (terse) |
29
+ |---|------|----------------|-------------|
30
+ | 1 | **No filler phrases** | "I'll just go ahead and basically fix this" | "Fixed." |
31
+ | 2 | **Execute before explaining** | "I'll now read the file to understand..." | [reads file, then reports finding] |
32
+ | 3 | **No meta-commentary** | "I'll start by looking at the auth module" | [looks at auth module] |
33
+ | 4 | **No preamble** | "Sure! I'd be happy to help you with that." | [does the thing] |
34
+ | 5 | **No postamble** | "Let me know if you need anything else!" | [silence] |
35
+ | 6 | **No tool announcements** | "I'm now going to run the tests..." | [runs tests] |
36
+ | 7 | **Explain only when needed** | Explain every line of obvious code | Explain only non-obvious logic |
37
+ | 8 | **Let code speak** | Paraphrase what code does in prose | Show the code |
38
+ | 9 | **Errors: fix, don't narrate** | "I see an error occurred. Let me investigate..." | [fixes error] |
39
+ | 10 | **Drop hedging** | "It might potentially be possible that..." | "Yes." / "No." / state the fact |
40
+
41
+ **Response pattern**: `[thing] [action] [reason]. [next step].`
42
+
43
+ Drop: `a`, `an`, `the`, `just`, `really`, `basically`, `actually`, `simply`, `sure`, `certainly`, `of course`, `I'll`, `Let me`, `going to`, `I think`, `perhaps`, `might`, `could potentially`.
44
+
45
+ ---
46
+
47
+ ## 2. Compression Intensity Levels
48
+
49
+ Agents select compression level based on context. Configure default in `project.json > communication.default_intensity`.
50
+
51
+ | Level | Token reduction | Rules |
52
+ |-------|----------------|-------|
53
+ | **lite** | ~40% | Keep articles; full sentences OK; drop filler only |
54
+ | **full** | ~60% | Drop articles; fragments allowed; no pleasantries |
55
+ | **ultra** | ~75% | Use abbreviations (DB, auth, cfg, deps); arrows for causality (`→`); max compression |
56
+
57
+ ### When to use each level
58
+
59
+ ```
60
+ lite → human-facing explanations, user-visible output, onboarding
61
+ full → standard agent-to-agent communication (default)
62
+ ultra → internal chains, memory updates, log entries, status checks
63
+ ```
64
+
65
+ ### Auto-Clarity Exception (mandatory)
66
+
67
+ **Suspend all compression** for:
68
+ - Security warnings (severity HIGH or CRITICAL)
69
+ - Irreversible operation confirmations (DROP, DELETE, rm -rf, force push)
70
+ - Multi-step sequences where fragment order could cause misunderstanding
71
+ - Escalations to the user
72
+
73
+ Resume compression after the critical section completes.
74
+
75
+ ```
76
+ # Example: destructive op requires full clarity
77
+ [SECURITY ESCALATION — COMPRESSION SUSPENDED]
78
+ This operation will permanently delete the production database.
79
+ It cannot be undone. All user data will be lost.
80
+ Please confirm explicitly before proceeding.
81
+ [COMPRESSION RESUMED]
82
+ ```
83
+
84
+ ---
85
+
86
+ ## 3. Model Selection (Cost Control)
87
+
88
+ Always use cheapest model for the job. Refer to `project.json > routing`.
89
+
90
+ ```
91
+ Lite (Haiku) → Reading, logging, formatting, status, reports
92
+ Standard (Sonnet) → Writing code, debugging, API design, tests
93
+ Heavy (Opus) → Architecture, security audits, complex cross-system design
94
+ ```
95
+
96
+ **Relative cost ratios** (approximate):
97
+ - Lite: 1×
98
+ - Standard: ~15×
99
+ - Heavy: ~75×
100
+
101
+ **Never use Heavy when Standard works. Never use Standard when Lite works.**
102
+
103
+ ---
104
+
105
+ ## 4. Memory File Compression (Input Token Reduction)
106
+
107
+ Every agent session re-reads memory files from disk. A 1,000-token `shared-context.md` × 100 sessions = 100,000 tokens of unnecessary input cost.
108
+
109
+ **Solution**: Keep memory files in compressed caveman-style prose. ~46% input reduction per session.
110
+
111
+ ### Memory compression rules
112
+
113
+ When writing to any memory file, apply these:
114
+
115
+ ```
116
+ # DROP from memory entries:
117
+ - Articles: a, an, the
118
+ - Filler: just, really, basically, actually, simply
119
+ - Hedging: might, could, possibly, perhaps
120
+ - Meta-phrases: "It is worth noting that...", "As mentioned above..."
121
+ - Redundant context: don't repeat what's already in the file header
122
+
123
+ # PRESERVE exactly:
124
+ - Code blocks (fenced and indented)
125
+ - Inline code (`backtick content`)
126
+ - File paths (/src/components/...)
127
+ - URLs and links
128
+ - Technical terms, library names, API names
129
+ - Dates, version numbers, model IDs
130
+ - Headings and structural markers
131
+ - Bullet points and list structure
132
+ ```
133
+
134
+ ### Memory write examples
135
+
136
+ ```markdown
137
+ # BAD (verbose):
138
+ [2026-04-15 14:30] [backend-dev] DECISION: After careful consideration
139
+ and reviewing the existing codebase, I have decided that it would be
140
+ best to use Zod for runtime validation across all of the API boundaries
141
+ because it provides better TypeScript integration | REASON: The current
142
+ approach of manual type guards is leading to inconsistencies
143
+
144
+ # GOOD (compressed, ~60% fewer tokens):
145
+ [2026-04-15 14:30] [backend-dev] DECISION: Use Zod for runtime validation
146
+ at all API boundaries | REASON: Manual type guards → inconsistencies; Zod →
147
+ better TS integration
148
+ ```
149
+
150
+ ---
151
+
152
+ ## 5. Loop Prevention
153
+
154
+ ### Hard limits
155
+ - Max **3 attempts** on same approach → stop, escalate to blockers
156
+ - Max **5 iterations** over same file in one session
157
+ - Max **3 levels** of agent delegation depth (A → B → C → stop)
158
+
159
+ ### Loop detection — before retrying, check:
160
+ 1. Is this the exact same approach as last attempt?
161
+ 2. Is the error different from last time?
162
+ 3. Do I have new information?
163
+
164
+ If all NO → stop immediately. Log to `memory/blockers.md`. Escalate.
165
+
166
+ ### Anti-patterns
167
+
168
+ ```
169
+ # BAD: blind retry
170
+ while not success:
171
+ try_same_thing()
172
+
173
+ # GOOD: bounded retry with escalation
174
+ for attempt in range(3):
175
+ result = try_approach(attempt)
176
+ if result.success: break
177
+ log_failure(attempt, result.error)
178
+ else:
179
+ escalate_to_blockers()
180
+ ```
181
+
182
+ ---
183
+
184
+ ## 6. Context Window Conservation
185
+
186
+ ### Do NOT read unnecessarily
187
+ - Don't read file just to confirm existence → use glob/search
188
+ - Don't re-read file already read this session → use your context
189
+ - Don't read full large files for a single section → use offset/limit
190
+ - Don't read test files unless writing or debugging tests
191
+ - Don't read config files unless directly relevant
192
+
193
+ ### Do NOT write unnecessarily
194
+ - No boilerplate "just in case"
195
+ - No comments on code you didn't change
196
+ - No fallback handlers for impossible scenarios
197
+ - No helper functions for one-time use
198
+ - No type annotations on untouched code
199
+ - No extra files "for the future"
200
+
201
+ ---
202
+
203
+ ## 7. Session Length Management
204
+
205
+ When a session is growing long (many tool calls, many iterations):
206
+
207
+ 1. Write state to `memory/agent-states/<role>.state.md` (compressed)
208
+ 2. Write pending items to `memory/handoff-queue.md`
209
+ 3. Log progress in `reports/CHANGELOG.md`
210
+ 4. **End session. Start fresh.**
211
+
212
+ Long sessions degrade quality and pay for repeated context. Brevity + frequent commits beats verbose marathons.
213
+
214
+ ---
215
+
216
+ ## 8. Batch Operation Protocol
217
+
218
+ Before bulk ops (mass file edits, large DB queries):
219
+
220
+ 1. Log intent in `memory/decisions.log`
221
+ 2. Test on single item first
222
+ 3. Confirm result is correct
223
+ 4. User confirmation required for 10+ files
224
+
225
+ ---
226
+
227
+ ## 9. Forbidden Patterns (Immediate Stop)
228
+
229
+ Stop and log to `memory/blockers.md` on any of:
230
+
231
+ ```bash
232
+ rm -rf / # or dangerous rm
233
+ DROP DATABASE # unqualified destructive SQL
234
+ git push --force main # force push to main/master
235
+ while true; do # infinite loop
236
+ SELECT * FROM big_table # without LIMIT
237
+ ```
238
+
239
+ Full list: `project.json > railguards.forbidden_operations`
240
+
241
+ ---
242
+
243
+ ## 10. Escalation Thresholds
244
+
245
+ Auto-escalate (don't keep trying) when:
246
+ - Same error 3× in a row
247
+ - Task in handoff-queue 2+ sessions without progress
248
+ - Token usage for single task exceeds `project.json > routing.<tier>.max_tokens`
249
+ - Blocker OPEN for 1+ sprint
250
+
251
+ ---
252
+
253
+ ## Quick Reference Card
254
+
255
+ ```
256
+ OUTPUT: terse. no filler. execute first. code > prose. errors → fix.
257
+ MODEL: lite=reads/logs standard=code heavy=architecture
258
+ LOOP: 3 attempts max → blocker → escalate
259
+ MEMORY: compressed prose. append only. preserve code/paths/URLs.
260
+ CONTEXT: read only what's needed. write only what was asked.
261
+ CRITICAL: suspend compression for security + destructive ops.
262
+ ```