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/SPEC-<id>-<short-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/SPEC-<id>-<short-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. Any missing project-reference facts needed for Builder or QA work: runtime versions, build/test/lint commands, database engine and schema sources, driver constraints, and legacy error-log paths.
8. 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/SPEC-<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. Run the Spec Readiness Checklist, mark the spec DRAFT, and present it to the user.

Spec Readiness Checklist before approval:

• Status is DRAFT.
• Business Context, Acceptance Criteria, Technical Design & Contracts, Implementation Plan, Verification & Regression Plan, and Target Files are complete.
• Active specs have been checked for target-file overlap.
• Build/test/lint commands are documented in .devfoundry/references/environments.md, or the spec explicitly records that no command exists for the affected stack.
• Database changes include current schema notes, target-engine DDL, dependent queries/views/reports, and rollback or backup steps.
• Specs with no database/schema changes record exactly: No schema changes; rollback is git revert.
• Every implementation task has a preceding test/manual-verification task with completed: <YYYY-MM-DD HH:MM> timestamp space.

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.

3a. Abandoning a draft

If the user cancels a DRAFT spec before approval, set its status to ABANDONED, add a brief cancellation reason in the Business Context or a final note, and move it to specs/archive/SPEC-<id>-<short-name>.md. Do not decrement specs/.spec-counter and do not reuse the ID.

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. They may check a task box [x] once that task's local verification passes and its completed: <YYYY-MM-DD HH:MM> note is recorded. The overall spec is not complete until the QA Verifier approves every acceptance criterion and regression check.

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/SPEC-<id>-<short-name>.md to specs/archive/SPEC-<id>-<short-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 or abandoned 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
docs/process-checks.md	Repeatable process verification checks for workflow documentation changes
.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 retrospective entries plus a maintained Friction Tally

Spec Status Values

Status	Set by	Meaning / next step
DRAFT	Solution Architect	Spec is ready for user review, but implementation has not started.
APPROVED	User approval, recorded by the agent	Acceptance Criteria and Technical Design are frozen; Builder may start.
IN PROGRESS	Builder	First Implementation Plan task has been started or checked off.
REVISED	Solution Architect / Builder, after a post-freeze scope change	Frozen sections have an amendment pending user approval.
COMPLETED	QA Verifier	All acceptance criteria and regression checks passed; Process Improver runs before archive.
ABANDONED	User cancellation, recorded by the agent	Draft work was cancelled before approval; the spec is archived and its ID is never reused.

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.