npm package: @snow-tzu/kiro-jira-spec-workflow
Description: Kiro skill for JIRA-integrated spec-driven development workflow (BA → TL → Dev → QA)
Author: Snow Tzu
Latest version: 1.0.4

# Kiro JIRA Spec Workflow

## 🚀 Quick Install

```bash
npx @snow-tzu/kiro-jira-spec-workflow
```

That's it! The interactive installer will guide you through the setup.

## 📦 What's Included

This package provides a complete JIRA-integrated workflow for spec-driven development:

- **BA Workflow**: Generate requirements.md from JIRA stories
- **TL Workflow**: Create design.md with architecture and correctness properties  
- **Dev Workflow**: Generate tasks.md and implement with AI assistance
- **QA Workflow**: Test against requirements
- **Steering Files**: Auto-activation rules for seamless skill usage
- **Templates**: Pre-configured templates for all spec documents

## 📚 Documentation

- **SKILL.md** - Complete skill documentation with all workflows
- **README.md** - This file (quick start guide)
- **templates/** - Template files for requirements, design, and tasks

## 🎯 Quick Start

### 1. Install

```bash
npx @snow-tzu/kiro-jira-spec-workflow
```

### 2. Configure MCP

The installer will help you create `mcp.json` with:

```json
{
  "mcpServers": {
    "atlassian-rovo": {
      "url": "https://mcp.atlassian.com/v1/mcp",
      "disabled": false,
      "autoApprove": [
        "getAccessibleAtlassianResources",
        "getJiraIssue",
        "search",
        "fetch",
        "atlassianUserInfo",
        "addCommentToJiraIssue",
        "editJiraIssue"
      ]
    }
  }
}
```

### 3. Set Up OAuth

Follow: https://support.atlassian.com/atlassian-rovo-mcp-server/

### 4. Test

```
"Get JIRA issue PROJ-123"
```

### 5. Use

```
"Create requirements for JIRA story PROJ-123"
```

## 🎨 Features

✅ JIRA integration via MCP  
✅ Interactive requirements generation  
✅ Design with correctness properties  
✅ Task breakdown with auto-generated subtasks  
✅ Human-in-the-loop approval gates  
✅ Parallel development (one spec per story)  
✅ Agent-agnostic (works with Kiro, Claude, Cursor, etc.)  

## 📖 Example Usage

### BA Creates Requirements

```
BA: "Create requirements for JIRA story SCRUM-1"

System:
✅ Fetched SCRUM-1
✅ Created requirements.md
⚠️ Need clarification on 2 criteria

[Interactive questions...]

✅ Ready for review
```

### TL Creates Design

```
TL: "Create design for SCRUM-1"

System:
✅ Read requirements.md
✅ Conducting design interview...
✅ Created design.md
✅ Ready for review
```

### Dev Implements

```
Dev: "Create tasks for SCRUM-1"
✅ Created 45 tasks

Dev: "Implement task 1.1"
✅ Implemented
✅ Tests passing
✅ Task complete
```

## 🛠️ Installation Methods

### Method 1: npx (Easiest)
```bash
npx @snow-tzu/kiro-jira-spec-workflow
```

### Method 2: Manual
```bash
mkdir -p .kiro/skills/spec-driven-development-with-jira
cp SKILL.md .kiro/skills/spec-driven-development-with-jira/
cp -r templates .kiro/skills/spec-driven-development-with-jira/
# See SKILL.md for details
```

## 📁 File Structure

After installation:

```
.kiro/
├── skills/
│   ├── ba-requirements-workflow/
│   │   ├── SKILL.md
│   │   └── templates/
│   │       └── requirements-template.md
│   ├── tl-design-workflow/
│   │   ├── SKILL.md
│   │   └── templates/
│   │       └── design-template.md
│   └── dev-tasks-workflow/
│       ├── SKILL.md
│       └── templates/
│           ├── tasks-template.md
│           └── metadata-template.json
├── steering/
│   ├── jira-spec-workflow-activation.md    # Auto-activates skill
│   └── spec-naming-convention.md           # Enforces naming rules
├── settings/
│   └── mcp.json
└── specs/
    ├── story-1/
    │   ├── requirements.md
    │   ├── design.md
    │   └── tasks.md
    └── story-2/
        ├── requirements.md
        ├── design.md
        └── tasks.md
```

## 🔧 Requirements

- JIRA access (Cloud or Server/Data Center)
- AI agent with MCP support (Kiro, Claude Desktop, Cursor, etc.)
- Node.js >= 14 (for npm installation)

## 🆘 Troubleshooting

### Skill Not Activating

**Problem**: Kiro doesn't use the skill when you ask to create requirements/design/tasks

**Solutions**:

1. **Use exact command phrases**:
   ```
   "Create requirements from JIRA story PROJ-123"
   "Create design from JIRA story PROJ-123"
   "Create tasks from JIRA story PROJ-123"
   ```

2. **Manually reference the skill** using `#` in Kiro:
   ```
   #Spec-Driven Development Workflow create requirements from JIRA story PROJ-123
   ```

3. **Check steering file exists**: `.kiro/steering/jira-spec-workflow-activation.md`
   - This file is automatically installed by the package
   - It tells Kiro to use the appropriate skill for each role
   - If missing, reinstall the package

4. **Verify skill files exist**:
   ```bash
   ls .kiro/skills/ba-requirements-workflow/SKILL.md
   ls .kiro/skills/tl-design-workflow/SKILL.md
   ls .kiro/skills/dev-tasks-workflow/SKILL.md
   ```

See **SKILL-ACTIVATION-GUIDE.md** for detailed explanation of how skill activation works.

### MCP Connection Fails
- Check OAuth setup
- Verify mcp.json configuration
- Restart AI agent

### Skill Not Found
- Verify file location
- Restart AI agent
- Check file permissions

### JIRA Issue Not Found
- Verify issue key format
- Check access permissions
- Verify JIRA instance URL

See **SKILL.md** for detailed troubleshooting.

## 📝 License

MIT

## 🤝 Contributing

Contributions welcome! This is a reusable skill that can be improved.

## 📞 Support

- Read the documentation
- Test with simple stories first
- Check MCP server logs
- Review examples in skill file

## 🔗 Links

- **GitHub**: https://github.com/ganesanarun/kiro-skills
- **Full Documentation**: SKILL.md
- **Atlassian MCP**: https://support.atlassian.com/atlassian-rovo-mcp-server/

---

**Ready to start?** Run `npx @snow-tzu/kiro-jira-spec-workflow`