IXV-Agents

Overview

IXV-Agents is a specification-driven AI development system that organizes multiple AI agents into a fixed, role-based team. It integrates agile roles and events with specification-driven development to ensure governance, traceability, and practical enterprise usage.

---

Core Concept

Fixed roles, evolving skills. Humans define intent and specifications, while AI agents collaborate as a structured team.

• Specifications (Specs) are the single source of truth
• Roles define responsibility boundaries
• Events establish development rhythm

---

4 Principles

1. Specs are living documents
2. Specs are the Single Source of Truth (SSoT)
3. Change and iteration are assumed
4. AI reduces cost, humans decide

---

7 Processes

#	Process	Output	Approval
1	Constitution	CONSTITUTION.md	Human
2	Specify	README.md (SSoT)	Human
3	Plan	docs/*	Human(*)
4	Tasks	queue/tasks/, dashboard.md	-
5	Implement	Code + Tests, reports/*.yaml	-
6	Verify/Accept	dashboard.md, Backlog update	Human
7	Migration/Op	→ Process 2 or 4	-

(*) = when needed

See templates/PROCESS.md for details.

---

Agent Team Composition (Fixed)

Role	Count	Responsibility
Product Owner (PO)	1	Define goals and priorities, create specifications
Scrum Master (SM)	1	Orchestrate workflow, decompose and assign tasks
Development (Dev)	3	Implementation

---

Prerequisites

• macOS / Windows
• Terminal multiplexer (tmux / psmux)
• AI Editor (one of the following)
  • OpenCode (opencode) - Default
  • Claude Code (claude)

---

Setup

AI Editor

Install one of the following.

OpenCode (Default)

• Desktop app: Download from opencode.ai/download
• Command install: curl -fsSL https://opencode.ai/install | bash
• Other installation methods: See official site

Claude Code

• Desktop app: Download from claude.ai/download
• Command install: curl -fsSL https://claude.ai/install.sh | bash
• Other installation methods: See official documentation

Terminal Multiplexer

macOS: tmux

• Command install: brew install tmux
• Other installation methods: See official Wiki

Windows: psmux (tmux-compatible)

• Command install: irm https://raw.githubusercontent.com/marlocarlo/psmux/master/scripts/install.ps1 | iex
• Other installation methods: See official repository
• PowerShell 7+ required

---

Usage

1. Start Agents

macOS:

# Start with OpenCode (default)
./scripts/boot.sh

# Start with Claude Code
./scripts/boot.sh --claude-code

# Specify model
./scripts/boot.sh --model anthropic/claude-opus-4-5

Windows (PowerShell):

# Start with OpenCode (default)
.\scripts\boot.ps1

# Start with Claude Code
.\scripts\boot.ps1 -ClaudeCode

# Specify model
.\scripts\boot.ps1 -Model anthropic/claude-opus-4-5

On first run, the workspace is automatically initialized.

2. Session Layout

A single tmux session (ixv-agents) is created and automatically attached:

[ixv-agents] All Agents (5 panes)
┌─────────┬───────┬───────┬───────┐
│   PO    │ Dev1  │ Dev2  │ Dev3  │
│  (0.0)  │ (0.2) │ (0.3) │ (0.4) │
├─────────┤       │       │       │
│   SM    │       │       │       │
│  (0.1)  │       │       │       │
└─────────┴───────┴───────┴───────┘

Usage:

• Communicate your requirements to PO (upper-left pane), and tasks will be assigned to the Dev team via SM
• Other panes (SM, Dev1-3) operate automatically; no manual interaction required

Detach from session:

• Ctrl+b d to detach (session continues in background)

Reattach to session:

tmux attach-session -t ixv-agents

3. Stop Sessions

# macOS
./scripts/stop.sh
./scripts/stop.sh --force    # Force stop if processes remain

# Windows
.\scripts\stop.ps1
.\scripts\stop.ps1 -Force    # Force stop if processes remain

4. Setup New Workspace

macOS:

./scripts/setup_workspace.sh

# Skip backup and reinitialize only
./scripts/setup_workspace.sh --no-backup

Windows (PowerShell):

.\scripts\setup_workspace.ps1

# Skip backup and reinitialize only
.\scripts\setup_workspace.ps1 -NoBackup

If an existing workspace/ exists, it will be backed up to backups/, and a new workspace will be created.

tmux Quick Reference

Action	Command
Detach from session	Ctrl+b d
Reattach to session	tmux attach-session -t ixv-agents
List sessions	tmux ls

---

Directory Structure

ixv-agents/
├── roles/              # Role instructions (PO, SM, Dev)
├── skills/             # AI CLI skill definitions
├── templates/          # Workspace initialization templates
│   └── queue/          # Queue and report templates
├── scripts/            # Startup and management scripts
│   ├── banner.sh / .ps1           # Display banner
│   ├── boot.sh / .ps1             # Start agents
│   ├── stop.sh / .ps1             # Stop agents
│   ├── setup_workspace.sh / .ps1  # Initialize workspace
│   └── tmux-help.txt              # In-pane help text
├── OLD/                # Legacy assets (kept for reference)
├── backups/            # Workspace backups [.gitignore]
├── workspace/          # AI editor working directory [.gitignore]
├── docs/               # Documentation
├── Spec.md             # System specification
└── README.md

workspace/ Directory

workspace/ is the directory where AI editors actually perform their work. It is isolated from the repository root, preventing AI editors from accessing tool READMEs and other unrelated files.

workspace/
├── README.md           # Project spec (Single Source of Truth)
├── CONSTITUTION.md     # Project constitution
├── PROCESS.md          # Process and operations
├── AGENTS.md           # AI conduct guidelines
├── roles -> ../roles   (symlink)
├── .claude/skills -> ../../skills   (symlink)
├── .opencode/skills -> ../../skills (symlink)
├── queue/              # Inter-agent communication
│   ├── dashboard.md    # Project status board
│   ├── po_to_sm.yaml   # PO -> SM
│   ├── tasks/          # SM -> Dev
│   └── reports/        # Dev -> SM
└── (artifacts)         # Implementation code, tests, etc.

---

Operational Principles

• Single Source of Truth: Always reference workspace/README.md
• Traceability: Track via spec_ref / request_id / task_id
• Role Boundaries: Writing to files outside role scope is prohibited

---

Key Documents

• Spec.md: System architecture, roles, workflow, and constraints
• docs/20260129implementation-plan.md: Implementation plan
• docs/20260201directory-restructure-plan.md: Directory restructure plan

---

License

TBD