Unclassified

AGENTS.md

Architecture Authority

The canonical architecture source of truth is:

docs/architecture/INTEGRATEWISE_ARCHITECTURE.md

This AGENTS.md defines repository execution and implementation constraints
derived from that architecture. If this file conflicts with the canonical
architecture document, the architecture document takes precedence.

Code and tests determine whether an architectural capability is actually
implemented.

Authority hierarchy:

1. docs/architecture/INTEGRATEWISE_ARCHITECTURE.md
   = architecture SSOT (Parts I-VII, includes consolidated Master Reference
     in Part V and Book-of-Record Baseline in Part VII)

2. AGENTS.md
   = repository execution rules derived from the architecture SSOT

3. package-level AGENTS.md / README / local docs
   = scoped implementation guidance

4. code + tests
   = implementation evidence

Master Reference

The architecture document contains a consolidated Master Reference (Part V)
that captures the essential structure from the Master Index:

Product definition
Core vocabulary
Workbench Doctrine
Five-Zone Shell
Sidebar Architecture
Platform UI Design System
Workbench IA & Spine Projection Map

The full Master Index (IntegrateWise_Master_Index.md) remains as a detailed
supporting document for implementation specifics.

Consolidated Canon

The architecture document contains a Consolidated Canon (Part VI) that
defines the unified architecture:

Canonical hierarchy (One Auth → Adaptive Spine → Projection Engine → Workbench → Twin → Capability Fabric → Governance → Execution → Verify → Reconcile → Spine)
Canonical runtime loop (Discover/Install → Continue)
Adaptive Workbench (compiled, not constructed; Auto-Tuner inside projection loop)
Front-end consolidation (stable shell with contextual Twin)
Twin definition (Context Assembly + Retrieval + Memory + Reasoning + Research + Explanation + Preparation + Proposal + Coordination + Monitoring)
Capability Fabric + MCP Marketplace (execution path resolution, not product layer)
Final product model (one platform, not a stack of products)

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.

Book-of-Record Baseline

The architecture document contains a Book-of-Record Baseline (Part VII, v1.1) that
governs the implementation baseline:

Product Boundary Model (Entry, Product, Platform, Flows)
Spine Network (umbrella for external AI/tool ecosystem)
Storage Authority (Neon control-plane + D1 operational Spine per tenant)
20 Platform Runtime Services (ownership contracts)
Governed Command Envelope (PlatformCommand)
Platform Event Envelope (PlatformEvent)
Transactional Outbox pattern
Projection Contract (ProjectionService → ProjectionEngine → SharedWorkbench)
Auto-Tuner feedback loop (projection adjustment, not composition)
Twin and AI Coworker Model (Human + Twin as sibling consumers)
Capability Fabric v1.1 (OmniRouter inside execution boundary)
Execution and Reconciliation (states, transitions, invariants)
Runtime Infrastructure (D1, KV, R2, Vectorize, DO, Queues, Workflows)
Security and Zero Trust (never trust/always derive)
Go-Live Sequence (7 phases)
Stop-Ship Rules (18 rules)
Acceptance Criteria

Consolidated Canon

The architecture document contains a Consolidated Canon (Part VI) that
defines the unified architecture:

Canonical hierarchy (One Auth → Adaptive Spine → Projection Engine → Workbench → Twin → Capability Fabric → Governance → Execution → Verify → Reconcile → Spine)
Canonical runtime loop (Discover/Install → Continue)
Adaptive Workbench (compiled, not constructed; Auto-Tuner inside projection loop)
Front-end consolidation (stable shell with contextual Twin)
Twin definition (Context Assembly + Retrieval + Memory + Reasoning + Research + Explanation + Preparation + Proposal + Coordination + Monitoring)
Capability Fabric + MCP Marketplace (execution path resolution, not product layer)
Final product model (one platform, not a stack of products)

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.

Final Implementation Status

Wiring Model: Verified and mapped onto existing monorepo structure — no new top-level apps created.

What Was Built

54/54 canonical routes verified and resolving correctly
6/6 site contract verification points confirmed
TypeScript typecheck: not independently verified in this review (command exceeded timeout)
914 tests previously reported passing; not independently verified in this review (command exceeded timeout)
2 pre-existing import path failures unrelated to changes

Architecture Authority Compliance (per INTEGRATEWISE_ARCHITECTURE.md)

Rule	Status
Spine is SSOT	Verified via route resolution
Governance is a hard gate	CTA flow verified
Twin never acts without approval	Navigation reflects this
No AI direct DB access	Server-only packages conventional boundary (not CI-enforced)
L1/L2/L4/L7 never in user UI	Verified in navigation
TypeScript/Node only	All packages are TS/Node
No new platform concepts	Only existing packages used
Consolidate into existing monorepo first	Verified — no new apps/api/ingress/worker/marketplace/mcp created

