Prismatic 1.0.10

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
• 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

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
prismatic init

This creates:

• .prismatic/ - Configuration directory
  • agent-names.json - Customize agent names
  • tokens.env - API tokens (optional)
• green/, red/, blue/, black/ - Agent workspaces
• .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.

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 in current directory
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

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.

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

# Start service
prismatic start slack
prismatic status slack

# File-based fallback (only if Slack/Teams/GChat unavailable)
# Note: Limited functionality, no real-time updates
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) and should only be used as a last resort.

Agent Roles & Workflows

Agent Roles

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 tools for 30x faster execution:

cd green/.tools
./build-tools.sh --release    # Linux/macOS
.\build-tools.ps1 -Release    # Windows

Impact: 3s → 100ms startup time

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

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

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.

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/