agent-together

English | 中文

Shared project state for every AI coding agent.

Every agent leaves its own fragments — .opencode/, .claude/, CLAUDE.md, scattered todo.md / 计划.md — so the next agent has to re-learn the project from scratch. agent-together fixes that with one convention:

1. A shared state directory .agent/ (progress, memory, conventions, plans)
2. A skill (agent-fusion) that teaches agents when to read and write it
3. A fusion subagent + /fusion command that merges legacy scattered files

Design history (self-contained, any agent can pick up): docs/plans/PLAN_v2.md · docs/plans/PLAN_v1.md

Quick start

opencode

# 1. Install components (skill + agent + command) globally
./scripts/install.sh --target opencode

# 2. Scaffold shared state into a project
./scripts/install.sh --scaffold /path/to/your/project

# 3. Restart opencode, then inside the project:
#    /fusion status   # detect drift
#    /fusion sync     # merge scattered legacy files
#    /fusion init     # (only if you skipped scaffold)

Install into a single project instead of global:

./scripts/install.sh --target opencode --project /path/to/your/project

Claude Code

./scripts/install.sh --target claude          # -> ~/.claude/{skills,agents,commands}
./scripts/install.sh --scaffold /path/to/proj
# restart Claude Code, then: /fusion status  |  /fusion sync

Project-level install (no global changes):

./scripts/install.sh --target claude --project /path/to/your/project

Both ecosystems at once

./scripts/install.sh --target all --project /path/to/your/project

Shared state layout

your-project/
├── AGENTS.md           # entry pointer: every agent reads this first
├── CLAUDE.md           # shim → AGENTS.md (Claude Code entry)
└── .agent/
    ├── STATE.md        # progress: phase, done, todo, next steps
    ├── MEMORY.md       # long-lived facts: decisions, pitfalls, preferences
    ├── CONVENTIONS.md  # file rules: dirs, naming, where artifacts go
    └── plans/          # plan archive (never scatter todos in repo root)

Reading order when taking over a task: AGENTS.md → STATE.md → MEMORY.md → CONVENTIONS.md → plans/.

Components

