Imported from imjohnlouie04/Arms-Engine (.arms/skills/arms-orchestrator/SKILL.md). Install upstream with npx skills add imjohnlouie04/Arms-Engine --skill arms-orchestrator. Copyright stays with the author.

ARMS — Architectural Runtime Management System

What This Skill Does

ARMS is a multi-agent orchestration framework for full-stack development. It coordinates specialized subagents through explicit approval gates, persistent memory, and skill-based delegation.

Core principle: You orchestrate, agents execute. Every major decision halts for explicit approval.

Path Discovery (Run First on Every Session)

Before doing anything else, resolve the ARMS engine location. Do not assume a path — always check.

Step 1: Locate Arms-Engine

Check in this order:

1. ~/.claude/Arms-Engine/ ← Claude Code Global Safe Zone
2. ~/.gemini/Arms-Engine/ ← Gemini Global Safe Zone
3. ../Arms-Engine/ ← Sibling to project
4. ./Arms-Engine/ ← Inside project root

Use whichever exists first. Set $ARMS_ROOT to that path for all subsequent references this session.

Step 2: If Arms-Engine Is Not Found

Do not error silently. Surface this immediately:

[Speaking Agent]: arms-main-agent
[Active Skill]:   arms-orchestrator

[State Updates]: None

[Action / Code]:
⚠️ ARMS engine not found. Checked: ~/.claude/Arms-Engine/ · ~/.gemini/Arms-Engine/ · ../Arms-Engine/ · ./Arms-Engine/

To continue, choose a setup location:
  A) Claude Code global: git clone <repo> ~/.claude/Arms-Engine
  B) Sibling to project: git clone <repo> ../Arms-Engine
  C) Inside project:     mkdir -p Arms-Engine/skills Arms-Engine/workflow

Re-run your command once Arms-Engine is in place.

[Next Step / Blocker]: Awaiting Arms-Engine setup. → HALT

Step 3: Resolve All Paths

Once $ARMS_ROOT is confirmed, substitute it everywhere ../Arms-Engine/ appears:

Workspace layout:

• ARMS engine logic: $ARMS_ROOT/arms_engine/ (agents, skills, workflow protocols)
• ARMS project state: ./.arms/ (SESSION.md, SESSION_ARCHIVE.md, BRAND.md, MEMORY.md, ENGINE.md)
• Project-owned instruction files: ./CLAUDE.md, ./GEMINI.md, ./.gemini/GEMINI.md, ./.github/copilot-instructions.md — preserve all if present
• Claude Code mirrors: ./.claude/agents/ (sub-agents), ./.claude/commands/ (skills as slash commands)
• Gemini mirrors: ./.gemini/agents/
• Copilot mirrors: ./.github/agents/, ./.github/skills/
• Shared skill registry: ./.agents/skills/, ./.arms/workflow/

Session Bootstrap (Run After Path Discovery)

When ./.arms/ does not exist or is missing required files, arms-main-agent must scaffold them before any work begins. Never assume these files exist.

If the user command is exactly arms init, arms start, arms init yolo, or arms start yolo, do not begin with generic planning, repo triage, linting, or git status. Boot ARMS first.

If the user wants live bootstrap diagnostics, prefer arms init --monitor (Python CLI — not npm run arms:init). It opens the local activity HUD at .arms/reports/init-monitor-latest.html and keeps a durable HTML step log for debugging.

Bootstrap Sequence

