# Agent Factory — Execution Guide

## Overview

The ultraplan (`ultraplan-2026-04-11-agent-factory.md`) has 27 steps across 8 sessions
in 3 waves. This guide provides self-contained prompts for each wave.

**Key principle:** Each session reads its blueprint document (in `blueprints/`) which
contains exact file contents. No interpretation needed — implement what the blueprint specifies.

## Reference Documents

- **Plan:** `.claude/plans/ultraplan-2026-04-11-agent-factory.md`
- **Spec:** `.claude/ultraplan-spec-2026-04-11-agent-factory.md`
- **Research brief:** `.claude/research/ultraresearch-2026-04-11-openclaw-paperclip-agent-frameworks.md`
- **Source code analysis:** `.claude/research/source-code-analysis-2026-04-11.md`
- **Blueprints:** `.claude/plans/blueprints/session-{N}-*.md`

## Execution Order

```
Wave 0:  Preparation (blueprints + assumption verification)
           │
Wave 1:  S1 ─┬─ S2 ─┬─ S3 ─┬─ S4 ─┬─ S5 ─┬─ S6  (6 parallel)
              │      │      │      │      │      │
Wave 2:  ────────────────── S7 ──────────────────  (after S3+S4)
                             │
Wave 3:  ─────────────────── S8 ─────────────────  (after S1+S2+S7)
```

---

## Wave 0 — Preparation (CREATE BLUEPRINTS)

Run this FIRST. It creates the detailed blueprints that all other waves depend on.

```
/ultraexecute-local .claude/plans/ultraplan-2026-04-11-agent-factory.md
```

If not using ultraexecute, use this prompt:

```
Agent Factory Wave 0: Create session blueprints.

Context:
- Plan: .claude/plans/ultraplan-2026-04-11-agent-factory.md
- Spec: .claude/ultraplan-spec-2026-04-11-agent-factory.md
- Research: .claude/research/ultraresearch-2026-04-11-openclaw-paperclip-agent-frameworks.md
- Source analysis: .claude/research/source-code-analysis-2026-04-11.md
- Current codebase: 15 files, read ALL of them to understand conventions

Task 1: Verify the 4 assumptions in the plan:
  a) Search for Anthropic billing API docs (WebSearch). Document what exists.
  b) Test `claude --resume` with a custom session ID format. Document behavior.
  c) Check /schedule trigger docs. Document stability.
  d) Confirm Docker approach (Dockerfile + docker-compose.yml).
  Update the plan's Assumptions table with findings.

Task 2: Create 8 session blueprint documents in .claude/plans/blueprints/:
  - session-1-foundation.md (Steps 1-5)
  - session-2-skills-templates.md (Steps 6-7)
  - session-3-openclaw.md (Steps 9-12)
  - session-4-paperclip.md (Steps 14-18)
  - session-5-selflearning.md (Steps 20-21)
  - session-6-integration.md (Steps 22-24)
  - session-7-skill-updates.md (Steps 13, 19, 25)
  - session-8-finalization.md (Steps 8, 26, 27)

Each blueprint MUST contain:
  1. EXACT file contents for every new file (copy-paste ready)
  2. Precise diff descriptions for files being modified
  3. Verify commands that check CONTENT, not just file existence
  4. Quality criteria specific to the session
  5. Scope fence (what this session may/may not touch)

For exact template content, use:
  - Research brief for OpenClaw/Paperclip patterns (3-tier memory, WAL, heartbeat, etc.)
  - Source code analysis for implementation details (heartbeat format, budget schema, etc.)
  - Existing codebase files for conventions (frontmatter format, placeholder syntax, hook patterns)

All bash scripts must be bash 3.2 compatible. All templates use {{PLACEHOLDER}} syntax.
Python3 for JSON/YAML/date parsing in scripts.

Commit after all blueprints are created:
  git commit -m "docs(plans): create session blueprints for Agent Factory execution"
  git push origin main
```

---

## Wave 1 — Parallel Execution (6 sessions)

Run these 6 sessions in parallel. Each is independent.

### Session 1: Foundation — Rename and Commands

```
Agent Factory Session 1: Foundation — Rename and Commands.

Read these files FIRST:
- Blueprint: .claude/plans/blueprints/session-1-foundation.md
- Plan steps 1-5: .claude/plans/ultraplan-2026-04-11-agent-factory.md

Execute steps 1-5 from the blueprint:
1. Rename plugin from agent-builder to agent-factory (plugin.json, CLAUDE.md, README, commands, skills)
2. Create /agent-factory:deploy command (commands/deploy.md)
3. Create deployment-advisor agent (agents/deployment-advisor.md)
4. Create /agent-factory:evaluate command (commands/evaluate.md)
5. Create /agent-factory:status command (commands/status.md)

SCOPE FENCE:
- Touch: .claude-plugin/plugin.json, CLAUDE.md, README.md, commands/*, agents/deployment-advisor.md
- Touch: skills/agent-system-design/SKILL.md (rename references ONLY)
- NEVER touch: scripts/templates/*, skills/managed-agents/

Implement EXACTLY what the blueprint specifies. Commit after each step.
Run all verify commands. Push when all 5 steps pass.
```

