Adopting an Agentic Software Development Workflow

This is an agentic workflow for building software from idea to launch, and a guide for adopting it in your own project.

Each step in the workflow produces one or more artifacts, each a markdown file under its output path. Steps move from higher abstraction to lower. The input and output paths define the dependencies between steps: requirements always flow from the top. When two artifacts disagree, the upstream one is authoritative. Either step back and revise the upstream artifact, or align the downstream artifact with it. After each step, a checkpoint agent analyzes the artifact just produced and proposes a plan: move forward, or step back and refine an earlier step. A human approves the plan before work proceeds. Each step lists a done when check that the checkpoint agent verifies before proposing to move forward.

The linked structure exists to make every change a navigation problem instead of a search problem. The artifacts form a tree, or a forest of trees, from vision down to code. Input paths, output paths, and the component map are its edges. Each level is one well-defined abstraction, small enough to hold in a single context. An agent or a human working a task doesn't search the repository for context. They start at the vision and follow the edges down to the branches that matter, stopping at the smallest set of artifacts that holds what the task needs. Understanding a feature works this way; so does changing one: descend to the subtrees it touches, decide which need updating, and let the change ripple down to their children. That is the intent behind the whole design: smaller contexts, lower token cost, more accurate changes, and software that stays maintainable as it grows.

The next section covers adopting the workflow: scaffolding it into your repository and running it there. The sections after that describe the machinery that makes it work (an orchestrator session, the checkpoint between steps, a state file, and the scoping rule that decides which steps a change activates), followed by the full set of steps, from vision to launch.

Adopting this agentic workflow in your own project

To use this workflow in your own repository, hand this post to an agent and have it build the machinery described below. The steps:

Scaffold from this post. Open an agent session (Claude Code or similar) in your project repository. Give it this post's URL and ask it to fetch the post and scaffold the workflow it describes. The scaffold is three things: docs/workflow-state.md with every step not-started, one step file per step under a workflow directory, and the orchestrator instructions in the file your agent tooling loads at session start (for Claude Code, CLAUDE.md).
Check the step files. Each step file must capture that step's job, input paths, output path, and done-when check from this post. Keep step files portable markdown so they work across agent tools. Per-tool configuration (skills, agent definitions) should be a thin shim that points at them. The step files are the contract; review them before running anything.
Seed existing work, if any. For a project that already has code, don't start from an empty step 1. Have the agent reverse-engineer the upstream artifacts from what exists: vision, actors, components, data. Review them, mark them approved in the state file, and enter the workflow at the first step where reality and artifacts disagree.
Run the loop. Run the orchestrator loop described in "Running the workflow" below. Scope the first pass to the smallest launchable product. Everything else is a later iteration that re-enters at step 1.
Refine as you go. The first run exposes gaps in the step files. Fix the step file, not just the artifact, so the next run inherits the correction. The workflow improves the same way the product does: a problem found downstream is fixed upstream.

Running the workflow

The workflow has no engine. Files are its memory, git is its history, subagents do the work, and an orchestrator session schedules them.

Each step in the workflow becomes a step file, loadable as a skill: the step's job, input paths, output path, and done-when check. A step runs as a subagent that starts with an empty context and receives two things: the step file, and the instruction to read only that step's input paths. Its deliverable is the artifacts it writes to the step's output path. The summary it returns is not the deliverable.

The orchestrator is the long-lived session where the human sits. It does no step work itself. Its loop is small: read the state file, spawn the next step's subagent, spawn the checkpoint subagent on the result, present the plan to the human, record the decision, commit. Because the heavy work happens in subagents, the orchestrator's context stays small across many steps. Subagents never talk to the human. All judgment flows through the orchestrator.

One full cycle: the orchestrator reads the state file and sees step 3 is next. It spawns the step 3 subagent with the step file and its input paths. The subagent writes docs/components/ and exits. The orchestrator spawns the checkpoint subagent, which verifies the done-when and proposes a plan: advance, or step back with evidence. The human approves, rejects with feedback, or directs a step back. On approval, the orchestrator updates the state file, commits, and moves to step 4. On rejection, the step subagent re-runs with the critique appended.

The checkpoint between steps

After each step, the checkpoint subagent asks one question: is this good enough to build on, or does it expose a problem upstream? An awkward test suite often means the design underneath is unclear. A design that resists becoming concrete often means the vision above left something unresolved. Stepping back costs less than building three more layers on a bad foundation.

