Enterprise‑Scale Codex + OpenSpec + Superpowers Workflow: A Step‑by‑Step, Governed AI Development Process

Problem addressed

AI coding often starts generating code without clarified requirements, leading to large unreviewed changes, missing specifications, inconsistent usage across team members, and unclear boundaries when refactoring legacy systems.

Tool responsibilities

Codex : execution engine that reads the codebase, places files according to project structure, runs commands, and enforces rules.

OpenSpec : specification skeleton that defines what to change, why, and how to verify before any code is written.

Superpowers : workflow skill layer that makes Codex brainstorm, plan, execute, and verify.

Key mechanisms

Codex AGENTS.md hierarchy

When Codex starts it reads ~/.codex/AGENTS.md and the nearest AGENTS.md in the current working directory; files closer to the directory have higher priority.

Codex skill mechanism

Skills can be invoked manually or matched automatically. User‑level skills reside in $HOME/.agents/skills.

Superpowers integration

Clone the repository and create a junction to ~/.agents/skills/superpowers, then restart Codex.

git clone https://github.com/obra/superpowers.git "$env:USERPROFILE\.codex\superpowers"
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.agents\skills"
cmd /c mklink /J "$env:USERPROFILE\.agents\skills\superpowers" "$env:USERPROFILE\.codex\superpowers\skills"
# restart Codex

OpenSpec command flow

Fast path: /opsx:propose → /opsx:apply → /opsx:archive Extended flow:

/opsx:new → /opsx:ff or /opsx:continue → /opsx:apply → /opsx:verify → /opsx:archive

Enterprise architecture diagrams

Repository layout example

C:\Users\admin\
├─ .codex\
│  ├─ AGENTS.md
│  └─ superpowers\
├─ .agents\
│  └─ skills\
│      └─ superpowers → C:\Users\admin\.codex\superpowers\skills
├─ architecture-spec\
│  └─ openspec\
│      └─ specs\
│          ├─ api-design\
│          ├─ auth\
│          ├─ gateway\
│          ├─ observability\
│          └─ security\
└─ workspace\
   ├─ user-service\
   │  ├─ AGENTS.md
   │  ├─ openspec\
   │  │  ├─ specs\
   │  │  ├─ changes\
   │  │  └─ config.yaml
   │  ├─ src\
   │  └─ pom.xml
   └─ order-service\
      ├─ AGENTS.md
      ├─ openspec\
      │  ├─ specs\
      │  ├─ changes\
      │  └─ config.yaml
      ├─ src\
      └─ pom.xml

Three‑layer governance rules

Global rules ( ~/.codex/AGENTS.md): small incremental commits, avoid adding dependencies casually, add specs before behavior changes, run Java unit tests first.

Project rules ( AGENTS.md in each repo): must follow OpenSpec, brainstorm complex tasks, plan before execute, enforce strict layering.

Spec rules ( openspec/specs + changes): define system behavior and change boundary.

Installation

Superpowers for Codex

git clone https://github.com/obra/superpowers.git "$env:USERPROFILE\.codex\superpowers"
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.agents\skills"
cmd /c mklink /J "$env:USERPROFILE\.agents\skills\superpowers" "$env:USERPROFILE\.codex\superpowers\skills"
# restart Codex

OpenSpec

npm install -g @fission-ai/openspec@latest
cd <em>project-directory</em>
openspec init
openspec config profile
openspec update

File templates

Global ~/.codex/AGENTS.md

# ~/.codex/AGENTS.md
## 工作约定
- 在更改架构或行为之前，始终先理解当前代码。
- 优先使用小的、可审查、可逆的变更。
- 除非必要，避免引入新的依赖。
- 行为变更前先更新规范。
- 优先遵循现有项目约定。

## Java / Spring 默认规范
- 分层结构：interfaces / application / domain / infrastructure。
- 构造函数注入。
- API 使用明确的请求/响应 DTO。
- 控制器不泄露持久化实体。

## 交付默认规范
- 中等或大型任务在实施前先规划。
- 包含 OpenSpec 时遵循其工作流。
- 任务匹配已安装的技能时使用对应技能。

Project‑level AGENTS.md

# AGENTS.md
## 项目身份
本仓库是一个 Spring Boot 微服务。

## 强制工作流
1. 阅读当前代码和相关模块。
2. 首先创建或更新 OpenSpec 产物。
3. 审查提案/设计/任务的一致性。
4. 以小步骤实施。
5. 通过测试和契约检查进行验证。
6. 代码和规范对齐后归档。

