Rami Afif AI Development Workflow v2.6

1. Why I Created This Workflow

AI coding tools are genuinely fast. They can generate an API endpoint, a database migration, a frontend component, or a test suite in seconds. That speed is real and it matters. But speed alone does not make software correct, secure, maintainable, or aligned with what was actually required.

The gap between what AI generates quickly and what a production system needs is where problems accumulate. I built this workflow to close that gap with specific, named controls rather than general caution.

Risks this workflow was built to address

• Implementing from assumptions rather than repository evidence. An AI reasoning from training data or a summary rather than reading the actual codebase produces plausible-looking code that conflicts with the existing architecture, naming conventions, or constraints.
• An AI approving its own work. An AI implementer that also reviews its own output cannot provide independent verification. Self-review is not review — it is a systematic blind spot.
• Silent scope or architecture changes. An AI may quietly expand scope, introduce new dependencies, or change architectural decisions during implementation without surfacing those decisions for human review.
• Tests that pass without proving the requirement. A green test suite confirms that the code does what the tests test. It does not confirm that the tests test what the requirement actually specified.
• Material correction plans that are not technically challenged. A reviewer proposes fixes. Those fixes may themselves introduce errors, miss edge cases, or conflict with constraints the reviewer did not fully examine.
• Repository actions occurring before human review. Staging, committing, pushing, or deploying before a human has reviewed and approved the implementation creates facts that are difficult to reverse cleanly. Every such gate is made explicit in this workflow.
• Repeated mistakes across later packets. Without a systematic learning loop, the same class of error recurs in every subsequent development packet.

These are not theoretical risks. They are patterns that emerge when AI tools are used without a governance structure. This workflow addresses each one with a named mechanism.

2. Core Operating Model

The workflow defines clear roles for each participant. Role clarity is what prevents the most common failure mode: one participant effectively doing the job of another, or no participant clearly owning a critical function.

Read-only specialist participants — focused on specific questions such as security analysis, schema review, or performance assessment — may be introduced where useful, with scope limited to analysis and reporting.

This principle applies to every gate in the workflow. The implementer does not authorize the implementation. The reviewer does not authorize corrections without challenge. The architect does not authorize plans without human approval. Every authorization action belongs to the Human Owner.

3. The Architect–Implementer Challenge Protocol

Before any implementation begins, the implementer (Claude Code) reads the proposed plan from the architect (ChatGPT) and formally evaluates it against the actual repository state. This is not a courtesy review — it is a structured technical challenge with four possible outcomes.

An important distinction: ACCEPT is not implementation authorization. Even a clean ACCEPT status means only that the plan passed technical challenge. Implementation still requires a separate, explicit authorization step from the Human Owner.

This separation ensures that a technically sound plan does not automatically become an instruction to proceed. The human controls the gap between “the plan is valid” and “build it.”

4. Iterative Revised-Plan Re-Challenge Loop

When a CHALLENGE status is returned, the architect revises the plan to address the identified concerns. The revised plan is then submitted for another challenge evaluation — not assumed to be acceptable simply because earlier concerns were addressed.

This process can run through second, third, fourth, or later rounds. There is no assumption that concerns will be fully resolved in one revision. The loop continues until the plan receives ACCEPT or ACCEPT WITH MINOR NOTES, or the Human Owner decides to restructure the work differently.

The practical effect of this loop is that rushed, under-specified, or architecturally unsafe plans cannot be pushed through by iteration count alone. Each revised plan is evaluated on its own merits against the current repository state.

A BLOCK status during any round of the re-challenge loop requires resolution of the blocking condition before the loop continues. It does not pass around the block — it halts until the pre-condition is met.

5. Small, Reviewable Development Packets

Implementation work is divided into discrete, narrowly scoped packets. Each packet carries an explicit objective, a defined scope, stated non-goals, acceptance criteria, a verification plan, and stop conditions.

• Narrow objective. A packet addresses one clearly bounded change — not “improve the API” but “add endpoint X with behavior Y and test coverage Z.”
• Explicit scope. The packet lists which files are expected to change and which are explicitly not in scope. Any deviation from the expected file impact requires a challenge before proceeding.
• Non-goals. What the packet intentionally excludes is as important as what it includes. Non-goals prevent scope expansion during implementation.
• Acceptance criteria. Specific, verifiable conditions that determine whether the packet is complete — not vague (“it should work”) but specific (“the endpoint returns 200 with the correct schema for a valid input and 422 when the required field is missing”).
• Verification plan. How the implementation will be confirmed — automated tests, manual verification steps, or both — decided before implementation begins.
• Stop conditions. Conditions under which the implementer must halt and report rather than continue. These prevent silent failure modes where an implementer continues past a pre-condition failure.

Small packets make independent review tractable. A 200-line diff with a clear objective can be meaningfully reviewed. A 2,000-line diff across 30 files cannot — and any review of it will inevitably miss something material.

6. Requirement-to-Test Traceability

