kspec 1.0.24 → 1.0.26

package/README.md

@@ -5,6 +5,20 @@
 
 Spec-driven development workflow for Kiro CLI with context management, verification at every step, and Jira integration.
 
+## 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 → tasks → build) |
+| **Lost learnings** | `memory.md` compounds knowledge across projects |
+| **Enterprise silos** | Jira integration bridges BA/PM and developers |
+
+Read the full [Methodology](docs/methodology.md) or see a complete [Example Walkthrough](docs/examples/todo-app/).
+
 ## Installation
 
 ```bash
@@ -130,23 +144,85 @@ Switch agents in kiro-cli: `/agent swap kspec-build` or use keyboard shortcuts.
 
 ```
 .kspec/
-├── config.json           # User preferences
-├── .current              # Current active spec path
-├── CONTEXT.md            # Auto-generated context for agents
-├── memory.md             # Project learnings
+├── 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/
-        ├── spec.md       # Full specification
+        ├── spec.md       # Full specification (commit)
         ├── spec-lite.md  # Concise (for context compression)
-        ├── tasks.md      # Implementation tasks
-        ├── memory.md     # Feature learnings
-        └── jira-links.json # Jira issue links (if integrated)
+        ├── tasks.md      # Implementation tasks (commit)
+        ├── memory.md     # Feature learnings (commit)
+        └── jira-links.json # Jira issue links (commit)
 
 .kiro/
-├── steering/             # Project rules (Kiro native)
-└── agents/               # kspec-generated agents
+├── steering/             # Project rules (commit)
+├── agents/               # kspec-generated agents (commit)
+└── mcp.json.template     # MCP config template (commit, no secrets)
 ```
 
+## 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/steering/` | Yes | Shared product, tech, testing guidelines |
+| `.kiro/agents/` | Yes | Consistent agent configurations |
+| `.kiro/mcp.json.template` | Yes | MCP setup template (no secrets) |
+| `.kspec/config.json` | Yes | Project preferences |
+| `.kspec/specs/` | Yes | Specifications, tasks, memory |
+| `.kspec/.current` | No | Personal working state |
+| `.kspec/CONTEXT.md` | No | Auto-generated, local state |
+| `~/.kiro/mcp.json` | N/A | Personal secrets in home directory |
+
+### Setting Up MCP for Teams
+
+**Problem**: API tokens should never be committed, but teams need consistent MCP configuration.
+
+**Solution**: Use environment variables with a committed template.
+
+1. Commit a template file (`.kiro/mcp.json.template`):
+   ```json
+   {
+     "mcpServers": {
+       "atlassian": {
+         "command": "npx",
+         "args": ["-y", "@anthropic/mcp-atlassian"],
+         "env": {
+           "ATLASSIAN_HOST": "${ATLASSIAN_HOST}",
+           "ATLASSIAN_EMAIL": "${ATLASSIAN_EMAIL}",
+           "ATLASSIAN_API_TOKEN": "${ATLASSIAN_API_TOKEN}"
+         }
+       }
+     }
+   }
+   ```
+
+2. Each team member creates their personal config:
+   ```bash
+   # Copy template to home directory
+   mkdir -p ~/.kiro && chmod 700 ~/.kiro
+   cp .kiro/mcp.json.template ~/.kiro/mcp.json
+   chmod 600 ~/.kiro/mcp.json
+
+   # Edit with real credentials
+   nano ~/.kiro/mcp.json
+   ```
+
+3. Or use environment variables directly:
+   ```bash
+   # Add to ~/.bashrc or ~/.zshrc
+   export ATLASSIAN_HOST="https://your-domain.atlassian.net"
+   export ATLASSIAN_EMAIL="your-email@example.com"
+   export ATLASSIAN_API_TOKEN="your-api-token"
+   ```
+
+See [SECURITY.md](SECURITY.md) for detailed security best practices.
+
 ## Jira Integration
 
 Bridge the gap between BAs/PMs and developers by integrating with Jira via Atlassian MCP.
@@ -178,7 +254,19 @@ Generate Jira subtasks from tasks.md for progress tracking.
 
 ### Prerequisites
 
