commit e2f76e40271fab8c9d8fbb5a6de5c5cdfc2c93a4 Author: AG Date: Mon Aug 3 19:56:51 2026 +0300 docs: frozen v1.0 bundle format specs (manifest, agent-card, o1 package structure) diff --git a/README.md b/README.md new file mode 100644 index 0000000..5965b5c --- /dev/null +++ b/README.md @@ -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) diff --git a/docs/specs/agent-card-spec.md b/docs/specs/agent-card-spec.md new file mode 100644 index 0000000..6290c7c --- /dev/null +++ b/docs/specs/agent-card-spec.md @@ -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. diff --git a/docs/specs/manifest-spec.md b/docs/specs/manifest-spec.md new file mode 100644 index 0000000..72fa5bb --- /dev/null +++ b/docs/specs/manifest-spec.md @@ -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. diff --git a/docs/specs/o1-package-structure.md b/docs/specs/o1-package-structure.md new file mode 100644 index 0000000..ebdf291 --- /dev/null +++ b/docs/specs/o1-package-structure.md @@ -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.