M2c1 Worker

M2C1 Worker Agent Skill

Any cortextOS agent can autonomously build complete software by acting as the "human" in the M2C1 framework, managing a dedicated worker Claude Code session through the full 12-phase lifecycle.

Worker session spawn is fully implemented. Use cortextos spawn-worker to launch an isolated Claude Code M2C1 build session.

Overview

This skill enables 3-layer agentception:

1. You (the cortextOS agent) act as the human/supervisor
2. Worker (a fresh Claude Code session) acts as the M2C1 orchestrator
3. Subagents (spawned by the worker) execute parallel research and tasks

You provide the brain dump, answer discovery questions, help with tool setup, monitor progress, and validate the final output. The worker does all the building.

Prerequisites

• M2C1 skill files available (bundled in cortextos templates)
• A clear project idea or brain dump
• An isolated directory for the build
• Worker session spawn mechanism available (cortextos spawn-worker)

Phase 0: Setup

1. Create the project directory

PROJECT_DIR="$HOME/<project-name>"
mkdir -p "$PROJECT_DIR"
cd "$PROJECT_DIR"
git init
echo "node_modules/" > .gitignore
echo ".claude/" >> .gitignore
git add .gitignore && git commit -m "init: $PROJECT_DIR"

2. Copy M2C1 skill files

mkdir -p .claude/skills/m2c1/artifact-templates

# Copy from the installed framework
for file in SKILL.md orchestration-workflow.md; do
  cp "${CTX_FRAMEWORK_ROOT}/templates/agent/.claude/skills/m2c1/$file" "./.claude/skills/m2c1/$file"
done

3. Create the worker's inbox

mkdir -p "$CTX_ROOT/inbox/<worker-name>"
mkdir -p "$CTX_ROOT/state/<worker-name>"

4. Write BRAINDUMP.md

Write a comprehensive brain dump in $PROJECT_DIR/BRAINDUMP.md. Include:

• What you are building and why
• Technical requirements and constraints
• Reference implementations or existing code to study
• Any research already done
• Success criteria

5. Copy comms skill to worker project

The worker needs the bus messaging skill to communicate with you:

mkdir -p "$PROJECT_DIR/.claude/skills/comms"
cp "$CTX_FRAMEWORK_ROOT/templates/agent/.claude/skills/comms/SKILL.md" "$PROJECT_DIR/.claude/skills/comms/SKILL.md" 2>/dev/null

6. Set up .claude/ permission bypass

Workers write to .claude/orchestration-*/ extensively. Set up permissions BEFORE spawning:

mkdir -p "$PROJECT_DIR/.claude"
cat > "$PROJECT_DIR/.claude/settings.json" << 'SETTINGS'
{
  "permissions": {
    "allow": [
      "Edit",
      "Write",
      "Bash"
    ],
    "allowedPaths": [
      ".claude/"
    ]
  }
}
SETTINGS

If the file already exists (e.g., with MCP config), merge the permissions key into it rather than overwriting.

7. Write AGENTS.md

Write $PROJECT_DIR/AGENTS.md with instructions for the worker:

# <Project Name> - M2C1 Autonomous Build

You are building <description>.

## Your Role
You are the M2C1 orchestrator. Follow the 12-phase workflow in .claude/skills/m2c1/orchestration-workflow.md.

## Communication
Send messages to <your-agent-name>:

cortextos bus send-message <your-agent-name> normal '<message>'

Check inbox:

cortextos bus check-inbox

Set environment:

export CTX_AGENT_NAME="<worker-name>" export CTX_ORG="<org>" export CTX_FRAMEWORK_ROOT="<path>" export CTX_ROOT="$HOME/.cortextos/default"

When you have questions during Phase 3 (Discovery), send them via send-message. Do NOT use AskUserQuestion.

## Start
1. Read BRAINDUMP.md
2. Read .claude/skills/m2c1/orchestration-workflow.md
3. Begin Phase 0, then Phase 1
4. Message <your-agent-name> when PRD is ready
5. Continue autonomously through all phases

Phase 1: Spawn the Worker

