Spec-driven development means writing what to build (spec.md), how to build it (plan.md) and an ordered task list (tasks.md) before an AI coding agent writes code. This generator turns your feature idea and user stories into those files in GitHub Spec Kit format, or Kiro's requirements, design and tasks format, with the folder layout, setup script and commands for Claude Code, Codex, Cursor, Copilot or Gemini CLI. Everything runs in your browser.
Format: As a [role], I want to [action], so that [benefit]. Plain sentences work too.
specs/001-team-invite-links/spec.md
File
# Feature Specification: Team invite links
**Feature Branch**: `001-team-invite-links`
**Created**: YYYY-MM-DD
**Status**: Draft
**Input**: User description: "Workspace admins share one link to invite teammates instead of adding each email by hand"
## User Scenarios & Testing *(mandatory)*
### User Story 1 - Create an invite link (Priority: P1)
As a workspace admin, I want to create an invite link, so that teammates can join without me adding each email.
**Why this priority**: This is the core of the feature and the MVP: without it nothing else is useful.
**Independent Test**: Can be fully tested by having a workspace admin create an invite link, and delivers the outcome that teammates can join without them adding each email.
**Acceptance Scenarios**:
1. **Given** a signed-in workspace admin, **When** they create an invite link, **Then** teammates can join without them adding each email.
2. **Given** missing or invalid input, **When** they try to create an invite link, **Then** they see a clear error and nothing changes.
---
### User Story 2 - Join from the link (Priority: P2)
As an invited teammate, I want to join from the link, so that I can start working right away.
**Why this priority**: Adds value on top of User Story 1; build it after the P1 story works on its own.
**Independent Test**: Can be fully tested by having an invited teammate join from the link, and delivers the outcome that they can start working right away.
**Acceptance Scenarios**:
1. **Given** a signed-in invited teammate, **When** they join from the link, **Then** they can start working right away.
2. **Given** missing or invalid input, **When** they try to join from the link, **Then** they see a clear error and nothing changes.
---
### User Story 3 - Revoke an invite link (Priority: P3)
As a workspace admin, I want to revoke an invite link, so that old links stop working.
**Why this priority**: Adds value on top of User Story 2; build it after the P2 story works on its own.
**Independent Test**: Can be fully tested by having a workspace admin revoke an invite link, and delivers the outcome that old links stop working.
**Acceptance Scenarios**:
1. **Given** a signed-in workspace admin, **When** they revoke an invite link, **Then** old links stop working.
2. **Given** missing or invalid input, **When** they try to revoke an invite link, **Then** they see a clear error and nothing changes.
---
### Edge Cases
- What happens when the user lacks permission for the action?
- What happens when two people change the same record at once?
- How does the system respond when a dependency (network, database, third-party API) fails partway?
## Requirements *(mandatory)*
### Functional Requirements
- **FR-001**: System MUST let a workspace admin create an invite link.
- **FR-002**: System MUST let an invited teammate join from the link.
- **FR-003**: System MUST let a workspace admin revoke an invite link.
- **FR-004**: [NEEDS CLARIFICATION: How long should invite links stay valid by default?]
- **FR-005**: [NEEDS CLARIFICATION: Can invited users choose their own role?]
### Key Entities
- **Invite link**: token, workspace, expiry, max uses, created by
- **Membership**: user, workspace, role
## Success Criteria *(mandatory)*
### Measurable Outcomes
- **SC-001**: 90% of workspace admins can create an invite link on the first attempt without help.
- **SC-002**: 90% of invited teammates can join from the link on the first attempt without help.
- **SC-003**: 90% of workspace admins can revoke an invite link on the first attempt without help.
- **SC-004**: [NEEDS CLARIFICATION: performance or business target, for example "page responds in under 1 second at p95"]
## Assumptions
- Existing authentication and roles are reused.
- Out of scope: Sending invite emails.
- Out of scope: SSO and SCIM provisioning.
1. Install Spec Kit (terminal)
# Once per repository. Commit first: --force can replace Spec Kit-managed files.
uv tool install specify-cli
specify init --here --force --integration claude
2. Write all files (setup script)
#!/usr/bin/env bash
# Run from the repository root. Writes the spec files shown above.
set -euo pipefail
mkdir -p 'specs/001-team-invite-links'
mkdir -p '.specify/memory'
cat > 'specs/001-team-invite-links/spec.md' <<'EOF'
# Feature Specification: Team invite links
**Feature Branch**: `001-team-invite-links`
**Created**: YYYY-MM-DD
**Status**: Draft
**Input**: User description: "Workspace admins share one link to invite teammates instead of adding each email by hand"
## User Scenarios & Testing *(mandatory)*
### User Story 1 - Create an invite link (Priority: P1)
As a workspace admin, I want to create an invite link, so that teammates can join without me adding each email.
**Why this priority**: This is the core of the feature and the MVP: without it nothing else is useful.
**Independent Test**: Can be fully tested by having a workspace admin create an invite link, and delivers the outcome that teammates can join without them adding each email.
**Acceptance Scenarios**:
1. **Given** a signed-in workspace admin, **When** they create an invite link, **Then** teammates can join without them adding each email.
2. **Given** missing or invalid input, **When** they try to create an invite link, **Then** they see a clear error and nothing changes.
---
### User Story 2 - Join from the link (Priority: P2)
As an invited teammate, I want to join from the link, so that I can start working right away.
**Why this priority**: Adds value on top of User Story 1; build it after the P1 story works on its own.
**Independent Test**: Can be fully tested by having an invited teammate join from the link, and delivers the outcome that they can start working right away.
**Acceptance Scenarios**:
1. **Given** a signed-in invited teammate, **When** they join from the link, **Then** they can start working right away.
2. **Given** missing or invalid input, **When** they try to join from the link, **Then** they see a clear error and nothing changes.
---
### User Story 3 - Revoke an invite link (Priority: P3)
As a workspace admin, I want to revoke an invite link, so that old links stop working.
**Why this priority**: Adds value on top of User Story 2; build it after the P2 story works on its own.
**Independent Test**: Can be fully tested by having a workspace admin revoke an invite link, and delivers the outcome that old links stop working.
**Acceptance Scenarios**:
1. **Given** a signed-in workspace admin, **When** they revoke an invite link, **Then** old links stop working.
2. **Given** missing or invalid input, **When** they try to revoke an invite link, **Then** they see a clear error and nothing changes.
---
### Edge Cases
- What happens when the user lacks permission for the action?
- What happens when two people change the same record at once?
- How does the system respond when a dependency (network, database, third-party API) fails partway?
## Requirements *(mandatory)*
### Functional Requirements
- **FR-001**: System MUST let a workspace admin create an invite link.
- **FR-002**: System MUST let an invited teammate join from the link.
- **FR-003**: System MUST let a workspace admin revoke an invite link.
- **FR-004**: [NEEDS CLARIFICATION: How long should invite links stay valid by default?]
- **FR-005**: [NEEDS CLARIFICATION: Can invited users choose their own role?]
### Key Entities
- **Invite link**: token, workspace, expiry, max uses, created by
- **Membership**: user, workspace, role
## Success Criteria *(mandatory)*
### Measurable Outcomes
- **SC-001**: 90% of workspace admins can create an invite link on the first attempt without help.
- **SC-002**: 90% of invited teammates can join from the link on the first attempt without help.
- **SC-003**: 90% of workspace admins can revoke an invite link on the first attempt without help.
- **SC-004**: [NEEDS CLARIFICATION: performance or business target, for example "page responds in under 1 second at p95"]
## Assumptions
- Existing authentication and roles are reused.
- Out of scope: Sending invite emails.
- Out of scope: SSO and SCIM provisioning.
EOF
cat > 'specs/001-team-invite-links/plan.md' <<'EOF'
# Implementation Plan: Team invite links
**Branch**: `001-team-invite-links` | **Date**: YYYY-MM-DD | **Spec**: [spec.md](./spec.md)
**Input**: Feature specification from `/specs/001-team-invite-links/spec.md`
## Summary
Workspace admins share one link to invite teammates instead of adding each email by hand. Delivered as 3 independently testable user stories, P1 first.
## Technical Context
**Language/Version**: Next.js 16, TypeScript
**Primary Dependencies**: NEEDS CLARIFICATION: libraries this feature adds, if any
**Storage**: Postgres via Prisma
**Testing**: Vitest and Playwright
**Target Platform**: Web (Vercel)
**Project Type**: web application (frontend + backend)
**Performance Goals**: NEEDS CLARIFICATION
**Constraints**: NEEDS CLARIFICATION
**Scale/Scope**: NEEDS CLARIFICATION
## Constitution Check
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
- [ ] **Test-First**: Write a failing test for each acceptance scenario before the code that makes it pass. No task is done until its tests pass.
- [ ] **Simplicity**: Build only what the spec asks for. No speculative options, abstractions or dependencies; every added dependency is justified in plan.md.
- [ ] **Follow Existing Patterns**: Reuse the codebase's components, helpers, naming and folder layout before adding new ones.
- [ ] **Security by Default**: Validate all input at trust boundaries, check authorization on every request, and never log secrets or personal data.
## Project Structure
### Documentation (this feature)
```text
specs/001-team-invite-links/
├── plan.md # This file
├── research.md # Phase 0: decisions and alternatives
├── data-model.md # Phase 1: entities and fields
├── quickstart.md # Phase 1: how to run and verify
├── contracts/ # Phase 1: API or interface contracts
└── tasks.md # Phase 2: ordered task list
```
### Source Code (repository root)
```text
backend/
├── src/
│ ├── models/
│ ├── services/
│ └── api/
└── tests/
frontend/
├── src/
│ ├── components/
│ ├── pages/
│ └── services/
└── tests/
```
**Structure Decision**: Web application split into backend (models, services, API) and frontend (pages and components). Replace these folders with the repository's real paths.
## Phase 0: Research
- Resolve every NEEDS CLARIFICATION above and in spec.md; record each decision, its rationale and the alternatives considered in research.md.
## Phase 1: Design
- **Invite link**: token, workspace, expiry, max uses, created by (data-model.md)
- **Membership**: user, workspace, role (data-model.md)
- Write the interface contracts in contracts/ and a verification walkthrough in quickstart.md.
## Complexity Tracking
| Violation | Why Needed | Simpler Alternative Rejected Because |
|-----------|------------|-------------------------------------|
| None | | |
EOF
cat > 'specs/001-team-invite-links/tasks.md' <<'EOF'
# Tasks: Team invite links
**Input**: Design documents from `/specs/001-team-invite-links/`
**Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/
**Tests**: Requested. Test tasks come first in each story and must fail before implementation.
## Format: `[ID] [P?] [Story] Description`
- **[P]**: Can run in parallel (different files, no dependencies)
- **[Story]**: Which user story this task belongs to (US1, US2, ...)
## Phase 1: Setup (Shared Infrastructure)
- [ ] T001 Create the folders listed in plan.md Project Structure
- [ ] T002 Add any new dependencies named in plan.md to the project manifest
- [ ] T003 [P] Confirm linting, formatting and the test runner work on a clean checkout
## Phase 2: Foundational (Blocking Prerequisites)
**⚠️ CRITICAL**: No user story work can begin until this phase is complete
- [ ] T004 [P] Create Invite link model in backend/src/models/invite-link.ts
- [ ] T005 [P] Create Membership model in backend/src/models/membership.ts
- [ ] T006 Add the schema migration for Invite link, Membership in Postgres via Prisma
- [ ] T007 Add shared validation, error handling and logging used by every story
**Checkpoint**: Foundation ready - user story implementation can now begin
---
## Phase 3: User Story 1 - Create an invite link (Priority: P1) 🎯 MVP
**Goal**: A workspace admin can create an invite link.
**Independent Test**: Have a workspace admin create an invite link and confirm teammates can join without them adding each email.
### Tests for User Story 1
- [ ] T008 [P] [US1] Integration test for the happy path in backend/tests/integration/create-an-invite-link.test.ts
- [ ] T009 [P] [US1] Test that invalid input shows an error and changes nothing in backend/tests/unit/create-an-invite-link-validation.test.ts
### Implementation for User Story 1
- [ ] T010 [US1] Implement the service logic to create an invite link in backend/src/services/create-an-invite-link.ts
- [ ] T011 [US1] Add the screen and endpoint for "Create an invite link" in frontend/src/pages/create-an-invite-link.tsx
- [ ] T012 [US1] Add validation, permission checks and error messages for this story
**Checkpoint**: User Story 1 works and is testable on its own
---
## Phase 4: User Story 2 - Join from the link (Priority: P2)
**Goal**: An invited teammate can join from the link.
**Independent Test**: Have an invited teammate join from the link and confirm they can start working right away.
### Tests for User Story 2
- [ ] T013 [P] [US2] Integration test for the happy path in backend/tests/integration/join-from-the-link.test.ts
- [ ] T014 [P] [US2] Test that invalid input shows an error and changes nothing in backend/tests/unit/join-from-the-link-validation.test.ts
### Implementation for User Story 2
- [ ] T015 [US2] Implement the service logic to join from the link in backend/src/services/join-from-the-link.ts
- [ ] T016 [US2] Add the screen and endpoint for "Join from the link" in frontend/src/pages/join-from-the-link.tsx
- [ ] T017 [US2] Add validation, permission checks and error messages for this story
**Checkpoint**: User Story 2 works and is testable on its own
---
## Phase 5: User Story 3 - Revoke an invite link (Priority: P3)
**Goal**: A workspace admin can revoke an invite link.
**Independent Test**: Have a workspace admin revoke an invite link and confirm old links stop working.
### Tests for User Story 3
- [ ] T018 [P] [US3] Integration test for the happy path in backend/tests/integration/revoke-an-invite-link.test.ts
- [ ] T019 [P] [US3] Test that invalid input shows an error and changes nothing in backend/tests/unit/revoke-an-invite-link-validation.test.ts
### Implementation for User Story 3
- [ ] T020 [US3] Implement the service logic to revoke an invite link in backend/src/services/revoke-an-invite-link.ts
- [ ] T021 [US3] Add the screen and endpoint for "Revoke an invite link" in frontend/src/pages/revoke-an-invite-link.tsx
- [ ] T022 [US3] Add validation, permission checks and error messages for this story
**Checkpoint**: User Story 3 works and is testable on its own
---
## Phase 6: Polish & Cross-Cutting Concerns
- [ ] T023 [P] Update quickstart.md and user-facing docs
- [ ] T024 Run the full test suite and fix regressions
- [ ] T025 Check every acceptance scenario in spec.md by hand against the running app
## Dependencies & Execution Order
- Setup → Foundational → user stories in priority order (P1 is the MVP; stop and validate after it) → Polish.
- Tasks marked [P] touch different files and can run at the same time, including by parallel agents.
EOF
cat > '.specify/memory/constitution.md' <<'EOF'
# Team invite links Constitution
## Core Principles
### I. Test-First
Write a failing test for each acceptance scenario before the code that makes it pass. No task is done until its tests pass.
### II. Simplicity
Build only what the spec asks for. No speculative options, abstractions or dependencies; every added dependency is justified in plan.md.
### III. Follow Existing Patterns
Reuse the codebase's components, helpers, naming and folder layout before adding new ones.
### IV. Security by Default
Validate all input at trust boundaries, check authorization on every request, and never log secrets or personal data.
## Technology Constraints
- Stack: Next.js 16, TypeScript
- Storage: Postgres via Prisma
- Testing: Vitest and Playwright
## Governance
This constitution overrides other practices. Every plan.md runs the Constitution Check against it, and any violation is justified in Complexity Tracking or removed. Amendments are made in a pull request that updates the version below.
**Version**: 1.0.0 | **Ratified**: YYYY-MM-DD | **Last Amended**: YYYY-MM-DD
EOF
# Lets Spec Kit plan, tasks and implement find this feature without a matching git branch.
mkdir -p .specify
cat > '.specify/feature.json' <<'EOF'
{
"feature_directory": "specs/001-team-invite-links"
}
EOF
echo "Wrote 4 files to specs/001-team-invite-links"
Read specs/001-team-invite-links/spec.md, specs/001-team-invite-links/plan.md, specs/001-team-invite-links/tasks.md, .specify/memory/constitution.md.
First list every NEEDS CLARIFICATION marker and ask me about each one; do not guess.
Then implement specs/001-team-invite-links/tasks.md in order, one phase at a time. Tasks marked [P] can run in parallel.
Check off each task in tasks.md as you finish it. At each Checkpoint, run the tests and stop for my review.
Do not change spec.md without asking me first.
Or let Spec Kit regenerate the files
/speckit-constitution Principles: Test-First, Simplicity, Follow Existing Patterns, Security by Default.
/speckit-specify Workspace admins share one link to invite teammates instead of adding each email by hand. As a workspace admin, I want to create an invite link, so that teammates can join without me adding each email. As an invited teammate, I want to join from the link, so that I can start working right away. As a workspace admin, I want to revoke an invite link, so that old links stop working
/speckit-plan Use Next.js 16, TypeScript. Store data in Postgres via Prisma. Test with Vitest and Playwright
/speckit-tasks
The spec-driven development loop
1. Constitution
Project rules every plan must pass: testing, simplicity, security. Written once per repository.
2. Specify
What and why: user stories, acceptance scenarios, requirements and success criteria. No tech stack.
3. Clarify
The agent asks about every NEEDS CLARIFICATION marker and writes your answers back into the spec.
4. Plan
How: stack, structure, data model and contracts, checked against the constitution.
5. Tasks
An ordered checklist grouped by user story, so P1 ships as an MVP before P2 starts.
6. Implement and converge
The agent works through tasks.md, then converge checks the code against the spec and adds any missing tasks.
Given/When/Then scenarios, FR-001 requirements, T001 tasks with [P] and [US1] markers. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI and many more agents.
EARS acceptance criteria (WHEN … THEN the system SHALL …), a design document, and numbered tasks that link back to requirements. Kiro shows a Start task button above each one.
How to use the spec generator
1. Pick your coding agent
Choose Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI or Kiro. This sets the folder layout and the command spelling.
2. Describe the feature
Write one paragraph on what and why, then list user stories most important first, plus entities, out-of-scope items and open questions.
3. Add the technical context
Enter the stack, storage, test framework and project type, and choose the constitution principles every plan must pass.
4. Write the files and start building
Copy or download each file, or run the setup script from your repository root, then run the agent commands or paste the kickoff prompt.
Tips for specs agents follow well
Keep the stack out of spec.md. Requirements say what users can do; plan.md says how.
Make each user story shippable on its own, and put the MVP first. Stop and test after P1.
Leave unknowns as NEEDS CLARIFICATION instead of guessing. The agent asks before it builds.
Keep one feature per spec. If tasks.md passes about 40 tasks, split the feature.
Commit the spec files with the code so reviewers can check the change against them.
Spec-driven development FAQ
What is spec-driven development?
Spec-driven development is a way of building software with AI coding agents where you first write down what to build and why (spec.md), then how to build it (plan.md), then an ordered checklist of small tasks (tasks.md). The agent implements the tasks one at a time and you review against the spec, instead of steering it with one long chat prompt.
What is GitHub Spec Kit?
Spec Kit is GitHub's open source toolkit for spec-driven development. Its specify CLI installs commands such as specify, plan, tasks, implement and converge into your coding agent, and keeps each feature's files in specs/NNN-feature-name/ with project rules in .specify/memory/constitution.md.
How do I run Spec Kit commands in Claude Code, Codex or Gemini CLI?
The steps are the same but the spelling differs. Claude Code, Cursor and GitHub Copilot use /speckit-specify, Codex uses $speckit-specify, and Gemini CLI uses /speckit.specify. Run them in the agent's chat, not the terminal, one at a time, reviewing each result.
What goes in spec.md, plan.md and tasks.md?
spec.md holds prioritized user stories with Given/When/Then acceptance scenarios, numbered functional requirements, success criteria and open questions, with no tech stack. plan.md holds the stack, project structure and the constitution check. tasks.md holds numbered tasks (T001, T002) grouped by phase and user story, with [P] marking tasks that can run in parallel.
Do I need to install Spec Kit to use these files?
No. Run the setup script to write the files into your repository and give your agent the kickoff prompt: read the three files, ask about every NEEDS CLARIFICATION marker, then work through tasks.md phase by phase. Installing Spec Kit adds the clarify, analyze, implement and converge commands on top.
How is a Kiro spec different from a Spec Kit spec?
Kiro keeps each feature in .kiro/specs/feature-name/ as requirements.md, design.md and tasks.md, and writes acceptance criteria in EARS form such as WHEN an admin revokes a link THEN the system SHALL reject it. Spec Kit uses spec.md, plan.md and tasks.md with Given/When/Then scenarios. Pick Kiro as the agent to get the Kiro layout.
Run the spec, plan, tasks loop as a repeatable workflow
Typing each step into chat works for one feature. Tornic runs deterministic multi-step workflows on the Claude Code, Codex or Cursor CLI you already pay for, so the same spec-to-code pipeline runs the same way every time.