Final Canonical Story (mapped onto existing repo)

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.

The wiring model is respected as architectural intent, but mapped onto the existing repository structure before creating any new top-level applications.

App Ownership (per architecture authority — mapped onto existing repo)

All 16 existing apps. Zero newly invented apps.

App	Domain	Purpose
`apps/marketing`	integratewise.ai	Company + category + platform marketing
`apps/marketing-sites`	spineworkspace.com	Spine Workspace product marketing
`apps/web`	app.spineworkspace.com	Primary authenticated workspace (one runtime, many projections)
`apps/auth`	auth.spineworkspace.com	Authentication
`apps/activation`	activation.spineworkspace.com	Onboarding
`apps/connector`	connector.spineworkspace.com	Connector / OAuth / provider runtime implementation
`apps/platform-console`	platform.spineworkspace.com	Customer control plane UI
`apps/platform`	backend/runtime	Trusted backend / runtime (Gateway + capabilities)
`apps/mcp-servers`	mcp.integratewise.ai	Governed MCP boundary
`apps/one-access`	session / identity / tenant runtime	Identity and session management
`apps/one-access-console`	identity administration	Identity administration console
`apps/desktop`	Spine Workspace desktop	Desktop client
`apps/mobile`	Spine Workspace mobile	Mobile client
`apps/docs`	docs.integratewise.ai	Company documentation
`apps/portfolio`	IntegrateWise internal operations	Internal operations
`apps/workspace`	reusable workspace/projection composition	Workspace composition package

Key Execution Path

User → One Access → Workspace Identity → Active Context →
Projection Resolver → User Intent → Capability Resolution →
Governance → Approval if required → Execution → Provider →
Reconciliation → Adaptive Spine → Knowledge + Memory →
Context Compiler → Projection Refresh

No New Top-Level Apps

Confirmed: Zero new apps/api, apps/ingress, apps/worker, apps/marketplace, or apps/mcp created. All deployable surfaces mapped onto existing repo structure.

Design System

Leveraged existing @integratewise/design-system package
Dark Glass + Operational Precision visual language
All claims discipline rules followed (no invented metrics, logos, certifications)

Verification Against Wiring Model §19 (mapped onto existing repo)

One company: IntegrateWise
One flagship product: Spine Workspace
One category: Self-Organizing Workspace
One authenticated workspace: app.spineworkspace.com
One continuity substrate: Adaptive Spine
One contextual intelligence: Twin
One governed execution: Governed Actions
Many contextual projections: role × department × industry × entity × intent × context

Runtime Sequence (mapped onto existing)

LOAD → NORMALIZE → STORE → THINK → APPROVE → ACT → REPEAT
                         ↑                 ↑
                    Store in Spine    Approve Twin's Action
                    Ask your Twin     Assign your Twin

Canonical Corrections Applied

No apps/api — platform responsibilities exist in apps/platform
No apps/ingress — logical boundary, not separate app initially
No apps/worker — queue consumers organized within apps/platform/src/
No apps/marketplace — lives in apps/platform-console initially
apps/mcp maps to existing apps/mcp-servers
app.spineworkspace.com = authenticated workspace only; subdomains are marketing aliases
Context/Active Context is first-class; all subsystems share same contract
Workbenches = core modules; Plugins = optional marketplace extensions (separated)
Projection resolver includes: identity × role × department × industry × entity × intent × activeContext × permissions × entitlements × signals × capabilities × policy
Server/client package boundaries desired; enforcement is conventional, not CI-enforced

Package Layering

apps/ = deployment/composition surfaces (all preserved from existing repo)
packages/ = reusable contracts and behavior (derived from existing code)
Workbenches = first-party domain projection modules
Plugins = optional extension/distribution units (separate from core workbenches)

Canonical Package Model

