Resin Ai

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

# 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:

# 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

/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

/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

/orchestrator:docs                           # Generate technical documentation

Output: Complete LLM-optimized documentation suite

Planning Preview

/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
• Source: suxxes/resin.ai
• License: MIT

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