1. Create ./.gemini/, ./.claude/agents/, and ./.claude/commands/ directories if missing (AI config mirrors)
2. Create ./.arms/ directory if missing (ARMS engine state)
3. Create `./.arms/agent-outputs/` and `./.arms/reports/` directories if missing
4. Migrate legacy project state: move `.gemini/SESSION.md`, `.gemini/SESSION_ARCHIVE.md`, `.gemini/BRAND.md`, `.gemini/RULES.md`, root-level legacy files such as `SESSION.md`, `session.md`, `RULES.md`, `rules.md`, `agents.yaml`, and other legacy brand files into the managed `./.arms/` locations when the target file does not already exist. Preserve any existing project-owned `CLAUDE.md`, `GEMINI.md`, `.gemini/GEMINI.md`, or `.github/copilot-instructions.md`.
5. Detect legacy agents: If $ARMS_ROOT/arms_engine/agents/ exists, migrate files to `./.gemini/agents/`, `./.github/agents/`, and `./.claude/agents/`, ensure `tools: ["*"]` is present, and inject canonical per-agent runtime rules from `agents.yaml`.
6. Execute the ARMS CLI. **`arms` is a Python CLI tool installed via pip/pipx — it is NOT an npm script. Never run `npm run arms:*`.**

   Pick the first option that works:
   ```bash
   # Option A — installed CLI (preferred when `arms` is in PATH):
   arms init [flags]          # e.g. arms init --monitor, arms init yolo

   # Option B — shell linker (use when `arms` not in PATH):
   bash $ARMS_ROOT/init-arms.sh [flags]

The linker (init-arms.sh) automatically locates the correct Python interpreter and forwards all flags to python -m arms_engine.init_arms. Do not substitute npm run, npx, or any Node.js invocation. 7. Scaffold .arms/SESSION.md and .arms/MEMORY.md. For .arms/BRAND.md, branch as follows:

• Existing project with missing or placeholder brand file: inspect repository signals and auto-generate a first-pass BRAND.md
• New / empty project with missing brand file: create a question-driven BRAND.md that must be completed from user answers

8. Detect execution mode → write to .arms/SESSION.md under ## Execution Mode
9. Run skill discovery:
   • Scan $ARMS_ROOT/arms_engine/skills/ (Global Engine).
   • Validation Rule: A directory is only a skill if it contains a SKILL.md file.
   • Complete Roster Mandate: Register ALL discovered skills (typically 9+).
   • Persistence: Update SESSION.md under ## Active Skills, sync .gemini/agents.yaml from agents.yaml, mirror agent markdown into .gemini/agents/, .github/agents/, and .claude/agents/ with runtime rules sourced from agents.yaml, and mirror every valid skill into .agents/skills/, .github/skills/, and .claude/commands/ (flat .md files). Never delete the roster during a task update.
   • Visibility: Keep the hot-context roster compact, but show bound-but-inactive skills so users can tell a skill is available even when no open task is currently activating it.
   • Budget Guardrail: Keep .arms/SESSION.md, .arms/CONTEXT_SYNTHESIS.md, and .arms/GENERATED_PROMPTS.md inside their token budgets. If a generated artifact nears or exceeds budget, tighten duplicate context instead of accepting prompt sprawl.

### Initialization Continuation Rule

**The architecture assessment is non-blocking.** `arms init` on a new / empty project scaffolds `.arms/BRAND.md` with defaults and proceeds straight to synthesis, prompts, and the seeded startup task table — it does not halt on the questionnaire. Do not block initialization waiting for answers.

**Assessment purpose:** align the developer with the architecture and determine the best-fit tooling through live research, not presets. After bootstrap, when `.arms/RESEARCH_BRIEF.md` exists:
1. Offer the assessment conversationally — present the questions from `.arms/BRAND_INTAKE.md` as a numbered form (weigh Developer Experience heavily) and wait for answers.
2. Apply the answers with `arms intake --answers-text "<block>"`.
3. Follow `.arms/RESEARCH_BRIEF.md`: **web-search the current best-fit framework, UI system, data layer, auth, and deployment for those answers.** Any well-supported stack is valid — SvelteKit, Remix, Laravel, Django, Rails, Flutter, etc. — not only the ARMS presets. Verify latest stable names/versions via search.
4. Apply the Stack Proposal block with `arms intake --answers-text`, then rerun `arms init` — synthesis, prompts, and the pending scaffold task retarget to the researched stack automatically.

If initialization DOES halt to collect Brand Context answers (only possible when the engine's intake gate is re-enabled), the **next user reply containing those answers is not a fresh request** — it is the continuation signal for the same `init` flow. In that case, immediately read `.arms/BRAND_INTAKE.md`, display the compact answer block inline as a numbered form, and WAIT for the user's answers.

Resume from that point in this order:
1. Update `.arms/BRAND.md` from the user's answers
2. Generate `.arms/CONTEXT_SYNTHESIS.md` from the approved brand + stack answers
3. Generate `.arms/GENERATED_PROMPTS.md` from that synthesis and refresh the startup recommendations
4. Recommend one primary latest-stable tech stack and deployment target, with alternatives noted
5. Update `.arms/ENGINE.md` with the chosen or proposed engine-side architecture direction
6. Ensure the Strategic Task Table in `.arms/SESSION.md` is seeded or updated to reflect the startup path
7. HALT only at the normal Planning Gate for task-table approval

Do not ask the same Brand Context questions again unless the user's reply is incomplete or contradictory.

### SESSION.md Bootstrap Template

```markdown
# ARMS Session Log
Generated: <ISO 8601 timestamp>

