Prismatic 1.0.43

Prismatic - .NET AI Development Workspace

Prismatic is a cross-platform AI development workspace, designed for collaborative software development with AI agents using OpenCode. While the platform is running on .NET, agents can be used to run any software projects.

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/Microsoft Teams/Google Chat 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)
• ✅ Up to 10 specialized agent roles (Green, Red, Blue, Black, ...)
• ✅ Optional integrations (Slack, Microsoft 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 (or alternatively VSCode with any agent plugin)

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

# Then modify your tokens.env (and agent-names.json for chat)
(joe/pico/vim/notepad/whatever) .prismatic/tokens.env

# And start the communication channel daemon
# Platforms: slack/gchat/teams/sharedfolder
prismatic start [platform]
#

4. Launch Agents

Recommended to launch an agent per different window/tab in your UI/OS.

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.

Editor Preference

By default, Prismatic launches agents using OpenCode CLI. You can configure it to use Visual Studio Code with your favorite AI coding extension (Kilo Code, Claude Code, etc.) instead:

Edit .prismatic/tokens.env:

# Use OpenCode CLI (default)
EDITOR=OPENCODE

# Or use Visual Studio Code with your favorite AI extension
EDITOR=VSCODE

Example:

# Terminal 1
prismatic blue     # Opens VS Code in ./blue folder

# Terminal 2  
prismatic red      # Opens another VS Code window in ./red folder

Both editors work great (if you have an agent plugin configured) - choose based on your preference! One limitation is that there is no automatic TUI/push-notifications support for agents, so they have to be manually asked to check their chat-messages (polling) every now and then.

5. (Optional) Compile Tools for Speed

The compiled dlls come with the package, so no need to do this. But if you (or your agents) modify the fsx scripts, the dlls can be recompiled. F# tools can be compiled for 48x faster startup (2.4s → 50ms):

# Compile all tools for all agents (takes a minute)
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 .tools/bin/LinearFlow.dll list          # Fast (~50ms)
dotnet fsi .tools/src/LinearFlow.fsx list      # Slow (~2.4s)

Note:

• Compiled DLLs are created from .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: They should really match your communication channel bot-names.

{
  "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), Busch (Agent-Black)

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

Display Preferences (Optional)

Customize emoji and color output in .prismatic/tokens.env:

# Disable emoji output (use ASCII fallbacks like [*], [+], [!])
NO_EMOJI=1

# Disable colored output (standard NO_COLOR convention)
NO_COLOR=1

Note: These can also be set as system environment variables if you prefer system-wide settings. Workspace settings in .prismatic/tokens.env take priority.

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/Infrastructure (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. By default, the project owner keeps track of tickets in a CSV file (so you can open it with Excel).

GitHub Issues

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 (TUI, on OpenCode only)
• 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              # Deploy 4 agents (default)
dotnet fsi deploy-slack-team.fsx --num-agents 6  # Deploy 6 agents
dotnet fsi deploy-teams-team.fsx --num-agents 10 # Deploy all 10 agents for Teams
dotnet fsi deploy-gchat-team.fsx --help       # Show all options

# 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
Emoji/colors display incorrectly	Add NO_EMOJI=1 and/or NO_COLOR=1 to .prismatic/tokens.env

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              # Default 4 agents
# Or: dotnet fsi deploy-slack-team.fsx --num-agents 10  # All 10 agents

# 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
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: What is this?
A: Your automatic software team. Like GitHub CoPilot agent-mode, but many of them collaborating in parallel, optionally without Microsoft.

Q: What is the difference between this and my favorite VSCode agent tool (Claude/Kilo/...)? A: This is a multi-agent solution. By providing shared communication tools, the agents have a better tendency to follow protocols of communication and software engineering, rather than doing whatever they want (MCP). VSCode doesn't support TUI/push text messages (as of 2025) like OpenCode.ai, so real-time communication among agents will be a challenge.

Q: Do I need auth-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 the MCP protocol? A: Prismatic operates as a 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 the open MCP protocol.

Q: Can I use Visual Studio Code instead of OpenCode?
A: Yes! Edit .prismatic/tokens.env and set EDITOR=VSCODE. Each agent will launch in a separate VS Code window where you can use Kilo Code, Claude Code, Cursor, or any other AI coding extension.

Why OpenCode.ai?

OpenCode.ai is a free editor that supports many paid models (Claude Sonnet/GPT-Codex/Grok/...) as well as free models, with any providers (direct Anthropic, OpenAI, xAI or via GitHub Copilot, Ollama, ...). It works on your local machine, so if your build takes 20 minutes, you don't pay for 20 minutes, only the queries. The costs are visible on the screen.

Using the OpenCode Editor

Windows users need a 3rd party terminal (e.g., WezTerm) because Windows terminal (Command Prompt/PowerShell) doesn't keep up with the speed. You register a provider with opencode auth login. Keep your sessions on one topic. You can return to an old session via /session.

Keys:

• Ctrl+C is quit.
• Ctrl+Insert is copy, Shift+Insert is paste, like Linux/MS-DOS.
• Ctrl+U: Remove all input from the prompt line.
• Tab: Switch between Build (read+write) and Plan (read-only) modes.
• @ gives a shortcut to files, where you can just type any-char to match the directory.

Example project Slack communication

Contributing

Contributions welcome! See individual tool directories for development guides:

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