When a step is revised, the orchestrator doesn't re-check the whole workflow in one pass. It runs a walk-forward re-check: one downstream step at a time, each as its own sub-task scoped only to that step's input paths plus the change. The sub-task reports whether the change affects it. If not, the walk stops there: nothing past that point depends on what changed, so there's nothing to re-check. If it does, that step is revisited before moving to the next. Each check runs in a small context, and most changes should stop propagating within a step or two of where they started.

Maintaining the state file

docs/workflow-state.md is the single source of truth for where the workflow stands. Every session, human or agent, starts by reading it. It reconstructs the workflow's position without re-reading any artifact: which steps are trusted, which is in flight, which don't exist yet.

| step | name       | status      | approved at (git sha) |
|------|------------|-------------|-----------------------|
| 1    | vision     | approved    | a3f9c12               |
| 2    | ux         | approved    | 8b21e07               |
| 3    | components | in-progress | -                     |
| 4    | data       | not-started | -                     |

## Decision log
- 2026-07-15: checkpoint after step 3 flagged a missing admin actor.
  Stepped back to step 2, revised, re-approved.

The maintenance rules:

Only the orchestrator writes the state file, and only at a checkpoint decision. Step subagents never touch it.
Each step's status is one of: not-started, in-progress, approved, invalidated.
On approval, the orchestrator commits the step's artifacts and the state file together, and records that commit's sha in the step's row.
When an upstream step is revised, the walk-forward re-check marks each affected downstream step invalidated. An invalidated step must be re-approved before work continues past it.
Every checkpoint decision, including rejections and step-backs, gets one line in the decision log with the date and the reason.

The recorded shas make the re-check concrete. When step 2 is revised, git diff 8b21e07..HEAD -- docs/ux/ is exactly what changed. Each downstream check receives that diff plus its own input paths, in a fresh context, and reports whether the change affects it.

Scoping a change

Not every change runs all sixteen steps. The input and output paths form a dependency graph, and the orchestrator scopes each change against it before any work starts. A change enters by naming the artifacts it would alter. The orchestrator walks upstream first and enters at the most upstream step whose artifact the change contradicts or extends. A pure implementation fix enters at step 13. A new actor enters at step 2. From the entry step, the change flows downstream through the walk-forward re-check until it stops propagating. Steps outside that path keep their approved status and their recorded shas. Dormant steps still bind: their artifacts remain authoritative inputs for the steps that do run.

The rule recurses into the code. Each component in docs/components/ names the source path that implements it, so a change confined to one component activates only that component's code and tests. The walk between components follows the API contracts that step 3 owns: if a component's contract is unchanged, its dependents are unaffected and the walk stops there. Step 13 never needs the whole codebase in context. A code subagent receives the component's doc, its named source path, and the contracts of its neighbors, nothing else.

The proposed scope is a checkpoint decision like any other. The human approves the entry step before work starts, and the decision gets a line in the decision log.

The skills named in each step below are hypothetical for now. Develop them as needed when you run the workflow.

Part A: Document the intent, goals, and design

Discovery, market validation, and vision. What the system is for. The motivation, the intent, the problem it solves, and the value it provides. Feature priorities and KPIs. Include NFRs at this abstraction level.
- input path: NA. This is the highest level.
- output path: docs/vision/
- skills: vision, market-research
- done when: The problem, the value provided, feature priorities, and KPIs are each stated in one place. No unresolved TODOs.
User and actor design. Who interacts with the system, and how. The experience each actor has, and how the system responds. UX and accessibility requirements for every human-facing surface: interaction flows, visual design, WCAG conformance. This layer owns the view models: the data each actor sees and submits. Threat model the actor boundary: authentication, authorization, input validation, abuse cases. Include NFRs. API contracts belong to step 3 and storage schemas to step 4.
- input path: docs/vision/
- output path: docs/ux/
- skills: ui-mock
- done when: Every actor has documented flows, data shapes, and a threat model. Every human-facing surface has UX and accessibility requirements.
Compute and messaging component design. Modules and services that do work but don't hold state: handlers, workers, queues, event buses. Environment-agnostic. This layer owns the API contracts and the message shapes between modules: document each module's capabilities, its API spec, and the shape of data in and out. See Parnas, On the Criteria to Be Used in Decomposing Systems into Modules: decompose around the decisions likely to change. Threat model module boundaries: least privilege between modules, what each one is trusted to do. Include NFRs. Each component names the code path that will implement it, by default src/<component>/. The decomposition dictates the code layout, not the other way around. Cross-cutting code gets its own component with its own doc, so every source path has exactly one owner.
- input path:
  - docs/ux/
  - docs/vision/
