Web Dte Rust Svelte
Web Workflow (REST + SQL)
A structured, AI-collaborative workflow for building web application prototypes — from raw idea to working code, one stage at a time.
What This Is
This is not a tool. It is a process.
A sequence of stages, each with a defined goal, a persona, concrete input artifacts, and concrete output artifacts. You run it with an LLM CLI (Claude Code, Gemini CLI, or any tool that supports AGENTS.md). The AI plays a role in each stage — asking questions, proposing designs, writing code — and you approve, adjust, and steer.
The workflow is specialized for a specific type of software: web applications with REST endpoints and a SQL database. But the underlying philosophy is generic and can be adapted to any domain.
Core Philosophies
These are the ideas that make this workflow work. They are transferable to any workflow you build on top of this foundation.
1. Collaborative by Design — AI Proposes, You Approve
Every significant decision goes through a propose-approve loop. The AI suggests a data model, an endpoint signature, a function contract, a design direction. You say yes, no, or adjust. Nothing is implemented without your sign-off.
This keeps you in control without requiring you to drive every detail. You stay oriented — you understand every piece of the system being built — without doing all the work.
2. Personas Per Stage — Not a Generic Assistant
Each stage has a defined persona with a specific responsibility:
- Project Initiator — asks questions until the idea is clear
- Knowledge Auditor — surfaces what you know and what you don't
- Data Architect — turns entities into database schemas
- Senior Developer — implements one use case at a time
- Workflow Engineer — fixes the workflow itself
The persona frames what the AI pays attention to and what it ignores. A Knowledge Auditor does not write code. A Senior Developer does not redesign the data model. The role prevents scope creep and keeps sessions focused.
3. Artifacts as Context Bridges
Every stage consumes specific input artifacts and produces specific output artifacts. The output of one stage is the input of the next.
This means:
- Sessions can end at any time — the artifacts capture the state
- New sessions start by reading artifacts, not by relying on conversation memory
- Handoffs between phases are explicit and verifiable
The workflow does not depend on a continuous conversation thread. It depends on files.
4. Phase 0 — The Workflow Improves Itself
Stage 0 (Meta-Workflow) is a dedicated stage for fixing the workflow itself. When a stage instruction is unclear, a script fails, or the AI behaves unexpectedly, you invoke Stage 0. A Workflow Engineer persona diagnoses the problem, applies a fix, and logs the change to docs/workflow-changelog.md.
Every workflow improvement is documented. The system gets better over time and the history of changes is searchable.
5. Prototype Mindset
The workflow produces a working prototype — not production code. The goal is to validate the design by building something real. Speed and correctness are in tension; this workflow resolves it by choosing speed first.
Phase 5 deploys the prototype.
This separation matters because prototyping decisions (SQLite instead of Postgres, no caching, no deployment config) are different from production decisions. Mixing them slows the prototype phase without improving the design.
6. Logs as Institutional Memory
Every stage session is exported as a human-readable transcript. The log captures what was discussed, what was decided, and why. Over the course of a project, the logs become a record of the design process — not just the design.
Auto-export runs every 5 minutes during a session (crash protection). A final export is made at the end of each stage.
7. Tool-Agnostic by Design
The canonical workflow instructions live in AGENTS.md — the standard adopted by Claude Code, Gemini CLI, GitHub Copilot, Cursor, and others (Linux Foundation / Agentic AI Foundation, December 2025). Tool-specific configuration (.claude/, .gemini/) contains only thin wrappers that delegate to the canonical layer in .agent-utils/.
Adding support for a new LLM tool requires:
- A tool-specific skill wrapper for
start-stage - A tool-specific skill wrapper for
export-log(with the tool's transcript path and a converter script) - A converter script extending
workflow/scripts/convert_transcript_generic.py
This Workflow: Web (REST + SQL)
The web workflow is a specialization for building web applications with:
- A REST API (JSON over HTTP)
- A SQL database (SQLite for prototyping, any relational DB for production)
Frontend rendering approach and authentication mechanism are chosen in Stage 1-5 (Tech Selection):
- Rendering: SPA, SSR, hybrid, or MPA (HTMX, Hotwire, etc.)
- Auth: JWT (Bearer token), session-based, OAuth, or hybrid
The Five Phases
| Phase | Goal | Stages |
|---|---|---|
| Phase 1: Discovery + Tech Selection | Understand what to build and pick the stack (generic — applies to any workflow branch) | 6 stages |
| Phase 2: Sketching & Data Modeling | Design entities, data model, endpoints, and UI sketches | 4 stages |
| Phase 3: UI Polish | Style the plain HTML views into a working interface | 5 stages |
| Phase 4: Prototype Implementation | Build it, refactor it | 4 stages (setup + alternating loop + refactor) |
| Phase 5: Deployment | Deploy the prototype to a real environment | 1 stage (skeleton) |
On-Demand Stages
Two stages run outside the phase cycle, whenever needed:
| Stage | Purpose |
|---|---|
| Stage 0 — Meta-Workflow | Fix the workflow itself, run git operations, import external artifacts |
| Stage teacher — Teacher | Socratic learning sessions, rubber duck debugging, pre-meeting knowledge tests, diagrams |
What It Produces
- A working prototype with real endpoints and a real database
- Automated tests (unit + integration) for every implemented use case
- Styled HTML views
- Complete design documentation (
project-brief.md,use-cases.md,api-design.md,ui-style-guide.md, and more) - Architecture Decision Records for all significant tech choices
Prerequisites
See PREREQUISITES.md for the full list with installation instructions.
Required:
- An LLM CLI that supports
AGENTS.md(Claude Code recommended) - Python 3 (workflow scripts)
- bash (hook scripts)
- SQLite CLI (schema validation in Phase 2)
- A web browser (reviewing HTML views in Phases 2 and 3)
Quick check:
echo "Python 3: $(python3 --version 2>/dev/null || echo 'NOT FOUND')"
echo "bash: $(bash --version 2>/dev/null | head -1 || echo 'NOT FOUND')"
echo "sqlite3: $(sqlite3 --version 2>/dev/null || echo 'NOT FOUND')"
Quick Start
Clone this branch into your new project directory
git clone --branch web --single-branch <repo-url> my-project cd my-projectOpen the project in your LLM CLI
claude # or: gemini, cursor, etc.Start Stage 1-1 to begin Discovery
/start-stage 1-1Follow the stage. The AI will adopt the Project Initiator persona and ask about your idea. Answer, discuss, and at the end of the session, export the log:
/export-log 1-1Continue stage by stage. Each stage reads the outputs of the previous one. The workflow guides you.
Project Structure
project-root/
├── BRANCH-INFORMATION.md ← Branch metadata (name, objective, path)
├── AGENTS.md ← Canonical workflow instructions (read by all LLM tools)
├── CLAUDE.md ← Claude Code redirect → AGENTS.md
├── GEMINI.md ← Gemini CLI redirect → AGENTS.md
├── README.md ← You are here
├── PREREQUISITES.md ← Tool installation requirements
├── .claude/
│ ├── settings.json ← Hook configuration (auto-export, session start)
│ └── skills/ ← Claude Code slash commands (thin wrappers)
│ ├── start-stage/
│ └── export-log/
├── .agent-utils/
│ └── skills/ ← Canonical, tool-agnostic skill content
│ ├── start-stage/
│ └── export-log/
├── imported-artifacts/ ← Raw imports + adapted *-imported.md files (Stage 0)
├── consolidation-artifacts/ ← Phase milestone documents (committed to git)
├── prototype-code/ ← Working prototype code (committed to git)
├── docs/
│ ├── logs/ ← Conversation logs (one per stage session)
│ ├── assets/ ← Views (HTML), CSS, SQL schema, diagrams
│ ├── adrs/ ← Architecture Decision Records
│ └── *.md ← Working design artifacts (project-brief.md, use-cases.md, etc.)
└── workflow/
├── stages/ ← Stage files (one per stage, organized by phase)
├── shared/ ← Shared protocols (Existing Artifact Protocol)
├── templates/ ← Output templates
└── scripts/ ← Automation scripts (log export, auto-export)
Slash Commands
| Command | What it does |
|---|---|
/start-stage 1-1 |
Start a specific stage (Phase 1, Stage 1) |
/start-stage 0 |
Start the Meta-Workflow (workflow fixes, git ops, artifact import) |
/start-stage teacher |
Start the Teacher (teaching, rubber duck, knowledge test, diagrams) |
/export-log 1-1 |
Export the current session log for Stage 1-1 |
Building Your Own Workflow
The web specialization lives in workflow/stages/. The philosophy it runs on is generic.
If you wanted to build a game workflow or a cli workflow, the structure would be the same:
- Define your phases — what are the natural checkpoints from idea to working prototype?
- Define stages within each phase — what is the goal, the persona, the inputs, the outputs?
- Write stage files following the same pattern: Persona → Purpose → Input Artifacts → Process → Output Artifacts → Exit Criteria → Next Stage
- Keep Stage 0 — the Meta-Workflow is universal. Every workflow needs a way to fix itself.
- Keep the log strategy — export every session, auto-export for crash protection.
The core ideas that transfer to any workflow:
- Phases create clean checkpoints (you finish one before starting the next)
- Artifacts eliminate dependency on conversation memory
- The propose-approve loop keeps you oriented
- Personas prevent scope creep
- Stage 0 makes the workflow self-correcting
The web specialization is one application of these ideas. Build the next one on the same foundation.
The Workflow Changelog
Every change to the workflow itself is logged in docs/workflow-changelog.md. This file is the record of how the workflow evolved — what problems were found, what was fixed, and why.
If you fork this workflow and improve it, the changelog is where you track those improvements.
