The Flexso Spec-Driven Framework
This is the heartbeat of how we work. Every unit of work — a new feature, a bug fix, a refactor, a new SaaS app — follows the same lifecycle. No exceptions. The framework is deliberately simple because complexity kills adoption.
The 6-Stage Lifecycle
| Stage | Name | Description |
|---|---|---|
| 01 | Opportunity | Sales/customer identifies need |
| 02 | Spec | Functional writes detailed spec |
| 03 | Build | AI-assisted development |
| 04 | Review | Human code review + test |
| 05 | Ship | Merge deploys DEV; release tag → TST → PRD |
| 06 | Operate | Monitor, maintain, iterate |
Stage Details
Before the stages — Kickstart (projects and large trajects)
Who: the engineer. For a new project or a traject too large for one issue, /spexso-kickstart runs a breadth-first interview and feeds the lifecycle in bulk: a type::epic parent issue (it carries no stage:: label, so it never enters the lifecycle itself and no marathon picks it), a spexso/ milestone, the first wave of slices straight into stage::spec with a full spec, and the remaining slices into stage::opportunity — linked by blocks edges so /spexso-marathon --milestone builds them in order. An MR seeds GLOSSARY.md and the constitution. See Project of traject kickstarten.
Stage 1 — Opportunity
Who: Sales / Product Scout + Functional Consultant. A customer need, a product idea, or a competitive gap is identified. The sales person creates a GitLab issue with label stage::opportunity using the Opportunity Template. This is a lean doc: who's the customer, what's the pain, what's the rough value. Claude helps draft the business case with market context.
Stage 2 — Spec (The Critical Stage)
Who: Functional Consultant (owner) + Tech Lead (reviewer). This is where the magic happens. The functional consultant writes a complete specification in the GitLab issue using the Flexso Spec Template (see Section 06). The spec must include: user stories, acceptance criteria, data model sketch, integration points, and edge cases. Claude assists in generating BDD test scenarios from acceptance criteria and identifying missing edge cases. The issue moves to stage::spec. Once the spec is complete, the issue is ready for /spexso-start — issues still in stage::opportunity are blocked.
Stage 3 — Build
Who: Developer Consultant (with Claude Code). The developer opens Claude Code, points it to the spec and CLAUDE.md, and starts building. AI generates the first draft. Human reviews, adjusts, iterates. Code is committed to a feature branch linked to the issue. Small, focused commits. Label: stage::build.
Stage transitions are single-value: each step (spec → build → ship) goes through
npx spexso stage <id> <stage>, which removes every otherstage::*before adding the new one. An issue therefore carries exactly one stage label at any time — see GitLab Setup.
Stage 4 — Review
Who: AI reviewer subagent (automated). /spexso-review checks the implementation against the spec — code quality, test coverage, and spec adherence. Critical and high issues are auto-fixed inline. Low-severity issues are left as comments. When review passes, the developer runs /spexso-finish to ship the work. Label: stage::review (tracked on the MR).
Stage 5 — Ship
Who: /spexso-finish (automated) + Developer (manual QA). The finish command pushes the branch, creates a MR targeting the configured targetBranch, and auto-merges it (squash). On merge, the issue moves to stage::ship with the needs::manual-test label. Spexso posts the acceptance criteria as a checklist comment on the issue. The developer runs the checklist and removes needs::manual-test when done. With a test hand-off configured, the issue stays open and is assigned to a tester instead; a failed test sends it back to stage::build / stage::spec. The merge triggers CI/CD: build → deploy to DEV. Shipping to TST/PRD happens per release: the manual prepare-release job tags main, and the tag pipeline deploys TST automatically and PRD behind a manual gate — see CI/CD design. Label: stage::ship.
Stage 6 — Operate
Who: Entire team. The application is live. Bugs come in as issues with type::bug. Feature requests come in as type::enhancement. Both follow the same lifecycle from Stage 2 onwards. Monitoring dashboards are linked in the project wiki. Label: stage::operate.
Non-Negotiable Rule
No code is written without a spec. Not a quick fix. Not a "small change." Not a hotfix (unless it's literally production-down, and even then a retroactive spec is written within 24 hours). This rule is what separates a product team from a team that's just reacting.