Shared Core Skill

"You are an agent utilizing the Shared Core Skill, which provides essential instructions and guidelines for all agents in the system."

IMPORTANT: Use Built-in Tools, Not Shell Commands

Use your CLI's built-in tools:

Read tool - to read session files, state, messages
Write tool - to write message files, update state
Grep tool - to search code
Bash tool - only for git commands, running tests, builds
Fetch tool - to make HTTP requests
MCP Servers - to interact with MCP services like GitKraken, Playwright, Web search, Vision, etc.

Communication Protocols

There are 2 layers of communication: The Watchdog and Agents Direct Messaging.

FIRST: Read Your Pending Messages

The watchdog delivers messages to you in TWO ways (check in this order):

1. PRIMARY: CLI Message Argument

Claude CLI: Check $arguments.message - contains JSON array of messages
OpenCode CLI: Check the initial --prompt content - contains JSON array of messages
If present and non-empty, parse as JSON array and process all messages

2. FALLBACK: Pending Messages File

Read: ./.claude/session/pending-messages-{your-agent-name}.json
This file contains the batch of messages the watchdog delivered to you
Parse the messages array from this JSON file

3. DIAGNOSTICS ONLY: Inbox Folder

Path: ./.claude/session/messages/{your-agent-name}/*.json
DO NOT read this for your pending work - the watchdog manages this
Only check here for debugging if both primary and fallback are empty

Message Reading Protocol:

Step 1: Check CLI message argument ($arguments.message or initial prompt)
Step 2: If empty, read ./claude/session/pending-messages-{your-agent-name}.json
Step 3: Parse messages array and process ALL messages in the batch
Step 4: NEVER delete inbox or pending files - Watchdog owns lifecycle

Determining Your Agent Name:

Check $arguments.agent (for worker commands)
Or identify from the workflow skill you loaded (pm-workflow → "pm", developer-workflow → "developer", etc.)

SECOND: NEVER FORGET TO UPDATE A TASK STATUS AND WAKE UP THE NEEDED AGENTS

You are the glue that keeps the development cycle running. You must update a task status to the next agent and send a message to watchdog to wake them up.

How Message Delivery Works

Receive Context:
- Primary: Check CLI message argument ($arguments.message or initial prompt)
- Fallback: Check pending-messages-{agent}.json file
Process Messages:
- Iterate through the messages in the array.
- Execute the requested task (implementation, testing, analysis).
- Do not check message-state.json. The Watchdog guarantees unique delivery.
Complete Transaction:
- When batch work is done, send a status_update message with explicit processed IDs.
- Include processedMessageIds (all processed message IDs) and processedMessageCount.
- Use ready, waiting, or idle only when you are available for next delivery.
- Watchdog clears pending lock only after batch acknowledgement is validated.

Sending Messages

To send a message, you must use an Pattern to prevent partial reads by the watchdog.

Protocol:

Generate ID: msg-{yyyyMMdd-HHmmss}-{random8chars}
Write content to: ./.claude/session/messages/{recipient}/{id}.json

Message Structure

{
  "id": "msg-20260208-140000-a1b2c3d4",
  "from": "{your-agent-name}",
  "to": "{recipient}",
  "type": "{message_type}",
  "priority": "normal",
  "payload": { ... },
  "timestamp": "2026-02-08T14:00:00Z",
  "status": "pending"
}

Your Agent Name: Determine your agent name from:

$arguments.agent (Claude CLI with slash command)
The workflow skill you loaded (developer-workflow → "developer", qa-workflow → "qa", etc.)
Or check which pending-messages file exists for you

Example: Sending a Status Update

Create the content (using Write tool): File: ./.claude/session/messages/watchdog/msg-status-123.json

{
  "id": "msg-status-20260208-120000-x9y8z7",
  "from": "developer",
  "to": "watchdog",
  "type": "status_update",
  "priority": "low",
  "payload": {
    "status": "working",
    "currentTask": "feat-001",
    "details": "Implementing feature"
  },
  "timestamp": "2026-02-08T12:00:00Z",
  "status": "pending"
}

Task Status Updates

IMPORTANT: Always send status updates when starting and finishing work. This ensures the dashboard shows accurate agent status.

Canonical Status Values

starting - Agent spawned and initializing
working - Active execution
awaiting_pm - Blocked waiting PM input
awaiting_gd - Blocked waiting Game Designer input
waiting - Waiting for dependency/event but safe for watchdog queue control
ready - Finished current batch and available for new work
idle - No active task
error - Error state reported to watchdog

When You START Working on a Task

Send status: "working" immediately when you begin processing:

Payload:

{
  "status": "working",
  "currentTask": "{taskId}",
  "details": "{brief description}"
}

When You FINISH a Task

Send status: "ready" when complete and ready for next assignment:

Payload:

{
  "status": "ready",
  "processedMessageIds": ["msg-20260208-120000-x9y8z7"],
  "processedMessageCount": 1,
  "currentTask": null,
  "details": "Task complete, ready for next assignment"
}

Standard Message Types

1. Validation Request (Dev -> QA)

Type: validation_request Payload:

{
  "taskId": "{taskId}",
  "description": "Implementation complete",
  "branch": "main"
}

2. Task Complete (QA -> PM)

Type: task_complete Payload:

{
  "taskId": "{taskId}",
  "summary": "All tests pass",
  "validationPassed": true
}

3. Bug Report (QA -> PM)

Type: bug_report Priority: high Payload:

{
  "taskId": "{taskId}",
  "bugs": ["List of bugs found"],
  "severity": "high"
}

4. Research Request (Any -> PM)

Type: research_request Payload:

{
  "topic": "Topic to research",
  "context": "Why I need this",
  "needCodeExamples": true
}

5. General Request (Any -> Any)

Type: task_request Payload:

{
  "topic": "Topic to research",
  "context": "Why I need this",
  "needCodeExamples": true
}

Asking Questions

Type: question Payload:

{
  "question": "What is the requirement for X?",
  "context": "Implementing feat-Y",
  "taskId": "{taskId}"
}

Signaling Work Complete

IMPORTANT: When you finish processing a message and are ready for more work, signal the watchdog:

File: ./.claude/session/messages/watchdog/msg-status-{timestamp}.json
Content:
{
  "id": "msg-status-{timestamp}",
  "from": "{your-agent-name}",
  "to": "watchdog",
  "type": "status_update",
  "priority": "low",
  "payload": {
    "status": "ready",
    "processedMessageIds": ["msg-{processed-id-1}", "msg-{processed-id-2}"],
    "processedMessageCount": 2,
    "lastTask": "{taskId}"
  },
  "timestamp": "{UTC-timestamp}",
  "status": "pending"
}

Valid message types for the watchdog message system

You MUST use the message system to communicate with the watchdog and other agents. Valid message types include:

  {
    "messageTypes": ["task_assign", "validation_request", "bug_report", "task_complete",
            "question", "answer", "research_update", "regression_request",
            "prd_update", "status_update", "priority_review", "agent_ready",
            "work_complete", "error", "shutdown",
            "implementation_complete", "work_blocked", "task_abandoned", "quality_concern",
            "retrospective_initiate", "retrospective_contribution", "research_request", "research_response",
            "prd_reorganized", "skill_improvements", "priority_response", "skill_request",
            "gdd_ready", "gdd_update", "design_question", "design_answer",
            "playtest_request", "playtest_report", "mechanic_proposal", "design_guidance",
            "design_guidance_request", "test_plan_request", "test_plan_contribution",
            "asset_assign", "asset_ready", "asset_question", "shader_request", "reference_request"]
  }

Universal Commit Rule

CRITICAL: Every agent MUST commit their file changes.

Any time an agent makes file changes, those changes MUST be committed with the Ralph format.

When to Commit:

After any file modifications (source files, configs, PRD, docs, session files)
Before sending completion messages
After any skill file updates
After any documentation changes

Commit Format

[ralph] [{{AGENT}}] {{PRD_ID}}: {{Brief description}}

- Change 1
- Change 2

PRD: {{PRD_ID}} | Agent: {{AGENT}} | Iteration: {{N}}

shared-core

SKILL.md.claude/skills/shared-core/SKILL.md