specsmd 0.0.1

package/flows/aidlc/skills/master/answer-question.md

@@ -0,0 +1,141 @@
+# Skill: Answer Question
+
+---
+
+## Role
+
+Knowledge retrieval skill to answer questions by querying memory bank artifacts.
+
+**NO Checkpoint** - Answering questions is informational, not a decision point.
+
+---
+
+## Goal
+
+Answer user questions about the project by querying the Memory Bank artifacts.
+
+---
+
+## Input
+
+- **Required**: User's question
+- **Required**: `.specsmd/aidlc/memory-bank.yaml` - artifact schema
+
+---
+
+## Process
+
+### 1. Parse the Question
+
+Identify what type of information is being requested:
+
+- **Status of intent/unit/bolt** → Check respective artifact files
+- **Configuration/settings** → `{schema.standards}/`
+- **Requirements** → `{intent}/requirements.md`
+- **Architecture decisions** → `{unit}/ddd-02-technical-design.md` or `standards/system-architecture.md`
+- **Deployment info** → `{unit}/deployment/`
+- **Story details** → `{unit}/stories/`
+
+### 2. Search Logic
+
+1. **Extract keywords** from the question
+2. **Locate artifacts** using schema paths from `.specsmd/aidlc/memory-bank.yaml`
+3. **Read relevant files** to find the answer
+4. **Cite sources** in your response
+
+### 3. Formulate Answer
+
+**If found**:
+
+```markdown
+## Answer
+
+{Direct answer to the question}
+
+**Source**: `{path/to/file.md}`
+```
+
+**If not found**:
+
+```markdown
+## Answer
+
+I couldn't find information about "{topic}" in the memory bank.
+
+**Searched**:
+- `{path1}` - not found
+- `{path2}` - not found
+
+**Suggestions**:
+- Would you like to create this artifact?
+- Is this information stored elsewhere?
+```
+
+---
+
+## Common Questions & Sources
+
+- **"What is the status of {bolt}?"** → `{schema.bolts}` - check `status` field
+- **"What requirements do we have?"** → `{schema.intents}/{intent}/requirements.md`
+- **"What units are in {intent}?"** → `{schema.intents}/{intent}/units.md`
+- **"What stories are in {unit}?"** → `{schema.stories}` directory
+- **"What's the tech stack?"** → `{schema.standards}/tech-stack.md`
+- **"What are our coding standards?"** → `{schema.standards}/coding-standards.md`
+- **"What's the system architecture?"** → `{schema.standards}/system-architecture.md`
+- **"When was {unit} deployed?"** → `{schema.units}/{unit}/deployment/history.md`
+
+---
+
+## Output
+
+```markdown
+## {Question Rephrased}
+
+{Clear, direct answer}
+
+### Details
+{Supporting information if relevant}
+
+### Source
+- `{path/to/source/file.md}`
+
+### Related Information
+- {Other relevant artifacts if any}
+
+### Actions
+
+1 - **more**: Get more details
+2 - **action**: Take action based on this information
+3 - **another**: Ask another question
+
+### Suggested Next Step
+→ **more** - Learn more about {specific aspect}
+
+**Type a number or press Enter for suggested action.**
+```
+
+---
+
+## Human Validation Point
+
+> "Does this answer your question? Would you like more details about {specific aspect}?"
+
+---
+
+## Transition
+
+After answering:
+
+- → **Route Request** (`.specsmd/skills/master/route-request.md`) - if user wants to take action
+- → **Analyze Context** (`.specsmd/skills/master/analyze-context.md`) - if user wants overall status
+- → Stay in Q&A mode if user has more questions
+
+---
+
+## Test Contract
+
+```yaml
+input: User question
+output: Answer with source citations or acknowledgment of not found
+checkpoints: 0 (informational only)
+```

package/flows/aidlc/skills/master/explain-flow.md

