coulomb/snuggles-inventor
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Seeded intent

Browse Source
This commit is contained in:
Bernd Worsch
2026-06-22 21:42:30 +02:00
parent c7f568663e
commit 58a7ef4a68
1 changed files with 347 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

347
INTENT.md Normal file
View File

@@ -0,0 +1,347 @@
---
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.**