🎩 You're Invited:Meet the Socket team at Black Hat in Las Vegas, August 3-6.RSVP →
Sign In

kspec

Package Overview
Dependencies
Maintainers
1
Versions
66
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

kspec - npm Package Compare versions

Comparing version
2.2.4
 to
2.3.1-beta-c699aef
+1
-1
package.json
{
"name": "kspec",
"version": "2.2.4",
"version": "2.3.1-beta-c699aef",
"description": "Spec-driven development workflow for Kiro CLI",

@@ -5,0 +5,0 @@ "main": "src/index.js",

+65
-38
README.md

@@ -8,2 +8,14 @@ # kspec — Spec-Driven Development for Kiro CLI

## What's new in 2.3.0
| Area | What you get |
|---|---|
| **Kiro V3 early access** | `kspec engine set v3` generates Markdown agents, capability permissions, 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](CHANGELOG.md#230--2026-06-23) for the full release notes.
## What's new in 2.2.0

@@ -80,3 +92,3 @@

> Build a todo app with categories
(agent creates spec.md, spec-lite.md, updates context)
(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

@@ -115,4 +127,8 @@

| `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 spec.md + spec-lite.md |
| `kspec spec "Name"` | Create active-engine requirements + spec-lite.md |
| `kspec verify-spec` | Interactively review and shape spec with clarifying questions |

@@ -419,6 +435,6 @@ | `kspec design` | Create technical design from spec (optional) |

- uses: actions/checkout@v4
- run: curl -fsSL https://kiro.dev/install.sh | sh
- 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 --simple --trust-tools=read,shell --no-interactive
run: kspec review --engine v2 --simple --trust-tools=read,shell --no-interactive
# ...posts review as PR comment via actions/github-script

@@ -431,9 +447,4 @@ ```

`.kiro/settings/hooks.json` with:
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.
- **`preToolUse`** — audit-log every shell command, hard-block destructive patterns (`rm -rf`, `git push`, `sudo`, `curl http`)
- **`postToolUse`** — audit-log every file write
- **`onSpecComplete`** — runs `kspec verify` and `kspec sync-jira --progress` automatically
- **`onSessionStop`** — refreshes CONTEXT.md so the next CI run starts clean
Powered by Kiro CLI 2.0+ headless mode (`--no-interactive`, `KIRO_API_KEY`, `--trust-tools`). See [Kiro headless docs](https://kiro.dev/docs/cli/headless/).

@@ -448,3 +459,3 @@

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

@@ -460,5 +471,7 @@ > /kspec-build

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)
Every kspec agent ships with a `toolsSettings` block scoping what it can touch:
V2 agents use `toolsSettings`; V3 Markdown agents use capability-based `permissions`. Both retain the same role-based filesystem, shell, MCP, secret, and subagent boundaries.

@@ -524,19 +537,19 @@ | Agent type | Write paths | Shell scope |

kspec maintains context that survives AI context compression:
kspec maintains a deterministic active-work snapshot regenerated from source artifacts:
```
.kiro/CONTEXT.md (auto-generated)
├── Current Spec: 2026-01-24-user-auth
├── Progress: 3/12 tasks completed
├── Design: present / not yet created
├── Requirements Summary (from spec-lite)
├── Decisions & Learnings
├── Jira Links (if integrated)
└── Quick Commands (design, tasks, build, verify...)
.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
```
Agents read CONTEXT.md first, automatically restoring state after context compression. CONTEXT.md is refreshed both before and after agent chat sessions.
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`.
```bash
kspec context # View and refresh context (CLI)
kspec context # Refresh and view context
kspec context --stdout # Hook/agent-safe output without the footer
kspec use <spec> # Select the active spec
```

@@ -550,4 +563,13 @@

**Note:** There is no automatic hook for `/compact` — CONTEXT.md won't auto-refresh on context compaction. Use `kspec-context` agent or run `kspec context` after compacting.
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`](https://kiro.dev/changelog/cli/2-7/) runs an iterative, completion-checked loop for longer work.
- [Queue steering](https://kiro.dev/docs/cli/chat/queue-steering/) redirects active work at the next tool boundary; `Ctrl+S` toggles steer/queue behavior.
- [`/rewind`](https://kiro.dev/docs/cli/chat/rewind/) branches from an earlier turn without changing the original session.
- [`/transcript save`](https://kiro.dev/changelog/cli/2-6/) exports the current conversation as Markdown, plaintext, or JSON.
## Agents & Shortcuts

@@ -580,3 +602,3 @@

When you run `/compact` in kiro-cli, CONTEXT.md may become stale. Refresh it inline:
Kiro compaction creates a new session and reloads resources. The session-start hook refreshes context automatically. You can also refresh it explicitly:

@@ -587,3 +609,3 @@ ```

This regenerates CONTEXT.md with current spec progress without leaving your session.
The context agent delegates to `kspec context --stdout`; it never writes its own alternate snapshot format.

@@ -638,3 +660,5 @@ ## ACP (Agent Client Protocol)

│ └── 2026-01-22-feature/
│ ├── spec.md # Full specification (commit)
│ ├── 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)

@@ -652,7 +676,7 @@ │ ├── design.md # Technical design (commit, optional)

├── steering/ # Project rules — incl. enterprise-governance.md if --enterprise (commit)
├── agents/ # kspec-generated agents — *.json (CLI) + *.md (IDE chat, optional) (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)
│ └── hooks.json # Hooks (basic / enterprise / documentation / ci preset)
│ └── mcp.json # MCP config (local only)
└── mcp.json.template # MCP config template (commit, no secrets)

@@ -678,3 +702,4 @@ ```

| `.kiro/steering/` | Yes | Shared product, tech, testing guidelines (+ enterprise-governance.md if `--enterprise`) |
| `.kiro/agents/` | Yes | Agent configurations — JSON for CLI, optional `.md` for IDE chat |
| `.kiro/agents/` | Yes | Active-engine agents — V2 JSON or V3 Markdown |
| `.kiro/hooks/` | Yes | Versioned V3 lifecycle hooks |
| `.kiro/skills/` | Yes | Kiro Agent Skills — `/<name>` slash commands |

@@ -686,5 +711,4 @@ | `.kiro/mcp.json.template` | Yes | MCP setup template (no secrets) |

| `.kiro/CONTEXT.md` | No | Auto-generated, local state |
| `.kiro/audit.log` | No | CI hooks audit trail (local only) |
| `.kiro/sessions/` | No | Review session logs |
| `.kiro/settings/` | No | Local MCP config + hooks.json |
| `.kiro/settings/` | No | Local workspace MCP config |
| `~/.kiro/mcp.json` | N/A | Personal secrets in home directory |

@@ -808,3 +832,3 @@

Migration moves `config.json`, `.current`, `CONTEXT.md`, `memory.md`, and `specs/` from `.kspec/` to `.kiro/`, then removes the empty `.kspec/` directory.
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.

@@ -817,3 +841,4 @@ ## Configuration

- **Auto-execute**: ask (default), auto, or dry-run
- **Model**: AI model for agents (claude-sonnet-4.6, claude-opus-4.6, claude-haiku-4.5, or custom)
- **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
- **Jira project**: Default project key for `sync-jira` (when Atlassian MCP detected)

@@ -824,3 +849,3 @@ - **Reviewers**: Multi-CLI reviewers for agentic review loop (Copilot, Claude, Gemini, etc.)

- **Enterprise governance**: MCP/model registry URLs, IdP, prompt logging (opt-in, off by default)
- **Hooks preset**: none / basic / enterprise / documentation / ci
- **Hooks**: V2 embeds context lifecycle and destructive-command guard hooks; V3 uses the versioned lifecycle hook file

@@ -832,2 +857,4 @@ ### Environment variables

| `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 |

@@ -857,4 +884,4 @@

|------------|------------|
| **No `/compact` hook** | CONTEXT.md doesn't auto-refresh on context compaction. Run `/agent swap kspec-context` or `kspec context` manually. |
| **spec-lite.md auto-update is truncation** | `truncateSpecLite()` truncates spec.md (not AI summary). Run `kspec refresh` or `/agent swap kspec-refresh` for AI-generated summary. |
| **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. |

@@ -861,0 +888,0 @@ ## Requirements

src/index.js

Sorry, the diff of this file is too big to display