Prismatic 1.0.22

Prismatic - F#/.NET AI Development Workspace

Prismatic is a cross-platform AI development workspace using F# and .NET, designed for collaborative software development with AI agents using OpenCode.

What is Prismatic?

Prismatic provides a structured multi-agent workspace where AI agents can:

• Work independently - Each agent has its own workspace directory
• Collaborate via chat - Optional Slack/Teams/GChat integration with real-time push notifications
• Manage projects - GitHub Issues or Linear ticket tracking
• Review code - Automated PR analysis
• Follow workflows - Product Owner → Developer → Integration Engineer

Key Features:

• ✅ Works standalone (no external services required)
• ✅ Cross-platform (Windows, Linux, macOS)
• ✅ Four specialized agent roles (Green, Red, Blue, Black)
• ✅ Optional integrations (Slack, Teams, Google Chat, GitHub, Linear, Excel via CSV)
• ✅ F# tooling for ticket management, PR analysis, and automation
• ✅ Real-time push notifications - Automatic message delivery to agents (no manual polling needed)

Quick Start

1. Prerequisites

Required:

• .NET SDK 10.0+ - Download
• OpenCode CLI - Install

Optional (for advanced features):

• GitHub CLI (gh) - For PR analysis and issue management
• Linear API - Alternative issue tracking
• Slack/Teams/GChat Bot credentials - Team communication

2. Installation

Install as dotnet tool from NuGet:

dotnet tool install prismatic -g

Or clone the git repository and install as local tool.

dotnet pack -c Release
dotnet tool install -g --add-source ./bin/Release Prismatic

3. Initialize Your Project Workspace

# Go to your project directory
cd ~/my-project

# Initialize Prismatic workspace (default: 5 agents)
prismatic init

# Or specify the number of agents you need (1-10)
prismatic init 3   # Creates 3 agents: green, red, blue
prismatic init 10  # Creates all 10 agents

This creates:

• .prismatic/ - Configuration directory
  • agent-names.json - Customize agent names (populated for selected agent count)
  • tokens.env - API tokens (optional, populated for selected agent count)
• Agent workspaces: green/, red/, blue/, black/, yellow/ (default: 5)
  • Additional agents with 10: purple/, pink/, orange/, brown/, white/
• .slackconductor/, .teamsconductor/, .gchatconductor/ - Chat integration (optional)
• .gitignore - Excludes secrets from version control

4. Launch Agents

prismatic green    # Product Owner
prismatic red      # TDD Senior Developer
prismatic blue     # TDD Senior Developer
prismatic black    # DevOps/Infrastructure

That's it! You can start using Prismatic immediately. The .prismatic/tokens.env file is pre-filled with template values - only edit it if you need Slack/Teams/GChat integration.

5. (Optional) Compile Tools for Speed

F# tools can be compiled for 48x faster startup (2.4s → 50ms):

# Compile all tools for all agents (recommended)
prismatic compile

# Tools automatically discovered and compiled for each agent
# - green/: LinearFlow, WorkflowAutomation, TicketBackend, etc.
# - red/blue/black/yellow/: DevelopmentWorkflow, AgentRegister, etc.

After compilation, agents can use faster DLL versions:

dotnet LinearFlow.dll list          # Fast (~50ms)
dotnet fsi LinearFlow.fsx list      # Slow (~2.4s)

Note:

• Compiled DLLs are created next to .fsx files and gitignored (not committed)
• Agents can compile individual tools if needed (see agent AGENTS.md files)
• Run prismatic compile after updating tools or pulling changes

Configuration

Agent Names (Optional)

Customize agent names in .prismatic/agent-names.json:

{
  "AGENT_GREEN": "Skinner",
  "AGENT_RED": "Scully",
  "AGENT_BLUE": "Mulder",
  "AGENT_BLACK": "Busch",
  "AGENT_YELLOW": "Doggett"
}

Default names: Skinner (Agent-Green), Scully (Agent-Red), Mulder (Agent-Blue), Bluch (Agent-Black)

After editing, run prismatic start [platform] to regenerate conductor config with new names.

Optional Integrations

Edit .prismatic/tokens.env only if you need these features:

GitHub Issues (recommended for issue tracking):

# Just authenticate GitHub CLI - no tokens needed
gh auth login

Linear (alternative issue tracking):

LINEAR_API_KEY=lin_api_xxxxxxxxxxxxx
LINEAR_TEAM_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Slack (team communication):

