A Local End-to-End AI-Assisted SDLC Walkthrough

This page is the implementation-heavy companion to the closed-loop AI-assisted SDLC model. The goal is not to reproduce a production platform on a laptop. The goal is to preserve the stage model while simplifying infrastructure enough that one engineer can follow the whole lifecycle in a single repository.

The example feature is intentionally bounded: add category-level notification preferences to an existing service that already stores a single “email on/off” setting. That gives us concrete acceptance criteria, a realistic schema change, tests, reviewable diffs, and production-style feedback without turning the walkthrough into a toy problem.

Walkthrough Scope: What This Local Build Includes and Excludes

This build includes a normalized requirements packet, an orchestrated stage graph, a bounded generation stage, validation evidence, a manual approval checkpoint, a mock deployment decision, and feedback re-entry. It excludes multi-user coordination, real CI runners, production rollout automation, and enterprise-grade secrets handling.

Those exclusions matter. The walkthrough is meant to preserve the lifecycle contracts from the hub, not to imply that a local file system equals a production control plane.

Repository Shape and Artifact Directory Structure

Keep the repository layout boring and explicit. A simple local shape might look like this:

app/
  preferences/
artifacts/
  requirements/
  runs/
  evals/
  releases/
workflow/
  graph.py
  state.py
tests/

The `artifacts/requirements/` directory stores normalized packets. `artifacts/runs/` stores stage outputs per run. `artifacts/evals/` stores test and quality evidence. `artifacts/releases/` stores release decisions and feedback summaries. This mirrors the contract-first expectations from the requirements normalization and orchestration architecture pages.

Local Tooling Stack: LangGraph, Model Interface, and Validation Tooling

LangGraph is a good local orchestration choice because it is designed for stateful, long-running agent workflows. Use it here to model the graph and state transitions, not to hide lifecycle semantics behind magic defaults. LangSmith is helpful if you want trace visibility and eval logging even in local runs, though the walkthrough should still work without a hosted observability dependency.

For model access, keep the interface swappable. LiteLLM can be useful if you want a unified local abstraction over multiple providers. Ollama is useful if you want to keep the walkthrough fully local; its official docs expose a simple local API surface, which makes it easy to experiment without depending on an external hosted model. If you need tool/data integration, MCP is worth understanding because the official specification frames it as an open protocol for connecting LLM applications to external tools and data sources. None of these choices should dominate the lifecycle design.

Implementing Graph Stages and Stage Contracts

Model the graph as explicit stages:

1. load requirements packet
2. plan generation scope
3. generate code diff proposal
4. generate and run tests
5. review evidence and wait for approval
6. make release decision
7. collect feedback and emit requirements delta

Each stage should declare expected input and output artifacts. For example, the code generation stage consumes `requirements.json` plus a small set of repository files, then emits `generated-diff.md`, `assumptions.json`, and `touched-files.json`. The test stage consumes those artifacts and emits `test-evidence.json`. Keeping the stage contract explicit is more important than making the implementation elegant.

Adding Approval Checkpoints and Manual Overrides

Even locally, add a real stop point before release. Have the graph pause after validation and emit `approval-checkpoint.json` with the generated summary, test evidence, and unresolved risks. The human operator can approve, reject, or request remediation. That preserves the control boundary from the review and remediation stage.

Manual override should also exist. If the run reveals a broken assumption, allow the operator to send the flow back to requirements or generation with a reason code. A local walkthrough that skips this step teaches the wrong lesson: that the graph is fully autonomous once started.

Capturing Traces, Evals, and Run Metadata

Give each run a `runId` and preserve stage timestamps, stage status, retry count, artifact references, and evaluator summaries. If you wire LangSmith in, attach the trace identifiers to the same run record. If you keep everything local, write a `run-metadata.json` file that points to the artifacts created in that run.

The important thing is that you can answer, after the fact, which requirement packet was executed, which files were touched, what tests ran, and why the release decision went one way or the other. That is what turns a local demo into a faithful lifecycle analog.

Running a Full Cycle: Requirements to Feedback to Revised Requirements

For the notification-preferences example, start with a requirement packet that says users can opt out of marketing notifications while retaining security notifications. Generate the diff proposal, then have the test stage assert category-level persistence, backward compatibility for existing users, and audit-event emission. Review the evidence, approve the change, and write a release decision that simulates phased rollout to internal accounts first.

Then inject feedback: for example, users expect category defaults to inherit from the global setting until they make an explicit override. Capture that in `feedback.json`, rank it as a medium-severity product correctness issue, and emit `requirements-delta.json` with revised acceptance criteria. That final handoff is what makes the run closed-loop instead of just a one-way pipeline demo.

Extending the Local Walkthrough Toward Production Readiness

The path to production is mostly about replacing local durability and operator assumptions with shared systems. Move from JSON files to a shared state store, from local command execution to CI runners, from manual approval files to role-aware approval surfaces, and from local traces to shared observability. The stage contracts, artifact shapes, and gate semantics should remain intact.

That is the real lesson of the walkthrough: the production model is not “different logic at bigger scale.” It is the same lifecycle with stronger durability, access control, and operability around it.