Spec-Driven Development on Mobile: Spec Kit, BMAD, OpenSpec, and What I Use Day to Day

If you have ever spent ten minutes structuring a prompt before asking Cursor, Copilot, or Claude Code for code, congratulations: you already practice Spec-Driven Development (SDD). You just may not have named the process yet.

In my personal projects, this is routine. When I coach squads in enterprise contexts (Super Apps with years of code, regulated onboarding, convergence between GenAI, Server-Driven UI, and mobile security), the conversation shifts tone: the risk is not the AI getting Swift or Kotlin syntax wrong. The risk is duplicating modules, ignoring internal SDK contracts, breaking feature-flag isolation, or violating security guidelines that took months to mature.

SDD formalizes what mature teams already do ad hoc. Today there are three open-source frameworks that materialize this discipline with distinct approaches: GitHub Spec Kit, BMAD Method, and OpenSpec. Each occupies a different place on the spectrum from lightweight to comprehensive, and choosing wrong means using a hammer to crack a nut, or a pocketknife to build a shopping mall.

*Note: this is a long post. Read it at your own pace. I wrote it for mobile devs, tech leads, and architects who already use AI day to day, but still do not know when to formalize specs, and which tool to adopt in each context.*

This post was also written in Portuguese, click here to access the Portuguese version.

1. The problem nobody talks about

The promise of generative AI in mobile development is seductive: describe what you want and receive code. In practice, in a brownfield Super App, the agent does not know your monorepo's decision history. It does not know that the :feature-wallet module already exists, that AuthSDK is the only entry point for session, or that the design system forbids components outside DSKit.

The result? Code that compiles, but does not belong to the architecture.

Spec-Driven Development proposes inverting the logic: before code, we align intent, constraints, and acceptance criteria in structured artifacts that live in the repository. As the positioning of GitHub Spec Kit puts it: maintaining software comes to mean evolving specifications; code becomes last-mile.

In this article, I share the view of the three pillars I use and recommend, a practical playbook for brownfield Super Apps, and a matrix to decide which philosophy to adopt according to your context: enterprise, greenfield, or brownfield.

2. What is a "spec" in this context

The term "spec" is still disputed in the market. Birgitta Böckeler, Distinguished Engineer at Thoughtworks, proposed a useful taxonomy in her analysis of Kiro, spec-kit, and Tessl:

flowchart LR
  subgraph levels [SDDLevels]
    SF[SpecFirst]
    SA[SpecAnchored]
    SS[SpecAsSource]
  end
  SF --> SA --> SS

• Spec-first: you write the spec before code for the task in progress.
• Spec-anchored: the spec remains in the repository as the source of truth as the feature evolves.
• Spec-as-source: the human edits only the spec; code is generated (still experimental).

For me, the more practical distinction is another: Memory Bank versus feature spec.

The Memory Bank is documents that guide all AI sessions in the project. The spec matters only for the functionality being created or changed.

The three frameworks materialize SDD artifacts; the RPI discipline (Research → Plan → Implement) governs when the agent can move from reading to planning and from planning to code. I detail this in section 8.

The concept that most changed how I work in brownfield came from OpenSpec: instead of rewriting the entire spec, you produce deltas: requirement diffs with + and -, showing exactly what changes in the system. The reviewer understands intent without rereading forty pages of markdown.

3. GitHub Spec Kit: the Swiss Army knife in the IDE

GitHub Spec Kit is a CLI that installs templates, prompts, and slash commands in the workspace. It works with Cursor, Copilot, Claude Code, and other assistants.

The main workflow follows a clear sequence:

/speckit.constitution → /speckit.specify → /speckit.clarify → /speckit.plan → /speckit.tasks → /speckit.implement

For features with meaningful ambiguity, the official quickstart recommends additional gates: /speckit.checklist and /speckit.analyze before implementation.

Typical artifacts per feature: spec.md, plan.md, tasks.md, research.md, data-model.md, API contracts.

Why it works well on mobile

• Constitution as an immutable contract: ideal for platform rules. An example I use: *"never access Keychain outside the SecurityCore module"*.
• Tasks with sequential IDs, explicit dependencies, and [P] marker for parallelizable tasks: useful when iOS and Android evolve the same domain contract in separate modules.
• Git integration: branch per spec, conversion of tasks to issues with /speckit.taskstoissues.
• Checklists as Definition of Done per phase: the agent (and you) know when to advance.