RED_TOKEN=xoxb-your-red-bot-token
GREEN_TOKEN=xoxb-your-green-bot-token
BLUE_TOKEN=xoxb-your-blue-bot-token
BLACK_TOKEN=xoxb-your-black-bot-token
SLACK_CHANNEL_ID=C123456789

Teams/GChat: See .prismatic/tokens.env for template values.

See SERVICES.md for complete setup instructions and automated bot deployment scripts.

Architecture

Project Structure

prismatic/
├── green/              # Product Owner workspace
├── red/                # TDD Senior Developer workspace
├── blue/               # TDD Senior Developer workspace
├── black/              # DevOps/Infrastructure workspace
├── .prismatic/         # Configuration (agent-names.json, tokens.env)
├── .slackconductor/    # Slack conductor (optional)
├── .teamsconductor/    # Teams conductor (optional)
├── .gchatconductor/    # GChat conductor (optional)
└── tests/              # Unit tests

Architecture Overview

graph TB
    subgraph "Agent Workspaces"
        Green[🟢 Green - Product Owner]
        Red[🔴 Red - TDD Senior Developer]
        Blue[🔵 Blue - TDD Senior Developer]
        Black[⚫ Black - DevOps/Infrastructure]
    end
    
    subgraph "F# Tools Stack"
        LinearFlow[LinearFlow.fsx<br/>Ticket Management]
        MergeInsight[MergeInsight.fsx<br/>PR Analysis]
        WorkflowAuto[WorkflowAutomation.fsx<br/>Queue & Dependencies]
        DevWorkflow[DevelopmentWorkflow.fsx<br/>TDD Cycle]
    end
    
    subgraph "External Services (Optional)"
        Linear[Linear API<br/>Issue Tracking]
        GitHub[GitHub CLI<br/>Issues & PRs]
        Slack[Slack/Teams/GChat<br/>Team Communication]
    end
    
    Green --> WorkflowAuto
    Green --> LinearFlow
    Green --> GitHub
    
    Red --> DevWorkflow
    Blue --> DevWorkflow
    Red --> MergeInsight
    Blue --> MergeInsight
    
    WorkflowAuto --> LinearFlow
    LinearFlow --> Linear
    LinearFlow --> GitHub
    MergeInsight --> GitHub
    
    Green -.-> Slack
    Red -.-> Slack
    Blue -.-> Slack
    Black -.-> Slack
    
    style Green fill:#90EE90
    style Red fill:#FFB6C1
    style Blue fill:#ADD8E6
    style Black fill:#D3D3D3

Core Components

• Prismatic CLI - Global .NET tool for workspace management and agent launching
  • prismatic init - Initialize workspace
  • prismatic <color> - Launch agents
  • prismatic start/stop/status - Manage conductor daemons
• F# Tools:
  • LinearFlow - Linear/GitHub issue management
  • MergeInsight - PR analysis and review aggregation
  • WorkflowAutomation - Queue, dependencies, quality gates
  • DevelopmentWorkflow - TDD cycle automation
• Optional Services:
  • Conductor Services - Slack/Teams/GChat integration

Note: Legacy launcher scripts (agent, agent.ps1) are deprecated. Use prismatic <color> instead.

Commands Reference

Essential Commands

# Workspace Setup
prismatic init              # Initialize workspace with 5 agents (default)
prismatic init 3            # Initialize workspace with 3 agents
prismatic init 10           # Initialize workspace with all 10 agents
prismatic help              # Show detailed help
prismatic --version         # Show version

# Launch Agents (Main Usage)
prismatic green             # Product Owner (domain expert, tickets)
prismatic red               # TDD Senior Developer (implementation)
prismatic blue              # TDD Senior Developer (implementation)
prismatic black             # DevOps/Infrastucture (CI/CD/IaC coordination)

# Conductors (Optional - for chat integration)
prismatic start slack       # Start Slack conductor daemon (recommended)
prismatic start teams       # Start Microsoft Teams conductor
prismatic start gchat       # Start Google Chat conductor
prismatic start sharedfolder  # Start folder-based conductor (last resort fallback)
prismatic status [platform] # Check if conductor is running
prismatic stop [platform]   # Stop conductor daemon
prismatic restart [platform]# Restart conductor daemon

Quick Reference

