Claude-Code-Workflow/.ccw/workflows/cli-tools-usage.md

CLI Tools Execution Specification

Unified reference for ccw cli — runs agent tools (gemini, qwen, codex, claude, opencode) with a shared interface for prompt, mode, model, directory, templates, and session resume.

References: ~/.claude/cli-tools.json (tool config), ~/.ccw/templates/cli/ (protocol + prompt templates)

---

1. Quick Reference

Command Syntax

ccw cli -p "<PROMPT>" [options]

Options

Option	Description	Default
-p, --prompt	Required. Prompt text	—
--tool <name>	Tool: gemini, qwen, codex, claude, opencode	First enabled in config
--mode <mode>	analysis (read-only), write (create/modify/delete), review (codex-only)	analysis
--model <model>	Model override	Tool's primaryModel
--cd <dir>	Working directory	Current directory
--includeDirs <dirs>	Additional directories (comma-separated)	—
--rule <template>	Load protocol + prompt template	— (optional)
--id <id>	Execution ID	Auto: {prefix}-{HHmmss}-{rand4}
--resume [id]	Resume session (last if no id, comma-separated for merge)	—

Mode Definition (Authoritative)

Mode	Permission	Auto-Invoke Safe	Use For
analysis	Read-only	Yes	Review, exploration, diagnosis, architecture analysis
write	Create/Modify/Delete	No — requires explicit intent	Implementation, bug fixes, refactoring
review	Read-only (git-aware)	Yes	Codex only. Uncommitted changes, branch diffs, specific commits

--mode is the authoritative permission control for ccw cli. The MODE: field inside prompt text is a hint for the agent — both should be consistent, but --mode governs actual behavior.

Codex review mode: Target flags (--uncommitted, --base, --commit) are codex-only and mutually exclusive with -p.

---

2. Configuration

Config File: ~/.claude/cli-tools.json

Field	Description
enabled	Tool availability
primaryModel	Default model
secondaryModel	Fallback model
tags	Capability tags (for caller-side routing)

Tool Types

Type	Usage	Capabilities
builtin	--tool gemini	Full (analysis + write)
cli-wrapper	--tool doubao	Full (analysis + write)
api-endpoint	--tool g25	Analysis only (no file write)

Tool Selection

1. Explicit --tool specified → use it (validate enabled)
2. No --tool → first enabled tool in config order

Fallback Chain

Primary model fails → secondaryModel → next enabled tool → first enabled (default).

---

3. Prompt Construction

Assembly Order

ccw cli builds the final prompt as:

1. Mode protocol — loaded based on --mode (analysis-protocol.md / write-protocol.md)
2. User prompt — the -p value
3. Rule template — loaded from --rule template name (if specified)

Prompt Template (6 Fields)

PURPOSE: [goal] + [why] + [success criteria]
TASK: [step 1] | [step 2] | [step 3]
MODE: analysis|write
CONTEXT: @[file patterns] | Memory: [prior work context]
EXPECTED: [output format] + [quality criteria]
CONSTRAINTS: [scope limits] | [special requirements]

• PURPOSE: What + Why + Success. Not "Analyze code" but "Identify auth vulnerabilities; success = OWASP Top 10 covered"
• TASK: Specific verbs. Not "Review code" but "Scan for SQL injection | Check XSS | Verify CSRF"
• MODE: Must match --mode flag
• CONTEXT: File scope + memory from prior work
• EXPECTED: Deliverable format, not just "Report"
• CONSTRAINTS: Task-specific limits (vs --rule which loads generic templates)

CONTEXT: File Patterns + Directory

• @**/* — all files in working directory (default)
• @src/**/*.ts — scoped pattern
• @../shared/**/* — sibling directory (requires --includeDirs)

Rule: If CONTEXT uses @../dir/**/*, must add --includeDirs ../dir.

# Cross-directory example
ccw cli -p "<PROMPT>" --tool gemini --mode analysis \
  --cd "src/auth" --includeDirs "../shared"

CONTEXT: Memory

Include when building on previous work:

Memory: Building on auth refactoring (commit abc123), implementing refresh tokens
Memory: Integration with auth module, using shared error patterns

--rule Templates

Universal: universal-rigorous-style, universal-creative-style

Analysis: analysis-trace-code-execution, analysis-diagnose-bug-root-cause, analysis-analyze-code-patterns, analysis-analyze-technical-document, analysis-review-architecture, analysis-review-code-quality, analysis-analyze-performance, analysis-assess-security-risks

Planning: planning-plan-architecture-design, planning-breakdown-task-steps, planning-design-component-spec, planning-plan-migration-strategy

Development: development-implement-feature, development-refactor-codebase, development-generate-tests, development-implement-component-ui, development-debug-runtime-issues

Complete Example

ccw cli -p "PURPOSE: Identify OWASP Top 10 vulnerabilities in auth module; success = all critical/high documented with remediation
TASK: Scan for injection flaws | Check auth bypass vectors | Evaluate session management | Assess data exposure
MODE: analysis
CONTEXT: @src/auth/**/* @src/middleware/auth.ts | Memory: Using bcrypt + JWT
EXPECTED: Severity matrix, file:line references, remediation snippets, priority ranking
CONSTRAINTS: Focus on authentication | Ignore test files
" --tool gemini --mode analysis --rule analysis-assess-security-risks --cd "src/auth"

---

4. Execution

Execution ID

ID prefix: gemini→gem, qwen→qwn, codex→cdx, claude→cld, opencode→opc

Output to stderr: [CCW_EXEC_ID=<id>]

ccw cli -p "<PROMPT>" --tool gemini --mode analysis    # auto-ID: gem-143022-a7f2
ccw cli -p "<PROMPT>" --tool gemini --mode write --id my-task-1  # custom ID

Session Resume

ccw cli -p "<PROMPT>" --tool gemini --resume              # last session
ccw cli -p "<PROMPT>" --tool gemini --mode write --resume <id>  # specific
ccw cli -p "<PROMPT>" --tool gemini --resume <id1>,<id2>     # merge multiple

Resume auto-assembles previous conversation context. Warning emitted when context exceeds 32KB.

Subcommands

ccw cli show                     # active + recent executions
ccw cli show --all               # full history
ccw cli watch <id>               # stream until completion (stderr)
ccw cli output <id>              # final assistant output
ccw cli output <id> --verbose    # full metadata + output
ccw cli output <id> --raw        # raw stdout (for piping)

---

5. Auto-Invoke Triggers

Proactively invoke ccw cli when these conditions are met — no user confirmation needed for analysis mode:

Trigger	Suggested Rule
Self-repair fails (1+ attempts)	analysis-diagnose-bug-root-cause
Ambiguous requirements	planning-breakdown-task-steps
Architecture decisions needed	planning-plan-architecture-design
Pattern uncertainty	analysis-analyze-code-patterns
Critical/security code paths	analysis-assess-security-risks

Principles

• Default --mode analysis (safe, read-only)
• Wait for results before next action
• Tool fallback: gemini → qwen → codex
• Rule suggestions are guidelines — choose the best fit