Skip to main content

Project Plan

Documentation Map​

Project Plan

Product Goal​

jhf-warp becomes the standalone orchestration control plane for OpenClaw-based multi-agent delivery.

It should:

  • classify work and generate the correct agent setup
  • keep runtime topology aligned with the real OpenClaw installation
  • manage allowed communication paths and trust levels
  • synchronize topology-sensitive systems such as Helpifyr Pattern and jhf-shuttle
  • generate bounded bootstrap bundles with small, role-specific context
  • support bounded sub-agents and second-pass stabilization work

Delivery Strategy​

The implementation should happen in three broad passes:

  1. foundation

    • service contract
    • state model
    • topology model
    • compatibility model

  2. runtime integration

    • OpenClaw discovery
    • safe config patching
    • topology sync
    • Helpifyr Pattern visibility

  3. hardening

    • sub-agent lifecycle
    • second-pass orchestration
    • regression and drift safety
    • packaging for macOS and Linux

Definition Of Done​

A slice is done only when:

  • code is implemented
  • targeted tests pass
  • docs and contracts are updated if behavior changed
  • no unrelated breakage is introduced
  • cross-platform assumptions were considered

A sprint is done only when:

  • all listed slices are complete
  • integration behavior is verified at the intended level
  • open risks are documented

Phase 0 - Foundations And Repo Setup​

Sprint 0.1 - Bootstrap The Product Skeleton​

Goal:

  • establish the repo as a real implementation home

Slices:

  • choose backend stack and package layout
  • define src/, tests/, docs/, scripts/ structure
  • add Python project metadata
  • add lint/test/typecheck baseline
  • add minimal make/task runner commands that work on macOS and Linux
  • add .env.example
  • add initial CI workflow for Linux

Acceptance:

  • clean local bootstrap on macOS and Linux
  • basic CI can install and run empty baseline checks

Sprint 0.2 - Core Domain Model​

Goal:

  • define the core orchestration entities before building adapters

Slices:

  • model TaskProfile
  • model TeamSetup
  • model AgentRoleAssignment
  • model BootstrapBundle
  • model TopologySnapshot
  • model TopologyPatchPlan
  • model CompatibilityRule
  • model AuditEvent

Acceptance:

  • domain models covered by unit tests
  • serialization contracts stable

Sprint 0.3 - API Skeleton​

Goal:

  • create the control-plane shape

Slices:

  • add API app skeleton
  • add health/version endpoints
  • add POST /api/v1/setup/preview
  • add GET /api/v1/topology/current
  • add GET /api/v1/audit/events
  • add OpenAPI generation
  • add contract tests for early endpoints

Acceptance:

  • API boots locally
  • first endpoints respond with typed placeholder payloads

Phase 1 - Setup Generation Engine​

Sprint 1.1 - Task Classification​

Goal:

  • classify work by systems, risk, and execution mode

Slices:

  • define task taxonomy
  • add scoring for feature, bugfix, live-debug, release-hardening, UI, integration, simulation
  • add risk flags and live-impact flags
  • add default verification level selection
  • add classification tests with representative tasks from Helpifyr Pattern, Helpifyr Spindle, jhf-shuttle

Acceptance:

  • same task input yields deterministic classification

Sprint 1.2 - Team Composition Engine​

Goal:

  • generate the right main/support setup for a task

Slices:

  • add role capability registry
  • define lead/support/sub-agent selection rules
  • add exclusion rules for unnecessary roles
  • add context-budget selection per role
  • add output diff view for why a role was selected

Acceptance:

  • setup generation is explainable and deterministic

Sprint 1.3 - Bootstrap Compiler V1​

Goal:

  • compile structured bootstraps from generated setup

Slices:

  • define global bootstrap schema
  • define project bootstrap schema
  • define task bootstrap schema
  • define role bootstrap schema
  • add compiler output in JSON/YAML
  • add derived markdown rendering for human review

Acceptance:

  • compiler outputs stable artifacts from the same inputs

Phase 2 - OpenClaw Runtime Discovery And Safe Apply​

Sprint 2.1 - Installation Discovery​

Goal:

  • detect real OpenClaw installation state

Slices:

  • add version detection adapter
  • add config path detection
  • add runtime capability detection
  • add schema-generation mapping
  • add current team/topology parsing

Acceptance:

  • service can read a real or fixture-based OpenClaw installation snapshot

Sprint 2.2 - Topology Diffing​

Goal:

  • compare desired and actual state

Slices:

  • diff agent inventory
  • diff allowed communication paths
  • diff trust-mode edges
  • diff runtime constraints
  • render human-readable drift summaries

Acceptance:

  • desired vs actual drift is reproducible and test-covered

Sprint 2.3 - Safe Patch Planning​

Goal:

  • generate non-destructive patch plans

Slices:

  • patch planning for openclaw.json
  • compatibility validation against runtime version
  • rejection of unsupported mutations
  • explicit dry-run output
  • rollback notes generation

Acceptance:

  • unsafe changes are rejected before apply

Sprint 2.4 - Apply And Verify​

Goal:

  • support safe hot-reload-aware updates

Slices:

  • write patch application layer
  • trigger hot reload when supported
  • verify post-apply topology
  • emit audit events and correlation IDs
  • add integration tests against fixture runtime states

Acceptance:

  • safe mutations can be applied and verified end-to-end in a test harness

Phase 3 - Communication Graph And Topology Sync​

Sprint 3.1 - Communication Graph Model​

Goal:

  • make communication policy explicit

Slices:

  • model agents, sub-agents, services, callbacks as graph nodes
  • model edges with trust mode, transport, escalation target, review requirement
  • add graph serialization and validation

Acceptance:

  • graph can represent OpenClaw and n8n delivery paths