- output path: docs/components/
- skills: component-design, api-spec
- done when: Every module has documented capabilities, API specs, data in and out, a trust boundary, and a named code path. No two modules claim the same path.
Persistence design. Data model, schema, constraints. Underlying datastore technologies and configurations. The content is environment- and infrastructure-agnostic. Classify the data, and threat model accordingly: encryption at rest, access control, privacy and compliance obligations (e.g., GDPR, CCPA). Include NFRs. This layer owns the storage schema.
- input path:
  - docs/vision/
  - docs/ux/
  - docs/components/
- output path: docs/data/
- skills: data-modeling
- done when: Every entity has a schema, constraints, a data classification, and access rules.

Part B: Design and build the infrastructure

The workflow assumes two environments by default, dev and prod, plus an optional integration environment (int).

Environment-agnostic infrastructure design. Compute (for a hosted service, the container strategy), messaging, storage. How users and agents bootstrap, update, release, and maintain software in each one. The delivery pipeline: CI/CD for a hosted service, an app store for a mobile or desktop app, a package registry for a library. How pipeline jobs run per environment, including rollout strategy: feature flags, progressive rollout, canary, rollback, or their channel equivalents such as staged store rollouts and pre-release tags. For packaged products, design the package itself: artifact format, the supported runtime and platform matrix, and dependency policy. Define the versioning and deprecation policy. Consumers stay on old versions and a bad release can only be yanked, so backward compatibility does the work rollback does for a hosted service. Cost and budget per environment: expected spend, the drivers behind it, and a ceiling that triggers review. Threat model the infrastructure boundary: network segmentation, secrets management, SAST/SCA in the pipeline. For packaged products, extend the threat model to the supply chain: signed releases, provenance, SBOM, and protection of publish credentials. Include NFRs.
- input path:
  - docs/components/
  - docs/data/
- output path: docs/infra/allenvs/
- skills: infra-design
- done when: Release, rollout, rollback, cost ceilings, and secrets management are defined for compute, messaging, and storage. For packaged products, the versioning policy, supported matrix, and supply-chain measures are defined.
Environment-specific infrastructure design. Instructions to get bootstrapped in each environment. For packaged products, the integration environment is a pre-release channel on the registry. Storage (e.g., SQLite in dev vs. PostgreSQL in prod), environment-level observability, telemetry, and alerting infrastructure for integration and prod: log aggregation, metrics, traces, and crash reporting for client-delivered products. Telemetry watches continuously and alerts an operator when something goes wrong. Product analytics that measure the KPIs defined in step 1. Include security aspects and NFRs.
- input path:
  - docs/components/
  - docs/data/
  - docs/infra/allenvs/
- output path:
  - docs/infra/dev/
  - docs/infra/int/
  - docs/infra/prod/
- skills: env-infra-design, observability-design
- done when: Each environment has bootstrap instructions. Int and prod have observability, alerting, and product analytics designs.
Implement the infrastructure. Provision each environment and turn the designs above into code: infrastructure as code, the delivery pipeline, telemetry and alerting configuration, product analytics, secrets management. Dev comes first. Int and prod can follow later, but must be live before the gate in step 14.
- input path:
  - docs/infra/allenvs/
  - docs/infra/dev/
  - docs/infra/int/
  - docs/infra/prod/
- output path: infra/
- skills: infra-implementation
- done when: Dev is provisioned and a trivial change flows through the delivery pipeline end to end.
Confirm dev readiness. Dev must be ready before development starts. Int and prod have their own gate in step 14.
- input path:
  - docs/infra/dev/
  - infra/
- output path: No artifact generation. This is a go/no-go gate.
- skills: infra-readiness-check
- done when: The dev environment works as documented: bootstrap, release, and observe a change.

Part C: Define how it's validated

Test case design for the vision and every design document. What must be tested, and why, for the requirements to be considered met. Covers every environment-agnostic layer above: UX flows, component contracts, and the data layer. Each test case names the component it exercises. A case that spans components names the API contract it crosses instead.
- input path:
  - docs/vision/
  - docs/ux/
  - docs/components/
  - docs/data/
- output path: docs/validate/allenvs/
- skills: test-authoring
- done when: Every requirement in the input docs maps to at least one test case, and every test case cites the requirement it validates and the component or contract it exercises.
Environment-specific test case design, if needed. For where dev and prod diverge: messaging infrastructure, observability, third-party dependencies. Runs in integration or prod. For packaged products, include a clean-room install test: install the published artifact from the registry on each supported runtime and platform.
- input path:
  - docs/components/
  - docs/data/
  - docs/infra/allenvs/
  - docs/infra/dev/
  - docs/infra/int/
  - docs/infra/prod/
- output path:
  - docs/validate/dev/
  - docs/validate/int/
  - docs/validate/prod/