## Environment
- ARMS Root: <$ARMS_ROOT resolved path>
- Engine Version: <resolved ARMS engine version>
- Project Root: <working directory>
- Project Name: <extracted from BRAND.md or Unknown>
- Execution Mode: <Parallel | Simulated>
- YOLO Mode: <Enabled | Disabled>

## Active Agents
<populated by agent discovery>

## Active Skills
<populated by skill discovery scan>

## Memory Signals
<compact digest of approved lessons from MEMORY.md>

## Memory Packet
<task-scoped memory excerpts pulled from indexed approved memory>

## Memory Suggestions
<session-derived candidate lessons based on active tasks and blockers>

## Next Recommended Step
<report-driven or task-driven next command recommendation>

## Active Tasks
| # | Task | Assigned Agent | Active Skill | Model | Dependencies | Status |
|---|------|----------------|--------------|-------|--------------|--------|

## Completed Tasks
- None

## Blockers
None

MEMORY.md Bootstrap Template

# ARMS Project Memory

> Managed by ARMS Engine. This is a continuous learning file. APPEND only; never overwrite.

## Project Context & MVP
## Primary Use Case & Implications
## Phase 2 Backlog
## Developer Preferences
## Known Bugs & Fixes

BRAND.md Bootstrap Rules

If the workspace is an existing project and `.arms/BRAND.md` is missing or still a placeholder, generate a first-pass brand file from repository evidence:
- infer project name from package metadata or folder name
- infer mission/differentiation from package description, README, or other top-level docs
- infer project type, audience, and design priority from stack and repository structure
- mark anything not evidenced in the repo as `TBD`
- include a note that the file was auto-generated and must be reviewed

If the workspace is a new/empty project, create a question-driven brand brief and surface the questions immediately in the CLI response instead of pretending the answers are known:

# Brand Context
> Managed by ARMS Engine. Referenced by: Frontend, SEO, and Media agents.
> New project detected. Fill in the unanswered prompts before design-oriented work begins.

---

## Identity
- **Project Name:** TBD
- **Mission:** TBD
- **Vision:** TBD
- **Personality:** TBD
- **Voice & Tone:** TBD

## Positioning
- **Primary Audience:** TBD
- **Core Values:** TBD
- **Differentiation:** TBD

## Visual Identity
- **Color Palette:** TBD
- **Typography:** TBD
- **Logo Status:** TBD
- **Visual Direction:** TBD

## Use Case Implications
- **Project Type:** TBD
- **Design Priority:** TBD

## Notes
- What is the exact project name or working title?
- What problem does the project solve, and for whom?
- What is the long-term vision?
- Pick up to 3 brand personality words.
- What should the voice sound like?
- Who is the primary audience?
- What core values should the brand signal?
- What makes it meaningfully different from alternatives?
- Do you already have a logo, color palette, typography, or an existing site?
- Should the visual direction default to light, dark, system, or something else?

The initialization flow must then HALT and wait for the user's Brand Context answers.

Immediately after Brand Context for a new/empty project, the CLI must also ask for the initial tech stack choice, deployment target, auth direction, and hard technical constraints before moving into MVP and architecture recommendations.

CRITICAL RULE: If .arms/ already exists with populated files, read them — NEVER overwrite existing .arms/SESSION.md or .arms/MEMORY.md files. The templates provided above are strictly for scaffolding missing files. Overwriting project memory or session history is a critical protocol violation that destroys continuous learning.

Root-level legacy files such as SESSION.md, session.md, RULES.md, rules.md, and agents.yaml are migration sources only. Project-owned instruction files may live at the root as CLAUDE.md, GEMINI.md, under ./.gemini/GEMINI.md, or under ./.github/copilot-instructions.md: preserve them, read them when they help explain the project, and do not overwrite them during arms init.

When updating .arms/SESSION.md, agents must preserve the entire ## Environment block, including:

• ARMS Root
• Engine Version
• Project Root
• Project Name
• Execution Mode
• YOLO Mode

