| name | engine |
| description | Smart assistant for the workflow engine — answers questions, invokes scripts, and navigates docs. Triggers: "engine help", "how does the engine work", "run an engine command", "what scripts are available". |
| version | 3 |
| tier | lightweight |
Smart assistant for the workflow engine — answers questions, invokes scripts, and navigates engine docs/scripts/skills.
Engine Assistant Protocol (The Operator's Manual)
[!!!] This is a sessionless utility skill. No session directory, no logging, no debrief. It boots, loads the engine index, and enters an interactive loop until the user is done.
0. Setup Phase
-
Intent: Execute §CMD_REPORT_INTENT.
0: Starting Engine Assistant. ___.
Focus: ___.
Not: ___.
-
Load Engine Index [UNCONDITIONAL — costs ~4% context, always worth it]:
Run BOTH commands in parallel — no exceptions, no skipping, no deferring:
engine --help
engine toc
These provide the complete command reference and directory structure (~283 lines / ~15 KB total). This is your knowledge base for the entire session. Load once at boot — do NOT re-run on subsequent iterations.
-
Parse User Intent: Review the user's original request (the /engine arguments). Classify it:
- Q&A — User is asking a question ("how does session.sh work?", "what's the tag lifecycle?", "explain §CMD_PARSE_PARAMETERS")
- Execute — User wants to run a command ("run doctor", "show status", "find sessions tagged #needs-review")
- Navigate — User wants to find something ("where is the fleet config?", "which doc covers context overflow?")
- Mixed — Multiple intents, or unclear. Ask for clarification.
Phase 0 always proceeds to Phase 1 — no transition question needed.
1. Interactive Loop
This phase loops until the user is done. Each iteration handles one request.
For Q&A requests:
-
Check Index: Can the question be answered from --help or toc output alone?
- If yes: Answer directly from the index. Cite the specific script/doc/skill.
- If no: Read the specific file on demand to give an authoritative answer.
-
On-Demand Reads: When the index isn't sufficient:
- Script questions: Read the script file (
~/.claude/scripts/<name>.sh) — focus on the header comments and usage section.
- Directive questions (
§CMD_*, ¶INV_*): Read from ~/.claude/.directives/COMMANDS.md or INVARIANTS.md. These are already in context from boot — search your context first.
- Doc questions: Read the specific doc file (
~/.claude/docs/<name>.md or ~/.claude/engine/docs/<name>.md).
- Skill questions: Read
~/.claude/skills/<name>/SKILL.md for the skill protocol.
- Hook questions: Read
~/.claude/hooks/<name>.sh for hook behavior.
- Tag questions: The tag system is defined in
SIGILS.md (already in context from boot).
-
Answer Format: Be precise and cite sources. When referencing files, use clickable links per ¶INV_TERMINAL_FILE_LINKS. Include relevant command examples when helpful.
For Execute requests:
-
Parse Command: Determine the exact engine <subcommand> [args] to run.
-
Confirm Before Running: Execute AskUserQuestion showing the command and alternatives:
Present the command and context before asking:
Command: engine <subcommand> [args]
What it does: [1-2 sentence description]
Side effects: [list any state changes, file modifications, or network calls]
Then ask via AskUserQuestion (multiSelect: false):
"Run this command?"
Options vary by command — always include the proposed command and cancel. Add helpful alternatives when relevant:
- "Run:
engine <cmd>" — Execute the command
- "[Alternative command if relevant]" — [why this might be better]
- "Cancel" — Don't run anything
Examples of helpful alternatives:
- User asks
engine status → also offer engine report ("more detailed system health report")
- User asks
engine tag find '#needs-review' → also offer adding --context flag ("includes surrounding text")
- User asks
engine push → remind about engine test first ("run tests before pushing")
-
Execute: Run the confirmed command via Bash. Display the output.
-
Interpret: After running, explain the output if it's not self-evident. Flag any warnings or errors.
For Navigate requests:
- Search the index (
toc output) for the relevant file or directory.
- Provide the path as a clickable link per
¶INV_TERMINAL_FILE_LINKS.
- Offer to read: "Want me to read this file and explain it?"
Iteration:
After handling each request, wait for the user's next message. Do NOT proactively ask "What else?" — just wait. The user will either:
- Ask another question → handle it
- Invoke another skill → let the skill system handle it
- Say nothing → session ends naturally
Key Reference: Engine Command Categories
Use this as a quick lookup when helping users find the right command.
| Need | Command | Notes |
|---|
| Launch Claude | engine or engine run | Default behavior |
| Start fleet | engine fleet start | Multi-agent workspace |
| Full setup | engine setup | First-time or repair |
| Check health | engine status (quick) or engine report (detailed) | |
| Manage sessions | engine session <cmd> | activate, phase, deactivate, check |
| Manage tags | engine tag <cmd> | add, remove, swap, find |
| Search sessions | engine session-search query "text" or engine find-sessions <filter> | Semantic vs structured |
| Search docs | engine doc-search query "text" | Semantic search |
| Validate engine | engine doctor [-v] [dir] | Skills, CMDs, directives, sessions, sigils |
| View engine tree | engine toc | All files in ~/.claude/ |
| Git operations | engine push, engine pull, engine deploy | Engine source control |
| Switch mode | engine local or engine remote | Local dev vs GDrive |
| Run tests | engine test | Engine test suite |
| Uninstall | engine uninstall | Remove all engine symlinks |
Key Reference: Documentation Map
| Topic | File | Location |
|---|
| Engine philosophy | WHY_ENGINE.md | ~/.claude/docs/ |
| CLI protocol | ENGINE_CLI.md | ~/.claude/docs/ |
| Session lifecycle | SESSION_LIFECYCLE.md | ~/.claude/docs/ |
| Directive system | DIRECTIVES_SYSTEM.md | ~/.claude/docs/ |
| Day-to-day usage | WORKFLOW.md | ~/.claude/docs/ |
| Tag lifecycle | TAG_LIFECYCLE.md | ~/.claude/docs/ |
| Fleet workspace | FLEET.md | ~/.claude/docs/ |
| Context overflow | CONTEXT_GUARDIAN.md | ~/.claude/docs/ |
| Daemon dispatch | DAEMON.md | ~/.claude/docs/ |
| Guards & gates | AUTOMATIC_GUARDS.md | ~/.claude/docs/ |
| Testing | ENGINE_TESTING.md | ~/.claude/docs/ |
| Hooks | HOOKS.md | ~/.claude/docs/ |
| Doc indexing | DOCUMENT_INDEXING.md | ~/.claude/docs/ |
| Commands vocabulary | COMMANDS.md | ~/.claude/.directives/ |
| System invariants | INVARIANTS.md | ~/.claude/.directives/ |
| Tag conventions | SIGILS.md | ~/.claude/.directives/ |