WORKER_NAME="m2c1-$(basename $PROJECT_DIR)"

cortextos spawn-worker "$WORKER_NAME" \
  --dir "$PROJECT_DIR" \
  --prompt "Read AGENTS.md for your instructions, then read BRAINDUMP.md for the project spec. Begin the M2C1 workflow starting with Phase 0." \
  --parent $CTX_AGENT_NAME

The worker:

• Runs in $PROJECT_DIR with --dangerously-skip-permissions
• Gets CTX_AGENT_NAME=$WORKER_NAME so it can use cortextos bus send-message to reach you
• Is tracked by the daemon: cortextos list-workers shows its status

Log the spawn:

cortextos bus log-event action worker_spawned info \
  --meta '{"worker":"'$WORKER_NAME'","parent":"'$CTX_AGENT_NAME'","project":"'$PROJECT_DIR'"}'

Phase 2: Monitor and Communicate

Communication Priority

1. Bus messages (primary) — worker sends you updates, you reply via bus.
2. Direct session intervention (fallback) — only when the worker is stuck or unresponsive to bus. Implementation pending.
3. Git (monitoring) — check commits to see what was built without interrupting the worker.

Checking Progress

# Via bus messages (worker sends updates)
cortextos bus check-inbox

# Via git (see what was built)
cd $PROJECT_DIR && git log --oneline | head -10

# Via file system (check orchestration artifacts)
ls $PROJECT_DIR/.claude/orchestration-*/

Answering Discovery Questions (Phase 3)

The worker will send you questions via send-message. Answer them:

cortextos bus send-message <worker-name> normal '<your answers>'

Base your answers on:

• The original brain dump requirements
• Any research you have done
• Your domain knowledge as a cortextOS agent
• The org's goals and constraints (GOALS.md, knowledge.md)

If you do not know the answer, make a reasonable decision and note it. Do not block the worker with "ask the user" unless it is truly a human-only decision.

Handling Stuck States

If the worker appears stuck (no bus messages, no new git commits > 15 minutes):

1. Send a bus message: cortextos bus send-message <worker-name> normal 'Continue with the M2C1 workflow. What phase are you on?'
2. Check git: cd $PROJECT_DIR && git log --oneline | head -5
3. Inject directly into the PTY if still unresponsive: cortextos inject-worker <worker-name> "Continue with the M2C1 workflow. What phase are you on?"
4. Check worker status: cortextos list-workers
5. If halted: cortextos terminate-worker <worker-name> then re-spawn

Phase 3: Tool Setup Support (CRITICAL - Act Like a Human)

This is one of the most important phases. You act exactly like a human developer setting up a project: installing tools, configuring MCPs, setting env variables, logging into services, testing that everything works. The worker cannot do this itself — it needs you to configure its environment.

Think Holistically About Tools

Before the worker starts building, ask yourself:

• What MCPs would help? (Playwright for browser testing, etc.)
• What accounts/services does the project need? (APIs, hosting, etc.)
• What CLI tools should be installed? (expo, vercel, railway, etc.)
• What env variables does the worker need? (API keys, tokens, etc.)
• What skills could help the worker? (existing cortextOS skills)
• What testing tools are needed? (iOS Simulator, Playwright, etc.)

MCP Configuration

# 1. Create or update the worker's MCP config
mkdir -p "$PROJECT_DIR/.claude"
node -e "
const fs = require('fs');
const path = '$PROJECT_DIR/.claude/settings.json';
const cfg = fs.existsSync(path) ? JSON.parse(fs.readFileSync(path)) : {};
cfg.mcpServers = cfg.mcpServers || {};
cfg.mcpServers.playwright = { command: 'npx', args: ['@anthropic-ai/mcp-playwright'] };
fs.writeFileSync(path, JSON.stringify(cfg, null, 2));
console.log('MCP config updated');
"

# 2. Worker must restart to pick up MCP config
# Send via bus message:
cortextos bus send-message <worker-name> normal \
  'MCP config updated at .claude/settings.json. Please restart your session with --continue to pick it up, then test Playwright by taking a screenshot of google.com.'