kspec — Spec-Driven Development for Kiro CLI

Spec-driven development workflow for Kiro CLI with context management, verification at every step, and Jira integration.

What's new in 2.3.0

| Area | What you get | |---|---| | Kiro V3 early access | kspec engine set v3 generates JSON agents with tag-based tools, capability permissions (+ toolsSettings), and standalone V3 hooks; V2 remains the default | | Native specs | New V3 work uses requirements.md; legacy spec.md remains supported and can be converted with kspec migrate-spec | | Reliable active context | Every custom agent and /kspec-* skill resolves .kiro/.current, refreshes CONTEXT.md through kspec, and reads active artifacts | | Lean prompts | Historical .kiro/specs/**/*.md files are no longer loaded into every agent request | | Current CLI support | Persistent model inheritance, --effort, KIRO_HOME, official installer URL, and explicit V2 CI |

See CHANGELOG for the full release notes.

What's new in 2.2.0

| Area | What you get | |---|---| | Enterprise governance | kspec init --enterprise (or KSPEC_ENTERPRISE=1) — single opt-in prompt that scaffolds an MCP-registry / model-registry / IdP / prompt-logging governance steering doc auto-loaded into every agent prompt | | CI/headless mode | kspec init --ci scaffolds .github/workflows/kspec-review.yml running kspec review --no-interactive on every PR + a CI hooks preset (preToolUse audit + destructive-command block) | | Least-privilege agents | Every agent now ships with toolsSettings: write paths scoped per-role, shell commands allow/denylisted, secrets/git/node_modules always-denied, explicit subagent.availableAgents delegation graph | | Kiro Agent Skills | 5 SKILL.md files (/kspec-spec, /kspec-build, /kspec-review, /kspec-verify, /kspec-jira) — auto-become slash commands in CLI 2.1+ default chat | | All-MCP injection | kspec-spec and the spec/build/review pipeline now see every configured MCP (not just Atlassian) — @github, @confluence, @slack, etc. | | kspec sync-agents | Refresh agent JSON + IDE markdown after adding a new MCP — no full kspec init re-run | | IDE chat subagents | Optional .md agent files alongside .json so Kiro IDE chat can use kspec workflows | | Smart steering | inclusion: fileMatch so api-standards.md, frontend.md, backend.md only auto-load when matching files are touched. Existing inclusion_mode files migrated transparently |

See CHANGELOG for the full release notes.

Why kspec?

AI coding assistants forget context, drift from requirements, and repeat mistakes. kspec solves this:

| Problem | kspec Solution | |---------|---------------| | Context loss | CONTEXT.md survives AI context compression | | Scope creep | Specs define boundaries before coding | | No verification | Verify at every step (spec → design → tasks → build) | | Lost learnings | memory.md compounds knowledge across projects | | Enterprise silos | Jira integration bridges BA/PM and developers |

Read the full Methodology or see a complete Example Walkthrough.

Installation

npm install -g kspec

Quick Start

kspec init                    # Interactive setup
kspec analyse                 # Analyse codebase
kspec spec "User Auth API"    # Create specification
kspec design                  # Create technical design (optional)
kspec tasks                   # Generate tasks
kspec build                   # Execute with TDD
kspec verify                  # Verify implementation
kspec done                    # Complete & harvest memory

Two Ways to Use kspec

1. CLI Mode (Outside kiro-cli)

Run kspec commands from your terminal:

kspec init
kspec spec "User Authentication"
kspec design                       # optional — creates design.md
kspec tasks
kspec build

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

Stay inside your kiro-cli session and switch between specialized agents. Every agent includes pipeline navigation suggesting the next step:

$ kiro-cli

> /agent swap kspec-spec
> Build a todo app with categories
  (agent creates requirements.md on V3 or spec.md on V2, plus spec-lite.md)
  → Next: /agent swap kspec-design or /agent swap kspec-tasks

> /agent swap kspec-design
  (reads spec → creates design.md with architecture)
  → Next: /agent swap kspec-tasks

> /agent swap kspec-tasks
  (reads CONTEXT.md + design.md → generates tasks)
  → Next: /agent swap kspec-build