Sprint 3.2 - jhf-shuttle Sync Contract​

Goal:

  • make downstream routing synchronization explicit

Slices:

  • define topology sync payload contract
  • add POST /api/v1/integrations/jhf-shuttle/topology-sync
  • add full snapshot endpoint
  • add history endpoint
  • add contract tests and example payload docs

Acceptance:

  • topology changes produce versioned sync payloads

Sprint 3.3 - Drift Detection​

Goal:

  • catch stale assumptions between systems

Slices:

  • compare desired topology vs OpenClaw snapshot
  • compare desired topology vs last synced jhf-shuttle view
  • classify drift severity
  • emit drift alerts and audit evidence

Acceptance:

  • stale routes and trust-path mismatches are flagged clearly

Phase 4 - Helpifyr Pattern Integration​

Sprint 4.1 - Setup Request Surface​

Goal:

  • let operators ask for generated setups

Slices:

  • define Helpifyr Pattern integration contract
  • add setup preview payload shape
  • add topology diff view payload shape
  • add rollout approval payload shape

Acceptance:

  • Helpifyr Pattern can request setup previews without embedding orchestration logic

Sprint 4.2 - Operator Review And Approvals​

Goal:

  • support guarded runtime changes

Slices:

  • add approval states
  • add safe auto-apply vs approval-gated mutation policy
  • add operator comments/evidence fields
  • add approval tests

Acceptance:

  • risky changes are blocked pending approval

Sprint 4.3 - Runtime Visibility Pack​

Goal:

  • improve operator observability

Slices:

  • expose runtime inventory endpoint
  • expose rollout history endpoint
  • expose drift summary endpoint
  • expose bootstrap preview endpoint

Acceptance:

  • Helpifyr Pattern can show generated setup, drift, and rollout state from the API

Phase 5 - Product-Specific Profiles​

Sprint 5.1 - Helpifyr Pattern Profiles​

Slices:

  • setup templates for UI rebuild
  • setup templates for live-debug
  • setup templates for runtime bridge work
  • verification matrix for deployed UI behavior

Sprint 5.2 - Helpifyr Spindle Profiles​

Slices:

  • finance-domain profile
  • HiL/approval-heavy profile
  • simulation-harness profile
  • live-adjacent smoke profile

Sprint 5.3 - jhf-shuttle Profiles​

Slices:

  • topology contract profile
  • release-hardening profile
  • runtime sync/debug profile

Sprint 5.4 - Mem0 Capability Profiles​

Slices:

  • memory-capability detection input
  • optional memory-aware bootstrap hints
  • fallback behavior when memory kit absent

Acceptance for Phase 5:

  • product families get narrower, more useful default setups than a generic team generator

Phase 6 - Sub-Agents And Second Pass​

Sprint 6.1 - Sub-Agent Lifecycle​

Goal:

  • support bounded ephemeral workers

Slices:

  • define sub-agent profile model
  • define parent-child ownership rules
  • define expiry/promotion rules
  • add minimal inherited bootstrap projection

Sprint 6.2 - Second-Pass Orchestration​

Goal:

  • support build-first then polish/debug passes

Slices:

  • add second-pass policy to setup generation
  • add adjacent-fix allowance rules
  • add verification-intensity modes
  • add second-pass audit labeling

Sprint 6.3 - Queue And Handoff Semantics​

Goal:

  • make sub-agent work safe and inspectable

Slices:

  • queue payload model
  • handoff model
  • result and failure reporting model
  • bounded-scope verification rules

Acceptance:

  • sub-agents can be generated without receiving oversized project context

Phase 7 - MCP Surface​

Sprint 7.1 - Read Tools​

Slices:

  • get_runtime_topology
  • get_topology_diff
  • get_team_setup_preview
  • get_rollout_audit

Sprint 7.2 - Safe Action Tools​

Slices:

  • plan_openclaw_patch
  • trigger_safe_apply
  • sync_n8n_topology
  • preview_bootstrap_bundle

Sprint 7.3 - Agent-Oriented Tools​

Slices:

  • generate_subagent_plan
  • explain_role_selection
  • explain_verification_matrix

Acceptance:

  • MCP tools are thin wrappers over stable API behavior

Phase 8 - Packaging, Regression, Release Candidate​

Sprint 8.1 - Native Dev Experience​

Slices:

  • macOS install path
  • Linux install path
  • platform notes and bootstrap script
  • developer smoke checks

Sprint 8.2 - Container Path​

Slices:

  • Dockerfile
  • Compose profile for API + DB + fixture integrations
  • integration-test container path

Sprint 8.3 - End-To-End Regression Harness​

Slices:

  • fixture OpenClaw installations
  • fixture topology histories
  • fixture jhf-shuttle sync receiver
  • regression suite for desired-vs-actual flows

Sprint 8.4 - Release Candidate​

Slices:

  • release checklist
  • compatibility matrix
  • security/config review
  • operator runbook

Acceptance:

  • product is usable natively on macOS and Linux
  • container path works for CI and reproducible integration runs
  1. Phase 0
  2. Phase 1
  3. Phase 2
  4. Phase 3
  5. Phase 4
  6. Phase 5
  7. Phase 6
  8. Phase 7
  9. Phase 8

Best-Practice Gaps To Remember​

Do not forget:

  • explicit compatibility registry for OpenClaw versions and config schema variants
  • approval tiers for risky runtime mutation
  • topology graph as first-class data, not just docs
  • correlation IDs across rollout and sync events
  • idempotent topology sync
  • audit evidence for every mutation
  • bounded sub-agent inheritance
  • second-pass quality mode
  • platform-aware packaging for both macOS and Linux

License​

AGPLv3. See ../LICENSE (LICENSE). Learn more at helpifyr.com.