FeaturedAdvanced~30 minSpec-Driven Dev

Spec-Driven Fullstack Auth

Write a spec, generate linked tasks, and implement JWT authentication using the full SDD workflow with AI.

SDDJWTSpecFull workflow
/kn-init/kn-research/kn-spec/kn-plan/kn-implement/kn-verify
kn-init
kn-research
kn-spec
Review & Approve
kn-plan
kn-implement
kn-verify
kn-extract

Prerequisites

Knowns installed, MCP configured, and a Node.js/Express project ready to go.

What You'll Build

  • A spec document defining auth requirements and acceptance criteria
  • Tasks auto-linked to the spec with fulfills mapping
  • JWT login/register endpoints implemented by AI
  • Verified coverage: every spec AC mapped to a completed task

Initialize Session

Start every session by loading project context.

/kn-init

Your AI reads KNOWNS.md, existing tasks, docs, and memory. It knows your project before writing a line of code.

Research First

Don't skip this step

Before writing a spec or plan, always research the existing codebase. Your AI needs to understand what's already there — existing patterns, conventions, and related code — before it can write a good spec.

/kn-research JWT authentication, middleware pattern, Express route structure

The AI searches your codebase, docs, and memory for relevant context:

AI researching
AI:  Researching "authentication" in project context...

   Found:
   - Doc: @doc/patterns/api-design — REST conventions
   - Memory: "Express + TypeScript, Prisma ORM"
   - Code: src/middleware/ — existing middleware pattern
   - Code: src/routes/ — route structure (router → handler)
   - No existing auth implementation found

   Recommendations:
   1. Follow existing middleware pattern in src/middleware/
   2. Use Prisma for user model (consistent with project)
   3. Express route pattern: router.post('/path', handler)

This context feeds directly into the spec — your AI writes better specs when it understands the project first.

Create the Auth Spec

/kn-spec user-auth

The AI creates a structured spec at .knowns/docs/specs/user-auth.md, informed by the research:

File structure
.knowns/
├── docs/
│   └── specs/
│       └── user-auth.md    ← new spec
├── tasks/
└── config.json
Spec output
# User Authentication Spec

## Overview
JWT-based authentication for the REST API.

## Acceptance Criteria
- AC-1: POST /auth/register creates a user and returns 201
- AC-2: POST /auth/login returns a JWT on valid credentials
- AC-3: POST /auth/login returns 401 on invalid credentials
- AC-4: Protected routes return 401 without a valid token
- AC-5: Passwords are never stored in plain text

Review and edit the spec. When you're satisfied:

knowns doc edit "specs/user-auth" --tags spec --description "JWT auth spec"

Review & Approve the Spec

Gate: Spec must be approved before proceeding

This is a human checkpoint. Read the spec carefully — once approved, kn-plan or kn-go will generate tasks from it. A bad spec leads to bad tasks.

Review the spec for:

  • Completeness — are all requirements covered?
  • Clarity — can each AC be verified objectively?
  • Scope — is it too broad or too narrow?

When you're satisfied, approve it:

You: Spec looks good. Approved.

Two paths after approval

  • /kn-plan --from @doc/specs/user-auth — generates tasks, waits for you to approve each plan before implementing
  • /kn-go specs/user-auth — full autopilot: generates tasks and implements them all without review gates

Generate Tasks from Spec

/kn-plan --from @doc/specs/user-auth

The AI breaks the spec into implementation tasks, each linked via spec and fulfills:

Generated tasks
Task 1: "Setup auth middleware"
→ spec: specs/user-auth
→ fulfills: AC-4

Task 2: "Implement register endpoint"
→ spec: specs/user-auth
→ fulfills: AC-1, AC-5

Task 3: "Implement login endpoint"
→ spec: specs/user-auth
→ fulfills: AC-2, AC-3

Check the board:

knowns task list --plain

Implement Each Task

Work through tasks in order. The AI reads the linked spec and follows your patterns.

/kn-implement <task-id>

For each task, the AI:

  1. Reads the task and its acceptance criteria
  2. Follows the @doc/specs/user-auth reference
  3. Checks project memory for existing patterns
  4. Implements the code
  5. Checks off ACs as they're completed
AI implementing register endpoint
You: /kn-implement abc123

AI:  Reading task abc123: "Implement register endpoint"
   → Spec: @doc/specs/user-auth (AC-1, AC-5)
   → Memory: "Express + TypeScript, Prisma ORM"

   Creating src/routes/auth.ts...
   Creating src/middleware/validate.ts...
   Adding bcrypt password hashing...

   ✓ AC-1: POST /auth/register creates user → implemented
   ✓ AC-5: Passwords hashed with bcrypt → implemented
   ✓ Task marked done, spec ACs auto-synced

Verify Coverage

After all tasks are done, verify that every spec AC is covered:

/kn-verify
Verification result
Spec: specs/user-auth
✓ AC-1: POST /auth/register creates a user and returns 201
✓ AC-2: POST /auth/login returns a JWT on valid credentials
✓ AC-3: POST /auth/login returns 401 on invalid credentials
✓ AC-4: Protected routes return 401 without a valid token
✓ AC-5: Passwords are never stored in plain text

Coverage: 5/5 (100%)
All acceptance criteria verified.

Extract Patterns (Optional)

Save reusable patterns for future sessions:

/kn-extract

The AI saves patterns like:

  • "JWT auth pattern: bcrypt + jsonwebtoken + middleware guard"
  • "Express route structure: router → controller → service"

These persist in project memory and are available in every future session.

Key Takeaways

Traditional approachWith Knowns SDD
Write code, then figure out if it's doneDefine 'done' in a spec before writing code
Tasks are disconnected from requirementsTasks auto-link to spec ACs via fulfills
AI starts blind — no project contextAI researches first, then writes informed specs
Manual checking of requirementsOne command verifies full coverage
Knowledge stays in your headPatterns extracted and saved for reuse

What's next?

Try the AI Task Workflow for a simpler everyday loop, or read the Workflow Guide to choose the right flow for your task.

Back to all articles