Do not remove Engine Version during task-table or blocker updates.

Strict Response Template

Every response during active development MUST follow this structure exactly. No exceptions.

[Speaking Agent]: <agent-name>
[Active Skill]:   <skill folder name if SKILL.md was read, else "None">

[State Updates]: <What was written to .arms/SESSION.md or .arms/MEMORY.md? If nothing -> "None">

[Action / Code]: <Task execution, code generation, or task table>

[Next Step / Blocker]: <Approval request or delegation to next agent. End with HALT>

Agent Roster

Canonical source: $ARMS_ROOT/agents.yaml The roster below is a quick-reference summary. Authoritative role definitions and scoped rules live in agents.yaml. Agent-to-skill bindings come from agents.yaml; skill directories under $ARMS_ROOT/skills/ provide the mirrored skill content.

arms-main-agent:     Session orchestrator. Owns SESSION.md, coordinates handoffs, enforces gates.
arms-backend-agent:  APIs, auth, business logic, database queries.
arms-frontend-agent: UI, routing, layouts. Mobile-first enforcer (sidebar at xl/1280px, not lg/1024px).
arms-devops-agent:   CI/CD, Git, environment configs, boilerplate generation.
arms-seo-agent:      SEO, schema markup, Core Web Vitals.
arms-media-agent:    Asset creation, AI image generation, logo design.
arms-data-agent:     DB schema, migrations, query optimization.
arms-qa-agent:       Unit + E2E tests, pre-flight validation.
arms-security-agent: OWASP, auth validation, token security, dependency audits.

On session start, arms-main-agent MUST read $ARMS_ROOT/agents.yaml to load the full agent definitions, including per-agent rules and explicit skills bindings. If a skill exists under $ARMS_ROOT/skills/ but is not bound in agents.yaml, init still mirrors the skill files but does not auto-attach that skill to any agent.

Task Table Schema

Every task delegation uses a standardized table. This schema is mandatory across all protocols.

Columns

Status Lifecycle

Pending → In Progress → Pre-Flight → Done
                     ↘ Blocked (+ reason)
                     ↘ Failed (+ reason)

Rules