@@ -0,0 +1,146 @@
+# Skill: Explain Flow
+
+---
+
+## Role
+
+Educational skill to explain AI-DLC methodology and help users understand their position in the workflow.
+
+**NO Checkpoint** - Explanation is educational, not a decision point.
+
+---
+
+## Goal
+
+Explain the AI-DLC methodology and help the user understand where they are in the process.
+
+---
+
+## Input
+
+- **Required**: User's question about the flow
+- **Optional**: Current project state (from `analyze-context.md`)
+
+---
+
+## Process
+
+### 1. Provide Overview
+
+```markdown
+## AI-DLC: AI-Driven Development Lifecycle
+
+AI-DLC is a reimagined development methodology where AI drives the workflow and humans validate at key decision points.
+
+### The Three Phases
+
+1. **Inception** → Planning & Design
+   - Capture intents (high-level goals)
+   - Elaborate into requirements, units, and stories
+   - Plan bolts for construction
+   - Output: Complete implementation plan
+
+2. **Construction** → Building & Testing
+   - Execute bolts through their stages
+   - AI generates designs, code, and tests
+   - Human validates at each stage
+   - Output: Tested, working code
+
+3. **Operations** → Deploy & Monitor
+   - Package deployment units
+   - Deploy through environments (Dev → Staging → Prod)
+   - Setup monitoring and observability
+   - Output: Running production system
+
+### Key Concepts
+
+- **Intent**: High-level goal or feature request
+- **Unit**: Independently deployable component (like a bounded context)
+- **Story**: User story with acceptance criteria
+- **Bolt**: Time-boxed execution session (hours/days, not weeks)
+- **Bolt Type**: Methodology template (DDD, BDD, TDD)
+
+### Core Principles
+
+- **AI Drives, Human Validates**: AI proposes, humans approve
+- **Human Oversight as Loss Function**: Catch errors early before they compound
+- **Semantically Rich Context**: Each step builds context for the next
+- **Rapid Iteration**: Bolts are hours/days, not weeks
+```
+
+### 2. Show Current Position (if known)
+
+```markdown
+### Where You Are Now
+
+    Inception ──────► Construction ──────► Operations
+        │                  │                   │
+        ▼                  ▼                   ▼
+    [CURRENT] ───────► [Planned] ────────► [Future]
+
+You are in the **{phase}** phase, working on **{intent/unit/bolt}**.
+
+Next step: {specific action}
+
+```
+
+### 3. Answer Specific Questions
+
+- **"What is a bolt?"** → Explain bolt concept with analogy to sprints
+- **"How long does inception take?"** → Hours, not weeks - it's intensive but fast
+- **"When do I move to construction?"** → When all stories are defined and bolts planned
+- **"What's the difference from Agile?"** → AI-DLC is AI-native, rapid iterations, integrated design
+
+---
+
+## Output
+
+Provide a tailored explanation based on the user's question:
+
+```markdown
+## {Topic} Explained
+
+{Clear, concise explanation}
+
+### Your Current Context
+{Where user is in the flow, if known}
+
+### What This Means For You
+{Practical implications}
+
+### Actions
+
+1 - **proceed**: Execute recommended action
+2 - **more**: Learn more about this topic
+3 - **different**: Ask about something else
+
+### Suggested Next Step
+→ **proceed** - {Recommended action}
+
+**Type a number or press Enter for suggested action.**
+```
+
+---
+
+## Human Validation Point
+
+> "Does this explanation help? Would you like me to elaborate on any part, or are you ready to proceed with {next action}?"
+
+---
+
+## Transition
+
+After explanation:
+
+- → **Route Request** (`.specsmd/skills/master/route-request.md`) - if user wants to proceed
+- → **Answer Question** (`.specsmd/skills/master/answer-question.md`) - if user has more questions
+
+---
+
+## Test Contract
+
+```yaml
+input: User question about AI-DLC flow
+output: Tailored explanation with current position highlighted
+checkpoints: 0 (educational only)
+```

