FIS Architecture

Orchestrate multi-agent workflows with JSON tickets and A2A coordination. Use when delegating tasks between CyberMao (Main) and Worker agents (Engineer/Resea...

Security Scan

The skill's code and instructions are consistent with its stated purpose (multi-agent task orchestration using JSON tickets, Discord threads, and the OpenClaw sessions API), but it reads/writes local OpenClaw workspace/ticket directories and can spawn background sub-agents, so review generated commands and workspace paths before use.

Purpose & Capability

The name/description (FIS multi-agent orchestration) matches the actual behavior: creating JSON tickets, generating thread templates, invoking sessions_send/sessions_spawn semantics, and coordinating Workers. Hardcoded Discord role IDs and forum channel mappings are consistent with a Discord-based coordination workflow.

Instruction Scope

SKILL.md and the scripts instruct the agent to create/modify tickets under a shared hub, create Forum threads via the platform 'discord' tool, and call sessions_send/sessions_spawn. The code also attempts to detect the current session via OPENCLAW_SESSION_KEY or by calling the 'openclaw' CLI, and the lifecycle code scans workspace output/deliverables directories for files. These actions are expected for a coordination tool but do access local filesystem metadata and invoke platform CLI/tools — review outputs before broadcasting.

Install Mechanism

No install spec; the skill is instruction-plus-scripts only. It requires Python 3.8+ (standard library only) and uses existing runtime tools (openclaw CLI, platform-provided 'discord' and session APIs). Nothing is downloaded from external URLs or written by an installer.

Credentials

The skill does not declare required env vars, but the code will read optional variables if present (OPENCLAW_SESSION_KEY, OPENCLAW_HOME, FIS_HUB_PATH). It also writes and reads files under the derived OpenClaw home and workspaces (e.g., ~/.openclaw/fis-hub/tickets and workspace-* directories). These accesses are proportionate to ticket/deliverable tracking, but you should be aware it will enumerate files in workspace output/deliverables and include path/metadata in tickets.

Persistence & Privilege

always is false. The skill uses platform session APIs (sessions_send, sessions_spawn) to notify and spawn sub-agents; this is expected for a coordination skill. It does create and manage its own ticket files under the OpenClaw workspace, but it does not change other skills' configs or request elevated system privileges.

Assessment

This skill appears to do what it says (create/manage JSON tickets, generate Discord thread templates, and coordinate sub-agents). Before installing or running it: 1) Review the repository locally to confirm you trust the hardcoded Discord role and forum IDs and the printed A2A/sessions commands. 2) Note it will create/read ticket files under your OpenClaw home (default ~/.openclaw/fis-hub) and scan workspace output/deliverables directories — consider setting FIS_HUB_PATH or OPENCLAW_HOME to an isolated location if you don't want it enumerating your existing workspaces. 3) When executing generated sessions_send or sessions_spawn commands, inspect them first — spawning background sub-agents can increase the blast radius of any subsequent actions. 4) Ensure the Discord bot permissions it requests are intentionally granted to the correct bot accounts. If you need higher assurance, open the truncated generate_report/archive code paths (not fully shown) to confirm they don't read file contents or transmit more than file metadata and small summaries.

FIS Architecture 3.2 Pro

Multi-agent workflow framework for CyberMao (Main) → Worker coordination using JSON tickets and Discord Forum threads.

---

When to Use This Skill

Use FIS when:

• CyberMao (Main) needs to delegate complex tasks to specialized Workers
• A task requires domain expertise (coding, research, writing)
• You need to track task status across multiple sessions
• Multi-step workflows require coordination between agents

Agent Roles:

Role	Agent ID	Expertise
Architect	main	Coordination, task routing, user communication
Coding	engineer	Python, gprMax, algorithms, data analysis
Research	researcher	Theory, literature, simulation planning
Writing	writer	Documentation, LaTeX, visualization

---

Discord Bot Permissions (REQUIRED)