-Configure Atlassian MCP in `~/.kiro/mcp.json`:
+`kspec init` creates `.kiro/mcp.json.template` automatically. To enable Jira integration:
+
+```bash
+# Copy template to your home directory (keeps secrets out of repo)
+mkdir -p ~/.kiro && chmod 700 ~/.kiro
+cp .kiro/mcp.json.template ~/.kiro/mcp.json
+chmod 600 ~/.kiro/mcp.json
+
+# Edit with your real credentials
+nano ~/.kiro/mcp.json
+```
+
+Replace the `${...}` placeholders with your actual values:
 
 ```json
 {
@@ -198,6 +286,8 @@ Configure Atlassian MCP in `~/.kiro/mcp.json`:
 
 Get your API token: https://id.atlassian.com/manage-profile/security/api-tokens
 
+See [Team Collaboration](#team-collaboration) for secure team setup with environment variables.
+
 ## Configuration
 
 Set during `kspec init`:
@@ -225,6 +315,12 @@ kspec --version
 - Kiro CLI or Amazon Q CLI
 - Atlassian MCP (optional, for Jira integration)
 
+## Documentation
+
+- [Methodology](docs/methodology.md) — Why spec-driven development works
+- [Example: Todo App](docs/examples/todo-app/) — Complete walkthrough with real files
+- [SECURITY.md](SECURITY.md) — Secure MCP configuration and best practices
+
 ## License
 
 MIT

package/package.json

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

package/src/index.js

@@ -661,7 +661,7 @@ WORKFLOW (do this autonomously):
 5. Update .kspec/.current with the spec folder path
 6. Update .kspec/CONTEXT.md with current state
 
-After completion, suggest: "Switch to kspec-tasks agent to generate implementation tasks"`,
+Next step: Run \`/agent swap kspec-tasks\` or \`kspec tasks\` to generate implementation tasks.`,
     keyboardShortcut: 'ctrl+shift+s',
     welcomeMessage: 'Ready to create specification. Describe your feature.'
   },
@@ -693,7 +693,7 @@ WORKFLOW:
 
 Tasks must be atomic and independently verifiable.
 
-After completion, suggest: "Switch to kspec-build agent to start implementing tasks"`,
+Next step: Run \`/agent swap kspec-build\` or \`kspec build\` to start implementing tasks.`,
     keyboardShortcut: 'ctrl+shift+t',
     welcomeMessage: 'Reading current spec and generating tasks...'
   },
@@ -730,7 +730,7 @@ CRITICAL:
 - NEVER delete .kiro or .kspec folders
 - Use non-interactive flags for commands (--yes, -y)
 
-When all tasks complete, suggest: "Switch to kspec-verify agent to verify implementation"`,
+When all tasks complete: Run \`/agent swap kspec-verify\` or \`kspec verify\` to verify implementation.`,
     keyboardShortcut: 'ctrl+shift+b',
     welcomeMessage: 'Reading current task and building...'
   },
@@ -908,8 +908,56 @@ const commands = {
       }
     }
 
+    // Create MCP template (safe to commit, no secrets)
+    const mcpTemplatePath = path.join('.kiro', 'mcp.json.template');
+    if (!fs.existsSync(mcpTemplatePath)) {
+      ensureDir('.kiro');
+      const mcpTemplate = {
+        mcpServers: {
+          atlassian: {
+            command: 'npx',
+            args: ['-y', '@anthropic/mcp-atlassian'],
+            env: {
+              ATLASSIAN_HOST: '${ATLASSIAN_HOST}',
+              ATLASSIAN_EMAIL: '${ATLASSIAN_EMAIL}',
+              ATLASSIAN_API_TOKEN: '${ATLASSIAN_API_TOKEN}'
+            }
+          }
+        }
+      };
+      fs.writeFileSync(mcpTemplatePath, JSON.stringify(mcpTemplate, null, 2));
+      log(`Created ${mcpTemplatePath} (commit this, set env vars for secrets)`);
+    }
+
+    // Update .gitignore for kspec (append if exists, create if not)
+    const kspecGitignore = `
+# kspec local state (don't commit - personal working state)
+.kspec/.current
+.kspec/CONTEXT.md
+
+# DO commit these for team collaboration:
+# .kspec/config.json - project preferences
+# .kspec/specs/ - specifications, tasks, memory
+# .kiro/steering/ - product, tech, testing guidelines
+# .kiro/agents/ - agent configurations
+# .kiro/mcp.json.template - MCP template (no secrets)
+`;
+    const gitignorePath = '.gitignore';
+    if (fs.existsSync(gitignorePath)) {
+      const existing = fs.readFileSync(gitignorePath, 'utf8');
+      if (!existing.includes('.kspec/.current')) {
+        fs.appendFileSync(gitignorePath, kspecGitignore);
+        log('Updated .gitignore with kspec entries');
+      }
+    } else {
+      fs.writeFileSync(gitignorePath, kspecGitignore.trim() + '\n');
+      log('Created .gitignore with kspec entries');
+    }
+
     console.log('\n✅ kspec initialized!\n');
