ryderfreeman4logos/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. CSA tokens (gemini-cli/codex) are significantly cheaper than Claude tokens, and CSA tools have larger 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.

Required schema:

[result]
status = "success"  # success | partial | error | needs_clarification
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

Phase 3: Verification (Optional, Recommended on Risk)

Manager not fully confident
  -> Manager dispatches independent verification employee
  -> Reviewer returns result.toml with verdict
  -> Manager synthesizes two reports (A + reviewer)
  -> Manager gives final recommendation to user

SA Mode Propagation (MANDATORY)

When operating in SA mode, ALL csa invocations MUST include --sa-mode true. This applies to every csa run, csa review, csa debate, and any other execution command dispatched by the Layer 0 manager. Omitting --sa-mode at root depth causes a hard error; passing false breaks prompt-guard propagation and disables SA-specific safety mechanisms. All dispatch templates below include --sa-mode true by default.

Practical Dispatch Templates

Template A: Planning Dispatch (Manager -> Layer 1)

PROMPT_FILE=$(mktemp /tmp/sa-plan-XXXXXX.txt)
cat > "$PROMPT_FILE" <<'PLAN_EOF'
You are Layer 1 Employee in sa manager-employee mode.

Read and follow AGENTS.md and CLAUDE.md.

OBJECTIVE:
[what to plan]

INPUT:
[user requirements and constraints]

OUTPUT FORMAT:
- CONTRACT MARKER: CSA_RESULT_TOML_PATH_CONTRACT=1
- Write TODO artifact to $CSA_SESSION_DIR/artifacts/TODO.md
- Write manager-facing result.toml to $CSA_RESULT_TOML_PATH_CONTRACT using required schema
- Print ONLY the absolute result.toml path

SCOPE:
- You may read code, analyze architecture, and spawn Layer 2 workers.
- You own implementation strategy decisions.

DONE WHEN:
- $CSA_SESSION_DIR/artifacts/TODO.md exists
- $CSA_RESULT_TOML_PATH_CONTRACT exists with status in {success, partial, needs_clarification, error}
- $CSA_RESULT_TOML_PATH_CONTRACT contains [result], [report], [timing], [tool], [artifacts]
PLAN_EOF

SID=$(csa run --sa-mode true --prompt-file "$PROMPT_FILE")
scripts/csa/session-wait-until-done.sh "$SID"

Template B: Implementation Dispatch (Manager -> Layer 1)

PROMPT_FILE=$(mktemp /tmp/sa-impl-XXXXXX.txt)
cat > "$PROMPT_FILE" <<'IMPL_EOF'
You are Layer 1 Employee in sa manager-employee mode.

MANDATORY: Before writing ANY code, read ./AGENTS.md and identify which rules
apply to your task. After writing code, self-review against those rules.
Specifically verify: error handling (009), security (014), commits (015),
testing (016), and code smells (017).

Read and follow AGENTS.md and CLAUDE.md.

OBJECTIVE:
Implement approved plan end-to-end.

INPUT:
- Approved TODO path: [path]
- Session context: [session id if any]

OUTPUT FORMAT:
- CONTRACT MARKER: CSA_RESULT_TOML_PATH_CONTRACT=1
- Perform implementation and validation autonomously
- Write manager-facing result.toml to $CSA_RESULT_TOML_PATH_CONTRACT using required schema
- Include commit_hash/review_result in [artifacts] when available
- Print ONLY the absolute result.toml path

SCOPE:
- You choose HOW to implement.
- You may spawn Layer 2 workers.
- You must perform appropriate review before reporting success.
- If a commit is needed inside the child session, use plain `git commit` with hooks enabled.

DONE WHEN:
- Implementation tasks are complete or explicitly marked partial/error
- $CSA_RESULT_TOML_PATH_CONTRACT exists and is self-contained for manager decision
IMPL_EOF

SID=$(csa run --sa-mode true --session "$SESSION_ID" --prompt-file "$PROMPT_FILE")
scripts/csa/session-wait-until-done.sh "$SID"

Template C: Trust Verification Dispatch (Manager -> Reviewer Employee)

PROMPT_FILE=$(mktemp /tmp/sa-verify-XXXXXX.txt)
cat > "$PROMPT_FILE" <<'VERIFY_EOF'
You are the independent reviewer (Employee B).

Read and follow AGENTS.md and CLAUDE.md.

OBJECTIVE:
Verify Employee A's reported outcome independently.

INPUT:
- Employee A result.toml path: [path]
- Verification type: [code-review | design-review]

OUTPUT FORMAT:
- CONTRACT MARKER: CSA_RESULT_TOML_PATH_CONTRACT=1
- Run independent verification (e.g. csa review --diff or csa debate)
- Write manager-facing result.toml to $CSA_RESULT_TOML_PATH_CONTRACT
- In [report], clearly state agreement/disagreement and why
- Print ONLY the absolute result.toml path

SCOPE:
- Independent judgment required.
- Do not assume Employee A is correct.

DONE WHEN:
- Verification completed
- $CSA_RESULT_TOML_PATH_CONTRACT includes clear verdict in summary/report
VERIFY_EOF

SID=$(csa run --sa-mode true --prompt-file "$PROMPT_FILE")
scripts/csa/session-wait-until-done.sh "$SID"

Canonical LLM dispatch form

For Layer 0 manager dispatch, route through the tier config and pin only the tool when the manager needs a specific CLI:

SID=$(csa run \
  --sa-mode true \
  --tier tier-4-critical \
  --tool codex \
  --timeout 7200 \
  --prompt-file "$PROMPT_FILE")

Why this is the canonical Layer 0 dispatch form:

• --tier resolves model and thinking budget from tier config, keeping model versions in one source of truth
• --tool forces the desired tool (for example, codex) while still respecting the tier's model selection
• tier routing owns fallback, so --no-failover is not needed here
• --timeout 7200 is the sprint-safe default for long-running employee work

Reserve --model-spec for one-off debugging overrides only; never document it as a reusable dispatch pattern. Default to this form unless the user explicitly asks for a different tool.

Model Selection Guidelines

• Tool and thinking budget are determined by the tier system in ~/.config/cli-sub-agent/config.toml. Do NOT hardcode model versions or --thinking. Use --tool only when a workflow explicitly requires a particular CLI.
• Cross-review should prefer a different model family than the original author (configured via [review] tool = "auto").

Forbidden Behaviors (Enforced)

Layer 0 Manager

• No code reading
• No code editing
• No local testing
• No local review via diff inspection
• No transcript mining
• No artifact content inspection
• No self-verification by technical investigation

Layer 1 Senior Employee

• No under-specified reports (must be self-contained)
• No hiding risks in vague wording
• No success status without explicit validation outcome

Layer 2 Worker

• No unilateral scope expansion
• No irreversible architectural changes without Layer 1 approval

Success Criteria for This Skill

This sa skill is working as designed only when all are true:

1. Manager can make decisions using only result.toml.
2. Manager never reads code or artifacts directly.
3. Verification is done by independent employee cross-review.
4. Employee reports include enough detail to avoid manager investigation loops.
5. User receives concise natural-language summaries rather than raw artifact dumps.