@hailer/mcp 1.1.8 → 1.1.10
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/.mcp.json +4 -4
- package/.opencode/opencode.json +7 -0
- package/CHANGELOG.md +7 -0
- package/dist/cli.js +0 -0
- package/dist/mcp-server.js +35 -4
- package/package.json +1 -1
- package/.hailer-mcp-port +0 -1
- package/dist/CLAUDE.md +0 -370
- package/dist/lib/discussion-lock.d.ts +0 -42
- package/dist/lib/discussion-lock.js +0 -110
- package/dist/mcp/tools/bot-config/constants.d.ts +0 -23
- package/dist/mcp/tools/bot-config/constants.js +0 -94
- package/dist/mcp/tools/bot-config/core.d.ts +0 -253
- package/dist/mcp/tools/bot-config/core.js +0 -2456
- package/dist/mcp/tools/bot-config/index.d.ts +0 -10
- package/dist/mcp/tools/bot-config/index.js +0 -59
- package/dist/mcp/tools/bot-config/tools.d.ts +0 -7
- package/dist/mcp/tools/bot-config/tools.js +0 -15
- package/dist/mcp/tools/bot-config/types.d.ts +0 -50
- package/dist/mcp/tools/bot-config/types.js +0 -6
- package/dist/mcp/tools/bug-fixer-tools.d.ts +0 -45
- package/dist/mcp/tools/bug-fixer-tools.js +0 -1096
- package/dist/mcp/tools/document.d.ts +0 -11
- package/dist/mcp/tools/document.js +0 -741
- package/dist/mcp/tools/investigate.d.ts +0 -9
- package/dist/mcp/tools/investigate.js +0 -254
- package/inbox/failures.log +0 -1
package/.mcp.json
CHANGED
|
@@ -2,12 +2,12 @@
|
|
|
2
2
|
"mcpServers": {
|
|
3
3
|
"hailer": {
|
|
4
4
|
"type": "stdio",
|
|
5
|
-
"command": "
|
|
5
|
+
"command": "npx",
|
|
6
6
|
"args": [
|
|
7
|
-
"-
|
|
8
|
-
"
|
|
7
|
+
"mcp-remote",
|
|
8
|
+
"http://localhost:3030/api/mcp?apiKey=unique-api-key-for-this-agent"
|
|
9
9
|
],
|
|
10
10
|
"env": {}
|
|
11
11
|
}
|
|
12
12
|
}
|
|
13
|
-
}
|
|
13
|
+
}
|
package/.opencode/opencode.json
CHANGED
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,13 @@ All notable changes to this project will be documented in this file.
|
|
|
4
4
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
5
5
|
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
6
6
|
|
|
7
|
+
## [1.1.10] - 25-02-2026
|
|
8
|
+
|
|
9
|
+
### Added
|
|
10
|
+
|
|
11
|
+
- **OpenCode MCP support:** Added `.opencode/opencode.json` with Hailer MCP server configuration
|
|
12
|
+
- **Dynamic port patching for OpenCode:** On server startup, `.opencode/opencode.json` is now auto-updated with the actual port (alongside the existing `.mcp.json` patching), so both Claude Code and OpenCode always connect to the right server
|
|
13
|
+
|
|
7
14
|
## [1.1.7] - 18-02-2026
|
|
8
15
|
|
|
9
16
|
### Fix
|
package/dist/cli.js
CHANGED
|
File without changes
|
package/dist/mcp-server.js
CHANGED
|
@@ -474,12 +474,43 @@ class MCPServerService {
|
|
|
474
474
|
healthCheck: `http://localhost:${port}/health`,
|
|
475
475
|
mcpEndpoint: `http://localhost:${port}/api/mcp`
|
|
476
476
|
});
|
|
477
|
-
//
|
|
477
|
+
// Update .mcp.json with the actual port so Claude Code connects to the right server
|
|
478
478
|
const fs = require('fs');
|
|
479
479
|
const path = require('path');
|
|
480
|
-
const
|
|
481
|
-
|
|
482
|
-
|
|
480
|
+
const mcpJsonPath = path.join(process.cwd(), '.mcp.json');
|
|
481
|
+
try {
|
|
482
|
+
if (fs.existsSync(mcpJsonPath)) {
|
|
483
|
+
const mcpJson = JSON.parse(fs.readFileSync(mcpJsonPath, 'utf-8'));
|
|
484
|
+
const hailerServer = mcpJson?.mcpServers?.hailer;
|
|
485
|
+
if (hailerServer?.args) {
|
|
486
|
+
const urlIndex = hailerServer.args.findIndex((arg) => typeof arg === 'string' && arg.includes('localhost:'));
|
|
487
|
+
if (urlIndex !== -1) {
|
|
488
|
+
hailerServer.args[urlIndex] = hailerServer.args[urlIndex].replace(/localhost:\d+/, `localhost:${port}`);
|
|
489
|
+
fs.writeFileSync(mcpJsonPath, JSON.stringify(mcpJson, null, 2) + '\n');
|
|
490
|
+
this.logger.debug('.mcp.json updated with port', { port });
|
|
491
|
+
}
|
|
492
|
+
}
|
|
493
|
+
}
|
|
494
|
+
}
|
|
495
|
+
catch (err) {
|
|
496
|
+
this.logger.debug('Could not update .mcp.json', { error: err.message });
|
|
497
|
+
}
|
|
498
|
+
// Update .opencode/opencode.json with the actual port so OpenCode connects to the right server
|
|
499
|
+
const opencodeJsonPath = path.join(process.cwd(), '.opencode', 'opencode.json');
|
|
500
|
+
try {
|
|
501
|
+
if (fs.existsSync(opencodeJsonPath)) {
|
|
502
|
+
const opencodeJson = JSON.parse(fs.readFileSync(opencodeJsonPath, 'utf-8'));
|
|
503
|
+
const hailerMcp = opencodeJson?.mcp?.hailer;
|
|
504
|
+
if (hailerMcp?.url && typeof hailerMcp.url === 'string' && hailerMcp.url.includes('localhost:')) {
|
|
505
|
+
hailerMcp.url = hailerMcp.url.replace(/localhost:\d+/, `localhost:${port}`);
|
|
506
|
+
fs.writeFileSync(opencodeJsonPath, JSON.stringify(opencodeJson, null, 2) + '\n');
|
|
507
|
+
this.logger.debug('.opencode/opencode.json updated with port', { port });
|
|
508
|
+
}
|
|
509
|
+
}
|
|
510
|
+
}
|
|
511
|
+
catch (err) {
|
|
512
|
+
this.logger.debug('Could not update .opencode/opencode.json', { error: err.message });
|
|
513
|
+
}
|
|
483
514
|
resolve();
|
|
484
515
|
});
|
|
485
516
|
this.server.on('error', (error) => {
|
package/package.json
CHANGED
package/.hailer-mcp-port
DELETED
|
@@ -1 +0,0 @@
|
|
|
1
|
-
3031
|
package/dist/CLAUDE.md
DELETED
|
@@ -1,370 +0,0 @@
|
|
|
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** — Use `/yolo` for autonomous execution
|
|
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`, `/yolo`, `/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>
|
|
@@ -1,42 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Discussion Lock Registry
|
|
3
|
-
*
|
|
4
|
-
* Prevents multiple bots from responding to the same discussion.
|
|
5
|
-
* When a specialist bot (like Giuseppe) is handling a discussion,
|
|
6
|
-
* it acquires a lock. Other bots (like Orchestrator) check the lock
|
|
7
|
-
* before responding.
|
|
8
|
-
*/
|
|
9
|
-
/**
|
|
10
|
-
* Acquire a lock on a discussion
|
|
11
|
-
* @param discussionId - The discussion to lock
|
|
12
|
-
* @param botName - Name of the bot acquiring the lock (for logging)
|
|
13
|
-
* @param ttlMs - Lock duration in milliseconds (default: 5 minutes)
|
|
14
|
-
* @returns true if lock acquired, false if already locked by another bot
|
|
15
|
-
*/
|
|
16
|
-
export declare function acquireDiscussionLock(discussionId: string, botName: string, ttlMs?: number): boolean;
|
|
17
|
-
/**
|
|
18
|
-
* Release a lock on a discussion
|
|
19
|
-
* @param discussionId - The discussion to unlock
|
|
20
|
-
* @param botName - Name of the bot releasing (must match acquirer)
|
|
21
|
-
*/
|
|
22
|
-
export declare function releaseDiscussionLock(discussionId: string, botName: string): void;
|
|
23
|
-
/**
|
|
24
|
-
* Check if a discussion is locked by another bot
|
|
25
|
-
* @param discussionId - The discussion to check
|
|
26
|
-
* @param myBotName - Name of the checking bot (own locks don't block)
|
|
27
|
-
* @returns true if locked by ANOTHER bot, false if free or own lock
|
|
28
|
-
*/
|
|
29
|
-
export declare function isDiscussionLocked(discussionId: string, myBotName: string): boolean;
|
|
30
|
-
/**
|
|
31
|
-
* Clean up expired locks (call periodically)
|
|
32
|
-
*/
|
|
33
|
-
export declare function cleanupExpiredLocks(): number;
|
|
34
|
-
/**
|
|
35
|
-
* Get current lock status (for debugging)
|
|
36
|
-
*/
|
|
37
|
-
export declare function getLockStatus(): Map<string, {
|
|
38
|
-
botName: string;
|
|
39
|
-
acquiredAt: number;
|
|
40
|
-
expiresAt: number;
|
|
41
|
-
}>;
|
|
42
|
-
//# sourceMappingURL=discussion-lock.d.ts.map
|
|
@@ -1,110 +0,0 @@
|
|
|
1
|
-
"use strict";
|
|
2
|
-
/**
|
|
3
|
-
* Discussion Lock Registry
|
|
4
|
-
*
|
|
5
|
-
* Prevents multiple bots from responding to the same discussion.
|
|
6
|
-
* When a specialist bot (like Giuseppe) is handling a discussion,
|
|
7
|
-
* it acquires a lock. Other bots (like Orchestrator) check the lock
|
|
8
|
-
* before responding.
|
|
9
|
-
*/
|
|
10
|
-
Object.defineProperty(exports, "__esModule", { value: true });
|
|
11
|
-
exports.acquireDiscussionLock = acquireDiscussionLock;
|
|
12
|
-
exports.releaseDiscussionLock = releaseDiscussionLock;
|
|
13
|
-
exports.isDiscussionLocked = isDiscussionLocked;
|
|
14
|
-
exports.cleanupExpiredLocks = cleanupExpiredLocks;
|
|
15
|
-
exports.getLockStatus = getLockStatus;
|
|
16
|
-
const logger_1 = require("./logger");
|
|
17
|
-
const logger = (0, logger_1.createLogger)({ component: 'discussion-lock' });
|
|
18
|
-
// Singleton map of discussionId -> { botName, acquiredAt, expiresAt }
|
|
19
|
-
const locks = new Map();
|
|
20
|
-
// Default lock TTL: 5 minutes (allows for LLM processing time)
|
|
21
|
-
const DEFAULT_LOCK_TTL_MS = 5 * 60 * 1000;
|
|
22
|
-
/**
|
|
23
|
-
* Acquire a lock on a discussion
|
|
24
|
-
* @param discussionId - The discussion to lock
|
|
25
|
-
* @param botName - Name of the bot acquiring the lock (for logging)
|
|
26
|
-
* @param ttlMs - Lock duration in milliseconds (default: 5 minutes)
|
|
27
|
-
* @returns true if lock acquired, false if already locked by another bot
|
|
28
|
-
*/
|
|
29
|
-
function acquireDiscussionLock(discussionId, botName, ttlMs = DEFAULT_LOCK_TTL_MS) {
|
|
30
|
-
const now = Date.now();
|
|
31
|
-
const existing = locks.get(discussionId);
|
|
32
|
-
// Check if existing lock is still valid
|
|
33
|
-
if (existing && existing.expiresAt > now) {
|
|
34
|
-
if (existing.botName === botName) {
|
|
35
|
-
// Same bot - extend the lock
|
|
36
|
-
existing.expiresAt = now + ttlMs;
|
|
37
|
-
return true;
|
|
38
|
-
}
|
|
39
|
-
// Different bot has the lock
|
|
40
|
-
logger.debug('Discussion already locked', {
|
|
41
|
-
discussionId,
|
|
42
|
-
lockedBy: existing.botName,
|
|
43
|
-
requestedBy: botName
|
|
44
|
-
});
|
|
45
|
-
return false;
|
|
46
|
-
}
|
|
47
|
-
// Acquire lock
|
|
48
|
-
locks.set(discussionId, {
|
|
49
|
-
botName,
|
|
50
|
-
acquiredAt: now,
|
|
51
|
-
expiresAt: now + ttlMs
|
|
52
|
-
});
|
|
53
|
-
logger.debug('Discussion lock acquired', { discussionId, botName, ttlMs });
|
|
54
|
-
return true;
|
|
55
|
-
}
|
|
56
|
-
/**
|
|
57
|
-
* Release a lock on a discussion
|
|
58
|
-
* @param discussionId - The discussion to unlock
|
|
59
|
-
* @param botName - Name of the bot releasing (must match acquirer)
|
|
60
|
-
*/
|
|
61
|
-
function releaseDiscussionLock(discussionId, botName) {
|
|
62
|
-
const existing = locks.get(discussionId);
|
|
63
|
-
if (existing && existing.botName === botName) {
|
|
64
|
-
locks.delete(discussionId);
|
|
65
|
-
logger.debug('Discussion lock released', { discussionId, botName });
|
|
66
|
-
}
|
|
67
|
-
}
|
|
68
|
-
/**
|
|
69
|
-
* Check if a discussion is locked by another bot
|
|
70
|
-
* @param discussionId - The discussion to check
|
|
71
|
-
* @param myBotName - Name of the checking bot (own locks don't block)
|
|
72
|
-
* @returns true if locked by ANOTHER bot, false if free or own lock
|
|
73
|
-
*/
|
|
74
|
-
function isDiscussionLocked(discussionId, myBotName) {
|
|
75
|
-
const now = Date.now();
|
|
76
|
-
const existing = locks.get(discussionId);
|
|
77
|
-
// No lock or expired
|
|
78
|
-
if (!existing || existing.expiresAt <= now) {
|
|
79
|
-
return false;
|
|
80
|
-
}
|
|
81
|
-
// Own lock doesn't block
|
|
82
|
-
if (existing.botName === myBotName) {
|
|
83
|
-
return false;
|
|
84
|
-
}
|
|
85
|
-
return true;
|
|
86
|
-
}
|
|
87
|
-
/**
|
|
88
|
-
* Clean up expired locks (call periodically)
|
|
89
|
-
*/
|
|
90
|
-
function cleanupExpiredLocks() {
|
|
91
|
-
const now = Date.now();
|
|
92
|
-
let cleaned = 0;
|
|
93
|
-
for (const [discussionId, lock] of locks.entries()) {
|
|
94
|
-
if (lock.expiresAt <= now) {
|
|
95
|
-
locks.delete(discussionId);
|
|
96
|
-
cleaned++;
|
|
97
|
-
}
|
|
98
|
-
}
|
|
99
|
-
if (cleaned > 0) {
|
|
100
|
-
logger.debug('Cleaned up expired locks', { count: cleaned });
|
|
101
|
-
}
|
|
102
|
-
return cleaned;
|
|
103
|
-
}
|
|
104
|
-
/**
|
|
105
|
-
* Get current lock status (for debugging)
|
|
106
|
-
*/
|
|
107
|
-
function getLockStatus() {
|
|
108
|
-
return new Map(locks);
|
|
109
|
-
}
|
|
110
|
-
//# sourceMappingURL=discussion-lock.js.map
|
|
@@ -1,23 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Bot Configuration Constants
|
|
3
|
-
*/
|
|
4
|
-
import type { BotInfo } from './types';
|
|
5
|
-
export declare const LOCAL_STATE_FILE: string;
|
|
6
|
-
export declare const SCHEMAS_DIR: string;
|
|
7
|
-
export declare const LOCAL_CREDENTIALS_FILE: string;
|
|
8
|
-
export declare const SIGNAL_DEDUP_WINDOW_MS = 5000;
|
|
9
|
-
export declare const RESTART_DEBOUNCE_MS = 500;
|
|
10
|
-
export declare const AGENT_DIRECTORY_PATTERNS: string[];
|
|
11
|
-
export declare const DEPLOYED_PHASE_PATTERNS: string[];
|
|
12
|
-
export declare const RETIRED_PHASE_PATTERNS: string[];
|
|
13
|
-
export declare const FIELD_KEY_HAILER_PROFILE: string[];
|
|
14
|
-
export declare const FIELD_KEY_EMAIL: string[];
|
|
15
|
-
export declare const FIELD_KEY_PASSWORD: string[];
|
|
16
|
-
export declare const FIELD_KEY_BOT_TYPE: string[];
|
|
17
|
-
export declare const FIELD_KEY_SCHEMA_CONFIG: string[];
|
|
18
|
-
export declare const LEGACY_AGENT_ACTIVITY_IDS: Record<string, string>;
|
|
19
|
-
/**
|
|
20
|
-
* Available bots - single source of truth
|
|
21
|
-
*/
|
|
22
|
-
export declare const AVAILABLE_BOTS: BotInfo[];
|
|
23
|
-
//# sourceMappingURL=constants.d.ts.map
|