specsmd 0.0.0-dev

package/flows/aidlc/templates/inception/unit-brief-template.md

@@ -0,0 +1,177 @@
+# Unit Brief Template
+
+Use this template when creating unit briefs during decomposition. This is the **critical input for Construction**.
+
+---
+
+## Frontmatter
+
+```yaml
+---
+unit: {UUU}-{unit-name}
+intent: {NNN}-{intent-name}
+phase: inception
+status: draft|ready
+created: {YYYY-MM-DDTHH:MM:SSZ}
+updated: {YYYY-MM-DDTHH:MM:SSZ}
+---
+```
+
+**Note**: The `unit` field uses the full folder name including the 3-digit prefix (e.g., `001-auth-service`). This matches the folder structure and enables direct path construction in scripts. Story naming uses the story title (e.g., `001-user-signup.md`).
+
+---
+
+## Content
+
+```markdown
+# Unit Brief: {Unit Name}
+
+## Purpose
+
+{Clear, concise statement of what this unit does and why it exists}
+
+## Scope
+
+### In Scope
+- {What this unit IS responsible for}
+- {What this unit IS responsible for}
+
+### Out of Scope
+- {What this unit is NOT responsible for}
+- {What other units handle}
+
+---
+
+## Assigned Requirements
+
+**These FRs from the intent are assigned to this unit. Stories will be created from these.**
+
+| FR | Requirement | Priority |
+|----|-------------|----------|
+| FR-{n} | {description from intent requirements.md} | Must/Should/Could |
+
+---
+
+## Domain Concepts
+
+### Key Entities
+| Entity | Description | Attributes |
+|--------|-------------|------------|
+| {Entity 1} | {What it represents} | {Key properties} |
+| {Entity 2} | {What it represents} | {Key properties} |
+
+### Key Operations
+| Operation | Description | Inputs | Outputs |
+|-----------|-------------|--------|---------|
+| {Operation 1} | {What it does} | {Input data} | {Output data} |
+| {Operation 2} | {What it does} | {Input data} | {Output data} |
+
+---
+
+## Story Summary
+
+| Metric | Count |
+|--------|-------|
+| Total Stories | {n} |
+| Must Have | {n} |
+| Should Have | {n} |
+| Could Have | {n} |
+
+### Stories
+
+| Story ID | Title | Priority | Status |
+|----------|-------|----------|--------|
+| {story-1} | {Title} | Must | Planned |
+| {story-2} | {Title} | Should | Planned |
+
+---
+
+## Dependencies
+
+### Depends On
+| Unit | Reason |
+|------|--------|
+| {unit-name} | {Why this dependency exists} |
+
+### Depended By
+| Unit | Reason |
+|------|--------|
+| {unit-name} | {Why they depend on this} |
+
+### External Dependencies
+| System | Purpose | Risk |
+|--------|---------|------|
+| {External system} | {Why needed} | {Risk level} |
+
+---
+
+## Technical Context
+
+### Suggested Technology
+{Recommendations based on tech stack standards}
+
+### Integration Points
+| Integration | Type | Protocol |
+|-------------|------|----------|
+| {System/Unit} | API/Event/DB | REST/GraphQL/Kafka |
+
+### Data Storage
+| Data | Type | Volume | Retention |
+|------|------|--------|-----------|
+| {Data type} | SQL/NoSQL/Cache | {Volume} | {Retention} |
+
+---
+
+## Constraints
+
+- {Technical constraint specific to this unit}
+- {Business constraint specific to this unit}
+
+---
+
+## Success Criteria
+
+### Functional
+- [ ] {Criterion 1: What must work}
+- [ ] {Criterion 2: What must work}
+
+### Non-Functional
+- [ ] {Performance target}
+- [ ] {Security requirement}
+
+### Quality
+- [ ] Code coverage > 80%
+- [ ] All acceptance criteria met
+- [ ] Code reviewed and approved
+
+---
+
+## Bolt Suggestions
+
+Based on stories and complexity:
+
+| Bolt | Type | Stories | Objective |
+|------|------|---------|-----------|
+| bolt-{unit}-1 | DDD | S1, S2 | Core entities |
+| bolt-{unit}-2 | DDD | S3, S4 | API layer |
+
+---
+
+## Notes
+
+{Any additional context, risks, or considerations for Construction}
+```
+
+---
+
+## Quality Checklist
+
+Before marking unit brief as ready:
+
+- [ ] Purpose is clear and specific
+- [ ] Scope boundaries are defined
+- [ ] Key entities identified
+- [ ] Stories assigned to this unit
+- [ ] Dependencies mapped
+- [ ] Success criteria are measurable
+- [ ] Bolt suggestions provided

package/flows/aidlc/templates/inception/units-template.md

