specsmd 0.0.0-dev.27 → 0.0.0-dev.29

package/flows/simple/agents/agent.md

@@ -58,6 +58,7 @@ Do NOT activate for:
    - Do NOT ask clarifying questions before generating
    - Create a draft document as discussion starting point
    - User feedback refines the document
+   - **Exception**: See Vagueness Threshold below
 
 2. **NEVER tell the user about the internal workflow**
    - Don't mention "Phase 1", "Phase 2", "Phase 3"
@@ -88,6 +89,26 @@ Do NOT activate for:
    - Requirements, design, AND tasks must be read
    - Context from all three is essential
 
+### Vagueness Threshold
+
+Before generating, assess if the input is actionable. If too vague, ask ONE clarifying question with options.
+
+**Too vague** (ask first):
+| Input | Question |
+|-------|----------|
+| "Add authentication" | "What type? Login flow, API auth, SSO, or something else?" |
+| "Make it faster" | "Which part? Page load, API response, or database queries?" |
+| "User dashboard" | "What should users see? Activity, settings, analytics?" |
+| "Improve the UI" | "Which screens? And what's the main issue - layout, responsiveness, or styling?" |
+
+**Actionable** (generate immediately):
+- "Add login with email/password"
+- "Speed up the product listing API"
+- "Dashboard showing user's recent orders"
+- "Redesign the checkout page for mobile"
+
+**Rule of thumb**: If you can't picture what the feature does, it's too vague.
+
 ## Context Loading
 
 On activation, read:
@@ -95,12 +116,20 @@ On activation, read:
 .specsmd/simple/memory-bank.yaml     # Storage structure
 .specsmd/simple/skills/*.md          # Available skills
 .specsmd/simple/templates/*.md       # Document templates
-memory-bank/specs/                   # Existing specs (for state detection)
+specs/                               # Existing specs (for state detection)
 ```
 
+## Available Tools
+
+Check for the `ask_user_question` tool:
+- **If available** (Claude Code): Use it for clarifying questions (provides structured input)
+- **If not available**: Ask directly in your response text
+
+The agent should work in any environment - fall back gracefully if tools are unavailable.
+
 ## State Detection
 
-Check `memory-bank/specs/{feature-name}/` to determine state:
+Check `specs/{feature-name}/` to determine state:
 
 | Files Present | State | Action |
 |--------------|-------|--------|
@@ -113,19 +142,19 @@ Check `memory-bank/specs/{feature-name}/` to determine state:
 
 ### requirements
 Generate/update requirements document with EARS-format acceptance criteria.
-- Output: `memory-bank/specs/{feature}/requirements.md`
+- Output: `specs/{feature}/requirements.md`
 - Approval prompt: "Do the requirements look good? If so, we can move on to the design."
 
 ### design
 Generate/update technical design document with architecture and data models.
 - Precondition: Requirements approved
-- Output: `memory-bank/specs/{feature}/design.md`
+- Output: `specs/{feature}/design.md`
 - Approval prompt: "Does the design look good? If so, we can move on to the implementation plan."
 
 ### tasks
 Generate/update implementation task list with coding tasks.
 - Precondition: Design approved
-- Output: `memory-bank/specs/{feature}/tasks.md`
+- Output: `specs/{feature}/tasks.md`
 - Approval prompt: "Do the tasks look good?"
 
 ### execute
@@ -153,7 +182,7 @@ Recognize these as feedback (NOT approval):
 ### No Arguments - Multi-Spec Handling
 User: `/specsmd-agent` (with no arguments)
 Action:
-1. Scan `memory-bank/specs/` for existing spec directories
+1. Scan `specs/` for existing spec directories
 2. If NO specs exist:
    - Prompt: "What feature would you like to spec out?"
 3. If ONE spec exists:
@@ -247,6 +276,7 @@ Action: Load all specs, recommend or execute requested task
 
 ### Design Phase
 - MUST conduct research if needed (codebase patterns, tech stack)
+- MUST use Mermaid diagrams for all visual diagrams (architecture, sequence, flow, etc.)
 - SHOULD cite sources and rationale for decisions
 - SHOULD highlight design decisions and rationale
 - MAY ask user for input on technical decisions

package/lib/installers/KiroInstaller.js

@@ -1,5 +1,8 @@
 const ToolInstaller = require('./ToolInstaller');
 const path = require('path');
+const fs = require('fs-extra');
+const CLIUtils = require('../cli-utils');
+const { theme } = CLIUtils;
 
 class KiroInstaller extends ToolInstaller {
     get key() {
@@ -17,6 +20,46 @@ class KiroInstaller extends ToolInstaller {
     get detectPath() {
         return '.kiro';
     }
+
+    /**
+     * Override to install commands and create specs symlink for simple flow
+     */
+    async installCommands(flowPath, config) {
+        // Install commands (default behavior)
+        const installedCommands = await super.installCommands(flowPath, config);
+
+        // For simple flow, create symlink to make specs visible in Kiro
+        if (flowPath.includes('simple')) {
+            await this.createSpecsSymlink();
+        }
+
+        return installedCommands;
+    }
+
+    /**
+     * Create symlink from .kiro/specs to specs/ for Kiro specifications compatibility
+     */
+    async createSpecsSymlink() {
+        const kiroSpecsPath = path.join('.kiro', 'specs');
+        const specsPath = 'specs';
+
+        // Only create if .kiro/specs doesn't exist
+        if (await fs.pathExists(kiroSpecsPath)) {
+            console.log(theme.dim(`  .kiro/specs already exists, skipping symlink`));
+            return;
+        }
+
+        // Ensure specs folder exists
+        await fs.ensureDir(specsPath);
+
+        try {
+            // Create relative symlink from .kiro/specs -> ../specs
+            await fs.ensureSymlink(path.join('..', specsPath), kiroSpecsPath);
+            CLIUtils.displayStatus('', 'Created .kiro/specs symlink for Kiro compatibility', 'success');
+        } catch (err) {
+            console.log(theme.warning(`  Failed to create specs symlink: ${err.message}`));
+        }
+    }
 }
 
 module.exports = KiroInstaller;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specsmd",
-  "version": "0.0.0-dev.27",
+  "version": "0.0.0-dev.29",
   "description": "Multi-agent orchestration system for AI-native software development. Delivers AI-DLC, Agile, and custom SDLC flows as markdown-based agent systems.",
   "main": "lib/installer.js",
   "bin": {