Implementation Plan: Cognitive Extension Layer

Implement AI-driven cognitive amplification services: context analysis, artifact generation, CADSL runtime/renderer, and routing across agent capabilities.

Provenance & Traceability

Architectural Decisions (ADRs)

ADR ID Decision Title Impact on This Plan
ADR-007 Cognitive Extension Layer Defines AI-driven artifact recommendation.
ADR-008 CADSL Generative UI CADSL is the canonical UI description language.
ADR-026 Cognitive Supply Chain Prompts are versioned specs (BAML).

Product Requirements (PRDs)

PRD ID Requirement Title Satisfied By (SDS) Acceptance Criteria
PRD-001 AI Generative Capabilities SDS-005 Artifact generation
PRD-002 Cognitive Amplification SDS-051, SDS-005 Context + synthesis
PRD-003 Context-Aware Recommendations SDS-051 Context analysis
PRD-004 Dynamic Artifact Generation SDS-005, SDS-038 Artifact pipeline
PRD-005 Interactive Artifact Experience SDS-038 CADSL runtime

Software Design Specifications (SDS)

SDS ID Service/Component Bounded Context SEA-DSL Spec File Implementation Status
SDS-051 Universal Context Service shared N/A Draft
SDS-005 Artifact Engine Service cognitive-extension N/A Designed
SDS-038 CADSL Runtime & Renderer cognitive-extension N/A Designed

Note: SDS-004 (Context Analyzer) has been superseded by SDS-051 (Universal Context Service) to provide holistic context vectors for the compiler.

Technical Stack Selection

Updated 2025-12-30: Selected governed, deterministic AI stack.

Capability Selection Justification
Orchestration LangGraph + Semantic Kernel Graph-based agents, state management, Softmax Router pattern.
Prompt Engineering BAML Type-safe, versionable prompts-as-code.
Structured Output Outlines Token-level constrained generation (deterministic).
Workflow Activepieces Integration workflows for CMMN cases.
UI Components CopilotKit Chat UI and Generative UI components (via adapter).

Architecture and Design

Components & Ports (No Technical Debt)

All AI capabilities are wrapped to ensure governance and swapability.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

// AI Orchestration Port (Wraps LangGraph)
interface CognitiveOrchestrationPort {
  routeIntent(context: Context): Promise<AgentRoute>;
  executeWorkflow(workflowId: string, input: any): Promise<WorkflowResult>;
}

// Generative UI Port (Wraps CopilotKit + Activepieces)
interface CognitiveUIPort {
  renderChat(context: SemanticContext): ChatComponent; // returns abstract component
  renderGenerativeArtifact(cadsl: CADSLSpec): ArtifactComponent;
}

// Prompt Engine Port (Wraps BAML)
interface PromptEnginePort {
  generate(templateId: string, variables: Record<string, any>): Promise<string>;
}

Design Principles Applied

Dependency Justification

Updated 2025-12-30: Added specific dependencies from gap analysis sections 2.1, 2.2, 2.3.

2.1 AI Orchestration & Agent Framework

Dependency Type Version NPM/PyPI Package Justification ADR/SDS Reference
LangGraph Python Library 0.4.x langgraph Graph-based agent patterns (Softmax Router), state management, checkpointing, visual debugging. SDS-040, SDS-006
Semantic Kernel Python/Node Library 1.x semantic-kernel (Python) Orchestration workflows, memory integration, plugin system. SDS-040
Outlines Python Library 0.1.x outlines Constrained generation at token level using FSM/regex. Guarantees schema validity without retries. Local-first. SDS-027, SDS-029
BAML Tool/CLI 0.90.x @boundaryml/baml (NPM); baml (Python) Type-safe prompt definitions with generated clients, retry/fallback, model abstraction. Prompts-as-code. ADR-009, ADR-026, SDS-025

2.2 Artifact Generation (CADSL)

Dependency Type Version NPM/PyPI Package Justification ADR/SDS Reference
Mermaid Node.js Library 11.x mermaid Generate diagrams from CADSL templates; flowcharts, sequence, ER, C4. ADR-008, SDS-038
D2 CLI Tool 0.6.x @terrastruct/d2 (NPM); via mise d2 Alternative diagram renderer for declarative diagrams. SDS-038
Graphviz CLI Tool 12.x System package; @hpcc-js/wasm-graphviz (NPM) Render DOT graphs programmatically. SDS-038
Unified/Remark Node.js Library 11.x unified, remark-parse, remark-stringify Transform markdown with custom syntax extensions. SDS-038
HeadlessUI React Library 2.x @headlessui/react Accessible UI primitives for CADSL artifact rendering. PRD-005, SDS-038
shadcn/ui React Library N/A via npx shadcn-ui Styled component system built on Radix. SDS-038
CopilotKit React Library 1.x @copilotkit/react-core, @copilotkit/react-ui Chat UI and Generative UI components. Wrap in port adapter. SDS-038, SDS-048

2.3 Case Management (CMMN)

Dependency Type Version NPM/PyPI Package Justification ADR/SDS Reference
Activepieces Platform 0.39.x Self-hosted via Docker Integration workflows for case execution and triggers. ADR-021, SDS-012
Temporal.io Platform 1.x @temporalio/client, @temporalio/worker Reliable case execution with durable workflows. ADR-021, SDS-012

Installation Commands

1
2
3
4
5
6
7
8
9
10

# Python dependencies
pip install langgraph semantic-kernel outlines baml

# Node.js dependencies
pnpm add mermaid unified remark-parse remark-stringify @headlessui/react @copilotkit/react-core @copilotkit/react-ui

# CLI tools via mise
mise use d2@0.6.0

# Temporal (Docker service - see infra/docker-compose.yml)

Proposed Cycles

Cycle Branch Wave Files Modified Files Created Specs Implemented  
C1A cycle/p020-c1a-context-service 1 docs/specs/shared/sds/051-universal-context-service.md — Universal context  
C1B cycle/p020-c1b-artifact-engine 1 docs/specs/cognitive-extension/sds/005-artifact-engine-service.md — Artifact generation  
C2A cycle/p020-c2a-cadsl-runtime 2 docs/specs/cognitive-extension/sds/038-cadsl-runtime-renderer.md — CADSL runtime  

Task Breakdown

Wave 1 (Parallel)

Wave 2 (Depends on Wave 1)

Validation & Verification

Spec Validation

Implementation Validation

Risks & Mitigation

Risk Likelihood Impact Mitigation Strategy
Non-deterministic generation Medium High Use Outlines regex constraints; pin seeds.
UI Coupling to CopilotKit Low Medium Strict usage of CognitiveUIPort adapter.