Where I see limitations

Böckeler tested Spec Kit on a 3–5 point feature in an existing codebase and concluded that the volume of markdown generated was disproportionate to the problem size. On a small bug, the workflow became "using a hammer to crack a nut": four user stories and sixteen acceptance criteria for a point fix.

Other points I have lived in practice:

• The agent may ignore "existing code" notes in research.md and duplicate classes.
• Many files to review in brownfield, and honestly, sometimes I prefer reviewing code over repetitive markdown.
• The model is still more spec-first than long-term spec-anchored (each spec is born in a branch; post-merge persistence depends on team discipline).

The Thoughtworks Technology Radar (Apr/2026) positions Spec Kit as better suited to greenfield projects, and I agree, with caveats for new modules inside mature monorepos.

4. BMAD Method: the operating system for enterprise

The BMAD Method (Build More Architect Dreams) is a full life-cycle open-source framework. Documentation is at docs.bmad-method.org.

While Spec Kit focuses on the spec → implementation pipeline, BMAD covers everything from brainstorming to deploy, with specialized agents (PM, Architect, Developer, UX, Test Architect, and others).

flowchart TD
  idea[IdeaOrBug] --> analysis[AnalysisPhase]
  analysis --> planning[PlanningPRDArchitecture]
  planning --> solutioning[Solutioning]
  solutioning --> impl[Implementation]
  impl --> validate[TestArchitectTEA]

Why I adopt it in enterprise contexts

• Established Projects: workflow designed for brownfield, not just greenfield.
• Test Architect (TEA): risk-based test strategy. In financial apps, this is not a luxury.
• Party Mode: multiple agent personas discussing trade-offs. Useful when Super App modularization involves PM, architect, and chapter lead.
• Web Bundles: planning (PRD, UX, market research) in Gemini or ChatGPT with flat-rate subscription; artifacts refined later in the IDE. Real savings on long engagements.
• Implicit constitution via project context + ADRs: aligns directly with what I wrote in the ADR guide for generative AI.

Where I see limitations

• Installation curve: npx bmad-method install, Node.js, Python, uv.
• Can be heavy for a weekend prototype.
• Requires discipline so it does not become infinite documentation nobody reads.
• The Thoughtworks Radar classifies workflows like BMAD as more rigid than lightweight alternatives like OpenSpec.

5. OpenSpec: the brownfield and spec-anchored pillar

OpenSpec is a lightweight SDD framework, highlighted in the Thoughtworks Technology Radar (Apr/2026) in the Assess category: worth exploring to understand the impact in your enterprise context.

What convinced me was the explicit positioning: brownfield-first. Most SDD tools assume you are starting from zero. OpenSpec assumes you are evolving a system that already exists, and that describes 90% of my professional work.

Quick comparison of the three frameworks

Workflow

propose → apply → archive

A typical command in Cursor: /openspec:proposal. The agent searches existing specs, reads relevant code, and generates a change folder:

openspec/changes/add-wallet-overview/
├── proposal.md      ← why the change
├── design.md        ← technical decisions
├── tasks.md         ← implementation steps
└── specs/           ← requirement deltas
    └── wallet-session/
        └── spec.md  ← diff with new GIVEN/WHEN/THEN scenarios

The long-term library lives in openspec/specs/, organized by capability:

openspec/specs/
├── auth-login/spec.md
├── auth-session/spec.md
├── wallet-summary/spec.md
└── checkout-payment/spec.md

Each spec uses GIVEN/WHEN/THEN scenarios: aligned with BDD and with the acceptance criteria format of Kiro.

Example delta I would write for a mobile flow:

### Requirement: Offline balance display
- The app MUST display the last cached balance when offline.
#### Scenario: User without connectivity
- GIVEN an authenticated user with balance cached less than 24h ago
- WHEN the device is offline
- THEN display balance with "last updated" indicator
+ AND disable actions that require network (transfer, instant payment)

Why OpenSpec became my brownfield default

• Intent review, not just code review: the reviewer reads the delta before the implementation PR.
• Agent swap without losing context: specs in Git survive switching from Cursor to Copilot.
• Archive merges the delta into the live spec: onboarding a new dev on the feature-wallet module becomes trivial.
• Not waterfall: OpenSpec itself says: spend ten minutes thinking, not three weeks planning.

