AGENTS.md

1# src/hooks/keyword-detector/ -- Mode Keyword Injection
2 
3**Generated:** 2026-07-17
4 
5## OVERVIEW
6 
7Transform Tier hook on `messages.transform`. Scans the first user message for mode keywords and injects mode-specific system prompts. The detector and routing logic stay in `src/hooks/keyword-detector/`; prompt bodies now live in [`packages/prompts-core/prompts/`](../../../../prompts-core/prompts) so they can be shared by future harness adapters.
8 
9This matches the package layering direction in [`ROADMAP.md`](../../../../../ROADMAP.md): `packages/prompts-core` owns static prompt content, while this OpenCode hook owns keyword detection, model routing, and message injection.
10 
11## KEYWORDS
12 
13| Keyword | Pattern | Effect |
14|---------|---------|--------|
15| `ultrawork` / `ulw` | `/\b(ultrawork|ulw)\b/i` | Full orchestration mode: parallel agents, deep exploration, relentless execution |
16| Team mode | `TEAM_PATTERN` (from `team/`) | Forces orchestration via `team_*` tools when user invokes `team mode` / `team-mode` / `team_mode` / `teammode`; instructs user to enable `team_mode.enabled` if tools are absent and reminds lead to run the closure sequence once every task is terminal |
17| Hyperplan mode | `HYPERPLAN_PATTERN` (from `hyperplan/`) | Loads the `hyperplan` skill and injects adversarial planning mode guidance |
18| Hyperplan-ultrawork combo | `HYPERPLAN_ULTRAWORK_PATTERN` (from `constants.ts`) | Prepends the combo banner, requires the `hyperplan` skill, then appends the routed ultrawork message |
19 
20## STRUCTURE
21 
22```
23keyword-detector/
24├── index.ts           # Barrel export
25├── hook.ts            # createKeywordDetectorHook() chat.message handler
26├── detector.ts        # detectKeywordsWithType() + extractPromptText()
27├── constants.ts       # KEYWORD_DETECTORS array, re-exports from submodules
28├── types.ts           # KeywordDetector, DetectedKeyword types
29├── ultrawork/
30│   ├── index.ts       # getUltraworkMessage() router
31│   ├── source-detector.ts # agent/model routing helpers
32│   ├── default.ts     # thin loader for prompts-core/prompts/ultrawork/default.md
33│   ├── gpt.ts         # thin loader for prompts-core/prompts/ultrawork/gpt.md
34│   ├── gemini.ts      # thin loader for prompts-core/prompts/ultrawork/gemini.md
35│   ├── glm.ts         # thin loader for prompts-core/prompts/ultrawork/glm.md
36│   └── planner.ts     # thin loader for prompts-core/prompts/ultrawork/planner.md
37├── team/
38│   ├── index.ts
39│   └── default.ts     # TEAM_PATTERN + TEAM_MESSAGE from prompts-core mode prompt
40└── hyperplan/
41    ├── index.ts
42    └── default.ts     # HYPERPLAN_PATTERN + HYPERPLAN_MESSAGE from prompts-core mode prompt
43```
44 
45## PROMPT CONTENT LOCATIONS
46 
47| Prompt family | Markdown source |
48|---------------|-----------------|
49| Ultrawork default | [`packages/prompts-core/prompts/ultrawork/default.md`](../../../../prompts-core/prompts/ultrawork/default.md) |
50| Ultrawork GPT | [`packages/prompts-core/prompts/ultrawork/gpt.md`](../../../../prompts-core/prompts/ultrawork/gpt.md) |
51| Ultrawork Gemini | [`packages/prompts-core/prompts/ultrawork/gemini.md`](../../../../prompts-core/prompts/ultrawork/gemini.md) |
52| Ultrawork GLM | [`packages/prompts-core/prompts/ultrawork/glm.md`](../../../../prompts-core/prompts/ultrawork/glm.md) |
53| Ultrawork planner | [`packages/prompts-core/prompts/ultrawork/planner.md`](../../../../prompts-core/prompts/ultrawork/planner.md) |
54| Team mode | [`packages/prompts-core/prompts/mode/team.md`](../../../../prompts-core/prompts/mode/team.md) |
55| Hyperplan mode | [`packages/prompts-core/prompts/mode/hyperplan.md`](../../../../prompts-core/prompts/mode/hyperplan.md) |
56 
57The `src/hooks/keyword-detector/{team,hyperplan}/default.ts` files keep the regex triggers in the hook layer and import the markdown-backed constants from `@oh-my-opencode/prompts-core`. The ultrawork files import markdown with Bun's `.md` text loader so the exact prompt bytes are bundled into `dist/index.js`.
58 
59## ULTRAWORK VARIANT ROUTING
60 
61[`ultrawork/source-detector.ts`](ultrawork/source-detector.ts) decides the ultrawork source in priority order:
62 
631. Planner agents (`prometheus`, `planner`, or normalized `plan`) route to `planner.md`.
642. GPT family models, as detected by `isGptModel(modelID)`, route to `gpt.md`.
653. Gemini family models, as detected by `isGeminiModel(modelID)`, route to `gemini.md`.
664. GLM family models, as detected by `isGlmModel(modelID)`, route to `glm.md`.
675. Everything else routes to `default.md`.
68 
69[`ultrawork/index.ts`](ultrawork/index.ts) exposes `getUltraworkMessage(agentName, modelID)`, switches on that source, and returns the loaded markdown body.
70 
71## DETECTION LOGIC
72 
73```
74chat.message (user input)
75  -> extractPromptText(parts)
76  -> isSystemDirective? skip
77  -> removeSystemReminders(text)  # strip <SYSTEM_REMINDER> blocks
78  -> detectKeywordsWithType(cleanText, agentName, modelID, disabledKeywords)
79  -> isNonOmoAgent(agentName)? filter keyword injection
80  -> isPlannerAgent(agentName)? filter standalone ultrawork
81  -> for each detected keyword: inject mode message into output
82```
83 
84## CONFIG
85 
86```jsonc
87{
88  "keyword_detector": {
89    // Skip injection for any keyword in this list.
90    "disabled_keywords": ["team", "hyperplan"]
91  }
92}
93```
94 
95Default: empty/missing means every detector is active. Schema lives at [`src/config/schema/keyword-detector.ts`](../../config/schema/keyword-detector.ts).
96 
97## GUARDS
98 
99- **System directive skip**: Messages tagged as system directives are not scanned (prevents infinite loops)
100- **Planner agent filter**: Prometheus/plan agents do not receive `ultrawork` injection
101- **Non-OMO agent filter**: OpenCode built-in Builder/Plan agents do not receive keyword injection
102- **Session agent tracking**: Uses `getSessionAgent()` to get actual agent (not just input hint)
103- **Model-aware messages**: `getUltraworkMessage(agentName, modelID)` adapts message to active model
104- **Ultrawork source routing**: `ultrawork/ultrawork-source-routing.test.ts` pins agent/model-to-prompt-source routing for `getUltraworkSource`
105