generated from coulomb/repo-seed
Bootstrap coulomb-loop engagement: governance, loops, and activity definitions.
Register with state-hub, accept DEC-001–004 and ADR-004 rotation policy, scaffold pilot roster, hourly ActivityDefinition copies, and bootstrap log after schedule init on three custodian pilot repos.
This commit is contained in:
156
INTENT.md
Normal file
156
INTENT.md
Normal file
@@ -0,0 +1,156 @@
|
||||
# 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`
|
||||
Reference in New Issue
Block a user