specsmd 0.0.1

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

@@ -0,0 +1,171 @@
+# Skill: Define System Context
+
+---
+
+## Progress Display
+
+Show at start of this skill:
+
+```text
+### Inception Progress
+- [x] Intent created
+- [x] Requirements gathered
+- [ ] Generating artifacts...  ← current
+    - [ ] System Context  ← this skill
+    - [ ] Units
+    - [ ] 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
+
+Identify system boundaries, actors, and external dependencies to establish the "world" the system lives in.
+
+---
+
+## Input
+
+- **Required**: Intent name
+- **Required**: `requirements.md` for the intent
+- **Required**: `.specsmd/aidlc/memory-bank.yaml` - artifact schema
+
+---
+
+## Process
+
+### 1. Identify Actors
+
+Ask questions to discover all system users:
+
+- **Human Users**: "Who uses this directly?" (Admin, Customer, Support)
+- **System Users**: "What systems call this?" (Scheduler, Event Bus)
+- **External Systems**: "What third-party services interact?" (Stripe, Auth0)
+
+### 2. Map External Systems
+
+For each external dependency, document:
+
+- **System name**: What is it?
+- **Direction**: Inbound/Outbound/Both
+- **Data Exchanged**: What data crosses?
+- **Protocol**: REST/GraphQL/Event
+
+### 3. Define Data Flows
+
+Document what data crosses the boundary:
+
+**Inbound**:
+
+- What data enters the system?
+- What format? (JSON, XML, Binary)
+- What validation is needed?
+
+**Outbound**:
+
+- What data leaves the system?
+- What consumers expect it?
+- What guarantees are needed? (Delivery, ordering)
+
+### 4. Create Context Diagram
+
+Generate a C4 Context diagram (Mermaid):
+
+```markdown
+## System Context Diagram
+
+​```mermaid
+C4Context
+    title System Context - {intent-name}
+
+    Person(user, "User", "Primary user of the system")
+    System(sys, "{System Name}", "The system being built")
+    System_Ext(ext1, "External System", "Third-party service")
+
+    Rel(user, sys, "Uses")
+    Rel(sys, ext1, "Integrates with")
+​```
+```
+
+### 5. Document Context
+
+1. **Read Path**: Check `schema.system_context` from `.specsmd/aidlc/memory-bank.yaml`
+   *(Default: `memory-bank/intents/{intent-name}/system-context.md`)*
+
+2. **Use Template**: `.specsmd/aidlc/templates/inception/system-context-template.md`
+
+3. **Structure**:
+
+   ```markdown
+   ## Actors
+
+   - **{Actor}** ({Type}): {Description}
+
+   ## External Systems
+
+   - **{System}**: {Purpose} - {Integration Type}
+
+   ## Data Flows
+   ### Inbound
+   ### Outbound
+
+   ## Context Diagram
+   {Mermaid diagram}
+   ```
+
+### 6. Validate Completeness
+
+Ask:
+
+- "Did I miss any third-party integrations?"
+- "Are there legacy systems this needs to work with?"
+- "Any planned future integrations to consider?"
+
+---
+
+## Output
+
+```markdown
+## System Context: {intent-name}
+
+### Actors Identified
+
+- **Customer** (Human): Web/Mobile UI
+- **Admin** (Human): Admin Dashboard
+- **Payment Gateway** (System): REST API
+
+### External Dependencies
+
+- **Stripe**: Payments - Risk: High
+- **SendGrid**: Email - Risk: Medium
+
+### Data Flow Summary
+- **Inbound**: User requests, webhook events
+- **Outbound**: Transaction records, notifications
+
+### Artifact Created
+✅ `{intent-path}/system-context.md`
+```
+
+**No menu** - Skill complete, return to agent.
+
+---
+
+## Test Contract
+
+```yaml
+input: Intent requirements
+output: system-context.md with actors, systems, data flows
+checkpoints: 0 (part of Checkpoint 3 batch)
+```

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

@@ -0,0 +1,211 @@
+# Skill: Create Intent
+
+---
+
+## Progress Display
+
+Show at start of this skill:
+
+```text
+### Inception Progress
+- [ ] Intent created  ← this skill
+- [ ] Requirements gathered (Checkpoint 1, Checkpoint 2)
+- [ ] Artifacts reviewed (Checkpoint 3)
+- [ ] Ready for Construction (Checkpoint 4)
+```
+
+---
+
+## Checkpoints in This Skill
+
+**NO Checkpoint** - This skill is a prerequisite to the checkpoint workflow.
+
+Intent creation is a simple initialization step. The workflow checkpoints begin in the `requirements` skill.
+
+---
+
+## Goal
+
+Guide the user to define a high-level feature (Intent) and initialize its structure in the Memory Bank.
+
+---
+
+## Input
+
+- **Required**: User's feature idea or request
+- **Required**: `.specsmd/aidlc/memory-bank.yaml` - artifact schema
+- **Optional**: `memory-bank/project.yaml` - project type for context-aware suggestions
+
+---
+
+## Process
+
+### 0. Load Project Context
+
+**Before asking questions**, read project configuration:
+
+1. Read `memory-bank/project.yaml` to get `project_type`
+2. List `memory-bank/intents/` directory to see existing intents
+
+---
+
+#### Case A: FIRST Intent (no intents exist)
+
+**Be creative** and suggest 3-4 relevant intent examples based on project type.
+
+Consider the project type and generate suggestions that:
+
+- Are common starting points for that type of application
+- Provide foundational functionality to build upon
+- Are appropriately scoped for an intent (not too large, not too small)
+
+**Show to user:**
+
+```markdown
+## Create Your First Intent
+
+**Project Type**: {project_type}
+
+Here are some ideas for your first feature:
+- "{creative suggestion 1 relevant to project type}"
+- "{creative suggestion 2 relevant to project type}"
+- "{creative suggestion 3 relevant to project type}"
+
+Or tell me what you'd like to build.
+```
+
+If `project.yaml` doesn't exist, ask what they want to build without suggestions.
+
+---
+
+#### Case B: Subsequent Intents (intents already exist)
+
+Analyze existing intents to understand project context and suggest related features:
+
+1. **Read existing intent names** from `memory-bank/intents/` folder names
+2. **Read requirements.md** from each existing intent to understand scope
+3. **Infer project domain** (e.g., e-commerce, SaaS, developer tool, social platform)
+4. **Suggest complementary features** that would naturally extend the existing functionality
+
+**Example Analysis:**
+
+If existing intents are:
+
+- `001-user-authentication`
+- `002-product-catalog`
+
+Then suggest:
+
+- "Shopping cart and checkout" (natural next step for e-commerce)
+- "Order management and history" (complements product catalog)
+- "User reviews and ratings" (enhances product catalog)
+- "Wishlist functionality" (user engagement feature)
+
+**Show to user:**
+
+```markdown
+## Create New Intent
+
+Based on your existing intents:
+- `001-user-authentication` - {brief description from requirements}
+- `002-product-catalog` - {brief description from requirements}
+
+Your project appears to be a **{inferred domain, e.g., "e-commerce platform"}**.
+
+Here are some features that might complement your existing work:
+- "{suggestion 1}"
+- "{suggestion 2}"
+- "{suggestion 3}"
+
+Or tell me what you'd like to build next.
+```
+
+### 1. Elicit Intent Details
+
+Ask clarifying questions to understand the intent:
+
+- **"What is the name for this intent?"** → Get kebab-case identifier (e.g., `user-authentication`)
+- **"What problem does this solve?"** → Understand business value
+- **"Who benefits from this?"** → Identify stakeholders
+- **"What's in scope vs out of scope?"** → Set boundaries early
+
+**IMPORTANT**: Intent names MUST have a 3-digit numeric prefix to indicate implementation order:
+
+- Format: `{NNN}-{intent-name}` (e.g., `001-user-authentication`, `002-payment-processing`)
+- Check existing intents to determine next available number
+- First intent is `001-*`, second is `002-*`, etc.
+
+Note: All naming (units, stories) is derived from folder names. No prefix fields needed in frontmatter.
+
+### 2. Classify Intent Type
+
+Determine the intent category:
+
+- **New Feature**: Brand new capability (e.g., "Add payment processing")
+- **Enhancement**: Improve existing feature (e.g., "Add MFA to auth")
+- **Bug Fix**: Correct defective behavior (e.g., "Fix checkout race condition")
+- **Refactor**: Technical improvement (e.g., "Migrate to new API version")
+- **Infrastructure**: Platform/DevOps change (e.g., "Add caching layer")
+
+### 3. Initialize Artifacts
+
+Once confirmed, perform these file operations:
+
+1. **Read Schema**: Check `.specsmd/aidlc/memory-bank.yaml` for `intents` path
+   *(Default: `memory-bank/intents/{intent-name}/`)*
+
+2. **Create Directory**:
+
+   ```text
+   {schema.intents}/{intent-name}/
+   ```
+
+3. **Create `requirements.md`**:
+   - Use template: `.specsmd/aidlc/templates/inception/requirements-template.md`
+   - Populate Goal and Scope with user input
+   - Set status to `draft`
+
+4. **Create `inception-log.md`**:
+   - Use template: `.specsmd/aidlc/templates/inception/inception-log-template.md`
+   - Initialize with intent metadata and empty sections
+   - Track progress, decisions, and scope changes
+
+### 5. Confirm Creation
+
+Show confirmation with **exactly ONE action list** - no workflow overview, no extra lists:
+
+```markdown
+## Intent Created: `{intent-name}`
+
+**Goal**: {user's stated goal}
+**Type**: {intent type}
+**Location**: `{intent-path}/`
+
+Files created:
+- `requirements.md` (draft)
+- `inception-log.md` (progress tracker)
+
+1 - **requirements**: [Recommended] Gather detailed requirements
+2 - **context**: Define system context and boundaries
+3 - **menu**: Return to inception menu
+
+**Type a number to continue.**
+```
+
+---
+
+## Transition
+
+After intent created:
+
+- → **requirements** - begin checkpoint workflow at Checkpoint 1
+
+---
+
+## Test Contract
+
+```yaml
+input: User's feature idea
+output: Intent directory with requirements.md and inception-log.md
+checkpoints: 0 (prerequisite to workflow)
+```

package/flows/aidlc/skills/inception/intent-list.md

@@ -0,0 +1,124 @@
+# Skill: List Intents
+
+---
+
+## Role
+
+Utility skill to view all intents and their status.
+
+**NO Checkpoint** - This is an informational/navigation skill.
+
+---
+
+## Goal
+
+Display all intents in the memory bank with their current status and suggest next actions.
+
+---
+
+## Input
+
+- **Required**: `.specsmd/aidlc/memory-bank.yaml` - artifact schema
+- **Required**: Intents at path defined by `schema.intents`
+
+---
+
+## Process
+
+### 1. Load Schema
+
+Read `.specsmd/aidlc/memory-bank.yaml` to get the `intents` path.
+
+### 2. Scan Intents
+
+For each directory in `schema.intents`:
+
+1. Read `requirements.md` frontmatter for metadata
+2. Check for existence of key artifacts:
+   - `requirements.md` - requirements defined?
+   - `system-context.md` - context mapped?
+   - `units.md` - decomposed?
+   - `units/*/stories/` - stories created?
+3. Check path from `schema.bolts` for planned bolts
+
+### 3. Determine Status
+
+Status progression based on artifacts present:
+
+- Only `requirements.md` (draft) → **Draft** (Early Inception)
+- `requirements.md` complete → **Requirements Done** (Inception)
+- `system-context.md` exists → **Context Mapped** (Inception)
+- `units.md` exists → **Decomposed** (Inception)
+- Stories exist → **Stories Done** (Inception)
+- Bolts planned → **Ready for Construction** (Inception Complete)
+- Bolts in-progress → **Building** (Construction)
+- All bolts complete → **Ready for Deployment** (Construction Complete)
+- Deployed → **Live** (Operations)
+
+### 4. Display Results
+
+```markdown
+## Intents Overview
+
+- ⏳ **{intent-1}**: {status} - {phase} - {x/y} progress
+- [ ] **{intent-2}**: {status} - {phase} - {x/y} progress
+- ✅ **{intent-3}**: Completed - Operations
+
+### Summary
+- **Total**: {count} intents
+- **By Phase**: Inception ({n}), Construction ({n}), Operations ({n})
+- **Needs Attention**: {list of blocked or stale intents}
+```
+
+---
+
+## Output
+
+```markdown
+## Project Intents
+
+### Active Intents
+
+- ⏳ **user-authentication**: Construction - Bolt 2/3 in progress (2024-12-05)
+- [ ] **payment-integration**: Inception - Stories needed (2024-12-04)
+
+### Completed Intents
+
+- ✅ **core-api**: Completed 2024-11-28 - Production
+
+### Summary
+- **Total**: 3 intents
+- **Active**: 2
+- **Completed**: 1
+
+### Actions
+
+1 - **payment-integration**: Create stories to complete inception
+2 - **user-authentication**: Continue bolt execution
+3 - **create-intent**: Create a new intent
+
+### Suggested Next Step
+→ **payment-integration** - Complete inception by creating stories
+
+**Type a number or press Enter for suggested action.**
+```
+
+---
+
+## Transition
+
+After viewing list:
+
+- → **intent-create** - if user wants new intent
+- → **requirements** - if user picks intent in early inception
+- → **Construction Agent** - if intent is ready for construction
+
+---
+
+## Test Contract
+
+```yaml
+input: Memory bank path
+output: List of intents with status, suggested actions
+checkpoints: 0 (informational only)
+```

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

@@ -0,0 +1,207 @@
+# Skill: Inception Navigator
+
+---
+
+## Role
+
+Entry point for Inception Agent. Routes to appropriate skill based on state.
+
+**NO Checkpoint** - Navigator is a routing skill, not a decision point.
+
+---
+
+## Goal
+
+Present the Inception Agent's skills and guide the user to the appropriate next action.
+
+---
+
+## Input
+
+- **Optional**: Current intent (from `--intent` parameter)
+- **Required**: `.specsmd/aidlc/memory-bank.yaml` - artifact schema
+
+---
+
+## Process
+
+### 1. Determine Context
+
+If intent is specified, load its current state:
+
+- Check which artifacts exist
+- Identify current progress stage
+- Determine logical next step
+
+### 2. Present Menu
+
+Build menu dynamically using the Output sections below based on current state.
+
+### 3. Context-Aware Suggestions
+
+Scan artifacts **in order** - first missing item is the suggested next step:
+
+| Check (in order)              | If missing → Suggest     |
+|-------------------------------|--------------------------|
+| No intent folder exists       | Create Intent            |
+| `requirements.md`             | Gather Requirements      |
+| `system-context.md`           | Define Context           |
+| `units.md`                    | Decompose Units          |
+| `story-index.md`              | Create Stories           |
+| `bolt-plan.md`                | Plan Bolts               |
+| All complete                  | Review & Complete        |
+
+**CRITICAL**: The suggested step becomes **Option 1** in the menu.
+
+### 4. Handle Selection
+
+When user selects an option:
+
+1. Acknowledge the selection
+2. Load the corresponding skill file
+3. Execute with current intent context
+
+---
+
+## Output (No Active Intent)
+
+```markdown
+## Inception Agent
+
+### No Active Intent
+
+### Get Started
+
+1 - **Create Intent** ← Start here
+
+### Other Actions
+
+2 - List Intents
+3 - Return to Main Menu
+
+---
+
+**Type 1 to continue, or a number for other actions.**
+```
+
+---
+
+## Output (With Active Intent)
+
+**Option 1 is determined by Context-Aware Suggestions table above.**
+
+```markdown
+## Inception Agent
+
+### Active Intent: `{intent-name}`
+**Goal**: {intent goal}
+
+### Progress
+- {✅ or [ ]} Requirements gathered {← current if next step}
+- {✅ or [ ]} System context defined {← current if next step}
+- {✅ or [ ]} Units decomposed {← current if next step}
+- {✅ or [ ]} Stories created {← current if next step}
+- {✅ or [ ]} Bolts planned {← current if next step}
+- [ ] Review complete {← current if all above done}
+
+---
+
+### Continue This Intent
+
+1 - **{Next step from table}** ← Next step
+{N} - Revisit {completed steps...}
+
+### Other Actions
+
+{N} - Create New Intent
+{N} - List All Intents
+{N} - Return to Main Menu
+
+---
+
+**Type 1 to continue, or a number for other actions.**
+```
+
+**Example: Requirements done, context missing**
+
+```markdown
+## Inception Agent
+
+### Active Intent: `user-auth`
+**Goal**: Implement user authentication with OAuth
+
+### Progress
+- ✅ Requirements gathered
+- [ ] System context defined ← current
+- [ ] Units decomposed
+- [ ] Stories created
+- [ ] Bolts planned
+- [ ] Review complete
+
+---
+
+### Continue This Intent
+
+1 - **Define Context** ← Next step
+2 - Revisit Requirements
+
+### Other Actions
+
+3 - Create New Intent
+4 - List All Intents
+5 - Return to Main Menu
+
+---
+
+**Type 1 to continue, or a number for other actions.**
+```
+
+---
+
+## Output (Inception Complete)
+
+```markdown
+## Inception Agent
+
+### Intent Complete: `{intent-name}`
+
+All inception artifacts have been created:
+
+- ✅ Requirements gathered
+- ✅ System context defined
+- ✅ Units decomposed
+- ✅ Stories created
+- ✅ Bolts planned
+- ✅ Review complete
+
+### Summary
+- Units defined: {n}
+- Stories created: {n}
+- Bolts planned: {n}
+- Ready for Construction
+
+### Next Step
+→ Proceed to Construction: `/specsmd-construction-agent --intent="{intent-name}"`
+
+Or create another intent.
+```
+
+---
+
+## Transition
+
+After user selection:
+
+- → Load selected skill
+- → Skill contains the Checkpoint markers
+- → Execute skill process
+
+---
+
+## Test Contract
+
+```yaml
+input: Intent state (optional)
+output: Menu with dynamic Option 1 based on state
+checkpoints: 0 (routing only)
+```