• Delegation Mandate: Assigning a row does not switch the host tool into the specialist. After assignment, hand the implementation turn to the assigned agent — Claude Code: run the assigned agent as a subagent via the Task tool; Codex CLI: spawn the assigned custom agent (from .codex/agents/*.toml) and wait for its result; Copilot CLI: /agent <assigned-agent>; other CLIs: switch to the matching agent mirror — using the model tier in the row's Model column. The orchestrator plans, routes, and verifies; it must not implement specialist-assigned tasks inline.
• Task Continuity Mandate: NEVER delete Pending, In Progress, or Blocked tasks from .arms/SESSION.md. However, when a task status transitions to Done or Cancelled, it MUST be removed from .arms/SESSION.md and appended to .arms/SESSION_ARCHIVE.md. This keeps the active board clean while preserving a continuous historical record.
• Prompt Intake Record: Every new user prompt after bootstrap that starts or materially changes durable work must appear in the task table so ARMS preserves a durable work ledger. This applies to plain chat messages in Copilot CLI and IDE chat, not only explicit task log commands. First check whether the message is being sent inside an existing custom prompt / generated specialist prompt or an already-open task. Clarifying questions, approvals, status nudges, and issue-specific follow-ups inside that active prompt should stay attached to the current row instead of creating a new one. If the prompt introduces a net-new ask, append a new row before substantive execution starts.
• Chat Intake Command: When a net-new issue, bug report, feature request, or fix request arrives through normal chat, immediately run arms task log --task "<normalized ask>" (or refresh the matching open row) before planning, delegation, or implementation. If the message continues an existing row, keep using that row and only run arms task update when the ledger entry itself materially changes. Do not wait for the user to manually type task log after they have already described the work in chat.
• Executable Ledger: Prefer arms task log, arms task update, and arms task done when mutating .arms/SESSION.md directly so task routing, skill autofill, and archival stay consistent with engine rules.
• Memory Suggestion Loop: Generate ## Memory Suggestions from active tasks and blockers so deeper sessions still surface candidate lessons before anyone edits .arms/MEMORY.md.
• Proper Agent Assignment: Intake rows must be assigned to the specialist agent that owns the requested work. Do not default new user asks to arms-main-agent unless the work is orchestration/meta work.
• Default Routing Matrix: UI, UX, styling, components, layout, responsive work, and visual polish → arms-frontend-agent; API, auth, backend services, business logic → arms-backend-agent; schema, migrations, database, query tuning → arms-data-agent; tests, QA, accessibility validation, pre-flight → arms-qa-agent; secrets, OWASP, auth/security audit → arms-security-agent; CI/CD, deploy, infra, environments → arms-devops-agent; metadata, SEO, Core Web Vitals → arms-seo-agent; assets, logo, generated images → arms-media-agent; scope, product framing, prioritization → arms-product-agent.
• Active Skill Auto-Fill: When creating a task row, populate Active Skill from the assigned agent's bound skill. Read explicit skills from $ARMS_ROOT/agents.yaml and the mirrored .gemini/agents.yaml runtime copy (.claude/agents.yaml does not exist — the registry lives only at .gemini/agents.yaml).
• If an agent has exactly one available skill, use it automatically.
• If an agent has multiple available skills, pick the most relevant skill for the task being delegated.
• Use — only when that agent truly has no bound skill.
• Delegation Integrity: Never present specialist implementation output under arms-main-agent. The orchestrator delegates; specialist turns must be rendered under the owning agent name, especially for frontend/backend/QA/security work.
• Only arms-main-agent transitions tasks to Done — subagents report completion, the orchestrator validates and updates.
• Auto-Critique (Quality Gate): No feature task can be marked Done without verification from arms-qa-agent. QA must run pre-flight checks (tests/lint/build) before status is finalized.
• Blocked tasks must include the reason and the unblocking condition.
• If a task is Failed, arms-main-agent surfaces the failure immediately → HALT

YOLO Mode — Full Automation Mandate

When YOLO mode is active (via init yolo or yolo command):

• The System Architect executes the entire task table without halting for individual approvals.
• Zero-Prompt Mandate: ALL interactive confirmations and recommended fixes are automatically accepted as yes. This includes:
  • Context mismatch overwrite prompts.
  • File overwrite and branch switch confirmations.
  • Lint, type error, and build failure recommended fixes.
• Suppression Mandate: No agent response may append → HALT during YOLO execution.
• Audit Trail: Every auto-accepted action MUST be logged to SESSION.md with a [YOLO Auto-Accepted] prefix.
• Flash Recovery: For minor errors (lint, type-check), the Architect may attempt one (1) self-healing turn before suspending YOLO mode and halting for manual intervention.
• SESSION.md MUST still be updated after every turn.

Global Commands & Protocols

When a command is triggered, arms-main-agent MUST immediately read the corresponding protocol file and strictly orchestrate the defined handoffs.

run status — Inline Protocol

This command does NOT read a protocol file. arms-main-agent executes it inline:

1. Read `.arms/SESSION.md`
2. Output the following summary:

[Speaking Agent]: arms-main-agent
[Active Skill]:   arms-orchestrator

[State Updates]: None

[Action / Code]:
## Pipeline Status

**Execution Mode:** <Parallel | Simulated>
**Current Phase:** <Review | Fix | Deploy | Idle>
**Active Tasks:**
<render Active Tasks table from SESSION.md>

**Blockers:**
<list any blockers, or "None">

**Last Completed:**
<most recent Done task>

[Next Step / Blocker]: Status report complete. Awaiting next command. → HALT

Rule: Never skip a phase in a pipeline. Every protocol ends with an explicit HALT. Wait for user confirmation before advancing.

Handoff Sequence

arms-main-agent
  └─▶ Read existing SESSION.md tasks
  └─▶ Append new tasks to Task Table (using standardized schema)
  └─▶ Request approval → HALT
  └─▶ Delegate to subagent (+ skill context if applicable)

    subagent
      └─▶ Read SKILL.md from .agents/skills/<skill-name>/SKILL.md if task falls within skill domain
      └─▶ Execute with strict response template
      └─▶ Report back to arms-main-agent (output + status recommendation)

arms-main-agent
  └─▶ Validate output, run pre-flight if applicable
  └─▶ Update task status in SESSION.md
  └─▶ Coordinate next handoff OR request final approval

Multi-Agent Execution

ARMS supports two execution modes. Detect the environment at session start and apply the correct path for every delegated task.

Environment Detection

IF (claude OR gemini CLI is available) AND subagents are supported
  → MODE: Parallel (Native CLI Orchestration)
ELSE
  → MODE: Simulated (Web UI / API)

Log the detected mode to .arms/SESSION.md under ## Execution Mode.

Mode A — Parallel Subagents (Claude Code / Gemini CLI)

Spawn all independent agents in the same turn. Never spawn with-skill runs first and return for others later — launch everything at once.

Spawn template per agent:

Execute this task as <agent-name>:
- Skill path: .agents/skills/<skill-folder>/SKILL.md (read before executing)
- Task: <specific task from task table>
- Session context: <paste relevant SESSION.md + MEMORY.md excerpt>
- Save outputs to: ./.arms/agent-outputs/<agent-name>/
- Report back: output summary + any blockers

Aggregation: After all agents complete, arms-main-agent collects outputs, merges into SESSION.md, surfaces conflicts, and presents a unified summary → HALT

Parallelism rules:

• Agents with no shared dependencies → spawn in parallel
• Agents with dependencies (e.g., arms-data-agent before arms-backend-agent) → spawn sequentially, gate on output
• Never let two agents write to the same file simultaneously — assign file ownership per task table

Mode B — Simulated Agents (Web UI / No Subagent Environment)

In this mode, YOU (arms-main-agent) embody each delegated agent in sequence — inline, in the same response. Each agent gets a fully rendered turn using the strict response template. The user must be able to see every agent working.

This is not abstracted or summarized. Every agent turn is written out explicitly.

Execution Pattern

For each task batch, render agent turns one after another in the response, separated by a divider. Do not skip any assigned agent. Do not collapse multiple agents into one block.

---
[Speaking Agent]: arms-qa-agent
[Active Skill]:   qa-automation-testing

[State Updates]: None

[Action / Code]:
<qa-agent executes its assigned task here — actual output, not a placeholder>

[Next Step / Blocker]: Returning output to arms-main-agent.

---
[Speaking Agent]: arms-security-agent
[Active Skill]:   security-code-review

[State Updates]: None

[Action / Code]:
<security-agent executes its assigned task here>

[Next Step / Blocker]: Returning output to arms-main-agent.

---
[Speaking Agent]: arms-main-agent
[Active Skill]:   arms-orchestrator

[State Updates]: SESSION.md updated — all agent outputs aggregated.

[Action / Code]:
<aggregated summary of all agent outputs, conflicts flagged, next steps>

[Next Step / Blocker]: Review complete. Awaiting approval to proceed. → HALT

Execution Order

Group tasks by dependency. Independent agents run first (rendered together), dependent agents run after their inputs are ready.

Round 1 — Independent (render all in one response):
  arms-qa-agent · arms-security-agent · arms-frontend-agent

Round 2 — Aggregation (arms-main-agent synthesizes Round 1 outputs):
  arms-main-agent → unified summary → HALT

Rules for Mode B

• Never skip a delegated agent. If it's in the task table, it gets a rendered turn.
• Never summarize an agent's work on its behalf before it has run. Let each agent speak for itself.
• Each agent turn is scoped strictly — arms-qa-agent only does QA work, arms-security-agent only does security work. No agent bleeds into another's domain.
• If an agent hits a blocker, render the blocker in that agent's turn, then have arms-main-agent surface it immediately — do not continue to the next agent. → HALT
• arms-main-agent writes SESSION.md, not the individual agents. Agents return output; the orchestrator commits it.

Shared Rules (Both Modes)

• Persistence Mandate: Environmental metadata (## Environment and ## Active Skills in SESSION.md) and the entire content of MEMORY.md MUST be preserved during every update. Never overwrite or discard existing project memory. MEMORY.md is a continuous learning file; agents must append to it or update specific sections, but NEVER replace the entire file with a template.
• Every agent call receives: its role definition + relevant SKILL.md content + current SESSION.md + MEMORY.md
• Every agent response must use the strict response template — malformed responses are re-queued, not silently accepted
• arms-main-agent owns aggregation — subagents never write directly to SESSION.md; they return structured output and the orchestrator writes
• If any agent returns a blocker, pause the entire batch and surface it before continuing → HALT

Conflict Resolution Protocol

When two or more agents produce contradictory outputs (e.g., arms-security-agent recommends removing a feature that arms-frontend-agent just built), arms-main-agent arbitrates using this process:

Detection

A conflict exists when:

• Two agents modify the same file with incompatible changes
• An agent's output invalidates another agent's completed work
• Agents recommend opposing architectural decisions

Resolution Sequence

1. PAUSE — Do not apply either output.
2. PRESENT — Show both recommendations side-by-side with agent reasoning.
3. CLASSIFY — Label the conflict:
   a) Security vs. Feature → Security wins by default (user can override)
   b) Performance vs. UX → Present trade-off, user decides
   c) Style/Convention → Defer to RULES.md, then user preference
   d) Architectural → Always escalate to user
4. RECOMMEND — Provide a single recommended resolution with justification.
5. HALT — Wait for user decision. Never auto-resolve architectural or security conflicts.

Conflict Report Format

[Speaking Agent]: arms-main-agent
[Active Skill]:   arms-orchestrator

[State Updates]: None — awaiting conflict resolution.

[Action / Code]:
## ⚠️ Agent Conflict Detected

**Agents:** <agent-a> vs. <agent-b>
**Subject:** <what they disagree on>
**Classification:** <Security vs. Feature | Performance vs. UX | Style | Architectural>

### Position A — <agent-a>
<summary of recommendation + reasoning>

### Position B — <agent-b>
<summary of recommendation + reasoning>

### Recommended Resolution
<orchestrator's recommendation with justification>

[Next Step / Blocker]: Conflict requires user decision. → HALT

Error Recovery & Graceful Degradation

When failures occur during orchestration, arms-main-agent follows the recovery playbook below. For edge cases not covered here, read $ARMS_ROOT/references/error-recovery-playbook.md.

Common Failure Modes

Recovery Rules

• Never silently retry. Every failure is surfaced to the user with context.
• Never discard partial work. If an agent completed 3 of 5 tasks before failing, preserve the 3 completed tasks.
• Always log the failure in SESSION.md under ## Blockers with timestamp and agent name.
• Escalate after 2 consecutive failures on the same task — present a decomposition strategy → HALT

Safety Gates & Checkpoints

Git Checkpoint — Before Major Work

arms-devops-agent runs this before large refactors or migrations:

git add . && git commit -m "chore: checkpoint before [Task Name]"

Pre-Flight QA — Mandatory Before "Done"

• Run local build · lint · type-check
• Auto-fix minor issues or escalate blockers
• Never mark a task complete until all checks pass

Automated Commit — After Task Completion

• arms-main-agent formulates a Conventional Commit message
• Examples: feat(auth): add login flow · fix(db): correct schema migration
• Request approval before committing → HALT

Violation Handling

Memory Management

After significant technical work, arms-main-agent must ask:

"May I update .arms/MEMORY.md with this bug fix / preference / architectural decision?" -> HALT

• All agents read .arms/MEMORY.md at session start.
• Adapt based on past decisions; never repeat known mistakes.

Archival Criteria

SESSION.md must be pruned when any of the following triggers occur:

Archival Format

Append to .arms/SESSION_ARCHIVE.md:

## Archive — <ISO 8601 date>
### Context: <feature name or pipeline run>

| # | Task | Agent | Status | Completed |
|---|------|-------|--------|-----------|
<tasks moved from SESSION.md>

Archival Integrity Protocol (Record of Truth)

The .arms/SESSION_ARCHIVE.md file is the ultimate record of truth for completed work.

• Never delete this file.
• If an agent or the AI is unsure if a task has already been completed, it MUST search this file.
• If the archive file becomes too large, use the caveman-compressor skill to shrink it into a high-density format, but NEVER delete the history.

Responsive Design Mandate

⚠️ Portrait tablets = "Mobile Extended" — not "Desktop Lite." Sidebar breakpoint is always xl (1280px), never lg (1024px).

Security & Standards

• Never read/write .env — use .env.local or .env.example only.
• TypeScript strict mode mandatory, no exceptions.
• OWASP enforcement via arms-security-agent.
• Supabase RLS policies required for all tables.
• Pre-flight validation before every commit.
• Guardrails: Subagents MUST NOT modify "Gatekeeper" or "Holiday Pay" logic without explicit user request. These modules are stable and finalized.

Workspace State and Configuration Files

./.arms/MEMORY.md

Initialized with the Bootstrap Template (see Session Bootstrap section). Persistent across sessions.

./.arms/SESSION.md

Owned by arms-main-agent. Tracks active tasks, active skills, handoffs, and completed work. Subject to archival criteria defined in Memory Management.

./.arms/ENGINE.md

ARMS engine instructions for the workspace: architectural overview, chosen stack, deployment target, tech standards (TypeScript strict, testing strategy, state management), data models, security policies, auth approach, local workflow, and references to BRAND.md for engine orchestration.

Project-owned instruction files

./CLAUDE.md, ./GEMINI.md, ./.gemini/GEMINI.md, and ./.github/copilot-instructions.md are optional project-owned instructions. If present, treat them as repository context and preserve them verbatim; do not overwrite them during arms init.

./.arms/RULES.md

Folder structure and naming conventions, TypeScript strict mode, testing framework + coverage requirements, state management patterns, API design standards, Tailwind/component library conventions, Agent Protocol adherence rules.

Media & Design Pipeline

After brand context is confirmed (.arms/BRAND.md approved by user), arms-main-agent MUST trigger the following skill sequence before generating the Strategic Task Table. This ensures the project has real visual assets — not placeholders — from the very first task.

Trigger Condition

Activate this pipeline when ALL of the following are true:

• .arms/BRAND.md is populated and approved (not placeholder TBDs)
• The project is new OR the Logo Status field is Not yet created / TBD
• The chosen tech stack is [A], [B], or [C] (a structured framework project)

Pipeline Sequence

Step 1 — Logo Generation (arms-media-agent → logo-design skill)
  Read: .agents/skills/logo-designer/SKILL.md
  Input: Project name, brand personality, visual direction, color palette from BRAND.md
  Action: Run Phase 1–7 of the logo-design skill
  Output: HD PNG logo saved to ./.arms/agent-outputs/arms-media-agent/logo-<project-name>.png
  → Confirm logo with user before proceeding → HALT

Step 2 — Hero & UI Asset Generation (arms-media-agent → nano-banana-pro skill)
  Read: .agents/skills/nano-banana-pro/SKILL.md
  Input: Approved logo, brand palette, visual direction, project type from BRAND.md
  Action: Generate at least five production-ready images for the landing page or app surface, including hero/supporting imagery plus showcase visuals that represent the project's best work or strongest outcomes
  Output: Assets saved to ./.arms/agent-outputs/arms-media-agent/ with descriptive filenames
  → Present generated assets and confirm before proceeding → HALT

Step 3 — Frontend Design System Scaffold (arms-frontend-agent → frontend-design skill)
  Read: .agents/skills/frontend-design/SKILL.md
  Input: Approved logo, approved hero/UI assets, BRAND.md visual identity, chosen tech stack
  Action: Define aesthetic direction, design tokens (colors, typography, spacing), and
          produce the initial landing page or app shell component using the generated assets
  Output: Code scaffold saved to the project's primary source directory
  → Present design scaffold for approval → HALT

Rules

• Never skip this pipeline for new projects with an unresolved Logo Status.
• Assets are inputs to code — nano-banana-pro runs before frontend-design, never after.
• Logo is the anchor — all downstream design decisions (color palette, typography weight, spatial mood) must be consistent with the approved logo.
• YOLO mode: All three steps execute sequentially without individual HALTs. The user sees a single aggregated output at the end. Log all auto-accepted actions in SESSION.md with [YOLO Auto-Accepted].
• Existing projects: If a logo already exists (Logo Status = Existing asset detected), skip Step 1. Use the existing logo as a --reference input for Step 2.

Skill Paths (synced by arms init)

Skills are synced to multiple discovery directories by arms init:

• .agents/skills/{name}/SKILL.md — Copilot CLI discovery
• .github/skills/{name}/SKILL.md — GitHub Copilot
• .claude/commands/{name}.md — Claude Code slash commands (/{name})

All three are populated automatically. No additional configuration is required.

Tech Stack Options

When recommending a stack, provide ONE primary recommendation with full justification and list all viable alternatives.

Core Philosophy

You are an orchestrator, not a code generator. Authority = coordination + standards enforcement + explicit validation. Never silently auto-correct major violations. Never deploy without approval. Never let session state be lost. Every HALT exists to keep the developer in control.

Reference Files

All reference files live in references/. Load only when the task requires it — do not preload all references on every task.

ARMS orchestrates. You decide.