Introducing kspec: Spec-Driven Development for Kiro CL

For enterprises leveraging Amazon Q and Kiro CLI, the promise of AI-assisted development is compelling: faster delivery, reduced cognitive load, and enhanced productivity. But enterprise development demands more than speed — it requires consistency, traceability, and quality assurance.

kspec bridges this gap by bringing specification-driven development (SDD) to Kiro CLI, giving enterprises the structured workflows and verification checkpoints they need to deploy AI-assisted coding with confidence.

The Enterprise Challenge

When adopting AI coding assistants like Kiro CLI and Amazon Q at scale, enterprises face unique challenges:

1. Compliance and Auditability: How do you document what was built and why?

2. Consistency Across Teams: How do you ensure all teams follow the same development standards?

3. Quality Assurance: How do you verify AI-generated code meets specifications?

4. Knowledge Management: How do you capture institutional knowledge from each development cycle?

5. Context Loss: How do you maintain context when AI conversations get compressed?

6. Onboarding: How do new team members understand the codebase and past decisions?

kspec addresses all of these by enforcing a structured, verifiable workflow that integrates seamlessly with Kiro CLI and Amazon Q.

What is kspec?

kspec is a CLI tool that implements specification-driven development for Kiro CLI. It automates a structured workflow that takes you from initial analysis through implementation to final verification, with documentation and verification at every step.

The core philosophy: plan thoroughly, verify constantly, learn continuously.

Two Ways to Use kspec

1. CLI Mode (Outside kiro-cli)

Run kspec commands from your terminal:

kspec init
kspec spec "User Authentication"
kspec tasks
kspec build

2. Agent Mode (Inside kiro-cli) — Recommended

Stay inside your kiro-cli session and switch between specialized agents:

$ kiro-cli
> /agent swap kspec-spec
> Build a todo app with categories
  (agent creates spec.md, spec-lite.md, updates context)
> /agent swap kspec-tasks
  (reads CONTEXT.md → knows current spec → generates tasks)
> /agent swap kspec-build
  (reads CONTEXT.md → continues from current task)

This approach solves the context loss problem — agents read .kspec/CONTEXT.md automatically to restore state after context compression.

The kspec Workflow

kspec follows a linear, nine-step workflow designed for enterprise rigor:

init → analyse → spec → verify-spec → tasks → verify-tasks → build → verify → done

Each step produces documented artifacts, creating a complete audit trail.

1. Initialize (kspec init)

Configure kspec for your project with interactive setup:

• Date format: YYYY-MM-DD, DD-MM-YYYY, or MM-DD-YYYY for organizing specifications

• Execution mode:

  • ask (default) — prompts for confirmation before actions

  • auto — executes without prompts (for CI/CD pipelines)

  • dry-run — shows what would happen without executing (for review)

2. Analyse (kspec analyse)

Before writing specifications, analyze the existing codebase:

• Maps codebase structure and dependencies

• Updates steering documents

• Provides context for Kiro CLI and Amazon Q interactions

• Documents architectural patterns and conventions

3. Create Specification (kspec spec "Feature Name")

Generate detailed specification documents:

• spec.md — comprehensive specification with requirements, acceptance criteria, edge cases

• spec-lite.md — condensed version (<500 words) for context retention after compression

These documents become the source of truth for what needs to be built.

4. Verify Specification (kspec verify-spec)

Before implementation, verify specification completeness:

• All requirements are clearly defined

• Acceptance criteria are measurable and testable

• Edge cases are identified

• Technical approach is documented

This gate prevents incomplete requirements from reaching development.

5. Generate Tasks (kspec tasks)

Convert specifications into actionable implementation tasks:

• Creates structured task list in tasks.md

• Breaks features into manageable, assignable pieces

• Orders tasks logically with dependencies

• Maps each task to specification requirements

6. Verify Tasks (kspec verify-tasks)

Ensure task coverage before implementation begins:

• Every specification requirement maps to tasks

• No gaps between spec and implementation plan

• Dependencies are correctly identified

• Effort distribution is reasonable

7. Build (kspec build)

Execute implementation using Test-Driven Development:

• Follows task list systematically

• Enforces test-first development

• Integrates with Kiro CLI for AI-assisted coding

• Tracks progress through each task

• Updates context after each completed task

8. Verify Implementation (kspec verify)

After building, verify against specifications:

• All acceptance criteria pass

• Tests provide adequate coverage

• Edge cases are handled

• Code meets quality standards

9. Complete (kspec done)

Finalize and capture learnings:

• Mark specification as complete

• Harvest insights into memory.md

• Update project knowledge base

• Generate completion report

Context Management System

One of kspec's most powerful features is its context management system — designed to solve the problem of losing context when AI conversations get compressed.

How It Works