> /agent swap kspec-build
  (reads CONTEXT.md → continues from current task)
  → Next: /agent swap kspec-verify

This approach solves the context loss problem — agents read .kiro/CONTEXT.md automatically to restore state after context compression. You never need to exit kiro-cli; the full pipeline is available through agent swapping.

Workflow

init → analyse → spec → verify-spec → design (optional) → tasks → verify-tasks → build → verify → done

Commands

Core Workflow

| Command | Description | |---------|-------------| | kspec init | Interactive setup (date format, execution mode, Jira project, enterprise opt-in) | | kspec init --enterprise | Skip the prompt — go straight into governance setup (MCP/model registries, IdP, prompt logging) | | kspec init --ci | Setup with GitHub Actions workflow + CI hooks preset (audit + destructive-block) | | kspec sync-agents | Refresh agent JSON/markdown after adding a new MCP server (idempotent) | | kspec engine status | Show the selected engine and detected Kiro CLI version | | kspec engine set v2\|v3 [--dry-run] | Validate, back up, and regenerate agents/hooks for one engine | | kspec use <spec> | Select the active spec and refresh deterministic context | | kspec migrate-spec <spec> [--dry-run] [--yes] | Reversibly convert legacy spec.md to native requirements.md | | kspec analyse | Analyse codebase, update steering docs | | kspec spec "Name" | Create active-engine requirements + spec-lite.md | | kspec verify-spec | Interactively review and shape spec with clarifying questions | | kspec design | Create technical design from spec (optional) | | kspec verify-design | Verify design against spec requirements | | kspec tasks | Generate tasks.md from spec (uses design.md if present) | | kspec verify-tasks | Verify tasks cover spec | | kspec build | Execute tasks with TDD | | kspec verify | Verify implementation matches spec | | kspec done | Complete spec, harvest memory |

Jira Integration (requires Atlassian MCP)

| Command | Description | |---------|-------------| | kspec spec --jira PROJ-123,PROJ-456 "Feature" | Create spec from Jira issues | | kspec sync-jira | Smart sync — updates existing issue or creates new | | kspec sync-jira --create | Force create new Jira issue | | kspec sync-jira --project SECOPS | Create in specific project | | kspec sync-jira --update PROJ-123 | Update existing Jira issue | | kspec jira-pull | Pull latest updates from linked Jira issues | | kspec jira-subtasks | Create Jira subtasks from tasks.md | | kspec jira-subtasks PROJ-123 | Create subtasks under specific issue |

Rally / Azure DevOps / GitHub Issues

| Command | Description | |---------|-------------| | kspec rally-pull US123456 | Pull Rally work item context + change report | | kspec sync-rally | Smart sync — update linked Rally item or create new | | kspec sync-rally --create --tags "qms,sdd" | Force-create with tags | | kspec rally-tasks US123456 | Create Rally tasks from tasks.md | | kspec ado-pull 12345 | Pull Azure DevOps work item context + change report | | kspec sync-ado --update 12345 | Update an Azure DevOps work item | | kspec ado-tasks 12345 | Create ADO child tasks from tasks.md | | kspec github-pull owner/repo#123 | Pull GitHub issue context + change report | | kspec sync-github --repo owner/repo | Smart sync to GitHub Issues | | kspec github-tasks owner/repo#123 | Create task issues from tasks.md |

Requires the matching MCP (rally, azure-devops, or github). After upgrading kspec, run kspec sync-agents to add the new agents/skills.

Work Types (Abbreviated Pipelines)

| Command | Description | |---------|-------------| | kspec fix "Bug description" | Bug fix with TDD (spec→test→fix→verify) | | kspec refactor "What and why" | Refactor code (no behavior change) | | kspec spike "Question" | Time-boxed investigation (no code) | | kspec revise | Revise spec from stakeholder feedback | | kspec demo | Generate stakeholder walkthrough | | kspec estimate | Assess complexity before building |

Memory, Milestones & Observability

| Command | Description | |---------|-------------| | kspec memory | Show project memory | | kspec memory review | AI-assisted memory review | | kspec memory prune | Remove outdated entries | | kspec milestone list | List milestones | | kspec milestone create <name> | Create milestone | | kspec milestone add <name> | Add current spec to milestone | | kspec milestone status <name> | Show milestone progress | | kspec metrics | Show timeline for current spec |

