name = "csa-setup" version = "0.1.0" description = "Install CSA, Weave, and coding workflow patterns for AI agent bots" homepage = "https://github.com/RyderFreeman4Logos/cli-sub-agent" target = "agent-bots"

CSA Setup

Installation guide for AI agent bots (openclaw, Moltis, etc.) to set up CSA and Weave with optional coding workflow patterns.

Skill Files

File	Description
skill.md (this file)	Installation and setup guide
skills/AGENTS.md	Full skill & pattern catalog
README.md	Project documentation

Prerequisites

Before starting, verify these tools are available:

# Required
git --version          # Git 2.30+
cargo --version        # Rust toolchain (only needed for building from source)

# Optional but recommended
mise --version         # Cross-platform tool version manager
gh --version           # GitHub CLI (for PR workflows)

If mise is not installed (see mise.jdx.dev/installing for alternatives):

# Verify domain before piping to shell
curl https://mise.run | sh

If cargo is not installed (see rustup.rs for alternatives):

# Official Rust installer — verify TLS and domain
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Step 1: Install CSA

Option A: Quick install (prebuilt binaries)

curl -fsSL https://raw.githubusercontent.com/RyderFreeman4Logos/cli-sub-agent/main/install.sh | sh

This installs both csa and weave from prebuilt binaries.

Option B: via mise (recommended for version management)

mise use -g ubi:RyderFreeman4Logos/cli-sub-agent[exe=csa]
mise use -g ubi:RyderFreeman4Logos/cli-sub-agent[exe=weave]
csa --version

Upgrade later with mise upgrade.

Option C: from source

git clone https://github.com/RyderFreeman4Logos/cli-sub-agent.git
cd cli-sub-agent
cargo install --path crates/cli-sub-agent

Verify

csa --version
# Expected: csa <version>

Step 2: Install Weave

Weave is the skill-lang compiler and package manager.

If you used Option A (install.sh) in Step 1, weave is already installed. Otherwise:

# Via mise
mise use -g ubi:RyderFreeman4Logos/cli-sub-agent[exe=weave]

# Or from source (if you already cloned in Step 1 Option C, skip the clone)
git clone https://github.com/RyderFreeman4Logos/cli-sub-agent.git
cd cli-sub-agent
cargo install --path crates/weave

Verify

weave --help
# Expected: weave <version> - Skill-lang compiler and package manager

Step 3: Initialize Project

Navigate to the target project:

cd /path/to/your-project

Decide whether to create a project config

Check if a global config already exists:

ls ~/.config/cli-sub-agent/config.toml 2>/dev/null && echo "GLOBAL_EXISTS" || echo "NO_GLOBAL"

If GLOBAL_EXISTS: Project config is usually unnecessary — CSA falls back to global config automatically. Skip csa init by default. Only run it if the user explicitly requests project-specific overrides.
If NO_GLOBAL: ASK THE USER which mode to use:
- csa init --minimal (Recommended): Creates only [project] metadata. Tools, tiers, and resources inherit from built-in defaults. Best for most projects.
- csa init (Full): Creates a complete config with tool detection, smart tiers, and resource estimates. Use when the project needs custom tool configuration.

CRITICAL: Do NOT run csa init without user consent. Running it unconditionally overrides global settings with project-local defaults.

Install git branch protection (recommended)

Prevents commits on protected branches (main, dev, master). Works with all tools — Claude Code, Codex, Gemini, manual git:

lefthook install

Hook scripts live in scripts/hooks/ and are configured via lefthook.yml.

CSA also ships built-in prompt guards (branch-protection, dirty-tree-reminder, commit-workflow) that automatically inject workflow reminders into every csa run session — no installation needed.

Check tool availability

csa doctor

This reports which AI tools (claude-code, codex, gemini-cli, opencode) are available and properly configured.

Step 4: Install Core Skills

Install the base persona skills that enable CSA's core capabilities:

# Install from the CSA repository
weave install RyderFreeman4Logos/cli-sub-agent

This installs all skills and patterns into .weave/deps/cli-sub-agent/.

