# Resin Ai

> Research Institute of Artificial Intelligence

- **Type:** MCP server
- **Install:** `agentstack add mcp-suxxes-resin-ai`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [suxxes](https://agentstack.voostack.com/s/suxxes)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [suxxes](https://github.com/suxxes)
- **Source:** https://github.com/suxxes/resin.ai

## Install

```sh
agentstack add mcp-suxxes-resin-ai
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Resin.ai Orchestrator

An autonomous multi-agent orchestration system for software development using Claude Code's plugin architecture. Built on state machine orchestration with deterministic execution, hierarchical planning, and specialized AI agents.

## Installation

### Prerequisites

**Required:**
- **tmux** - Session management and monitoring
  ```bash
  # macOS
  brew install tmux

  # Ubuntu/Debian
  sudo apt-get install tmux

  # Fedora/RHEL
  sudo dnf install tmux
  ```

**Automatically Available:**
- **Claude Code** - You're already using it
- **Python 3.10+** - Built into macOS/Linux
- **Git** - Pre-installed on most systems

### Install Plugin

```bash
# Add marketplace and install plugin (one command)
/plugin marketplace add suxxes/resin.ai && /plugin install orchestrator@resin-ai
```

That's it! The orchestrator is ready to use.

## System Overview

**Project Type**: Claude Code Plugin System
**Version**: 3.1.0
**Purpose**: Autonomous orchestration of complete software development lifecycle through specialized AI agents

### Core Architecture

- **Plugin-Based System**: Seamlessly integrated into Claude Code IDE via marketplace
- **MCP Server**: Zero-dependency Python implementation using Model Context Protocol
- **State Machine Orchestration**: Deterministic, repeatable execution through structured phases
- **Specialized AI Agents**: 5 domain-specific agents with hierarchical expertise
- **Language Skills System**: 4 language-specific skills (Python, TypeScript, Next.js, Swift) for developer agent
- **Resource-Driven**: All knowledge stored as structured Markdown (48 resource files)
- **Hierarchical Planning**: Project → Epic → Story → Task structure with enriched context

## Technology Stack

### Core Technologies
- **Python 3.10+**: MCP server implementation (zero external dependencies)
- **Model Context Protocol (MCP)**: JSON-RPC 2.0 over stdio
- **Markdown**: Knowledge base and documentation format
- **JSON Schema**: Tool parameter validation
- **Git**: Integrated version control workflow

### Architecture Pattern
- **Plugin Architecture**: Claude Code IDE marketplace integration
- **State Machine Design**: Deterministic phase transitions with return codes
- **Agent Delegation**: Hierarchical agent coordination
- **Template System**: Standardized output formats

## Directory Structure

```
orchestrator/
├── .claude-plugin/
│   └── plugin.json              # Plugin metadata (v3.1.0)
├── .mcp.json                    # MCP server configuration
├── resources.py                 # MCP server implementation (Python)
├── agents/                      # AI agent definitions (5 agents)
│   ├── product-manager.md       # Strategic project planning
│   ├── project-manager.md       # Epic-to-story breakdown
│   ├── feature-manager.md       # Story-to-task breakdown
│   ├── developer.md             # Unified multi-language developer agent
│   └── quality-assurance.md     # Enhanced QA validation
├── commands/                    # CLI orchestrators (4 commands)
│   ├── plan.md                  # Planning state machine
│   ├── work.md                  # Implementation state machine
│   ├── dryrun.md                # Planning preview (no execution)
│   └── docs.md                  # Documentation generation
├── skills/                      # Language-specific skills (4 skills)
│   ├── developer-python/        # Python standards and patterns
│   ├── developer-typescript/    # TypeScript/JavaScript standards
│   ├── developer-nextjs/        # Next.js full-stack patterns
│   └── developer-swift/         # Swift/Apple platform standards
├── resources/                   # Markdown knowledge base (48 files)
│   ├── CORE/                    # Core requirements (5 files)
│   ├── STATE-MACHINE/           # State definitions (14 files)
│   ├── AGENT/                   # Agent phases (8+ directories)
│   └── TEMPLATE/                # Output templates (20+ files)
└── hooks/                       # Lifecycle hooks (session monitoring)
```

## Key Features

### 1. Autonomous Multi-Agent Orchestration

Coordinates specialized AI agents through deterministic state machines where each agent has specific expertise:

- **Product Manager**: Strategic planning, architecture, technology stack selection
- **Project Manager**: Epic breakdown into stories with prioritization
- **Feature Manager**: Story breakdown into tasks with technical specifications
- **Developer**: Unified multi-language TDD implementation with automatic language skill activation
- **Quality Assurance**: Enhanced validation with 95%+ test coverage requirements

### 2. Hierarchical Planning System

Auto-detects planning scope and creates complete development plans:

```
Project Level → Epic Level → Story Level → Task Level
```

**Numbering Format**: `XXXX.YY.ZZ` (Epic.Story.Task)
- Epic: `0001`
- Story: `0001.01`
- Task: `0001.01.01`

**Generated Documentation**:
```
docs/
├── OVERVIEW.md                  # Project vision and goals
├── ARCHITECTURE.md              # System architecture
├── TECH-STACK.md                # Technology decisions
├── DEPLOYMENT.md                # Deployment strategy
├── DEVELOPMENT.md               # Development guidelines
├── FILES.md                     # File organization
├── DEVELOPMENT-PLAN.md          # Master plan with all epics/stories/tasks
└── DEVELOPMENT-PLAN/
    ├── 0001 - Epic Name.md
    ├── 0001.01 - Epic - Story.md
    └── 0001.01.01 - Epic - Story - Task.md
```

### 3. State Machine Execution

**Planning State Machine** (`/orchestrator:plan`):
```
PLAN_INIT → PLAN_LOOP → PLAN_QUIZ → PLAN_WORK → PLAN_DONE
```

**Implementation State Machine** (`/orchestrator:work`):
```
EPIC_LOOP → STORY_LOOP → TASK_LOOP
  ├── INIT: Initialize and prepare
  ├── WORK: Execute implementation
  ├── TEST: Validate and verify
  └── DONE: Complete and transition
```

**State Transitions**: Controlled by return codes (CONTINUE, EXIT, FAILURE)

### 4. Language Skills System

Developer agent automatically activates language-specific skills based on task requirements:

**Supported Languages**:
- **Python**: Type hints, testing patterns, Pythonic best practices
- **TypeScript/JavaScript**: Strict types, generics, utility types, async/await patterns
- **Next.js**: App Router, Server Components, RSC patterns, server actions
- **Swift**: SwiftUI, protocol-oriented design, modern concurrency, optionals

**Skill Activation**: Automatic during Phase 03 (Requirements Analysis) via Skill tool

**Skill Contents**: Language standards, best practices, common patterns, testing standards

### 5. Test-Driven Development (TDD) Enforcement

Developer agent follows strict TDD methodology with 11 phases:

1. Initialize Tasks
2. Requirements Analysis (includes language skill activation)
3. Project Discovery
4. Test Design
5. Test Implementation
6. Code Implementation
7. Test Verification
8. Documentation
9. Validation & Handoff

### 6. Requirements Enrichment

Prevents re-asking questions through enriched context:

- **Questionnaire-based discovery** at each planning level
- **Context preservation** through hierarchical delegation
- **Parent context inheritance** (Story inherits Epic context, Task inherits Story context)
- **Scope-specific questions** only

### 7. Enhanced Quality Assurance

Through-the-roof quality standards:

- **95% minimum test coverage**
- **Multiple validation layers**: Unit, integration, E2E
- **Security vulnerability scanning**
- **Performance benchmarking**
- **Regression validation**
- **Zero tolerance for failures**: Returns to development on any test failure

### 8. Documentation Automation

Template-driven documentation generation:

- **LLM-optimized technical writing**
- **Eliminates duplication** across documentation files
- **Concrete code examples** with file references
- **Automatic updates** during implementation

### 9. MCP Server Implementation

Two zero-dependency MCP servers power the orchestrator:

**Resources Server** (`resources.py`):
- **JSON-RPC 2.0 protocol** over stdio
- **Single tool**: `read` for accessing Markdown resources
- **URI scheme**: `plugin:orchestrator:resources://path/to/file.md`
- **Security**: Directory traversal prevention, Markdown-only validation
- **Error handling**: Comprehensive JSON-RPC error responses

**Ping-Pong Server** (`ping-pong.py`):
- **Hook-based session monitoring** via file mtime tracking
- **Auto-discovery** of sessions from `$CLAUDE_PLUGIN_ROOT/.sessions/` directories
- **Stale detection** and automatic continuation prompts
- **Direct tmux session** communication for session revival
- **Randomized continuation messages** for natural interaction (5+ variants)
- **Debug-only logging** via `RESIN_AI_DEBUG=1` environment variable
- **System-wide session tracking** at plugin root level

### 9. Session Monitoring & Revival

Hooks-based ping/pong system ensures continuous agent operation:

**How it works**:
1. **Hooks track activity**: Every tool use updates session file with todos from `tool_input.todos`
2. **Ping-pong monitors**: Background process checks for stale sessions via file mtime
3. **Auto-continuation**: Sends prompts to tmux sessions by session ID when stale detected (only if active todos exist)
4. **Session files**: `$CLAUDE_PLUGIN_ROOT/.sessions/{normalized_project}/{session_id}.json`

**Session lifecycle**:
- **PreToolUse hook** (TodoWrite): Updates session file with todos array from `tool_input.todos`
- **PostToolUse hook**: Updates file mtime for activity tracking
- **UserPromptSubmit hook**: Ensures tmux session name stays synchronized with Claude Code session ID
- **SessionStart hook**: Renames tmux session to match Claude Code session ID
- **Background monitor**: Checks file mtime every 30 seconds, parses todos, counts active/pending tasks
- **Stale detection**: No activity for 150 seconds + active/pending todos triggers continuation
- **SessionEnd hook**: Deletes session file (todo-aware - preserves if active todos exist)

**Continuation messages**:
- **Randomized prompts**: 5+ message variants for natural interaction
- **Examples**: "Please continue working...", "Let's keep going...", "Continue..."

**Debug mode**:
- **Enable logging**: Set `RESIN_AI_DEBUG=1` environment variable
- **Production default**: Logging disabled for zero overhead
- **Log location**: `$CLAUDE_PLUGIN_ROOT/.sessions/logs/`

**Session file format**:
- **Filename**: `{session_id}.json` (session_id encoded in filename)
- **Contents**: JSON array of todos from `tool_input.todos` in PreToolUse hook payload
- **Example**: `[{"content":"Phase 1","activeForm":"Running Phase 1","status":"in_progress"}]`
- **Benefits**:
  - Self-contained (no dependency on `~/.claude/todos`)
  - Reads directly from hook payload (`tool_input.todos`)
  - Falls back to `~/.claude/todos` if needed
  - mtime-based staleness detection
  - Smart continuation (only when active/pending todos exist)

**Requirements**:
- **tmux required**: All orchestrator work must run in tmux
- **Automatic setup**: Hooks are plugin-native (no manual configuration)
- **Zero overhead**: File write operations on active events only (~1-2ms per event)

### 10. TMUX Environment Requirements

All orchestrator commands require tmux for session persistence and monitoring:

**Critical requirements**:
- **MUST** run in tmux session for orchestrator commands (`/orchestrator:plan`, `/orchestrator:work`, `/orchestrator:docs`)
- **Automatic verification**: Phase 00 checks `$TMUX_PANE` environment variable
- **Immediate stop**: Commands halt with clear error message if tmux not detected
- **Template-based errors**: Consistent error reporting via `TMUX-ERROR.md` template

**How to start tmux**:
```bash
# Create new session
tmux new -s resin-ai-orchestrator

# Or attach to existing session
tmux attach -t resin-ai-orchestrator
```

**Why tmux is required**:
- **Session persistence**: Long-running orchestrations survive terminal disconnects
- **Activity monitoring**: Ping-pong system tracks stale sessions via session IDs
- **Auto-revival**: Continuation prompts sent directly to tmux sessions by session ID
- **Session naming**: tmux sessions automatically renamed to match Claude Code session IDs
- **Simplified targeting**: Uses session IDs (e.g., `tmux send-keys -t $SESSION_ID`) instead of pane IDs for more robust communication
- **Stable references**: Session IDs don't change, unlike pane IDs which can shift

**Resources**:
- **TMUX requirements**: `orchestrator/resources/CORE/TMUX.md`
- **Error template**: `orchestrator/resources/TEMPLATE/REPORT/TMUX-ERROR.md`

## CLI Commands

### Planning Orchestrator

```bash
/orchestrator:plan                           # Auto-discover next planning level
/orchestrator:plan "Build SaaS platform"     # Project-level planning
/orchestrator:plan "Add authentication"      # Epic-level planning
/orchestrator:plan "User login story"        # Story-level planning
```

**Output**: Complete development plan with documentation hierarchy

### Implementation Orchestrator

```bash
/orchestrator:work                           # Auto-discover next task
/orchestrator:work 0003                      # Full epic orchestration
/orchestrator:work 0003.02                   # Story-level orchestration
/orchestrator:work 0003.02.01                # Task-level orchestration
```

**Process**: Autonomous execution through all implementation phases with TDD

### Documentation Generator

```bash
/orchestrator:docs                           # Generate technical documentation
```

**Output**: Complete LLM-optimized documentation suite

### Planning Preview

```bash
/orchestrator:dryrun [DESCRIPTION]           # Preview planning without execution
```

**Purpose**: Understand what will be created before committing

## Workflow Architecture

### Complete Development Lifecycle

```
1. Planning Phase (/orchestrator:plan)
   ↓
   Product Manager: Project architecture and epic discovery
   ↓
   Project Manager: Epic breakdown into stories
   ↓
   Feature Manager: Story breakdown into tasks
   ↓
   Output: Complete development plan

2. Implementation Phase (/orchestrator:work)
   ↓
   For each Task:
     ├── Developer: TDD implementation (11 phases)
     ├── Quality Assurance: Enhanced validation
     └── Transition to next task
   ↓
   For each Story:
     └── Complete all tasks → Story complete
   ↓
   For each Epic:
     └── Complete all stories → Epic complete
   ↓
   Output: Fully implemented, tested, validated code

3. Documentation Phase (/orchestrator:docs)
   ↓
   Auto-generate technical documentation
   ↓
   Output: LLM-optimized docs with code examples
```

### State Transition Flow

```
User Command
   ↓
Auto-detect Scope (Project/Epic/Story/Task)
   ↓
Load State Machine Definition
   ↓
Execute Current Phase
   ↓
Evaluate Return Code
   ├── CONTINUE → Next phase
   ├── EXIT → Complete orchestration
   └── FAILURE → Handle error
   ↓
Update State and Documentation
   ↓
Loop until completion
```

## Agent Specialization

### Product Manager
- **Expertise**: Strategic planning, architecture, technology selection
- **Phases**: Project initialization, epic discovery
- **Output**: OVERVIEW.md, ARCHITECTURE.md, TECH-STACK.md, DEPLOYMENT.md

### Project Manager
- **Expertise**: Epic decomposition, story prioritization
- **Phases**: Epic planning, story breakdown
- **Output**: Epic documentation with story definitions

### Feature Manager
- **Expertise**: Task specification, technical dependencies
- **Phases**: Story planning, task breakdown
- **Output**: Story documentation with task specifications

### Developer Specialists
- **Expertise**: Language-specific TDD implementation
- **Languages**: Python, TypeScript, Next.js, Swift
- **Methodology**: 11-phase TDD with zero-placeholder policy
- **Output**: Production-ready, fully-tested code

### Quality Assurance
- **Expertise**: Enhanced validation, comprehensive testing
- **Standards**: 95%+ coverage, security scanning, performance validation
- **Methodology**: Multi-layer testing (unit, i

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [suxxes](https://github.com/suxxes)
- **Source:** [suxxes/resin.ai](https://github.com/suxxes/resin.ai)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** yes
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-suxxes-resin-ai
- Seller: https://agentstack.voostack.com/s/suxxes
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.