specsmd 0.0.1

package/flows/aidlc/memory-bank.yaml

@@ -0,0 +1,104 @@
+# Memory Bank Configuration for AI-DLC Flow
+# Defines the directory structure and required folders for project context
+
+# Structure created at project initialization
+# Note: units/ and stories/ are NOT created at init - they are created
+# dynamically when intents are elaborated during Inception phase
+structure:
+  - path: intents/
+    description: "Intents (Features/Capabilities) - units created per intent"
+  - path: bolts/
+    description: "Execution Instances (Bolt Sessions)"
+  - path: standards/
+    description: "Project Standards (Architecture, Tech Stack)"
+  - path: operations/
+    description: "Operations Context (Deployment, Monitoring)"
+
+# Project configuration file (created during project-init)
+project_config:
+  path: "memory-bank/project.yaml"
+  description: "Project type and initialization metadata"
+  fields:
+    - project_type: "full-stack-web | backend-api | frontend-app | cli-tool | library"
+    - initialized_at: "ISO 8601 timestamp"
+
+# Dynamic structure (created by agents, not at init)
+# - intents/{NNN}-{intent-name}/           → Created by Inception when intent is created
+# - intents/{NNN}-{intent-name}/units/     → Created by Inception when units are defined
+# - intents/{NNN}-{intent-name}/units/{unit-name}/stories/ → Created when stories are added
+
+# Data Conventions (CRITICAL - Agents MUST follow these)
+conventions:
+  timestamps:
+    format: "ISO 8601 with time and timezone"
+    pattern: "YYYY-MM-DDTHH:MM:SSZ"
+    example: "2024-12-05T10:30:00Z"
+    note: "ALL timestamps in memory-bank artifacts MUST include time, not just date"
+    applies_to:
+      - "created, started, completed fields in bolt files"
+      - "stages_completed entries"
+      - "construction-log entries"
+      - "inception-log entries"
+      - "any date/time field in frontmatter"
+
+# Naming Conventions (CRITICAL - Agents MUST follow these)
+# All names are derived from folder/file names - NO frontmatter prefixes needed
+naming:
+  intents:
+    format: "{NNN}-{intent-name}"
+    example: "001-user-authentication"
+    note: "3-digit prefix indicates order, kebab-case name"
+
+  units:
+    format: "{unit-name}"
+    example: "auth-service"
+    note: "Kebab-case, descriptive name"
+
+  stories:
+    format: "{SSS}-{title-slug}.md"
+    example: "001-user-signup.md"
+    note: "3-digit story number + kebab-case story title"
+    full_path_example: "memory-bank/intents/001-user-authentication/units/auth-service/stories/001-user-signup.md"
+
+  bolts:
+    format: "bolt-{unit-name}-{N}/"
+    example: "bolt-auth-service-1/"
+    note: "Directory per bolt, contains bolt.md and stage artifacts"
+    contents:
+      - "bolt.md"                      # Bolt instance metadata
+      - "ddd-01-domain-model.md"       # Stage 1 artifact (DDD bolt)
+      - "ddd-02-technical-design.md"   # Stage 2 artifact (DDD bolt)
+      - "ddd-03-test-report.md"        # Stage 4 artifact (DDD bolt)
+
+# Schema Definition (Source of Truth for Agents)
+schema:
+  intents: "memory-bank/intents/{intent-name}/"
+  units: "memory-bank/intents/{intent-name}/units/{unit-name}/"
+  stories: "memory-bank/intents/{intent-name}/units/{unit-name}/stories/"
+  bolts: "memory-bank/bolts/{bolt-id}/"
+  bolt-artifacts: "memory-bank/bolts/{bolt-id}/"
+  standards: "memory-bank/standards/"
+  story-index: "memory-bank/story-index.md"
+  inception-log: "memory-bank/intents/{intent-name}/inception-log.md"
+  construction-log: "memory-bank/intents/{intent-name}/units/{unit-name}/construction-log.md"
+
+  # Agent Ownership
+  # Note: Both Inception and Construction can plan/create bolts
+  # Inception: initial planning, Construction: replanning during execution
+  ownership:
+    inception: [intents, units, stories, story-index, bolts]  # Plans bolts initially
+    construction: [units, bolts]                               # Executes and can replan bolts
+    operations: [operations]
+
+# Global Story Index Options
+# Choose ONE approach for project-wide story tracking
+story-index:
+  enabled: true
+  # Options:
+  #   1. single-file: One story-index.md at memory-bank root (recommended for small projects)
+  #   2. per-intent: One story-index.md per intent folder (recommended for large projects)
+  #   3. aggregate: Auto-generated from unit-level stories (computed, not stored)
+  mode: "single-file"
+  path: "memory-bank/story-index.md"
+
+