Command	What It Does
prismatic init [count]	Create workspace (default: 5 agents, optional: 1-10)
prismatic green	Launch Product Owner agent (create tickets, assign work)
prismatic red	Launch TDD Senior Developer agent (implement features)
prismatic blue	Launch TDD Senior Developer agent (implement features)
prismatic black	Launch DevOps/Infrastructure (coordinate, CI/CD/IaC, deployment)
prismatic start slack	Enable Slack team communication
prismatic status slack	Check if Slack conductor is running

Optional Tools

All tools are completely optional - Prismatic works standalone.

GitHub Issues (Recommended)

Manage issues with GitHub CLI - no external service needed!

gh auth login
cd green/.tools
./githubissues config
./githubissues create "Title" "Description" "label"
./githubissues get #42

See: green/.tools/GITHUB_ISSUES.md

LinearFlow (Alternative)

Linear project management integration.

dotnet fsi .tools/LinearFlow.fsx create "Title" "Description"
dotnet fsi .tools/LinearFlow.fsx get PRO-123

Requires: LINEAR_API_KEY and LINEAR_TEAM_ID

MergeInsight

GitHub PR analysis and code review.

dotnet fsi .tools/MergeInsight.fsx

Requires: GitHub CLI (gh)

Conductor Services

Team communication via Slack/Teams/GChat (recommended) or file-based fallback.

Features:

• Real-time push notifications - Agents automatically receive relevant messages
• Simple registration - One-time registration per agent using provided script
• Message filtering - Only delivers @mentions, replies, and assigned tickets
• Background monitoring - Checks for new messages every 5 seconds

# Deploy bots (automated - recommended)
cd .deployment-scripts
dotnet fsi deploy-slack-team.fsx

# Start service (enables push notifications)
prismatic start slack
prismatic status slack

# Register each agent for push notifications (one-time per agent)
cd green && dotnet fsi .tools/AgentRegister.fsx
cd ../red && dotnet fsi .tools/AgentRegister.fsx
cd ../blue && dotnet fsi .tools/AgentRegister.fsx

# File-based fallback (only if Slack/Teams/GChat unavailable)
# Note: Limited functionality, no real-time updates, no push notifications
prismatic start sharedfile

See: SERVICES.md and .deployment-scripts/README.md

Note: SharedFolderConductor (.sharedfolderconductor/) is a folder-based fallback for environments where Slack/Teams/GChat cannot be used. It has limitations (no real-time updates, manual file polling, no push notifications) and should only be used as a last resort.

Agent Roles & Workflows

Agent Roles

Agent	Role	Primary Responsibilities
Green	Product Owner	Create/validate tickets, assign work, domain expertise
Red	TDD Senior Developer	Implement features using TDD, create PRs
Blue	TDD Senior Developer	Implement features using TDD, create PRs
Black	DevOps/Infrastructure	Coordinate workflows, CI/CD, IaC, deployments

Example Workflow

A typical development cycle:

1. Green creates ticket

   # In green workspace
   ./githubissues create "Add user login" "Implement OAuth flow" "enhancement"
   

2. Green assigns to developer

   ./workflow.ps1 queue #42 Agent-Red
   ./workflow.ps1 assign Agent-Red
   

3. Red/Blue implements feature

   • Discovers ticket
   • Implements with TDD
   • Creates PR when ready

4. Review and merge

   • Review PR in GitHub
   • Merge to main branch

5. Developer cleanup

   • Delete feature branch
   • Close related issues

6. Green completes ticket

   ./workflow.ps1 complete #42 Agent-Red
   

See individual AGENTS.md files in each agent directory for detailed workflows and best practices.

Advanced Features

Performance Optimization

Compile all F# tools for 48x faster startup (2.4s → 50ms):

# From workspace root - compiles all agents' tools
prismatic compile

Impact: Script startup drops from ~2.4s to ~50ms per tool execution.

When to recompile:

• After updating tools or pulling changes
• When switching between development and production usage
• To optimize frequently-used tools

Batch Operations

Process multiple commands efficiently:

linearflow batch get PRO-123 -- status PRO-123 "Done" -- comment PRO-123 "Completed"

See: green/.tools/BATCH_MODE.md

Testing

cd tests
./run-all-tests.sh           # Linux/macOS
.\run-all-tests.ps1          # Windows

See: tests/README.md

Troubleshooting

Issue	Solution
dotnet: command not found	Install .NET SDK from https://dotnet.microsoft.com/download
opencode: command not found	Install OpenCode: https://opencode.ai
prismatic: command not found	Reinstall global tool: dotnet tool install -g --add-source ./bin/Release Prismatic
Permission denied (Linux/macOS)	chmod +x tools-protect && ./tools-protect
Scripts not running (Windows)	Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

