@ydtb/specsmd 0.1.22

package/flows/aidlc/memory-bank.yaml

@@ -0,0 +1,105 @@
+# 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: "{UUU}-{unit-name}"
+    example: "001-auth-service"
+    note: "3-digit prefix within intent, kebab-case 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/001-auth-service/stories/001-user-signup.md"
+
+  bolts:
+    format: "{BBB}-{unit-name}/"
+    example: "001-auth-service/"
+    note: "Global 3-digit sequence, unit name for context"
+    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"
+  decision-index: "memory-bank/standards/decision-index.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, decision-index]               # Executes, can replan bolts, maintains decision index
+    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,322 @@
+# 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). Two types available:
+
+| Bolt Type | Best For |
+|-----------|----------|
+| **DDD Construction** | Complex business logic, domain modeling |
+| **Simple Construction** | UI, integrations, utilities |
+
+### Step 4: Execute Bolts
+
+Switch to the Construction Agent to execute:
+
+```text
+/specsmd-construction-agent bolt-start
+```
+
+Each bolt type has its own stages:
+
+**DDD Construction Bolt** (for complex business logic):
+
+1. **Domain Model** - Model the business domain
+2. **Technical Design** - Define interfaces and architecture
+3. **ADR Analysis** - Document significant decisions (optional)
+4. **Implement** - Write production code
+5. **Test** - Verify correctness
+
+**Simple Construction Bolt** (for UI, integrations, utilities):
+
+1. **Spec** - Define what to build
+2. **Implement** - Write the code
+3. **Test** - Verify it works
+
+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 and Simple 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. Two types: DDD Construction and Simple Construction.
+
+### 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!