Polished feature development workflow with Mermaid diagram

feature-development-workflow.md

Feature Development Workflow

Keep main stable. Treat feature branches as the default path for any meaningful change.

Core Rules

1. Create a feature branch before starting implementation work.
2. Use the codex/ prefix when it fits the task, such as codex/add-spectator-delay.
3. Keep a todo.md updated while the work is in progress.
4. Stay on the branch that matches the current task.
5. Do not mix unrelated work on the same branch.
6. Before switching branches, commit or stash your work and make sure the working tree is clean.
7. If you are handling multiple tasks in parallel, keep one task per branch and prefer separate worktrees when practical.
8. Make sure the thread is associated with the active feature branch before committing.
9. Never commit directly to main unless that is explicitly requested.
10. Keep branches small, focused, and easy to review.
11. Rebase or merge from main regularly if the branch lives for more than a short burst of work.
12. Run relevant tests and checks before committing.
13. Commit and push only after the change has been validated.
14. Merge only after the branch is in a good state.

Practical Flow

Start

• Create or switch to the correct feature branch.
• Confirm the branch name reflects a single purpose.
• Open or update todo.md with the work you plan to do.

While Working

• Keep implementation scoped to the branch's purpose.
• Avoid carrying unrelated edits forward.
• Use a separate worktree when two active tasks would otherwise collide.

Before Switching Branches

• Commit or stash current work.
• Confirm git status is clean.
• Switch only after the current branch is in a safe stopping state.

Before Commit

• Confirm the thread is attached to the active branch.
• Run the relevant tests, checks, or validation steps.
• Review the diff to make sure the branch stayed focused.

Before Merge

• Pull in fresh main changes if needed.
• Re-run the important checks.
• Merge only when the branch is valid, tested, and still single-purpose.

Decision Diagram

flowchart TD
    A["Start<br/>New Feature or Meaningful Change"] --> B["Create a Feature Branch"]
    B --> C["Use a <code>codex/...</code> Name When Appropriate"]
    C --> D["Reference <code>todo.md</code>"]
    D --> E["Stay on the Branch for This Task"]

    E --> F{"Switching Branches?"}
    F -- Yes --> G["Commit or Stash Current Work"]
    G --> H["Make Sure the Working Tree Is Clean"]
    H --> I["Switch Branches Safely"]
    F -- No --> J["Continue Implementation"]

    I --> J
    J --> K{"Working on Multiple Tasks?"}
    K -- Yes --> L["Keep One Task per Branch"]
    L --> M["Use Separate Worktrees When Practical"]
    K -- No --> N["Proceed on Current Branch"]

    M --> O["Ensure the Thread Matches the Active Branch"]
    N --> O

    O --> P["Implement the Change"]
    P --> Q["Run Tests and Checks"]
    Q --> R{"Do Checks Pass?"}

    R -- No --> P
    R -- Yes --> S["Commit and Push"]

    S --> T["Keep the Branch Small and Focused"]
    T --> U["Rebase or Merge from <code>main</code> Regularly"]

    U --> V{"Is the Change Valid?"}
    V -- No --> P
    V -- Yes --> W["Merge into <code>main</code>"]

    W --> X["Finish<br/><code>main</code> Stays Stable"]

    classDef start fill:#e8f7ee,stroke:#2f855a,stroke-width:2px,color:#163a24;
    classDef action fill:#f7fafc,stroke:#4a5568,stroke-width:1.5px,color:#1a202c;
    classDef decision fill:#fff7e6,stroke:#c05621,stroke-width:2px,color:#5a2d0c;
    classDef terminal fill:#ebf8ff,stroke:#2b6cb0,stroke-width:2px,color:#153e75;

    class A start;
    class B,C,D,E,G,H,I,J,L,M,N,O,P,Q,S,T,U,W action;
    class F,K,R,V decision;
    class X terminal;

Loading

Goal

Use feature branches by default so main stays stable, changes stay reviewable, and rollback stays simple.