Codex Workflow Plugin

Local Codex plugin that provides an explicitly triggered, interactive project workflow for medium and large coding tasks. For Chinese requests, generated workflow docs default to Simplified Chinese.

What It Adds

• Plugin: ai-workflow
• Skill: $project-workflow
• Templates: plugins/ai-workflow/assets/templates/docs/ai/
• Guided flow with optional advanced commands: $project-workflow:init through $project-workflow:done

The workflow is intentionally explicit so small one-shot requests stay fast. Use it when a task needs codebase analysis, option comparison, user-selected implementation strategy, todo-by-todo execution, validation, progress tracking, or resumability.

Guided Workflow

Users normally start with one prompt and then reply with short choices such as 1, 继续, 状态, 复查, 验收, or 完成. The long command names remain available for advanced/manual control, but they should not be required after the workflow starts.

1. $project-workflow:init Initializes docs/ai/ and asks whether to create or append AGENTS.md. This does not allow source-code edits.
2. $project-workflow <需求描述> or $project-workflow:plan <需求描述> Reads the repo, writes request docs, proposes options, and stops for user choice.
3. User replies 1, 2, 3, or gives modifications. The AI writes PLAN.md, VERIFICATION.md, PROGRESS.md, and stops before coding.
4. User replies 1, 继续, or 执行. Implements exactly one Todo, adds or updates automated tests for behavior-changing code according to the chosen validation level, runs that Todo's validation, updates progress, and stops.
5. User replies 继续 for the next Todo, or 状态 to inspect progress. Summarizes active and archived requests from docs/ai/STATE.md.
6. User replies review or 复查. Reviews completed code against the plan and writes REVIEW.md without editing source.
7. User replies 验收 or 测试. Generates or updates manual verification guidance without editing product code.
8. User replies 完成 or 归档. Archives the request only after Todos and validation are complete, unless force is explicitly confirmed.

The default mode is manual-gated. Permission to create workflow docs does not imply permission to edit source code. The user can say auto-continue, but the workflow still stops for failed validation, destructive changes, migrations, public API changes, unclear product decisions, or scope changes.

During the workflow, users can give modification feedback at any stop point. The agent should review the impact first, then record it in the right place: current request docs for one-time decisions, VERIFICATION.md for validation changes, and LESSONS.md/BOUNDARIES.md/TESTING.md only for stable reusable project rules.

Behavior-changing code edits have an automated-test gate. The request cannot be normally archived until VERIFICATION.md records the gate as passed, exempted with a reason, or not applicable. Missing test database, test account, API host, or dependency sandbox information is treated as a blocker that should be asked about and recorded in docs/ai/TESTING.md; secrets should stay in local env files or secret stores, not in workflow docs.

During init, the agent must handle the AGENTS.md decision. If both docs/ai/ and AGENTS.md are missing, the recommended option should create both; it must not only ask to generate docs/ai/.

For backend/API/database changes, planning must ask for the validation level instead of silently generating Mockito/mock-only tests: mock/unit, DB/integration, service/API, or a combined strategy. Service/API validation can start the backend or target a configured environment and record request/response evidence in the verification docs.

Generated Request Docs

Each planned request lives under docs/ai/requests/<request-id>/:

• FEATURE_SPEC.md: requirement, scope, assumptions, open questions, and user decisions
• PLAN.md: selected option, option comparison, Todo table, and per-Todo sub-progress
• PROGRESS.md: compact resume snapshot, current Todo, next Todo, changed files, and validation
• VERIFICATION.md: Todo-level validation plan and execution results

These files are the context handoff surface. After a context-window reset, use $project-workflow:status or $project-workflow:exec <request-id> to resume from them.

Guided Replies

At each gate the agent should end with a compact menu, for example:

下一步可选：
1. 继续下一个 Todo
2. 查看状态
3. review 当前代码
4. 暂停

直接回复数字或短句即可。

Installed Paths

• Canonical project: /Users/a111/IdeaProjects/codex-workflow-plugin
• Home plugin symlink: /Users/a111/plugins/ai-workflow
• Marketplace entry: /Users/a111/.agents/plugins/marketplace.json
• Direct skill install, when used: /Users/a111/.codex/skills/project-workflow

Example Prompts

使用 $project-workflow:init 初始化这个仓库的 workflow 文档。

使用 $project-workflow 需求：<需求描述>

1

继续

状态