fix(ambient): ensure skill tool invocations happen before text output (#158)

## Summary
- Ambient mode skills were not loading despite correct
GUIDED/ORCHESTRATED classification
- Root cause: model prints "Loading: X, Y" text then skips actual
`Skill()` tool calls — generating prose overrides the tool-call
requirement
- Fix: reverse instruction order in ambient-router SKILL.md and hook
preamble so Skill tool invocations must happen **before** any text
output

## Changes
- `shared/skills/ambient-router/SKILL.md` — IMPORTANT block and Step 4
now require tool calls first, classification text after
- `scripts/hooks/ambient-prompt` — preamble reinforces "FIRST tool calls
MUST be Skill tool invocations"
- `tests/integration/helpers.ts` — sync preamble string
- `tests/ambient.test.ts` — sync drift detection expected value
- `CHANGELOG.md` — add fix to [Unreleased]

## Test plan
- [x] Build passes (`npm run build`)
- [x] All 362 tests pass (`npm test`)
- [x] Preamble drift detection test passes (verifies hook ↔ helpers
sync)

Co-authored-by: Dean Sharon <deanshrn@gmain.com>

Author: dean0x

CHANGELOG.md

@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+- **Ambient mode**: skills not loading despite correct classification — reordered instructions so Skill tool invocations happen before any text output
+
 ---
 
 ## [1.8.1] - 2026-03-22

scripts/hooks/ambient-prompt

@@ -40,7 +40,7 @@ fi
 
 # Inject classification preamble
 # SYNC: must match tests/integration/helpers.ts AMBIENT_PREAMBLE
-PREAMBLE="AMBIENT MODE ACTIVE: Before responding, silently classify this prompt using the ambient-router skill already in your session context. If QUICK, respond normally without stating classification. If GUIDED or ORCHESTRATED, you MUST load the selected skills using the Skill tool before proceeding."
+PREAMBLE="AMBIENT MODE ACTIVE: Before responding, silently classify this prompt using the ambient-router skill already in your session context. If QUICK, respond normally without stating classification. If GUIDED or ORCHESTRATED, your FIRST tool calls MUST be Skill tool invocations for each selected skill — before writing ANY text about the task."
 
 jq -n --arg ctx "$PREAMBLE" '{
   "hookSpecificOutput": {

shared/skills/ambient-router/SKILL.md

@@ -87,16 +87,18 @@ See `references/skill-catalog.md` for the full skill-to-intent mapping with file
 <IMPORTANT>
 When classification is GUIDED or ORCHESTRATED, skill loading is NON-NEGOTIABLE.
 Do not rationalize skipping skills. Do not respond without loading them first.
-BLOCKING REQUIREMENT: Invoke each selected skill using the Skill tool before proceeding.
+BLOCKING REQUIREMENT: Your FIRST tool calls MUST be Skill tool invocations — before
+writing ANY text about the task. Invoke all selected skills, THEN state classification,
+THEN proceed with work. Do NOT write implementation text before all Skill tools return.
 For IMPLEMENT intent, enforce TDD: write the failing test before ANY production code.
 NOTE: Skills loaded in the main session via ambient mode are reference patterns only —
 their allowed-tools metadata does NOT restrict your tool access. You retain full access
 to all tools (Edit, Write, Bash, Agent, etc.) for implementation work.
 </IMPORTANT>
 
 - **QUICK:** Respond directly. No preamble, no classification statement.
-- **GUIDED:** State classification briefly: `Ambient: IMPLEMENT/GUIDED. Loading: implementation-patterns, search-first.` Then invoke each skill using the Skill tool and work directly in main session. After code changes, spawn Simplifier on changed files.
-- **ORCHESTRATED:** State classification briefly: `Ambient: IMPLEMENT/ORCHESTRATED. Loading: implementation-orchestration, implementation-patterns.` Then invoke each skill using the Skill tool and follow Step 5 for agent orchestration.
+- **GUIDED:** First, invoke each selected skill using the Skill tool. After all Skill tools return, state classification briefly: `Ambient: IMPLEMENT/GUIDED. Loading: implementation-patterns, search-first.` Then work directly in main session. After code changes, spawn Simplifier on changed files.
+- **ORCHESTRATED:** First, invoke each selected skill using the Skill tool. After all Skill tools return, state classification briefly: `Ambient: IMPLEMENT/ORCHESTRATED. Loading: implementation-orchestration, implementation-patterns.` Then follow Step 5 for agent orchestration.
 
 ### GUIDED Behavior by Intent
 

tests/ambient.test.ts

@@ -260,7 +260,7 @@ describe('preamble drift detection', () => {
     // The helpers.ts AMBIENT_PREAMBLE is used by extractIntent/extractDepth etc.
     // We verify it indirectly by checking the shell script value matches expected.
     const expectedPreamble =
-      'AMBIENT MODE ACTIVE: Before responding, silently classify this prompt using the ambient-router skill already in your session context. If QUICK, respond normally without stating classification. If GUIDED or ORCHESTRATED, you MUST load the selected skills using the Skill tool before proceeding.';
+      'AMBIENT MODE ACTIVE: Before responding, silently classify this prompt using the ambient-router skill already in your session context. If QUICK, respond normally without stating classification. If GUIDED or ORCHESTRATED, your FIRST tool calls MUST be Skill tool invocations for each selected skill — before writing ANY text about the task.';
 
     expect(shellPreamble).toBe(expectedPreamble);
   });

tests/integration/helpers.ts

@@ -17,7 +17,7 @@ export function isClaudeAvailable(): boolean {
 
 // SYNC: must match scripts/hooks/ambient-prompt line 43
 const AMBIENT_PREAMBLE =
-  'AMBIENT MODE ACTIVE: Before responding, silently classify this prompt using the ambient-router skill already in your session context. If QUICK, respond normally without stating classification. If GUIDED or ORCHESTRATED, you MUST load the selected skills using the Skill tool before proceeding.';
+  'AMBIENT MODE ACTIVE: Before responding, silently classify this prompt using the ambient-router skill already in your session context. If QUICK, respond normally without stating classification. If GUIDED or ORCHESTRATED, your FIRST tool calls MUST be Skill tool invocations for each selected skill — before writing ANY text about the task.';
 
 /**
  * Run a prompt through claude CLI in non-interactive mode.