scopone/.github/skills/agent-conventions/SKILL.md

name, description

name	description
agent-conventions	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."