gutomec/nirvana-os-engine/businesses

Business Protocol Engine v2.0

Requires the Nirvana-OS engine (nrv on PATH). If it is absent, use the nirvana skill, which installs it. This skill is not standalone.

Multi-agent business orchestrator following BUSINESS_PROTOCOL_V2.md (the delta) over BUSINESS_PROTOCOL_V1.md (everything the delta does not change). Runtime-agnostic (Claude Code, Codex, Antigravity). Zero external dependencies beyond the runtime and the centralized validators in ~/.nirvana/skills/_shared/.

Scope of this skill

This skill is for business lifecycle operations: list / inspect / create / validate / migrate businesses; manage the ~/businesses/_library/dna/ mind-clone library; bootstrap structure; consult registries.

For execution requests ("use as empresas", "rode pela empresa X", "produza um livro/post/vídeo", any production brief), hand it to the harness (read ~/.nirvana/skills/harness/SKILL.md and follow it) instead. The harness skill carries the maestro intelligence — it reads the brief, optionally researches, picks the right business, dispatches its org chart, and runs the quality gate. This skill is not the entry point for orchestration.

Verifying real dispatch (when execution does happen via harness)

After delivery, confirm in ~/.harness-logs/$(date +%Y-%m-%d)/audit.jsonl:

• event=brief_received (from brief-business.ts)
• event=dispatch_business (or dispatch_squad for fallback) with this trace_id
• event=mind_clone_injected for each DNA file loaded (from buildEmployeePrompt)
• event=handoff_phase_advanced for plan → execute and execute → complete
• event=verify_passed (from verify-deliverable.ts)
• event=gate_passed (from quality-gate.ts) with the rubrics list
• The actual artifact at the dispatched target's declared outputs[] location

If absent, the orchestration didn't happen — claiming "I used business X + squad Y" without those events is fiction. Iterate, don't fake.

Protocol Compliance for Employees (HARD RULES)

When an employee is spawned via subagent (using buildEmployeePrompt() from lib/employee-prompt.ts), the prompt already includes a "PROTOCOL COMPLIANCE" section. Reinforced here for the runtime:

1. Read multi-target coordination artifacts in this order, every time:
2. <project_dir>/brief-enriched.md — the full project context.
3. <your_target_dir>/DISPATCH-INSTRUCTION.md (if it exists) — your specific scope, upstream deps, downstream consumers.
4. <each_upstream>/outputs/_SUMMARY.md for every phase in your depends_on — 1 page each.
5. Specific files under <upstream>/outputs/ only when your DISPATCH-INSTRUCTION calls them out by name.
6. Read `HANDOFF.json` on start. Phase tells you where to resume after rate-limit / kill / restart.
7. Advance phases: import updateHandoffPhase from ~/.nirvana/skills/_shared/lib/handoff.js:

• Before first artifact write → updateHandoffPhase(projectDir, "execute", {nextTaskId: "T-001"})
• After last artifact written → updateHandoffPhase(projectDir, "complete", {lastTaskCompleted: ...})
• On interruption → leave phase: "execute" with last_task_completed set; next session resumes.

1. Prefer squads — discover, shortlist the TOP 5, then pick the best agentically (§13.4). You are an orchestrator, not just a doer: before producing an atomic deliverable by hand, look for a squad that covers it. If the brief names a squad, use it. Otherwise:

a. Discover candidates by capability over the squad registry — match the brief against each squad's capabilities[].domains + produces + example_briefs + keywords (agentic mode, default; or seed the shortlist fast with nrv find "<need>" BM25). b. Shortlist the top 5 best-matching squads. c. Analyze those 5 deeply — read each one's full capability block (description, examples, produces, not_for, domains, fidelity, score_boost), judge fit against the brief and your role, then pick the single best. Tiebreak: higher produces/capability coverage → fidelity: validated → score_boost. Record in the audit why it beat the other four. d. Only if none of the 5 genuinely fit, produce it directly (and say so). Businesses do not whitelist squads by default: squads_authorized empty and absent both mean all squads are permitted (v2 §6.10), so this top-5 agentic choice is THE gate that keeps routing sharp. A non-empty squads_authorized is a hard restriction, and a per-employee list narrows it further; squads_preferred only reorders — listed squads come first, nothing is excluded. Don't pass the raw brief down: build a brief-context shaped by your role and (if type: mind_clone) your incorporated persona, hand that to the squad, then integrate its output. Executing directly what a squad already covers breaks the audit chain.

1. Verify before declaring done. Run verify-deliverable.ts and quality-gate.ts from the harness; write `outputs/_SUMMARY.md` (1 page max — your public API for downstream phases); only emit delivered audit event after gates PASS.
2. Scope isolation. Write only under your own target directory. Coordination with siblings is audit-only (plan_change_request, mention, notify_human) — never modify other targets' outputs.

These rules turn employees from "general-purpose subagents with persona text" into real Nirvana-OS citizens with auditable, resumable state.

