Shared Core

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

1. Receive Context:

   • Primary: Check CLI message argument ($arguments.message or initial prompt)
   • Fallback: Check pending-messages-{agent}.json file

2. 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.

3. 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:

1. Generate ID: msg-{yyyyMMdd-HHmmss}-{random8chars}
2. 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

1. 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}}

Converted and distributed by TomeVault — claim your Tome and manage your conversions.