npm package: @tamex/skill
Description: Multi-agent orchestration framework for Claude Code. Assigns roles (Coder, Reviewer, PM) to independent agent sessions that coordinate through a Telegram group.
Author: alfonsodev
Latest version: 0.1.0

# Tamex

Multi-agent orchestration for Claude Code. Turn a Telegram group into a
development team where each Claude Code session runs as a **Coder**, **Reviewer**,
or **PM** — coordinated through structured messages.

## How it works

```
PM assigns task ──► Coder implements ──► Reviewer reviews ──► PM gates merge
       │                                        │
       └── assigns next task ◄── coder reports done ◄── merge approved
```

- **Coders** receive tasks, code on feature branches, request reviews
- **Reviewers** read diffs, return actionable feedback with file:line references
- **PM** (hybrid) autonomously assigns tasks, but requires your Telegram approval for merges and resets

Multiple coders can work in parallel on separate branches.

## Setup

### 1. Create Telegram bots

Open [@BotFather](https://t.me/BotFather) on Telegram and create 3 bots:

| Bot | Purpose |
|-----|---------|
| `@yourproject_pm_bot` | PM's voice |
| `@yourproject_dev_bot` | Coder's voice |
| `@yourproject_rev_bot` | Reviewer's voice |

Save the tokens.

### 2. Create a Telegram group

1. Create a new Telegram group named after your project (e.g. "tamex-dev")
2. Add all 3 bots to the group
3. Get the group chat ID (add [@userinfobot](https://t.me/userinfobot) to the group temporarily)

### 3. Configure environment

```bash
cp launch/env.example .env
```

Edit `.env` with your bot tokens and chat ID:

```bash
TAMEX_PM_BOT_TOKEN=123456:ABC-DEF...
TAMEX_CODER_BOT_TOKEN=789012:GHI-JKL...
TAMEX_REVIEWER_BOT_TOKEN=345678:MNO-PQR...
TELEGRAM_CHAT_ID=-100xxxxxxxxxx
```

### 4. Install the Telegram channel plugin

```bash
claude /plugin install telegram@claude-plugins-official
```

### 5. Install role skills

Install the skill for each role you want to run:

```bash
npx skills add @tamex/skill --skill tamex-coder
npx skills add @tamex/skill --skill tamex-reviewer
npx skills add @tamex/skill --skill tamex-pm
```

## Usage

Launch each role in a separate terminal:

```bash
# Terminal 1: PM
./launch/launch.sh pm myproject

# Terminal 2: Coder 1
./launch/launch.sh coder myproject coder-1

# Terminal 3: Coder 2 (optional, for parallel work)
./launch/launch.sh coder myproject coder-2

# Terminal 4: Reviewer
./launch/launch.sh reviewer myproject
```

### Workflow

1. PM automatically assigns tasks to idle coders
2. Coders implement on feature branches, request reviews via Telegram
3. Reviewer picks up review requests, sends structured feedback
4. If changes needed, coder iterates; if approved, PM asks you to approve the merge
5. You reply "yes" or "no" in Telegram
6. On merge, PM assigns the next task (with your approval)

### PM commands

Send these to the Telegram group to control the PM:

| Command | Effect |
|---------|--------|
| `status` | Get a project status summary |
| `assign <task> to <coder>` | Manually assign a task |
| `pause` | Stop auto-assignment |
| `resume` | Resume auto-assignment |
| `reset <coder>` | Reset a coder's context |
| `backlog` | List remaining tasks |

## Communication protocol

All agents use structured message types:

| Message | Sender | Purpose |
|---------|--------|---------|
| `TASK ASSIGNMENT` | PM | Assign work to a coder |
| `REVIEW REQUEST` | Coder | Submit code for review |
| `REVIEW FEEDBACK` | Reviewer | Return actionable feedback |
| `APPROVAL REQUEST` | PM | Ask human for merge/reset approval |
| `MERGE APPROVED` | PM | Signal coder to merge |
| `TASK COMPLETE` | Coder | Report finished work |
| `RESET` | PM | Signal coder to clear context |

## Project structure

```
tamex/
├── SKILL.md                        # Root skill (orchestration overview)
├── skills/
│   ├── tamex-coder/SKILL.md        # Coder behavior contract
│   ├── tamex-reviewer/SKILL.md     # Reviewer behavior contract
│   └── tamex-pm/SKILL.md           # PM behavior contract (hybrid)
├── launch/
│   ├── launch.sh                   # Session launcher
│   └── env.example                 # Token template
├── package.json
└── .gitignore
```

## License

MIT