multi-agent-os

Imported from ekson73/multi-agent-os (AGENTS.md). Install upstream with npx skills add ekson73/multi-agent-os. Copyright stays with the author.

AGENTS.md

Guide for AI coding agents working on this repository. Follows the AGENTS.md open standard (AAIF / Linux Foundation, 60k+ projects).

Project Overview

Multi-Agent OS (MAOS) is a Claude Code plugin for orchestrating AI agents in software development workflows. It provides Sentinel Protocol (anomaly detection), GaaS (Governance-as-a-Service), worktree coordination, and response compression.

Build & Test

# Validate plugin structure
bash tests/validate-plugin.sh

# Test hook scripts
echo '{"tool_name":"Task","tool_input":{"prompt":"test"}}' | bash plugin-scripts/governance/token-budget-gate.sh

# Validate JSON configs
python3 -m json.tool hooks/hooks.json > /dev/null
python3 -m json.tool sentinel/config.json > /dev/null

# Run plugin locally (self-referential)
claude --plugin-dir .

Code Conventions

• Skills: subdirectory format with SKILL.md (follows Agent Skills open standard)
• Commands: markdown files with YAML frontmatter in commands/
• Agents: markdown files with YAML frontmatter in agents/
• Hook scripts: bash with set -euo pipefail, source lib/common.sh and lib/json-rpc.sh. Authored executables (hooks + bin/ tools) SHOULD adopt the self-heal-relay pattern — relay an UNEXPECTED fault (never a legitimate gate/deny/verdict exit) to an AI-harness fallback chain for auto-repair; see docs/self-heal-relay.md
• Config: JSON with _comment fields for documentation
• Naming: lowercase-hyphenated for skills/commands/agents. Sandwich Namespacing 5-layer pattern:
  • For skills/agents: no maos- prefix in filename — Claude Code runtime auto-namespaces via plugin id (e.g., subagents surface as maos:orchestrator)
  • For commands: runtime auto-namespace is empirically unreliable (verified 2026-05-21: /status collided with Claude Code built-in /status). Use function-specific filenames (e.g., agentic-status not status) + declare namespace prefix in .claude-plugin/plugin.json command_namespace block (Layer 2) + lint against vendor_reserved_audit.claude_code_builtins (Layer 4 reference: ekson73/vek-dot-claude:docs/vendor-reserved-words.md)
• Delegation: spawning sub-agents goes through skills/delegate-governance/SKILL.md (or plugin-scripts/gaac/delegate.sh init|dna|finalize) — canonical entry point for the GaaS/GaaC framework

Testing Instructions

Before committing any changes:

1. Run bash tests/validate-plugin.sh — must pass (1 pre-existing error about plugin.json hooks field is known)
2. Verify all JSON files are valid: python3 -m json.tool <file>
3. Verify hook scripts are executable and return valid JSON
4. New skills must pass the 10-item validation checklist in skills/skill-writer/SKILL.md

Commit & PR Guidelines

• Branch naming: {type}/{scope}-{description} (e.g., feat/response-compression)
• Commit style: Conventional Commits (feat:, fix:, docs:, chore:)
• Co-author: Include Co-Authored-By: <Agent Name> <noreply@provider.com>
• Worktree: Never commit directly to main. Use git worktree add (enforced by GaaS hook)
• Secret scan: gitleaks runs on pre-commit (enforced by GaaS hook)
• PR review: Bot reviewers (CodeRabbit, Copilot, Qodo) run automatically
• CHANGELOG entry: a PR that changes the consumable contract must add an entry under ## [Unreleased]. "Contract" is not a path pattern — it is decided by scripts/entry-classifier.sh, the same is_entry() predicate tests/validate-plugin.sh uses, plus skill profiles/ (parameterisation a consumer loads). So nested entries count (agents/consultants/*.md, commands/*/*.md) while ALL-CAPS documents (agents/README.md, agents/COWORK-AUTONOMY-POLICY.md) and a skill's sub-documents (examples/, EVAL-REPORT-*.md) do not. Enforced by changelog-required.yml, which runs the classifier from a trusted checkout of main and never checks out head — only the file list comes from the API. Escape: the no-changelog label, logged in the job, never silent. Ships in WARN mode (ENFORCE: '0'); promotion to BLOCK is an operator decision (see #278)

Key Directories

Architecture Decisions