- skills: env-test-authoring
- done when: Every dev/prod divergence has a test case or a documented reason it needs none.
Performance test design, if needed. How performance tests should run in dev. Use the ratio of dev to prod instance sizes to estimate the volume dev can stand in for.
- input path:
  - docs/components/
  - docs/data/
  - docs/infra/allenvs/
  - docs/infra/dev/
  - docs/infra/prod/
- output path: docs/validate/perf/
- skills: perf-test-authoring
- done when: Each performance-sensitive flow has a target, a load profile, and a dev-scaled volume.
Write the tests. Turns the validation design above into executable tests: Playwright for UI, integration tests, DB-level jobs, and load-generation scripts. The test tree mirrors the component map from step 3. Tests that span components are grouped by the contract they exercise.
- input path:
  - docs/validate/allenvs/
  - docs/validate/dev/
  - docs/validate/int/
  - docs/validate/prod/
  - docs/validate/perf/
- output path: tests/
- skills: test-implementation
- done when: Every test case in the validation docs is executable. Tests fail before the implementation exists. The test tree mirrors the component map, and cross-component tests cite the contract they exercise.

Part D: Develop, release, and hand off

Write the code. Environment-agnostic tests from step 12 pass. Performance tests from step 12 run and meet their targets. Passing tests are the evidence that the product is complete in dev. That evidence is only as strong as the test design in step 9. The source tree mirrors the component decomposition from step 3: each component's code lives under its named path.
- input path:
  - docs/ux/
  - docs/components/
  - docs/data/
  - docs/infra/allenvs/
  - docs/infra/dev/
  - tests/
- output path: src/
- skills: implementation
- done when: All environment-agnostic tests pass in dev. Performance tests run and meet their targets. The top level of src/ matches the component map, and every source path is claimed by exactly one component.
Confirm integration and prod readiness. Prod must be ready before end users can use the product. Int, if present, must be ready before tests run there.
- input path:
  - docs/infra/int/
  - docs/infra/prod/
  - infra/
- output path: No artifact generation. This is a go/no-go gate.
- skills: infra-readiness-check
- done when: Int and prod work as documented. Secrets, telemetry, and alerting are live.
Release, run the tests in each environment, and monitor continuously. Establishes that prod (and integration, if present) is functional, not just at launch. Ideally, no human intervention: pass, or kick back to an operator with a specific, diagnosable failure. A failure here re-enters through the checkpoint, the same as a failure at any other step.
- input path:
  - docs/infra/int/
  - docs/infra/prod/
  - infra/
  - tests/
- output path: No artifact generation. This step triggers releases.
- skills: release-pipeline
- done when: Environment-specific tests pass in each environment. Telemetry is green and alerts reach an operator.
Handoff. Release communication, docs, onboarding, and support for end users. For packaged products, include a changelog and migration guides. Establishes that the product is usable, not just deployed.
- input path:
  - docs/vision/
  - docs/ux/
- output path: docs/handoff/
- skills: release-comms
- done when: An end user can discover the product, onboard, and get support without help from the team.

Operating after launch

An alert from the telemetry designed in step 6 and built in step 7 notifies an operator. Working with an agent and observability tools over logs, metrics, and traces, the operator investigates and identifies the root cause. Incident fixes, feature requests, and other planned iteration all re-enter through the scoping rule above. The orchestrator enters at the most upstream artifact the change contradicts, usually step 1 or 2 for a feature, and the change flows forward through the same checkpoints.

The product analytics from step 6 report the KPIs defined in step 1. They feed prioritization when work re-enters step 1.

Relation to spec-driven development

This workflow is spec-driven development in spirit. Documents come first, agents implement against them, and a human approves each gate. It differs from tools like Kiro and GitHub Spec Kit on four axes.

Scope. Those tools spec one feature at a time. This workflow spans the product lifecycle from vision to operations, and the dependency graph scales it back down: the scoping rule activates only the steps a change impacts, so a feature-sized change stays feature-sized.
Artifact lifetime. An SDD spec usually lives only as long as its change request. These artifacts are permanent, and later work re-enters through them.
Change propagation. Spec drift is SDD's best-documented failure mode. The recorded shas and the walk-forward re-check are this workflow's answer to it.
Execution. SDD runs in one session where context accumulates. This workflow isolates each step in a subagent scoped to its input paths, and keeps human review narrow at each checkpoint: one artifact, one done-when check, one decision. The component map extends that scoping into the code, so context per task is bounded by component size, not codebase size.

This is a personal blog. Views expressed here are my own and do not represent any employer, client, or organization.