Every material requirement in a packet should have a traceable path from the stated requirement through the code that implements it to the test or verification step that confirms it, and on to the actual result.

This is not about comprehensive test coverage as a metric. It is about being able to answer a specific question for any material requirement: How do we know this was implemented correctly?

• Code paths. Which functions, endpoints, or components implement this requirement?
• Automated tests. Which tests exercise those code paths and verify the specified behavior?
• Manual tests where required. For behaviors that cannot be fully automated — UI interactions, microphone input, local hardware behavior — manual verification steps are written out and executed explicitly.
• Actual results. What did the verification produce? Not what was expected — what actually happened.

Traceability makes the difference between a claim and evidence. “This feature works” is a claim. “Requirement: endpoint returns 401 when the token is expired. Test: test_expired_token_returns_401. Result: pass, commit abc1234.” is evidence.

7. Implementation Visibility and Transparency

Silence during implementation is acceptable — the implementer should work without unnecessary narration. Silence at the end of implementation is not. Every packet concludes with a complete implementation report before any authorization gate is triggered.

The implementation report covers three phases:

• Before editing: The expected file impact — which files will be created, modified, or deleted — is declared before the first edit. Any deviation from this declaration requires a challenge before continuing.
• During longer work: Milestone visibility at natural stopping points. For a packet spanning multiple tasks, progress is reported after each task completes rather than only at the very end.
• After completion: The complete evidence package — exact changed-file list, diff summary, verification commands and results, and confirmation that each stop condition was checked.

This structure ensures the Human Owner and the independent reviewer have everything needed to make an informed approval decision. An implementation summary that says “done” without evidence is not an implementation report — it is a claim.

8. Independent Review of the Actual Diff

After implementation, ChatGPT reviews the actual code diff — not the implementer’s description of it. This distinction is critical.

An implementation summary describes what the implementer intended to do and believes it did. A code diff shows what was actually changed. These are not always the same. A reviewer reading only the summary cannot catch cases where the implementation diverged from the plan, where side-effects were introduced, or where correctness depends on an assumption the implementer did not surface.

A green test suite is also not a substitute for diff review. Tests confirm the code satisfies the tests. They cannot detect that the tests are wrong, incomplete, or testing the wrong thing. Independent diff review can.

The reviewer’s output is a structured set of findings categorized by type and severity. Material findings become the input to the post-implementation challenge gate.

9. Post-Implementation Reviewer–Implementer Challenge Gate

When the independent reviewer identifies material findings, the proposed corrections do not go directly to the implementer for execution. Claude Code first reviews the proposed corrections in read-only mode and formally challenges them before any correction edits are authorized.

This challenge evaluates proposed corrections for:

• Correctness — does the proposed fix actually resolve the identified problem?
• Completeness — are there edge cases the correction misses?
• Side-effects — does the correction introduce new issues?
• Repository compatibility — is the proposed correction consistent with the actual codebase?

The four challenge statuses (ACCEPT, ACCEPT WITH MINOR NOTES, CHALLENGE, BLOCK) apply here as they do to architect plans. A challenged correction is returned to the reviewer for revision. A blocked correction requires pre-condition resolution before any edit proceeds.

This gate applies the same principle as the initial challenge: the entity proposing a change cannot also be the entity that confirms it is safe to apply.

10. Separate Human Approval Gates

Each material action in the development lifecycle has its own explicit approval gate. These gates do not inherit authorization from earlier gates. An approval to implement does not authorize staging. An approval to stage does not authorize push.

This granularity is intentional. Combining gates creates authorization drift — a situation where it becomes unclear what was actually approved and by whom. Keeping gates separate keeps accountability clear and prevents an implementer from treating a broad authorization as a blanket permission for all downstream actions.

11. Controlled Workflow Learning Loop

After each completed packet, the Human Owner reviews the experience for lessons. If a class of mistake recurred, the workflow produces a specific response calibrated to that mistake.

Possible responses include:

• Improved challenge questions added to the Architect–Implementer Challenge Protocol to catch this class of issue earlier.
• New automated tests that would have caught the error during verification.
• Revised packet structures with more explicit acceptance criteria or stop conditions.
• Hook or CI check additions that enforce a previously manual control automatically.
• Rule updates added to the implementer’s working guidelines for the project.

The critical constraint of the learning loop: the workflow does not rewrite itself automatically. No AI participant proposes changes to the workflow governance structure without Human Owner review and explicit authorization. The workflow is the control structure — it cannot be modified by the entities it controls.

12. Real Project Application

This workflow has been applied in practice across two active projects. The following summaries describe each project at a general level.

13. Authorship and Scope

14. Complete Workflow

This article covers the core principles and mechanisms. The complete versioned workflow, including protocol definitions, governance rules, approval gates, and lifecycle controls, is maintained publicly on GitHub.

15. Open to Remote Opportunities

I am available for remote roles where I can bring this kind of structured, human-governed approach to AI-assisted engineering into a team environment.