package/flows/aidlc/quick-start.md

@@ -0,0 +1,315 @@
+# specsmd AI-DLC Quick Start Guide
+
+Get started with AI-Driven Development Lifecycle in minutes.
+
+---
+
+## Installation
+
+```bash
+npx specsmd@latest install
+```
+
+The installer will:
+
+1. Detect available agentic coding tools (Claude Code, Cursor, GitHub Copilot)
+2. Install agent definitions and skills
+3. Set up the memory bank structure
+4. Create slash commands for your tools
+
+---
+
+## Three-Phase Workflow
+
+AI-DLC has three sequential phases, each with a specialized agent:
+
+| Phase | Agent | Purpose |
+|-------|-------|---------|
+| **Inception** | Inception Agent | Capture intents, gather requirements, decompose into units |
+| **Construction** | Construction Agent | Execute bolts (rapid iterations) to build code |
+| **Operations** | Operations Agent | Deploy, verify, and monitor |
+
+The **Master Agent** orchestrates everything and helps you navigate.
+
+---
+
+## Quick Start Flow
+
+### Step 1: Initialize Your Project
+
+Open your AI coding tool (Claude Code, Cursor, etc.) and type this command as a prompt:
+
+```text
+/specsmd-master-agent
+```
+
+Then type `project-init` or `init` when prompted.
+
+This guides you through:
+
+- **Project type selection** (full-stack, backend API, frontend, CLI, library)
+- **Tech stack decisions** (language, framework, database, ORM)
+- **Coding standards** (formatting, linting, testing strategy)
+- **Optional standards** (architecture, UX guide, API conventions)
+
+Standards are saved to `memory-bank/standards/` and provide context for all AI agents.
+
+### Step 2: Create Your First Intent
+
+Switch to the Inception Agent:
+
+```text
+/specsmd-inception-agent intent-create
+```
+
+An **Intent** is a high-level goal. Examples:
+
+- "User authentication system"
+- "Product catalog with search"
+- "Payment processing integration"
+
+The agent will:
+
+1. Capture the intent
+2. Elaborate requirements
+3. Define system context
+4. Decompose into units
+
+### Step 3: Plan and Start Bolts
+
+Once units are defined, plan your first bolt:
+
+```text
+/specsmd-inception-agent bolt-plan
+```
+
+A **Bolt** is a rapid iteration (hours to days). Four types available:
+
+| Bolt Type | Best For |
+|-----------|----------|
+| **DDD Construction** | Complex business logic, domain modeling |
+| **TDD Construction** | Well-defined interfaces, test-first |
+| **BDD Construction** | User-facing features, acceptance criteria |
+| **Spike** | Research, exploration, unknowns |
+
+### Step 4: Execute Bolts
+
+Switch to the Construction Agent to execute:
+
+```text
+/specsmd-construction-agent bolt-start
+```
+
+Each bolt goes through stages:
+
+1. **Domain Design** - Model the domain
+2. **Logical Design** - Define interfaces and structure
+3. **Code** - Implement the solution
+4. **Test** - Verify correctness
+
+Human validation happens at each stage.
+
+### Step 5: Deploy
+
+When bolts are complete, use the Operations Agent:
+
+```text
+/specsmd-operations-agent deploy
+```
+
+---
+
+## Agent Commands Reference
+
+### Master Agent (`/specsmd-master-agent`)
+
+| Skill | Purpose |
+|-------|---------|
+| `project-init` | Initialize project with standards |
+| `analyze-context` | View current project state |
+| `route-request` | Get directed to the right agent |
+| `explain-flow` | Learn about AI-DLC methodology |
+| `answer-question` | Get help with any specsmd question |
+
+### Inception Agent (`/specsmd-inception-agent`)
+
+| Skill | Purpose |
+|-------|---------|
+| `intent-create` | Create a new intent |
+| `intent-list` | List all intents |
+| `requirements` | Elaborate intent requirements |
+| `context` | Define system context |
+| `units` | Decompose into units |
+| `story-create` | Create stories for a unit |
+| `bolt-plan` | Plan bolts for stories |
+| `review` | Review inception artifacts |
+| `navigator` | Navigate inception workflow |
+
+### Construction Agent (`/specsmd-construction-agent`)
+
+| Skill | Purpose |
+|-------|---------|
+| `bolt-start` | Start executing a bolt |
+| `bolt-status` | Check bolt progress |
+| `bolt-list` | List all bolts |
+| `bolt-plan` | Plan additional bolts |
+| `navigator` | Navigate construction workflow |
+
+### Operations Agent (`/specsmd-operations-agent`)
+
+| Skill | Purpose |
+|-------|---------|
+| `build` | Build the project |
+| `deploy` | Deploy to environment |
+| `verify` | Verify deployment |
+| `monitor` | Set up monitoring |
+
+---
+
+## Project Types
+
+Choose your project type during initialization:
+
+| Type | Required Standards | Recommended Standards |
+|------|-------------------|----------------------|
+| **full-stack-web** | tech-stack, coding-standards | system-architecture, ux-guide, api-conventions |
+| **backend-api** | tech-stack, coding-standards | system-architecture, api-conventions |
+| **frontend-app** | tech-stack, coding-standards | ux-guide |
+| **cli-tool** | tech-stack, coding-standards | - |
+| **library** | tech-stack, coding-standards | api-conventions |
+
+---
+
+## File Structure
+
+After installation, your project will have:
+
+```text
+.specsmd/
+├── manifest.yaml                 # Installation manifest
+└── aidlc/                        # AI-DLC flow
+    ├── agents/                   # Agent definitions (master, inception, construction, operations)
+    ├── commands/                 # Slash commands for agentic tools
+    ├── skills/                   # Agent skills by phase
+    │   ├── master/               # Master agent skills
+    │   ├── inception/            # Inception phase skills
+    │   ├── construction/         # Construction phase skills
+    │   └── operations/           # Operations phase skills
+    ├── templates/                # Artifact templates
+    │   ├── inception/            # Intent, unit, story templates
+    │   ├── construction/         # Bolt templates and bolt-types
+    │   │   └── bolt-types/       # DDD, TDD, BDD, Spike bolt definitions
+    │   └── standards/            # Standards facilitation
+    │       ├── catalog.yaml      # Standards registry
+    │       └── *.guide.md        # Facilitation guides
+    ├── shared/                   # Shared agent behaviors
+    ├── memory-bank.yaml          # Memory bank schema
+    ├── context-config.yaml       # Context loading configuration
+    ├── quick-start.md            # This file
+    └── README.md                 # Detailed documentation
+
+memory-bank/                      # Created after project-init
+├── intents/                      # Your captured intents
+│   └── {intent-name}/
+│       ├── requirements.md
+│       ├── system-context.md
+│       ├── units.md
+│       └── units/
+│           └── {unit-name}/
+│               ├── unit-brief.md
+│               └── stories/
+│                   └── {NNN}-{title}.md
+├── bolts/                        # Bolt execution records
+│   └── {bolt-id}/
+│       ├── bolt.md               # Bolt definition
+│       └── {stage-artifacts}.md  # Stage outputs
+├── standards/                    # Your project standards
+│   ├── tech-stack.md
+│   ├── coding-standards.md
+│   └── ...
+└── operations/                   # Deployment context
+```
+
+---
+
+## Key Concepts
+
+### Intent
+
+A high-level statement of purpose. The starting point for AI-driven decomposition.
+
+### Unit
+
+A cohesive, self-contained work element derived from an Intent. Analogous to a Subdomain (DDD) or Epic (Scrum).
+
+### Bolt
+
+The smallest iteration in AI-DLC. Unlike Sprints (weeks), Bolts are hours to days. Four types: DDD, TDD, BDD, Spike.
+
+### Memory Bank
+
+File-based storage for all project artifacts. Maintains context across agent sessions.
+
+### Standards
+
+Project decisions that inform AI code generation (tech stack, coding style, architecture).
+
+---
+
+## Human Validation
+
+AI-DLC emphasizes human oversight as a "loss function" - catching errors early.
+
+**Key validation points:**
+
+- After requirements elaboration
+- After unit decomposition
+- After story creation
+- After each bolt stage
+- Before deployment
+
+Each validation step transforms artifacts into rich context for subsequent stages.
+
+---
+
+## Tips for Success
+
+1. **Start with standards** - Project-init ensures AI agents understand your preferences
+2. **Keep intents focused** - One major goal per intent
+3. **Validate frequently** - Don't skip human checkpoints
+4. **Use fresh chats** - Each agent invocation starts fresh; context comes from Memory Bank
+5. **Trust the process** - AI-DLC is iterative; refinement happens naturally
+
+---
+
+## Troubleshooting
+
+### Agents don't remember context
+
+Agents are stateless. They read from Memory Bank at startup. Ensure artifacts are saved after each step.
+
+### Standards not being followed
+
+Re-run `project-init` to update standards. Agents load standards fresh each session.
+
+### Reset project state
+
+- Clear `memory-bank/` to reset artifacts
+- Delete `.specsmd/` to uninstall specsmd
+
+### Get help
+
+```text
+/specsmd-master-agent
+# Then type: answer-question "your question here"
+```
+
+---
+
+## What's Next?
+
+1. Run `/specsmd-master-agent` and type `project-init` to set up your project
+2. Create your first intent with `/specsmd-inception-agent intent-create`
+3. Follow the guided workflow through Inception → Construction → Operations
+
+Welcome to AI-native development!

