72 lines
5.0 KiB
Markdown
72 lines
5.0 KiB
Markdown
---
|
|
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."
|