┌─────────────────────────────────────────────────────┐
│ .kspec/CONTEXT.md (auto-generated before each cmd) │
├─────────────────────────────────────────────────────┤
│ # Current Work                                      │
│ Spec: 2026-01-24-user-authentication               │
│ Task: 3/12 - Implement JWT token validation        │
│                                                     │
│ # Requirements Summary (from spec-lite)             │
│ - OAuth2 with Google/GitHub                        │
│ - JWT tokens with 24h expiry                       │
│ - Role-based access control                        │
│                                                     │
│ # Recent Decisions                                  │
│ - Using Supabase Auth for backend                  │
│ - Storing refresh tokens in httpOnly cookies       │
└─────────────────────────────────────────────────────┘

Context Restoration After Compression

─── CONTEXT COMPRESSION HAPPENS ───
> /agent swap kspec-build
  (agent reads CONTEXT.md → fully restored!)
  "Continuing with task 3/12: Implement JWT token validation..."

View or Refresh Context

kspec context

This command displays and refreshes the context file manually.

Project Structure

kspec maintains organized documentation in .kspec:

.kspec/
├── config.json          # Project configuration
├── .current             # Current active spec path
├── CONTEXT.md           # Auto-generated context for agents
├── memory.md            # Project-wide learnings and patterns
└── specs/
    └── [date]-[feature]/
        ├── spec.md      # Full specification (audit artifact)
        ├── spec-lite.md # Condensed specification (<500 words)
        ├── tasks.md     # Implementation task breakdown
        └── memory.md    # Feature-specific learnings

This structure provides:

• Auditability: Complete history of what was specified and built

• Traceability: Clear links between requirements and implementation

• Context Retention: spec-lite.md preserves key info after compression

• Knowledge Base: Accumulated learnings for future development

Kiro CLI Integration

kspec generates seven specialized agents installed to .kiro/agents/:

| Shortcut | Agent | Purpose |

|----------|-------|---------|

| Ctrl+Shift+A | kspec-analyse | Codebase analysis |

| Ctrl+Shift+S | kspec-spec | Specification creation |

| Ctrl+Shift+T | kspec-tasks | Task generation |

| Ctrl+Shift+B | kspec-build | TDD implementation |

| Ctrl+Shift+V | kspec-verify | Implementation verification |

| Ctrl+Shift+R | kspec-review | Code review |

| Ctrl+Shift+J | kspec-jira | Jira integration |

Agent Features

All agents are configured with:

• CONTEXT.md as first resource — for automatic state restoration

• Steering file access — reads .kiro/steering/**/*.md

• Kspec file access — reads .kspec/**/*.md

• Workflow prompts — agents know what to do autonomously

Switching Agents Inside kiro-cli

> /agent swap kspec-spec
Ready to create specification. Describe your feature.
> Build a real-time chat application with rooms
(agent creates spec folder, spec.md, spec-lite.md, updates .current and CONTEXT.md)
After completion: "Switch to kspec-tasks agent to generate implementation tasks"

Enterprise Benefits

Compliance and Auditability

Every feature developed with kspec produces documented artifacts:

• Specification documents capture requirements

• Verification steps are logged

• Memory files document decisions and rationale

• Context files track progress and state

This creates an audit trail for compliance requirements.

Consistency Across Teams

kspec enforces the same workflow regardless of who's developing:

• All features follow the same specification format

• Verification gates ensure quality standards

• Memory system shares patterns across teams

• Context system maintains state across sessions

Quality Assurance

The dual verification system catches issues early:

verify-spec catches requirement problems:

• Missing acceptance criteria

• Unclear edge cases

• Incomplete technical approach

verify-tasks catches planning problems:

• Tasks that don't cover requirements

• Missing dependencies

• Incorrect sequencing

Context Engineering

kspec solves the "context loss" problem that plagues long AI sessions:

• spec-lite.md — concise requirements survive compression

• CONTEXT.md — auto-updated with current state, task progress, decisions

• Agent resources — CONTEXT.md is first resource for all agents

• Workflow prompts — agents read context before acting

Knowledge Management

The memory system captures institutional knowledge:

Project memory stores:

• Architectural decisions and rationale

• Common patterns and conventions

• Cross-cutting concerns

• Team standards

Feature memory captures:

• Implementation insights

• Problems and solutions

• Performance considerations

• Technical debt identified

Onboarding Acceleration

New team members can:

• Review past specifications to understand features

• Read memory files to learn patterns and decisions

• Follow the same workflow immediately

• Contribute with consistent quality from day one

Getting Started

Prerequisites

• Node.js 18 or higher

• Kiro CLI or Amazon Q CLI

• Optionally, Kiro IDE

Installation

npm install -g kspec

Quick Start

# Initialize in your project
kspec init
# Analyze codebase
kspec analyse
# Create your first specification
kspec spec "My Feature"
# Check context
kspec context
# Check status anytime
kspec status
# List all specifications
kspec list

Command Reference

| Command | Purpose |

