Adopt Spec-Driven Development for ThunderID

[brionmario]

The Problem

ThunderID is not one single component.

A single feature, improvement & bug fix touches the core server, multiple SDKs (web, mobile), the CLI, the MCP server, Skills, AI plugins, Documentation, and many more. Right now there is no forcing function that ensures all of these ship together or stay consistent.

Note

SDKs and docs currently live in this monorepo but SDKs will soon be moving to their own repositories. As the ecosystem splits across repos, keeping everything consistent and in sync becomes even harder without a shared contract to anchor against.

On top of that:

• Supporting multiple developer ecosystems: JavaScript, Python, Go, Java, Swift, Kotlin, and more. This means the same identity flows must be implemented correctly on every platform. Doing this manually is unsustainable and error-prone.
• New contributors don't know why something was built a certain way
• AI coding tools lack the context to generate accurate code without extensive hand-holding
• Manually implementing and maintaining SDKs for every platform consumes disproportionate time and resources

Proposed Solution

Specs

Introduce a specs/ folder at the root that will contain living specification documents. Each one encoding a specific contract or definition that the entire ecosystem must honour.

Example:

 .
 ├── backend/
 ├── frontend/
+└── specs/
+    ├── SDK-SPECIFICATION.md
+    └── FEATURE-DEVELOPMENT-SPECIFICATION.md

• SDK-SPECIFICATION.md — defines the canonical contract every ThunderID SDK must implement: flows, error handling, token lifecycle, and platform expectations. A new SDK for any language or framework starts here: implement the spec and ship it.

• FEATURE-DEVELOPMENT-SPECIFICATION.md — defines what "done" means for a feature across the entire ThunderID ecosystem. Every feature must satisfy this spec before it merges — covering the server, all SDKs, CLI, MCP, Skills, AI plugins, and docs.

Skills

Once the specs exist, we wire them into the AI agent workflow via skills in .agent/skills/. A skill for SDK development loads SDK-SPECIFICATION.md; a skill for feature development loads FEATURE-DEVELOPMENT-SPECIFICATION.md. Any contributor or AI agent can invoke the relevant skill and immediately have the full context needed to do the work correctly.

Sample Developer Workflow

Flow

flowchart TD
    A([New Issue / Task]) --> B{Type?}

    B -->|Feature or Bug Fix| C[Invoke `implement-feature` skill]
    B -->|New SDK / SDK Update| D[Invoke `new-sdk` skill]

    C --> E[Skill loads\nFEATURE-DEVELOPMENT-SPECIFICATION.md]
    D --> F[Skill loads\nSDK-SPECIFICATION.md]

    E --> G[AI Agent generates\nDelivery Checklist]
    F --> H[AI Agent scaffolds\nconformant SDK]

    G --> I[Implement across components\nServer · SDKs · CLI · MCP · Skills · AI Plugins · Docs]
    H --> J[Implement SDK\nfor target platform]

    I --> K{DOD checklist\ncomplete?}
    J --> L{Passes\ntest vectors?}

    K -->|No| I
    L -->|No| J

    K -->|Yes| M[Open PR]
    L -->|Yes| M

    M --> N[Review]
    N --> O([Merge])

Loading

Agent Interaction

sequenceDiagram
    actor Dev as Developer / Agent
    participant Skill as .agent/skills/
    participant Spec as specs/
    participant Repo as Repository

    Dev->>Skill: invoke implement-feature OR new-sdk
    Skill->>Spec: load relevant specification
    Spec-->>Skill: specification context
    Skill-->>Dev: full context + scoped instructions

    alt Feature / Bug Fix
        Dev->>Repo: implement server changes
        Dev->>Repo: update SDKs
        Dev->>Repo: update CLI
        Dev->>Repo: update MCP / Skills / AI Plugins
        Dev->>Repo: update Docs
        Dev->>Spec: verify against FEATURE-DEVELOPMENT-SPECIFICATION.md
        Spec-->>Dev: DOD checklist satisfied ✓
    else New SDK / SDK Update
        Dev->>Repo: scaffold SDK for target platform
        Dev->>Spec: verify against SDK-SPECIFICATION.md
        Spec-->>Dev: test vectors passed ✓
    end

    Dev->>Repo: open PR
    Repo-->>Dev: review & merge

Loading

Why This Matters for ThunderID

• SDK leverage: one spec drives every platform SDK; AI generates conformant implementations instead of developers hand-rolling each one
• Ecosystem completeness: every feature ships across the full stack, not just the core server
• Security: reviewers audit the design before a line of code is written
• AI-ready: skills make the specs executable, not just readable
• Contributor clarity: new contributors know exactly what to build and what done looks like

Proposed First Steps

1. Draft specs/SDK-SPECIFICATION.md
2. Draft specs/FEATURE-DEVELOPMENT-SPECIFICATION.md
3. Add skills under .agent/skills/ that invoke the relevant spec
4. Update CONTRIBUTING.md to reference both specs

🔬 Proposed Experiments

• Experiment how we can use Claude's Agent Teams to improve efficiency: https://code.claude.com/docs/en/agent-teams

Projects that adopt a similar approach

• calcom: https://github.com/calcom/cal.diy/tree/main/specs

Open Questions

• Review a draft of [SDK-SPECIFICATION.md](the https://github.com/brionmario/thunder-sdks/blob/main/docs/content/community/contributing/contributing-code/tooling-development/sdk-specification/README.md)
• Any other things to consider?

Looking forward to your thoughts!

[sahandilshan]

+1 on the direction. Two things before this carries real weight:

Enforcement. A spec and a skill are advisory — a PR that updates the server but forgets the SDKs still merges. The real forcing function is a CI check that fails the PR when the spec isn't met. Otherwise drift just moves somewhere prettier.

Test vectors over prose. A written spec drifts from the code over time. Make conformance test vectors the actual contract every SDK must pass, with the markdown as the readable companion — a test can't drift silently, and the vectors are what make "AI generates SDKs" safe.

[brionmario]

+1
We need to govern this from CI static analysis level or with an AI agent itself like Coderabbit.

[ayshsandu]

Related and compliments #3809

[ayshsandu]

further reading about spec driven development - https://developer.microsoft.com/blog/spec-driven-development-spec-kit