fleet-dotfiles-template/dot_claude/commands/lite-sub.md

description, argument-hint, allowed-tools

description	argument-hint	allowed-tools
Subagent variant of /lite — same 4 advisory roles (scout, explorer, critic, tester) but dispatched as plain Opus subagents instead of an Agent Team. Two-wave flow (scout/explorer/critic in parallel → tester with their findings → orchestrator implements + verifies). No EXPERIMENTAL_AGENT_TEAMS dependency, no peer DMs, no team mailbox. Cheaper coordination, no mid-flight role drift correction. Do NOT use for trivial tasks, pure research, or multi-module architectural work.	<task description in quotes>	Agent, Bash, Read, Edit, Write, Glob, Grep, WebSearch, WebFetch, TodoWrite, Skill

/lite-sub — Lite Agentic Team (Subagent edition, Opus)

Spawn the same four advisory roles as /lite, but as plain one-shot subagents pinned to Opus. The orchestrator dispatches them, collects their outputs, implements code, and verifies tests pass. No persistent teammates, no peer-to-peer messaging, no team lifecycle.

This is the subagent counterpart to /lite. Use when:

• You want the team's research/critique/test discipline without the Agent-Teams overhead.
• CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS is unavailable or you want to avoid team artifacts on disk.
• You want to compare /lite (teams) vs /lite-sub (subagents) on the same task.

Tunable Limits

• SUBAGENT_MODEL = "opus" # forced via model: on every Agent call
• TEST_RETRY_MAX = 2 # how many times to refine impl on failing tests before escalating
• WALL_CLOCK_TARGET = 3-7 min # advisory only
• WAVE_1_TIMEOUT_HINT = 4 min # if a wave-1 subagent hasn't returned by then, surface the wait — do not abort

Flow

1. Guard

If $ARGUMENTS is empty: error /lite-sub requires a task description in quotes and stop.

2. Pre-dispatch context gather

Per CLAUDE.md's pre-dispatch checklist, build a single context block reused for all subagent prompts.

• pwd and git rev-parse --show-toplevel 2>/dev/null → project root.
• Detect language + test framework (in order):
  • package.json → Node — check deps for vitest | jest | mocha
  • pyproject.toml or setup.py → Python — pytest if in deps, else default pytest
  • Package.swift → Swift — XCTest
  • go.mod → Go — go test
  • Cargo.toml → Rust — cargo test
  • Gemfile → Ruby — rspec if in deps else minitest
  • None of the above → "no project detected" branch (see Error handling)
• SSH hosts: grep -A5 "Host " ~/.ssh/config matching task domain.
• Skills: ls ~/.claude/skills/ matching task domain.
• Env var NAMES: grep -i <task-keyword> ~/.zshrc (NAMES only, never values).
• CLAUDE.md keywords: grep -B1 -A10 <keyword> ~/.claude/CLAUDE.md for any sections relevant to the task.

Standard context block (built once, pasted into every spawn prompt):

## Available System Access
- SSH: <relevant hosts, or "n/a">
- Skills: <relevant skill summaries, or "n/a">
- Env vars: <relevant env var NAMES only>
- Tools: WebSearch, WebFetch, Bash, Read, Glob, Grep
- Project root: <path or "no git project">
- Test framework: <auto-detected, or "none detected">

## Task (verbatim from user)
$ARGUMENTS

## Relevant CLAUDE.md sections
<paste matching grep output, or "n/a">

3. Wave 1 — dispatch scout, explorer, critic in parallel

A SINGLE assistant message with THREE Agent tool calls. Every call uses:

• model: "opus"
• subagent_type: the existing agentic-team agent name ("Research Scout", "Explorer", "Critic")
• description: 3-5 word summary
• prompt: the standard prompt template below, with role-specific addenda

Standard wave-1 prompt template:

You are a one-shot advisory subagent in the /lite-sub flow. You will run ONCE,
produce your output, and exit. There is no team mailbox, no peer messaging,
and no opportunity to react to other subagents — this is a single round.

Your full role definition is at:
  ~/.claude/agents/agentic-team/<phase>/<role>.md

Read that file ONCE at the start — it defines your identity, what you produce,
your rules, and your constraints. Stay in role.

<paste standard context block from step 2>

## Output discipline
- Be concise. Your output goes directly into the orchestrator's context for
  synthesis. Long preambles waste tokens.
- Lead with the deliverable your role specifies. End with a short "Notes for
  the tester" paragraph (≤4 bullets) flagging assumptions worth testing.
