snuggles-inventor/INTENT.md

---
domain: infotech
repo: snuggles-inventor
updated: "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:

1. **Ingest** the codebase into a living technical specification
2. **Plan** via an Agent Action Plan (AAP) or equivalent with human review
3. **Generate** in isolated environments with secrets kept out of model context
4. **Validate** build and tests before merge
5. **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:

1. **What codebase are we changing?** Ingestion, tech spec, dependency map.
2. **What should be built?** Prompts, rules, AAP / plan documents, human approval.
3. **How is code produced?** Multi-step generation, specialized agents, compile/runtime checks.
4. **Where does generation run?** By requesting sand-boxer build profiles — not by provisioning hosts.
5. **Does it work?** By invoking wise-validator (or delegating to CI) — not by owning e2e framework.
6. **How does it land?** PR creation, review workflow, merge/close/refine decisions.
7. **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.

```text
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:

```bash
# 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:

1. Resolve environment template (job-level or org base + override)
2. Call sand-boxer `create` with:
   - `profile: profile.build` (or `profile.agent-dev`)
   - `inputs.setup.instructions` — natural-language bootstrap text
   - `inputs.setup.secret_refs` — names only
   - `consumer: { harness: snuggles-inventor, actor: agt|atm, job_id }`
3. Run generation/build steps inside sandbox via glas-harness or invent worker
4. On job end or failure: sand-boxer `destroy` per 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:

1. `invent validate --job <id>` invokes wise-validator with repo ref at job branch
2. wise-validator requests its own sand-boxer profile (`profile.compose-e2e`) if needed
3. snuggles-inventor records pass/fail as job gate; does not parse `e2e.yml` itself

---

## Near-term outcomes (preliminary)

1. **This charter** — `INTENT.md` aligned with Coulomb sibling boundaries
2. **Job schema sketch** — phases, artifacts, approval gates
3. **sand-boxer integration doc** — build profile + setup metadata contract
4. **Minimal ingest + plan stub** — read repo, emit draft tech spec outline
5. **Forge extension stub** — branch + PR against Gitea remote
6. **Registry entry** — e.g. `capability.invention.codegen`
7. **State Hub job events** — phase transitions and PR links
8. **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.**