coulomb-loop/INTENT.md

INTENT — coulomb-loop

Project Name

coulomb-loop

One-Line Intent

coulomb-loop is Coulomb's engagement repository for scheduled self-improvement loops — operated with kaizen-agentic as supplier, activity-core as scheduler, and state-hub as fleet roster.

Purpose

Coulomb operates a large, multi-domain software fleet (56+ registered repositories). Improvement cannot rely on ad-hoc sessions alone. This repository exists to organize, contract, and operate recurring agent-driven improvement loops across that fleet — without absorbing kaizen agents into Coulomb's own codebase.

The engagement model is deliberate:

Role	Owner	Responsibility
Customer	Coulomb (coulomb-loop)	Defines what to improve, which repos, at what cadence, and acceptance criteria
Supplier	kaizen-agentic	Provides agents, CLI tooling, memory/metrics conventions, and engagement playbooks
Scheduler	activity-core	Fires cron/event triggers, resolves fleet roster, creates tasks
Roster	state-hub	Canonical repo list, host_paths, workstreams, progress events
Registry	reuse-surface	Capability maturity and registry hygiene signals

Agents are not Coulomb employees. They are supplier-provided personas that accumulate project-scoped memory (.kaizen/agents/<name>/memory.md) and execution metrics while working in Coulomb's context. That knowledge stays portable: it improves supplier efficiency for the next customer engagement.

Core Idea

Self-improvement at fleet scale needs a customer engagement repo, not more agents inside the supplier repo.

coulomb-loop holds everything Coulomb needs to run the loops:

• workplans and acceptance criteria for each loop
• fleet roster declarations (which repos participate in which loop)
• ActivityDefinition copies tuned for Coulomb cadence
• loop health records and cadence ramp policy
• decisions and progress events surfaced to state-hub

kaizen-agentic holds the reusable supplier IP: agent definitions, CLI, ADRs, and — after this engagement — a customer-repo bootstrap playbook so the next engagement starts faster.

The Four Loops

This engagement establishes four coordinated workstreams:

Workplan	Loop	Primary agents	Target
LOOP-WP-0001	Kaizen improvement stack	coach, optimization	Evidence-backed weekly-style improvement (metrics → synthesis → action)
LOOP-WP-0002	Reactive quality escalation	optimization, test-maintenance	Signal-driven tasks when agent or test health degrades
LOOP-WP-0003	Registry & orientation hygiene	scope-analyst, reuse-surface CLI	Fleet legibility — SCOPE, capability registry, SBOM alignment
LOOP-WP-0004	Loop regulator (second-order)	optimization, tooling-optimization	Monitor, throttle, and optimize the three primary loops

Loops 1–3 are first-order improvement. Loop 4 is second-order: it observes whether the first-order loops are worth their cost and tunes them.

Cadence Ramp Policy

Loops start fast to prove mechanics, then slow as noise drops and trust rises.

Phase	Cadence	Entry condition	Exit / promote condition
Bootstrap	Hourly	Loop workplan active; activity-core definition synced	3 consecutive successful end-to-end runs without manual rescue
Stabilize	Daily	Bootstrap exit met for all tasks in the loop	2 weeks daily runs; false-positive rate < 20%; loop regulator approves
Operate	Weekly	Stabilize exit met	Loop regulator may demote on sustained noise or missed SLAs

Cadence is stored per loop in loops/<loop-id>/cadence.yml (to be created in LOOP-WP-0004). The loop regulator owns promotions and demotions; operators approve demotions below daily.

Repo rotation (diminishing returns)

When optimization on a repo plateaus, the regulator classifies it saturated and rotates focus to the next repo in loops/kaizen-stack/roster.yaml expansion_queue (ADR-004). Coach runs may continue; optimization agent sessions shift to higher marginal-value targets. Implementation: LOOP-WP-0004 T09.

Hourly during bootstrap is intentional. It compresses feedback time while resolver wiring, task payloads, and session-close metrics are still fragile. It is not the long-term operating frequency.

Scope

In scope

• Operating scheduled improvement loops across the Coulomb fleet
• Declaring fleet participation rosters and per-target-repo opt-in (.kaizen/schedule.yml in target repos)
• Committing ActivityDefinition copies scoped to this engagement
• Recording loop health, cadence phase, and supplier feedback for kaizen-agentic reuse
• Progress events and decisions via state-hub once coulomb-loop is registered
• Pilot on custodian-domain repos, then expand domain-by-domain

Out of scope

• Owning kaizen agent definitions (supplier: kaizen-agentic)
• Implementing Temporal workers or context resolvers (owner: activity-core)
• State-hub schema changes (owner: the-custodian / state-hub)
• Replacing human approval for high-risk changes (releases, infra remediation)
• Merging agents into Coulomb application repositories

Fleet Context

The Coulomb cocreation environment today includes:

• 56 repos registered in state-hub across 12 domains
• 53 repos with reuse-surface registry/ federation participation
• 20 kaizen agents available from supplier (kaizen-agentic)
• activity-core already runs custodian jobs (e.g. SBOM staleness, coding retro)
• kaizen ActivityDefinitions drafted in supplier repo (enabled: false; resolver pending)

coulomb-loop does not duplicate that inventory. It consumes it and declares which slices participate in which loop.

Supplier Feedback Loop

This engagement is also a product-development exercise for kaizen-agentic:

1. Document what a minimal customer engagement repo must contain
2. Capture friction from bootstrap (missing CLI, unclear handoffs, resolver gaps)
3. Feed findings into a future supplier workplan (KAIZEN-WP-0008 or equivalent): customer-repo template, schedule init --engagement, engagement checklist

Success for Coulomb and the supplier means the second customer engagement requires materially less setup than this one.

Design Principles

1. Repo-local opt-in — a target repo joins a loop only with valid .kaizen/schedule.yml (or loop-specific roster entry).
2. Prepare, don't invoke — scheduled tasks run kaizen-agentic schedule prepare; sessions execute agent instructions.
3. Measure every loop — session close records metrics; loop regulator reads aggregate health.
4. Fail loud, fail small — bootstrap hourly runs surface breakage quickly; one repo per pilot before fleet fan-out.
5. Second-order before scale — do not promote cadence or expand roster until LOOP-WP-0004 approves.

Success Criteria

1. Three first-order loops run end-to-end on ≥3 pilot repos with activity-core task creation and successful schedule prepare sessions.
2. Loop regulator (LOOP-WP-0004) produces weekly health summaries and has demoted or promoted cadence at least once based on evidence.
3. Supplier playbook draft exists in kaizen-agentic citing coulomb-loop as reference engagement.
4. coulomb-loop registered in state-hub with workstreams synced from workplans/.

Related Documents

• workplans/LOOP-WP-0001-kaizen-improvement-stack.md
• workplans/LOOP-WP-0002-reactive-quality-escalation.md
• workplans/LOOP-WP-0003-registry-orientation-hygiene.md
• workplans/LOOP-WP-0004-loop-regulator.md
• Supplier: kaizen-agentic ADR-005, docs/integrations/activity-core-handoff-wp0006.md
• Scheduler: activity-core ActivityDefinition catalog
• Registry: reuse-surface docs/RegistryFederation.md