Event vocabulary. buildEmployeePrompt() already shows the working example (nrv audit emit x_clone_choice --business=<slug> --trace=<trace> --json='{...}') at the point an employee records its mind-clone choice — measured at zero rogue event names across 61 businesses (event-contract cut, 2026-08-28), so no separate block was added here the way squads got one. Same rule as squads: an event outside the closed enum (references/03-audit.md in the harness skill) gets the explicit x_ prefix at the call site, never a bare invented name.

First invocation (auto-bootstrap)

When this skill activates for the first time, ensure the minimal structure exists. Idempotent:

mkdir -p ~/businesses ~/businesses/_library/dna ~/businesses/_library/frameworks
mkdir -p ~/.businesses-state ~/.businesses-logs/$(date +%Y-%m-%d)
[ -f ~/.businesses-registry.json ] || echo '{"schema_version":"1.0.0","generated_at":"","businesses":{}}' > ~/.businesses-registry.json

Report: number of businesses found, registry status, dependencies (Python 3.9+, Node 18+ — only for validators).

Project scoping (NIRVANA_SCOPE)

When invoked from inside a project tree with <project>/.env containing NIRVANA_SCOPE=project|merge, all loaders (list/index/inspect/validate) honor that scope automatically. Project-local businesses live at <project>/.nirvana/businesses/<slug>/ and the registry persists at <project>/.nirvana/.businesses-registry.json. From global cwd or with NIRVANA_SCOPE=global (default), behavior is identical to the home installation. Full contract: ~/.nirvana/skills/_shared/SCOPE_CONTRACT.md.

Protocol source

Source of truth, in this directory: BUSINESS_PROTOCOL_V2.md (the v2 delta) plus BUSINESS_PROTOCOL_V1.md for every section v2 leaves untouched. A v1 business loads, routes and dispatches exactly as before; v2 fields are optional.

The validator that runs is Zod, in ~/.nirvana/skills/_shared/validators/validators.ts. validators.py is the canonical mirror for hosts with Python. ~/.nirvana/skills/_shared/schemas/business.schema.json and core-schemas.json are documentation mirrors — they describe the contract, they do not execute it, and a divergence between them and the Zod schema is a defect in the JSON. Always delegate validation to the validators instead of re-implementing it.

DNA library of mind-clones in ~/businesses/_library/dna/ (61 categories, 393 validated canonical mind-clones).

Canonical domain catalog in ~/.nirvana/skills/_shared/catalogs/CAPABILITY_CATALOG_V1.yaml.

Read on demand. NEVER preemptively load the full protocol into context.

Principles (BP1-BP13 + inherited Squad P1-P11)

• BP1 Zero-human is the default. A run that needs a human says so explicitly; nothing pauses on its own.
• BP2 Hierarchy is real, not decorative.
• BP3 Handoffs are structured. 3 mechanisms in v2: delegation, escalation, auto-routing.
• BP4 Acceptance is declared per seat (acceptance[]), judged by the gate — not self-scored by the author (v2 §11).
• BP5 3-tier memory with isolation by construction (Permanent, Project, Session).
• BP6 Brief is the unit of entry. Routing via routing.yaml.
• BP7 Antagonist mandatory above 5 employees.
• BP8 Default functional_specialist, not mind_clone.
• BP9 Retired in v2 (approval chains were never implemented; adversarial review is BP7).
• BP10 Retired in v2 (heartbeats were never scheduled; recurring work belongs to the host scheduler).
• BP11 Project outputs are source-of-truth, memory is cache.
• BP12 Audit trail is non-negotiable.
• BP13 Writing contract — every prose deliverable follows the contract appended to AGENTS.md / CLAUDE.md / GEMINI.md (prevention-by-injection, no post-hoc rewrite).

Filesystem layout (canonical)

~/businesses/                              # business root (one folder per business)
├── _library/
│   ├── dna/                               # canonical mind-clones (symlinks to disk)
│   └── frameworks/                        # reusable frameworks
└── <business-slug>/
    ├── business.yaml                      # manifest (protocol 1.0 or 2.0)
    ├── employees/<slug>.md                # employee frontmatter + body
    ├── org-chart.yaml                     # hierarchy + reporting + escalation_path
    ├── routing.yaml                       # brief intake + auto_routes (the only place auto_routes live)
    ├── .nirvana-surface.json              # contract surface — engine-owned, never hand-edited
    ├── memory/permanent.md                # curated, replaced on pack update
    ├── memory/learned.md                  # promoted by a human, survives pack updates
    └── projects/                          # per-project state (created on-demand)
 
~/.businesses-registry.json                # index generated by `*business index`
~/.businesses-state/                       # local skill state
~/.businesses-logs/<YYYY-MM-DD>/           # audit trail jsonl

Project outputs live in ${PROJECTS_OUTPUT_DIR}/<project-id>/businesses/<biz-slug>/ (default: <repo-root>/.projects-outputs/).

Project-root resolution:

1. $PROJECTS_OUTPUT_DIR env var
2. $NIRVANA_PROJECT_ROOT, else walk up to the nearest folder with .nirvana/project.yaml (written by nrv init; nrv init --adopt declares an existing folder)
3. No project: the engine's store, ~/.nirvana/outputs/

Intent classification

When the user invokes this skill, map the input to one of the actions below. Use AskUserQuestion to disambiguate when needed.