package/flows/aidlc/skills/construction/bolt-list.md

@@ -0,0 +1,163 @@
+# Skill: List Bolts
+
+---
+
+## Checkpoints in This Skill
+
+| Checkpoint | Purpose | Wait For |
+|------------|---------|----------|
+| Checkpoint 1 | Which bolt to work on? | User selection |
+
+---
+
+## Goal
+
+Display all bolt instances with their status, optionally filtered by unit or intent.
+
+---
+
+## Input
+
+- **Required**: `.specsmd/aidlc/memory-bank.yaml` - artifact schema
+- **Optional**: `--unit` - filter by unit name
+- **Optional**: `--intent` - filter by intent name
+
+---
+
+## Process
+
+### 1. Load Schema
+
+Read `.specsmd/aidlc/memory-bank.yaml` to get the `bolts` path.
+*(Default: `memory-bank/bolts/`)*
+
+### 2. Scan Bolt Files
+
+For each bolt directory in `memory-bank/bolts/`:
+
+1. Read `bolt.md` frontmatter for metadata
+2. Extract: id, unit, intent, bolt_type, status, current_stage, stories
+3. The `bolt_type` field indicates which bolt type definition to use for stage information
+
+### 3. Apply Filters
+
+If `--unit` or `--intent` provided:
+
+- Filter bolts to match the specified criteria
+- Show "No bolts found" if none match
+
+### 4. Calculate Progress
+
+For each bolt, determine progress:
+
+- **planned**: 0% - Not started
+- **in-progress**: `stages_completed / total_stages`
+- **completed**: 100%
+- **blocked**: Show blocker reason
+
+### 5. Display Results
+
+Sort bolts by:
+
+1. In-progress first (active work)
+2. Planned (upcoming)
+3. Blocked (needs attention)
+4. Completed (historical)
+
+---
+
+## Output
+
+```markdown
+## Bolts Overview
+
+### Active Bolts
+
+- ⏳ **bolt-auth-2** (auth-service, {bolt-type}) - Stage: {current-stage}, 2/4 (50%) ← working
+
+### Planned Bolts
+
+- [ ] **bolt-auth-3** (auth-service) - Stories: 005-*, 006-* - Ready ✅
+- [ ] **bolt-payments-1** (payment-api) - Stories: 001-*, 002-*, 003-* - Ready ✅
+
+### Blocked Bolts
+
+- 🚫 **bolt-api-1** - Waiting for auth (since 2024-12-04)
+
+### Completed Bolts
+
+- ✅ **bolt-auth-1** (auth-service) - Completed 2024-12-05 (4 hours)
+
+### Summary
+- **Total**: {n} bolts
+- **In Progress**: {n}
+- **Planned**: {n}
+- **Completed**: {n}
+- **Blocked**: {n}
+
+### Actions
+
+1 - **Continue active bolt**: Resume `bolt-auth-2`
+2 - **Start planned bolt**: Begin `bolt-auth-3`
+3 - **View bolt status**: Check detailed status
+4 - **Plan new bolts**: Create additional bolts
+
+**Type a number or bolt ID to continue.**
+```
+
+---
+
+## Output (Filtered)
+
+```markdown
+## Bolts for Unit: {unit-name}
+
+- ✅ **bolt-{unit}-1** ({bolt-type}) - Completed 100% - Stories: 001-*, 002-*
+- ⏳ **bolt-{unit}-2** ({bolt-type}) - In progress 50% - Stories: 003-*, 004-* ← current
+- [ ] **bolt-{unit}-3** ({bolt-type}) - Planned 0% - Stories: 005-*
+
+### Quick Actions
+
+1 - **Continue bolt-{unit}-2**: Resume current work
+2 - **View bolt-{unit}-1 status**: Review completed bolt
+
+**Type a number to continue.**
+```
+
+---
+
+## Bolt Selection
+
+**Checkpoint 1**: Ask user which bolt to work on:
+
+```text
+### Available Bolts
+
+1 - bolt-{unit}-1 (planned) - Stories: 001-*, 002-*
+2 - bolt-{unit}-2 (planned) - Stories: 003-*, 004-*
+
+Which bolt would you like to work on?
+```
+
+**Wait for user response.**
+
+**CRITICAL**: Never auto-select a bolt. Always ask which bolt.
+
+---
+
+## Transition
+
+After user selects bolt at Checkpoint 1:
+
+- → **Bolt Start** - execute selected bolt
+
+---
+
+## Test Contract
+
+```yaml
+input: Unit name or intent filter
+output: List of bolts with status
+checkpoints: 1
+  - Checkpoint 1: User selects which bolt to work on
+```