docs(plans): Agent Factory ultraplan + execution guide
27-step plan across 8 sessions in 3 waves for transforming agent-builder into Agent Factory v1.0.0. Includes research briefs, spec, and wave-by-wave execution prompts with scope fences. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Kjell Tore Guttormsen
parent
075383990f
commit
7419d4283d
5 changed files with 2294 additions and 0 deletions
346
.claude/plans/execution-guide.md
Normal file
346
.claude/plans/execution-guide.md
Normal file
|
|
@ -0,0 +1,346 @@
|
|||
# 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
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue