This ADR has been superseded by ADR-038 for spatial intelligence patterns.
See ADR-038: Spatial Intelligence Integration Patterns (September 30, 2025)
A PM-directed committed-theory review of spatial intelligence opened 2026-07-19 and has not concluded. Its question is what to do with the cold per-connector spatial-adapter layer. Spatial deletions are HELD until it concludes, and spatial intelligence is protected representation under PM’s standing rule (meaning-representation is never removed without PM consult).
If you arrived here because you found cold or half-implemented *_spatial code and are inferring
that this ADR’s ambition failed — stop and read
../spatial-intelligence-experience-thesis.md
first. That inference is available from this file alone, it is reasonable, and the
experience-design lane’s position is that it is wrong.
The short version: spatial intelligence here is several distinct capabilities at different maturities, not one capability at partial completion. The live spatial reasoning layer ships “Piper knows where things live”; ambient presence — “Piper inhabits your tools and notices changes” — was never begun anywhere, and is not the cold adapters at a higher percentage.
📍 For the layer breakdown and every live/cold claim, go to
../spatial-intelligence-layer-map-and-costed-options.md
— it is built from the import graph and is re-runnable. If it and this notice ever disagree, it is
right. (This paragraph used to enumerate the layers itself. It was wrong twice in two days —
“three capabilities,” “cold for five others” — because it froze a measured fact into prose. Collapsed
to a pointer per m-46. — CXO, 2026-07-30)
⚠️ The most expensive mistake available here: at least one per-connector adapter
(github_spatial) is live in production behind the context assembler and an HTTP route, so
retiring “the spatial adapter pattern” would delete working code, not an unbuilt ambition. A
filename sweep over the cold modules invites exactly that error — and the 7/19 characterization made
it, by building its cold list from a recalled filename pattern instead of a directory listing.
What is over-scoped in this ADR is its universality (“ALL external tool integrations MUST…”, “no exceptions”), not the spatial concept. Connectors work today through the ADR-070 consumer path without the per-connector adapter chain.
Status of the disposition: four lanes filed (Arch mechanism, CXO experience theory, PPM
product-value, Lead code census); Arch synthesizes; PM decides. Gated on PPM’s
roadmap-dependency check. Emerging convergence is toward keep-live-reasoning + park-cold-adapters +
scope-clarify — not yet a decision. Live synthesis:
dev/2026/07/29/spatial-intelligence-architectural-history-arch-WIP.md.
—mm
Status: Accepted Date: August 12, 2025 Supersedes: Direct API integration patterns Related: ADR-001 (MCP Integration), ADR-008 (MCP Connection Pooling)
Archaeological investigation of GitHub integrations reveals pattern fragmentation with 3+ different implementation approaches. Current state includes:
services/integrations/github/github_agent.py using PyGithubservices/mcp/consumer/github_adapter.py with protocol abstractionservices/integrations/slack/spatial_adapter.py as gold standardThis fragmentation creates maintenance overhead, inconsistent user experience, and prevents leveraging our 8-dimensional spatial intelligence across all external systems.
Slack Spatial Intelligence has proven to be our architectural signature differentiator, providing:
ALL external tool integrations MUST use the unified MCP + Spatial Intelligence pattern:
┌─────────────────┐ ┌──────────────────┐ ┌────────────────────┐
│ External Tool │ │ MCP Protocol │ │ Spatial Intelligence│
│ │◄──►│ │◄──►│ │
│ • GitHub │ │ • Connection │ │ • 8 Dimensions │
│ • Notion │ │ Pooling │ │ • Context Mapping │
│ • Linear │ │ • Circuit │ │ • Attention Model │
│ • Confluence │ │ Breaker │ │ • Emotional State │
└─────────────────┘ │ • Fallback │ │ • Navigation │
│ Strategy │ │ Intent │
└──────────────────┘ └────────────────────┘
│ │
└──────────┬─────────────┘
│
┌────────▼─────────┐
│ Domain Models │
│ │
│ • Pure Business │
│ Logic │
│ • No External │
│ Dependencies │
│ • Spatial Context│
└──────────────────┘
SpatialContext(
territory_id="github",
room_id="piper-morgan-product", # Repository
path_id="issues/156", # Issue number
attention_level="high", # Priority/urgency mapping
emotional_valence="negative", # Bug vs feature
navigation_intent="respond", # Action required
external_system="github",
external_id="156",
external_context={
"assignee": "john_doe",
"milestone": "v1.2",
"labels": ["bug", "high-priority"]
}
)
SpatialContext(
territory_id="notion",
room_id="product-requirements", # Database/space
path_id="pages/PM-workflow-spec", # Page path
attention_level="medium", # Review priority
emotional_valence="neutral", # Informational content
navigation_intent="investigate", # Research mode
external_system="notion",
external_id="page-uuid-123",
external_context={
"last_edited": "2025-08-12T10:00:00Z",
"author": "pm_team",
"tags": ["workflow", "specification"]
}
)
SpatialContext(
territory_id="slack",
room_id="dev-team", # Channel
path_id="threads/1691856123.456789", # Thread ID
attention_level="urgent", # @mention, DM, etc.
emotional_valence="positive", # Sentiment analysis
navigation_intent="respond", # Immediate action
external_system="slack",
external_id="1691856123.456789",
external_context={
"channel": "#dev-team",
"thread": true,
"mentions": ["@piper"]
}
)
SpatialContext(
territory_id="asana",
room_id="product-roadmap", # Project
path_id="tasks/1234567890", # Task ID
attention_level="high", # Due date proximity
emotional_valence="neutral", # Task nature
navigation_intent="monitor", # Status tracking
external_system="asana",
external_id="1234567890",
external_context={
"due_date": "2025-08-15",
"assignee": "product_team",
"progress": 0.75
}
)
BaseSpatialAdapterservices/integrations/slack/spatial_adapter.pyservices/mcp/consumer/consumer_core.pyservices/integrations/spatial_adapter.pydocs/development/deprecation-plan.mdThis ADR establishes MCP+Spatial as the mandatory integration pattern, ensuring architectural consistency and leveraging our 8-dimensional spatial intelligence as a competitive differentiator.