Physical namespace: @integratewise/* (not @spine/*).

packages/
├── config/
├── core/
├── runtime/
│
├── spine-contracts/
├── spine-store/
│
├── knowledge/
├── memory/
├── context-contracts/
├── context/
│
├── auth/
├── connector/
├── normalizer/
│
├── projection/
├── capability/
├── governance/
├── reconciler/
│
├── twin/
├── orchestrator/
├── agents/
├── skills/
├── workflows/
│
├── mcp/
├── events/
├── observability/
│
├── ui/
├── app-shell/
│
├── plugins/
│   ├── sdk/
│   └── registry/
│
└── workbenches/
    ├── account-success/
    ├── technical-account-success/
    ├── sales/
    ├── marketing/
    ├── content/
    ├── finance/
    ├── revops/
    ├── business-operations/
    ├── operations/
    ├── product/
    ├── engineering/
    ├── service/
    ├── support/
    ├── human-resources/
    ├── legal/
    ├── founder-ops/
    └── personal/

Existing equivalent packages should be reused and consolidated rather than duplicated.

Package Responsibilities

Package	Owns
`core`	IDs, errors, result types, shared primitives
`runtime`	Cloudflare bindings, env, queues, request/tenant context
`spine-contracts`	canonical Spine entity/event/relationship contracts
`spine-store`	persistence access to canonical Spine state
`knowledge`	documents, evidence, chunks, provenance, retrieval
`memory`	reviewed continuity, decisions, commitments, durable memory
`context-contracts`	`ActiveContextBundle` and related contracts
`context`	Context Compiler, hydration, policy, materialization/cache
`auth`	identity/session/workspace/permission contracts
`connector`	provider registry, OAuth, credential-bound provider adapters
`normalizer`	provider → canonical Spine normalization
`projection`	manifest resolution and compiled workspace projections
`capability`	capability registry/resolution/invocation contracts
`governance`	policy, authority, risk, approval decisions
`reconciler`	verify provider state and reconcile outcomes
`twin`	contextual reasoning, synthesis, drafts, proposals
`orchestrator`	multi-step execution coordination
`agents`	agent definitions/runtime contracts
`skills`	reusable reasoning/action skills
`workflows`	durable workflow definitions
`mcp`	MCP protocol ↔ governed capabilities
`events`	events, invalidation, subscriptions/streaming
`observability`	logs, traces, metrics, audit instrumentation
`ui`	reusable UI/design-system primitives
`app-shell`	common application/bootstrap composition
`plugins`	optional extension SDK + registry
`workbenches/*`	first-party projection/domain modules

Critical Dependency Direction

workbenches → projection → active context → Twin/Skills/Agents/Workflows
    → capability → governance → connector/execution → provider
    → reconciler → Adaptive Spine

Supporting layers:

              core
               │
     ┌─────────┼─────────┐
     ▼         ▼         ▼
  runtime    events  observability

Adaptive Spine = spine-store + knowledge + memory
    → context → projection

Active Context Is the Convergence Point

Operational Truth ─┐
Knowledge ──────────┤
Memory ─────────────┤
Signals ────────────┤
Evidence ───────────┘
        ↓
  Context Compiler
        ↓
  ActiveContextBundle
        ↓
┌───────┬───────┬───────┬───────┬──────────┐
View  Canvas   Twin   Agent  Workflow   Skill
└───────┴───────┴───────┴───────┴──────────┘
                  ↓
          Capability Runtime

No Twin-specific context store, agent-specific context store, or
workbench-specific reconstruction.

Workbench Package Contract

Each first-party workbench contributes declarative domain behavior:

packages/workbenches/<domain>/
├── manifest
├── navigation
├── views
├── canvases
├── entities
├── signals
├── context-policy
├── capabilities
├── skills
├── agents
├── workflows
├── twin-policy
└── components

A workbench references capabilities. It does not own provider
credentials or raw execution adapters.

Plugins Are Separate

Do not package core workbenches as marketplace plugins.

packages/workbenches/sales = first-party canonical domain module
packages/plugins/* = optional extensions

Plugins may contribute views, commands, skills, agents, workflows,
capability references, connector definitions, MCP exposure — but cannot
bypass governance or replace canonical Spine ownership.

Client/Server Exports

For packages crossing the browser boundary:

@integratewise/auth/client       @integratewise/auth/server
@integratewise/context/client    @integratewise/context/server
@integratewise/projection/client @integratewise/projection/server
@integratewise/capability/client @integratewise/capability/server
@integratewise/twin/client       @integratewise/twin/server

Server-only: spine-store, connector/server, normalizer, governance
execution, reconciler, orchestrator execution, mcp/server, provider
adapters, Cloudflare storage bindings, model credentials.

Package Invariant

@integratewise/*    = physical repository namespace
packages/           = reusable behavior + contracts
context             = shared Active Context compiler/runtime
workbenches/*       = first-party projections
plugins/*           = optional extensions
capability          = what may be done
governance          = whether it may be done
connector           = how provider execution occurs
reconciler          = what actually happened
Adaptive Spine      = durable continuity underneath all of it

Server/Client Boundary

Desired invariant: strict client/server/import boundaries.

Current enforcement: partially architectural/conventional.

Missing: CI-enforced import boundary rules.

Browser must never transitively pull: D1, R2, KV, Vectorize, provider SDKs, credentials, MCP server code.

Recommended eventual controls:

package exports
+ ESLint restricted imports / boundaries
+ server-only markers
+ dependency graph test
+ CI verification

The implementation is mapped onto the existing monorepo structure. The wiring model's architectural intent is preserved.