Limitations I need to mention

• Multi-repo workspaces still in development.
• Does not replace BMAD for complex product discovery.
• Requires someone to read and think about specs: not automatic vibe coding.
• The Radar recommends monitoring native agent capabilities and periodically reassessing the need for SDD tooling.

6. Enterprise, Greenfield, and Brownfield: which philosophy to adopt

Before choosing a tool, calibrate the project context. This is the section I use most when coaching professionals at the company.

6.1 The three contexts

Important note: Enterprise is not the opposite of brownfield. In practice, enterprise is almost always brownfield. The distinction here is organizational maturity: how many squads, how much compliance, how much formal process the business requires.

6.2 Three SDD philosophies

Before the tool, choose the team's posture:

The three frameworks map naturally:

• OpenSpec → spec-anchored (incremental brownfield)
• Spec Kit → spec-first with constitution (greenfield or new feature)
• BMAD → spec-governed (enterprise with discovery and TEA)

6.3 Adoption matrix

flowchart TD
  start[WhichContext] --> gf{Greenfield}
  start --> bf{Brownfield}
  start --> ent{Enterprise}

  gf -->|newAppOrModule| sk[SpecKit_Constitution_Plan]
  gf -->|rapidPrototype| light[OpenSpec_LightProposal]

  bf -->|capabilityEvolution| os[OpenSpec_Delta_Archive]
  bf -->|newModuleInMonorepo| sk2[SpecKit_WithMobileConstitution]
  bf -->|largeRefactor| bmad[BMAD_EstablishedProject]

  ent -->|multiSquadEpic| bmad2[BMAD_Plus_TEA_Plus_ADR]
  ent -->|regulatedMaintenance| os2[OpenSpec_LiveSpecs]
  ent -->|isolatedFeaturePerSquad| sk3[SpecKit_BranchPerSpec]

6.4 How I apply it in each context

Greenfield: start right without getting stuck

I start with a mobile constitution via Spec Kit before the first line of code: min SDK, module architecture, security rules. As capabilities emerge, I create OpenSpec specs: I do not try to document everything upfront. BMAD only enters if scope grows beyond one dev.

Brownfield: evolve without breaking what works

Default: OpenSpec for any change that touches existing behavior. The agent must read openspec/specs/ and module code before proposing. Spec Kit enters when it is a new module inside the monorepo. BMAD when the refactor crosses squad boundaries.

Enterprise: governance without paralysis

Hybrid model I recommend:

• BMAD for discovery, architecture, and test strategy on strategic initiatives.
• OpenSpec as the versioned behavior layer: when the auditor asks "what should the app do?", the answer is in Git.
• Spec Kit per squad on scoped features, with constitution aligned to the mobile chapter.
• ADRs as the bridge between the three.

6.5 Problem size (complementary matrix)

6.6 Rules I repeat to the team

Greenfield: invest 30 minutes in the constitution. It is the best ROI you will get with AI.

Brownfield: never ask for code before the agent reads what already exists: spec delta or research step are non-negotiable.

Enterprise: do not choose one tool: choose a hybrid model. OpenSpec on the maintenance track, BMAD on the innovation track.

Golden rule: if the change fits in one dev's PR in one day, OpenSpec or nothing. If it crosses squads, BMAD.

flowchart LR
  subgraph spectrum [SDDSpectrum]
    OS[OpenSpec_Light_Brownfield]
    SK[SpecKit_Medium_Greenfield]
    BM[BMAD_Full_Enterprise]
  end
  OS --> SK --> BM

Choose in 30 seconds

7. Practical playbook: brownfield Super App

I will illustrate with a scenario I face frequently: adding a wallet overview module inside an existing Super App, with internal auth SDK, feature flags, analytics, and design system.

Phase 0: Memory Bank (all approaches)

Before any feature spec:

• architecture.md: module diagram (host app, feature modules, shared kernels)
• mobile-constitution.md: min iOS/Android, offline, WCAG accessibility, ProGuard/R8, certificate pinning
• Referenced existing ADRs
• Contracts: BFF OpenAPI, feature flags schema, analytics events
• OpenSpec: openspec/specs/wallet-summary/spec.md if the capability already exists partially

Path A: Spec Kit