• GaaS principle: deterministic hooks > probabilistic prompts
• Sentinel: 10 detection rules, enforcement modes (soft/moderate/strict)
• Skills are Agent Skills standard: compatible with Claude Code, Cursor, Codex, Gemini CLI, Kiro, VS Code, Goose, and 25+ other tools
• No maos- prefix in filenames for skills+agents (Claude Code runtime auto-namespaces via plugin name maos). For commands, runtime auto-namespace is unreliable; prefix declaration lives in .claude-plugin/plugin.json command_namespace block (Sandwich Namespacing Layer 2), not in filename. Defense-in-depth: vendor-reserved-words lint reference at sister-repo ekson73/vek-dot-claude:docs/vendor-reserved-words.md (Layer 4)
• Framework Consumption Model: this repo is source of truth; consumers reference, don't duplicate

Security

• Never commit secrets (enforced by gitleaks pre-commit hook)
• Never use --no-verify to bypass hooks
• Never push --force to protected branches
• Treat hook scripts as security-critical (they have elevated permissions)

Branching & Release Model — GitHub Flow (Class B: library/marketplace)

This repo is CONSUMED by other repos/users — it does not deploy to environments. Model = GitHub Flow + SemVer. See docs/adrs/ADR-004-github-flow-branching.md.

• Trunk: main is always releasable. No environment branches (no homolog/ppe/prd here — those exist only in Class A deployed apps like vek-sales/vek-list).
• Work: branch feature/<id>-slug · fix/<id>-slug · hotfix/<id>-slug · docs/ · chore/ off main → PR → squash-merge → delete branch.
• Release PRs: a .claude-plugin/plugin.json version delta travels in a separate, rebased PR containing exactly one commit whose subject is chore(release): ...; it changes only the manifest version field and adds exactly one matching, additive CHANGELOG.md section. Repository squash is configured as COMMIT_OR_PR_TITLE + COMMIT_MESSAGES, so that single commit subject survives on main. README/CLAUDE versions remain derived by version-sync. The trusted-base workflow is authoritative evidence for maintainers, but remains advisory until a dedicated publisher identity or organization-level required workflow can authenticate its verdict without same-repository status spoofing.
• Agents MUST: never commit to main directly · always open a PR · never create env-branches here · treat tagging/release as a human/operator gate.
• Versioning & consumer source-pin: governed by the companion ADR-003 (version-ssot-float) + Jira — source ref = main during MVP (TTL'd). Do not re-decide it here.

GitNexus — Code Intelligence

This project is indexed by GitNexus as multi-agent-os (9822 symbols, 14591 relationships, 455 execution flows).

Index stale? Run node .gitnexus/run.cjs analyze --index-only from the project root — it auto-selects an available runner. No .gitnexus/run.cjs yet? Bootstrap with npx, bunx, or pnpm dlx — e.g. bunx gitnexus@latest analyze (npm 11 npx crash; #1939).

Always Do

• MUST run impact analysis before editing. Use impact({target: "symbolName", direction: "upstream"}) (MCP) or node .gitnexus/run.cjs impact "symbolName" --direction upstream --repo . (CLI fallback); report callers, processes, and risk. Never substitute grep for graph analysis.
• MUST analyze graph changes before committing. Use detect_changes({scope: "all"}) (MCP) or node .gitnexus/run.cjs detect-changes --scope all --repo . (CLI fallback). partial: true or truncated: true is not a clean check — a zero means unseen, not unaffected; re-run it. For regression review: detect_changes({scope: "compare", base_ref: "main"}) or node .gitnexus/run.cjs detect-changes --scope compare --base-ref "main" --repo ..
• MUST warn the user if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
• MUST treat risk: UNKNOWN as unresolved, not as low. An empty caller set is not evidence the symbol is unused — it can also mean the callers are not resolvable by the index (plain-object property access, dynamic dispatch, cross-language calls). impact pairs UNKNOWN with a riskNote saying so. Confirm with a text search before treating the symbol as safe to change or delete; do not proceed on the strength of a zero.
• When exploring unfamiliar code, use query({search_query: "concept"}) to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
• When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use context({name: "symbolName"}).
• For security review, explain({target: "fileOrSymbol"}) lists taint findings (source→sink flows; needs analyze --pdg).

Never Do

• NEVER edit a function, class, or method before MCP/CLI impact analysis.
• NEVER ignore HIGH or CRITICAL risk warnings from impact analysis, and never read UNKNOWN as an all-clear — it means the walk could not answer, which is the one verdict that requires confirming by other means.
• NEVER rename symbols with find-and-replace — use rename which understands the call graph.
• NEVER commit before MCP/CLI graph change analysis.

Resources

CLI