{"slug":"business/AGENTS","title":"AGENTS.md","section":"business","sectionLabel":"Business","status":"unclassified","type":"document","path":"business/AGENTS.mdx","bytes":19760,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n## Architecture Authority\n\nThe canonical architecture source of truth is:\n\n`docs/architecture/INTEGRATEWISE_ARCHITECTURE.md`\n\nThis AGENTS.md defines repository execution and implementation constraints\nderived from that architecture. If this file conflicts with the canonical\narchitecture document, the architecture document takes precedence.\n\nCode and tests determine whether an architectural capability is actually\nimplemented.\n\nAuthority hierarchy:\n\n```\n1. docs/architecture/INTEGRATEWISE_ARCHITECTURE.md\n   = architecture SSOT (Parts I-VII, includes consolidated Master Reference\n     in Part V and Book-of-Record Baseline in Part VII)\n\n2. AGENTS.md\n   = repository execution rules derived from the architecture SSOT\n\n3. package-level AGENTS.md / README / local docs\n   = scoped implementation guidance\n\n4. code + tests\n   = implementation evidence\n```\n\n### Master Reference\n\nThe architecture document contains a consolidated Master Reference (Part V)\nthat captures the essential structure from the Master Index:\n\n- Product definition\n- Core vocabulary\n- Workbench Doctrine\n- Five-Zone Shell\n- Sidebar Architecture\n- Platform UI Design System\n- Workbench IA & Spine Projection Map\n\nThe full Master Index (`IntegrateWise_Master_Index.md`) remains as a detailed\nsupporting document for implementation specifics.\n\n### Consolidated Canon\n\nThe architecture document contains a Consolidated Canon (Part VI) that\ndefines the unified architecture:\n\n- Canonical hierarchy (One Auth → Adaptive Spine → Projection Engine → Workbench → Twin → Capability Fabric → Governance → Execution → Verify → Reconcile → Spine)\n- Canonical runtime loop (Discover/Install → Continue)\n- Adaptive Workbench (compiled, not constructed; Auto-Tuner inside projection loop)\n- Front-end consolidation (stable shell with contextual Twin)\n- Twin definition (Context Assembly + Retrieval + Memory + Reasoning + Research + Explanation + Preparation + Proposal + Coordination + Monitoring)\n- Capability Fabric + MCP Marketplace (execution path resolution, not product layer)\n- Final product model (one platform, not a stack of products)\n\n**The invariant:** Every UI surface is a projection over the Spine; no surface owns its own database. The Spine is the contract and the Workbench is the rendering.\n\n### Book-of-Record Baseline\n\nThe architecture document contains a Book-of-Record Baseline (Part VII, v1.1) that\ngoverns the implementation baseline:\n\n- Product Boundary Model (Entry, Product, Platform, Flows)\n- Spine Network (umbrella for external AI/tool ecosystem)\n- Storage Authority (Neon control-plane + D1 operational Spine per tenant)\n- 20 Platform Runtime Services (ownership contracts)\n- Governed Command Envelope (`PlatformCommand`)\n- Platform Event Envelope (`PlatformEvent`)\n- Transactional Outbox pattern\n- Projection Contract (ProjectionService → ProjectionEngine → SharedWorkbench)\n- Auto-Tuner feedback loop (projection adjustment, not composition)\n- Twin and AI Coworker Model (Human + Twin as sibling consumers)\n- Capability Fabric v1.1 (OmniRouter inside execution boundary)\n- Execution and Reconciliation (states, transitions, invariants)\n- Runtime Infrastructure (D1, KV, R2, Vectorize, DO, Queues, Workflows)\n- Security and Zero Trust (never trust/always derive)\n- Go-Live Sequence (7 phases)\n- Stop-Ship Rules (18 rules)\n- Acceptance Criteria\n\n### Consolidated Canon\n\nThe architecture document contains a Consolidated Canon (Part VI) that\ndefines the unified architecture:\n\n- Canonical hierarchy (One Auth → Adaptive Spine → Projection Engine → Workbench → Twin → Capability Fabric → Governance → Execution → Verify → Reconcile → Spine)\n- Canonical runtime loop (Discover/Install → Continue)\n- Adaptive Workbench (compiled, not constructed; Auto-Tuner inside projection loop)\n- Front-end consolidation (stable shell with contextual Twin)\n- Twin definition (Context Assembly + Retrieval + Memory + Reasoning + Research + Explanation + Preparation + Proposal + Coordination + Monitoring)\n- Capability Fabric + MCP Marketplace (execution path resolution, not product layer)\n- Final product model (one platform, not a stack of products)\n\n**The invariant:** Every UI surface is a projection over the Spine; no surface owns its own database. The Spine is the contract and the Workbench is the rendering.\n\n## Final Implementation Status\n\n**Wiring Model**: Verified and mapped onto existing monorepo structure — no new top-level apps created.\n\n### What Was Built\n\n- 54/54 canonical routes verified and resolving correctly\n- 6/6 site contract verification points confirmed\n- TypeScript typecheck: not independently verified in this review (command exceeded timeout)\n- 914 tests previously reported passing; not independently verified in this review (command exceeded timeout)\n- 2 pre-existing import path failures unrelated to changes\n\n### Architecture Authority Compliance (per INTEGRATEWISE_ARCHITECTURE.md)\n\n| Rule                                     | Status                                                            |\n| ---------------------------------------- | ----------------------------------------------------------------- |\n| Spine is SSOT                            | Verified via route resolution                                     |\n| Governance is a hard gate                | CTA flow verified                                                 |\n| Twin never acts without approval         | Navigation reflects this                                          |\n| No AI direct DB access                   | Server-only packages conventional boundary (not CI-enforced)      |\n| L1/L2/L4/L7 never in user UI             | Verified in navigation                                            |\n| TypeScript/Node only                     | All packages are TS/Node                                          |\n| No new platform concepts                 | Only existing packages used                                       |\n| Consolidate into existing monorepo first | Verified — no new apps/api/ingress/worker/marketplace/mcp created |\n\n### Final Canonical Story (mapped onto existing repo)\n\n> **Spine Workspace is the Self-Organizing Workspace by IntegrateWise. It brings the relevant context from the systems a team already uses into one continuous work environment. Twin understands and prepares the work, governance controls what executes, and the Adaptive Spine keeps operational continuity intact underneath.**\n\nThe wiring model is respected as architectural intent, but mapped onto the **existing repository structure** before creating any new top-level applications.\n\n### App Ownership (per architecture authority — mapped onto existing repo)\n\nAll 16 existing apps. Zero newly invented apps.\n\n| App                       | Domain                                    | Purpose                                                         |\n| ------------------------- | ----------------------------------------- | --------------------------------------------------------------- |\n| `apps/marketing`          | integratewise.ai                          | Company + category + platform marketing                         |\n| `apps/marketing-sites`    | spineworkspace.com                        | Spine Workspace product marketing                               |\n| `apps/web`                | app.spineworkspace.com                    | Primary authenticated workspace (one runtime, many projections) |\n| `apps/auth`               | auth.spineworkspace.com                   | Authentication                                                  |\n| `apps/activation`         | activation.spineworkspace.com             | Onboarding                                                      |\n| `apps/connector`          | connector.spineworkspace.com              | Connector / OAuth / provider runtime implementation             |\n| `apps/platform-console`   | platform.spineworkspace.com               | Customer control plane UI                                       |\n| `apps/platform`           | backend/runtime                           | Trusted backend / runtime (Gateway + capabilities)              |\n| `apps/mcp-servers`        | mcp.integratewise.ai                      | Governed MCP boundary                                           |\n| `apps/one-access`         | session / identity / tenant runtime       | Identity and session management                                 |\n| `apps/one-access-console` | identity administration                   | Identity administration console                                 |\n| `apps/desktop`            | Spine Workspace desktop                   | Desktop client                                                  |\n| `apps/mobile`             | Spine Workspace mobile                    | Mobile client                                                   |\n| `apps/docs`               | docs.integratewise.ai                     | Company documentation                                           |\n| `apps/portfolio`          | IntegrateWise internal operations         | Internal operations                                             |\n| `apps/workspace`          | reusable workspace/projection composition | Workspace composition package                                   |\n\n### Key Execution Path\n\n```\nUser → One Access → Workspace Identity → Active Context →\nProjection Resolver → User Intent → Capability Resolution →\nGovernance → Approval if required → Execution → Provider →\nReconciliation → Adaptive Spine → Knowledge + Memory →\nContext Compiler → Projection Refresh\n```\n\n### No New Top-Level Apps\n\nConfirmed: Zero new `apps/api`, `apps/ingress`, `apps/worker`, `apps/marketplace`, or `apps/mcp` created. All deployable surfaces mapped onto existing repo structure.\n\n### Design System\n\n- Leveraged existing `@integratewise/design-system` package\n- Dark Glass + Operational Precision visual language\n- All claims discipline rules followed (no invented metrics, logos, certifications)\n\n### Verification Against Wiring Model §19 (mapped onto existing repo)\n\n```\nOne company: IntegrateWise\nOne flagship product: Spine Workspace\nOne category: Self-Organizing Workspace\nOne authenticated workspace: app.spineworkspace.com\nOne continuity substrate: Adaptive Spine\nOne contextual intelligence: Twin\nOne governed execution: Governed Actions\nMany contextual projections: role × department × industry × entity × intent × context\n```\n\n### Runtime Sequence (mapped onto existing)\n\n```\nLOAD → NORMALIZE → STORE → THINK → APPROVE → ACT → REPEAT\n                         ↑                 ↑\n                    Store in Spine    Approve Twin's Action\n                    Ask your Twin     Assign your Twin\n```\n\n### Canonical Corrections Applied\n\n1. No `apps/api` — platform responsibilities exist in `apps/platform`\n2. No `apps/ingress` — logical boundary, not separate app initially\n3. No `apps/worker` — queue consumers organized within `apps/platform/src/`\n4. No `apps/marketplace` — lives in `apps/platform-console` initially\n5. `apps/mcp` maps to existing `apps/mcp-servers`\n6. `app.spineworkspace.com` = authenticated workspace only; subdomains are marketing aliases\n7. Context/Active Context is first-class; all subsystems share same contract\n8. Workbenches = core modules; Plugins = optional marketplace extensions (separated)\n9. Projection resolver includes: identity × role × department × industry × entity × intent × activeContext × permissions × entitlements × signals × capabilities × policy\n10. Server/client package boundaries desired; enforcement is conventional, not CI-enforced\n\n### Package Layering\n\n- `apps/` = deployment/composition surfaces (all preserved from existing repo)\n- `packages/` = reusable contracts and behavior (derived from existing code)\n- Workbenches = first-party domain projection modules\n- Plugins = optional extension/distribution units (separate from core workbenches)\n\n### Canonical Package Model\n\nPhysical namespace: `@integratewise/*` (not `@spine/*`).\n\n```\npackages/\n├── config/\n├── core/\n├── runtime/\n│\n├── spine-contracts/\n├── spine-store/\n│\n├── knowledge/\n├── memory/\n├── context-contracts/\n├── context/\n│\n├── auth/\n├── connector/\n├── normalizer/\n│\n├── projection/\n├── capability/\n├── governance/\n├── reconciler/\n│\n├── twin/\n├── orchestrator/\n├── agents/\n├── skills/\n├── workflows/\n│\n├── mcp/\n├── events/\n├── observability/\n│\n├── ui/\n├── app-shell/\n│\n├── plugins/\n│   ├── sdk/\n│   └── registry/\n│\n└── workbenches/\n    ├── account-success/\n    ├── technical-account-success/\n    ├── sales/\n    ├── marketing/\n    ├── content/\n    ├── finance/\n    ├── revops/\n    ├── business-operations/\n    ├── operations/\n    ├── product/\n    ├── engineering/\n    ├── service/\n    ├── support/\n    ├── human-resources/\n    ├── legal/\n    ├── founder-ops/\n    └── personal/\n```\n\nExisting equivalent packages should be reused and consolidated rather than duplicated.\n\n#### Package Responsibilities\n\n| Package             | Owns                                                         |\n| ------------------- | ------------------------------------------------------------ |\n| `core`              | IDs, errors, result types, shared primitives                 |\n| `runtime`           | Cloudflare bindings, env, queues, request/tenant context     |\n| `spine-contracts`   | canonical Spine entity/event/relationship contracts          |\n| `spine-store`       | persistence access to canonical Spine state                  |\n| `knowledge`         | documents, evidence, chunks, provenance, retrieval           |\n| `memory`            | reviewed continuity, decisions, commitments, durable memory  |\n| `context-contracts` | `ActiveContextBundle` and related contracts                  |\n| `context`           | Context Compiler, hydration, policy, materialization/cache   |\n| `auth`              | identity/session/workspace/permission contracts              |\n| `connector`         | provider registry, OAuth, credential-bound provider adapters |\n| `normalizer`        | provider → canonical Spine normalization                     |\n| `projection`        | manifest resolution and compiled workspace projections       |\n| `capability`        | capability registry/resolution/invocation contracts          |\n| `governance`        | policy, authority, risk, approval decisions                  |\n| `reconciler`        | verify provider state and reconcile outcomes                 |\n| `twin`              | contextual reasoning, synthesis, drafts, proposals           |\n| `orchestrator`      | multi-step execution coordination                            |\n| `agents`            | agent definitions/runtime contracts                          |\n| `skills`            | reusable reasoning/action skills                             |\n| `workflows`         | durable workflow definitions                                 |\n| `mcp`               | MCP protocol ↔ governed capabilities                         |\n| `events`            | events, invalidation, subscriptions/streaming                |\n| `observability`     | logs, traces, metrics, audit instrumentation                 |\n| `ui`                | reusable UI/design-system primitives                         |\n| `app-shell`         | common application/bootstrap composition                     |\n| `plugins`           | optional extension SDK + registry                            |\n| `workbenches/*`     | first-party projection/domain modules                        |\n\n#### Critical Dependency Direction\n\n```\nworkbenches → projection → active context → Twin/Skills/Agents/Workflows\n    → capability → governance → connector/execution → provider\n    → reconciler → Adaptive Spine\n```\n\nSupporting layers:\n\n```\n              core\n               │\n     ┌─────────┼─────────┐\n     ▼         ▼         ▼\n  runtime    events  observability\n\nAdaptive Spine = spine-store + knowledge + memory\n    → context → projection\n```\n\n#### Active Context Is the Convergence Point\n\n```\nOperational Truth ─┐\nKnowledge ──────────┤\nMemory ─────────────┤\nSignals ────────────┤\nEvidence ───────────┘\n        ↓\n  Context Compiler\n        ↓\n  ActiveContextBundle\n        ↓\n┌───────┬───────┬───────┬───────┬──────────┐\nView  Canvas   Twin   Agent  Workflow   Skill\n└───────┴───────┴───────┴───────┴──────────┘\n                  ↓\n          Capability Runtime\n```\n\nNo Twin-specific context store, agent-specific context store, or\nworkbench-specific reconstruction.\n\n#### Workbench Package Contract\n\nEach first-party workbench contributes declarative domain behavior:\n\n```\npackages/workbenches/<domain>/\n├── manifest\n├── navigation\n├── views\n├── canvases\n├── entities\n├── signals\n├── context-policy\n├── capabilities\n├── skills\n├── agents\n├── workflows\n├── twin-policy\n└── components\n```\n\nA workbench **references** capabilities. It does not own provider\ncredentials or raw execution adapters.\n\n#### Plugins Are Separate\n\nDo not package core workbenches as marketplace plugins.\n\n- `packages/workbenches/sales` = first-party canonical domain module\n- `packages/plugins/*` = optional extensions\n\nPlugins may contribute views, commands, skills, agents, workflows,\ncapability references, connector definitions, MCP exposure — but cannot\nbypass governance or replace canonical Spine ownership.\n\n#### Client/Server Exports\n\nFor packages crossing the browser boundary:\n\n```\n@integratewise/auth/client       @integratewise/auth/server\n@integratewise/context/client    @integratewise/context/server\n@integratewise/projection/client @integratewise/projection/server\n@integratewise/capability/client @integratewise/capability/server\n@integratewise/twin/client       @integratewise/twin/server\n```\n\nServer-only: spine-store, connector/server, normalizer, governance\nexecution, reconciler, orchestrator execution, mcp/server, provider\nadapters, Cloudflare storage bindings, model credentials.\n\n#### Package Invariant\n\n```\n@integratewise/*    = physical repository namespace\npackages/           = reusable behavior + contracts\ncontext             = shared Active Context compiler/runtime\nworkbenches/*       = first-party projections\nplugins/*           = optional extensions\ncapability          = what may be done\ngovernance          = whether it may be done\nconnector           = how provider execution occurs\nreconciler          = what actually happened\nAdaptive Spine      = durable continuity underneath all of it\n```\n\n### Server/Client Boundary\n\nDesired invariant: strict client/server/import boundaries.\n\nCurrent enforcement: partially architectural/conventional.\n\nMissing: CI-enforced import boundary rules.\n\nBrowser must never transitively pull: D1, R2, KV, Vectorize, provider SDKs, credentials, MCP server code.\n\nRecommended eventual controls:\n\n```\npackage exports\n+ ESLint restricted imports / boundaries\n+ server-only markers\n+ dependency graph test\n+ CI verification\n```\n\nThe implementation is mapped onto the existing monorepo structure. The wiring model's architectural intent is preserved.\n"}