## OpenSpec 规则
- `openspec/specs/` 为基线事实来源。
- `openspec/changes/` 存储增量变更。
- `proposal.md` 说明原因。
- `design.md` 说明技术决策和权衡。
- `tasks.md` 说明执行步骤。
- 行为变更使用增量规范。

## Superpowers 规则
- 在设计前进行头脑风暴。
- 在实施前编写计划。
- 逐步执行计划。
推荐顺序：
- /superpowers:brainstorm
- /superpowers:write-plan
- /superpowers:execute-plan

## 编码约束
- 除非明确允许，否则保持向后兼容性。
- 控制器保持精简。
- 应用层编排用例。
- 领域层拥有业务规则。
- 基础设施层拥有数据库/MQ/RPC 集成。
- 为变更的行为添加测试。

Example demand: mobile phone verification login

Developer commands inside Codex:

Follow the repository's AGENTS.md.
Goal: add mobile phone verification login to user-service.
First brainstorm, then generate OpenSpec proposal/design/tasks/delta spec,
then implement stepwise, add tests, finally verify and provide an archive recommendation.

Rollout cadence

Phase 1 – Individual pilot (1 week)

Install the full toolset.

Initialize OpenSpec on a low‑risk service.

Configure AGENTS.md.

Complete a medium‑size demand and produce installation SOP, template repository, and operation manual.

Phase 2 – Service‑level pilot (2–4 weeks)

Classify demands as small change, regular feature, or complex refactor.

Enforce OpenSpec for designated scenarios.

Use verify as a pre‑merge check; deliver team guidelines, verification checklist, and prompt templates.

Phase 3 – Organization‑wide promotion (1–2 months)

Build a central spec repository.

Accumulate generic domain specs.

Platform maintains global configuration; deliver unified engineering templates, AI development admission standards, and PR acceptance criteria.

Work‑type landing methods

Small changes

No full documentation required.

Behavior‑affecting changes must add a delta spec.

Can use Codex directly while respecting AGENTS.md.

Regular feature development

Must brainstorm first.

Complete proposal, design, and tasks.

Execute according to plan, then verify.

Complex refactor / architecture overhaul

Must brainstorm first.

Design phase involves joint human‑AI review.

Break tasks down to the smallest deliverable.

Verify includes rollback and compatibility checks.

Spring Boot recommended code layering

src/main/java/com/company/userservice/
├─ interfaces/
│  └─ rest/
│      ├─ AuthController.java
│      └─ dto/
├─ application/
│  ├─ service/
│  ├─ command/
│  └─ assembler/
├─ domain/
│  ├─ model/
│  ├─ service/
│  └─ repository/
├─ infrastructure/
│  ├─ persistence/
│  ├─ sms/
│  ├─ token/
│  └─ audit/
└─ config/

Governance and KPI suggestions

Enforced governance rules

Business‑impacting changes must have an OpenSpec delta spec.

Work exceeding half a day should produce tasks first.

Complex tasks require brainstorming before implementation.

PRs must reference the corresponding OpenSpec path.

Merge is allowed only after a verify conclusion.

Trackable KPIs

First‑time implementation pass rate.

Average lines changed per PR.

Defect rollback rate.

Demand delivery cycle.

Proportion of demands with specs.

Verify coverage.

Common pitfalls

Superpowers does not appear in business code; it only changes Codex workflow.

OpenSpec does not slow development; small changes stay lightweight, complex demands follow the full process, reducing rework.

Having Codex does not eliminate architecture governance; stronger rules are needed as AI becomes more capable.

Central spec cannot replace local specs; both are required: central for company standards, local for service boundaries.

Minimal runnable sample commands

# Install superpowers
git clone https://github.com/obra/superpowers.git "$env:USERPROFILE\.codex\superpowers"
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.agents\skills"
cmd /c mklink /J "$env:USERPROFILE\.agents\skills\superpowers" "$env:USERPROFILE\.codex\superpowers\skills"

# Initialize openspec
cd D:\workspace\user-service
npm install -g @fission-ai/openspec@latest
openspec init
openspec config profile
openspec update

Conclusion

The core value of this solution is to make AI‑generated code standardized, controllable, and engineered rather than merely faster.

A reproducible enterprise pipeline is: demand → brainstorm → spec change → stepwise implementation → verify → archive → PR → release.

Reference skill set: https://github.com/SYZ-Coder/superpowers-openspec-team-skills