Agentic Review Loop

| Command | Description | |---------|-------------| | kspec review [target] | Code review with agentic loop (if reviewers configured) | | kspec review --simple | Quick review without loop | | kspec analyse | Analyse codebase with review loop | | kspec analyse --no-review | Skip review loop | | kspec build --review | Build with agentic review loop |

Other

| Command | Description | |---------|-------------| | kspec refresh | Regenerate spec-lite.md after editing spec.md | | kspec context | View/refresh context file | | kspec list | List all specs | | kspec status | Pipeline-aware status with next step suggestion | | kspec agents | List available agents | | kspec update | Check for updates | | kspec help | Show help |

Work Types

Not everything needs the full spec pipeline. kspec provides entry points for different work types:

Bug Fix

kspec fix "Login fails with special characters"

Or in kiro-cli:

> /agent swap kspec-fix
> Login fails when email contains + character. Error in auth.js line 42.

Refactor

kspec refactor "Extract validation logic from controllers"

Or in kiro-cli:

> /agent swap kspec-refactor
> Extract all validation logic from route controllers into a shared validation middleware

Spike (Investigation)

kspec spike "Can we migrate from REST to GraphQL?"

Or in kiro-cli:

> /agent swap kspec-spike
> Investigate feasibility of migrating our REST API to GraphQL

Revise (Feedback Loop)

kspec revise    # revise current spec from feedback

Or in kiro-cli:

> /agent swap kspec-revise
> PM says we need to add OAuth support and remove the remember-me feature

Demo (Stakeholder Walkthrough)

kspec demo      # generate walkthrough of current implementation

Estimate (Complexity Assessment)

kspec estimate  # assess before committing to build

Design Pipeline

The optional design step sits between spec and tasks, enabling technical architecture planning before implementation:

kspec spec "Payment Processing"    # Create spec
kspec design                       # Create design.md (architecture, data models, APIs)
kspec verify-design                # Verify design covers spec
kspec tasks                        # Generate tasks (uses design.md for ordering)

design.md includes:

• Architecture Overview
• Component Breakdown
• Data Models
• API Contracts
• Dependency Mapping
• Technical Decisions
• Risk Assessment

The design step is optional — run kspec tasks directly to skip it. When design.md exists, the tasks agent uses it for architecture guidance and dependency ordering.

Interactive Spec Shaping

kspec verify-spec goes beyond simple PASS/FAIL verification. It interactively shapes your spec:

1. Reads your spec.md thoroughly
2. Asks 4-8 targeted clarifying questions with sensible defaults
3. Proposes assumptions: "I assume X, is that correct?"
4. Waits for your responses
5. Suggests specific updates to spec.md
6. Gets your confirmation before making changes

This ensures specs are complete and unambiguous before moving to design or tasks.

Jira Pull Updates

Keep specs in sync with evolving Jira requirements:

kspec jira-pull

This fetches the latest state of all linked Jira issues, generates a change report showing new/modified criteria, status changes, and comments, then presents changes for your approval before modifying spec.md. Specs are never auto-updated.

Agentic Review Loop

kspec implements a devil's advocate pattern for code review, using multiple AI CLI tools as reviewers.

How It Works

1. Doer (kspec-review agent) performs the initial review
2. Reviewer (configured external CLIs) critiques the doer's work
3. Loop continues up to 3 rounds until approved or questions remain
4. Human-in-the-loop surfaces unresolved questions for your input

Configure Reviewers

During kspec init, select which CLIs to use as reviewers:

• GitHub Copilot CLI (copilot)
• Gemini CLI (gemini)
• Claude Code CLI (claude)
• OpenAI Codex CLI (codex)
• Aider (aider)

Or configure manually in .kiro/config.json:

{
  "reviewers": ["copilot", "claude", "gemini"]
}

Usage

# Review recent changes (uses configured reviewers)
kspec review

# Review specific target
kspec review "src/auth/*.js"

# Quick review without agentic loop
kspec review --simple

# Build with review loop
kspec build --review

Session Files