Recommended Setup Paths

Path 1: Standalone (No External Services)

Perfect for getting started:

# 1. Install and initialize
cd ~/my-project
prismatic init

# 2. Launch agents
prismatic green    # Open in terminal 1
prismatic red      # Open in terminal 2
prismatic blue     # Open in terminal 3

Use case: Single developer using AI agents for local development.

Path 2: With GitHub Issues

Add issue tracking without external services:

# 1. Initialize workspace
prismatic init

# 2. Authenticate GitHub
gh auth login

# 3. Set up workflow labels
cd green/.tools
./githubissues config    # Linux/macOS
.\githubissues.ps1 config    # Windows

# 4. Launch agents
prismatic green

Use case: Team using GitHub for code + issues, wants AI agent assistance.

Path 3: Full Team Setup (Chat Integration)

Enable multi-agent collaboration via Slack/Teams:

# 1. Initialize workspace
prismatic init

# 2. Deploy bots (automated - easiest)
cd .deployment-scripts
dotnet fsi deploy-slack-team.fsx    # Follow prompts

# 3. Start conductor
cd ..
prismatic start slack

# 4. Launch agents in separate terminals
prismatic green
prismatic red
prismatic blue

Use case: Team with chat platform, wants agents to collaborate automatically.

Manual Slack Setup (Alternative to Automated)

If you prefer manual configuration:

1. Create workspace at https://app.slack.com/
2. Create app at https://api.slack.com/apps
3. Add OAuth Scopes:
   • channels:read, chat:write, channels:history
   • groups:history, im:history, users:read
   • files:write, files:read, reactions:write, reactions:read
4. Install to workspace and add to channel
5. Copy tokens to .prismatic/tokens.env
6. Match bot names to .prismatic/agent-names.json
7. Start conductor: prismatic start slack

See: .deployment-scripts/README.md for automated setup (much easier!)

Git Repository Setup (For Developer Agents)

Set up git repositories in agent workspaces:

# Create git folder in developer workspace
cd red
mkdir git
cd git

# Clone or init your project
git clone https://github.com/user/repo.git
# OR
git init MyProject
cd MyProject
git remote add origin https://github.com/user/repo
git checkout -b dev

Repeat for blue agent if you have multiple developers.

Documentation

Document	Description
QUICKSTART.md	Step-by-step getting started guide
SERVICES.md	Setup for Linear, GitHub, Slack/Teams/GChat
green/.tools/GITHUB_ISSUES.md	Complete GitHub Issues guide
green/.tools/BATCH_MODE.md	Batch operations for bulk commands
tests/README.md	Testing guide and test runner docs
.deployment-scripts/README.md	Automated bot deployment (10 min setup)
AGENTS.md (per agent directory)	Agent-specific workflows and commands

FAQ

Q: Do I need tokens to use Prismatic?
A: No! Prismatic works standalone. Tokens are only for optional integrations (Slack/Linear/etc).

Q: Which issue tracker should I use?
A: GitHub Issues (free, integrated) or Linear (premium, feature-rich). Both work great. Or you can use just a CSV file which can be opened e.g. with Microsoft Excel.

Q: Can I use Prismatic without chat integration?
A: Yes! Launch agents directly and work with them in separate terminals. Push notifications require a conductor (Slack/Teams/GChat), but agents work fine without them.

Q: How do I update Prismatic?
A: dotnet pack -c Release && dotnet tool update -g --add-source ./bin/Release Prismatic

Q: Where do agents store their work?
A: Each agent has its own workspace directory (green/, red/, blue/, black/).

Q: Are you using MCP-protocol? A: Prismatic operates as set of well-defined tools for agents (rather than an open MCP-protocol). These tools focus on communication between the agents: Common chat-api and software ticket/issue management. The agents themselves can use whatever they want, but the tools Prismatic defines are not like open MCP-protocol.

Support & Community

• Issues: GitHub Issues
• Documentation: See above table
• .NET/F# Help: https://learn.microsoft.com/dotnet/fsharp/
• OpenCode Docs: https://opencode.ai/docs

Contributing

Contributions welcome! See individual tool directories for development guides:

• Agent tools: green/.tools/
• Conductor services: .slackconductor/, .teamsconductor/, .gchatconductor/
• Tests: tests/