I Stopped “Just Prompting” and Built a Repeatable AI Workflow

I’ve been experimenting with AI-assisted development for a while, and I already wrote about the idea of using agents for software work.

What changed recently is that the pattern stopped feeling like a clever setup and started feeling like a real workflow.

I’ve been maturing it inside a real project (my-menu), and now I’m using Codex (and sometimes Cursor) to run the same set of agents from .cursor/rules/. The result is simple:

AI is faster now, but more importantly, it’s becoming structured, predictable, and repeatable.

The Core Shift

The big change was moving from: “ask the AI to do a task”

to: “run a stage in a workflow with a clear role, inputs, outputs, and exit gate”

That sounds small, but it changes everything. Instead of hoping the model does the right thing, I give it a job inside a process.

The Pattern I’m Using

In this repo, I defined a stage-gated workflow in workflow/WORKFLOW.md with explicit roles:

• Orchestrator (brief/scope)
• Implementer (code)
• Tester (tests from acceptance criteria)
• Refactorer (structure only)
• Hardener (risk sweep)
• Documenter (decisions/gaps/ops notes)

• Critic (reviews every stage)

  This is the key idea: the Critic reviews every stage before the next one starts. That one rule alone reduces a lot of “AI momentum mistakes” (where something looks good and moves forward too quickly).

Why This Works Better Than a Single “Super Prompt”

Because each agent has:

• a narrow mission
• explicit allowed/not-allowed actions
• a stage exit gate

• required outputs

  Example: the Implementer is explicitly told to stay inside the brief and avoid refactors/optimization. The Tester is explicitly told to derive tests from the brief, not the implementation. The Hardener is explicitly focused on security/perf/observability/resilience.

  That separation makes the outputs more consistent and makes it easier for me to review.

The Most Important File: PROJECT.md

A big maturity improvement was introducing a real project context file (PROJECT.md) and making every agent read it first.

That file became the shared memory for:

• product scope
• architecture
• conventions
• locked decisions
• constraints
• glossary

• current status

  This solved a recurring problem: agents making “reasonable” decisions that were wrong for this project.

  Now the workflow is reusable, but the project behavior is grounded.

The Workflow Produces Artifacts, Not Just Code

Another reason this is working: each stage leaves evidence.

The repo now accumulates useful artifacts like:

