ryderfreeman4logos/cli-sub-agent/sa

sa: Manager-Employee Orchestration (Three-Layer Model)

Three-layer recursive delegation for planning and implementation with strict role boundaries.

• Layer 0 is the Department Manager: dispatches work, reads structured reports, makes approval decisions.
• Layer 1/Layer 2 are Employees: execute work autonomously and return self-contained reports.

This skill exists to keep the main agent out of code-level work.

Core Metaphor

┌──────────────────────────────────────────────────────────────┐
│ Layer 0: Department Manager (Main Agent)                     │
│                                                              │
│ Responsibilities:                                            │
│ • Define WHAT to do (objective, scope, done condition)       │
│ • Dispatch tasks via csa run                                 │
│ • Read result.toml (structured report only)                  │
│ • Decide approve/reject/escalate                             │
│ • Communicate summary to user                                │
│                                                              │
│ Forbidden: code reading/writing/testing/investigation        │
└─────────────────────────────┬────────────────────────────────┘
                              │
                              │ csa run --prompt-file prompt_file
                              v
┌──────────────────────────────────────────────────────────────┐
│ Layer 1: Senior Employee (Planner / Implementer)             │
│                                                              │
│ Responsibilities:                                            │
│ • Plan, implement, review, validate                          │
│ • Decide HOW to execute                                      │
│ • Spawn Layer 2 workers when needed                           │
│ • Return complete result.toml                                │
└─────────────────────────────┬────────────────────────────────┘
                              │
                              │ csa run "sub-task"
                              v
┌──────────────────────────────────────────────────────────────┐
│ Layer 2: Employee Worker                                     │
│                                                              │
│ Responsibilities:                                            │
│ • Focused exploration/fixes/review support                   │
│ • Reports back to Layer 1                                     │
└──────────────────────────────────────────────────────────────┘

Operating Contract

<prompt-guard name="hook-bypass-forbidden"> ABSOLUTE PROHIBITION on ALL hook bypass methods. You MUST NOT:

