specsmd 0.0.1

package/flows/aidlc/skills/inception/story-create.md

@@ -0,0 +1,304 @@
+# Skill: Create Stories
+
+---
+
+## Progress Display
+
+Show at start of this skill:
+
+```text
+### Inception Progress
+- [x] Intent created
+- [x] Requirements gathered
+- [ ] Generating artifacts...  ← current
+    - [x] System Context
+    - [x] Units
+    - [ ] Stories  ← this skill
+    - [ ] Bolt Plan
+- [ ] Artifacts reviewed (Checkpoint 3)
+- [ ] Ready for Construction
+```
+
+---
+
+## Checkpoints in This Skill
+
+**NO INDIVIDUAL Checkpoint** - This skill is part of the batched artifact generation.
+
+All artifacts (Context, Units, Stories, Bolts) are reviewed together at **Checkpoint 3** in the `review` skill.
+
+---
+
+## Goal
+
+Define atomic, testable User Stories for each Unit that will guide Construction.
+
+---
+
+## Input
+
+- **Required**: Unit name and `unit-brief.md`
+- **Required**: `.specsmd/aidlc/memory-bank.yaml` - artifact schema
+- **Optional**: Requirements to reference
+
+---
+
+## Process
+
+### 0. Gap Analysis (Internal)
+
+Before creating stories, analyze existing state internally:
+
+1. **Read story-index.md** if it exists
+2. **Scan story folders** for existing `.md` files
+3. **Identify gaps** - missing files, unmarked stories
+
+**Auto-proceed**: Create missing stories and update markers. Do not stop for user input.
+
+---
+
+### 1. Analyze Unit Brief
+
+Review the unit-brief.md to understand:
+
+- **Assigned Requirements** - FRs mapped to this unit (stories come from these)
+- Purpose and scope
+- Key entities and operations
+- Dependencies
+- Success criteria
+
+**IMPORTANT**: Stories are created from the unit's **Assigned Requirements** section, NOT directly from intent requirements.md. The FR-to-unit mapping happened during unit decomposition.
+
+### 2. Generate Stories
+
+For each feature in the unit:
+
+1. **Identify User Actions**: What can users do?
+2. **Break Down**: One story per testable behavior
+3. **Format**: Use standard user story format
+4. **Size**: Each story should be completable in one bolt stage
+
+**Story Format**:
+
+```markdown
+## Story: {story-id}
+
+### User Story
+As a {role}
+I want to {action}
+So that {benefit}
+
+### Acceptance Criteria
+- [ ] Given {context}, When {action}, Then {outcome}
+- [ ] Given {context}, When {action}, Then {outcome}
+
+### Technical Notes
+- {implementation hints if any}
+
+### Dependencies
+- {other stories this depends on}
+```
+
+### 3. Apply INVEST Criteria
+
+Validate each story against:
+
+- [ ] **I**ndependent: Can be developed without other stories? (Preferred)
+- [ ] **N**egotiable: Details can be refined during bolt? (Required)
+- [ ] **V**aluable: Delivers value to user? (Required)
+- [ ] **E**stimable: Scope is clear enough to plan? (Required)
+- [ ] **S**mall: Fits in a single bolt stage? (Required)
+- [ ] **T**estable: Acceptance criteria are binary? (Required)
+
+### 4. Group by Priority
+
+Organize stories for bolt planning:
+
+- **Must**: Core functionality (Authentication, core CRUD)
+- **Should**: Important but not blocking (Error handling, validation)
+- **Could**: Nice to have (Advanced features, optimizations)
+
+### 5. Document Stories
+
+1. **Read Path**: Check `schema.stories` from `.specsmd/aidlc/memory-bank.yaml`
+   *(Default: `memory-bank/intents/{intent-name}/units/{unit-name}/stories/`)*
+
+2. **Create Directory**:
+   Ensure `.../units/{unit-name}/stories/` exists
+
+3. **Create Story Files** (IMPORTANT - ONE FILE PER STORY):
+
+   **Read naming convention from `.specsmd/aidlc/memory-bank.yaml`**
+
+   Format: `{SSS}-{title-slug}.md`
+   - `{SSS}` = 3-digit story number (e.g., `001`, `002`)
+   - `{title-slug}` = Kebab-case story title (e.g., `user-can-login`)
+
+   **DO NOT** create a single `stories.md` file with all stories
+
+   Use template: `.specsmd/aidlc/templates/inception/story-template.md`
+
+   **Example for intent `001-user-authentication`, unit `auth-service` with 6 stories:**
+
+   ```text
+   001-user-authentication/
+   └── units/
+       └── auth-service/
+           ├── unit-brief.md
+           └── stories/
+               ├── 001-user-signup.md
+               ├── 002-user-login.md
+               ├── 003-user-logout.md
+               ├── 004-invite-members.md
+               ├── 005-remove-members.md
+               └── 006-change-roles.md
+   ```
+
+   **Global uniqueness** comes from the full path:
+   `memory-bank/intents/001-user-authentication/units/auth-service/stories/001-user-signup.md`
+
+4. **Link to Unit**:
+   Update unit's story index if one exists
+
+### 6. Update Unit Brief with Story Summary
+
+**CRITICAL**: After creating stories, update the unit-brief.md with a story summary.
+
+Add/update this section in the unit's `unit-brief.md`:
+
+```markdown
+---
+
+## Story Summary
+
+- **Total Stories**: {n}
+- **Must Have**: {n}
+- **Should Have**: {n}
+- **Could Have**: {n}
+
+### Stories
+
+- [ ] **AUTH-001**: User signup - Must - Planned
+- [ ] **AUTH-002**: User login - Must - Planned
+```
+
+This ensures each unit-brief shows its story count at a glance.
+
+### 7. Update Global Story Index
+
+**CRITICAL**: After creating EACH story, IMMEDIATELY update the index.
+
+**DO NOT** batch index updates - mark each story right after creating its file.
+
+1. **Read Configuration**: Check `story-index` settings in `.specsmd/aidlc/memory-bank.yaml`
+
+2. **Mark each story as generated:**
+
+   **Format - add ✅ GENERATED marker immediately after filename:**
+
+   ```markdown
+   ### 001-user-signup.md ✅ GENERATED
+   **Title**: User Registration with Password Hashing
+   ```
+
+   **Status markers:**
+   - No marker = Planned (not yet created)
+   - `✅ GENERATED` = File created
+   - `✅ COMPLETED` = Implemented in Construction
+
+3. **Based on mode**:
+
+   **Option 1: single-file** (default)
+   - Path: `memory-bank/story-index.md`
+   - Add all stories to the central index with full paths
+
+   **Option 2: per-intent**
+   - Path: `memory-bank/intents/{intent-name}/story-index.md`
+   - Create/update per-intent story indices
+
+   **Option 3: aggregate**
+   - No file to update (computed from unit stories on demand)
+
+4. **Story Index Format**:
+
+   ```markdown
+   # Global Story Index
+
+   ## Overview
+   - **Total stories**: {count}
+   - **Generated**: {count with ✅ GENERATED}
+   - **Last updated**: {date}
+
+   ---
+
+   ## Stories by Intent
+
+   ### {intent-name}
+
+   - [ ] **001-intent-AUTH-001** (auth): User signup - Must - Planned
+   - [x] **001-intent-AUTH-002** (auth): User login - Must - ✅ GENERATED
+   - [x] **001-intent-TASKS-001** (tasks): Create task - Must - ✅ COMPLETED
+
+   ---
+
+   ## Stories by Status
+
+   - **Planned**: {n}
+   - **Generated**: {n}
+   - **In Progress**: {n}
+   - **Completed**: {n}
+   ```
+
+5. **Verification after batch generation:**
+
+   After generating all stories for a unit, verify:
+
+   ```markdown
+   ### Verification: {unit-name}
+   - Stories planned: {n}
+   - Stories created: {n}
+   - Index updated: {n} marked ✅ GENERATED
+   - Gaps: {list any missing}
+   ```
+
+---
+
+## Output
+
+```markdown
+## Stories Created: {unit-name}
+
+### Story Summary
+
+- [ ] **S1**: User can register - Must - No dependencies
+- [ ] **S2**: User can login - Must - Requires S1
+- [ ] **S3**: User can reset password - Should - Requires S1
+- [ ] **S4**: User can enable MFA - Could - Requires S2
+
+### Acceptance Criteria Count
+- **Total criteria**: {n}
+- **Must-have stories**: {n}
+- **Should-have stories**: {n}
+- **Could-have stories**: {n}
+
+### Artifacts Created (one file per story)
+✅ `{unit-path}/stories/001-{title-slug}.md`
+✅ `{unit-path}/stories/002-{title-slug}.md`
+✅ `{unit-path}/stories/003-{title-slug}.md`
+
+### Estimated Bolt Coverage
+- Stories can be grouped into ~{n} bolts
+- Suggested grouping provided in bolt-plan
+```
+
+**No menu** - Skill complete, return to agent.
+
+---
+
+## Test Contract
+
+```yaml
+input: Unit brief, requirements
+output: Individual story files with acceptance criteria
+checkpoints: 0 (part of Checkpoint 3 batch)
+```

