Agent Workflow

Personal agent workflow layer built on top of OpenSpec, superpowers, gstack, and lessons from oh-my-codex.

Purpose

This repository is the source of truth for shared Claude Code and Codex agent rules.

• AGENTS.md: Codex-facing constitution.
• CLAUDE.md: Claude Code-facing constitution.
• skills/: workflow modules loaded when a task needs specific procedure.
• templates/: reusable state and planning files.
• examples/: routing examples used to validate Patch/Change/Initiative and team decisions.
• scripts/: local install and validation helpers.

Installed copies under ~/.claude and ~/.codex are build targets, not the source of truth.

Architecture

Constitution Layer（宪法层）
  AGENTS.md / CLAUDE.md
  定义优先级、Patch/Change/Initiative 分类、强制入口协议、安全门禁、auto-continue 规则

Spec Layer（规格层）
  OpenSpec
  定义 what / why / contracts / acceptance criteria

Orchestration Layer（编排层）
  skills/orchestration
  吸收 OMX：lane routing、team plan、state gate、concrete signal gate

Execution Layer（执行层）
  superpowers + gstack
  superpowers 负责单 lane 内的 TDD/debug/plan execution
  gstack 负责 QA/review/ship/deploy

Four-Layer Decision Model

Every task starts at the Constitution Layer and flows down:

Layer	Output	OMX Analogy
Constitution	Governance level (Patch/Change/Initiative) + execution shape (solo/team)	$ralplan routing
Spec	proposal.md, design.md, tasks.md	OpenSpec contract
Orchestration	team-plan.md, lane ownership, dependency graph, state file	$team lanes
Execution	code, tests, verification	$ralph single-owner execution

OMX Integration

This project learns from oh-my-codex but does not replicate its runtime:

OMX Concept	Our Approach
$ralplan / $ralph / $team lanes	Mapped to Patch/Change/Initiative + solo/team
keyword registry + pre-execution gate	Concrete Signal Gate in constitution
.omx/ state persistence	.agent/current-task.json
$deep-interview for vague tasks	Initiative → OpenSpec before execution
tmux-based multi-agent runtime	Subagent + worktree (environment-native)
auto-continue except ambiguous/destructive	Default: auto-continue; Exception: explicit user confirmation

Key difference: OMX is a Codex-native runtime. Ours is an orchestration layer that works across Claude Code and Codex, using existing tools (OpenSpec, superpowers, gstack) rather than building a custom runtime.

Getting Started

安装

git clone <this-repo>
cd agent-workflow
./scripts/sync-local.sh   # 安装到 ~/.claude 和 ~/.codex
./scripts/validate.sh     # 验证安装完整性

收到任务时，先分级

每次收到非闲聊任务，在脑中过一遍这个判断：

有具体文件路径/函数名/错误日志吗？
  ├── 没有 → Initiative（先走 OpenSpec 澄清需求）
  └── 有
      ├── 涉及 >5 个文件？跨模块？要改数据库？→ Initiative
      ├── 涉及 1-5 个文件，边界清晰？→ Change
      └── 单文件、单 commit、不改接口？→ Patch

分级不是 AI 替你选——AI 会给出判定依据，但你始终可以 override。

典型工作流：从需求到交付

以 "加一个 compact mode 切换" 为例：

1. AI 判级：Change
   → 输出：治理级别: Change | 执行形态: solo

2. 轻量 OpenSpec
   → 产出 openspec/changes/compact-mode/proposal.md
   → 产出 openspec/changes/compact-mode/tasks.md

3. 编码执行
   → superpowers: TDD → writing-plans → executing-plans

4. 验证
   → gstack: /qa 或 /browse 浏览器验证

5. 交付
   → gstack: /ship（commit + PR）

Patch 跳过步骤 2，Initiative 在步骤 2 之前需要 design.md + /plan-eng-review + APPROVED.md。

什么时候看哪个文件

我想...	看这个
判断治理级别	CLAUDE.md → 任务分级 章节
知道触发词该走哪个 skill	skills/keyword-registry.md
写 proposal / design / tasks	skills/openspec-light/（Change）或 skills/openspec-full/（Initiative）
拆 lane、派 subagent	skills/orchestration/
验证完成条件	skills/verification-gate/
跑自动化检查	scripts/validate.sh
看路由决策示例	tests/routing-cases.yaml
看典型工作流示例	examples/

Known Limitations

• macOS bash 3.2：routing-check.sh 避免使用 declare -A（关联数组）和 grep -P（Perl regex），这些仅 bash 4+ 和 GNU grep 支持
• Keyword Registry 是静态文档：改 CLAUDE.md 后需手动检查 keyword-registry.md 是否需要同步更新
• Subagent 能力边界：当前 lane 派发依赖 Claude Code 的 Agent tool。agent 无法使用 TaskCreate/SendMessage 等 team 原生工具，lane 间通信靠文件传递
• 无 fix loop 自动化：integration 发现 issue 后，退回 owner 修复和 re-verify 是手动流程