• Use --no-verify or -n with git commit or git push
• Set LEFTHOOK=0 environment variable (e.g., env LEFTHOOK=0 git commit, export LEFTHOOK=0)
• Set LEFTHOOK_SKIP environment variable
• Modify .git/hooks/* files to disable or weaken hooks
• Set core.hooksPath to an empty or permissive directory
• Use ANY other mechanism that prevents Lefthook/pre-commit hooks from running

All quality hooks MUST be allowed to run. Bypassing hooks is a critical SOP violation.

When just pre-commit fails:

1. Code quality issues (clippy, fmt, test) → FIX the code, do NOT bypass
2. Environment/sandbox limitations → report status="needs_clarification" with exact error, do NOT bypass
3. Pre-existing failures from unrelated crates → report as blocker with exact error, do NOT bypass

NEVER treat pre-existing failures as justification for LEFTHOOK=0. </prompt-guard>

Layer 0 Manager: What You MUST Do

1. Dispatch work with clear task contracts.
2. Require self-contained result.toml from every employee run.
3. Base decisions on reports, not direct code inspection.
4. Gate transitions: APPROVE / MODIFY / REJECT / ESCALATE.
5. If confidence is low, trigger cross-review by another employee.
6. After PR creation, invoke `/pr-bot` — this is MANDATORY. The pr-bot skill handles @codex review triggering, polling (10 min timeout), fallback to local review, and the full bot review loop. Layer 1 executors MUST invoke this skill; it is NOT optional.

Small Task Fast Path (COST OPTIMIZATION)

When ALL of the following are true, Layer 0 MAY execute directly instead of dispatching CSA:

1. Scope: total change is ≤30 lines across ≤3 files
2. Complexity: mechanical edit (config field addition, rename, flag wiring, template update)
3. Context: relevant code is already in the main agent's context window
4. Risk: no security-sensitive paths, no cross-crate architectural changes

In fast-path mode, Layer 0 may:

• Read/edit the specific files being changed (not exploratory reading)
• Run just pre-commit to validate
• Commit directly on the feature branch

Layer 0 MUST still delegate via CSA when:

• Change exceeds 30 lines or 3 files
• Design judgment is required (which approach? which abstraction?)
• Security-sensitive code paths are involved
• User explicitly requested SA mode or CSA delegation

Layer 0 Manager: What You MUST NEVER Do (Full SA Mode)

When NOT in small-task fast path, these absolute prohibitions apply:

• NEVER Read source files (*.rs, *.ts, *.py, etc.).
• NEVER Grep/Glob source code.
• NEVER run build/lint/test commands.
• NEVER run git investigation commands (git diff, git show, etc.) to verify quality.
• NEVER read CSA transcript logs.
• NEVER read artifact contents (TODO.md, review.md, design.md, etc.).
• NEVER write/edit code files.
• NEVER run csa review or csa debate as self-investigation.
• NEVER replace employee verification with personal inspection.

Layer 0 may only:

• Run csa run to dispatch employee tasks.
• Read manager-facing structured report files (result.toml from primary/verification runs).
• Write temporary prompt files for dispatch.
• Use task tracking tools (TaskCreate / TaskUpdate).
• Ask user decisions/questions via AskUserQuestion.
• Present artifact paths only (never artifact content).
• Summarize report conclusions to the user; never forward raw artifact content.

Layer 1/Layer 2 Employees: Autonomy Rules

Employees are professionals with subjective agency.

• Manager specifies WHAT; employee decides HOW.
• Employee chooses implementation details (algorithms, structures, error handling).
• Employee may delegate to lower tiers as needed.
• If requirements are ambiguous, employee returns status = "needs_clarification" with concrete questions.

Review/Debate Dispatch Discipline (MANDATORY)

For review tasks, Layer 0 MUST dispatch csa review. For debate tasks, Layer 0 MUST dispatch csa debate.

Layer 0 MUST NOT hand-write a csa run prompt that approximates review/debate unless the built-in command is blocked by a concrete, documented error.

In slow Rust repositories, a healthy review/debate session can take 30-60 minutes. Sparse early output or csa session wait timing out is not failure by itself.

While the original session is healthy, Layer 0 MUST keep waiting on the same session id. It MUST NOT launch a second review/debate flow for the same scope unless there is strong evidence of failure: explicit crash/error, persistent liveness failure, or direct user instruction.

Exploration Tool Preference (MANDATORY)

For codebase exploration (searching code, reading multiple files, understanding architecture), Layer 1 and Layer 2 employees MUST prefer `csa run` over Claude Code's built-in `Agent` tool with `subagent_type=Explore` when a supported CSA routing tool is available. Codex and OpenCode can be cheaper than Claude tokens, and CSA tools have large context windows for processing many files simultaneously. Reserve the built-in Explore agent only for quick searches that need <3 queries.

Structured Communication Protocol

Manager -> Employee (Dispatch Packet)

Every task prompt MUST include:

1. Objective
2. Input context
3. Output format
4. Scope boundaries
5. DONE WHEN (mechanically verifiable)

Example DONE WHEN:

• DONE WHEN: result.toml exists at $CSA_RESULT_TOML_PATH_CONTRACT and status is success.
• DONE WHEN: just pre-commit exits 0 and result.toml status is success.

Employee -> Manager (result.toml)

Employees MUST return a self-contained report that allows manager decision without opening any source/artifact content. Employees MUST write this file to $CSA_RESULT_TOML_PATH_CONTRACT (fallback: $CSA_SESSION_DIR/result.toml) and print that path only. Every attempt-bound receipt MUST copy $CSA_RESULT_TOML_ATTEMPT_NONCE into [result].attempt_nonce; CSA rejects a receipt without the current nonce.

Required schema:

[result]
status = "success"  # success | partial | error | needs_clarification
attempt_nonce = "$CSA_RESULT_TOML_ATTEMPT_NONCE"
summary = "Implemented JWT validation with 15 test cases. All pass."
error_code = ""
session_id = "019c4c24-..."
 
[report]
what_was_done = "Added JwtValidator struct with verify_token method"
key_decisions = ["Used RS256 algorithm", "15-minute token expiry"]
risks_identified = ["No refresh token mechanism yet"]
files_changed = 3
tests_added = 15
tests_passing = true
 
[timing]
started_at = "2026-02-11T10:00:00Z"
ended_at = "2026-02-11T10:05:00Z"
 
[tool]
name = "claude-code"
 
[review]
author_tool = "claude-code"
reviewer_tool = "codex"
 
[artifacts]
todo_path = "$CSA_SESSION_DIR/artifacts/TODO.md"
commit_hash = "abc1234"
review_result = "CLEAN"

Clarification extension (when status = "needs_clarification"):

[clarification]
questions = [
  "Should token expiry be configurable?",
  "Should refresh tokens be included in this scope?"
]
blocking_reason = "Security requirement is ambiguous"

Decision Rules for Manager

Given result.status:

1. success: summarize result.summary + report.what_was_done to user; continue workflow.
2. partial: summarize completed scope and unresolved risks; ask user whether to continue.
3. needs_clarification: ask user the employee's listed questions; do not proceed until answered.
4. error: report error_code + summary; ask user whether to retry, narrow scope, or stop.

Manager decision must rely on report fields, not source inspection.

Trust Verification (Cross-Review, Not Self-Investigation)

When manager confidence is low, manager assigns an independent employee review.

Trigger Conditions

• Employee report has unclear risk statements.
• Work is high-impact/security-sensitive.
• Contradictory findings across runs.
• User explicitly asks for independent verification.

Verification Workflow

Manager receives Employee A result.toml
    │
    ├─ If confidence sufficient -> approve/reject directly
    │
    └─ If confidence insufficient:
        1) Assign Employee B for verification
           - Code quality verification: Employee B runs `csa review --diff`
           - Design correctness: Employee B runs `csa debate`
        2) Employee B returns verification result.toml
        3) Manager compares A vs B structured reports
        4) Manager reports combined assessment to user

Manager still MUST NOT inspect source code or diffs directly.

End-to-End Workflow

Phase 1: Planning

User request
  -> Manager writes planning prompt file
  -> Manager dispatches Layer 1 (csa run)
  -> Layer 1 explores/plans (can spawn Layer 2)
  -> Layer 1 writes TODO + result.toml
  -> Manager reads result.toml only
  -> Manager reports summary + TODO path to user
  -> User: APPROVE / MODIFY / REJECT

Phase 2: Implementation

User APPROVE
  -> Manager writes implementation prompt file
  -> Manager dispatches Layer 1 with session continuity
  -> Layer 1 implements autonomously
  -> Layer 1 performs validation/review/commit workflow (use plain `git commit` with hooks enabled if a commit is required inside the CSA child session)
  -> Layer 1 returns result.toml (commit_hash, review_result, summary)
  -> Manager reads result.toml only
  -> Manager reports outcome to user