1. /speckit.constitution: mobile principles + *"do not recreate classes from the CoreNetworking module"*
2. /speckit.specify: user stories: offline user sees last cached balance
3. /speckit.clarify: which BFF? which screen in the navigation graph?
4. /speckit.plan: KMP or Swift Package, SDUI integration
5. /speckit.tasks: parallel waves with [P]
6. /speckit.implement: I review code, not just markdown
7. /speckit.converge: gap analysis

Example task:

- [ ] T014 [P] [US2] Implement WalletSummaryViewModel in feature-wallet/domain/
- [ ] T015 [US2] Integrate with AuthSDK.getSession() - do NOT create new HTTP client

Path B: BMAD

1. bmad-help: workflow Established Project
2. Analysis: host module dependencies (Architect agent)
3. Planning: PRD + sequence diagram (login → BFF → cache)
4. Solutioning: dynamic module vs compile-time; CI impact per flavor
5. Implementation: Dev agent with sharded context
6. TEA: risk matrix: P1 balance, P2 empty states, P3 animations

Path C: OpenSpec

1. Research: /openspec:proposal with "Add wallet overview with offline support and empty states"
2. Research: agent reads openspec/specs/auth-session/spec.md and code in feature-wallet/ (facts only, no solution yet)
3. Plan: generates openspec/changes/add-wallet-overview/ with proposal, design, tasks, and spec delta
4. Plan: human review of the delta: alignment with mobile security
5. Implement: Apply guided by tasks.md
6. Implement + SDD closure: Archive merges the delta into openspec/specs/wallet-summary/spec.md

Comparison in the same scenario

What changes in mobile practice

• Modularization: specs cite boundaries (:feature-wallet, WalletKit)
• Dual platform: parallelizable tasks with same domain contract
• SDUI + GenAI: spec describes intent; design defines native vs server renderer
• Security: threat modeling on financial flows, in any framework
• CI/CD: PR includes spec delta review before code review

The rule I keep non-negotiable: AI proposes, the specialist audits. That applies to code and specs.

8. RPI: Research, Plan, Implement, the discipline behind SDD

Having constitution.md, spec delta, or research.md in the repository does not stop the agent from ignoring everything if the session starts with "just implement this". SDD answers what to document and where to persist. Missing is the layer that answers in what order the agent acts, and when to stop.

That is where RPI (Research → Plan → Implement) comes in, popularized by the HumanLayer ecosystem and documented accessibly in the Kilo Path guide and the community repository patrob/rpi-strategy. RPI is not a fourth framework alongside Spec Kit, BMAD, and OpenSpec. It is the meta-discipline that makes the three effective: it separates reading, planning, and execution into phases with explicit gates.

SDD defines artifacts; RPI defines gates between session phases.

flowchart TB
  subgraph sdd [SDDLayer_Artifacts]
    MB[MemoryBank]
    Spec[SpecOrDelta]
    Tasks[TasksOrPlan]
  end
  subgraph rpi [RPILayer_Discipline]
    R[Research_FactsOnly]
    P[Plan_AtomicTasks]
    I[Implement_Verify]
  end
  R -->|"FAR gate"| P
  P -->|"FACTS gate"| I
  R -.-> MB
  P -.-> Spec
  P -.-> Tasks
  I -.->|"archive / converge"| Spec

The three phases

As the Kilo Path guide summarizes: planning without research leads to bad assumptions: planning without researching generates bad assumptions. In brownfield mobile, that translates to duplicating AuthSDK, ignoring :feature-wallet, or violating the constitution without noticing.

RPI in the three frameworks

Spec Kit already embeds RPI in the pipeline: the research.md from section 3 never had a name, but it is pure Research. The mapping looks like this:

Light gates: FAR and FACTS

It does not need to become bureaucracy. patrob/rpi-strategy proposes two validation scales: I use them as a mental checklist, not a mandatory spreadsheet:

• FAR (Research): Factual ≥4, Actionable ≥3, Relevant ≥3: does the agent have evidence in code or is it inventing?
• FACTS (Plan): average ≥3 on Feasible, Atomic, Clear, Testable, Scoped: does each task fit in a small PR and is verifiable in isolation?

Example replacing the vague prompt:

Instead of: "Add wallet screen"

Research: *"Map what exists in :feature-wallet and AuthSDK. Evidence: paths, contracts, specs in openspec/specs/. Do not propose a solution yet. Validate FAR."*