• docs/briefs/*.md (scope and acceptance scenarios)
• docs/critique.md (stage review feedback)
• docs/implementation-notes.md (out-of-scope issues spotted during implementation)
• docs/hardening-notes.md (risks, assumptions, deferred items)

• feature delivery docs in docs/*.md

  This creates a lightweight audit trail of how a feature matured, not just the final code diff.

  That matters when working with AI because the real risk is not only bad code, it’s hidden decisions.

What Matured in the Last Few Days

A few things made this feel much more stable recently:

1) Clear role boundaries in .cursor/rules/

Each agent file is now explicit about mission, constraints, and exit gates. This reduced role drift a lot.

2) Critic as a mandatory gate (not optional review)

The Critic is not “nice to have”. It’s the brake pedal.

3) Stage labels and PR progression

The workflow maps stages to PR maturity states, so the process is visible and not just in my head.

4) A Gate Keeper for git/PR hygiene

I added a gatekeeper rule to enforce commit/push/PR updates in the same staged workflow. This is important because process breaks often happen at the VCS/PR layer, not only in coding.

5) Reusability across tools (Codex and Cursor)

The workflow lives in repo files, not in one vendor UI. That means I can run the same pattern with different AI tools and keep the process consistent.

Real Benefit I’m Seeing

The biggest win is not “AI writes more code”.

It’s that I can now pair with the agent in a way that feels closer to working with a junior/mid engineer inside a defined team process:

• I set direction
• the agent executes a stage
• the critic reviews

• we move forward only when the stage is actually done

  This keeps velocity high without turning the project into chaos.

What I’d Recommend If You Want to Try This

Start small and make it boring:

1. Create a PROJECT.md and force every agent to read it first.
2. Split work into stages (brief, implement, test, refactor, harden, document).
3. Give each stage a dedicated role with clear “not allowed” rules.
4. Add a critic/reviewer step between stages.
5. Require written artifacts (briefs, critique, hardening notes), not only code.
6. Treat PR state as part of the workflow, not an afterthought.

Don’t optimize for the smartest prompt. Optimize for a workflow you can run again next week.

Final Thought

AI gets impressive results quickly, but sustainable progress comes from structure.

What I’m building now is less about “autonomous AI” and more about a reliable collaboration system: human direction + role-based agents + stage gates + artifacts.

That combination has been working well for me, and it’s becoming my default way to ship features with AI.

Repo-specific details I used

• Workflow definition: workflow/WORKFLOW.md
• Shared project context pattern: PROJECT.md
• Agent roles:
  • .cursor/rules/orchestrator.mdc
  • .cursor/rules/implementer.mdc
  • .cursor/rules/tester.mdc
  • .cursor/rules/refactorer.mdc
  • .cursor/rules/hardener.mdc
  • .cursor/rules/documenter.mdc
  • .cursor/rules/critic.mdc
• PR/VCS flow guard: .cursor/rules/gatekeeper.md

In my previous post, I introduced my Personal Engineering Operating System — a stage-gated workflow for AI-assisted development.

This post is more practical.

Here’s exactly how a feature moves from idea to merged PR in my setup — including:

• The markdown files created
• The folder structure
• How AI uses those files
• What changes in each stage
• What the final PR looks like

No theory. Just mechanics.

The Repository Structure

Here’s the minimal structure that makes this work:

docs/
  briefs/
    feature-name.md

  engineering/
    personal-engineering-os-v1.md

.ai/
  WORKFLOW.md

.github/
  pull_request_template.md

These files are not just documentation for humans.

They shape AI behaviour.

Stage 0 — Feature Brief Creation

When a new feature starts, the first artifact is:

docs/briefs/daily-mood-logging.md

The brief follows a strict structure:

Feature Brief Template (Annotated)

This document explains what each section in a Stage 0 Feature Brief is for.

The goal of Stage 0 is clarity, not code. This document exists to remove ambiguity before implementation begins.

## Status

Indicates which stage the feature is currently in.

Example:
Stage 0 — Framing

This creates visibility and prevents premature coding.

---

## Alternative name

Optional.

Used to clarify terminology and avoid naming confusion early.
Helps prevent renaming drift during implementation.

---

## Problem

Purpose:
Define the real issue being solved.

This section should:
- Explain the gap in current behavior
- Clarify why the change is needed
- Avoid describing the solution

If this section is unclear, the feature is not ready.

---

## Goal

Purpose:
Define what success looks like.

This should:
- Be concrete
- Be testable
- Avoid future scope creep

If you cannot measure or verify it, it’s not a goal.

---

## Who

Purpose:
Define affected user segments.

This prevents:
- Hidden edge cases
- Partial implementations
- Missed flows

List all user types impacted by the feature.

---

## What We Capture / Change

Purpose:
Clarify data-level changes.

This section should:
- List new fields
- List updated fields
- Clarify storage implications

This helps Stage 1 and Stage 2 later.

---

## Success Criteria

Purpose:
Define the Stage 0 exit conditions.

This should:
- Be written as checkboxes
- Be verifiable
- Map directly to future tests

If these are vague, implementation will drift.

---

## Non-Goals (Out of Scope)

Purpose:
Prevent scope creep.

This is one of the most important sections.

Explicitly state:
- What is NOT included
- What might be future work
- What is intentionally excluded

If it's not here, it’s allowed to creep in later.

---

## Acceptance Scenarios

Purpose:
Translate goals into behavior.

Split into:

### Happy Paths
- Primary successful user flows

### Unhappy Paths
- Validation failures
- API failures
- Edge behaviors
- Retry logic

These become:
- Stage 1 guardrails
- Stage 2 tests

If unhappy paths are missing, refactors will break behavior later.

---

## Edge Cases

Purpose:
Surface unusual but realistic conditions.

Examples:
- Timezones
- Leap years
- Null fields
- Legacy users

This section reduces future surprise.

---

## Approach (Short Rationale)

Purpose:
Outline high-level implementation strategy.

This is not code.

It should:
- Describe DB changes
- Describe routing logic
- Describe flow positioning
- Describe UI intent

This prevents architectural drift in Stage 1.

---

## Decisions (Locked)

Purpose:
Freeze important product/architecture decisions.

Examples:
- Required vs optional
- Editable vs immutable
- Field format decisions
- Explicit flags vs derived state

This prevents re-litigating decisions during implementation.

If a decision changes, Stage 0 must be updated.

---

## Stage 0 Exit Gate

Purpose:
Declare readiness.

Stage 0 is complete when:

- Problem is clear
- Goals are testable
- Non-goals are defined
- Acceptance scenarios include unhappy paths
- Major decisions are locked
- Approach is coherent

No production code is written before this file exists.

Stage 1 — Implementation

Now the AI works strictly within the brief.

It:

• Implements only what’s in scope
• Handles happy + unhappy paths
• Avoids refactoring or optimization

If I notice unrelated issues (for example, another page bug), they are not addressed unless the brief changes.

The PR is opened as Draft during this stage.

Label: stage-1-impl

Stage 2 — Tests

Now we lock behaviour.

Tests are generated directly from:

• Happy paths
• Unhappy paths
• Edge cases listed in the brief

CI must pass.

Label moves to: stage-2-tests

This stage protects against “refactor regret.”

Stage 3 — Refactor

Now that behaviour is protected:

• Improve structure
• Align naming
• Remove duplication
• Tighten types

Tests must remain green.

Label: stage-3-refactor

No behaviour changes are allowed.

Stage 4 — Hardening

This is a risk sweep.

Checklist:

• Security concerns?
• Dependency impact?
• Performance issues?
• Logging sufficient?

If anything risky is found, it’s either fixed or explicitly documented.

Label: stage-4-hardening

Stage 5 — PR Packaging

The final state of the PR includes:

• Clear summary
• Link to the brief
• Screenshots (if UI)
• Risk section
• Rollback plan

The PR template enforces this structure.

Label: ready-for-review

Now it’s safe to merge.

The PR Lifecycle

Here’s how a typical PR progresses:

Draft
  → stage-1-impl
  → stage-2-tests
  → stage-3-refactor
  → stage-4-hardening
  → ready-for-review
  → merge

One PR.
Multiple maturity states.

Not multiple PRs.

What Changed for Me

This workflow:

• Prevents premature optimization
• Reduces scope drift
• Synchronizes AI with human evaluation
• Creates clear checkpoints
• Reduces anxiety
• Improves review quality

The key insight is simple:

AI generates quickly.
Integration requires cadence.

The stages create that cadence.

Final Thought

If you’re experimenting with AI-assisted development, try this:

• Don’t optimize your prompts.
• Optimize your structure.
• Create stage boundaries.
• Define exit gates.
• Use markdown briefs as contracts.
• Let the PR reflect maturity progression.

You don’t need to control the AI.

You need to design the environment it operates in.

The problem wasn’t the AI — it was the absence of structure.

So I introduced a stage-gated workflow — what I now call my Personal Engineering Operating System — and the difference was immediate.

The Problem With Raw AI Speed

AI can generate:

• Hundreds of lines of code in seconds
• Refactors instantly
• Entire test suites on command
• Architectural suggestions continuously

The issue isn’t capability. It’s integration speed. AI can easily outpace your ability to:

• Review
• Reflect
• Evaluate trade-offs
• Protect direction
• Maintain architectural coherence

When AI outruns you, you stop designing and start reacting. That’s when anxiety creeps in.

The Solution: Stage-Gated Development

Instead of letting AI “run,” I introduced stages.

Not Jira stages. Not enterprise bureaucracy. Cognitive stages.

Each stage represents a different thinking mode.

The Six Stages

Stage 0 — Frame the Work

Before writing production code, I define:

• The problem
• Success criteria
• Non-goals
• Happy and unhappy paths
• Risks

Output: a simple Feature Brief in docs/briefs/.

No code is allowed yet. This prevents scope drift and ambiguity.

Stage 1 — Make It Work

Now the goal is simple: make it work.

Focus only on:

• The smallest vertical slice
• Happy path first
• Unhappy paths next
• Basic logging

No refactoring. No optimization. No architectural polishing. Just working behaviour.

Stage 2 — Lock Behaviour With Tests

Once it works, we protect it.

• Characterisation tests (capture current behaviour)
• Intent tests (assert desired behaviour)
• CI must pass

This stage prevents “refactor regret.”

Stage 3 — Refactor and Align

Only after behaviour is protected do we improve structure:

• Simplify flows
• Align naming and patterns
• Tighten types
• Reduce duplication

Behaviour must remain unchanged.

Stage 4 — Harden and De-Risk

Now we look for surprises:

• Security considerations
• Dependency health
• Performance sanity
• Observability

Anything risky must be fixed or explicitly documented.

Stage 5 — PR and Rollout

Finally:

• Clear PR summary
• Evidence (tests, screenshots)
• Risks and rollback plan

The goal is to make it easy to review and safe to ship.

Why This Worked

Three things changed immediately.

1. Less Cognitive Load

I stopped thinking about everything at once. Each stage has a single focus. There’s no mixing of modes.

2. Less Scope Drift

For example, I noticed a small unrelated issue during implementation. Previously, I would have fixed it immediately.

Now, Stage 0 defines scope. If it’s not in the brief, it waits.

That alone reduced distraction significantly.

3. Less Anxiety

Anxiety often comes from:

• Undefined “done”
• Too many simultaneous concerns
• AI moving faster than you

Stages created checkpoints. Exit gates created clarity. I always knew:

• Where we were
• What “done” meant
• What the next micro-step was

Flow became easier.

The Most Important Shift

I didn’t slow the AI down — I synchronized with it.

AI generates. I evaluate. We advance a stage. Repeat.

The structure ensures we follow my path, not the AI’s path.

The Core Principle

AI accelerates execution.
Structure preserves direction.

Raw AI speed feels productive. Structured AI collaboration feels sustainable.

I now optimize for sustainable throughput, not burst velocity.

The Meta-Lesson

The real leverage isn’t better prompts. It’s designing environments where AI behaves predictably.

Once I added:

• A stage-based workflow
• Clear exit gates
• Structured briefs
• PR enforcement

The AI stopped feeling chaotic and started behaving like a disciplined teammate.

Final Thought

If AI-assisted development feels overwhelming, don’t reduce AI usage.

Introduce structure.
Separate thinking modes.
Define exit gates.
Control cadence.

You don’t need to control the AI.

You need to control the environment it operates in.

If you’re experimenting with AI-native engineering workflows, I’d love to compare notes.