|---------|---------|

| kspec init | Interactive project setup |

| kspec analyse | Analyze codebase, update steering |

| kspec spec "Feature" | Create specification |

| kspec verify-spec | Verify spec completeness |

| kspec tasks | Generate implementation tasks |

| kspec verify-tasks | Verify task coverage |

| kspec build | Execute tasks with TDD |

| kspec verify | Verify implementation |

| kspec done | Complete spec, harvest memory |

| kspec context | View/refresh context file |

| kspec status | Show current progress |

| kspec list | List all specifications |

| kspec review | Code review |

| kspec agents | List available agents |

Jira Integration Commands (requires Atlassian MCP)

| Command | Purpose |

|---------|---------|

| kspec spec --jira PROJ-123 | Create spec from Jira issues |

| kspec sync-jira | Create Jira issue from spec |

| kspec sync-jira --update PROJ-123 | Update existing Jira issue |

| kspec jira-subtasks | Create Jira subtasks from tasks.md |

Jira Integration: Bridging BA and Development

One of the biggest challenges in enterprise development is bridging the gap between business analysts (BAs), product managers (PMs), and developers. Requirements live in Jira, but developers work in code. kspec bridges this gap.

Pull Requirements from Jira

# Create spec from Jira stories
kspec spec --jira PROJ-123,PROJ-456 "User Authentication"

This command:

1. Fetches issue details from Jira via Atlassian MCP

2. Extracts acceptance criteria and requirements

3. Creates a consolidated spec.md with source attribution

4. Links back to original Jira issues for traceability

Push Specifications to Jira

# Create new Jira issue from spec
kspec sync-jira
# Update existing issue
kspec sync-jira --update PROJ-789

This allows:

• BAs to review technical specifications in their familiar Jira interface

• Clear audit trail of what was specified vs. what was requested

• Easy approval workflow before development begins

Create Subtasks from Tasks

# After generating tasks.md
kspec jira-subtasks PROJ-789

This:

• Creates Jira subtasks for each implementation task

• Enables progress tracking in Jira

• Gives visibility to PMs without requiring terminal access

Prerequisites

Jira integration requires the Atlassian MCP server configured in ~/.kiro/mcp.json:

{
  "mcpServers": {
    "atlassian": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-atlassian"],
      "env": {
        "ATLASSIAN_HOST": "https://your-domain.atlassian.net",
        "ATLASSIAN_EMAIL": "[email protected]",
        "ATLASSIAN_API_TOKEN": "your-api-token"
      }
    }
  }
}

Enterprise Best Practices

1. Establish Specification Templates

Create organization-specific templates for spec.md that include required sections for your compliance needs.

2. Integrate with CI/CD

Use dry-run mode in pipelines to validate specifications before merging:

kspec verify-spec --mode=dry-run

3. Regular Memory Reviews

Schedule periodic reviews of project memory to:

• Identify patterns worth standardizing

• Update outdated guidance

• Share learnings across teams

4. Link to Issue Tracking

Reference issue tracker IDs in specifications for traceability:

## Related Issues
- JIRA-1234: User authentication requirements
- JIRA-1235: Security review findings

5. Use Agent Mode for Long Sessions

For extended development sessions, use agent mode inside kiro-cli:

• Context is automatically maintained

• State survives context compression

• Seamless workflow transitions

6. Code Review Integration

Use kspec review as part of your PR process to ensure implementations match specifications.

Why kspec for Amazon Q Enterprises?

Organizations investing in Amazon Q and Kiro CLI need tooling that matches their commitment to AI-assisted development. kspec provides:

• Structured workflows that complement Kiro CLI's capabilities

• Context management that survives AI context compression

• Verification gates that ensure AI-generated code meets requirements

• Documentation artifacts that satisfy enterprise compliance needs

• Knowledge capture that compounds the value of every feature built

kspec doesn't replace Kiro CLI — it amplifies its value by adding the structure, context management, and verification enterprises require.

Conclusion

For enterprises leveraging Amazon Q and Kiro CLI, kspec provides the missing piece: structured, verifiable, context-aware development workflows. By enforcing specification-driven development with verification at every step, kspec helps organizations:

• Deploy AI-assisted coding with confidence: Verification gates ensure quality

• Maintain context across sessions: CONTEXT.md and spec-lite.md prevent context loss

• Meet compliance requirements: Complete audit trail of specifications and decisions

• Scale consistently: Same workflow across all teams and projects

• Accumulate knowledge: Memory system captures learnings for continuous improvement

Whether you're piloting AI-assisted development or scaling across the organization, kspec provides the enterprise-grade structure your Amazon Q investment deserves.

Resources

• npm: npmjs.com/package/kspec

• GitHub: github.com/sanjeevkumarraob/kspec

• License: MIT

kspec is developed by Sanjeev Kumar Badrinath and is open source under the MIT license.