Plan: "Break into atomic tasks with Gradle/SPM paths. Validate FACTS: each task < 4h and testable in isolation."

Implement: "Execute T014; run tests; check the box."

What I change in practice

• Brownfield: Research is non-negotiable: I already repeat this in section 6.6; with RPI, I gain vocabulary for the team.
• Fresh context between phases: on risky tasks, I prefer a new session (or /clear in Cursor) when leaving Research for Plan, and Plan for Implement. Bloated context degrades agent quality: an insight the HumanLayer ecosystem documented when scaling RPI in production.
• Point bug (matrix 6.5): collapsed RPI: five-minute Research + direct Implement, no formal plan.

Note: HumanLayer evolved the original workflow to CRISPY: more alignment stages before code. For brownfield mobile, SDD + RPI already cover most of the gain; CRISPY is worth exploring when scope crosses squads and the cost of misalignment is high.

9. How I think, plan, and execute

My seven-step sequence: the first four choose SDD philosophy and tool; the last three follow the RPI skeleton:

1. Identify context: greenfield, brownfield, or enterprise
2. Choose philosophy: spec-first, spec-anchored, or spec-governed
3. Calibrate: problem size and clarity
4. Choose pillar: OpenSpec (evolution), Spec Kit (new feature), BMAD (epic)
5. Research: memory bank + ADRs + existing specs + reading relevant code
6. Plan: spec or delta + tasks; FAR/FACTS gates when risk justifies
7. Implement: execute mechanically, verify on device, archive or converge

Anti-patterns I see in companies:

• Giant spec without constitution → AI invents stack
• Skipping reading existing specs in brownfield → code duplication
• Treating spec as disposable prompt → loses traceability in audit
• Using full BMAD for padding adjustment
• Generating all specs upfront in OpenSpec → contrary to incremental model
• Monolithic Research + Plan + Implement session in one prompt → agent "hallucinates" architecture
• Plan without Research in brownfield → assumptions that become a discarded PR

10. Convergence with what I already evangelize

ADRs are the memory bank of decisions. Specs reference ADR-00X; agents understand the why beyond the what.

Server-Driven UI fits naturally: the spec describes the component contract; design defines whether the renderer is native or server.

GenAI executes tasks; the human validates on a real device, with contract tests and SAST where applicable.

MobileOps benefits from anchored specs, especially OpenSpec archive, as living documentation for releases and rollback.

11. Conclusion

SDD does not replace human judgment. It formalizes discipline.

• Greenfield → constitution first (Spec Kit); OpenSpec specs emerge with the product.
• Brownfield → OpenSpec as default; Spec Kit only for new modules.
• Enterprise → hybrid model: BMAD for innovation, OpenSpec for versioned behavior, ADRs for decisions.

The three frameworks converge on the spec-first principle. They diverge in weight, persistence, and governance. RPI is the cross-cutting layer that stops the agent from jumping straight to code: SDD without RPI becomes documentation the agent ignores; RPI without SDD becomes ephemeral chat without traceability.

Before installing any CLI, map your context on the matrix in section 6. The tool is a consequence of philosophy: not the other way around.

Experiment on personal projects. Calibrate the process. Then scale to enterprise with the confidence of someone who has already seen what works, and what becomes dead documentation.

References

Spec-Driven Development (concept and analysis)

• Martin Fowler: Understanding Spec-Driven Development: Kiro, spec-kit, and Tessl
• OpenSpec: What is Spec-Driven Development?
• Comprehensive Guide to Spec-Driven Development (Medium / Visrow)
• What is BMAD Method? A Simple Guide (Medium / Visrow)
• GitHub Spec Kit vs BMAD Method: Part 1 (Medium / Visrow)

Tools

• GitHub Spec Kit
• BMAD Method: Documentation
• BMAD Method: Workflow Map (BMM)
• BMAD Method: GitHub Repository
• OpenSpec: Official site
• OpenSpec: GitHub Repository
• Kiro Specs: Documentation

Radar and independent evaluation

• Thoughtworks Technology Radar: OpenSpec (Apr/2026)

Agentic workflows

• Research, Plan, Implement (RPI): Kilo Path
• patrob/rpi-strategy: GitHub
• HumanLayer: evolution from RPI to CRISPY (ZenML)

Further reading

• ADR: Practical Guide to Documenting Architecture and Supercharging Generative AI