Each agent's Discord bot must have these permissions configured in the Discord server. Without them, Thread creation and messaging will fail silently.

Required Bot Permissions:

• Send Messages — reply in channels and threads
• Send Messages in Threads — post inside Forum threads
• Create Public Threads — create new Forum posts programmatically
• Read Message History — read thread context
• Embed Links — send rich embeds in reports
• Attach Files — upload deliverables

How to configure:

1. Go to Discord Server Settings → Roles
2. For each bot role (CyberMao, Researcher, Engineer, Writer), enable the permissions above
3. Ensure each Forum channel grants these permissions to the relevant bot roles

Verify with:

{ "action": "threadCreate", "channelId": "<forum_channel_id>", "name": "Permission Test" }

If the bot lacks permissions, the discord tool will return an error.

---

Tool Configuration

Tool	Purpose	Path
fis_lifecycle_pro.py	Ticket lifecycle (create/status/complete/list)	scripts/fis_lifecycle_pro.py
fis_coordinator.py	Generate delegation templates (CyberMao only)	scripts/fis_coordinator.py
fis_worker_toolkit.py	Spawn sub-agents, generate reports (Workers only)	scripts/fis_worker_toolkit.py

Python Environment: Requires Python 3.8+ with standard library only (no external dependencies).

---

Core Workflow

Step 1: CyberMao Delegates Task

# Generate ticket + Thread template + A2A command
python3 scripts/fis_coordinator.py delegate \
  --agent engineer \
  --task "Implement GPR signal filter" \
  --forum coding

Output:

• Ticket ID: TASK_YYYYMMDD_XXX_AGENT
• Thread template content
• sessions_send command to notify Worker

Step 2: CyberMao Creates Forum Thread

Use the discord tool to create a Thread in the appropriate Forum channel:

{
  "action": "threadCreate",
  "channelId": "<forum_channel_id>",
  "name": "TASK_xxx: Implement GPR signal filter"
}

The response returns the new Thread ID. Then notify the Worker with the Thread ID:

python3 scripts/fis_coordinator.py notify \
  --ticket-id TASK_xxx \
  --thread-id <new_thread_id>

Execute the generated sessions_send command to notify the Worker.

Step 3: Worker Executes Task

# Check ticket
python3 scripts/fis_lifecycle_pro.py list

# Update status
python3 scripts/fis_lifecycle_pro.py status \
  --ticket-id TASK_xxx --status doing

# Optional: Spawn sub-agent for complex sub-tasks
python3 scripts/fis_worker_toolkit.py spawn \
  --parent-ticket TASK_xxx \
  --subtask "Analyze algorithm complexity"

Worker replies in the Forum Thread using the discord tool:

{
  "action": "threadReply",
  "channelId": "<thread_id>",
  "content": "Task received. Starting execution."
}

Step 4: Worker Reports Completion

# Generate completion report
python3 scripts/fis_worker_toolkit.py report \
  --parent-ticket TASK_xxx \
  --summary "Successfully implemented GPR filter" \
  --deliverables filter.py test_results.json

Execute the generated sessions_send command to notify CyberMao.

Step 5: CyberMao Finalizes

# View report
python3 scripts/fis_coordinator.py report --ticket-id TASK_xxx

# Mark complete
python3 scripts/fis_lifecycle_pro.py complete --ticket-id TASK_xxx

Archive the Thread and report to User in #daily-chat.

---

Architecture

User/Linn
    ↓
CyberMao (Main) - Architect, coordinator
    ↓ sessions_send + discord threadCreate
Worker (Engineer/Researcher/Writer) - Domain experts
    ↓ (optional) sessions_spawn mode="run"
SubAgent (temporary, background) - Complex sub-tasks

Key Principles:

1. A2A via sessions_send — Main calls Workers, Workers report back
2. Ticket tracking — All tasks have JSON tickets in fis-hub/
3. Programmatic Thread creation — CyberMao creates Forum Threads via discord tool's threadCreate action
4. SubAgent background mode — sessions_spawn with mode="run", no new Thread

