agent-builder/.claude/plans/execution-guide.md

Agent Factory — Execution Guide

Vision

Agent Factory gjør det mulig for alle å lage egne agentløsninger som gjør reelle oppgaver — gjennom en guidet, profesjonell prosess fra ide til produksjon.

Full lifecycle: Ide → Design → Build → Test → Deploy → Monitor → Improve

Zero barrier: Brukeren installerer ktg-plugin-marketplace og får Agent Factory + ultra-suiten (ultraplan, ultraresearch, ultraexecute). Ingenting annet trengs — ingen servere, ingen databaser, ingen konfigurasjon. Bare Claude Code og en plugin.

Arkitektur: Pluginens verdi er domenekunnskap (hva som utgjør et godt agent-system). Ultraplan er motoren (hvordan det bygges profesjonelt). Pluginen er en tynn orkestrator som kjører et domenespesifikt intervju, mater resultatet til ultraplan, og lar ultraexecute implementere planen.

Deployment er et valg: Lokal (cron/launchd), VPS (systemd), Docker, eller Managed Agents (begrenset — ingen MCP-støtte). Alle targets med full MCP er likeverdige. Brukeren velger basert på sine behov.

Inspirasjon, ikke konkurranse: OpenClaw og Paperclip er referanseimplementasjoner vi lærer av. Agent Factory konkurrerer ikke med dem — vi løser et annet problem.

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.

VISION (read this first — it shapes everything):
Agent Factory gjør det mulig for alle å lage egne agentløsninger som gjør
reelle oppgaver. Full lifecycle: Ide → Design → Build → Test → Deploy → Monitor → Improve.
Zero barrier: bruker installerer ktg-plugin-marketplace, får Agent Factory + ultra-suiten.
Ingenting annet trengs. Pluginen er en tynn orkestrator med domenekunnskap — ultraplan
er motoren. OpenClaw og Paperclip er inspirasjon, ikke konkurrenter.

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)

ARCHITECTURAL CONTEXT for blueprints:
  - Build command (Session 8) should be a thin orchestrator: run domain-specific
    interview → produce spec → feed to ultraplan → ultraexecute implements.
    Standalone mode as fallback when ultraplan is not installed.
  - Build command includes pause/resume mechanism (build-state.json) for when
    users need to create MCP servers or skills between phases.
  - Phase 3.5: Skills connection (existing or custom, with pause/resume)
  - Phase 4.5: MCP server integration (connect existing, guide creation, pause/resume)
  - Deployment targets: cron/launchd, systemd, Docker (full MCP support).
    Managed Agents as limited option (no MCP — only simple agents).
  - README must prominently recommend ktg-plugin-marketplace installation.
  - README value proposition: "Install one plugin, build complete agent systems
    that do real work. No servers, no databases, no configuration."

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:
    - Phase 2.5: Memory setup
    - Phase 3.5: Skills & custom components (with pause/resume via build-state.json)
    - Phase 3.7: Proactive agent (ADL/VFM)
    - Phase 4.5: Integrations & MCP servers (connect existing, guide creation, pause/resume)
    - Phase 5.5: Governance (autonomy levels, approval gates, budget)
    - Phase 5.7: Goals and org chart
    - Phase 6: Deployment target selection (ALL targets with trade-offs, user MUST choose)
    - Phase 7: Feedback loop setup
    - Resume mechanism: --resume flag reads build-state.json
27. Update plugin.json to v1.0.0, rewrite CLAUDE.md and README.md for full Agent Factory

CRITICAL ARCHITECTURAL DECISIONS for Step 26 (build command):
- Build command should be a THIN ORCHESTRATOR: run domain-specific interview,
  produce spec, feed to ultraplan-local if available, fall back to standalone if not.
- Detect ultraplan availability: check if /ultraplan-local skill exists.
  If yes: offer "Professional mode (recommended): uses ultraplan for deep planning"
  If no: run standalone build workflow (current monolithic approach)
- Build must support pause/resume: build-state.json persists all state between sessions

CRITICAL for Step 27 (README):
- README must prominently recommend ktg-plugin-marketplace:
  "## Prerequisites\n\nInstall the plugin marketplace for the full experience:\n\n```\n/install ktg-plugin-marketplace\n```\n\nThis gives you Agent Factory + the ultra-suite (ultraplan, ultraresearch,\nultraexecute) for professional-grade agent system development."
- Value proposition: "Install one plugin, build complete agent systems that do
  real work. Full lifecycle from idea to production. No servers, no databases,
  no configuration — just Claude Code."
- Deployment targets section with honest trade-offs (Managed Agents = limited, no MCP)
- Credit OpenClaw + Paperclip as inspiration, not competitors

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:

# 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