docs: frozen v1.0 bundle format specs (manifest, agent-card, o1 package structure)
This commit is contained in:
@@ -0,0 +1,9 @@
|
|||||||
|
# business-depo
|
||||||
|
|
||||||
|
OrenStack Depot — the business bundle store. Signed, installable business
|
||||||
|
packages (bundles) distributed from the self-hosted forge at git.orenstack.com.
|
||||||
|
|
||||||
|
See `docs/specs/` for the frozen v1.0 format specs:
|
||||||
|
- `manifest-spec.md` — bundle manifest format (v1.0)
|
||||||
|
- `agent-card-spec.md` — agent card schema (v1.0)
|
||||||
|
- `o1-package-structure.md` — o1 bundle package layout (v1.0)
|
||||||
@@ -0,0 +1,74 @@
|
|||||||
|
# Neutral Agent Card — Spec v1.0 (DRAFT)
|
||||||
|
|
||||||
|
The portable definition of a specialist. Runtime-agnostic: any agent runtime
|
||||||
|
(opencode here, a standalone server, an Odoo-side runner) can interpret a card.
|
||||||
|
This is the "Docker model": the format is neutral, the runtime ships or is
|
||||||
|
preinstalled per target.
|
||||||
|
|
||||||
|
## File
|
||||||
|
|
||||||
|
One JSON file per agent in `agents/`.
|
||||||
|
|
||||||
|
## Schema
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"schema_version": "1.0",
|
||||||
|
"agent_id": "o1-sellers-recruiter",
|
||||||
|
"name": "Seller Recruiter",
|
||||||
|
"role": "specialist",
|
||||||
|
"description": "Finds and recruits consignment sellers for O1 on OLX and local forums",
|
||||||
|
"model_hint": "free-tier",
|
||||||
|
"persona": "Practical Bulgarian business developer; direct, trustworthy; works in BG+EN",
|
||||||
|
"prompt_files": ["prompts/sellers-recruiter.md"],
|
||||||
|
"tools": ["odoo.search_records", "odoo.create_record", "file.read", "script.run"],
|
||||||
|
"memory": {
|
||||||
|
"engine": "brain",
|
||||||
|
"script": "brain/brain.py",
|
||||||
|
"namespace": "o1-sellers"
|
||||||
|
},
|
||||||
|
"gates": ["hours"],
|
||||||
|
"verification": {
|
||||||
|
"definition_of_done": "Confirmed N sellers recruited with signed consignment agreements this cycle",
|
||||||
|
"check": "odoo.search_records('o1.seller', [['status','=','signed']]).count >= N"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Field rules
|
||||||
|
|
||||||
|
1. **`model_hint`** is a *class* (`free-tier` / `balanced` / `max`), never a
|
||||||
|
concrete vendor model ID. Each runtime maps hints to its own models
|
||||||
|
(here: `free-tier` → `opencode/mimo-v2.5-free`).
|
||||||
|
2. **`tools`** are declared by *name* against a shared tool registry — no
|
||||||
|
inline code in cards. The runtime resolves names to implementations.
|
||||||
|
3. **`prompt_files`** keep prompts external (markdown) — cards stay data.
|
||||||
|
4. **`memory`** points to a brain script + namespace; the card never carries
|
||||||
|
memory content.
|
||||||
|
5. **`verification`** is mandatory — a machine-checkable definition of done.
|
||||||
|
A card without one is rejected by the validator. ("I processed X" is never
|
||||||
|
done; "I confirmed X exists/counts" is done.)
|
||||||
|
6. **`gates`** are named constraints (working hours, irreversible-action gate)
|
||||||
|
resolved by the runtime.
|
||||||
|
7. No runtime-specific syntax, no absolute paths, no secrets.
|
||||||
|
|
||||||
|
## Mapping: neutral card ↔ opencode agent
|
||||||
|
|
||||||
|
The converter is a small script; both directions must round-trip losslessly
|
||||||
|
(convert → back → identical hash).
|
||||||
|
|
||||||
|
| Neutral card field | opencode agent (`agent/*.md` frontmatter / body) |
|
||||||
|
|---|---|
|
||||||
|
| `description` | frontmatter `description` |
|
||||||
|
| `model_hint` | frontmatter `model` (resolved via model map) |
|
||||||
|
| `tools` | frontmatter tool booleans (`write: true`, `bash: true`, ...) |
|
||||||
|
| `prompt_files` | body / loaded instructions |
|
||||||
|
| `memory` | brain.py reference in body |
|
||||||
|
| `verification` | "Completion Verification" section in body |
|
||||||
|
| `gates` | body constraints section |
|
||||||
|
|
||||||
|
## Validator
|
||||||
|
|
||||||
|
`validate-depo.sh` rejects a package when: any card is missing a field,
|
||||||
|
`verification` is absent, `prompt_files` referenced but missing, tools named
|
||||||
|
but unregistered in the tool registry, or secrets detected.
|
||||||
@@ -0,0 +1,74 @@
|
|||||||
|
# Depo Package Manifest — Spec v1.0 (DRAFT)
|
||||||
|
|
||||||
|
One tag = one releasable business. The manifest is the contract between the
|
||||||
|
authoring machine and any target that pulls the package.
|
||||||
|
|
||||||
|
## File
|
||||||
|
|
||||||
|
`manifest.json` at package root.
|
||||||
|
|
||||||
|
## Schema
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"schema_version": "1.0",
|
||||||
|
"package_id": "hitridge-business-o1",
|
||||||
|
"display_name": "O1 — Consignment Refurbished Electronics",
|
||||||
|
"version": "0.1.0",
|
||||||
|
"license": "proprietary",
|
||||||
|
"requires": {
|
||||||
|
"odoo": ">=18.0",
|
||||||
|
"agent_runtime": ">=1.0"
|
||||||
|
},
|
||||||
|
"layers": {
|
||||||
|
"odoo_modules": ["aura_business_core", "hitridge_venture_o1"],
|
||||||
|
"agents": ["o1-sellers-recruiter", "o1-test-operator", "o1-closer", "o1-compliance"],
|
||||||
|
"docs": ["docs/playbook.md", "docs/agreement-template.odt", "docs/test-checklist.md"],
|
||||||
|
"config": ["config/channels.json", "config/pricing-rules.json"]
|
||||||
|
},
|
||||||
|
"install": {
|
||||||
|
"order": ["odoo_modules", "config", "agents", "docs"],
|
||||||
|
"verify": [
|
||||||
|
"all odoo_modules installed",
|
||||||
|
"all agents registered in runtime",
|
||||||
|
"venture menu visible",
|
||||||
|
"no secrets in package (secrets_scan)"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
"rollback": {
|
||||||
|
"strategy": "install previous tag; reverse install order"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Rules
|
||||||
|
|
||||||
|
1. **Versioning** — semver. Every change to any layer bumps the version. A tag
|
||||||
|
in the depot repo = the release.
|
||||||
|
2. **Signing** — manifest is hashed (SHA-256) and signed (ed25519). Targets
|
||||||
|
verify the signature before anything is applied. No signature = refuse.
|
||||||
|
3. **Idempotency** — installing the same version twice is a no-op; upgrading
|
||||||
|
follows the module version-bump path.
|
||||||
|
4. **Never ships in a package**:
|
||||||
|
- env secrets / credentials / API keys (env vars injected at target only)
|
||||||
|
- live data (rows are generated by the target, never imported from authoring)
|
||||||
|
- learned memories (brain capabilities ship; memories are empty seeds)
|
||||||
|
- anything target-specific (URLs, IDs, absolute paths)
|
||||||
|
5. **Fresh-target assumption** — target must be the Aura tower Odoo (or the
|
||||||
|
manifest declares the base modules it needs).
|
||||||
|
6. **Rollback is designed in** — reverse install order; each layer must be
|
||||||
|
undoable atomically.
|
||||||
|
|
||||||
|
## Install sequence (target side, pull model)
|
||||||
|
|
||||||
|
1. Fetch package (from depot git tag or registry).
|
||||||
|
2. Verify signature + hash.
|
||||||
|
3. Run `install.order` in sequence, each step verified before the next.
|
||||||
|
4. Run `install.verify` checklist. Any failure = abort + rollback, target
|
||||||
|
reports state, never silently continues.
|
||||||
|
|
||||||
|
## Local mirror (authoring side)
|
||||||
|
|
||||||
|
`depot-state.json` (SQLite or JSON): which package version is deployed to which
|
||||||
|
target, when, by whom, verification result. This is what enables diff, upgrade,
|
||||||
|
and rollback decisions. It never deploys anything itself.
|
||||||
@@ -0,0 +1,64 @@
|
|||||||
|
# O1 Package — Structure & Phase-1 Pilot (DRAFT)
|
||||||
|
|
||||||
|
The first business-in-a-box: consignment refurbished-electronics arbitrage.
|
||||||
|
Package id `hitridge-business-o1`.
|
||||||
|
|
||||||
|
## Package tree
|
||||||
|
|
||||||
|
```
|
||||||
|
hitridge-business-o1/
|
||||||
|
├── manifest.json # the contract (spec v1.0)
|
||||||
|
├── modules/ # layer 1: Odoo addon modules
|
||||||
|
│ ├── aura_business_core/ # generic venture core (schema, auth, layout)
|
||||||
|
│ └── hitridge_venture_o1/ # O1 models: seller, unit, order, warranty,
|
||||||
|
│ # price-guide content, pipeline views
|
||||||
|
├── agents/ # layer 2: neutral specialist cards + prompts
|
||||||
|
│ ├── o1-sellers-recruiter.json
|
||||||
|
│ ├── o1-test-operator.json
|
||||||
|
│ ├── o1-closer.json
|
||||||
|
│ └── o1-compliance.json
|
||||||
|
│ └── prompts/ # external prompt markdown per agent
|
||||||
|
├── brain/ # layer 3: runtime/memory
|
||||||
|
│ ├── brain.py # capability ships...
|
||||||
|
│ └── seeds/o1/ # ...memories are EMPTY seeds at install
|
||||||
|
├── docs/ # layer 4: business documents
|
||||||
|
│ ├── playbook.md # O1 operating manual (90-day plan)
|
||||||
|
│ ├── agreement-template.odt # BG consignment agreement
|
||||||
|
│ ├── test-checklist.md # unit intake test + report template
|
||||||
|
│ └── price-guide-starter.md # content engine seed
|
||||||
|
├── config/
|
||||||
|
│ ├── channels.json # OLX/forums target list (BG)
|
||||||
|
│ └── pricing-rules.json # intake→sale spread + price-drop ladder
|
||||||
|
├── install.sh # target-side verifier + installer (pull)
|
||||||
|
└── VALIDATE # output of validate-depo.sh (must pass)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Phase-1 pilot slice (what we build first)
|
||||||
|
|
||||||
|
| Item | Contents | Acceptance |
|
||||||
|
|---|---|---|
|
||||||
|
| 1. Manifest spec | `manifest-spec.md` frozen | validate-depo.sh accepts it |
|
||||||
|
| 2. Agent-card spec | `agent-card-spec.md` frozen | validator rejects malformed cards |
|
||||||
|
| 3. Converter | neutral card ↔ opencode md (both directions) | round-trip → identical hash |
|
||||||
|
| 4. O1 skeleton | manifest + core module stub + **2 agents** (sellers-recruiter, compliance) + docs stubs | package validates; 2 specialists runnable on THIS machine from neutral cards |
|
||||||
|
| 5. Tool registry | names → implementations (odoo.*, file.*, script.run) | card tools resolve |
|
||||||
|
|
||||||
|
Pilot deliberately ships **2 of 4 agents** (sellers-recruiter, compliance) —
|
||||||
|
they exercise the widest tool/memory/gate spread. test-operator and closer
|
||||||
|
are added in phase 2 once the pipeline is proven.
|
||||||
|
|
||||||
|
## Phase-1 acceptance (hard)
|
||||||
|
|
||||||
|
1. `validate-depo.sh` passes on `hitridge-business-o1` (exit 0, no warnings).
|
||||||
|
2. Both pilot agents launch on this machine **from the neutral cards**
|
||||||
|
(via converter → opencode), not from hand-written md.
|
||||||
|
3. Manifest round-trip: `manifest.json` → convert → convert back → identical.
|
||||||
|
4. No secrets in package (secrets_scan clean).
|
||||||
|
5. Nothing deployed anywhere — target install is phase 2.
|
||||||
|
|
||||||
|
## Sequencing after pilot
|
||||||
|
|
||||||
|
- Phase 2: `install.sh` + target verification on a throwaway Odoo (Aura tower).
|
||||||
|
- Phase 3: depot repo (git + signed tags) + local mirror (`depot-state.json`).
|
||||||
|
- Phase 4: remaining agents + runtime/chat UI (Level 2 from earlier discussion).
|
||||||
|
- Phase 5: on-demand bridge sessions (MCP/API), default-disconnected.
|
||||||
Reference in New Issue
Block a user