- Do NOT propose implementation code. Do NOT ask clarifying questions —
  proceed with the most reasonable interpretation and note ambiguities.
- Do NOT spawn further subagents. Do NOT call Agent.

## Your task in this run
<role-specific addendum below>

Role-specific addenda:

• Research Scout: "Find ≥3 references via WebSearch — libraries, blog posts, similar implementations. Check GitHub stars/last-commit on each. Output: a ## Prior art brief with one paragraph per reference (what it does, why it's relevant, link), followed by ## Recommended approach (1-2 paragraphs) and ## Notes for the tester (assumptions to test)."
• Explorer: "Verify every library/framework you would recommend (npm view <pkg>, pip show, brew info, gh repo view, or WebSearch the package registry). Output: a ## Version manifest table with <lib>@<ver> — last release <date> — status rows, a ## Test framework line stating what to use and which version, and ## Notes for the tester (any version-pinning gotchas)."
• Critic: "Read the task as if it were already a plan. Output: ## Concerns (severity-tagged: critical/important/minor, each one paragraph), ## Ambiguity register (a numbered list of unresolved questions and your default interpretation for each), and ## Notes for the tester — the riskiest assumptions, ranked. Identify problems; do not propose solutions. Flag FUNDAMENTALLY WRONG PLAN only if the task is contradictory or impossible — put that flag on its own line at the very top if applicable."

4. Inspect wave-1 outputs

When all three return:

• If Critic's first line contains FUNDAMENTALLY WRONG PLAN: STOP. Print Critic's reasoning to the user, ask them to confirm or revise, do NOT proceed to wave 2 or implementation.
• Otherwise: synthesize a short "wave-1 digest" string (≤30 lines total) consisting of:
  • Scout's Recommended approach paragraph
  • Explorer's Test framework line + any critical version pins
  • Critic's Notes for the tester (riskiest assumptions)
  • The three Notes for the tester blocks merged and de-duplicated

This digest is the spec for wave 2.

5. Wave 2 — dispatch tester (single Agent call)

You are the Tester subagent in the /lite-sub flow. You will run ONCE,
write failing tests, and exit. Your full role definition is at:
  ~/.claude/agents/agentic-team/implementation/tester.md

Read that file ONCE at the start. Stay in role.

<paste standard context block from step 2>

## Wave-1 digest (input from scout, explorer, critic)
<paste digest from step 4>

## Your task
Write FAILING tests in <detected test framework> at the project's standard
test path. Cover the riskiest assumptions from the digest. Tests should fail
because the implementation does not yet exist — not because of trivial syntax
errors. Output: a `## Test files` list (absolute paths created), `## Coverage`
(one bullet per concern from the digest, mapping concern → test name), and
`## Notes for the implementer` (≤4 bullets — invariants the impl must hold).

Use model: "opus" and subagent_type: "Tester".

6. Synthesis + implementation (orchestrator)

When tester returns AND the test files exist on disk:

• Read the test files (this is your spec).
• Implement code in the project to make the failing tests pass. Use Critic's concerns + Scout's prior art + Explorer's version manifest as guardrails.
• Do NOT refactor unrelated code.
• Do NOT commit (the user controls commits).

UX pass — required when the artifact has a user-facing surface. Before considering the implementation done, identify whether the artifact will produce output a human reads:

• Web (HTML/CSS/React/Tailwind/marketing) → invoke the hig-think skill via the Skill tool.
• SwiftUI / iOS / macOS native → invoke the swift-front skill.
• Other frontend (React Native, generic JS UI, design systems) → invoke the frontend-design skill.
• CLI / terminal → no dedicated skill; apply: bold for primary identifier, dim ANSI for metadata, color for category, respect NO_COLOR and isatty(), expose --json (or equivalent) as the machine-readable escape hatch, blank lines between logical sections, errors prefixed with program name.
• Backend / library / protocol → skip; no human surface.

Apply the invoked skill's recommendations alongside the test-driven structure. Default to the human-readable form; gate machine output behind a flag. Do NOT skip this step on the grounds that "tests pass" — tests measure the data contract, not what the user sees.

7. Verification

Run the project's test command (pytest, npm test, swift test, go test ./..., etc., per detected framework).