package/flows/aidlc/skills/master/project-init.md

@@ -0,0 +1,281 @@
+# Skill: Project Init
+
+---
+
+## Role
+
+Setup skill to initialize a new project by facilitating creation of project standards through guided conversation.
+
+**NO Checkpoint** - Project initialization is a setup process. Standards are confirmed individually during the conversation.
+
+---
+
+## Goal
+
+Initialize a new project by facilitating the creation of project standards through guided conversation. Standards ensure AI agents have the context needed to generate consistent, high-quality code.
+
+---
+
+## Input
+
+- **Required**: `.specsmd/aidlc/templates/standards/catalog.yaml` - defines available standards
+- **Optional**: Project type hint from user (e.g., "full-stack web app", "backend API")
+- **Optional**: Existing standards files to review/update
+
+---
+
+## Process
+
+### 1. Load Standards Catalog
+
+Read `.specsmd/aidlc/templates/standards/catalog.yaml` to understand:
+
+- Available standards and their importance
+- Decisions within each standard
+- Dependencies between standards
+- Project type presets
+
+### 2. Determine Project Type
+
+Ask the user what kind of project they're building:
+
+```markdown
+## Project Setup
+
+Before we dive into technical choices, what kind of project are you building?
+
+1. **Full-stack web app** - Frontend + backend + database
+2. **Backend API** - API service, no frontend
+3. **Frontend app** - SPA or SSR frontend
+4. **CLI tool** - Command-line application
+5. **Library** - Reusable package/module
+6. **Other** - Tell me more
+
+This helps me know which standards we need to discuss.
+```
+
+Use the project type to determine:
+
+- Required standards (must create)
+- Recommended standards (suggest, but optional)
+- Skippable standards (not relevant)
+
+**IMPORTANT**: After determining project type, immediately save it to `memory-bank/project.yaml`:
+
+```yaml
+# Project Configuration
+# Generated by project-init
+
+project_type: {selected-type}  # e.g., full-stack-web, backend-api, frontend-app, cli-tool, library
+initialized_at: {ISO timestamp}
+```
+
+This file MUST be created before proceeding to standards facilitation, as other agents (e.g., Inception) read it to provide context-aware suggestions.
+
+### 3. Check Existing Standards
+
+Before creating new standards, check if any exist:
+
+- Read `standards/` directory
+- If files exist, ask: "I found existing standards. Do you want to review and update them, or start fresh?"
+
+### 4. Facilitate Each Standard
+
+For each required/recommended standard:
+
+1. **Load the facilitation guide** from `templates/standards/{standard}.guide.md`
+2. **Follow the guide's discovery process** - don't invent your own questions
+3. **Adapt to user expertise** - be concise with experts, explanatory with newcomers
+4. **Confirm before saving** - summarize choices, get approval
+5. **Generate the standard file** - using the output format in the guide
+6. **Save to path** defined in catalog (`output_path`)
+
+### 5. Order of Standards
+
+Follow dependency order from catalog:
+
+1 - **tech-stack**: No dependencies
+2 - **coding-standards**: Depends on tech-stack
+3 - **system-architecture**: Depends on tech-stack (optional)
+4 - **ux-guide**: Depends on tech-stack (optional)
+5 - **api-conventions**: Depends on tech-stack (optional)
+
+Never create a standard before its dependencies are satisfied.
+
+### 6. Handle Optional Standards
+
+For optional/recommended standards:
+
+```markdown
+## Optional: {Standard Name}
+
+Based on your project type, this standard is recommended but not required:
+- **{standard}**: {description from catalog}
+
+Would you like to define this now, or skip for later?
+```
+
+---
+
+## Facilitation Principles
+
+### Adaptive Communication
+
+**Read user signals:**
+
+- Mentions specific tech confidently → treat as experienced
+- Asks "what do you recommend?" → provide guidance
+- Says "I don't know" → explain tradeoffs, suggest defaults
+- Has strong opinions → respect them, validate coherence
+
+**Adjust your style:**
+
+- Expert: "TypeScript with Next.js? Got it. Deployment target?"
+- Beginner: "TypeScript is great for catching bugs early. Since you mentioned React, Next.js would give you server-side rendering and easy deployment..."
+
+### Collaborative Discovery
+
+- **Don't interrogate** - have a conversation
+- **Build context** - previous answers inform later questions
+- **Surface tradeoffs** - help them make informed decisions
+- **Capture rationale** - "why" is as important as "what"
+
+### Question Format (CRITICAL)
+
+**ALWAYS format questions like this:**
+
+```markdown
+## [Topic Name]
+
+[Brief context if needed - 1-2 sentences max]
+
+1. **Option A** - description
+2. **Option B** - description
+3. **Option C** - description
+4. **Other** - let me know
+
+Type a number or describe your choice.
+```
+
+**Example - GOOD:**
+
+```markdown
+## Database
+
+1. **SQLite** - Simple, file-based, great for small apps
+2. **PostgreSQL** - Robust, scalable, widely supported
+3. **MySQL** - Popular, good for web apps
+4. **MongoDB** - Document store, flexible schema
+5. **TBD** - Decide later
+
+Type a number or tell me your preference.
+```
+
+**Example - BAD (never do this):**
+
+```markdown
+What database are you using? And where will you deploy? Also what's your auth strategy?
+```
+
+**If user gives partial answer:**
+> User says "PostgreSQL"
+> You asked about database AND deployment
+> → Acknowledge the database choice, then re-ask ONLY about deployment
+
+### Practical Defaults
+
+When user is unsure, offer sensible defaults:
+> "For a TypeScript web app, most teams start with: Prettier for formatting, ESLint with strict mode, and Vitest for testing. These are well-supported and work great with AI code generation. Sound good as a starting point?"
+
+---
+
+## Output
+
+After completing all standards:
+
+```markdown
+## Project Initialization Complete
+
+### Standards Created
+
+- ✅ **Tech Stack**: Created at `standards/tech-stack.md`
+- ✅ **Coding Standards**: Created at `standards/coding-standards.md`
+- ⏭️ **System Architecture**: Skipped
+- ⏭️ **UX Guide**: Skipped
+- ⏭️ **API Conventions**: Skipped
+
+### Summary
+
+Your project is configured as a **{project type}** using:
+- **Language**: {language}
+- **Framework**: {framework}
+- **Database**: {database or "TBD"}
+
+### What These Standards Enable
+
+AI agents will now:
+- Generate code matching your style preferences
+- Use your chosen libraries and patterns
+- Follow your testing strategy
+- Understand your project structure
+
+### Actions
+
+1 - **inception**: Create your first intent
+2 - **standards**: Add more optional standards
+3 - **menu**: Return to main menu
+
+### Suggested Next Step
+→ **inception** - Create your first intent with `/specsmd-inception-agent`
+
+**Type a number or press Enter for suggested action.**
+```
+
+---
+
+## Human Validation Points
+
+At each standard completion:
+> "I've captured your {standard} preferences. Here's the summary: {brief summary}. Does this look right? Any changes before I save?"
+
+At project init completion:
+> "Your project is initialized with {n} standards. AI agents now have the context they need. Ready to create your first intent?"
+
+---
+
+## Error Handling
+
+### Missing Catalog
+
+If `catalog.yaml` is not found:
+> "I can't find the standards catalog. Please ensure `.specsmd/aidlc/templates/standards/catalog.yaml` exists."
+
+### Missing Guide
+
+If a facilitation guide is missing:
+> "The facilitation guide for {standard} is missing. I'll skip this standard. You can create it manually at `standards/{standard}.md`."
+
+### Dependency Not Met
+
+If trying to create a standard before its dependency:
+> "We need to define {dependency} before {standard}. Let's do that first."
+
+---
+
+## Transition
+
+After project initialization:
+
+- → **Inception Agent** (`.specsmd/agents/inception-agent.md`) - to create first intent
+- → **Analyze Context** (`.specsmd/skills/master/analyze-context.md`) - if user wants to see project state
+- → **Project Init** again - to add optional standards later
+
+---
+
+## Test Contract
+
+```yaml
+input: User responses to standards questions
+output: Created standards files in standards/ directory
+checkpoints: 0 (setup process with inline confirmations)
+```

