kspec 1.0.17 → 1.0.18

package/README.md

@@ -3,7 +3,7 @@
 [![npm version](https://img.shields.io/npm/v/kspec.svg)](https://www.npmjs.com/package/kspec)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Spec-driven development workflow for Kiro CLI with verification at every step.
+Spec-driven development workflow for Kiro CLI with context management, verification at every step, and Jira integration.
 
 ## Installation
 
@@ -17,14 +17,45 @@ npm install -g kspec
 kspec init                    # Interactive setup
 kspec analyse                 # Analyse codebase
 kspec spec "User Auth API"    # Create specification
-kspec verify-spec             # Verify spec is complete
 kspec tasks                   # Generate tasks
-kspec verify-tasks            # Verify tasks cover spec
 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:
+
+```bash
+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.
+
 ## Workflow
 
 ```
@@ -44,166 +75,155 @@ init → analyse → spec → verify-spec → tasks → verify-tasks → build
 | `kspec build` | Execute tasks with TDD |
 | `kspec verify` | Verify implementation matches spec |
 | `kspec done` | Complete spec, harvest memory |
+| `kspec context` | View/refresh context file |
 | `kspec review` | Code review |
 | `kspec list` | List all specs |
 | `kspec status` | Current status |
+| `kspec agents` | List available agents |
+| `kspec update` | Check for updates |
 | `kspec help` | Show help |
-| `kspec --help, -h` | Show help (standard flag) |
-| `kspec --version, -v` | Show version (standard flag) |
+
+### Jira Integration (requires Atlassian MCP)
+
+| Command | Description |
+|---------|-------------|
+| `kspec spec --jira PROJ-123,PROJ-456 "Feature"` | 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 |
+| `kspec jira-subtasks PROJ-123` | Create subtasks under specific issue |
+
+## Context Management
+
+kspec maintains context that survives AI context compression:
+
+```
+.kspec/CONTEXT.md (auto-generated)
+├── Current Spec: 2026-01-24-user-auth
+├── Task: 3/12 - Implement JWT validation
+├── Requirements Summary (from spec-lite)
+├── Decisions & Learnings
+└── Jira Links (if integrated)
+```
+
+Agents read CONTEXT.md first, automatically restoring state after context compression.
+
+```bash
+kspec context    # View and refresh context manually
+```
 
 ## Agents & Shortcuts
 
 | Agent | Shortcut | Purpose |
 |-------|----------|---------|
-| kspec-analyse | Ctrl+A | Analyse codebase |
-| kspec-spec | Ctrl+S | Create specifications |
-| kspec-tasks | Ctrl+T | Generate tasks |
-| kspec-build | Ctrl+B | Execute with TDD |
-| kspec-verify | Ctrl+V | Verify spec/tasks/impl |
-| kspec-review | Ctrl+R | Code review |
+| kspec-analyse | Ctrl+Shift+A | Analyse codebase |
+| kspec-spec | Ctrl+Shift+S | Create specifications |
+| kspec-tasks | Ctrl+Shift+T | Generate tasks |
+| kspec-build | Ctrl+Shift+B | Execute with TDD |
+| kspec-verify | Ctrl+Shift+V | Verify spec/tasks/impl |
+| kspec-review | Ctrl+Shift+R | Code review |
+| kspec-jira | Ctrl+Shift+J | Jira integration |
+
+Switch agents in kiro-cli: `/agent swap kspec-build` or use keyboard shortcuts.
 
 ## Structure
 
 ```
 .kspec/
 ├── config.json           # User preferences
+├── .current              # Current active spec path
+├── CONTEXT.md            # Auto-generated context for agents
 ├── memory.md             # Project learnings
 └── specs/
     └── 2026-01-22-feature/
         ├── spec.md       # Full specification
         ├── spec-lite.md  # Concise (for context compression)
         ├── tasks.md      # Implementation tasks
-        └── memory.md     # Feature learnings
+        ├── memory.md     # Feature learnings
+        └── jira-links.json # Jira issue links (if integrated)
 
 .kiro/
-└── steering/             # Project rules (Kiro native)
+├── steering/             # Project rules (Kiro native)
+└── agents/               # kspec-generated agents
 ```
 
-## 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
-
-## Integration with Kiro IDE
-
-kspec and Kiro IDE work seamlessly together, combining structured workflow automation with interactive development assistance.
+## Jira Integration
 
-### Workflow Integration
+Bridge the gap between BAs/PMs and developers by integrating with Jira via Atlassian MCP.
 
-**kspec provides:**
-- Structured spec creation and task generation
-- Automated analysis and verification steps
-- TDD workflow enforcement
-- Project memory harvesting
+### Pull Requirements from Jira
 
-**Kiro IDE provides:**
-- Interactive implementation assistance
-- Real-time code help and debugging
-- Native spec workflow support
-- Advanced AI-powered development tools
-
-### Usage Patterns
-
-#### Pattern 1: kspec-Driven Development
 ```bash
-# Use kspec for structure and planning
-kspec init
-kspec analyse
-kspec spec "User Authentication API"
-kspec tasks
-
-# Switch to Kiro IDE for implementation
-# Reference spec files: #File .kspec/specs/2026-01-22-user-auth/spec.md
-# Implement tasks interactively with AI assistance
-
-# Return to kspec for verification
-kspec verify
-kspec done
+kspec spec --jira PROJ-123,PROJ-456 "User Authentication"
 ```
 
-#### Pattern 2: Kiro-Native with kspec Analysis
-```bash
-# Use Kiro's built-in spec workflow
-# Create specs using Kiro IDE's native tools
+This fetches issue details, extracts acceptance criteria, and creates a unified spec with source attribution.
 
-# Use kspec for analysis and verification
-kspec analyse          # Update steering docs
-kspec review          # Code review
-kspec verify          # Verify implementation
-```
+### Push Specs to Jira
 
-#### Pattern 3: Hybrid Approach
 ```bash
-kspec spec "Feature"   # Create initial spec
-# Edit and refine spec in Kiro IDE
-kspec tasks           # Generate tasks
-# Implement tasks in Kiro IDE with AI assistance
-kspec verify          # Final verification
+kspec sync-jira                      # Create new issue
+kspec sync-jira --update PROJ-789    # Update existing issue
 ```
 
-### File System Integration
+Create or update Jira issues with spec content for BA/PM review.
 
-Both tools share the same file structure:
+### Create Subtasks
 
+```bash
+kspec jira-subtasks PROJ-789
 ```
-.kiro/
-├── steering/         # Shared project context
-│   ├── product.md   # Used by both kspec and Kiro
-│   ├── tech.md      # Technology standards
-│   └── testing.md   # Testing approach
-└── agents/          # kspec-generated agents (usable in Kiro)
 
-.kspec/
-└── specs/           # kspec-generated specs
-    └── feature/
-        ├── spec.md      # Reference in Kiro: #File .kspec/specs/feature/spec.md
-        ├── spec-lite.md # Concise version for context
-        ├── tasks.md     # Task list
-        └── memory.md    # Learnings
+Generate Jira subtasks from tasks.md for progress tracking.
+
+### Prerequisites
+
+Configure Atlassian MCP in `~/.kiro/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "atlassian": {
+      "command": "npx",
+      "args": ["-y", "@anthropic/mcp-atlassian"],
+      "env": {
+        "ATLASSIAN_HOST": "https://your-domain.atlassian.net",
+        "ATLASSIAN_EMAIL": "your-email@example.com",
+        "ATLASSIAN_API_TOKEN": "your-api-token"
+      }
+    }
+  }
+}
 ```
 
-### Kiro IDE Context Usage
+Get your API token: https://id.atlassian.com/manage-profile/security/api-tokens
 
-Reference kspec files in Kiro IDE chat:
-
-```
-#File .kspec/specs/user-auth/spec.md     # Full specification
-#File .kspec/specs/user-auth/tasks.md    # Task list
-#Folder .kspec/specs/user-auth           # Entire spec folder
-#Folder .kiro/steering                   # Project context
-```
+## Configuration
 
-### Agent Integration
+Set during `kspec init`:
 
-kspec creates specialized agents that work in Kiro IDE:
+- **Date format**: YYYY-MM-DD, DD-MM-YYYY, or MM-DD-YYYY
+- **Auto-execute**: ask (default), auto, or dry-run
 
-- **kspec-analyse** (Ctrl+A): Codebase analysis
-- **kspec-spec** (Ctrl+S): Specification creation  
-- **kspec-tasks** (Ctrl+T): Task generation
-- **kspec-build** (Ctrl+B): TDD implementation
-- **kspec-verify** (Ctrl+V): Verification
-- **kspec-review** (Ctrl+R): Code review
+## Auto-Updates
 
-Switch agents in Kiro IDE: `/agent swap` or use keyboard shortcuts.
+kspec checks for updates automatically (cached for 24 hours). Check manually:
 
-### Best Practices
+```bash
+kspec update
+```
 
-1. **Start with kspec** for structured planning and analysis
-2. **Use Kiro IDE** for interactive implementation and debugging
-3. **Reference kspec files** in Kiro chat for context
-4. **Leverage steering docs** updated by kspec analysis
-5. **Use kspec agents** within Kiro for specialized workflows
-6. **Verify with kspec** to ensure completeness
+Or check when viewing version:
 
-This integration gives you the best of both worlds: structured workflow automation and intelligent development assistance.
+```bash
+kspec --version
+```
 
 ## Requirements
 
 - Node.js >= 18
 - Kiro CLI or Amazon Q CLI
-- Kiro IDE (optional, for enhanced integration)
+- Atlassian MCP (optional, for Jira integration)
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kspec",
-  "version": "1.0.17",
+  "version": "1.0.18",
   "description": "Spec-driven development workflow for Kiro CLI",
   "main": "src/index.js",
   "bin": {