9thlevelsoftware/legion/workflow-common-core

Legion Workflow Common Core

Always-load core conventions for every /legion: command. This file is intentionally compact.

Core Responsibilities

• Detect and load the active runtime adapter before command-specific logic.
• Resolve canonical state file paths under .planning/.
• Resolve settings.json defaults safely when file is missing or invalid.
• Resolve AGENTS_DIR once per invocation before loading personality files.
• Provide baseline command-to-skill mapping and context budget ceilings.

Execution Harness Contract (Core)

Every planning, execution, review, and advisory prompt must preserve this shared contract:

read-before-write -> evidence-before-action -> minimal diff -> verify-before-report

The contract turns Legion plans into constrained implementation work instead of open-ended design prompts. Any generated plan, executor prompt, or review brief that asks an implementation agent to modify files must define:

Stop gates are mandatory when a prompt or plan is incomplete. If a required read target is missing, a write target is absent from files_modified, instructions conflict with files_forbidden, an API/type/validation decision is unresolved, or success cannot be verified, the agent must report BLOCKED with evidence and the narrow missing decision. It must not infer the design, broaden scope, or report confidence without proof.

Adapter Detection (Core)

1. Check .legion-cli override in project root.
2. If absent, evaluate adapter primary detections from adapters/*.md.
3. If no primary match, evaluate adapter secondary detections.
4. If still no match, default to Claude Code adapter.
5. Read the full adapter file and use adapter-defined tool mapping/model settings.

User Interaction (Core)

CRITICAL: When commands or skills reference adapter.ask_user, Use adapter.ask_user, or instruct you to ask the user a question with structured choices, you MUST use the AskUserQuestion tool. Do NOT output questions as raw text and wait for a reply. The AskUserQuestion tool provides structured selection UI (arrow keys + Enter) which is the intended interaction model for all Legion commands.

For Claude Code, adapter.ask_user maps to:

AskUserQuestion(questions: [{
  question: "Your question here",
  options: [
    {label: "option-1", description: "Description of option 1"},
    {label: "option-2", description: "Description of option 2"}
  ]
}])

This applies to ALL question prompts in ALL commands — confirmation gates, mode selection, workflow preferences, and any other structured choice.

State Paths (Core)

Settings Resolution (Core)

Read settings.json from repo root if available. If missing/invalid, use defaults.

Defaults:

• planning.max_tasks_per_plan = 3 (per-plan task cap only; not a phase plan-count cap)
• review.max_cycles = 3
• execution.agent_personality_verbosity = "full"
• integrations.github = "prompt"
• memory.enabled = true
• memory.project_scoped_only = true
• control_mode = "guarded"

Mode Profile Resolution

After resolving control_mode from settings (default: "guarded"), load the corresponding profile:

Preconditions (MUST be verified before use):

1. control_mode key lookup is CASE-SENSITIVE. Valid values: exactly "autonomous", "guarded", "advisory", "surgical". Case variants ("Guarded", "GUARDED") are invalid — if detected, log warning and fall back to "guarded".
2. The 5-flag schema is a strict contract with downstream consumers (authority-enforcer, wave-executor). All 5 keys MUST be present in the resolved profile.
3. Partial profiles (missing 1+ flags) trigger: log WARNING "control-mode profile '{name}' missing flags: {list}. Falling back to guarded defaults for missing flags." and merge with hardcoded guarded defaults for only the missing flags. Do NOT fall back to guarded entirely — use the profile's provided flags where set.

Resolution steps:

1. Read .planning/config/control-modes.yaml explicitly via the Read tool. Capture raw bytes; do NOT assume content.
2. If the file does not exist at that path: do NOT silently fall back. Emit <escalation>severity: warning, type: infrastructure, decision: control-modes.yaml missing — falling back to hardcoded guarded defaults, context: .planning/config/control-modes.yaml not found; downstream gates will use hardcoded guarded flags</escalation> and continue with the hardcoded guarded fallback below.
3. If the file exists but cannot be parsed as YAML: emit <escalation>severity: blocker, type: infrastructure, decision: Cannot resolve control mode, context: control-modes.yaml present but YAML parse failed</escalation> and STOP.
4. Look up profiles[control_mode] to get the flag set (exact key match, case-sensitive).
5. If the mode key is not found: emit <escalation>severity: warning, type: infrastructure, decision: control_mode '{name}' not defined in control-modes.yaml — using hardcoded guarded defaults, context: settings.json declared control_mode that is absent from profiles</escalation> and fall back to hardcoded guarded.
6. Hardcoded guarded fallback flags:

• authority_enforcement: true, domain_filtering: true, human_approval_required: true, file_scope_restriction: false, read_only: false

1. Assert the resolved profile contains all 5 flags before passing downstream. If assertion fails (partial profile), merge with guarded defaults for missing flags and log the merge.
2. Pass resolved profile to authority-enforcer and wave-executor integration points.

The resolved profile is a set of 5 boolean flags: authority_enforcement, domain_filtering, human_approval_required, file_scope_restriction, read_only. This schema is the contract with downstream skills — adding or removing flags is a breaking change.

Agent Path Resolution (Core)

Resolve once per command invocation by actually reading the probe file (not assuming):

1. Use the Read tool on ~/.claude/agents/agents-orchestrator.md (global install — preferred path)

• If Read succeeds: set AGENTS_DIR = ~/.claude/agents and STOP resolution. This is the standard installed location and should work for all npm-installed Legion users.

1. Only if step 1 returns a file-not-found error: Use the Read tool on agents/agents-orchestrator.md (local dev mode)

• If Read succeeds: set AGENTS_DIR = agents (relative to project root)

1. Only if both fail: check manifests ~/.claude/legion/manifest.json then ~/.legion/manifest.json for an agents_dir key
2. If none found: fail fast with: "Agent files not found. Run: npm install -g @anthropic/legion"

CRITICAL: Do NOT skip the Read probe. Do NOT assume a path doesn't exist without trying it. Do NOT claim "agent files aren't on disk" without a real file-not-found error from the Read tool. The global install path (~/.claude/agents/) contains all 48 agent files for any npm-installed Legion instance.

Use resolved path for all personality reads: {AGENTS_DIR}/{agent-id}.md

Personality Injection (Core)

• Retrieval-led reasoning: ALWAYS read the agent personality file before spawning. Do NOT substitute pre-trained knowledge for the personality file contents. The Dynamic Knowledge Index in AGENTS.md provides the complete file map — use it to locate agent files by division, then Read the full file. This is non-negotiable.
• Load full personality markdown for assigned agent.
• Inject personality content + task instructions into adapter spawn prompt.
• Use adapter.model_execution for execution agents unless command overrides it.

Command-to-Skill Mapping (Core)

Context Budget Ceiling (Core)

Execution-context budgets (always-load skills only):

• build: soft 180 KB, hard 225 KB
• plan: soft 180 KB, hard 225 KB
• review: soft 180 KB, hard 225 KB
• status: soft 120 KB, hard 150 KB

Release checks enforce hard ceilings and print telemetry for every command. Agent line-count remains telemetry, not a gate.

State File Quick Validation

Lightweight validation that runs at the start of every command that loads project context. Fast enough to not add noticeable latency (pattern matching only, no full parse).