package/flows/aidlc/skills/inception/units.md

@@ -0,0 +1,271 @@
+# Skill: Decompose into Units
+
+---
+
+## Progress Display
+
+Show at start of this skill:
+
+```text
+### Inception Progress
+- [x] Intent created
+- [x] Requirements gathered
+- [ ] Generating artifacts...  ← current
+    - [x] System Context
+    - [ ] Units  ← this skill
+    - [ ] Stories
+    - [ ] Bolt Plan
+- [ ] Artifacts reviewed (Checkpoint 3)
+- [ ] Ready for Construction
+```
+
+---
+
+## Checkpoints in This Skill
+
+**NO INDIVIDUAL Checkpoint** - This skill is part of the batched artifact generation.
+
+All artifacts (Context, Units, Stories, Bolts) are reviewed together at **Checkpoint 3** in the `review` skill.
+
+---
+
+## Goal
+
+Break the Intent into independently deployable Units of Work based on project type configuration.
+
+---
+
+## Input
+
+- **Required**: Intent name
+- **Required**: `requirements.md` for the intent
+- **Required**: `system-context.md` for the intent
+- **Required**: `.specsmd/aidlc/memory-bank.yaml` - artifact schema
+- **Required**: `memory-bank/project.yaml` - project configuration (for project_type)
+- **Required**: `.specsmd/aidlc/templates/standards/catalog.yaml` - project type definitions
+
+---
+
+## Process
+
+### 1. Load Project Type Configuration
+
+**CRITICAL**: Before decomposing, understand what types of units to create.
+
+1. **Read project type** from `memory-bank/project.yaml`:
+   ```yaml
+   project_type: full-stack-web  # or backend-api, frontend-app, cli-tool, library
+   ```
+
+2. **Read unit structure** from `catalog.yaml` under `project_types.{project_type}.unit_structure`:
+   ```yaml
+   unit_structure:
+     backend:
+       enabled: true
+       decomposition: domain-driven
+       default_bolt_type: ddd-construction-bolt
+     frontend:
+       enabled: true
+       decomposition: feature-based
+       default_bolt_type: simple-construction-bolt
+       naming_pattern: "{intent}-ui"
+   ```
+
+3. **Determine which unit types to create**:
+   - If `backend.enabled: true` → Create backend service units using domain-driven decomposition
+   - If `frontend.enabled: true` → Create a frontend unit for UI work
+   - If `cli.enabled: true` → Create CLI command units
+
+**If project.yaml doesn't exist**, default to `backend-api` behavior (backend only).
+
+---
+
+### 2. Analyze Domain (Backend Units)
+
+**Skip this step if `backend.enabled: false`.**
+
+Review requirements and context to identify:
+
+- **Bounded Contexts**: "What distinct domains exist?"
+- **Aggregates**: "What are the core entities and their boundaries?"
+- **Services**: "What operations span multiple entities?"
+- **Integration Points**: "Where do contexts communicate?"
+
+### 3. Apply Decomposition Criteria (Backend Units)
+
+**Skip this step if `backend.enabled: false`.**
+
+For each potential unit, verify:
+
+- [ ] **Single Responsibility**: Does it do one thing well? (Required)
+- [ ] **Independence**: Can it be built/tested separately? (Required)
+- [ ] **Deployability**: Can it be deployed independently? (Preferred)
+- [ ] **Clear Interface**: Are inputs/outputs well-defined? (Required)
+- [ ] **Cohesion**: Do its parts belong together? (Required)
+
+### 4. Map Requirements to Units
+
+**CRITICAL**: Each FR from requirements.md must be assigned to exactly one unit.
+
+```markdown
+## Requirement-to-Unit Mapping
+
+- **FR-1**: {description} → `{unit-name}`
+- **FR-2**: {description} → `{unit-name}`
+- **FR-3**: {description} → `{unit-name}`
+```
+
+This mapping ensures:
+
+- Every FR is accounted for
+- Units have clear scope based on assigned FRs
+- Stories will be created from unit's assigned FRs (not directly from intent)
+
+### 5. Create Frontend Unit (if enabled)
+
+**Skip this step if `frontend.enabled: false`.**
+
+When `frontend.enabled: true` in the project type configuration, create a frontend unit:
+
+```markdown
+### Unit N: {intent}-ui
+
+- **Purpose**: Frontend application (pages, components, state management)
+- **Responsibility**: User interface and client-side logic
+- **Assigned Requirements**: All user-facing FRs
+- **Dependencies**: All backend service units
+- **Interface**: Consumes APIs from backend units
+- **Unit Type**: frontend
+- **Default Bolt Type**: simple-construction-bolt
+```
+
+**Frontend unit characteristics**:
+
+- Named using `naming_pattern` from catalog (default: `{intent}-ui`)
+- Depends on ALL backend service units
+- Uses `simple-construction-bolt` (not DDD)
+- Assigned all user-facing requirements (UI, UX, interactions)
+
+**Include in unit-brief.md**:
+
+```yaml
+---
+unit: {intent}-ui
+unit_type: frontend
+default_bolt_type: simple-construction-bolt
+---
+```
+
+---
+
+### 6. Propose Unit Structure
+
+Present proposed decomposition with their assigned requirements:
+
+```markdown
+## Proposed Units
+
+### Unit 1: {unit-name}
+- **Purpose**: {what it does}
+- **Responsibility**: {single responsibility}
+- **Assigned Requirements**: FR-1, FR-2
+- **Dependencies**: {other units it depends on}
+- **Interface**: {how other units interact with it}
+
+### Unit 2: {unit-name}
+- **Assigned Requirements**: FR-3, FR-4
+...
+
+### Unit N: {intent}-ui (if frontend enabled)
+- **Purpose**: Frontend application
+- **Unit Type**: frontend
+- **Dependencies**: All backend units
+```
+
+### 7. Document Units
+
+1. **Read Path**: Check `schema.units` from `.specsmd/aidlc/memory-bank.yaml`
+   *(Default: `memory-bank/intents/{intent-name}/units.md`)*
+
+2. **Create Central List**:
+   Update `units.md` with all units for this intent
+
+3. **Create Unit Directories**:
+   For each unit: `{schema.units}/{unit-name}/`
+
+4. **Create Unit Brief** (CRITICAL):
+   For each unit, create `unit-brief.md` using `.specsmd/aidlc/templates/inception/unit-brief-template.md`
+
+   This brief is the **input for Construction Agent**. Include:
+   - Purpose and scope
+   - Key entities and operations
+   - Dependencies on other units
+   - Technical constraints
+   - Success criteria
+
+   Example frontmatter:
+
+   ```yaml
+   ---
+   unit: auth-service
+   intent: 001-user-authentication
+   phase: inception
+   status: draft
+   ---
+   ```
+
+   Note: Story naming uses the story title (e.g., `001-user-signup.md`). No prefix field needed.
+
+   **For frontend units**, also include:
+   ```yaml
+   unit_type: frontend
+   default_bolt_type: simple-construction-bolt
+   ```
+
+### 8. Validate Independence
+
+For each unit, verify:
+
+- [ ] Can be developed by a separate team
+- [ ] Has clear API/interface
+- [ ] Failure doesn't cascade to other units
+- [ ] Can be deployed without deploying others
+
+---
+
+## Output
+
+```markdown
+## Unit Decomposition: {intent-name}
+
+### Units Created
+
+- [ ] **{unit-1}**: {purpose} - Dependencies: None - Stories: ~{n}
+- [ ] **{unit-2}**: {purpose} - Dependencies: `{unit-1}` - Stories: ~{n}
+
+### Dependency Graph
+
+    {unit-1} ──► {unit-2} ──► {unit-3}
+                    │
+                    ▼
+                {unit-4}
+
+### Artifacts Created
+
+✅ `{intent-path}/units.md`
+✅ `{intent-path}/units/{unit-1}/unit-brief.md`
+✅ `{intent-path}/units/{unit-2}/unit-brief.md`
+
+```
+
+**No menu** - Skill complete, return to agent.
+
+---
+
+## Test Contract
+
+```yaml
+input: Intent requirements, system context, project.yaml, catalog.yaml
+output: units.md, unit-brief.md for each unit (including frontend unit if enabled)
+checkpoints: 0 (part of Checkpoint 3 batch)
+```