• Tests pass: continue to step 8.
• Tests fail (iteration n of TEST_RETRY_MAX = 2):
  • If the failure is in your impl: refine the impl, re-run.
  • If the failure looks like a bad test (test asserts something the spec doesn't require): fix the test inline (you cannot DM the tester — it has exited). Note the test edit in the final report.
  • After TEST_RETRY_MAX failed iterations: STOP. Skip to step 8 with a failure report.

8. Final report

Concise final assistant message:

• Mode: subagent (Opus) — distinguishes from /lite's team mode.
• Research: 1-3 most relevant references scout found.
• Critiqued: 1-3 most important concerns critic raised.
• Tested: what assumptions are now under test.
• Built: what was implemented.
• Files changed: absolute paths.
• Test result: pass / fail-after-N-retries / escalated.

Error handling

Failure	Behavior
$ARGUMENTS empty	Error: /lite-sub requires a task description in quotes
Not in a git project	Continue, but tester writes to ~/lite-sub-scratch/<timestamp>/; orchestrator implements there too
No test framework detected	Continue; tester writes plain assertion script (e.g., a runnable Python file that exits non-zero on failure); report fallback used
Wave-1 subagent fails to return	Surface which one. If 1 of 3 fails: continue without them, note in report. If 2+ fail: stop with error.
Critic flags FUNDAMENTALLY WRONG PLAN	STOP. Print Critic's reasoning. Ask user to confirm/revise before proceeding. Do NOT proceed to wave 2.
Tester fails to return	STOP. Surface error. Do not implement without tests.
Tests fail after TEST_RETRY_MAX	Continue to step 8 (final report) with failure status. Print last test output.

Differences from /lite (Agent-Teams edition)

Property	/lite (teams)	/lite-sub (subagents)
Coordination	Persistent teammates + SendMessage + shared task list	One-shot subagents, no peer messaging
Model	Whatever each agent's frontmatter specifies	Forced model: "opus" on every call
Critic ↔ Tester	Live DM ("riskiest assumptions")	Wave-1 digest passed in tester's prompt
Drift correction	Orchestrator DMs role-drifters mid-flight	Not possible — subagents complete in one shot
Disk artifacts	~/.claude/teams/<name>/, ~/.claude/tasks/<name>/	None
Required env	CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1	None
Cost	~4-7× plain subagents	~1× plain subagents (still 3-4 Opus calls)
Wall clock	3-7 min typical	3-7 min typical (similar — wave-2 serial gate)

The structural tradeoff: /lite lets Tester react to Critic's concerns mid-flight. /lite-sub collapses that interaction into a single digest hop, which loses fidelity but eliminates a class of coordination failures (orphan teams, debate spirals, role drift).

Anti-patterns — when NOT to invoke /lite-sub

• Trivial tasks (rename, fix typo, format) — overhead > value.
• Pure-research, no implementation — direct WebSearch is faster.
• Cross-file architectural decisions — use the full team flow with Architect/Builder/Reviewer/Integrator.
• Spec is unclear — clarify with the user first; /lite-sub will commit to one interpretation.
• Time-sensitive emergencies — direct intervention is faster.
• LLM-orchestrating CLI tasks where the team's testing instinct pushes toward --json-schema or --model <smaller> overrides. In your task description, explicitly say: "use the user's default model and inherit session context — do not add --no-session-persistence, --system-prompt, --json-schema, or --model overrides."

Constraints (negative — what NOT to do)

• Do NOT introduce new agents. Use only the four existing ones (Research Scout, Explorer, Critic, Tester).
• Do NOT dispatch all four in a single wave — Tester must run AFTER scout/explorer/critic so the digest is available. The structural reason /lite-sub keeps the two-wave shape is that without it Tester has no signal beyond the raw task.
• Do NOT call TeamCreate, TeamDelete, or SendMessage — this command is the subagent variant by design. If you find yourself reaching for those tools, you are running the wrong command.
• Do NOT let subagents write implementation code (except Tester writing test code). The orchestrator implements.
• Do NOT ask the user clarifying questions during the flow — /lite-sub is fire-and-forget; if the task is ambiguous, proceed with the most reasonable interpretation and note it in the report.
• Do NOT skip the test-pass verification (step 7) — claiming "done" without running tests violates superpowers:verification-before-completion.
• Do NOT proceed past step 4 if Critic flags FUNDAMENTALLY WRONG PLAN.
• Do NOT skip the UX pass on user-facing artifacts on the grounds that tests pass.
• Do NOT omit model: "opus" on any of the four Agent calls — the whole point of /lite-sub is to pin Opus across the advisory wave + tester.