### Session 2: Skills and Initial Templates

```
Agent Factory Session 2: Skills and Domain Templates.

Read these files FIRST:
- Blueprint: .claude/plans/blueprints/session-2-skills-templates.md
- Plan steps 6-7: .claude/plans/ultraplan-2026-04-11-agent-factory.md

Execute steps 6-7:
6. Create managed-agents skill (skills/managed-agents/SKILL.md + references)
7. Create 5 domain templates (content-pipeline, code-review, monitoring, research-synthesis, data-processing)

SCOPE FENCE:
- Touch: skills/managed-agents/*, scripts/templates/domains/*
- NEVER touch: commands/, agents/, .claude-plugin/, scripts/templates/memory/, scripts/templates/heartbeat/

Implement EXACTLY what the blueprint specifies. Commit after each step.
Run all verify commands. Push when done.
```

### Session 3: OpenClaw Memory and Autonomy

```
Agent Factory Session 3: OpenClaw Memory and Autonomy Patterns.

Read these files FIRST:
- Blueprint: .claude/plans/blueprints/session-3-openclaw.md
- Plan steps 9-12: .claude/plans/ultraplan-2026-04-11-agent-factory.md
- Source analysis: .claude/research/source-code-analysis-2026-04-11.md (OpenClaw section)

Execute steps 9-12:
9.  Create 3-tier memory templates (SESSION-STATE.md, DAILY-LOG.md, MEMORY.md)
10. Create heartbeat + cron templates (HEARTBEAT.md, heartbeat-runner.sh) with emptiness detection
11. Create proactive agent template with ADL/VFM guardrails
12. Create isolated agentTurn and systemEvent cron templates

SCOPE FENCE:
- Touch: scripts/templates/memory/, scripts/templates/heartbeat/HEARTBEAT.md,
  scripts/templates/heartbeat/heartbeat-runner.sh, scripts/templates/heartbeat/README.md,
  scripts/templates/proactive/, scripts/templates/cron/
- NEVER touch: commands/, agents/, skills/,
  scripts/templates/heartbeat/context-packet.md, scripts/templates/heartbeat/wake-prompt.md

All bash scripts MUST pass `bash -n`. Use python3 for JSON/YAML/date parsing.
Implement EXACTLY what the blueprint specifies. Commit after each step. Push when done.
```

### Session 4: Paperclip Orchestration

```
Agent Factory Session 4: Paperclip Orchestration Patterns.

Read these files FIRST:
- Blueprint: .claude/plans/blueprints/session-4-paperclip.md
- Plan steps 14-18: .claude/plans/ultraplan-2026-04-11-agent-factory.md
- Source analysis: .claude/research/source-code-analysis-2026-04-11.md (Paperclip section)

Execute steps 14-18:
14. Create heartbeat context injection templates (context-packet.md, wake-prompt.md)
15. Create goal hierarchy templates (GOALS.md, goal-tracker.sh)
16. Create budget tracking templates (budget-hook.sh, BUDGET.md, budget-report.sh)
17. Create governance and approval gate templates (GOVERNANCE.md, approval-gate.sh)
18. Create org-chart template (ORG-CHART.md, org-manager.sh)

SCOPE FENCE:
- Touch: scripts/templates/heartbeat/context-packet.md, scripts/templates/heartbeat/wake-prompt.md,
  scripts/templates/goals/, scripts/templates/budget/, scripts/templates/governance/,
  scripts/templates/org-chart/
- NEVER touch: commands/, agents/, skills/,
  scripts/templates/heartbeat/HEARTBEAT.md, scripts/templates/heartbeat/heartbeat-runner.sh

All bash scripts MUST pass `bash -n`. Use python3 for JSON/YAML/date parsing.
Implement EXACTLY what the blueprint specifies. Commit after each step. Push when done.
```

### Session 5: Self-Learning Systems

```
Agent Factory Session 5: Self-Learning Systems.

Read these files FIRST:
- Blueprint: .claude/plans/blueprints/session-5-selflearning.md
- Plan steps 20-21: .claude/plans/ultraplan-2026-04-11-agent-factory.md

Execute steps 20-21:
20. Create feedback loop templates (FEEDBACK.md, feedback-collector.sh, performance-scorer.sh)
21. Create pipeline optimization and self-healing templates (pipeline-optimizer.sh, self-healing.sh)

SCOPE FENCE:
- Touch: scripts/templates/feedback/, scripts/templates/optimization/
- NEVER touch: commands/, agents/, skills/, all other template dirs

All bash scripts MUST pass `bash -n`. Use python3 for JSON/YAML/date parsing.
Implement EXACTLY what the blueprint specifies. Commit after each step. Push when done.
```

### Session 6: Integration — Docker, Transfer, Templates