@@ -0,0 +1,52 @@
+---
+intent: {NNN}-{intent-name}
+phase: inception
+status: units-decomposed
+updated: {YYYY-MM-DDTHH:MM:SSZ}
+---
+
+# {Intent Name} - Unit Decomposition
+
+## Units Overview
+
+This intent decomposes into {N} units of work:
+
+### Unit 1: {unit-name}
+
+**Description**: {What this unit does}
+
+**Stories**:
+
+- Story-1: {Title}
+- Story-3: {Title}
+
+**Deliverables**:
+
+- {Specific artifacts this unit produces}
+
+**Dependencies**:
+
+- Depends on: {Other units}
+- Depended by: {Units that need this}
+
+**Estimated Complexity**: S/M/L/XL
+
+### Unit 2: {unit-name}
+
+...
+
+## Unit Dependency Graph
+
+```text
+[Unit A] ──> [Unit B] ──> [Unit D]
+   │            │
+   └────> [Unit C] ──┘
+```
+
+## Execution Order
+
+Based on dependencies:
+
+1. Day 1-2: Unit A (foundation)
+2. Day 2-4: Unit B, Unit C (parallel)
+3. Day 5-6: Unit D (integration)

package/flows/aidlc/templates/standards/catalog.yaml

@@ -0,0 +1,345 @@
+# Standards Catalog
+# Defines what standards exist, their decisions, and relationships.
+# Each standard has a facilitation guide in templates/standards/
+
+standards:
+  tech-stack:
+    description: Core technology choices for the project
+    facilitation: templates/standards/tech-stack.guide.md
+    output_path: standards/tech-stack.md
+    importance: critical
+    sections:
+      - header: Overview
+        type: static
+        content: "Core technology decisions for this project."
+      - type: from_decisions
+    decisions:
+      - id: languages
+        display_name: Languages
+        category: core
+        importance: critical
+        depends_on: []
+
+      - id: framework
+        display_name: Framework
+        category: core
+        importance: critical
+        depends_on: [languages]
+
+      - id: authentication
+        display_name: Authentication
+        category: security
+        importance: high
+        optional: true
+        depends_on: [framework]
+
+      - id: infrastructure
+        display_name: Infrastructure & Deployment
+        category: deployment
+        importance: high
+        depends_on: [framework]
+
+      - id: package_manager
+        display_name: Package Manager
+        category: tooling
+        importance: medium
+        depends_on: [languages]
+
+  data-stack:
+    description: Database and data persistence choices
+    facilitation: templates/standards/data-stack.guide.md
+    output_path: standards/data-stack.md
+    importance: high
+    depends_on_standards: [tech-stack]
+    sections:
+      - header: Overview
+        type: static
+        content: "Database and data persistence decisions for this project."
+      - type: from_decisions
+    decisions:
+      - id: database
+        display_name: Database
+        category: data
+        importance: high
+        depends_on: []
+
+      - id: orm
+        display_name: ORM / Database Client
+        category: data
+        importance: medium
+        depends_on: [database]
+
+  coding-standards:
+    description: Code style, patterns, and quality standards
+    facilitation: templates/standards/coding-standards.guide.md
+    output_path: standards/coding-standards.md
+    importance: critical
+    depends_on_standards: [tech-stack]
+    sections:
+      - header: Overview
+        type: static
+        content: "Code style and quality standards for this project."
+      - type: from_decisions
+    decisions:
+      - id: formatting
+        display_name: Code Formatting
+        category: style
+        importance: high
+        depends_on: []
+
+      - id: linting
+        display_name: Linting Rules
+        category: quality
+        importance: high
+        depends_on: []
+
+      - id: naming_conventions
+        display_name: Naming Conventions
+        category: style
+        importance: high
+        depends_on: []
+
+      - id: file_organization
+        display_name: File & Folder Organization
+        category: structure
+        importance: high
+        depends_on: []
+
+      - id: testing_strategy
+        display_name: Testing Strategy
+        category: quality
+        importance: critical
+        depends_on: []
+
+      - id: error_handling
+        display_name: Error Handling Patterns
+        category: patterns
+        importance: high
+        depends_on: []
+
+      - id: logging
+        display_name: Logging Standards
+        category: observability
+        importance: medium
+        depends_on: []
+
+  system-architecture:
+    description: High-level system design and architectural patterns
+    facilitation: templates/standards/system-architecture.guide.md
+    output_path: standards/system-architecture.md
+    importance: high
+    optional: true
+    depends_on_standards: [tech-stack]
+    sections:
+      - header: Overview
+        type: static
+        content: "High-level architectural decisions and patterns."
+      - type: from_decisions
+    decisions:
+      - id: architecture_style
+        display_name: Architecture Style
+        category: structure
+        importance: critical
+        depends_on: []
+
+      - id: api_design
+        display_name: API Design
+        category: communication
+        importance: high
+        optional: true
+        depends_on: []
+
+      - id: state_management
+        display_name: State Management
+        category: data
+        importance: high
+        optional: true
+        depends_on: []
+
+      - id: caching_strategy
+        display_name: Caching Strategy
+        category: performance
+        importance: medium
+        optional: true
+        depends_on: []
+
+      - id: security_patterns
+        display_name: Security Patterns
+        category: security
+        importance: high
+        depends_on: []
+
+  ux-guide:
+    description: UI/UX patterns and design system choices
+    facilitation: templates/standards/ux-guide.guide.md
+    output_path: standards/ux-guide.md
+    importance: medium
+    optional: true
+    depends_on_standards: [tech-stack]
+    sections:
+      - header: Overview
+        type: static
+        content: "UI/UX standards and design system choices."
+      - type: from_decisions
+    decisions:
+      - id: design_system
+        display_name: Design System / Component Library
+        category: ui
+        importance: high
+        depends_on: []
+
+      - id: styling_approach
+        display_name: Styling Approach
+        category: ui
+        importance: high
+        depends_on: []
+
+      - id: accessibility
+        display_name: Accessibility Standards
+        category: compliance
+        importance: high
+        depends_on: []
+
+      - id: responsive_strategy
+        display_name: Responsive Design Strategy
+        category: ui
+        importance: medium
+        depends_on: []
+
+  api-conventions:
+    description: API design conventions and standards
+    facilitation: templates/standards/api-conventions.guide.md
+    output_path: standards/api-conventions.md
+    importance: medium
+    optional: true
+    depends_on_standards: [tech-stack]
+    sections:
+      - header: Overview
+        type: static
+        content: "API design conventions and response formats."
+      - type: from_decisions
+    decisions:
+      - id: api_style
+        display_name: API Style
+        category: design
+        importance: critical
+        depends_on: []
+
+      - id: versioning
+        display_name: API Versioning
+        category: design
+        importance: medium
+        depends_on: []
+
+      - id: response_format
+        display_name: Response Format
+        category: format
+        importance: high
+        depends_on: []
+
+      - id: error_format
+        display_name: Error Response Format
+        category: format
+        importance: high
+        depends_on: []
+
+      - id: pagination
+        display_name: Pagination Strategy
+        category: design
+        importance: medium
+        optional: true
+        depends_on: []
+
+# Project type presets - determines which standards to create and how to decompose units
+project_types:
+  full-stack-web:
+    description: Full-stack web application
+    required_standards:
+      - tech-stack
+      - data-stack
+      - coding-standards
+    recommended_standards:
+      - system-architecture
+      - ux-guide
+      - api-conventions
+    # Unit decomposition structure
+    unit_structure:
+      backend:
+        enabled: true
+        decomposition: domain-driven
+        default_bolt_type: ddd-construction-bolt
+        description: Backend services using DDD decomposition
+      frontend:
+        enabled: true
+        decomposition: feature-based
+        default_bolt_type: simple-construction-bolt
+        naming_pattern: "{intent}-ui"
+        description: Frontend application (pages, components, state)
+
+  backend-api:
+    description: Backend API service
+    required_standards:
+      - tech-stack
+      - data-stack
+      - coding-standards
+    recommended_standards:
+      - system-architecture
+      - api-conventions
+    unit_structure:
+      backend:
+        enabled: true
+        decomposition: domain-driven
+        default_bolt_type: ddd-construction-bolt
+        description: Backend services using DDD decomposition
+      frontend:
+        enabled: false
+
+  frontend-app:
+    description: Frontend application (SPA/SSR)
+    required_standards:
+      - tech-stack
+      - coding-standards
+    recommended_standards:
+      - ux-guide
+    unit_structure:
+      backend:
+        enabled: false
+      frontend:
+        enabled: true
+        decomposition: feature-based
+        default_bolt_type: simple-construction-bolt
+        description: Frontend application (pages, components, state)
+
+  cli-tool:
+    description: Command-line tool
+    required_standards:
+      - tech-stack
+      - coding-standards
+    recommended_standards: []
+    unit_structure:
+      backend:
+        enabled: false
+      frontend:
+        enabled: false
+      cli:
+        enabled: true
+        decomposition: command-based
+        default_bolt_type: simple-construction-bolt
+        description: CLI commands and handlers
+
+  library:
+    description: Reusable library/package
+    required_standards:
+      - tech-stack
+      - coding-standards
+    recommended_standards:
+      - data-stack
+      - api-conventions
+    unit_structure:
+      backend:
+        enabled: true
+        decomposition: module-based
+        default_bolt_type: simple-construction-bolt
+        description: Library modules and public API
+      frontend:
+        enabled: false