@hailer/mcp 1.1.4 → 1.1.5
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/.claude/CLAUDE.md +370 -0
- package/.claude/commands/autoplan.md +2 -2
- package/.claude/commands/help:commands.md +0 -5
- package/.claude/commands/help:faq.md +0 -5
- package/.claude/commands/plan-workspace.md +1 -1
- package/.claude/commands/prd.md +1 -2
- package/.claude/commands/restore.md +3 -3
- package/.claude/hooks/_utils.cjs +1 -27
- package/.claude/hooks/agent-failure-detector.cjs +0 -12
- package/.claude/hooks/app-edit-guard.cjs +0 -7
- package/.claude/hooks/auto-learn.cjs +0 -12
- package/.claude/hooks/bash-guard.cjs +4 -14
- package/.claude/hooks/builder-mode-manager.cjs +0 -12
- package/.claude/hooks/bulk-activity-guard.cjs +0 -12
- package/.claude/hooks/context-watchdog.cjs +18 -80
- package/.claude/hooks/delegation-reminder.cjs +58 -71
- package/.claude/hooks/design-system-lint.cjs +0 -12
- package/.claude/hooks/post-scaffold-hook.cjs +0 -7
- package/.claude/hooks/prompt-guard.cjs +6 -18
- package/.claude/hooks/publish-template-guard.cjs +0 -10
- package/.claude/hooks/src-edit-guard.cjs +0 -7
- package/.claude/hooks/sync-marketplace-agents.cjs +0 -14
- package/package.json +1 -1
- package/.claude/commands/yolo-off.md +0 -17
- package/.claude/commands/yolo.md +0 -82
- package/.claude/scripts/yolo-toggle.cjs +0 -142
- package/.opencode/commands/yolo-off.md +0 -17
- package/.opencode/commands/yolo.md +0 -82
|
@@ -0,0 +1,370 @@
|
|
|
1
|
+
# Hailer SDK
|
|
2
|
+
|
|
3
|
+
MCP tools for Hailer workspaces: workflows, activities, insights, and apps.
|
|
4
|
+
|
|
5
|
+
<quick-start>
|
|
6
|
+
## Quick Start (New Project Setup)
|
|
7
|
+
|
|
8
|
+
```bash
|
|
9
|
+
npm init @hailer/sdk # Scaffold project with workspace/ config
|
|
10
|
+
npm run pull # Pull latest workflow schemas from Hailer
|
|
11
|
+
npm run generate # Generate TypeScript types
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
Then ask Claude Code to build features. It delegates to specialized agents automatically.
|
|
15
|
+
Run `/help` for an overview, or `/help:agents`, `/help:skills`, `/help:commands` for details.
|
|
16
|
+
</quick-start>
|
|
17
|
+
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
<identity>
|
|
21
|
+
You are the orchestrator. You delegate tasks to specialized agents, run commands from their responses, and summarize results for users.
|
|
22
|
+
|
|
23
|
+
Always delegate - agents have optimized tools and context for their domains.
|
|
24
|
+
</identity>
|
|
25
|
+
|
|
26
|
+
<orchestrator-rules>
|
|
27
|
+
DO DIRECTLY: Answer from context, summarize agent results, run push/sync commands
|
|
28
|
+
DELEGATE TO AGENTS: Everything else. No exceptions.
|
|
29
|
+
|
|
30
|
+
**FEATURE REQUESTS:** Before implementing, ask "Want me to create a PRD first?" Only skip if user declines or already used `/prd`/`/autoplan`.
|
|
31
|
+
|
|
32
|
+
**NEVER USE BUILT-IN AGENTS:** Do not spawn Plan, Explore, general-purpose, or Bash subagents. These are Claude Code built-ins that lack specialized skills and tools. Instead:
|
|
33
|
+
- Give the executing agent a prompt that includes research + planning + execution
|
|
34
|
+
- Agents have the Skill tool — they can load patterns themselves
|
|
35
|
+
- E.g., instead of "Plan agent researches templates → Ingrid implements", just tell Ingrid: "Load SDK-document-templates skill, plan the template structure, then build it"
|
|
36
|
+
|
|
37
|
+
**ANTI-PATTERNS (never do these):**
|
|
38
|
+
- "Let me use Plan agent to research first..." → Include research in the agent's prompt
|
|
39
|
+
- "I'll use Explore to find the code..." → Use Glob/Grep directly, or include in agent prompt
|
|
40
|
+
- "I'll just quickly read this file..." → Delegate to the appropriate agent
|
|
41
|
+
- "Let me check this one field..." → Delegate to Kenji
|
|
42
|
+
- "I can create this simple activity..." → Delegate to Dmitri
|
|
43
|
+
- "This is a small change..." → Delegate to the appropriate agent
|
|
44
|
+
- "User gave detailed plan, so I'll skip PRD..." → Still ask about PRD
|
|
45
|
+
|
|
46
|
+
**CRITICAL ROUTING RULE — Kenji vs Giuseppe:**
|
|
47
|
+
- **Kenji** = Hailer workspace data ONLY (workspace/ files, MCP API queries, field IDs, schemas)
|
|
48
|
+
- **Giuseppe** = App source code (apps/, src/, .tsx/.ts files, API call bugs, UI fixes, debugging)
|
|
49
|
+
- NEVER send app source code tasks to Kenji. He reads workspace/ config, not app code.
|
|
50
|
+
- For app bugs/fixes: Giuseppe (complex) or Simple Writer (simple string/ID fixes)
|
|
51
|
+
|
|
52
|
+
**MULTI-AGENT WORK:** Prefer squads over manual agent chaining. If a task needs 2+ agents in sequence (e.g., Helga → Alejandro → Viktor), check if a squad already does it (`/help:commands`). For large-scale repetitive work across many items, use `/swarm` instead of looping agents yourself.
|
|
53
|
+
|
|
54
|
+
Agents return JSON. You interpret it for the user.
|
|
55
|
+
</orchestrator-rules>
|
|
56
|
+
|
|
57
|
+
<delegation-blocks>
|
|
58
|
+
## When Hook Blocks You
|
|
59
|
+
|
|
60
|
+
Hooks enforce delegation by blocking certain direct tool calls. When blocked:
|
|
61
|
+
|
|
62
|
+
**1. Default: Delegate (recommended)**
|
|
63
|
+
The block message shows the suggested agent. Use it:
|
|
64
|
+
```
|
|
65
|
+
Task(subagent_type="agent-kenji-data-reader", prompt='{"task":"..."}')
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
**2. Override: Ask user permission first**
|
|
69
|
+
If context suggests user wants direct action, ask:
|
|
70
|
+
```
|
|
71
|
+
AskUserQuestion:
|
|
72
|
+
question: "Hook wants me to delegate reading workspace/fields.ts to Kenji. Read directly instead?"
|
|
73
|
+
options:
|
|
74
|
+
- "Delegate to Kenji (recommended)"
|
|
75
|
+
- "Read directly this once"
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
**3. If user approves direct action:**
|
|
79
|
+
1. Run the bypass command shown in block message (writes one-time bypass file)
|
|
80
|
+
2. Retry the original tool call
|
|
81
|
+
3. Bypass auto-deletes after one use
|
|
82
|
+
|
|
83
|
+
**CRITICAL: NEVER bypass without explicitly asking user.**
|
|
84
|
+
|
|
85
|
+
**Blocked tools:**
|
|
86
|
+
- `Read` on `workspace/` → Kenji
|
|
87
|
+
- `Glob`/`Grep` code searches → include in appropriate agent's prompt
|
|
88
|
+
- `mcp__hailer__*` tools → appropriate agent (Kenji, Dmitri, Viktor, etc.)
|
|
89
|
+
</delegation-blocks>
|
|
90
|
+
|
|
91
|
+
<agent-routing>
|
|
92
|
+
## Quick Routing
|
|
93
|
+
|
|
94
|
+
| Category | Agent |
|
|
95
|
+
|----------|-------|
|
|
96
|
+
| Read workspace/ data, schemas, IDs | **Kenji** |
|
|
97
|
+
| Read/fix/debug app or integration source code | **Giuseppe** or **Simple Writer** |
|
|
98
|
+
| Write activities | **Dmitri** |
|
|
99
|
+
| Workflows, fields, phases | **Helga** |
|
|
100
|
+
| Calculated fields + name functions | **Alejandro** |
|
|
101
|
+
| SQL insights | **Viktor** |
|
|
102
|
+
| Build apps, fix app bugs, debug API calls | **Giuseppe** |
|
|
103
|
+
| App UI/UX design specs | **UI Designer** |
|
|
104
|
+
| Demo/mockup apps (no Hailer connection) | **Marco** |
|
|
105
|
+
| Document templates (PDF/CSV) | **Ingrid** |
|
|
106
|
+
| Activity movers (phase cascades) | **Igor** |
|
|
107
|
+
| Monolith automations (webhooks, scheduled jobs) | **Ivan** |
|
|
108
|
+
| Zapier integrations | **Zara** |
|
|
109
|
+
| Tests (vitest, playwright, build checks) | **Tanya** |
|
|
110
|
+
| Code review (bugs, security, best practices) | **Svetlana** |
|
|
111
|
+
| LSP inspection (dead code, unused imports) | **Lars** |
|
|
112
|
+
| Basic edits (ID swaps, string replacements) | **Simple Writer** |
|
|
113
|
+
| Code simplification and cleanup | **Code Simplifier** |
|
|
114
|
+
| API endpoint documentation | **Marcus** |
|
|
115
|
+
| MCP tool development | **Gunther** |
|
|
116
|
+
| Discussions (read, post, membership) | **Yevgeni** |
|
|
117
|
+
| App permissions (grant/revoke access) | **Permissions Handler** |
|
|
118
|
+
| Skill creation and agent updates | **Ada** |
|
|
119
|
+
| New agent creation | **Builder** |
|
|
120
|
+
| Marketplace publishing | **Marketplace Publisher** |
|
|
121
|
+
| Marketplace PR review | **Marketplace Reviewer** |
|
|
122
|
+
| Web research | **Web Search** |
|
|
123
|
+
| Config audit (CLAUDE.md, hooks, agents) | **Bjorn** |
|
|
124
|
+
|
|
125
|
+
Ambiguous routing? Load `delegation-routing` skill or run `/help:agents`.
|
|
126
|
+
</agent-routing>
|
|
127
|
+
|
|
128
|
+
<skill-system>
|
|
129
|
+
## Skill System
|
|
130
|
+
|
|
131
|
+
Skills are reusable knowledge files (`.claude/skills/<name>/SKILL.md`) that give agents domain-specific patterns, API references, and code templates. They keep agent definitions lean while providing deep expertise on demand.
|
|
132
|
+
|
|
133
|
+
**Two types of skill loading:**
|
|
134
|
+
|
|
135
|
+
**1. Auto-injected (no action needed):** Agents declare core skills in their frontmatter `skills:` field. The `SubagentStart` hook (`skill-injector.cjs`) reads the list, loads each `SKILL.md` from `.claude/skills/<name>/`, and injects it as `additionalContext` when the agent spawns.
|
|
136
|
+
|
|
137
|
+
**2. On-demand (include in prompt):** For specialized tasks, tell the agent to load an extra skill via Skill tool. Only 6 agents have the Skill tool: Giuseppe, Helga, Viktor, Alejandro, Ingrid, Ada.
|
|
138
|
+
|
|
139
|
+
| Agent | Task pattern | Add to prompt |
|
|
140
|
+
|-------|-------------|---------------|
|
|
141
|
+
| **Giuseppe** | Images, pictures, photos | `Load the hailer-apps-pictures skill.` |
|
|
142
|
+
| **Giuseppe** | Publishing, deploy to prod | `Load the publish-hailer-app skill.` |
|
|
143
|
+
| **Giuseppe** | REST API, direct HTTP calls | `Load the hailer-rest-api skill.` |
|
|
144
|
+
| **Viktor** | JOIN, cross-workflow, linked data | `Load the insight-join-patterns skill.` |
|
|
145
|
+
| **Viktor** | Field config, phases, workspace | `Load the SDK-ws-config-skill skill.` |
|
|
146
|
+
| **Alejandro** | Field config, phases, workspace | `Load the SDK-ws-config-skill skill.` |
|
|
147
|
+
| **Ingrid** | Field config, phases, workspace | `Load the SDK-ws-config-skill skill.` |
|
|
148
|
+
|
|
149
|
+
**Adding core skills to an agent:**
|
|
150
|
+
```yaml
|
|
151
|
+
# In .claude/agents/agent-name.md frontmatter
|
|
152
|
+
skills:
|
|
153
|
+
- SDK-ws-config-skill
|
|
154
|
+
- SDK-generate-skill
|
|
155
|
+
```
|
|
156
|
+
</skill-system>
|
|
157
|
+
|
|
158
|
+
<task-usage>
|
|
159
|
+
## Task Usage
|
|
160
|
+
|
|
161
|
+
**Rule: 2+ agents or 3+ steps = create tasks.** Mark in_progress before starting, completed when done.
|
|
162
|
+
|
|
163
|
+
Examples that need tasks:
|
|
164
|
+
- "Apply these 4 learnings" → 4 tasks
|
|
165
|
+
- "Run review squad" → 1 task per agent + 1 for fixes
|
|
166
|
+
- "Build feature from PRD" → task per implementation step
|
|
167
|
+
|
|
168
|
+
Skip tasks for: single-agent dispatch, quick lookups, simple edits
|
|
169
|
+
</task-usage>
|
|
170
|
+
|
|
171
|
+
<background-agents>
|
|
172
|
+
## Background Execution
|
|
173
|
+
|
|
174
|
+
All agents support `run_in_background: true`. Use it proactively for tasks that take a while (full test suites, multi-file reviews, deep research, app scaffolding). Tell the user "Running X in background" and keep working. Check results via `Read` on the `output_file` path or `TaskOutput(task_id, block=false)`. Multiple agents can run in background simultaneously.
|
|
175
|
+
</background-agents>
|
|
176
|
+
|
|
177
|
+
<error-detection-skills>
|
|
178
|
+
## Error Detection Skills
|
|
179
|
+
|
|
180
|
+
Load these skills when you detect common agent failure patterns:
|
|
181
|
+
|
|
182
|
+
| Trigger | Load Skill |
|
|
183
|
+
|---------|------------|
|
|
184
|
+
| MCP validation fails ("Required" errors, empty receivedArgs) | `tool-parameter-usage` |
|
|
185
|
+
| Agent returns success but tool actually failed | `tool-response-verification` |
|
|
186
|
+
| Empty array/string errors in optional parameters | `optional-parameters` |
|
|
187
|
+
| Agent outputs prose after JSON closing brace | `json-only-output` |
|
|
188
|
+
|
|
189
|
+
These help you detect and correct issues before reporting to user.
|
|
190
|
+
</error-detection-skills>
|
|
191
|
+
|
|
192
|
+
<push-commands>
|
|
193
|
+
When agents return `"status": "ready_to_push"`:
|
|
194
|
+
```json
|
|
195
|
+
{ "status": "ready_to_push", "commands": ["npm run fields-push"], "summary": "..." }
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
YOU run these commands via Bash tool. This triggers safety hooks.
|
|
199
|
+
Do NOT ask user to run them manually.
|
|
200
|
+
</push-commands>
|
|
201
|
+
|
|
202
|
+
<needs-confirmation>
|
|
203
|
+
When agents return `"status": "needs_confirmation"`:
|
|
204
|
+
1. AskUserQuestion to confirm
|
|
205
|
+
2. If yes: run the `safe_command` from result
|
|
206
|
+
3. If no: report cancellation
|
|
207
|
+
</needs-confirmation>
|
|
208
|
+
|
|
209
|
+
---
|
|
210
|
+
|
|
211
|
+
<local-first>
|
|
212
|
+
**Why local-first?** Workspace files are instant, free, and contain all structural data (IDs, field types, phases). API calls are slow, rate-limited, and only needed for live activity data. Always check workspace/ BEFORE API calls.
|
|
213
|
+
|
|
214
|
+
```
|
|
215
|
+
workspace/
|
|
216
|
+
├── workflows.ts, enums.ts, teams.ts, groups.ts
|
|
217
|
+
└── [Workflow]_[id]/
|
|
218
|
+
├── fields.ts
|
|
219
|
+
└── phases.ts
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
LOCAL: Workflow/field/phase IDs, field types, labels, options
|
|
223
|
+
API: Activity data, counts, discussion messages
|
|
224
|
+
|
|
225
|
+
REFRESH: `npm run pull`
|
|
226
|
+
</local-first>
|
|
227
|
+
|
|
228
|
+
<hooks>
|
|
229
|
+
## Hooks
|
|
230
|
+
|
|
231
|
+
26 CJS hooks in `.claude/hooks/` wired via `settings.json`. Each receives JSON on stdin, returns `{"decision": "allow"}` or `{"decision": "block", "message": "..."}` on stdout.
|
|
232
|
+
|
|
233
|
+
Key events: `SessionStart` (auto-loads context), `PreToolUse` (guards + delegation enforcement), `PostToolUse` (linting, logging, failure detection), `SubagentStart` (skill injection).
|
|
234
|
+
|
|
235
|
+
**If hooks break after `npm install`:** Check `.claude/settings.json` paths, test with `node .claude/hooks/<script>.cjs --help`, or run `/clear-defaults`.
|
|
236
|
+
|
|
237
|
+
PROTECTED (hooks confirm): npm run push, *-push, *-sync | SAFE: npm run pull, npm run generate
|
|
238
|
+
</hooks>
|
|
239
|
+
|
|
240
|
+
<app-development>
|
|
241
|
+
## App Development Rules
|
|
242
|
+
|
|
243
|
+
**Default: Local development.** Scaffold creates a dev app at `http://localhost:3000` automatically. Run `npm run dev` and test inside Hailer iframe.
|
|
244
|
+
|
|
245
|
+
**Publishing: Only when user explicitly asks.** Tell Giuseppe to load the `publish-hailer-app` skill. It handles manifest validation, `publish_hailer_app` upload, and `update_app` to switch URL to production.
|
|
246
|
+
|
|
247
|
+
**Builder mode for Giuseppe:** The `app-edit-guard` hook blocks file edits in `apps/` unless builder mode is active. Before spawning Giuseppe directly, run:
|
|
248
|
+
```bash
|
|
249
|
+
node .claude/hooks/app-edit-guard.cjs --agent-on
|
|
250
|
+
```
|
|
251
|
+
After Giuseppe completes:
|
|
252
|
+
```bash
|
|
253
|
+
node .claude/hooks/app-edit-guard.cjs --agent-off
|
|
254
|
+
```
|
|
255
|
+
The `/app-squad` command handles this automatically.
|
|
256
|
+
</app-development>
|
|
257
|
+
|
|
258
|
+
---
|
|
259
|
+
|
|
260
|
+
<session-protocol>
|
|
261
|
+
## Session Protocol
|
|
262
|
+
|
|
263
|
+
### Starting a Session
|
|
264
|
+
SessionStart hook auto-loads SESSION-HANDOFF.md + DEVELOPMENT.md into context.
|
|
265
|
+
1. Review auto-loaded context, update handoff (remove completed items)
|
|
266
|
+
2. If handoff has "Pending Tasks" → recreate with `TaskCreate`
|
|
267
|
+
3. If no DEVELOPMENT.md → offer to create one
|
|
268
|
+
4. Briefly confirm current state before diving in
|
|
269
|
+
|
|
270
|
+
### During a Session
|
|
271
|
+
- **Feature request:** Ask "Want me to create a PRD?" even if user provides detailed plan. Only skip if user explicitly declines or already used `/prd`/`/autoplan`.
|
|
272
|
+
- **Tasks:** 2+ agents or 3+ steps = create tasks. Mark in_progress before starting, completed when done. If it won't be done this session, put it in DEVELOPMENT.md backlog.
|
|
273
|
+
- **Learnings:** Use `/learn <cat> <desc>` to capture gotchas and patterns.
|
|
274
|
+
|
|
275
|
+
### Ending a Session
|
|
276
|
+
- **Completion:** Update DEVELOPMENT.md + PRD status. Offer code-simplifier after features.
|
|
277
|
+
- **Context full:** Update handoff, tell user to run `/handoff`.
|
|
278
|
+
- **When to update DEVELOPMENT.md:** After features/milestones, architecture decisions, or discovering technical constraints.
|
|
279
|
+
|
|
280
|
+
### Planning Workflow
|
|
281
|
+
1. **Big picture → DEVELOPMENT.md** — Purpose, stack, roadmap linking to PRDs
|
|
282
|
+
2. **Feature details → PRDs** (`docs/prd-*.md`) — One per feature, links back to roadmap
|
|
283
|
+
3. **Implementation → Pick a PRD and build**
|
|
284
|
+
|
|
285
|
+
**Quick start:** `/autoplan "description"` creates DEVELOPMENT.md + PRDs automatically.
|
|
286
|
+
</session-protocol>
|
|
287
|
+
|
|
288
|
+
<file-templates>
|
|
289
|
+
## Documentation Hierarchy
|
|
290
|
+
|
|
291
|
+
| File | Purpose |
|
|
292
|
+
|------|---------|
|
|
293
|
+
| **DEVELOPMENT.md** | Project status, backlog, tech stack, roadmap |
|
|
294
|
+
| **docs/prd-*.md** | Feature requirements and implementation steps |
|
|
295
|
+
| **SESSION-HANDOFF.md** | Current work, next steps, key context |
|
|
296
|
+
|
|
297
|
+
**DEVELOPMENT.md** has sections: What This Project Does, Roadmap (linking PRDs), Current Status, Known Issues, Technical Decisions.
|
|
298
|
+
**SESSION-HANDOFF.md** has sections: Current Work, Next Steps, Context.
|
|
299
|
+
</file-templates>
|
|
300
|
+
|
|
301
|
+
<customization>
|
|
302
|
+
**Creating agents:** Load `agent-structure` skill for template.
|
|
303
|
+
**Modify:** Edit `.claude/agents/*.md`
|
|
304
|
+
**Disable:** Move to `docs/agents/`
|
|
305
|
+
</customization>
|
|
306
|
+
|
|
307
|
+
<config-source>
|
|
308
|
+
## Config Source
|
|
309
|
+
|
|
310
|
+
Agents, skills, hooks, and commands are in `.claude/` (project-local).
|
|
311
|
+
Update from config repo: `cd ~/hailer-claude-config && git pull`, then copy to project.
|
|
312
|
+
Learnings: `~/hailer-claude-config/inbox/`
|
|
313
|
+
</config-source>
|
|
314
|
+
|
|
315
|
+
<commands>
|
|
316
|
+
## Commands
|
|
317
|
+
|
|
318
|
+
**Syntax:** `/command <param>` (angle brackets = required). `/help:topic` (colon = subtopic).
|
|
319
|
+
|
|
320
|
+
**Essential:** `/save`, `/handoff`, `/prd`, `/autoplan`, `/ws-pull`, `/learn`
|
|
321
|
+
|
|
322
|
+
**Squads** (multi-agent workflows):
|
|
323
|
+
|
|
324
|
+
| Squad | Agents | Use for |
|
|
325
|
+
|-------|--------|---------|
|
|
326
|
+
| `/app-squad` | Kenji → Designer → Giuseppe → Tanya | Build apps end-to-end |
|
|
327
|
+
| `/review-squad` | Svetlana + Lars + Tanya | Code review with auto-fix |
|
|
328
|
+
| `/config-squad` | Helga → Alejandro → Viktor | Workflow + fields + insights |
|
|
329
|
+
| `/hotfix-squad` | Tanya → Simple Writer → Svetlana | Quick bug fixes |
|
|
330
|
+
| `/debug-squad` | Kenji + Viktor + Svetlana + Tanya | Parallel investigation |
|
|
331
|
+
| `/swarm <desc>` | Auto-selected | Large-scale parallel work |
|
|
332
|
+
|
|
333
|
+
More squads + full command list: `/help:commands`
|
|
334
|
+
</commands>
|
|
335
|
+
|
|
336
|
+
<directory>
|
|
337
|
+
## Project Structure
|
|
338
|
+
|
|
339
|
+
```
|
|
340
|
+
workspace/ # Hailer config - check FIRST for IDs
|
|
341
|
+
apps/ # Frontend apps
|
|
342
|
+
integrations/ # Backend services
|
|
343
|
+
.claude/ # Agents, hooks, skills, commands (project-local)
|
|
344
|
+
DEVELOPMENT.md # Project status
|
|
345
|
+
```
|
|
346
|
+
</directory>
|
|
347
|
+
|
|
348
|
+
<sdk-gotchas>
|
|
349
|
+
## Hailer SDK Quick Reference
|
|
350
|
+
|
|
351
|
+
Common pitfalls that cause debugging loops - check these FIRST:
|
|
352
|
+
|
|
353
|
+
| Gotcha | Correct | Wrong |
|
|
354
|
+
|--------|---------|-------|
|
|
355
|
+
| Activity field updates | `{type: "string", value: "x"}` wrapper | Raw value `"x"` |
|
|
356
|
+
| `linkedfrom` in isolated-vm | Does NOT work - use ActivityLink field instead | Trying cross-link resolution |
|
|
357
|
+
| Code in isolated-vm | Plain JavaScript only | TypeScript syntax (`as`, type annotations) |
|
|
358
|
+
| Phase transitions | Exact string: `"Uudet"` → `"Tehty"` | Guessed names |
|
|
359
|
+
| Field IDs | Read from workspace/ files | Guessing from labels |
|
|
360
|
+
| Dropdown values | `{data: [{value, label}]}` | `{options: [...]}` |
|
|
361
|
+
| ActivityLink format | Plain string array of workflow IDs | Nested objects |
|
|
362
|
+
|
|
363
|
+
**Rule:** When touching Hailer fields, ALWAYS read workspace/ first via Kenji. Never guess IDs or formats.
|
|
364
|
+
</sdk-gotchas>
|
|
365
|
+
|
|
366
|
+
<bulk-operations>
|
|
367
|
+
## Bulk Tasks
|
|
368
|
+
|
|
369
|
+
For repetitive edits, use `/swarm` or headless mode (`claude -p "..." --allowedTools "Edit,Read,Grep,Glob"`). Act first — grep to find instances, then edit immediately.
|
|
370
|
+
</bulk-operations>
|
|
@@ -533,7 +533,7 @@ project/
|
|
|
533
533
|
|
|
534
534
|
**Next steps:**
|
|
535
535
|
1. Review PRDs and refine requirements
|
|
536
|
-
2.
|
|
536
|
+
2. Start building from a PRD: review requirements, then implement
|
|
537
537
|
```
|
|
538
538
|
|
|
539
539
|
**For EXISTING projects:**
|
|
@@ -551,7 +551,7 @@ project/
|
|
|
551
551
|
|
|
552
552
|
**Next steps:**
|
|
553
553
|
1. Review new PRDs
|
|
554
|
-
2.
|
|
554
|
+
2. Start implementing from the PRD
|
|
555
555
|
```
|
|
556
556
|
|
|
557
557
|
## Important
|
|
@@ -61,10 +61,6 @@ SQUADS (multi-agent commands)
|
|
|
61
61
|
/janitor-squad Parallel+Loop: Lars + Bjorn + Viktor → Simple Writer (cleanup)
|
|
62
62
|
/swarm <desc> Swarm: orchestrator picks agents, splits work, dispatches parallel workers
|
|
63
63
|
|
|
64
|
-
AUTONOMOUS MODE
|
|
65
|
-
/yolo <task> Run task without asking permission
|
|
66
|
-
/yolo-off Disable autonomous mode
|
|
67
|
-
|
|
68
64
|
SESSION
|
|
69
65
|
/recap [focus] Resume session - load handoff, status, learnings
|
|
70
66
|
/save <message> Save changes to git (local commit)
|
|
@@ -77,7 +73,6 @@ Examples:
|
|
|
77
73
|
/plan-workspace "CRM system" Thorough discovery for new project
|
|
78
74
|
/autoplan "Add invoicing" Quick planning for feature
|
|
79
75
|
/prd "customer portal" Create PRD for feature
|
|
80
|
-
/yolo docs/prd-feature.md Implement a PRD autonomously
|
|
81
76
|
/save "Add customer form" Local git commit
|
|
82
77
|
/learn agent/kenji "Check enums first"
|
|
83
78
|
```
|
|
@@ -68,11 +68,6 @@ A: /autoplan - Quick planning, creates DEVELOPMENT.md + PRDs
|
|
|
68
68
|
/plan-workspace - Thorough 10-phase discovery for complex workspaces
|
|
69
69
|
Use /autoplan for features, /plan-workspace for new projects.
|
|
70
70
|
|
|
71
|
-
Q: What is /yolo mode?
|
|
72
|
-
A: Autonomous execution without permission prompts. Best for PRD-based
|
|
73
|
-
tasks where requirements are clearly defined. Still delegates to
|
|
74
|
-
agents and creates restore points. Use /yolo-off to disable.
|
|
75
|
-
|
|
76
71
|
Q: How do PRDs and DEVELOPMENT.md work together?
|
|
77
72
|
A: DEVELOPMENT.md is the big picture (roadmap, status, decisions).
|
|
78
73
|
PRDs (docs/prd-*.md) are detailed requirements for each feature.
|
|
@@ -717,7 +717,7 @@ Use the PRD templates from autoplan but with REAL DATA from the discovery:
|
|
|
717
717
|
|
|
718
718
|
**Next steps:**
|
|
719
719
|
1. Review PRDs with stakeholder
|
|
720
|
-
2. Start
|
|
720
|
+
2. Start building from the first PRD
|
|
721
721
|
```
|
|
722
722
|
|
|
723
723
|
---
|
package/.claude/commands/prd.md
CHANGED
|
@@ -126,6 +126,5 @@ Updated: DEVELOPMENT.md roadmap
|
|
|
126
126
|
|
|
127
127
|
Next steps:
|
|
128
128
|
- Review PRD requirements
|
|
129
|
-
- When ready to implement,
|
|
130
|
-
since the requirements are already clearly defined
|
|
129
|
+
- When ready to implement, work through the PRD requirements step by step
|
|
131
130
|
```
|
|
@@ -16,7 +16,7 @@ Recent saves:
|
|
|
16
16
|
|
|
17
17
|
[1] a1b2c3d - 2 hours ago - "Fix login button"
|
|
18
18
|
[2] e4f5g6h - Yesterday - "Add user form"
|
|
19
|
-
[3] i7j8k9l - 2 days ago - "
|
|
19
|
+
[3] i7j8k9l - 2 days ago - "Add dashboard"
|
|
20
20
|
...
|
|
21
21
|
|
|
22
22
|
Which save do you want to restore to? (enter number)
|
|
@@ -27,7 +27,7 @@ Use `git log --oneline --format="%h - %ar - %s" -10` for nice format.
|
|
|
27
27
|
**Step 3: Confirm with user**
|
|
28
28
|
After user picks a number, show:
|
|
29
29
|
```
|
|
30
|
-
You selected: "
|
|
30
|
+
You selected: "Add dashboard"
|
|
31
31
|
|
|
32
32
|
This will:
|
|
33
33
|
- Save your current state first (safety backup)
|
|
@@ -52,7 +52,7 @@ Proceed? (yes/no)
|
|
|
52
52
|
|
|
53
53
|
**Step 5: Confirm**
|
|
54
54
|
```
|
|
55
|
-
Done! Restored to "
|
|
55
|
+
Done! Restored to "Add dashboard"
|
|
56
56
|
|
|
57
57
|
Your previous state was saved as "Before restore - safety backup"
|
|
58
58
|
If you want to undo, run /restore again and pick that save.
|
package/.claude/hooks/_utils.cjs
CHANGED
|
@@ -3,35 +3,10 @@
|
|
|
3
3
|
* Shared utilities for Claude Code hooks
|
|
4
4
|
*
|
|
5
5
|
* Usage:
|
|
6
|
-
* const {
|
|
6
|
+
* const { readStdin, safeJsonParse, outputAllow } = require('./_utils.cjs');
|
|
7
7
|
*/
|
|
8
8
|
|
|
9
9
|
const fs = require('fs');
|
|
10
|
-
const path = require('path');
|
|
11
|
-
|
|
12
|
-
// Cache yolo mode per-process since it doesn't change within a single hook execution
|
|
13
|
-
let _yoloCache;
|
|
14
|
-
|
|
15
|
-
/**
|
|
16
|
-
* Check if yolo mode is active
|
|
17
|
-
* @returns {boolean}
|
|
18
|
-
*/
|
|
19
|
-
function isYoloMode() {
|
|
20
|
-
if (_yoloCache !== undefined) return _yoloCache;
|
|
21
|
-
try {
|
|
22
|
-
const statePath = path.join(
|
|
23
|
-
process.env.CLAUDE_PROJECT_DIR || process.cwd(),
|
|
24
|
-
'.claude',
|
|
25
|
-
'yolo-state.json'
|
|
26
|
-
);
|
|
27
|
-
const state = JSON.parse(fs.readFileSync(statePath, 'utf8'));
|
|
28
|
-
_yoloCache = state.mode === 'yolo';
|
|
29
|
-
return _yoloCache;
|
|
30
|
-
} catch {
|
|
31
|
-
_yoloCache = false;
|
|
32
|
-
return false;
|
|
33
|
-
}
|
|
34
|
-
}
|
|
35
10
|
|
|
36
11
|
/**
|
|
37
12
|
* Read stdin safely with TTY check (async)
|
|
@@ -123,7 +98,6 @@ function fileExists(filePath) {
|
|
|
123
98
|
}
|
|
124
99
|
|
|
125
100
|
module.exports = {
|
|
126
|
-
isYoloMode,
|
|
127
101
|
readStdin,
|
|
128
102
|
readStdinSync,
|
|
129
103
|
safeJsonParse,
|
|
@@ -34,18 +34,6 @@ const fs = require('fs');
|
|
|
34
34
|
const path = require('path');
|
|
35
35
|
const os = require('os');
|
|
36
36
|
|
|
37
|
-
// Skip in yolo mode
|
|
38
|
-
try {
|
|
39
|
-
const statePath = path.join(process.env.CLAUDE_PROJECT_DIR || process.cwd(), '.claude', 'yolo-state.json');
|
|
40
|
-
const state = JSON.parse(fs.readFileSync(statePath, 'utf8'));
|
|
41
|
-
if (state.mode === 'yolo') process.exit(0);
|
|
42
|
-
} catch (e) {
|
|
43
|
-
// ENOENT is expected when not in yolo mode - only warn on unexpected errors
|
|
44
|
-
if (e.code !== 'ENOENT' && !e.message.includes('Unexpected')) {
|
|
45
|
-
console.error(`[agent-failure-detector] Warning: ${e.message}`);
|
|
46
|
-
}
|
|
47
|
-
}
|
|
48
|
-
|
|
49
37
|
const TEMP_DIR = os.tmpdir();
|
|
50
38
|
const TRACKER_FILE = path.join(TEMP_DIR, '.claude-agent-failures.json');
|
|
51
39
|
const GLOBAL_LOG_FILE = path.join(
|
|
@@ -44,13 +44,6 @@ const fs = require('fs');
|
|
|
44
44
|
const path = require('path');
|
|
45
45
|
const os = require('os');
|
|
46
46
|
|
|
47
|
-
// Skip in yolo mode
|
|
48
|
-
try {
|
|
49
|
-
const statePath = path.join(process.env.CLAUDE_PROJECT_DIR || process.cwd(), '.claude', 'yolo-state.json');
|
|
50
|
-
const state = JSON.parse(fs.readFileSync(statePath, 'utf8'));
|
|
51
|
-
if (state.mode === 'yolo') process.exit(0);
|
|
52
|
-
} catch {}
|
|
53
|
-
|
|
54
47
|
// Skip in subagent context - subagents can't use AskUserQuestion or Bash to recover
|
|
55
48
|
// Orchestrator should use --agent-on before spawning, but this is a safety fallback
|
|
56
49
|
if (process.env.CLAUDE_AGENT_ID || process.env.CLAUDE_SUBAGENT) {
|
|
@@ -31,18 +31,6 @@ const fs = require('fs');
|
|
|
31
31
|
const path = require('path');
|
|
32
32
|
const os = require('os');
|
|
33
33
|
|
|
34
|
-
// Skip in yolo mode
|
|
35
|
-
try {
|
|
36
|
-
const statePath = path.join(process.env.CLAUDE_PROJECT_DIR || process.cwd(), '.claude', 'yolo-state.json');
|
|
37
|
-
const state = JSON.parse(fs.readFileSync(statePath, 'utf8'));
|
|
38
|
-
if (state.mode === 'yolo') process.exit(0);
|
|
39
|
-
} catch (e) {
|
|
40
|
-
// ENOENT is expected when not in yolo mode - only warn on unexpected errors
|
|
41
|
-
if (e.code !== 'ENOENT' && !e.message.includes('Unexpected')) {
|
|
42
|
-
console.error(`[auto-learn] Warning: ${e.message}`);
|
|
43
|
-
}
|
|
44
|
-
}
|
|
45
|
-
|
|
46
34
|
const LEARNINGS_FILE = path.join(
|
|
47
35
|
process.env.HAILER_INBOX_DIR || path.join(process.env.CLAUDE_PROJECT_DIR || process.cwd(), 'inbox'),
|
|
48
36
|
'learnings.md'
|
|
@@ -59,14 +59,6 @@ Usage:
|
|
|
59
59
|
process.exit(0);
|
|
60
60
|
}
|
|
61
61
|
|
|
62
|
-
// --- Yolo mode check ---
|
|
63
|
-
let isYolo = false;
|
|
64
|
-
try {
|
|
65
|
-
const statePath = path.join(projectDir, '.claude', 'yolo-state.json');
|
|
66
|
-
const state = JSON.parse(fs.readFileSync(statePath, 'utf8'));
|
|
67
|
-
isYolo = state.mode === 'yolo';
|
|
68
|
-
} catch {}
|
|
69
|
-
|
|
70
62
|
// --- Read stdin ---
|
|
71
63
|
let input = '';
|
|
72
64
|
process.stdin.setEncoding('utf8');
|
|
@@ -99,12 +91,10 @@ function processHook(data) {
|
|
|
99
91
|
if (!command) { allow(); return; }
|
|
100
92
|
|
|
101
93
|
// Run checks in order of specificity
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
checkWorkspaceAutoSave(command);
|
|
107
|
-
}
|
|
94
|
+
checkDestructive(command);
|
|
95
|
+
checkMcpServer(command);
|
|
96
|
+
checkWorkspacePull(command);
|
|
97
|
+
checkWorkspaceAutoSave(command);
|
|
108
98
|
allow();
|
|
109
99
|
}
|
|
110
100
|
|
|
@@ -42,18 +42,6 @@ const fs = require('fs');
|
|
|
42
42
|
const path = require('path');
|
|
43
43
|
const os = require('os');
|
|
44
44
|
|
|
45
|
-
// Skip in yolo mode
|
|
46
|
-
try {
|
|
47
|
-
const statePath = path.join(process.env.CLAUDE_PROJECT_DIR || process.cwd(), '.claude', 'yolo-state.json');
|
|
48
|
-
const state = JSON.parse(fs.readFileSync(statePath, 'utf8'));
|
|
49
|
-
if (state.mode === 'yolo') process.exit(0);
|
|
50
|
-
} catch (e) {
|
|
51
|
-
// ENOENT is expected when not in yolo mode - only warn on unexpected errors
|
|
52
|
-
if (e.code !== 'ENOENT' && !e.message.includes('Unexpected')) {
|
|
53
|
-
console.error(`[builder-mode-manager] Warning: ${e.message}`);
|
|
54
|
-
}
|
|
55
|
-
}
|
|
56
|
-
|
|
57
45
|
const TEMP_DIR = os.tmpdir();
|
|
58
46
|
const BUILDER_MODE_FILE = path.join(TEMP_DIR, '.claude-builder-agent-active');
|
|
59
47
|
const AGENT_STACK_FILE = path.join(TEMP_DIR, '.claude-agent-stack.json');
|
|
@@ -28,18 +28,6 @@ const fs = require('fs');
|
|
|
28
28
|
const path = require('path');
|
|
29
29
|
const os = require('os');
|
|
30
30
|
|
|
31
|
-
// Skip in yolo mode
|
|
32
|
-
try {
|
|
33
|
-
const statePath = path.join(process.env.CLAUDE_PROJECT_DIR || process.cwd(), '.claude', 'yolo-state.json');
|
|
34
|
-
const state = JSON.parse(fs.readFileSync(statePath, 'utf8'));
|
|
35
|
-
if (state.mode === 'yolo') process.exit(0);
|
|
36
|
-
} catch (e) {
|
|
37
|
-
// ENOENT is expected when not in yolo mode - only warn on unexpected errors
|
|
38
|
-
if (e.code !== 'ENOENT' && !e.message.includes('Unexpected')) {
|
|
39
|
-
console.error(`[bulk-activity-guard] Warning: ${e.message}`);
|
|
40
|
-
}
|
|
41
|
-
}
|
|
42
|
-
|
|
43
31
|
// Skip in subagent context - orchestrator handles confirmation via delegation-bulk-guard
|
|
44
32
|
// Subagents can't use AskUserQuestion or Bash, so blocking them is unrecoverable
|
|
45
33
|
if (process.env.CLAUDE_AGENT_ID || process.env.CLAUDE_SUBAGENT) {
|