Token optimization: reduce plugin overhead by 55% and enforce Agent Teams (#36)

* 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>

* Fix uncaught exception exit code in require_delegation hook

Change exit code from 0 (fail-open) to 1 (internal error) in the
uncaught exception handler, per hook exit code convention:
0=allow, 1=error, 2=block. Addresses Qodo review feedback on PR #36.

* Fix Qodo review issues: PEP 723 blocks, execution_mode threshold, npx next output, delegate allowlist

- Add PEP 723 inline metadata to inject_workflow_orchestrator.py and require_delegation.py
- Fix execution_mode selection to fall back to subagent when team_mode_score <= -3 (not just breadth tasks)
- Fix npx next output suppression: only compress 'next lint', pass through other next commands
- Update delegate.md allowed-tools to include all required tools (EnterPlanMode, ExitPlanMode, TaskCreate, etc.)

* Fix execution_mode threshold to match CLAUDE.md policy (>= 5 for team, < 5 for subagent)

Aligns workflow_orchestrator.md team_mode_score decision logic with the
documented policy in CLAUDE.md. The previous threshold (> -3) effectively
restricted subagent fallback to breadth-only tasks. The correct threshold
(>= 5) ensures subagent mode is selected whenever the score indicates
insufficient complexity for team coordination.

* Fix team_mode_score threshold: default to team mode unless score <= -3

Align execution mode selection policy so that team mode is the default
when Agent Teams is enabled, falling back to subagent only when
team_mode_score <= -3 (previously required score >= 5 to use teams).
Updated both workflow_orchestrator.md and CLAUDE.md for consistency.

* fix: correct next lint test to use proper subcommand args

* fix: enable Claude Code Review to post PR comments

- Remove plugin-based review approach (code-review@claude-code-plugins)
  that was not posting comments correctly
- Use standard auto-detected review mode for pull_request events
- Add missing permissions: issues: write, actions: read
- Add additional_permissions for CI result reading
- Use prompt input for review instructions instead of plugin skill invocation

* docs: update architecture and environment variable documentation

* fix: normalize DONE format and prevent wrapping long-running npx commands

* Fix ruff formatting in token_rewrite_hook.py

Resolves CI linting failure caused by unformatted code.

* Fix delegate command allowed-tools: add ToolSearch, TeamCreate, SendMessage

---------

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

Author: barkain

.github/workflows/claude-code-review.yml

@@ -26,7 +26,9 @@ jobs:
     permissions:
       contents: read
       pull-requests: write
+      issues: write
       id-token: write
+      actions: read
 
     steps:
       - name: Checkout repository
@@ -39,9 +41,11 @@ jobs:
         uses: anthropics/claude-code-action@v1
         with:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
-          plugin_marketplaces: 'https://github.com/anthropics/claude-code.git'
-          plugins: 'code-review@claude-code-plugins'
-          prompt: '/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }}'
+          prompt: |
+            Review this PR for code quality, potential bugs, and improvements.
+            Focus on meaningful issues rather than style nits.
+          additional_permissions: |
+            actions: read
           # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
           # or https://code.claude.com/docs/en/cli-reference for available options
         env:

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,13 +79,16 @@ In plugin mode, agent/skill names use prefix `workflow-orchestrator:` (e.g., `wo
 
 ### Execution Flow
 
+**Token overhead:** Conditional injection (stub ~200 tokens on startup, full ~11K tokens on first delegation) + per-agent delegation (~350 tokens)
+
 ```
 User prompt
   → UserPromptSubmit hook (clear state, record turn timestamp, clear team state)
-  → SessionStart hooks (inject workflow_orchestrator.md + output style)
-  → workflow_orchestrator detects multi-step → enters native plan mode (EnterPlanMode)
-  → plan mode: main agent explores codebase, decomposes, assigns agents, creates tasks via TaskCreate
-  → plan mode: evaluates execution_mode (subagent vs team via team_mode_score)
+  → SessionStart hooks (inject stub orchestrator + output style + token efficiency)
+    [Stub version provides just enough system direction, avoiding unnecessary tokens]
+  → Task detection: if multi-step connectors found, enters native plan mode (EnterPlanMode)
+  → plan mode: injects full workflow_orchestrator, explores codebase, decomposes, assigns agents, creates tasks via TaskCreate
+  → plan mode: evaluates execution_mode (subagent vs team via TeamCreate tool availability)
   → plan mode: exits via ExitPlanMode (requires lead approval)
   → PostToolUse hook (remind_skill_continuation.py): creates workflow_continuation_needed.json on ExitPlanMode
   → After ExitPlanMode approval, main agent continues to Stage 1
@@ -96,7 +98,7 @@ User prompt
     → Agents write to $CLAUDE_SCRATCHPAD_DIR, return DONE|{path}
     → SubagentStop hooks: remind task update, suggest verification
     → Main agent: TaskUpdate to mark completed, proceed to next wave
-  → TEAM MODE (experimental, CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1):
+  → TEAM MODE (when TeamCreate tool is available):
     → Create .claude/state/team_mode_active + team_config.json
     → TeamCreate(team_name=...), then Agent(team_name=...) for each teammate with agent configs
     → Create shared tasks with dependencies, bridge to framework Tasks API
@@ -106,22 +108,22 @@ User prompt
   → Stop hook: calculate turn duration, quality analysis
 ```
 
-### Hook System (6 lifecycle events, 15 scripts)
+### Hook System (6 lifecycle events, 14 hooks)
 
 | 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`) | `validate_task_graph_compliance.py`, `require_delegation.py`, `token_rewrite_hook.py` (Bash only) | Validate Agent/Task invocations against active task graph; block non-allowed tools (compressed error messages); rewrite Bash commands for token efficiency (cd && pattern, eslint, next, tsc) |
 | **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 |
+| **SessionStart** (`startup\|resume\|clear\|compact`) | `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, workflow continuation (block stop + inject "continue"), quality analysis |
 
 Hook config source of truth: `hooks/plugin-hooks.json` (not settings.json). All hooks are Python for cross-platform compatibility (Windows/macOS/Linux).
 
 ### Tool Allowlist
 
-Main agent can only use: `AskUserQuestion`, `TaskCreate`, `TaskUpdate`, `TaskList`, `TaskGet`, `Skill`, `SlashCommand`, `Agent`, `Task`, `SubagentTask`, `AgentTask`, `EnterPlanMode`, `ExitPlanMode`, `ToolSearch`
+Main agent can only use: `AskUserQuestion`, `TaskCreate`, `TaskUpdate`, `TaskList`, `TaskGet`, `Skill`, `SlashCommand`, `Agent`, `Task`, `SubagentTask`, `AgentTask`, `EnterPlanMode`, `ExitPlanMode`, `ToolSearch`, `CronCreate`, `CronDelete`, `CronList`
 
 Special cases:
 - `Write` tool allowed for temp/scratchpad paths only (`/tmp/`, `/private/tmp/`, `/var/folders/`)
@@ -144,9 +146,10 @@ 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.
 
+**Note:** The `task-planner` skill has been removed. Its orchestration and planning functionality is now provided by native plan mode (EnterPlanMode/ExitPlanMode), which handles both planning and execution orchestration directly within the main agent context.
+
 ### Specialized Agents (8)
 
 | Agent | Domain |
@@ -176,12 +179,13 @@ Two team workflow patterns:
 - **Team mode (simple):** Single AGENT TEAM phase with `phase_type: "team"` and `teammates` array -- used for multi-perspective exploration (e.g., "explore from different angles")
 - **Team mode (complex):** Multiple individual phases across waves, all executed as teammates via `Agent(team_name=...)` -- used for collaborative implementation (e.g., "implement project, tasks should be collaborative"). The plan has `execution_mode: "team"` at the top level; no individual phase needs `phase_type: "team"`
 
-**Mode selection** uses `team_mode_score` (calculated during plan mode):
-- Phase count >8: +2, Tier 3 complexity: +2, cross-phase data flow: +3
-- Review-fix cycles: +3, iterative refinement: +2, user keyword "collaborate"/"team": +5
-- Breadth task: -5, phase count <=3: -3
-- With `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`: default to team mode; only fall back to subagent when `team_mode_score <= -3` (breadth-only tasks)
-- Without env var: always parallel subagent mode (≥2 subtasks mandatory)
+**Mode selection** is based on TeamCreate tool availability (detected during plan mode):
+- **If TeamCreate tool is available** (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 is set): Calculate `team_mode_score` to determine whether to use team mode or subagent mode
+  - Phase count >8: +2, Tier 3 complexity: +2, cross-phase data flow: +3
+  - Review-fix cycles: +3, iterative refinement: +2, user keyword "collaborate"/"team": +5
+  - Breadth task: -5, phase count <=3: -3
+  - Default to team mode (score not calculated, absent, or > -3); use subagent mode only when score <= -3
+- **If TeamCreate tool is not available** (env var not set): Always use subagent mode (≥2 subtasks mandatory)
 
 **When team mode is active:**
 - `validate_task_graph_compliance.py` hook is bypassed (team handles dependencies)
@@ -191,7 +195,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)
 
@@ -241,7 +248,7 @@ Agent config format: YAML frontmatter (`name`, `description`, optional `tools`/`
 | `CLAUDE_PLUGIN_ROOT` | Not set | Set by plugin system for path resolution |
 | `CLAUDE_SCRATCHPAD_DIR` | Per-session | Session-isolated temp dir for agent output |
 | `CLAUDE_PROJECT_DIR` | `$PWD` | State directory base path |
-| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | `0` | Enable Agent Teams dual-mode (`1` to enable team mode scoring and tools) |
+| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | `0` | Enable Agent Teams (TeamCreate tool availability and team mode scoring; `1` to enable) |
 | `CLAUDE_CODE_ENABLE_TASKS` | `true` | Set `false` to revert to TodoWrite |
 | `CLAUDE_CODE_TASK_LIST_ID` | Per-session | Share task list across sessions |
 | `CLAUDE_TOKEN_EFFICIENCY` | `1` | Enable token-efficient CLI output compression (`0` to disable) |
@@ -252,11 +259,15 @@ 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. **cd && pattern handling**: Hooks support chained commands with `cd && command` pattern for working directory preservation in compressed output
+4. **Extended language support**: Rewrite hook supports eslint, next, tsc build tools in addition to git/test families
+5. **Partial file reads**: Use Read tool with `offset` and `limit` parameters for files >200 lines to avoid loading entire file contents into context
+6. **Compressed error messages**: Delegation error messages are optimized for minimal token consumption (use logging, never print statements)
 
-**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
+**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, eslint, next, tsc
 
 Disable: `export CLAUDE_TOKEN_EFFICIENCY=0`
 
@@ -287,13 +298,13 @@ Ensure SessionStart hooks are installed (inject_workflow_orchestrator.py) so tha
 
 **TeamCreate blocked:**
 ```bash
-echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS  # Must be "1"
+echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS  # Check if set to "1"
 export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
 ```
-The PreToolUse hook blocks all team tools (`TeamCreate`, `SendMessage`, pattern `*team*`/`*teammate*`) unless this env var is set. The hook prints a specific error message indicating the env var is missing.
+The PreToolUse hook blocks all team tools (`TeamCreate`, `SendMessage`, pattern `*team*`/`*teammate*`) unless this env var is set. The hook auto-creates `.claude/state/team_mode_active` when the env var is "1" and a team tool is invoked.
 
 **Team mode not activating despite keywords:**
-When `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` is set, team mode is the default. It only falls back to subagent mode when `team_mode_score <= -3` (breadth-only tasks with no complexity factors). Without the env var, plan mode always selects `"subagent"` mode (with ≥2 subtasks mandatory).
+Team mode is activated by tool availability detection during plan mode. Ensure `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` is set before running a workflow that should use team mode. The planning phase evaluates `team_mode_score` based on task complexity and characteristics. Without the env var, plan mode always selects `"subagent"` mode (with ≥2 subtasks mandatory).
 
 **Team state files stale after crash:**
 ```bash

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