# Codex Standard workflow

> Codex: Six stages from requirements to delivery: understand, plan, implement, test, review and commit.

URL: https://docs.passion8.cc/en/docs/codex/workflow
Language: en
Publisher: Passion8

A reliable collaboration loop is **understand → plan → make focused changes → test → review → commit**. Each stage should produce something reviewable so failures can be located precisely.

## The six stages

| Stage | Purpose |
| --- | --- |
| 1. Clarify requirements | Turn a vague request into concrete behavior and boundaries |
| 2. Plan | Identify changes before editing |
| 3. Implement in small steps | Keep each change understandable and reversible |
| 4. Test | Demonstrate behavior with actual results |
| 5. Review | Inspect correctness and introduced risks |
| 6. Commit and reflect | Save the result and retain useful lessons |

---







### Clarify requirements

**Goal: turn “improve the homepage” into an actionable task.**

Describe:

- **Background:** what the project is and why the change matters.
- **Specific problem:** desired scope and exclusions.
- **Relevant files:** likely files to inspect before editing.
- **Protected areas:** behavior that must remain intact.
- **Completion criteria:** observable results.
- **Risks:** potential side effects.

```text
Analyze the requirements before changing code.

Request: [describe the request]

Explain:
1. Project background and reason for the change.
2. Concrete problem, intended scope and exclusions.
3. Likely relevant files; list them without editing yet.
4. Behavior that must not change.
5. Completion criteria.
6. Required tests.
7. Potential risks.

Finish with a short implementation recommendation.
```





### Plan

**Goal: align direction before implementation.**

```text
Do not write code or change files yet.
Prepare a change plan based on the requirements and repository structure.
Wait for my confirmation before implementing this plan.
```




Use /plan for complex work. Adjust supported reasoning effort with /model when deeper investigation is needed.








### Implement in small steps

**Goal: implement one coherent feature at a time.**

Set clear boundaries:

- Change only files required for this feature.
- Avoid unrelated refactors, directory rearrangement or global settings.
- Record optional improvements as suggestions.
- Clarify material uncertainties before dependent work.

```text
Implement step [N]: [feature name].

Requirements:
- Change only files needed for this feature.
- Do not refactor unrelated code.
- Do not add unnecessary dependencies.
- Preserve existing features.

When complete, report:
- Changed files and the reason for each change.
- Any work outside the plan.
- Risks or limitations.
- Recommended next step.
```





### Test

**Goal: prove behavior with results, not a completion claim.**

Start with focused checks and broaden where relevant:

| Check | Command or action |
| --- | --- |
| Unit tests | The project's relevant test command, such as npm test |
| Types | tsc --noEmit where applicable |
| Lint | npm run lint; distinguish new failures from existing ones |
| Build | npm run build; successful packaging alone does not prove deployability |
| Manual verification | Relevant UI, forms, authentication or payment flow |
| Browser inspection | Console, network and mobile layout |
| Regression | Confirm existing behavior still works |




Regression checks are easy to omit and often reveal the problems that otherwise appear after release.




Before manual testing, ask for an action/expected-result table and verify it against the application.





### Review

**Goal: confirm that passing tests correspond to the intended change.**

Use two passes:

**Agent review:** report unplanned files, unrelated refactoring, dependencies, deleted behavior, hard-coded values and risks.

**Human diff review:** concentrate on:

- **Edge cases:** empty data, failed requests, missing authentication, denied access and repeated clicks.
- **Security:** exposed credentials, missing authorization, unvalidated input and API authentication.
- **Deletions:** removed components, fallbacks or configuration that may still be required.
- **Business logic:** working code can still calculate the wrong price or open the wrong page.

```text
Review this change without writing more code.

Check:
1. Unplanned files, unrelated refactoring, dependencies and hard-coded values.
2. Whether the implementation matches the agreed scope.
3. Edge-case coverage.
4. Security.
5. Deletions: what, why and any remaining dependencies.
6. Business correctness.

Conclude: ready to continue / small fixes needed / partial rollback / replan.
Review only; do not edit files.
```




For authentication, payments, permissions or database changes, a second independent reviewer can provide useful cross-checking.








### Commit and reflect

**Goal: save the verified result and useful project knowledge.**

- After tests and review, commit/push according to the repository workflow and open a PR when appropriate.
- Update AGENTS.md with durable project conventions and lessons.
- The agent executes work; the owner reviews decisions and delivery.




AGENTS.md is useful for persistent project rules. Record concrete conventions so the next task does not need to rediscover them. See [Advanced usage](https://docs.passion8.cc/en/docs/codex/tips).