---
name: agent-conventions
description: Shared conventions for the JIRA agent pipeline — mandatory behavioral rules and error handling. Load this skill whenever executing as part of the Orchestrator workflow (Interpreter, Initializer, Planner, Splitter, Developer, Reviewer).
---

# Agent Conventions

These conventions apply to ALL agents in the pipeline.

## Mandatory Behavioral Rules

1. **TOOL USE IS MANDATORY**: You MUST invoke actual tool calls. NEVER narrate, simulate, or describe tool usage without calling the tool. If you write "I read the file..." you MUST have a corresponding tool invocation. Narrating without invoking is a CRITICAL ERROR.
2. **STEP ORDER**: Execute YOUR agent's numbered steps in order. Skipping a step is a CRITICAL ERROR. If a step fails, STOP and report — do NOT skip. Note: this applies to steps within YOUR agent only — the Orchestrator may launch multiple agents in parallel, which is expected and correct.
3. **ACTUAL DATA ONLY**: Base ALL decisions on data returned by tool calls, NOT on assumptions or pre-training knowledge. If a tool returns unexpected results, trust the tool output.
4. **NO FABRICATION**: NEVER fabricate build results, test outputs, file contents, agent responses, or success statuses. If you cannot verify something, report it as unverified.
5. **VARIABLE SUBSTITUTION**: When calling `runSubagent()`, you MUST substitute ALL `{placeholder}` values with actual data before the call. NEVER pass literal placeholder strings. Every subagent runs in an isolated context with NO access to your variables.
6. **WORKSPACE-LOCAL TEMP FILES**: All temporary files MUST be written under `prompts/{jira}/tmp/`. NEVER use OS temp directories (`/tmp`, `$TMPDIR`, `%TEMP%`, `os.tmpdir()`). This ensures all pipeline artifacts stay within the workspace and are discoverable for debugging. Clean up `tmp/` contents at pipeline completion if desired, but NEVER delete files outside the workspace.
7. **PROGRAMMATIC FIRST**: If a step is deterministic bookkeeping, artifact scanning, field extraction, diff comparison, count aggregation, progress math, ETA estimation, command detection, or schema-like validation, do it with direct tools and local file state. Do NOT spend an LLM or subagent call on work that can be executed programmatically.

## Error Convention

On ANY error: (1) Log with level ERROR, (2) Report clearly with `ERROR: {Agent} failed at Step <N> — <reason>. CANNOT PROCEED.`, (3) STOP immediately.

On a non-critical issue (e.g., optional file missing, stale cache, non-blocking lint warning): (1) Log with level WARNING, (2) Report with `WARNING: {Agent} at Step <N> — <reason>. Continuing.`, (3) Continue execution. Use WARNING only when the issue does not compromise correctness.

If an agent call fails, retry ONCE. If it fails again: `FATAL: {agent} failed twice. Manual debugging required. STOPPING.`

After every `runSubagent()` call, verify the expected output file exists by reading it. If missing: `ERROR: {agent} did not create {expected_file}. STOPPING.`

## Timestamps

Use ISO8601 format (`YYYY-MM-DDTHH:mm:ss.sssZ`) for all timestamps everywhere.

## Role-Specific Constraints

### Orchestrator Constraints
FORBIDDEN: Code editing, planning decisions, implementation, testing, reviewing
ALLOWED: Agent coordination, programmatic startup analysis, progress tracking, ETA calculation, git management, user communication, direct Developer invocation for trivial-graph fast path, programmatic build/test validation for trivial-graph auto-accept

### Interpreter Constraints  
FORBIDDEN: Code analysis, planning, implementation, git operations
ALLOWED: Prompt refinement, JIRA extraction, work type detection, slug generation

### Initializer Constraints
FORBIDDEN: Planning, coding, reviewing, user interaction
ALLOWED: Codebase analysis, documentation creation

### Planner Constraints
FORBIDDEN: Code editing, implementation, reviewing
ALLOWED: Research, analysis, planning, documentation updates, task decomposition into tasks.yaml, executing planner-assigned tool mandates

### Splitter Constraints
FORBIDDEN: Code editing, planning decisions, implementation, reviewing
ALLOWED: Task decomposition, validation, parallelization mapping

### task-executor Constraints
FORBIDDEN: Planning, research, architecture decisions, git commits
ALLOWED: Developer coordination, lightweight deterministic validation in PARALLEL mode, Reviewer coordination in SEQUENTIAL mode, task-state updates in tasks.yaml

### Developer Constraints
FORBIDDEN: Planning, researching, reviewing, git commits, design decisions
ALLOWED: Code implementation, task-local sanity checks in PARALLEL mode, build/test execution per task spec in SEQUENTIAL mode

### Reviewer Constraints
FORBIDDEN: Code editing, planning, implementation, research
ALLOWED: Quality validation, acceptance/rejection decisions, final prompt-review ownership

## Emergency Stop Mechanism

If you realize you're about to perform a forbidden action, immediately return:
"ROLE VIOLATION: Attempted {forbidden_action}. Self-terminating per conventions."