```
Agent Factory Session 6: Integration — Docker, Transfer, Additional Templates.

Read these files FIRST:
- Blueprint: .claude/plans/blueprints/session-6-integration.md
- Plan steps 22-24: .claude/plans/ultraplan-2026-04-11-agent-factory.md

Execute steps 22-24:
22. Create Docker deployment templates (Dockerfile, docker-compose.yml, docker-entrypoint.sh)
23. Create import/export system (export-system.sh, import-system.sh, MANIFEST.md)
24. Create 5 additional domain templates (customer-support, devops, legal, sales, security)

SCOPE FENCE:
- Touch: scripts/templates/docker/, scripts/templates/transfer/,
  scripts/templates/domains/customer-support.md, devops-automation.md,
  legal-review.md, sales-intelligence.md, security-audit.md,
  scripts/templates/domains/README.md (update only)
- NEVER touch: commands/, agents/, skills/,
  scripts/templates/domains/content-pipeline.md, code-review.md,
  monitoring.md, research-synthesis.md, data-processing.md

All bash scripts MUST pass `bash -n`.
Implement EXACTLY what the blueprint specifies. Commit after each step. Push when done.
```

---

## Wave 2 — Skill Updates (after Wave 1 Sessions 3+4)

### Session 7: Skill References

```
Agent Factory Session 7: Skill Updates and References.

PREREQUISITE: Wave 1 Sessions 3 and 4 must be complete. Verify:
  ls scripts/templates/memory/ && ls scripts/templates/heartbeat/ &&
  ls scripts/templates/goals/ && ls scripts/templates/budget/

Read these files FIRST:
- Blueprint: .claude/plans/blueprints/session-7-skill-updates.md
- Plan steps 13, 19, 25: .claude/plans/ultraplan-2026-04-11-agent-factory.md
- The templates created in Sessions 3+4 (to reference accurately)

Execute steps 13, 19, 25:
13. Update agent-system-design skill with OpenClaw pattern references (memory-patterns.md, autonomy-patterns.md)
19. Update agent-system-design skill with Paperclip pattern references (orchestration-patterns.md, governance-patterns.md)
25. Create MCP integration reference (mcp-integrations.md)

SCOPE FENCE:
- Touch: skills/agent-system-design/SKILL.md, skills/agent-system-design/references/*
- NEVER touch: commands/, agents/, scripts/templates/

Steps 13 and 19 both modify SKILL.md — execute them SEQUENTIALLY.
Implement EXACTLY what the blueprint specifies. Commit after each step. Push when done.
```

---

## Wave 3 — Finalization (after Wave 1 Sessions 1+2 + Wave 2)

### Session 8: Build Command Integration

```
Agent Factory Session 8: Build Command Integration and Finalization.

PREREQUISITE: All Wave 1 + Wave 2 sessions must be complete. Verify:
  ls commands/deploy.md commands/evaluate.md commands/status.md &&
  ls skills/managed-agents/SKILL.md &&
  ls scripts/templates/domains/ | wc -l  # should be 11 (10 templates + README)
  ls skills/agent-system-design/references/memory-patterns.md

Read these files FIRST:
- Blueprint: .claude/plans/blueprints/session-8-finalization.md
- Plan steps 8, 26, 27: .claude/plans/ultraplan-2026-04-11-agent-factory.md
- Current state of commands/build.md (to understand what to modify)
- Current state of .claude-plugin/plugin.json

Execute steps 8, 26, 27:
8.  Update build command for domain templates and new features (Phase 0 template selection)
26. Update build command to integrate ALL Phase 2-5 features (memory, proactive, governance, goals, org-chart, budget, heartbeat, Docker)
27. Update plugin.json to v1.0.0, rewrite CLAUDE.md and README.md for full Agent Factory

Steps 8 and 26 both modify commands/build.md — execute them SEQUENTIALLY.
Step 27 is the final commit: "feat: Agent Factory v1.0.0"

SCOPE FENCE:
- Touch: commands/build.md, .claude-plugin/plugin.json, CLAUDE.md, README.md
- NEVER touch: scripts/templates/, skills/, agents/

After step 27, run ALL verification commands from the plan's Verification section.
Commit and push. Tag: git tag v1.0.0
```

---

## Post-Execution Verification

After all waves complete, run the full verification suite:

```bash
# All renamed
grep -r "agent-builder" . --include="*.md" --include="*.json" | grep -v ".git/" | grep -v "research/" | grep -v "ultraplan" | wc -l  # → 0

# Plugin manifest
python3 -c "import json; d=json.load(open('.claude-plugin/plugin.json')); print(d['name'], d['version'])"  # → agent-factory 1.0.0

# All commands
ls commands/ | sort  # → build.md deploy.md evaluate.md status.md

# All agents
ls agents/ | sort  # → builder.md deployment-advisor.md

# All skills
ls skills/ | sort  # → agent-system-design managed-agents

# Template directories
ls scripts/templates/ | sort  # → budget cron docker domains feedback goals governance heartbeat memory optimization org-chart proactive transfer + existing files

# Domain templates
ls scripts/templates/domains/*.md | wc -l  # → 11

# All bash scripts pass syntax check
find scripts/templates -name "*.sh" -exec bash -n {} \;  # → no errors

# All agents have valid frontmatter
find agents -name "*.md" -exec python3 -c "import yaml,sys; yaml.safe_load(open(sys.argv[1]).read().split('---')[1])" {} \;  # → no errors
```