package/flows/aidlc/skills/master/analyze-context.md

@@ -0,0 +1,132 @@
+# Skill: Analyze Context
+
+---
+
+## Role
+
+Diagnostic skill to determine current project state by inspecting memory bank artifacts.
+
+**NO Checkpoint** - Analysis is informational, not a decision point.
+
+---
+
+## Goal
+
+Deduce the current project state and recommend the logical next step by inspecting the memory bank artifacts.
+
+---
+
+## Input
+
+- **Required**: `.specsmd/aidlc/memory-bank.yaml` - artifact schema
+- **Required**: Project artifacts at paths defined in schema
+
+---
+
+## Process
+
+### 1. Load Schema
+
+Read `.specsmd/aidlc/memory-bank.yaml` to understand artifact paths:
+
+- `schema.intents` - where intents are stored
+- `schema.units` - where units are stored
+- `schema.bolts` - where bolts are stored
+
+### 2. Inspect Intents
+
+List contents of `schema.intents` directory:
+
+- Are there any intent directories?
+- For each intent, what artifacts exist?
+
+### 3. Inspect Units (if intents exist)
+
+For recent/active intents:
+
+- Does `units.md` exist?
+- Does `units/` directory have content?
+- For each unit, are there stories in `stories/`?
+
+### 4. Inspect Bolts (if units exist)
+
+Check `schema.bolts` directory:
+
+- Are there bolt instance files?
+- What is their status? (planned, in-progress, completed)
+- What stage are in-progress bolts at?
+
+### 5. Determine Phase
+
+Based on evidence found:
+
+- **No intents** → Pre-Inception → Create first intent
+- **Intent exists, no requirements.md** → Early Inception → Gather requirements
+- **Requirements exist, no units.md** → Mid Inception → Decompose into units
+- **Units exist, no stories** → Late Inception → Create stories
+- **Stories exist, no bolts** → Inception Complete → Plan bolts
+- **Bolts planned** → Ready for Construction → Start first bolt
+- **Bolts in-progress** → Construction → Continue current bolt
+- **All bolts completed** → Ready for Operations → Deploy unit
+- **Deployed to production** → Operations → Monitor and maintain
+
+---
+
+## Output
+
+Provide a structured analysis:
+
+```markdown
+## Project State Analysis
+
+### Summary
+- **Phase**: {current phase}
+- **Active Intent**: {name or "None"}
+- **Active Unit**: {name or "None"}
+- **Active Bolt**: {id or "None"}
+
+### Evidence
+- Intents found: {count} ({list names})
+- Units found: {count} for {intent}
+- Stories found: {count} for {unit}
+- Bolts found: {count} ({status breakdown})
+
+### Current State Details
+{Specific details about what exists and what's missing}
+
+### Actions
+
+1 - **proceed**: Execute suggested action
+2 - **explain**: Learn more about current phase
+3 - **different**: Work on something else
+
+### Suggested Next Step
+→ **proceed** - {Specific command to run}
+
+**Type a number or press Enter for suggested action.**
+```
+
+---
+
+## Human Validation Point
+
+> "Based on my analysis, you're in the {phase} phase. Does this match your understanding? If not, tell me what you're trying to accomplish."
+
+---
+
+## Transition
+
+After analysis, either:
+
+- → **Route Request** (`.specsmd/skills/master/route-request.md`) - to direct user to specialist agent
+- → **Answer Question** (`.specsmd/skills/master/answer-question.md`) - if user has questions about state
+
+---
+
+## Test Contract
+
+```yaml
+input: Memory bank schema and artifacts
+output: Project state analysis with phase, evidence, and suggested next step
+checkpoints: 0 (informational only)
+```