13 KiB
domain, repo, updated
| domain | repo | updated |
|---|---|---|
| infotech | snuggles-inventor | 2026-06-22 |
INTENT
snuggles-inventor is the Coulomb meta-framework for structured code generation and evolution — ingestion, planning artifacts, multi-agent generation, human-in-the-loop review, and PR-oriented output — while consuming sand-boxer for build environments and wise-validator for proof. This file is preliminary; refine as the invention boundary is implemented.
Naming note: Sibling docs in sand-boxer and glas-harness refer to this
project as snuggle-inventor (singular). This repository slug is
snuggles-inventor; align naming across repos in a future consistency pass.
Why it exists
Custodian domains need large, structured code changes — features, refactors, modernization, security fixes — without every team operating a bespoke codegen pipeline, prompt playbook, and review workflow.
Commercial platforms (notably Blitzy) demonstrate a durable pattern:
- Ingest the codebase into a living technical specification
- Plan via an Agent Action Plan (AAP) or equivalent with human review
- Generate in isolated environments with secrets kept out of model context
- Validate build and tests before merge
- Ship as a pull request with human gates at every critical step
That pattern bundles invention concerns (spec, generation, PR) with runtime concerns (sandboxes, tests, agent sessions) when implemented as a monolith. Coulomb splits the stack:
| Layer | Owner |
|---|---|
| Code generation and evolution | snuggles-inventor |
| Sandbox establishment | sand-boxer |
| E2e and health validation | wise-validator |
| Agent harness | glas-harness |
snuggles-inventor exists to be the invention layer: one consistent way to generate and evolve code with extensions for ingestors, planners, generators, and forge integrations — environments from sand-boxer, proof from wise-validator, optional agent UX from glas-harness.
sand-boxer establishes where work runs. snuggles-inventor invents what to merge.
The governing principle
snuggles-inventor is the code generation and evolution service — repository understanding, planning artifacts, generation orchestration, review gates, and PR emission. Nothing more.
It answers:
- What codebase are we changing? Ingestion, tech spec, dependency map.
- What should be built? Prompts, rules, AAP / plan documents, human approval.
- How is code produced? Multi-step generation, specialized agents, compile/runtime checks.
- Where does generation run? By requesting sand-boxer build profiles — not by provisioning hosts.
- Does it work? By invoking wise-validator (or delegating to CI) — not by owning e2e framework.
- How does it land? PR creation, review workflow, merge/close/refine decisions.
- What happened? Job lifecycle and audit events to State Hub.
It must not become the sandbox provisioner, the validation orchestrator, the agent gateway, the scheduler, work-state authority, tunnel/CA owner, or production deployer on Railiance01.
Coulomb sibling boundaries
sand-boxer — sandbox establishment
sand-boxer owns: Profiles, extensions, provision/teardown, placement, secret resolution at the provision boundary.
snuggles-inventor owns: Attaching setup metadata (Blitzy-style natural-
language build instructions, secret_refs, variable names) as inputs when
requesting a build sandbox. Generated source never transits sand-boxer APIs.
snuggles-inventor sand-boxer
─────────────── ──────────
job needs build env → POST /v1/sandboxes
profile: profile.build (or similar)
setup: { instructions, secret_refs }
agents run in sandbox via harness ← sandbox_id + reachability
destroy when job completes → DELETE /v1/sandboxes/{id}
wise-validator — e2e test and health
wise-validator owns: e2e.yml contracts, health polling, test commands,
pass/fail reporting.
snuggles-inventor owns: Triggering validation after generation (job step), interpreting pass/fail as a merge gate — not reimplementing health-wait or test runners.
Typical job DAG: generate → build in sandbox → wise-validator.run → open PR.
glas-harness — agent harness
glas-harness owns: Agent sessions, tools, memory, channels.
snuggles-inventor does not replace the harness. Long-running codegen may use glas-harness for operator chat UX; snuggles-inventor owns the job model, artifacts (spec, AAP, PR), and generation pipeline either way.
Boundary diagram
Human reviewer / glas-harness (optional UX)
│
▼
snuggles-inventor
(invent + evolve)
│
┌─────────────┼─────────────┐
▼ ▼ ▼
sand-boxer wise-validator forge (Gitea/GitHub)
(build env) (prove) (PR)
Existing Custodian repos
| Concern | Owner |
|---|---|
| Workstream, task, progress state | state-hub |
| Cron and orchestration | activity-core |
| SSH reverse tunnels | ops-bridge |
| SSH certificate issuance | ops-warden |
| Canon and agent instruction canon | the-custodian |
| Capability federation hub | reuse-surface |
| LLM inference routing | llm-connect |
| Agent runtime | glas-harness |
| Production on Railiance01 | railiance-apps / domain repos |
snuggles-inventor consumes sand-boxer, wise-validator, llm-connect, and forge integrations; it does not subsume them.
What it is
snuggles-inventor is a meta-framework with four pillars (preliminary):
1. Unified invention API
One surface for codegen jobs:
# Conceptual CLI (v0)
invent ingest --repo <url|path>
invent plan --job <id> # AAP / plan generation + human review gate
invent generate --job <id> # runs in sand-boxer-backed env
invent validate --job <id> # delegates to wise-validator
invent publish --job <id> # open or update PR
invent status --job <id>
HTTP: POST /v1/jobs, GET /v1/jobs/{id}, phase transitions with explicit
human approval endpoints where required.
Consumers: human operators (adm), activity-core workflows (atm), glas-harness
agent tools (agt).
2. Job lifecycle and artifacts
Structured phases (Blitzy-aligned, Coulomb-owned):
| Phase | Artifact | Human gate |
|---|---|---|
| Ingestion | Codebase map, dependency graph | Optional |
| Tech spec | Living spec document | Review recommended |
| Plan | AAP / implementation plan | Required before generate |
| Generate | Branch, diff, build log | Review before publish |
| Validate | wise-validator result | Required for auto-publish policies |
| Publish | Pull request | Required before merge |
Job state is snuggles-inventor authority; workstream/task linkage is State Hub.
3. Extension platform
Extensions delegate invention mechanics:
| Extension class | Examples |
|---|---|
| Ingestor | Git checkout, monorepo scan, submodule-aware ingest |
| Spec builder | Tech spec templates, architecture diagrams, API contracts |
| Planner | AAP generator, rule-aware plan refinement |
| Generator | Multi-agent codegen, language-specific workers |
| Forge | Gitea, GitHub, GitLab PR and branch operations |
| Policy | Org rules (style, security, test coverage requirements) |
Extensions call llm-connect for inference; they do not embed provider SDKs as the only path.
4. Environment and secret model (Blitzy-derived)
Generation jobs declare environment intent, sand-boxer fulfills runtime:
| Concept | Owner |
|---|---|
| Natural-language setup instructions | snuggles-inventor job config |
${VAR} names in instructions |
snuggles-inventor |
| Secret values | Resolved by sand-boxer / platform secret store — never in LLM prompts |
| UI login credentials for auth-gated apps | Secret refs for validation steps |
Variables (non-sensitive) may appear in specs; secrets are referenced by name only.
What it is not
| Concern | Owner |
|---|---|
| Sandbox provision, host SSH, compose lifecycle | sand-boxer |
E2e tests, health checks, e2e.yml |
wise-validator |
| Agent gateway, session tools, channels | glas-harness |
| When jobs are scheduled | activity-core |
| Task/workstream canonical state | state-hub |
| Model routing and API keys | llm-connect |
| General issue tracking | issue-core |
snuggles-inventor produces code change proposals. It does not operate production services or replace domain repo ownership.
Lineage and research inputs
Blitzy (primary commercial reference)
Patterns to adopt (platform docs: https://docs.blitzy.com/):
- Human-in-the-loop at plan, guide, and PR review stages
- Tech spec as foundation kept in sync with the repo
- Environment configuration separate from codegen logic
- Secrets encrypted and masked; never sent to AI models
- Multi-environment merge (base + project override)
- Validation signals before merge (build, tests, optional Computer Use)
- Prompt templates and golden rules as registered policy extensions
Blitzy Sandbox (GitHub org) is demo content — not runtime infrastructure. snuggles-inventor is not a Blitzy clone; it is Coulomb's self-hosted invention meta-framework with the same separation discipline as sand-boxer.
sand-boxer research
sand-boxer/research/02-reference-frameworks.md — Blitzy environment metadata
maps to sand-boxer profile setup blocks; snuggles-inventor supplies the text,
sand-boxer supplies the box.
Coulomb forge
PR and branch operations integrate with org forge (Gitea remote, GitHub, etc.) via forge extensions — not via sand-boxer.
Intended users
- Human operators (
adm) — approve plans, review PRs, configure environments - Engineering leads — delegate large refactors without losing review gates
- Deterministic automations (
atm) — activity-core triggered modernization jobs - LLM agents (
agt) — via glas-harness tools that start/snippet invent jobs - Domain repos — targets of ingestion; do not embed codegen infrastructure
- Extension authors — ingestors, planners, forge adapters
Design principles
- Invention meta-framework, not monolith — one job API; extensions per phase
- Human gates by default — no silent merge of large generated diffs
- sand-boxer for environments — never embed provisioners in invent pipeline
- wise-validator for proof — declarative validation, not inlined pytest hacks
- Secrets never in prompts — reference names only; Blitzy discipline
- Spec before code — tech spec and approved plan precede generation
- PR-oriented output — branches and PRs, not direct pushes to protected branches
- Observable jobs — every phase transition attributable (
adm/agt/atm) - Registry-first reuse — register invention capabilities in
registry/ - Evolution, not one-shot — support refine, regenerate, and incremental jobs
sand-boxer consumption contract (preliminary)
When a generation job needs a build environment:
- Resolve environment template (job-level or org base + override)
- Call sand-boxer
createwith:profile: profile.build(orprofile.agent-dev)inputs.setup.instructions— natural-language bootstrap textinputs.setup.secret_refs— names onlyconsumer: { harness: snuggles-inventor, actor: agt|atm, job_id }
- Run generation/build steps inside sandbox via glas-harness or invent worker
- On job end or failure: sand-boxer
destroyper job cleanup policy
Generated file contents flow through git/PR APIs — never through sand-boxer.
wise-validator consumption contract (preliminary)
After generation, when validation is required:
invent validate --job <id>invokes wise-validator with repo ref at job branch- wise-validator requests its own sand-boxer profile (
profile.compose-e2e) if needed - snuggles-inventor records pass/fail as job gate; does not parse
e2e.ymlitself
Near-term outcomes (preliminary)
- This charter —
INTENT.mdaligned with Coulomb sibling boundaries - Job schema sketch — phases, artifacts, approval gates
- sand-boxer integration doc — build profile + setup metadata contract
- Minimal ingest + plan stub — read repo, emit draft tech spec outline
- Forge extension stub — branch + PR against Gitea remote
- Registry entry — e.g.
capability.invention.codegen - State Hub job events — phase transitions and PR links
- Policy extension hook — org rules file format (successor to Blitzy rules)
Maturity target
A mature snuggles-inventor is Coulomb's default structured codegen path:
- Large refactors start with ingestion and spec, not ad hoc agent sessions
- Every generate phase runs in sand-boxer-backed environments with secret hygiene
- wise-validator gates merge for repos with
e2e/contracts - Humans approve plans and PRs; automations never bypass both gates silently
- glas-harness can drive jobs conversationally without owning the pipeline
- Domain repos stay thin —
INTENT.md, code, tests — not embedded invent infra
sand-boxer establishes the box. glas-harness runs the agent. wise-validator proves it works. snuggles-inventor invents what ships.