Review sessions are logged to .kiro/sessions/ with full transcripts:

.kiro/sessions/review-pr-2026-03-04T20-29-38-940Z.md

Each session captures doer output, reviewer critiques, and final status (APPROVED, NEEDS_CHANGES, or NEEDS_HIL).

Contracts (Beta)

Enforce structured outputs and non-negotiable checks in your spec. This prevents context loss and regression by ensuring specific files and patterns exist before verification proceeds.

Add a ## Contract section to your spec.md:

## Contract

\`\`\`json
{
  "output_files": ["package.json", "src/index.js"],
  "checks": [
    { "type": "contains", "file": "package.json", "text": "\"name\": \"my-app\"" }
  ]
}
\`\`\`

kspec verify will automatically validate these rules.

See Contracts Documentation for full details.

Enterprise Governance

For teams operating under SOC2, regulated environments, or any org with central control over MCP/model usage. All four governance settings are off by default: kspec asks once during kspec init whether to configure them, and the prompt only fires when you opt in.

How to enable

# Option 1 — opt in interactively
kspec init
> Configure enterprise governance? (MCP/model registries, prompt logging, IdP) (y/N): y

# Option 2 — flip the prompt default to Yes for the whole org
export KSPEC_ENTERPRISE=1   # in dev container / shell init
kspec init                  # prompt now defaults Y, devs can still opt out per-project

# Option 3 — non-interactive (CI / org templates)
kspec init --enterprise

What it configures

| Setting | What it does | Why it matters | |---|---|---| | MCP registry URL | Admin-hosted JSON allow-list of approved MCP servers. Kiro fetches it every 24h and auto-revokes unapproved servers | Central fleet control, automatic revocation | | Model registry URL | Admin-hosted approved-models list. Off-policy model: fields get rewritten to the org default | Cost control + regulatory model whitelisting | | Identity provider | Okta / Microsoft Entra ID / AWS IAM Identity Center / Other | Required for the above governance features | | Prompt logging | Documents (in steering) that prompts are recorded by Kiro for SOC2 / regulatory audit | Surfaces "don't paste secrets" guidance to every agent |

What it ships

Opting in writes .kiro/steering/enterprise-governance.md with inclusion: always, so every agent loads it as context. It substitutes your registry URLs and IdP into the doc and reminds agents to:

• Cite governance gaps in spec output instead of silently ignoring them
• Surface model/MCP needs as questions rather than guessing
• Treat audit.log and .kiro/sessions/ as evidence (don't delete)

See Kiro enterprise governance docs for the upstream feature spec.

CI/CD Integration

kspec init --ci scaffolds two things so kspec runs on every PR:

1. GitHub Actions workflow

Drops .github/workflows/kspec-review.yml:

name: kspec review
on:
  pull_request:
    types: [opened, synchronize, reopened]
jobs:
  kspec-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: curl -fsSL https://cli.kiro.dev/install | bash
      - run: npm install -g kspec
      - env: { KIRO_API_KEY: ${{ secrets.KIRO_API_KEY }} }
        run: kspec review --engine v2 --simple --trust-tools=read,shell --no-interactive
      # ...posts review as PR comment via actions/github-script

You only need to add KIRO_API_KEY as a repo secret — everything else is wired up.

2. CI hooks preset

V2 hooks are embedded in generated agent profiles; V3 uses .kiro/hooks/kspec.json. They refresh context on agent/session start and apply the destructive-command guard before shell execution. The generated headless CI workflow remains explicitly V2.

Powered by Kiro CLI 2.0+ headless mode (--no-interactive, KIRO_API_KEY, --trust-tools). See Kiro headless docs.

Agent Skills (Kiro CLI 2.1+)

In addition to the JSON custom agents (/agent swap kspec-spec), kspec ships Agent Skills as .kiro/skills/<name>/SKILL.md. In Kiro CLI 2.1+ these auto-become slash commands in the default chat agent — no /agent swap required.

> /kspec-spec
> Build a payment processing feature
  (clarifies → active requirements → spec-lite.md)

> /kspec-build
  (executes tasks with strict TDD)

> /kspec-review
  (multi-CLI parallel review)

5 skills shipped: kspec-spec, kspec-build, kspec-review, kspec-verify, kspec-jira. Created when you answer Y to "Create Kiro Agent Skills?" during kspec init (default Yes). See Kiro skills docs.

Every skill reads .kiro/.current, refreshes through kspec context --stdout, reads .kiro/CONTEXT.md, and then loads the active requirements/tasks. Skills never write CONTEXT.md directly.

Agent Permissions (Least-Privilege)

V2 and V3 agents are JSON configs in .kiro/agents/. V2 uses toolsSettings; V3 adds capability-based permissions and keeps toolsSettings (kiro-cli 2.11 skips permissions-only agents on discovery, so both are shipped). Both retain the same role-based filesystem, shell, MCP, secret, and subagent boundaries.

| Agent type | Write paths | Shell scope | |---|---|---| | State-only (analyse, context, refresh, jira, demo, estimate) | .kiro/** | none | | Spec pipeline (spec, design, tasks, revise, spike) | .kiro/** (+ AGENTS.md for spec) | none | | Verifiers (verify, review) | .kiro/** | read-only commands + test runners | | Code-modifying (build, fix, refactor) | .kiro/**, src/**, lib/**, test/**, *.ts/.js/.py/.go/.rs, ... | npm/pnpm/yarn, pytest, go test, cargo, git status/diff/add/commit |

Universal denylist (all agents): .env*, **/secrets/**, **/credentials/**, *.pem, *.key, .git/**, node_modules/**, vendor/**, dist/**, build/**.

Shell denylist (build/verify/review): rm -rf, git push, git reset --hard, sudo, curl, wget, npm publish, pip install, apt.

Subagent delegation graph — every agent declares an explicit availableAgents list (e.g. kspec-build → [verify, review, fix], kspec-verify → [] terminal). Makes the call graph auditable and admin-restrictable. See Kiro custom agents reference.

Powers

Powers are modular knowledge files that enhance AI agent capabilities. kspec ships with 5 powers:

| Power | Description | |-------|-------------| | contract | Enforce structured outputs and checks in specs | | document | Documentation best practices (README, CONTRIBUTING, CHANGELOG, ADRs) | | tdd | Test-driven development patterns and workflows | | code-review | Code review checklists and quality standards | | code-intelligence | Tree-sitter and LSP setup for enhanced AI assistance |

In Kiro IDE: Open the Powers panel and install from this repository's powers/ directory.

With kspec CLI: Powers are reference documentation in the powers/ directory. Agents can read them for context.

Custom Powers: Create your own in powers/{name}/POWER.md following the Kiro power format.

Steering Documents

Steering files in .kiro/steering/ are project rules that agents load as context. kspec ships 7 templates with Kiro-native inclusion modes:

| File | Inclusion | When it loads | |---|---|---| | product.md | always | Every prompt | | tech.md | always | Every prompt | | testing.md | always | Every prompt | | security.md | always | Every prompt | | api-standards.md | fileMatch | When **/api/**, **/routes/**, **/handlers/**, **/controllers/** files are touched | | frontend.md | fileMatch | When **/*.tsx, **/*.jsx, **/components/**, **/styles/**, **/*.css files are touched | | backend.md | fileMatch | When **/server/**, **/services/**, **/db/**, **/migrations/** files are touched |

fileMatch keeps context small in monorepos — frontend rules don't pollute backend agent prompts.

Non-destructive merge

If a steering file already exists (e.g. from base Kiro IDE init), kspec init merges instead of overwriting:

• Missing H2 sections are appended with a <!-- added by kspec --> marker
• Missing frontmatter keys are added; existing values never overwritten
• Files outside the 7 known templates are left fully untouched

Legacy inclusion_mode: on_demand files are auto-migrated to inclusion: auto on next init.

Context Management

kspec maintains a deterministic active-work snapshot regenerated from source artifacts:

.kiro/CONTEXT.md (auto-generated, max 8 KiB)
├── Active spec, format, phase, type, milestone
├── Nested task progress, current chunk and task
├── Design and Jira status
├── Requirements summary and recent decisions
└── Next action

Every custom agent and /kspec-* Agent Skill resolves .kiro/.current, runs kspec context --stdout, reads CONTEXT.md, and then reads the active requirements and tasks. Source artifacts remain authoritative, and kspec is the only writer of CONTEXT.md.

kspec context             # Refresh and view context
kspec context --stdout    # Hook/agent-safe output without the footer
kspec use <spec>          # Select the active spec

Or refresh inline without leaving kiro-cli:

> /agent swap kspec-context

Compaction creates a new Kiro session and reloads persistent resources. Session-start hooks and the Agent Skill preflight regenerate the snapshot before it is consumed.

Native Kiro session controls

kspec does not wrap controls Kiro already provides:

• /goal runs an iterative, completion-checked loop for longer work.
• Queue steering redirects active work at the next tool boundary; Ctrl+S toggles steer/queue behavior.
• /rewind branches from an earlier turn without changing the original session.
• /transcript save exports the current conversation as Markdown, plaintext, or JSON.

Agents & Shortcuts

| Agent | Shortcut | Purpose | |-------|----------|---------| | kspec-analyse | Ctrl+Shift+A | Analyse codebase, update steering | | kspec-spec | Ctrl+Shift+S | Create specifications | | kspec-design | Ctrl+Shift+D | Create technical design from spec | | kspec-tasks | Ctrl+Shift+T | Generate tasks (uses design if present) | | kspec-build | Ctrl+Shift+B | Execute tasks with TDD | | kspec-verify | Ctrl+Shift+V | Verify spec/design/tasks/implementation | | kspec-review | Ctrl+Shift+R | Code review (+ configured reviewers) | | kspec-jira | Ctrl+Shift+J | Jira integration (pull, sync, subtasks) | | kspec-fix | Ctrl+Shift+F | Fix bugs (abbreviated pipeline) | | kspec-refactor | Ctrl+Shift+G | Refactor code (no behavior change) | | kspec-spike | Ctrl+Shift+I | Investigate/spike (no code) | | kspec-revise | Ctrl+Shift+E | Revise spec from feedback | | kspec-demo | Ctrl+Shift+W | Generate stakeholder walkthrough | | kspec-estimate | Ctrl+Shift+X | Assess complexity | | kspec-context | Ctrl+Shift+C | Refresh CONTEXT.md inline | | kspec-refresh | — | Generate AI summary of spec |

Switch agents in kiro-cli: /agent swap kspec-build or use keyboard shortcuts.

Every agent includes a PIPELINE section suggesting contextual next steps — so you can navigate the full workflow without leaving kiro-cli.

Context Refresh After /compact

Kiro compaction creates a new session and reloads resources. The session-start hook refreshes context automatically. You can also refresh it explicitly:

> /agent swap kspec-context

The context agent delegates to kspec context --stdout; it never writes its own alternate snapshot format.

ACP (Agent Client Protocol)

ACP enables Kiro to work with JetBrains IDEs (IntelliJ, WebStorm, PyCharm) and Zed editor.

JetBrains Setup

Create or edit ~/.jetbrains/acp.json:

{
  "agent_servers": {
    "Kiro Agent": {
      "command": "/full/path/to/kiro-cli",
      "args": ["acp"]
    }
  }
}

Replace /full/path/to/kiro-cli with the actual path (find with which kiro-cli). Restart your IDE after configuration.

Once ACP is configured, kspec agents work the same way as in Kiro IDE. Your .kiro/agents/ configurations are loaded automatically.

See: https://kiro.dev/docs/cli/acp/

Code Intelligence

Kiro includes built-in code intelligence powered by tree-sitter, with optional LSP integration for deeper analysis.

/code init      # Index your project
/code status    # Check indexing status

This enables structural code understanding (symbols, references, definitions) for 18 languages. See the code-intelligence power for detailed setup and usage guide.

See: https://kiro.dev/docs/cli/code-intelligence/

Structure

.kiro/
├── config.json           # User preferences (commit)
├── .current              # Current active spec path (local only)
├── CONTEXT.md            # Auto-generated context (local only)
├── memory.md             # Project learnings (commit)
├── specs/
│   └── 2026-01-22-feature/
│       ├── requirements.md # Kiro V3 requirements (commit)
│       ├── spec.md       # Legacy requirements (supported)
│       ├── contract.json # V3 structured output contract (optional)
│       ├── spec-lite.md  # Concise (for context compression)
│       ├── design.md     # Technical design (commit, optional)
│       ├── tasks.md      # Implementation tasks (commit)
│       ├── memory.md     # Feature learnings (commit)
│       ├── metadata.json # Spec type metadata (commit)
│       ├── metrics.json  # Pipeline timeline (commit)
│       ├── estimate.md   # Complexity estimate (commit, optional)
│       ├── demo.md       # Stakeholder walkthrough (commit, optional)
│       └── jira-links.json # Jira issue links (commit)
├── milestones/           # Milestone groupings (commit)
├── sessions/             # Review session logs (local only)
├── steering/             # Project rules — incl. enterprise-governance.md if --enterprise (commit)
├── agents/               # Active engine agents — V2 *.json or V3 *.md (commit)
├── skills/               # Kiro Agent Skills — /<name> slash commands in default chat (commit)
├── hooks/                # V3 versioned lifecycle hooks (commit)
├── settings/
│   └── mcp.json          # MCP config (local only)
└── mcp.json.template     # MCP config template (commit, no secrets)

When kspec init --ci is used, also creates:

.github/workflows/kspec-review.yml   # Headless review on every PR (commit)

Team Collaboration

kspec is designed for team collaboration. Most files should be committed to share specifications, tasks, and guidelines across your team.

What to Commit

| Path | Commit? | Why | |------|---------|-----| | .kiro/config.json | Yes | Project preferences (incl. enterprise + ideAgents + skills flags) | | .kiro/specs/ | Yes | Specifications, designs, tasks, memory | | .kiro/steering/ | Yes | Shared product, tech, testing guidelines (+ enterprise-governance.md if --enterprise) | | .kiro/agents/ | Yes | Active-engine agents — JSON configs (V2 toolsSettings or V3 permissions) | | .kiro/hooks/ | Yes | Versioned V3 lifecycle hooks | | .kiro/skills/ | Yes | Kiro Agent Skills — /<name> slash commands | | .kiro/mcp.json.template | Yes | MCP setup template (no secrets) | | .kiro/memory.md | Yes | Project learnings | | .github/workflows/kspec-review.yml | Yes | If --ci was used — headless review on PRs | | .kiro/.current | No | Personal working state | | .kiro/CONTEXT.md | No | Auto-generated, local state | | .kiro/sessions/ | No | Review session logs | | .kiro/settings/ | No | Local workspace MCP config | | ~/.kiro/mcp.json | N/A | Personal secrets in home directory |

Setting Up MCP for Teams

kspec init creates .kiro/mcp.json.template which uses mcp-remote with OAuth (no API tokens needed):

{
  "mcpServers": {
    "atlassian": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.atlassian.com/v1/sse"],
      "timeout": 120000
    }
  }
}

Each team member copies to their settings:

mkdir -p ~/.kiro/settings
cp .kiro/mcp.json.template ~/.kiro/settings/mcp.json

Or add via CLI: kiro-cli mcp add --name atlassian

See SECURITY.md for security best practices.

Planning Tool Integrations

Bridge planning tools and SDD artifacts. Jira remains the deepest integration; Rally, Azure DevOps Boards, and GitHub Issues follow the same pull / sync / tasks pattern.

Jira (Atlassian MCP)

kspec spec --jira PROJ-123,PROJ-456 "User Authentication"
kspec sync-jira                      # Smart: updates existing or creates new
kspec sync-jira --create             # Force create new issue
kspec sync-jira --project SECOPS     # Create in specific project
kspec sync-jira --update PROJ-789    # Update specific issue
kspec jira-pull
kspec jira-subtasks PROJ-789

sync-jira checks jira-links.json for an existing linked issue and updates it by default. Pulls never auto-overwrite local specs — they produce a change report first.

Configure Atlassian MCP:

kiro-cli mcp add --name atlassian

Or add to .kiro/settings/mcp.json / ~/.kiro/settings/mcp.json:

{
  "mcpServers": {
    "atlassian": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.atlassian.com/v1/sse"],
      "timeout": 120000
    }
  }
}

Rally / Azure DevOps / GitHub Issues

# Rally
kspec rally-pull US123456
kspec sync-rally --tags "qms,sdd,traceability"
kspec rally-tasks US123456

# Azure DevOps Boards
kspec ado-pull 12345
kspec sync-ado --project org/project --labels "kspec,sdd"
kspec ado-tasks 12345

# GitHub Issues
kspec github-pull owner/repo#123
kspec sync-github --repo owner/repo --tags "kspec,technical-specification"
kspec github-tasks owner/repo#123

Link state is stored per spec as rally-links.json, ado-links.json, or github-links.json, and surfaced in .kiro/CONTEXT.md.

kiro-cli mcp add --name rally
kiro-cli mcp add --name azure-devops
kiro-cli mcp add --name github

See: https://kiro.dev/docs/cli/mcp/

See Team Collaboration for secure team setup with environment variables.

Migrating from v1

kspec v2.0 consolidates everything into .kiro/ (previously split between .kspec/ and .kiro/).

When you run any kspec command, it will automatically detect .kspec/ and offer to migrate:

$ kspec status

  kspec v2.0 Migration

  kspec now stores everything under .kiro/ instead of .kspec/

  Files to migrate:
    - config.json
    - specs/ (3 specs)

  Migrate .kspec/ to .kiro/ now? (Y/n):

Migration moves config.json, .current, memory.md, and specs/ from .kspec/ to .kiro/, regenerates CONTEXT.md from the migrated source artifacts, then removes the empty .kspec/ directory.

Configuration

Set during kspec init:

• Date format: YYYY-MM-DD, DD-MM-YYYY, or MM-DD-YYYY
• Auto-execute: ask (default), auto, or dry-run
• Kiro engine: V2 by default; select V3 with --engine v3 or kspec engine set v3
• Model: inherits Kiro's persistent preference by default, or pin a custom model ID
• Planning tools: Jira / Rally / Azure DevOps / GitHub Issues (multi-select; when matching MCP detected)
• Reviewers: Multi-CLI reviewers for agentic review loop (Copilot, Claude, Gemini, etc.)
• IDE chat subagents: Optional .md agent files for Kiro IDE chat (default No)
• Agent Skills: Slash-command skills (/kspec-spec etc.) for default chat (default Yes)
• Enterprise governance: MCP/model registry URLs, IdP, prompt logging (opt-in, off by default)
• Hooks: V2 embeds context lifecycle and destructive-command guard hooks; V3 uses the versioned lifecycle hook file

Environment variables

| Variable | Effect | |---|---| | KSPEC_ENTERPRISE=1 | Flips the "Configure enterprise governance?" prompt default to Yes (orgs set this in dev container / shell init) | | KSPEC_KIRO_ENGINE=v2|v3 | Selects the harness when no global --engine flag is supplied | | KIRO_HOME=/path | Overrides the global Kiro agents/settings/MCP home | | KIRO_API_KEY | Required for headless mode — used by the --ci GitHub Actions workflow |

File Locking

kspec build uses file locking to prevent concurrent builds on the same spec. If another build is running, you'll see an error with the PID and lock time. Locks auto-expire after 30 minutes if the process crashes.

Auto-Updates

kspec checks for updates automatically (cached for 24 hours). Check manually:

kspec update

Or check when viewing version:

kspec --version

Known Limitations

| Limitation | Workaround | |------------|------------| | V3 headless CI is early access | Generated CI stays explicitly on V2 until Kiro documents stable V3 headless behavior. | | spec-lite.md auto-update is truncation | truncateSpecLite() truncates the active requirements artifact. Run kspec refresh or /agent swap kspec-refresh for an AI-generated summary. |

Requirements

• Node.js >= 18
• Kiro CLI or Amazon Q CLI
• Atlassian MCP (optional, for Jira integration)

Documentation

• Methodology — Why spec-driven development works
• Example: Todo App — Complete walkthrough with real files
• Contracts — Enforce structured outputs in specs
• CHANGELOG — Version history and release notes
• SECURITY.md — Secure MCP configuration and best practices

License

MIT