Verify installation

weave audit
weave check --fix

Step 4b: Install Pattern Skills

Each pattern ships a companion skill that serves as its entry point. These skills tell the orchestrator (Claude Code, etc.) how to invoke the pattern. The companion skill is NOT executed by the pattern workflow (that would cause infinite recursion) — it is a facade for tool discovery.

weave install automatically creates symlinks from .claude/skills/ (and other tool-specific directories) into the global package store. No manual setup is needed.

Verify

ls -la .claude/skills/

You should see symlinks for each pattern skill (e.g., commit, mktd, sa).

Maintenance

If symlinks become stale or broken (e.g., after updating packages):

weave link sync          # Reconcile: create missing, remove stale, fix broken
weave check --fix        # Remove broken symlinks only

Conflict resolution

If two packages expose the same skill name, weave install will report a conflict. To resolve, install with --no-link and create renamed symlinks:

weave install user/repo --no-link
cd .claude/skills
ln -s ../../.weave/store/repo/.../patterns/commit/skills/commit/ my-commit

The renamed symlink still points to the canonical companion skill directory.

Scope control

weave install user/repo                          # Default: project-level (.claude/skills/)
weave install user/repo --link-scope user        # User-level (~/.claude/skills/)
weave install user/repo --no-link                # Skip linking entirely

Step 5: Programming Patterns (Interactive)

CSA ships with 18 compiled workflow patterns for coding tasks. Not all projects need all patterns.

ASK THE USER: Present the following categories and let the user choose which patterns to install. Use checkboxes or a numbered menu.

Category A: Commit & Review (recommended for all coding projects)

These patterns enforce strict commit discipline with security audit, test verification, and heterogeneous model review.

Pattern	What it does
`commit`	Audited commits: format, lint, test, security scan, AI review, then commit
`ai-reviewed-commit`	Review-fix-re-review loop until clean before committing
`code-review`	Scale-adaptive GitHub PR review (small/medium/large)
`pr-bot`	Iterative PR review with configurable cloud bot feedback and merge

Install:

# Patterns are already in .weave/deps/ from Step 4.
# Compile them for your project:
mkdir -p .csa/plans
for pattern in commit ai-reviewed-commit code-review pr-bot; do
  weave compile .weave/deps/cli-sub-agent/patterns/$pattern/PATTERN.md \
    --output .csa/plans/$pattern.toml
done

Category B: Security & Audit

Adversarial security analysis and compliance auditing.

Pattern	What it does
`security-audit`	Pre-commit vulnerability scan and test-completeness check
`file-audit`	Per-file AGENTS.md compliance audit with report generation
`csa-review`	Independent CSA-driven code review with structured output
`codebase-audit`	Bottom-up per-module security audit with structured reports
`codebase-blog`	Generate technical deep-dive blogs from audit results
`review-loop`	Bounded iterative review-fix loop until clean or max rounds

Install:

mkdir -p .csa/plans
for pattern in security-audit file-audit csa-review codebase-audit codebase-blog review-loop; do
  weave compile .weave/deps/cli-sub-agent/patterns/$pattern/PATTERN.md \
    --output .csa/plans/$pattern.toml
done

Category C: Planning & Task Management

Structured planning workflows with debate and version control.

Pattern	What it does
`mktd`	Make TODO: reconnaissance, drafting, debate, approval
`mktsk`	Convert TODO plans into persistent serial tasks
`debate`	Adversarial multi-tool strategy debate with convergence

Install:

mkdir -p .csa/plans
for pattern in mktd mktsk debate; do
  weave compile .weave/deps/cli-sub-agent/patterns/$pattern/PATTERN.md \
    --output .csa/plans/$pattern.toml
done

Category D: Advanced Workflows

End-to-end orchestration and issue reporting.

Pattern	What it does
`sa`	Three-layer recursive sub-agent orchestration
`dev2merge`	Branch-to-merge: plan (mktd+debate), implement, validate, PR, review, merge
`dev-to-merge`	Backward-compatible alias of `dev2merge`
`csa-issue-reporter`	Structured GitHub issue filing for CSA errors
`migrate`	Configuration and state migration workflows

