Sprout Generator Spec
How do you prove the mycelium works — by growing something on it?
Build Contract
The deliverable. Commissioning reads this table. Tight Five sections below justify what's in it.
| # | Feature | Function | Outcome | Job | State |
|---|---|---|---|---|---|
| 1 | Sprout generator | Nx generator creates venture app from templates | New venture in one command | Platform proof | Built |
| 2 | Venture self-creation | Bootstrap creates venture row on first boot | Zero seed scripts needed | Self-healing | Gap |
| 3 | Agent card auto-registration | Agent card writes to registry on startup | Mycelium discovers ventures automatically | Discovery | Gap |
| 4 | WorkChart venture scoping | Boot seeds one WorkChart definition with ventureId | Proves execution layer is venture-scoped | Scoped execution | Gap |
| 5 | A2A endpoint stubs | Execute and data routes respond | Venture has API surface | Interop | Gap |
| 6 | Acceptance test | 7-line binary validation script | Binary proof of platform thesis | Verification | Built |
| 7 | Safe Nx runner | Prevents hang on interactive prompts | Generator runs unattended | Reliability | Built |
| 8 | Domain entity scaffolding | Feature scaffold generates per-entity CRUD with A2A | Venture has real business logic | Domain depth | Gap |
| 9 | Real A2A execution | Replace stubs with A2AHttpClientAdapter calls | Ventures can call each other | Composition | Gap |
| 10 | Venture access control | org-venture-role permission table | Ventures have their own users | Security | Gap |
| 11 | Second sprout | Run generator for a second venture | Platform proof — one works, two proves the pattern | Validation | Gap |
| 12 | Cross-venture A2A | Agent in venture A delegates to agent in venture B | Mycelium network effect | Network | Gap |
Principles
What truths constrain the design?
The Job
| Element | Detail |
|---|---|
| Situation | Platform has 18 venture-scoped tables and shared libs, but new ventures require manual wiring |
| Intention | One command produces a working venture app — thesis proven by automation |
| Obstacle | Unknown coupling to drmg-sales. Shared libs built inside one app, never tested standalone |
| Hardest Thing | Additive template (from zero) must compose shared libs that carry invisible assumptions from their only consumer |
Why Now
The platform has 7 ventures listed but 0 running independently. Every day without a second app is a day the "platform" claim is untested. The generator is built (Steps 1.1-1.5 complete). Schema migration is applied. The only thing between thesis and proof is running Step 1.6.
Design Constraints
| Constraint | Rationale |
|---|---|
| New app, not module | Module inside drmg-sales proves ventures are features. Standalone app proves the mycelium pattern. |
| Venture IS the app boundary | venture_ventures table is first-class with 18+ scoped tables. Slug field = routing/A2A/agent namespace. |
| Additive, not subtractive | Stripping drmg-sales carries invisible assumptions. Building from zero is slower but honest. |
| Auto-register, not server lib | Agent cards register on startup. Registration is a side effect of existing, not a task. |
| Self-create on boot | Missing venture row → create it. Self-healing over seed scripts. |
| Domain-specific entities | Berleytrails gets spots/reports/catches, not contacts/deals. Platform generator, not CRM template. |
Refusal Spec
| Category | Action | Response |
|---|---|---|
| Copy from drmg-sales | Strip app-drmg-sales-server into template | Refuse — additive principle. Build from zero. |
| Skip acceptance test | Ship without 7-line validation | Refuse — the test IS the deliverable. |
| Add features before boot | Wire domain tables before generator proves it boots | Refuse — earn the right to build. |
| Shared namespace | Use berleytrails.a2a instead of berleytrails | Refuse — namespace derives from app name. |
Performance
How do we know it's working?
Priority Score
PRIORITY = Pain x Demand x Edge x Trend x Conversion
| Dimension | Score (1-5) | Evidence |
|---|---|---|
| Pain | 5 | Existential — platform thesis is unproven. 7 ventures listed, 0 running independently. Manual wiring costs days per venture with 30% boot failure rate. |
| Demand | 2 | Internal only — 7 ventures need platform proof. No external customers have asked. Second consumer rule drives the need. |
| Edge | 4 | Proprietary 18-table schema surface across 5 domains. 6 locked architecture decisions from strategic design session. Generator template pattern with auto-registration. |
| Trend | 5 | A2A protocol adoption accelerating. AI agent platforms becoming primary interface. Multi-venture composable platforms inevitable — structural shift. |
| Conversion | 2 | Internal tool — revenue path is indirect. Generator enables ventures that have pricing models (berleytrails, prettymint). No direct invoice this month. |
| Composite | 400 | Product of all five. Strong candidate — platform credibility at stake. |
Quality Targets
| Target | Threshold | Method |
|---|---|---|
| Generator completes | 100% (binary) | Acceptance test line 1 |
| Boot time | < 30 seconds | Cold boot timer |
| Acceptance test | 7/7 pass | Acceptance script |
| drmg-sales regression | 0 failures | Existing test suite |
Eval Strategy
| What | How | When |
|---|---|---|
| Generator output correctness | Acceptance test script (7-line) | Every generator run |
| Shared lib independence | Dependency audit (import chain map) | Phase 1 completion |
| Platform proof | Second sprout (Phase 4) | After Phase 1 acceptance |
| Template improvement | Legacy principle — compare Phase 1 vs Phase 4 templates | Phase 4 completion |
Kill signal: If berleytrails cannot cold boot and serve an A2A request within 60 days of first generator run, the shared libs are not shared — pivot to monolith architecture.
Platform
What do we control?
Current State
| Component | Built | Wired | Working | Notes |
|---|---|---|---|---|
| Venture schema (18 tables) | Yes | Yes | Yes | 5 domains in production |
| Migration 0048 (WorkChart scoping) | Yes | Yes | Untested | 3 nullable columns, zero breaking changes |
| Sprout generator | Yes | Yes | Untested | Templates registered, never run |
| Safe Nx runner | Yes | Yes | Yes | Handles interactive prompt hang |
| Acceptance test | Yes | — | Untested | Script written, waiting for generator output |
| A2A endpoints | Stub | Stub | — | Phase 3 replaces stubs |
| Feature scaffold | Yes | — | Yes (drmg-sales) | Untested standalone |
| Shared libs | Yes | — | Yes (drmg-sales) | Riskiest — never tested outside one consumer |
Schema Surface
18 tables with ventureId across 5 domains:
| Domain | Tables | What Berleytrails Inherits |
|---|---|---|
| schema-accounting (5) | cost_centers, gl_accounts, metric_measurements, outcome_measurements, transactions | Financial tracking |
| schema-planning (1) | planning_projects | Project management |
| schema-value (1) | venture_agent_value_events | Value tracking |
| schema-venture (11) | agent_cost_centers, agent_dev_timeseries, agent_execution_sessions, business_ideas, dashboard_slides, discovery_sessions, knowledge_base, llama_cloud_indexes, proposals, contacts, documents | Knowledge, contacts, proposals, dashboards |
| schema-agent (1) | agent_profile_deals (via rfp_venture_id) | Deal pipeline |
Activation Backlog
Commented relations in venture.relations.ts — each activation adds composition ratio:
- Agent layer: capabilities, performance history, skill gaps, team compositions, time allocation
- Financial layer: cap table, financial KPIs, performance, funding rounds, investors, revenue streams
- Operational layer: milestones, experiments, pivots, interventions
- Team layer: team members, teams
Build Ratio
~85% composition (shared libs, schema, generator templates), ~15% new code (venture-specific boot sequence, A2A stubs)
Protocols
How do we coordinate?
Build Order
| Sprint | Features | What | Effort | Acceptance |
|---|---|---|---|---|
| 0 | #1, #6, #7 | Generator + acceptance test + safe runner | Done | Steps 1.1-1.5 complete |
| 1 | #2, #3, #4, #5 | Run generator, boot, self-create, register, seed | 1 day | 7-line acceptance test passes |
| 2 | #8 | Domain entities (spots, reports, catches) + feature scaffold | 3 days | Per-entity CRUD accessible via A2A data endpoint |
| 3 | #9, #10 | Real A2A execute + access control | 5 days | Cross-app A2A call succeeds with scoped permissions |
| 4 | #11, #12 | Second sprout + cross-venture A2A | 2 days | Two ventures compose same shared lib, call each other |
Commissioning
| # | Feature | Install | Test | Operational | Optimize |
|---|---|---|---|---|---|
| 1 | Sprout generator | 100% | 0% | 0% | 0% |
| 2 | Venture self-creation | 100% | 0% | 0% | 0% |
| 3 | Agent card auto-registration | 100% | 0% | 0% | 0% |
| 4 | WorkChart venture scoping | 100% | 0% | 0% | 0% |
| 5 | A2A endpoint stubs | 100% | 0% | 0% | 0% |
| 6 | Acceptance test | 100% | 0% | 0% | 0% |
| 7 | Safe Nx runner | 100% | 100% | 100% | 0% |
| 8 | Domain entity scaffolding | 0% | 0% | 0% | 0% |
| 9 | Real A2A execution | 0% | 0% | 0% | 0% |
| 10 | Venture access control | 0% | 0% | 0% | 0% |
| 11 | Second sprout | 0% | 0% | 0% | 0% |
| 12 | Cross-venture A2A | 0% | 0% | 0% | 0% |
Agent-Facing Spec
Commands:
# Run generator
npx tsx tools/scripts/platform-engineering/nx/run-generator-safe.ts ./tools:sprout \
--name=berleytrails --domain=berleytrails --entities=spots,reports,catches
# Run acceptance test
A2A_API_KEY=dev-key \
DATABASE_URL=postgresql://dev_user:dev_password@localhost:5434/stackmates_dev \
npx tsx tools/scripts/platform-engineering/sprout/sprout-acceptance.ts --slug berleytrails
# Cold boot
pnpm nx dev berleytrails-app
# Verify no regression
pnpm nx dev drmg-sales
Boundaries:
| Always | Ask First | Never |
|---|---|---|
| Run acceptance test after generator | Add new shared lib dependency | Strip from drmg-sales |
| Use additive template | Activate commented venture relations | Skip acceptance test |
| Self-create on boot | Change generator output structure | Manual seed scripts |
Test Contract:
| # | Feature | Test | Assertion |
|---|---|---|---|
| 1 | Generator runs | sprout-acceptance.ts line 1 | Exit code 0 |
| 2 | Venture exists | sprout-acceptance.ts line 2 | Row with slug = berleytrails |
| 3 | Agent card | sprout-acceptance.ts line 3 | Card in registry under berleytrails namespace |
| 4 | WorkChart seed | sprout-acceptance.ts line 4 | Definition row with ventureId = berleytrails.id |
| 5 | A2A responds | sprout-acceptance.ts line 5 | HTTP 200 from execute and data endpoints |
| 6 | Entities stubbed | sprout-acceptance.ts line 6 | spots, reports, catches registered |
| 7 | No regression | sprout-acceptance.ts line 7 | drmg-sales jobs have ventureId = null |
Players
Who creates harmony?
Demand-Side Jobs
Job 1: Platform Engineer Creates a New Venture
Situation: Nav has 7 venture concepts but no mechanism to instantiate them. Each requires days of manual wiring — composition roots, A2A endpoints, DB scoping, agent registration — with 30% failure rate on first boot.
| Element | Detail |
|---|---|
| Struggling moment | "I want to prove berleytrails works on the mycelium but I'd need to manually wire 18 tables, create a new app structure, set up A2A endpoints, and register an agent card" |
| Current workaround | Clone drmg-sales patterns manually, debug import failures, seed data by hand |
| What progress looks like | Run one command, boot the app, see it serve requests with venture-scoped data |
| Hidden objection | "What if running the generator reveals the shared libs aren't actually shared — that we built a monolith?" |
| Switch trigger | Codex crash resolved, manual path estimated at 3+ days, generator ready to run |
Features that serve this job: #1, #2, #3, #4, #5, #6, #7
Job 2: Venture Founder Validates an Idea
Situation: Someone with a business idea (berleytrails: fishing platform) needs operational infrastructure without building from scratch.
| Element | Detail |
|---|---|
| Struggling moment | "I have a domain (fishing) and know my entities (spots, reports, catches) but I don't know how to build a full-stack app with auth, agents, and data pipelines" |
| Current workaround | Build from scratch on a different platform, or don't build at all |
| What progress looks like | Tell the platform what the domain is and what entities matter, get a working app with CRUD, A2A, and agents |
| Hidden objection | "Will this platform lock me in, or can I customize for my domain?" |
| Switch trigger | Seeing berleytrails run with domain-specific entities (spots, not contacts) |
Features that serve this job: #1, #8, #9
Role Definitions
| Role | Access | Permissions |
|---|---|---|
| Platform engineer | Full — generator, templates, schema | Create ventures, modify templates, run acceptance |
| Venture founder | Venture-scoped — their app, their data | Configure domain, manage entities, operate |
| Platform consumer | Read — A2A endpoints, agent cards | Query data, delegate tasks, compose |
Relationship to Other PRDs
| PRD | Relationship | Data Flow |
|---|---|---|
| Agent Platform | Peer | Sprout registers agent cards → Agent Platform manages them |
| Identity & Access | Peer (dependency) | Identity provides auth → Sprout apps consume auth |
| ETL Data Tool | Peer | ETL loads data → Venture apps consume data |
| Sales CRM & RFP | Peer (first consumer) | drmg-sales = first app on platform → Sprout = second app proof |
Context
- Pictures — Pre-flight maps that feed this spec
- Prompt Deck — Sales compression of this spec
- AI Product Requirements — Section definitions and checklist
- WorkCharts — Execution layer the generator seeds
- A&ID Template — Nomenclature for agents and instruments