Token optimization: reduce plugin overhead by 55% (20K→9K tokens)

## Conditional Orchestrator Injection
- SessionStart injects 40-line routing stub (~200 tokens) instead of
  full 545-line orchestrator (~5.5K tokens)
- Full orchestrator loads on-demand via /delegate command only
- Sessions that don't use multi-step delegation save ~5K tokens

## Prompt Compression
- Orchestrator slimmed 49% (1065→545 lines)
- /delegate template compressed 89% (4955→555 chars)
- Agent definitions deduplicated 47% (640→339 lines)
- Delegation error messages compressed 57%, no emoji

## Token Efficiency Enhancements
- DONE|{path} return format enforced in all 8 agent definitions
- Partial file read guidance (offset/limit for >200 lines)
- cd && command pattern handling in rewrite hook
- Added eslint, next lint, tsc to output compression
- Conversation filler reduction rules in output style

## Agent Teams as Default
- Team mode detection via TeamCreate tool availability (not Bash env check)
- Mandatory TeamCreate + Agent(team_name=...) when teams available
- Isolated subagents only as fallback when TeamCreate fails
- Team check is FIRST ACTION before any planning

## Cleanup
- Deleted deprecated task-planner skill (-622 lines)
- Planning exclusively via native EnterPlanMode
- Updated all documentation (CLAUDE.md, README.md, docs/)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: barkain

CLAUDE.md

@@ -46,15 +46,14 @@ uvx ruff format .                # Format code (auto-fix)
 uvx ruff check --no-fix .       # Lint code (check only)
 uvx pyright .                    # Type checking
 uvx deadcode hooks/ scripts/    # Dead code detection
-uvx pytest tests/ -v            # Run test suite
 ```
 
 The PostToolUse hook enforces a specific ruff rule subset on edited Python files:
 ```bash
 uvx ruff check --select F,E711,E712,UP006,UP007,UP035,UP037,T201,S <file>
 ```
 
-Test suite exists in `tests/` with comprehensive coverage for hooks and token efficiency features.
+CI workflow exists (`.github/workflows/ci.yml`) but tests are currently disabled/placeholder.
 
 ---
 
@@ -80,6 +79,8 @@ In plugin mode, agent/skill names use prefix `workflow-orchestrator:` (e.g., `wo
 
 ### Execution Flow
 
+**Token overhead:** System prompt (~11K tokens: orchestrator + CLAUDE.md + efficiency guidance) + per-agent delegation (~350 tokens)
+
 ```
 User prompt
   → UserPromptSubmit hook (clear state, record turn timestamp, clear team state)
@@ -106,11 +107,11 @@ User prompt
   → Stop hook: calculate turn duration, quality analysis
 ```
 
-### Hook System (6 lifecycle events, 15 scripts)
+### Hook System (6 lifecycle events, 12 scripts)
 
 | Event | Scripts | Purpose |
 |-------|---------|---------|
-| **PreToolUse** (`*`, `Bash`) | `require_delegation.py`, `validate_task_graph_compliance.py`, `token_rewrite_hook.py` | Block non-allowed tools; validate Agent/Task invocations against active task graph; rewrite Bash commands for token efficiency |
+| **PreToolUse** (`*`, `Bash`) | `require_delegation.py`, `validate_task_graph_compliance.py`, `token_rewrite_hook.py` | Block non-allowed tools (compressed error messages); validate Agent/Task invocations against active task graph; rewrite Bash commands for token efficiency |
 | **PostToolUse** | `python_posttooluse_hook.py` (Edit/Write/MultiEdit), `remind_skill_continuation.py` (ExitPlanMode\|Skill\|SlashCommand), `validate_task_graph_depth.py` + `remind_todo_after_task.py` (Agent/Task) | Python validation (Ruff, Pyright, security), workflow continuation state (triggers on ExitPlanMode for plan mode flows), depth-3 enforcement, task reminders |
 | **UserPromptSubmit** | `clear-delegation-sessions.py` | Clear delegation state, record turn start timestamp, clear team state (`team_mode_active`, `team_config.json`), rotate logs |
 | **SessionStart** (`startup\|resume\|clear\|compact`) | `inject_workflow_orchestrator.py`, `inject-output-style.py`, `inject_token_efficiency.py` | Inject system prompt + output style + token efficiency guidance |