Install:

mkdir -p .csa/plans
for pattern in sa dev2merge dev-to-merge csa-issue-reporter migrate; do
  weave compile .weave/deps/cli-sub-agent/patterns/$pattern/PATTERN.md \
    --output .csa/plans/$pattern.toml
done

Install All (ONLY on explicit user request)

CRITICAL: Do NOT run this automatically. Only execute when the user explicitly says they want all patterns installed (e.g., "install everything", "install all patterns"). Most projects only need Category A (Commit & Review).

If the user explicitly requests all patterns:

mkdir -p .csa/plans
for pattern in .weave/deps/cli-sub-agent/patterns/*/; do
  name=$(basename "$pattern")
  if [ -f "$pattern/PATTERN.md" ]; then
    weave compile "$pattern/PATTERN.md" --output ".csa/plans/$name.toml"
  fi
done

Step 6: Configure Global Settings

Create or edit ~/.config/cli-sub-agent/config.toml:

# Tool selection priority (first = most preferred)
[preferences]
tool_priority = ["claude-code", "codex", "gemini-cli", "opencode"]

# Review tool (auto = heterogeneous selection)
[review]
tool = "auto"

# Debate tool
[debate]
tool = "auto"

# Concurrency limits (default: 3 per tool)
[defaults]
max_concurrent = 3

# Per-tool overrides (uncomment as needed)
# [tools.codex]
# max_concurrent = 5

ASK THE USER: Which AI tools do they have access to? Adjust tool_priority accordingly. Common configurations:

Setup	Recommended `tool_priority`
Claude Code + Codex	`["claude-code", "codex"]`
Codex + Gemini CLI	`["codex", "gemini-cli"]`
All tools available	`["claude-code", "codex", "gemini-cli", "opencode"]`
Single tool only	Set `[review] tool = "<tool>"` and `[debate] tool = "<tool>"` explicitly

Step 7: Configure Hooks (Optional)

CSA has a hook system that runs shell scripts at key lifecycle events. Three built-in prompt guards are enabled by default — no configuration needed:

Guard	What it does
`branch-protection`	Warns when running on protected branches (main, dev, release/*)
`dirty-tree-reminder`	Reminds about uncommitted changes in the working tree
`commit-workflow`	Reminds about unpushed commits on feature branches

Adding custom guards

Custom guards stack on top of built-ins. Create or edit ~/.config/cli-sub-agent/hooks.toml (global) or ~/.local/state/csa/{project}/hooks.toml (project-level):

[[prompt_guard]]
name = "pr-reminder"
command = "/path/to/remind-pr.sh"
timeout_secs = 5

Guard scripts receive a JSON context on stdin (project_root, session_id, tool, is_resume, cwd) and write injection text to stdout. Empty stdout means no injection. Non-zero exit or timeout is warned and skipped.

Disabling built-in guards

builtin_guards = false

Hook events

Beyond prompt guards, CSA supports lifecycle hooks:

[pre_run]
enabled = true
command = "echo pre-run: {session_id} {tool}"
timeout_secs = 30

[post_run]
enabled = true
command = "echo post-run: {session_id} exit={exit_code}"
timeout_secs = 30

[session_complete]
enabled = true
# Built-in default auto-commits session data (active when command is not set)

See docs/hooks.md in the CSA repository for full reference.

Step 8: Verify Everything

# Check CSA is working
csa --version

# Check weave is working
weave --help

# Check tool availability
csa doctor

# Check installed skills
weave audit

# Check for broken symlinks
weave check --fix

# Test a simple run (replace with your preferred tool)
csa run --sa-mode false --tool codex "echo hello from CSA"

Quick Reference

CSA Commands

# Execution (--sa-mode REQUIRED for root callers; auto-detected for CSA children)
csa run --sa-mode false --tool <tool> "prompt"          # Run a task
csa run --sa-mode false --tool auto "prompt"            # Auto-select tool
csa run --sa-mode false --fork-last "continue"          # Fork most recent session
csa run --sa-mode false --fork-from <ULID> "continue"   # Fork specific session
csa run --sa-mode false --fork-call "task"              # Fork-call (child returns to parent)
csa run --sa-mode false --ephemeral "quick task"        # Ephemeral (no project files)
csa run --sa-mode false --model-spec gemini-cli/google/gemini-2.5-pro/xhigh "task"  # Model spec
csa review --sa-mode false --diff                       # Review uncommitted changes
csa review --sa-mode false --range main...HEAD          # Review commit range
csa review --sa-mode false --fix                        # Review-and-fix mode
csa review --sa-mode false --red-team                   # Red-team security review
csa debate --sa-mode false "design question"            # Adversarial model debate
csa debate --sa-mode false --thinking xhigh "question"  # Debate with high thinking budget

# Session & management
csa session list --tree                 # List session tree
csa memory list                         # List cross-session memories
csa tiers list                          # List model tiers
csa tokuin estimate <file>              # Estimate token count
csa doctor                              # Check environment and tools
csa gc --dry-run                        # Preview garbage collection
csa self-update                         # Update to latest release

Weave Commands

weave compile PATTERN.md                # Compile to execution plan
weave compile PATTERN.md -o workflow.toml   # Compile to file
weave install user/repo                 # Install skill from GitHub
weave install --path ./local-skill      # Install from local path
weave lock                              # Generate lockfile
weave update                            # Update all dependencies
weave audit                             # Check consistency
weave check --fix                       # Fix broken symlinks
weave visualize workflow.toml               # ASCII workflow diagram
weave visualize workflow.toml --mermaid     # Mermaid flowchart

Troubleshooting

Problem	Solution
`csa: command not found`	Run `mise use -g ubi:RyderFreeman4Logos/cli-sub-agent[exe=csa]`
`weave: command not found`	Run `curl -fsSL https://raw.githubusercontent.com/RyderFreeman4Logos/cli-sub-agent/main/install.sh \| sh` or build from source: `cargo install --path crates/weave`
`csa doctor` shows tool unavailable	Install the missing tool or remove from `tool_priority`
`weave audit` reports missing deps	Run `weave install RyderFreeman4Logos/cli-sub-agent`
Broken symlinks after update	Run `weave check --fix`
Pattern skills missing after install	Run `weave update && weave link sync --force`. If `weave update` reports the same commit, the bare cache may be stale — delete `~/.cache/weave/git/` and retry.
`weave link sync` reports foreign symlink conflict	A non-weave symlink exists at the target. Use `weave link sync --force` to overwrite, or remove it manually first.
Codex rate limit / quota	Wait for cooldown or switch tool: `csa run --tool claude-code`

FilesExpand file tree

skill.md

Latest commit

History

skill.md

File metadata and controls

name = "csa-setup" version = "0.1.0" description = "Install CSA, Weave, and coding workflow patterns for AI agent bots" homepage = "https://github.com/RyderFreeman4Logos/cli-sub-agent" target = "agent-bots"

CSA Setup

Skill Files

Prerequisites

Step 1: Install CSA

Option A: Quick install (prebuilt binaries)

Option B: via mise (recommended for version management)

Option C: from source

Verify

Step 2: Install Weave

Verify

Step 3: Initialize Project

Decide whether to create a project config

Install git branch protection (recommended)

Check tool availability

Step 4: Install Core Skills

Verify installation

Step 4b: Install Pattern Skills

Verify

Maintenance

Conflict resolution

Scope control

Step 5: Programming Patterns (Interactive)

Category A: Commit & Review (recommended for all coding projects)

Category B: Security & Audit

Category C: Planning & Task Management

Category D: Advanced Workflows

Install All (ONLY on explicit user request)

Step 6: Configure Global Settings

Step 7: Configure Hooks (Optional)

Adding custom guards

Disabling built-in guards

Hook events

Step 8: Verify Everything

Quick Reference

CSA Commands

Weave Commands

Troubleshooting