-    console.log('Next: kspec analyse');
+    console.log('Next step:');
+    console.log('  kspec analyse');
+    console.log('  or inside kiro-cli: /agent swap kspec-analyse\n');
   },
 
   async analyse() {
@@ -992,6 +1040,10 @@ Folder: ${folder}
 
 spec-lite.md is critical - it's loaded after context compression.`, 'kspec-spec');
     }
+
+    console.log('\nNext step:');
+    console.log('  kspec tasks');
+    console.log('  or inside kiro-cli: /agent swap kspec-tasks\n');
   },
 
   async 'verify-spec'(args) {
@@ -1140,6 +1192,10 @@ Create ${folder}/tasks.md with:
 - TDD approach (test first)
 - Logical order
 - File paths for each task`, 'kspec-tasks');
+
+    console.log('\nNext step:');
+    console.log('  kspec build');
+    console.log('  or inside kiro-cli: /agent swap kspec-build\n');
   },
 
   async 'verify-tasks'(args) {
@@ -1172,7 +1228,10 @@ Report: X/Y tasks done, gaps found, coverage assessment.`, 'kspec-verify');
     log(`Building: ${folder}`);
     if (stats) {
       if (stats.remaining === 0) {
-        log('All tasks completed! Run: kspec verify');
+        log('All tasks completed!');
+        console.log('\nNext step:');
+        console.log('  kspec verify');
+        console.log('  or inside kiro-cli: /agent swap kspec-verify\n');
         return;
       }
       log(`Progress: ${stats.done}/${stats.total} (${stats.remaining} remaining)`);
@@ -1197,6 +1256,18 @@ ${execNote}
 
 CRITICAL: Update tasks.md after each task completion.
 NEVER delete .kiro or .kspec folders.`, 'kspec-build');
+
+    // Show next step based on remaining tasks
+    const updatedStats = getTaskStats(folder);
+    if (updatedStats && updatedStats.remaining === 0) {
+      console.log('\nAll tasks completed!');
+      console.log('Next step:');
+      console.log('  kspec verify');
+      console.log('  or inside kiro-cli: /agent swap kspec-verify\n');
+    } else if (updatedStats && updatedStats.remaining > 0) {
+      console.log(`\n${updatedStats.remaining} tasks remaining.`);
+      console.log('Continue: kspec build\n');
+    }
   },
 
   async verify(args) {
@@ -1222,6 +1293,9 @@ Report:
 - Tasks: X/Y completed
 - Tests: PASS/FAIL
 - Gaps: [list any]`, 'kspec-verify');
+
+    console.log('\nIf verification passed:');
+    console.log('  kspec done  (to complete spec and harvest learnings)\n');
   },
 
   async refresh(args) {
@@ -1368,15 +1442,23 @@ Output: APPROVE or REQUEST_CHANGES with specifics.`, 'kspec-review');
       if (stats) {
         console.log(`Tasks: ${stats.done}/${stats.total} completed`);
         if (stats.remaining > 0) {
-          console.log(`\nNext: kspec build`);
+          console.log(`\nNext step:`);
+          console.log(`  kspec build`);
+          console.log(`  or inside kiro-cli: /agent swap kspec-build`);
         } else {
-          console.log(`\nNext: kspec verify`);
+          console.log(`\nNext step:`);
+          console.log(`  kspec verify`);
+          console.log(`  or inside kiro-cli: /agent swap kspec-verify`);
         }
       } else {
-        console.log(`\nNext: kspec tasks`);
+        console.log(`\nNext step:`);
+        console.log(`  kspec tasks`);
+        console.log(`  or inside kiro-cli: /agent swap kspec-tasks`);
       }
     } else {
-      console.log(`\nNo current spec. Run: kspec spec "Feature Name"`);
+      console.log(`\nNo current spec.`);
+      console.log(`  kspec spec "Feature Name"`);
+      console.log(`  or inside kiro-cli: /agent swap kspec-spec`);
     }
     console.log('');
   },