DevFoundry

DevFoundry is a spec-driven development scaffold for projects that mix legacy stacks (Classic ASP, VBScript, VB6, MS Access) with modern ones (C#/.NET, PHP, SQL Server, Postgres, SQLite). No implementation code is written without an approved spec in specs/active/. This document explains what actually happens, step by step, when a spec gets made and carried through to completion.

See CLAUDE.md for the operational directives an agent follows, and AGENTS.md for the full persona routing table.

The Lifecycle

[User Request]
      |
      v
[1. Requirements Analyst]  --> Elicits problem statement & acceptance criteria
      |
      v
[2. Solution Architect]    --> Drafts specs/active/<id>-<name>.md (status: DRAFT)
      |
      v
[User Approves Spec]       --> Status: DRAFT -> APPROVED (frozen)
      |
      v
[3. Builder]                --> Executes the implementation checklist step by step
      |
      v
[4. QA Verifier]           --> Checks every acceptance criterion, no regressions
      |
      v
[5. Process Improver]      --> Retrospective; logs lessons; escalates recurring friction
      |
      v
[Archive Spec]             --> Moves spec to specs/archive/<id>-<name>.md

Step by Step

1. Requirements gathering (Requirements Analyst)

Before any technical design starts, the Requirements Analyst persona (.devfoundry/personas/requirements-analyst.md) runs the interview procedure in .devfoundry/skills/spec-interview.md:

1. What problem is being solved, and for whom.
2. Which stack(s) and database engine(s) are affected.
3. Inputs, outputs, and edge cases (invalid input, empty data, concurrency).
4. Acceptance criteria, stated as Given/When/Then.
5. Which files/modules are likely affected.
6. Rollback or backward-compatibility needs if schema changes are involved.
7. A summary handed back to the user for confirmation.

This persona never proposes a technical solution — that's the next stage's job. If the request is ambiguous, it asks rather than assumes.

2. Drafting the spec (Solution Architect)

Once requirements are confirmed, the Solution Architect persona (.devfoundry/personas/solution-architect.md) runs .devfoundry/skills/technical-spec.md:

1. Copy specs/templates/spec-template.md to specs/active/<id>-<short-name>.md.
2. Fill in Business Context, Acceptance Criteria, and Technical Design & Contracts — schema changes, function/API signatures with their preconditions and postconditions (see Coding Standards below), architecture, and error handling strategy. Schema and dialect decisions are checked against .devfoundry/references/sql-dialects.md and .devfoundry/references/data-dictionary.md.
3. If the spec touches a database schema, .devfoundry/skills/db-schema-change.md applies: document the current schema, write exact DDL for the target engine, identify dependent queries/views/reports, and provide a rollback/backup step (mandatory for .mdb/.accdb files — copy before altering).
4. Break the work into an atomic, dependency-ordered implementation checklist (.devfoundry/skills/task-decomposition.md): schema changes first, then backend logic, then UI, then verification. Each task touches the minimum files necessary and has a clear definition of done.
5. Mark the spec DRAFT and present it to the user.

The Architect does not begin implementation — that only happens after approval.

3. Approval gate

The user reviews the DRAFT spec and approves it. Status flips DRAFT -> APPROVED, and the spec is now frozen: its Acceptance Criteria and Technical Design sections don't change without going back through this gate.

4. Implementation (Builder)

Depending on what's touched, either the Legacy Specialist or Modern Builder persona executes the implementation checklist one unchecked box at a time, in the TDD order the checklist was written in: write the failing test (or manual verification step) for a box, confirm it fails, then implement until it passes.

• Legacy Specialist (.devfoundry/personas/legacy-specialist.md) — .asp, .vbs, .bas, .frm, .cls, .mdb, .accdb. Follows .devfoundry/rules/legacy-asp-vb6.md and .devfoundry/rules/database-sql.md: explicit COM object release, parameterized ADO queries, defensive error handling, backups before structural Access changes, and TDD via a test harness where one exists (manual verification steps written first, otherwise).
• Modern Builder (.devfoundry/personas/modern-builder.md) — .cs, .php, SQL Server/Postgres/SQLite scripts. Follows .devfoundry/rules/dotnet-csharp.md and .devfoundry/rules/php.md: parameterized queries, TDD (test written and run red before any implementation).

Both personas touch only the files listed under the current task, and check the box [x] in the spec once a step is done and verified.

5. QA verification (QA Verifier)

The QA Verifier persona (.devfoundry/personas/qa-verifier.md) runs .devfoundry/skills/regression-check.md:

1. Re-read the spec's Acceptance Criteria and Verification Plan.
2. For legacy code, manually trace affected queries, forms, and reports.
3. For modern stacks, run the automated test suite plus any new tests.
4. Check known dependent features via .devfoundry/references/data-dictionary.md.
5. Record results in the spec's Verification & Regression Plan checklist.

A spec is not approved as complete if any acceptance criterion fails.

6. Retrospective (Process Improver)

Once QA passes, the Process Improver persona (.devfoundry/personas/process-improver.md) runs .devfoundry/skills/process-retrospective.md before the spec is archived:

1. Fill in the spec's Retrospective section (what worked, what friction occurred).
2. Append a dated entry to .devfoundry/improvement-log.md.
3. If the same friction (a rule gap, reference gap, interview gap, or repeated manual verification step) has now recurred 3+ times in the log, propose a concrete edit to the relevant rule/skill/persona/reference file for the user to approve.

This is what keeps the process itself improving — recurring corrections get folded back into the rules instead of being repeated by hand on every spec.

7. Archive

The completed spec moves from specs/active/<id>-<name>.md to specs/archive/<id>-<name>.md. Archived specs are immutable history and are never edited by later retrospectives.

Coding Standards

Three standards apply across every stack, defined in .devfoundry/rules/general.md and expanded per stack in the rule files:

• Test-Driven Development: Where automated testing is possible, the test is written first and confirmed to fail for the right reason before any implementation code is written — then only enough code is added to make it pass (red-green). Where no test harness exists (some legacy stacks), the manual verification steps are written before the code they verify, as the TDD-equivalent artifact. The spec's Implementation Plan pairs every implementation task with a preceding test/verification-writing task (spec-template.md, tasks-template.md), and the QA Verifier checks that ordering actually happened, not just that tests exist.
• Design by Contract: Every function/API/interface in a spec's Technical Design section must state its preconditions, postconditions, and invariants. Implementations validate preconditions at the boundary and fail fast rather than proceeding on unchecked assumptions.
• MVC by Default for Web Apps: New or substantially modified web app components default to a Model-View-Controller separation — request/business logic, data access, and presentation in distinct layers. A different architecture requires explicit justification in the spec.

See .devfoundry/rules/dotnet-csharp.md, .devfoundry/rules/php.md, and .devfoundry/rules/legacy-asp-vb6.md for how each applies per stack (e.g. ASP.NET Core MVC/Razor Pages, Laravel-style or explicit controllers/models/views in PHP, and concern-separated modules in Classic ASP, which has no built-in MVC framework).

Directory Reference

Path	Contents
specs/active/	Specs currently DRAFT, APPROVED, IN PROGRESS, or REVISED
specs/archive/	Completed, immutable specs
specs/templates/	spec-template.md, tasks-template.md
specs/.spec-counter	Next unused spec ID; incremented by the Solution Architect each time a spec is created — never reused
.devfoundry/personas/	The six agent roles in the lifecycle above
.devfoundry/skills/	The step-by-step procedures each persona follows
.devfoundry/rules/	Stack-specific coding standards (legacy, .NET, PHP, database/SQL, general)
.devfoundry/references/	Project-specific facts: environments, data dictionary, SQL dialects
.devfoundry/improvement-log.md	Append-only log of retrospectives across all specs

Spec Status Values

DRAFT → APPROVED → IN PROGRESS → COMPLETED (then archived). APPROVED flips to IN PROGRESS when the Builder checks the first Implementation Plan box. A spec can also move APPROVED/IN PROGRESS → REVISED if the user requests a genuine scope change after freeze — see “Amending an APPROVED or IN PROGRESS Spec” in .devfoundry/skills/technical-spec.md. Once the revision is approved, it returns to APPROVED or IN PROGRESS and continues toward COMPLETED.