@@ -144,7 +145,6 @@ Special cases:
 
 ### Skills (forked context)
 
-- **task-planner** (`skills/task-planner/SKILL.md`): Legacy planning skill, retained for reference/backward compatibility. The core planning logic (complexity scoring, tier classification, agent assignment, wave scheduling, task creation) has been absorbed into `system-prompts/workflow_orchestrator.md` and now executes as native plan mode (EnterPlanMode/ExitPlanMode) directly in the main agent context rather than a forked skill context.
 - **breadth-reader** (`skills/breadth-reader/SKILL.md`): Lightweight read-only breadth tasks. Spawns `Explore` subagents (Haiku). Returns summary only.
 
 ### Specialized Agents (8)
@@ -191,7 +191,10 @@ Two team workflow patterns:
 
 Agent selection uses keyword matching (≥2 matches threshold, highest count wins). Falls back to general-purpose if 0-1 matches. See `system-prompts/workflow_orchestrator.md` for keyword lists.
 
-Agent config format: YAML frontmatter (`name`, `description`, optional `tools`/`model`/`color`) + markdown system prompt body. All agents enforce `DONE|{output_file}` return format.
+Agent config format: YAML frontmatter (`name`, `description`, optional `tools`/`model`/`color`) + markdown system prompt body. All agents enforce `DONE|{output_file}` return format. Custom agent instructions include:
+- Return format must be exactly `DONE|{output_file_path}` (no summaries or explanations)
+- Write directly to output file using Write tool (do not delegate writing)
+- If Write is blocked, report error and stop (do not retry)
 
 ### State Files (Runtime)
 
