Introduction

AI-assisted development is easy to start but difficult to make reliable. A single prompt can generate code quickly, but production engineering requires much more than code generation: clear requirements, reviewable plans, scoped tasks, repeatable tests, human approval, and delivery artifacts that other engineers can understand.

I spent a significant amount of time building a local spec-driven AI development workflow to solve this problem. The goal was not to let AI freely modify a codebase. The goal was to make AI-assisted implementation structured, reviewable, and safe enough to use inside real engineering work.

The Problem

Most AI coding workflows start from a request such as:

implement ISSUE-1234

or:

implement retry-safe data sync

That looks simple, but the hidden complexity appears immediately:

• What exactly is the requirement?
• Which behavior already exists?
• What should be changed and what should remain untouched?
• What tests prove the change is correct?
• Which edge cases need adversarial review?
• How do we keep humans in control of important decisions?

Without guardrails, AI coding can produce a lot of code quickly, but it can also create unclear diffs, skipped assumptions, weak tests, and implementation decisions that are hard to review.

The Goal

The workflow I wanted had a different shape:

request → spec → plan → tasks → implementation → review → fixes → tests → delivery

The important part is that implementation does not start immediately. The workflow first turns the request into a specification, then into an execution plan, then into concrete tasks. Human approval gates exist between these stages so that engineers can review the direction before code changes happen.

Machine Bootstrap

The first part of the system is machine-level setup. A local CLI verifies that the required tools are available and prepares the development environment.

The bootstrap checks for common command-line dependencies such as:

• shell runtime
• Git
• HTTP download tooling
• AI development CLI
• multi-agent orchestration runtime
• terminal session manager

The goal is to make the workflow reproducible across machines. If a required tool is missing, the setup can either report it or install it where supported. This avoids a class of failures where the AI workflow behaves differently depending on a developer's local environment.

Repository Bootstrap

The second part is repository-level setup. A repository needs its own workflow files so that the AI session can understand how implementation should proceed inside that project.

The repository bootstrap installs local command definitions and metadata such as:

.workflow.json
.commands/workflow.implement.md
.commands/workflow.team-run.md
.commands/workflow.attack.md
.commands/workflow.fix.md
.commands/workflow.delivery.md
.specify/memory/constitution.md

The exact file names are less important than the principle: the workflow should be repo-local. The rules for a backend service, frontend application, library, and infrastructure repository are not the same. Keeping workflow metadata inside the repository makes the behavior explicit and reviewable.

The Project Constitution

One of the most useful parts of the system is the project constitution. It defines engineering guardrails for the repository.

Examples of guardrails include:

• preferred architecture boundaries
• testing expectations
• migration safety rules
• idempotency requirements
• error-handling conventions
• dependency rules
• security expectations

Without a constitution, AI agents fall back to generic coding behavior. With one, the workflow has a source of truth for how this specific project should be modified.

Forward Implementation Flow

The main workflow is used for new work. It starts from an issue identifier or a freeform request:

implement ISSUE-1234
implement retry-safe background sync

The lifecycle looks like this:

1. request intake
2. repository context review
3. spec generation
4. clarification if needed
5. spec approval
6. plan generation
7. plan approval
8. task generation
9. task approval
10. implementation
11. adversarial review
12. remediation
13. test execution
14. delivery summary

The approval gates are intentional. They prevent the workflow from turning a vague request into a large unreviewed diff.

Brownfield Reverse-Spec

Existing systems often have behavior that is not fully documented. For that case, I added a reverse-spec path.

Instead of starting with a new requirement, the workflow starts by inspecting the current codebase:

document existing background sync flow

or:

reverse spec current webhook retry behavior

The output is not a separate document family. It becomes the same canonical specification artifact used by the forward implementation flow. This is useful before refactoring legacy behavior because it creates a current-state baseline before any change is planned.

Why Approval Gates Matter

Autonomous implementation sounds attractive, but engineering work often fails at the boundaries: ambiguous requirements, hidden state transitions, migration risk, idempotency, and missing tests.

Approval gates force the workflow to pause at the moments where human judgment matters most:

approve spec
approve plan
approve tasks

After approval, the system can continue with implementation, review, fixes, and tests. This keeps the AI useful without letting it silently decide the shape of the work.

Adversarial Review

A key stage is adversarial review. Instead of only asking whether the code works, the workflow asks what could break:

• race conditions
• broken idempotency
• inconsistent state transitions
• missing authorization checks
• partial failure behavior
• retry edge cases
• test gaps

This review stage is deliberately harsh. The goal is not to praise the implementation. The goal is to find the problems before production does.

Authentication and Security Model

The workflow integrates with external systems such as issue trackers, Git providers, and documentation workspaces. For that reason, authentication needed to be explicit and safe.

The design avoids raw long-lived tokens where possible and relies on OAuth-based integrations. Sensitive local files are created with restrictive permissions, and configuration parsing avoids unsafe shell evaluation.

The security principles are simple:

• do not evaluate environment files as shell scripts
• allow only known managed variables
• keep sensitive files owner-only
• verify downloaded binaries where applicable
• make installation paths visible through symlinks
• separate diagnostic checks from strict validation gates

Readiness Checks

The workflow includes two types of checks:

Diagnostic mode explains what is missing without blocking development. It is useful during setup and troubleshooting.

Strict validation fails if prerequisites are missing. This is useful before running a workflow or as a CI-style gate.

Both checks inspect the machine environment, repository bootstrap files, authentication configuration, and workflow metadata.

What Worked Well

• Keeping workflow commands repo-local made behavior easier to reason about.
• Using a constitution gave AI agents project-specific constraints.
• Approval gates prevented vague requests from turning into uncontrolled implementation.
• Reverse-spec helped with legacy systems where the code was the only reliable source of truth.
• Adversarial review caught issues that a normal happy-path implementation pass would miss.

What Was Hard

The hardest part was not generating code. The hardest part was designing the boundaries around generation.

A useful AI workflow needs to answer questions like:

• When should the agent stop and ask?
• Which artifacts are canonical?
• How does the workflow resume after approval?
• How should broad tasks be split across agents?
• How do we prevent implementation from drifting away from the spec?
• How do we make the final output reviewable by humans?

These are workflow design problems more than coding problems.

Lessons Learned

1. AI Needs Source-of-Truth Artifacts

Prompts are not enough. The workflow needs durable artifacts such as specs, plans, task lists, and constitution files. These artifacts make the work reviewable and resumable.

2. Guardrails Are More Important Than Speed

Fast implementation is only useful if the result is correct. Approval gates, tests, and adversarial review slow the workflow down slightly, but they prevent expensive mistakes.

3. Brownfield Work Needs a Baseline

When modifying existing systems, the first step is often documenting what already exists. Reverse-spec turned out to be essential for safe refactoring.

4. Human Ownership Must Stay Explicit

AI can draft specs, propose plans, implement code, and review changes. But engineers still own the final decision: what gets merged, what risks are acceptable, and whether the behavior is correct.

Conclusion

Building this workflow took much longer than simply wiring an AI coding assistant into a repository. But that was the point. The hard part of AI-assisted engineering is not making AI write code. The hard part is making the work structured enough that humans can trust, review, and maintain it.

The final system is built around a simple idea:

AI can accelerate implementation, but engineering judgment must control the workflow.

That means specs before code, plans before tasks, review before merge, and clear ownership at every stage.