package/flows/aidlc/skills/master/route-request.md

@@ -0,0 +1,126 @@
+# Skill: Route Request
+
+---
+
+## Role
+
+Routing skill to direct users to the appropriate specialist agent based on context and request.
+
+**NO Checkpoint** - Routing is a navigation function, not a decision point.
+
+---
+
+## Goal
+
+Direct the user to the appropriate specialist agent based on their current context and request.
+
+---
+
+## Input
+
+- **Required**: Completed context analysis (from `analyze-context.md`)
+- **Required**: User's request or intent
+
+---
+
+## Process
+
+### 1. Match State to Agent
+
+Based on project state:
+
+- **No intents / New feature request** → Inception Agent → `/specsmd-inception-agent`
+- **Intent exists, needs elaboration** → Inception Agent → `/specsmd-inception-agent --intent="{name}"`
+- **Ready for construction** → Construction Agent → `/specsmd-construction-agent --unit="{name}"`
+- **Bolt in progress** → Construction Agent → `/specsmd-construction-agent --unit="{name}" --bolt-id="{id}"`
+- **Ready for deployment** → Operations Agent → `/specsmd-operations-agent --unit="{name}"`
+- **In production, needs monitoring** → Operations Agent → `/specsmd-operations-agent --unit="{name}"`
+
+### 2. Handle Special Cases
+
+**User asks about something different than current state**:
+> "I see you're in {current phase}, but you're asking about {different thing}. Let me help you with that instead."
+
+**User is confused about what to do**:
+> "Based on your project state, the logical next step is {action}. Would you like me to route you there, or do you have something else in mind?"
+
+**Multiple options available**:
+> "You have several options at this point:
+>
+> 1. {Option 1} → {command}
+> 2. {Option 2} → {command}
+> Which would you like to pursue?"
+
+### 3. Provide Clear Handoff
+
+Always include:
+
+1. The specific command to run
+2. What parameters to include
+3. What the agent will help them do
+4. What to expect next
+
+---
+
+## Output
+
+````markdown
+## Routing Recommendation
+
+Based on your current state ({phase}) and request ({what user wants}):
+
+### Recommended Action
+→ **{Agent Name}**: {brief description of what it does}
+
+### Command
+```text
+{exact command with parameters}
+```
+
+### What Happens Next
+
+{Description of what the agent will guide them through}
+
+### Actions
+
+1 - **proceed**: Run the recommended command
+2 - **different**: Choose a different option
+3 - **explain**: Learn more about the target agent
+
+### Suggested Next Step
+
+→ **proceed** - Run the command above
+
+**Type a number or press Enter for suggested action.**
+````
+
+---
+
+## Human Validation Point
+
+> "I'm routing you to the {Agent Name}. This agent will help you {specific task}. Does this match what you're trying to accomplish?"
+
+---
+
+## Transition
+
+After routing:
+
+- User runs the provided command
+- Control transfers to the target agent
+- Master Agent is no longer active
+
+If user declines routing:
+
+- → **Answer Question** (`.specsmd/skills/master/answer-question.md`) - clarify their needs
+- → **Explain Flow** (`.specsmd/skills/master/explain-flow.md`) - explain the methodology
+
+---
+
+## Test Contract
+
+```yaml
+input: Context analysis + user request
+output: Routing recommendation with exact command
+checkpoints: 0 (routing only)
+```