TLDR: I have been tinkering with my AI workflow and have landed on a conservative approach that allows me to stay in the loop and maintain a more clear understanding of the codebase.

Over the last few months, I have been tinkering to try to land on an AI workflow that works for me. One of the things I want to avoid is the concept of "vibe coding", which to me, means handing over cognitive control of a feature implementation to AI. While perhaps this does speed up immediate development, I believe that it is detrimental in the long run. Handing over control of a codebase to the AI can eventually lead to "losing control" of the codebase itself.

What do I mean by losing control? I mean that if something ends up breaking, you cannot immediately pinpoint the area of the codebase that lead to the breakage. You have lost full understanding of the system that is running your application and this is dangerous. Imagine an engineer not fully understanding how the bridge he is building will work? Imagine the engineering letting AI handle things such as weak points, whether the bridge can hold up against strong winds and whether or not it will be strong enough to hold the extra load should there be a traffic backup on the bridge. Would you want to cross that bridge? I know I wouldn't.

Granted, most software we work on isn't so important, but as engineers, it's important that we don't lose expertise of our craft.

That being said, I think I've landed on a workflow that I am comfortable with using for now. I am still making tweaks to it, and I think I always will, but it is in a solid enough place that I use it frequently.

It is a combination of AI skills/agents that work together to simulate an engineering team's workflow.

The skills are:

1. Feature Owner: This skill is the "orchestrator" of the workflow. Think of it as the product owner, responsible for helping define the feature, the requirements, and delegating the work among the other agents. It manages the memory of the workflow and keeps track of the progress of the feature.
2. Grill Me: When you first describe the feature you want, the Feature owner agent kicks off this skill to heavily question you regarding the feature. It is designed to make you think about the feature, its requirements and ensure that there is a clear understanding between you and the AI.
3. Feature intake: Once there is a complete shared understanding about the feature, the Feature owner agent kicks off this skill which converts the shared feature understanding into a brief.md document which contains the feature goals, non-goals, and acceptance criteria.
4. Design brief generator: Once the brief is explicitly accepted, the workflow moves on to the design brief generation. This skill takes the shared understanding, the information found in brief.md and generates a design.md document. This document outlines the UI feature requirements such as the primary flow, any UI states, interactions, an accessibility requirements. This design.md document must be explicitly accepted before continuing the workflow.
5. Tech spec generator: At this stage, the technical implementation plan for the feature begins. This skill evaluates the approach from various perspectives, forces a tradeoff discussion, then finally gives its implementation recommendation.
6. Implementation planner: Once the technical spec has been accepted, a plan.md document is created which breaks down the approved technical spec into smaller PR-sized chunks. This ensures that each "chunk", is small enough to enable code-review, rather than attempting to "one-shot" a feature.
7. PR Executor: Once the plan.md is accepted, this agent actually implements a chunk of the plan. After each chunk is completed, the workflow is paused for code review, and explicit approval is required before moving on.

State tracking

This entire workflow requires state tracking to ensure that the workflow is progressing as expected, can be picked up after leaving it and ensures that no context is lost. As described above, the following documents are created per workflow:

• brief.md
• design.md
• tech-spec.md
• plan.md
• status.yaml

While the .md files contain information about different aspects of the plan, the status.yaml is the actual "state memory". The document is outlined as follows:

feature: "<human readable feature name>"
slug: "<feature-slug>"
state: "<current state step>"
shared_understanding_summary: ""
current_chunk: ""
completed_chunks: []
open_questions: []
blockers: []
artifacts:
  brief: "./docs/features/<feature-slug>/brief.md"
  design: "./docs/features/<feature-slug>/design.md"
  tech_spec: "./docs/features/<feature-slug>/tech-spec.md"
  plan: "./docs/features/<feature-slug>/plan.md"
last_completed_step: ""
next_step: ""
updated_at: "<ISO-8601 timestamp>"

Overall, this approach is fairly conservative, but it helps keep me in the loop and allows me to keep full control and understanding of the features that the AI develops.