---

Commands Reference

fis_lifecycle_pro.py

# Create ticket
python3 scripts/fis_lifecycle_pro.py create \
  --agent engineer --task "Description" --channel-type coding

# Update status (todo/doing/done)
python3 scripts/fis_lifecycle_pro.py status \
  --ticket-id TASK_xxx --status doing --note "Progress update"

# Mark complete
python3 scripts/fis_lifecycle_pro.py complete --ticket-id TASK_xxx

# List active tickets
python3 scripts/fis_lifecycle_pro.py list

# Archive old tickets
python3 scripts/fis_lifecycle_pro.py archive

fis_coordinator.py (CyberMao only)

# Delegate and generate templates
python3 scripts/fis_coordinator.py delegate \
  --agent researcher --task "GPR theory analysis" --forum theory

# Notify Worker after Thread is created
python3 scripts/fis_coordinator.py notify \
  --ticket-id TASK_xxx --thread-id <discord_thread_id>

# View detailed report
python3 scripts/fis_coordinator.py report --ticket-id TASK_xxx

fis_worker_toolkit.py (Workers only)

# Spawn sub-agent (background, no Thread)
python3 scripts/fis_worker_toolkit.py spawn \
  --parent-ticket TASK_xxx --subtask "Complex sub-task description"

# Generate completion report
python3 scripts/fis_worker_toolkit.py report \
  --parent-ticket TASK_xxx \
  --summary "Completion summary" \
  --deliverables file1.py file2.json

---

Channel Mapping

Category	Forum Channel	Worker	Tool Flag
RESEARCH	🔬-theory-derivation	@Researcher	--forum theory
RESEARCH	📊-gpr-simulation	@Researcher	--forum simulation
DEVELOPMENT	💻-coding	@Engineer	--forum coding
WRITING	📝-drafts	@Writer	--forum drafts

---

Error Handling

If ticket creation fails:

• Check Python version: python3 --version (need 3.8+)
• Verify fis-hub/ directory exists and is writable
• Check disk space

If Thread creation fails:

• Verify the bot has Create Public Threads permission in the target Forum channel
• Check that channelId points to a Forum channel (not a regular text channel)
• Confirm the bot is a member of the server with correct roles

If A2A fails:

• Verify openclaw.json has agentToAgent.enabled: true
• Confirm Worker agent ID is in allow list
• Check Worker session is active

If sub-agent spawn fails:

• Ensure mode="run" is used (not mode="session")
• Verify task description is clear and specific

---

Quality Standards

1. One Task = One Ticket — Never reuse ticket IDs
2. Status Updates Required — Workers must update status (TODO → DOING → DONE)
3. Thread Per Task — Each task gets its own Forum Thread (created via threadCreate)
4. A2A Confirmation — Always confirm receipt via sessions_send
5. Archive After Complete — Archive Thread after task completion

---

Configuration

Required in ~/.openclaw/openclaw.json:

{
  "tools": {
    "agentToAgent": {
      "enabled": true,
      "allow": ["main", "researcher", "engineer", "writer"]
    }
  }
}

---

Testing

Quick A2A Test

# Test connectivity
sessions_send(sessionKey="engineer", message="A2A test")

Thread Creation Test

{ "action": "threadCreate", "channelId": "<forum_channel_id>", "name": "FIS Test Thread" }

Full Workflow Test

# 1. Create task
python3 scripts/fis_coordinator.py delegate \
  --agent researcher --task "Test task" --forum theory

# 2. Create Forum Thread via discord tool threadCreate

# 3. Notify Worker with Thread ID
python3 scripts/fis_coordinator.py notify \
  --ticket-id TASK_xxx --thread-id <thread_id>

# 4. Execute A2A command

# 5. Complete
python3 scripts/fis_lifecycle_pro.py complete --ticket-id TASK_xxx

---

FIS 3.2 Pro | Multi-Agent Workflow Framework