Component	Path	Role
skill agent-fusion	core/skills/agent-fusion/	When to read/write shared state; hard rules for artifact placement
opencode subagent	adapters/opencode/agents/fusion.md	Merge scattered files into .agent/ (permission.edit locked to .agent/**)
opencode command	adapters/opencode/command/fusion.md	/fusion init|sync|status
claude subagent	adapters/claude/agents/fusion.md	Same role; tools whitelist instead of permission map
claude command	adapters/claude/commands/fusion.md	/fusion init|sync|status
templates	core/templates/	Authoritative format for the three-piece state + entry files

The skill source is shared across ecosystems — installers copy core/skills/agent-fusion/ into each target's skills directory.

Repository layout

core/       # ecosystem-neutral: templates + skill
adapters/   # one subdirectory per ecosystem
            #   opencode/ ✅  claude/ ✅  codex/ gemini/ cursor/ (reserved)
scripts/    # install.sh (target mapping table)
docs/plans/ # self-contained design plans (any agent can continue from these)

Adapter status

Ecosystem	Entry file	Skill	Command	Subagent	Status
opencode	AGENTS.md	✅	✅ command/	✅ agents/	✅ implemented & e2e tested
Claude Code	CLAUDE.md / AGENTS.md	✅	✅ commands/	✅ agents/	✅ implemented & e2e tested
Codex CLI	AGENTS.md	✅ (via ~/.agents/skills)	⚠️	✅ (toml)	reserved
Gemini CLI	GEMINI.md	✅	✅	✅	reserved
Cursor	AGENTS.md / .cursor/rules	❌	❌	❌	reserved (rules-only fallback)

How to add an adapter (core stays untouched)

1. mkdir adapters/<name>/ with that ecosystem's agent/command files (reuse adapters/opencode/ and adapters/claude/ bodies; only paths and frontmatter differ)
2. Add a mapping branch in scripts/install.sh (global_prefix_for / project_subdir_for / command_subdir_for)
3. Ecosystem without skills? Rely on root AGENTS.md (embedded read/write rules) — the convention layer (.agent/ + AGENTS.md) is enough for minimum viability

Write rules (excerpt; skill is authoritative)

• Milestone done → update STATE.md; durable fact → append MEMORY.md; file rules live only in CONVENTIONS.md
• New plans/todos → .agent/plans/YYYY-MM-DD-topic.md — never scatter progress files in the repo root
• On conflict, .agent/ wins; merge legacy files with /fusion sync

Verification

bash -n scripts/install.sh
./scripts/install.sh --target all --prefix /tmp/at-cfg
./scripts/install.sh --scaffold /tmp/at-proj   # target dir must exist
# e2e: open opencode or Claude Code in a sandbox and run /fusion status → sync

License

MIT © 2026 wanxinhao

---

---

agent-together（agent融合装置）

English | 中文

给所有 AI 编程 agent 用的共享项目状态约定。

每个 agent 都留下自己的碎片（.opencode/、.claude/、CLAUDE.md、根目录乱放的 todo.md/计划.md），下一个 agent 接手时只能从头重新摸索。agent-together 用一套约定解决：

1. 共享状态目录 .agent/（进度、记忆、文件约定、计划）
2. skill agent-fusion：教会 agent 何时读、何时写
3. fusion subagent + /fusion 命令：把历史散落产物归并进来

设计档案（自包含，任何 agent 可直接接手）： docs/plans/PLAN_v2.md · docs/plans/PLAN_v1.md

快速开始

opencode

# 1. 全局安装组件（skill + agent + command）
./scripts/install.sh --target opencode

# 2. 给目标项目生成共享状态脚手架
./scripts/install.sh --scaffold /path/to/your/project

# 3. 重启 opencode，在项目里执行：
#    /fusion status   # 检查漂移
#    /fusion sync     # 归并散落旧产物
#    /fusion init     # （未跑 scaffold 时才需要）

只装进单个项目：

./scripts/install.sh --target opencode --project /path/to/your/project

Claude Code

./scripts/install.sh --target claude          # -> ~/.claude/{skills,agents,commands}
./scripts/install.sh --scaffold /path/to/proj
# 重启 Claude Code，然后：/fusion status  |  /fusion sync

项目级安装（不动全局）：

./scripts/install.sh --target claude --project /path/to/your/project

两个生态一起装

./scripts/install.sh --target all --project /path/to/your/project

共享状态目录

你的项目/
├── AGENTS.md           # 入口指针：任何 agent 先读这个
├── CLAUDE.md           # shim → AGENTS.md（Claude Code 入口）
└── .agent/
    ├── STATE.md        # 进度：阶段、已完成、待办、下一步
    ├── MEMORY.md       # 长期记忆：决策、坑、偏好（只追加）
    ├── CONVENTIONS.md  # 文件约定：目录、命名、产物归置
    └── plans/          # 计划归档（禁止根目录再散落进度文件）

接手任务的阅读顺序： AGENTS.md → STATE.md → MEMORY.md → CONVENTIONS.md → plans/。

组件

组件	路径	作用
skill agent-fusion	core/skills/agent-fusion/	何时读/写共享状态；产物归置硬规则
opencode subagent	adapters/opencode/agents/fusion.md	归并散落产物（permission.edit 锁定 .agent/**）
opencode command	adapters/opencode/command/fusion.md	/fusion init|sync|status
claude subagent	adapters/claude/agents/fusion.md	同上；权限用 tools 白名单表达
claude command	adapters/claude/commands/fusion.md	/fusion init|sync|status
模板	core/templates/	三件套 + 入口文件的权威格式

skill 源码跨生态共用——安装器把 core/skills/agent-fusion/ 拷到各目标的 skills 目录。

仓库结构

core/       # 生态中立：templates + skill
adapters/   # 每生态一个子目录
            #   opencode/ ✅  claude/ ✅  codex/ gemini/ cursor/（预留）
scripts/    # install.sh（target 映射表）
docs/plans/ # 自包含设计计划（任何 agent 可从这里继续）

Adapter 状态

生态	入口文件	Skill	Command	Subagent	状态
opencode	AGENTS.md	✅	✅ command/	✅ agents/	✅ 已实现并 e2e 验证
Claude Code	CLAUDE.md / AGENTS.md	✅	✅ commands/	✅ agents/	✅ 已实现并 e2e 验证
Codex CLI	AGENTS.md	✅（~/.agents/skills）	⚠️	✅（toml）	预留
Gemini CLI	GEMINI.md	✅	✅	✅	预留
Cursor	AGENTS.md / .cursor/rules	❌	❌	❌	预留（仅 rules 兜底）

如何新增 adapter（core 零改动）

1. mkdir adapters/<name>/，按该生态的 agents/commands 路径约定放入变体文件 （正文大量复用 adapters/opencode/ 与 adapters/claude/，仅路径与 frontmatter 不同）
2. 在 scripts/install.sh 的映射表加分支 （global_prefix_for / project_subdir_for / command_subdir_for）
3. 不支持 skill 的生态：依赖根目录 AGENTS.md（内嵌读写规则摘要）兜底—— 约定层（.agent/ + AGENTS.md）保证最低可用

写入规则（摘录，skill 内为权威）

• 里程碑 → 更新 STATE.md；持久事实 → 追加 MEMORY.md；约定只写 CONVENTIONS.md
• 新计划/todo 一律 .agent/plans/YYYY-MM-DD-主题.md，禁止根目录散落
• 冲突时以 .agent/ 为准，旧产物用 /fusion sync 归并

验证

bash -n scripts/install.sh
./scripts/install.sh --target all --prefix /tmp/at-cfg
./scripts/install.sh --scaffold /tmp/at-proj   # 目标目录需已存在
# e2e：在沙盒项目打开 opencode 或 Claude Code，跑 /fusion status → sync

协议

MIT © 2026 wanxinhao