@@ -252,9 +255,11 @@ Agent config format: YAML frontmatter (`name`, `description`, optional `tools`/`
 
 Minimize command output to reduce context consumption. Enabled by default (`CLAUDE_TOKEN_EFFICIENCY=1`).
 
-**Two-layer approach:**
+**Multi-layer approach:**
 1. **Behavioral guidance** (`system-prompts/token_efficient_cli.md`): Injected via SessionStart, teaches compact flag usage (e.g., `git status -sb`, `pytest -q --tb=short`)
 2. **Output compression** (`hooks/compact_run.py`): PreToolUse hook rewrites matching Bash commands through `compact_run.py`, which compresses git/test/log output post-execution
+3. **Partial file reads**: Use Read tool with `offset` and `limit` parameters for files >200 lines to avoid loading entire file contents into context
+4. **Compressed error messages**: Delegation error messages are optimized for minimal token consumption
 
 **Supported command families:** git (push/pull/commit/etc), pytest, cargo test, npm/pnpm/yarn/bun test, npx (vitest/jest/mocha/playwright), go test, make test/check, docker/kubectl logs
 

README.md

@@ -252,14 +252,14 @@ The `plugin-hooks.json` configures the delegation enforcement hooks using cross-
 
 **Note:** All hooks use `uv run --no-project --script` for cross-platform compatibility (Windows, macOS, Linux). The `--no-project` flag allows execution without requiring a pyproject.toml, and `--script` directly runs Python scripts using uv's managed interpreter.
 
-**Hook Events (6 lifecycle points, 15 scripts):**
+**Hook Events (6 lifecycle points, 14 hooks):**
 
 | Event | Scripts | Purpose |
 |-------|---------|---------|
-| **PreToolUse** | `validate_task_graph_compliance.py`, `require_delegation.py`, `token_rewrite_hook.py` (Bash only) | Validate task graph compliance; block non-delegated tools; rewrite Bash commands for token efficiency |
+| **PreToolUse** | `validate_task_graph_compliance.py`, `require_delegation.py`, `token_rewrite_hook.py` (Bash only) | Validate task graph compliance; block non-delegated tools; rewrite Bash commands for token efficiency (cd && pattern, eslint, next, tsc support) |
 | **PostToolUse** | `python_posttooluse_hook.py` (Edit/Write), `remind_skill_continuation.py` (ExitPlanMode/Skill/SlashCommand), `validate_task_graph_depth.py` (Agent/Task), `remind_todo_after_task.py` (Agent/Task, async) | Python validation (Ruff/Pyright); workflow continuation state; depth-3 enforcement; task reminders |
 | **UserPromptSubmit** | `clear-delegation-sessions.py` | Clear delegation/team state, record turn timestamp |
-| **SessionStart** | `inject_workflow_orchestrator.py`, `inject-output-style.py`, `inject_token_efficiency.py` | Inject system prompts (workflow orchestration, output style, token efficiency) |
+| **SessionStart** | `inject_workflow_orchestrator.py`, `inject-output-style.py`, `inject_token_efficiency.py` | Inject conditional orchestrator (stub on startup, full on /delegate), output style, token efficiency guidance |
 | **SubagentStop** | `remind_todo_update.py` (async), `trigger_verification.py` | Remind to update tasks, suggest verification |
 | **Stop** | `python_stop_hook.py` | Turn duration tracking, workflow continuation |
 
@@ -268,22 +268,10 @@ The `plugin-hooks.json` configures the delegation enforcement hooks using cross-
 Multi-step workflow orchestration requires the workflow_orchestrator system prompt to be appended:
 
 **Automatic (via SessionStart hook):**
-```json
-{
-  "hooks": {
-    "SessionStart": [
-      {
-        "hooks": [
-          {
-            "type": "append_system_prompt",
-            "path": "system-prompts/workflow_orchestrator.md"
-          }
-        ]
-      }
-    ]
-  }
-}
-```
+
+The `inject_workflow_orchestrator.py` hook uses conditional injection:
+- **On startup/resume:** Injects a lightweight stub that registers `/delegate` and `/bypass` commands without loading the full orchestrator prompt, keeping baseline token overhead minimal.
+- **On `/delegate` invocation:** The full `workflow_orchestrator.md` system prompt is loaded on-demand, providing the complete planning and execution logic only when needed.
 
 **What this enables:**
 - Multi-step task detection via pattern matching
@@ -415,7 +403,7 @@ No other configuration is required. Plan mode automatically evaluates whether a
 
 ### How Mode Selection Works
 
-During planning, plan mode calculates a `team_mode_score` based on task characteristics:
+During planning, plan mode checks if the TeamCreate tool is available (indicator that Agent Teams are enabled). If available, it calculates a `team_mode_score` based on task characteristics:
 
 | Factor                                | Points | Condition                                              |
 |---------------------------------------|--------|--------------------------------------------------------|
@@ -428,7 +416,7 @@ During planning, plan mode calculates a `team_mode_score` based on task characte
 | Breadth task                          | -5     | Simple exploration is better as subagents               |
 | Phase count <= 3                      | -3     | Small workflows don't need team overhead                |
 
-A score of **5 or higher** (with `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`) triggers team mode. Otherwise, subagent mode is used.
+Default to team mode when Agent Teams available (TeamCreate in tools). Falls back to subagent only when `team_mode_score <= -3` (breadth-only tasks). If TeamCreate tool is not available (env var not set), subagent mode is always selected.
 
 ### Subagent Mode vs Team Mode
 
@@ -503,7 +491,7 @@ Team mode creates two additional state files (automatically cleaned up on comple
 
 The framework minimizes command output to reduce context consumption and preserve tokens for meaningful work. Token efficiency is enabled by default (`CLAUDE_TOKEN_EFFICIENCY=1`).
 
-### Two-Layer Approach
+### Multi-Layer Approach
 
 1. **Behavioral Guidance** — The `token_efficient_cli.md` system prompt (injected via SessionStart) teaches compact flag usage:
    - `git status -sb` (short branch format)
@@ -515,6 +503,13 @@ The framework minimizes command output to reduce context consumption and preserv
    - Git: `push`, `pull`, `commit`, `merge`, `rebase`, `status`, etc.
    - Test runners: `pytest`, `cargo test`, `npm/pnpm/yarn/bun test`, `vitest`, `jest`, `mocha`, etc.
    - Logs: `docker logs`, `kubectl logs`, `make` output
+   - Build tools: `eslint`, `next`, `tsc`
+   - Command chaining: `cd && command` pattern support
+
+3. **Conditional System Prompt Injection** — The orchestrator is injected conditionally:
+   - On session startup: Stub version (~200 tokens) provides minimal direction
+   - On first plan mode entry (via /delegate or detected multi-step): Full version (~11K tokens) for complete planning capability
+   - Saves tokens for single-step and read-only tasks
 
 ### Disable Token Efficiency
 

agents/code-cleanup-optimizer.md

@@ -3,23 +3,10 @@ name: code-cleanup-optimizer
 description: Remove technical debt, improve quality, eliminate redundancy after implementation is verified. Never use before functionality works correctly.
 ---
 
-## RETURN FORMAT (CRITICAL - READ FIRST)
+## RETURN FORMAT (CRITICAL)
 
-**Your response to the main agent must be EXACTLY:**
-```
-DONE|{output_file_path}
-```
-
-**Example:** `DONE|$CLAUDE_SCRATCHPAD_DIR/cleanup_utils_module.md`
-
-**WHY:** Main agent context is limited. Full findings go in the file. Return value only confirms completion + path.
-
-**PROHIBITED in return value:**
-- Summaries
-- Findings
-- Recommendations
-- Explanations
-- Anything except `DONE|{path}`
+Return EXACTLY: `DONE|{output_file_path}` — nothing else. Example: `DONE|$CLAUDE_SCRATCHPAD_DIR/cleanup_utils_module.md`
+All findings go in the output file. No summaries, explanations, or text beyond `DONE|{path}` in return value.
 
 ---
 
@@ -42,32 +29,11 @@ Explain why changes improve the code. Distinguish critical improvements from nic
 
 ## COMMUNICATION MODE
 
-**If operating as a teammate in an Agent Team** (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1):
-- Write detailed output to the output_file path as usual
-- Send a brief completion message to the team: "Completed: {subject}. Output at {output_file}."
-- If you need clarification from another teammate, message them directly
-- If you discover issues that affect another teammate's work, message them proactively
-- NEVER call TeamCreate -- only the lead agent creates teams (no nested teams)
-- Before writing to a file another teammate might also modify, coordinate via SendMessage first
-
-**If operating as a subagent (Agent tool):**
-- Return EXACTLY: `DONE|{output_file_path}`
-- No summaries, no explanations -- only the path
+**Teammate mode** (Agent Teams): Write output to file, send brief completion message via SendMessage. Message teammates directly for clarification or cross-cutting issues. Never call TeamCreate.
+**Subagent mode**: Return EXACTLY `DONE|{output_file_path}`, nothing else.
 
----
-
-## CLI Efficiency (MANDATORY)
-
-Use compact CLI flags to minimize output tokens:
-- Git: `--quiet` on push/pull/commit, `-sb` on status, `--oneline -n 10` on log, `--stat` on diff
-- Tests: `pytest -q --tb=short --no-header`, `npm test -- --silent`
-- Ruff: ALWAYS `ruff check --output-format concise --quiet`, NEVER bare `ruff check`
-- Files: `ls -1` not `ls -la`, `head -50` not `cat`, `wc -l` before reading
-- Search: `rg -l` for file list, `rg -m 5` to cap matches, scope to directories
-- Always: `| head -N` when output may exceed 50 lines, `--no-pager` on git
+## CLI Efficiency
+Follow MANDATORY compact CLI rules: git `-sb`/`--quiet`/`--oneline -n 10`, ruff `--output-format concise --quiet`, pytest `-q --tb=short`, `ls -1`, `head -50` not `cat`, `rg -l`/`-m 5`, `| head -N` for >50 lines. Read: `offset`/`limit` for files >200 lines; grep-then-partial-read for CLAUDE.md.
 
 ## FILE WRITING
-
-- You HAVE Write tool access for the scratchpad directory ($CLAUDE_SCRATCHPAD_DIR)
-- Write directly to the output_file path - do NOT delegate writing
-- If Write is blocked, report error and stop (do not loop)
+Write to $CLAUDE_SCRATCHPAD_DIR output_file path directly. If Write blocked, report error and stop.

agents/code-reviewer.md

@@ -6,23 +6,10 @@ color: red
 activation_keywords: ["review code", "code review", "check implementation", "validate function", "review this", "best practices", "code quality", "refactor review", "implementation review"]
 ---
 
-## RETURN FORMAT (CRITICAL - READ FIRST)
+## RETURN FORMAT (CRITICAL)
 
-**Your response to the main agent must be EXACTLY:**
-```
-DONE|{output_file_path}
-```
-
-**Example:** `DONE|$CLAUDE_SCRATCHPAD_DIR/review_code.md`
-
-**WHY:** Main agent context is limited. Full findings go in the file. Return value only confirms completion + path.
-
-**PROHIBITED in return value:**
-- Summaries
-- Findings
-- Recommendations
-- Explanations
-- Anything except `DONE|{path}`
+Return EXACTLY: `DONE|{output_file_path}` — nothing else. Example: `DONE|$CLAUDE_SCRATCHPAD_DIR/review_code.md`
+All findings go in the output file. No summaries, explanations, or text beyond `DONE|{path}` in return value.
 
 ---
 
@@ -38,30 +25,11 @@ Provide specific, actionable feedback explaining the 'why' behind recommendation
 
 ## COMMUNICATION MODE
 
-**If operating as a teammate in an Agent Team** (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1):
-- Write detailed output to the output_file path as usual
-- Send a brief completion message to the team: "Completed: {subject}. Output at {output_file}."
-- If you need clarification from another teammate, message them directly
-- If you discover issues that affect another teammate's work, message them proactively
-- NEVER call TeamCreate -- only the lead agent creates teams (no nested teams)
-- Before writing to a file another teammate might also modify, coordinate via SendMessage first
+**Teammate mode** (Agent Teams): Write output to file, send brief completion message via SendMessage. Message teammates directly for clarification or cross-cutting issues. Never call TeamCreate.
+**Subagent mode**: Return EXACTLY `DONE|{output_file_path}`, nothing else.
 
-**If operating as a subagent (Agent tool):**
-- Return EXACTLY: `DONE|{output_file_path}`
-- No summaries, no explanations -- only the path
-
-## CLI Efficiency (MANDATORY)
-
-Use compact CLI flags to minimize output tokens:
-- Git: `--quiet` on push/pull/commit, `-sb` on status, `--oneline -n 10` on log, `--stat` on diff
-- Tests: `pytest -q --tb=short --no-header`, `npm test -- --silent`
-- Ruff: ALWAYS `ruff check --output-format concise --quiet`, NEVER bare `ruff check`
-- Files: `ls -1` not `ls -la`, `head -50` not `cat`, `wc -l` before reading
-- Search: `rg -l` for file list, `rg -m 5` to cap matches, scope to directories
-- Always: `| head -N` when output may exceed 50 lines, `--no-pager` on git
+## CLI Efficiency
+Follow MANDATORY compact CLI rules: git `-sb`/`--quiet`/`--oneline -n 10`, ruff `--output-format concise --quiet`, pytest `-q --tb=short`, `ls -1`, `head -50` not `cat`, `rg -l`/`-m 5`, `| head -N` for >50 lines. Read: `offset`/`limit` for files >200 lines; grep-then-partial-read for CLAUDE.md.
 
 ## FILE WRITING
-
-- You HAVE Write tool access for the scratchpad directory ($CLAUDE_SCRATCHPAD_DIR)
-- Write directly to the output_file path - do NOT delegate writing
-- If Write is blocked, report error and stop (do not loop)
+Write to $CLAUDE_SCRATCHPAD_DIR output_file path directly. If Write blocked, report error and stop.