aios-core 2.1.6 → 2.2.1

package/.aios-core/product/checklists/story-draft-checklist.md

@@ -1,216 +1,216 @@
-# Story Draft Checklist
-
-The Scrum Master should use this checklist to validate that each story contains sufficient context for a developer agent to implement it successfully, while assuming the dev agent has reasonable capabilities to figure things out.
-
-[[LLM: INITIALIZATION INSTRUCTIONS - STORY DRAFT VALIDATION
-
-Before proceeding with this checklist, ensure you have access to:
-
-1. The story document being validated (usually in docs/stories/ or provided directly)
-2. The parent epic context
-3. Any referenced architecture or design documents
-4. Previous related stories if this builds on prior work
-
-IMPORTANT: This checklist validates individual stories BEFORE implementation begins.
-
-VALIDATION PRINCIPLES:
-
-1. Clarity - A developer should understand WHAT to build
-2. Context - WHY this is being built and how it fits
-3. Guidance - Key technical decisions and patterns to follow
-4. Testability - How to verify the implementation works
-5. Self-Contained - Most info needed is in the story itself
-
-REMEMBER: We assume competent developer agents who can:
-
-- Research documentation and codebases
-- Make reasonable technical decisions
-- Follow established patterns
-- Ask for clarification when truly stuck
-
-We're checking for SUFFICIENT guidance, not exhaustive detail.]]
-
-## 1. GOAL & CONTEXT CLARITY
-
-[[LLM: Without clear goals, developers build the wrong thing. Verify:
-
-1. The story states WHAT functionality to implement
-2. The business value or user benefit is clear
-3. How this fits into the larger epic/product is explained
-4. Dependencies are explicit ("requires Story X to be complete")
-5. Success looks like something specific, not vague]]
-
-- [ ] Story goal/purpose is clearly stated
-- [ ] Relationship to epic goals is evident
-- [ ] How the story fits into overall system flow is explained
-- [ ] Dependencies on previous stories are identified (if applicable)
-- [ ] Business context and value are clear
-
-## 2. TECHNICAL IMPLEMENTATION GUIDANCE
-
-[[LLM: Developers need enough technical context to start coding. Check:
-
-1. Key files/components to create or modify are mentioned
-2. Technology choices are specified where non-obvious
-3. Integration points with existing code are identified
-4. Data models or API contracts are defined or referenced
-5. Non-standard patterns or exceptions are called out
-
-Note: We don't need every file listed - just the important ones.]]
-
-- [ ] Key files to create/modify are identified (not necessarily exhaustive)
-- [ ] Technologies specifically needed for this story are mentioned
-- [ ] Critical APIs or interfaces are sufficiently described
-- [ ] Necessary data models or structures are referenced
-- [ ] Required environment variables are listed (if applicable)
-- [ ] Any exceptions to standard coding patterns are noted
-
-## 3. REFERENCE EFFECTIVENESS
-
-[[LLM: References should help, not create a treasure hunt. Ensure:
-
-1. References point to specific sections, not whole documents
-2. The relevance of each reference is explained
-3. Critical information is summarized in the story
-4. References are accessible (not broken links)
-5. Previous story context is summarized if needed]]
-
-- [ ] References to external documents point to specific relevant sections
-- [ ] Critical information from previous stories is summarized (not just referenced)
-- [ ] Context is provided for why references are relevant
-- [ ] References use consistent format (e.g., `docs/filename.md#section`)
-
-## 4. SELF-CONTAINMENT ASSESSMENT
-
-[[LLM: Stories should be mostly self-contained to avoid context switching. Verify:
-
-1. Core requirements are in the story, not just in references
-2. Domain terms are explained or obvious from context
-3. Assumptions are stated explicitly
-4. Edge cases are mentioned (even if deferred)
-5. The story could be understood without reading 10 other documents]]
-
-- [ ] Core information needed is included (not overly reliant on external docs)
-- [ ] Implicit assumptions are made explicit
-- [ ] Domain-specific terms or concepts are explained
-- [ ] Edge cases or error scenarios are addressed
-
-## 5. TESTING GUIDANCE
-
-[[LLM: Testing ensures the implementation actually works. Check:
-
-1. Test approach is specified (unit, integration, e2e)
-2. Key test scenarios are listed
-3. Success criteria are measurable
-4. Special test considerations are noted
-5. Acceptance criteria in the story are testable]]
-
-- [ ] Required testing approach is outlined
-- [ ] Key test scenarios are identified
-- [ ] Success criteria are defined
-- [ ] Special testing considerations are noted (if applicable)
-
-## 6. CODERABBIT INTEGRATION (CONDITIONAL)
-
-[[LLM: CONDITIONAL SECTION - Check `coderabbit_integration.enabled` in `.aios-core/core-config.yaml`
-
-**IF `coderabbit_integration.enabled: false`:**
-- SKIP this entire section (6)
-- Verify the story contains the skip notice:
-  > **CodeRabbit Integration**: Disabled
-- Mark section as N/A in validation result
-- Log: "ℹ️ CodeRabbit validation skipped - disabled in core-config.yaml"
-
-**IF `coderabbit_integration.enabled: true`:**
-- Validate ALL items below
-- Story must have complete CodeRabbit section including Story 6.3.3 Self-Healing
-
-CodeRabbit integration ensures automated code review and quality gates. Verify:
-
-1. The 🤖 CodeRabbit Integration section is present
-2. Story type is correctly identified (Database, API, Frontend, Deployment, Security, Architecture, Integration)
-3. Specialized agents are assigned appropriately (@dev required, type-specific agents as needed)
-4. Quality gates are defined (Pre-Commit required, Pre-PR/Pre-Deployment as applicable)
-5. Self-Healing Configuration (Story 6.3.3) is present with correct mode
-6. Focus areas match the story type]]
-
-**Section Presence:**
-- [ ] 🤖 CodeRabbit Integration section exists
-- [ ] All subsections are populated (Story Type Analysis, Specialized Agents, Quality Gates, Self-Healing, Focus Areas)
-
-**Story Type Analysis:**
-- [ ] Primary story type is correctly identified
-- [ ] Complexity level matches story scope
-- [ ] Secondary types listed if applicable
-
-**Specialized Agent Assignment:**
-- [ ] @dev listed as primary agent (required for all stories)
-- [ ] Type-specific agents assigned appropriately:
-  - Database stories → @db-sage
-  - Frontend stories → @ux-expert
-  - Deployment stories → @github-devops
-  - Security stories → @architect
-
-**Quality Gate Tasks:**
-- [ ] Pre-Commit (@dev) defined - REQUIRED for all stories
-- [ ] Pre-PR (@github-devops) defined if PR will be created
-- [ ] Pre-Deployment (@github-devops) defined for production stories
-
-**Self-Healing Configuration (Story 6.3.3):**
-- [ ] Self-healing configuration section is present
-- [ ] Mode matches primary agent:
-  - @dev: light mode (2 iterations, 15 min, CRITICAL only)
-  - @qa: full mode (3 iterations, 30 min, CRITICAL+HIGH)
-  - @github-devops: check mode (report only)
-- [ ] Severity behavior is documented
-
-**Focus Areas:**
-- [ ] Focus areas match the story type
-- [ ] Type-specific validations are listed
-
-## VALIDATION RESULT
-
-[[LLM: FINAL STORY VALIDATION REPORT
-
-Generate a concise validation report:
-
-1. Quick Summary
-
-   - Story readiness: READY / NEEDS REVISION / BLOCKED
-   - Clarity score (1-10)
-   - Major gaps identified
-
-2. Fill in the validation table with:
-
-   - PASS: Requirements clearly met
-   - PARTIAL: Some gaps but workable
-   - FAIL: Critical information missing
-
-3. Specific Issues (if any)
-
-   - List concrete problems to fix
-   - Suggest specific improvements
-   - Identify any blocking dependencies
-
-4. Developer Perspective
-   - Could YOU implement this story as written?
-   - What questions would you have?
-   - What might cause delays or rework?
-
-Be pragmatic - perfect documentation doesn't exist, but it must be enough to provide the extreme context a dev agent needs to get the work down and not create a mess.]]
-
-| Category                             | Status | Issues |
-| ------------------------------------ | ------ | ------ |
-| 1. Goal & Context Clarity            | _TBD_  |        |
-| 2. Technical Implementation Guidance | _TBD_  |        |
-| 3. Reference Effectiveness           | _TBD_  |        |
-| 4. Self-Containment Assessment       | _TBD_  |        |
-| 5. Testing Guidance                  | _TBD_  |        |
-| 6. CodeRabbit Integration (conditional) | _TBD_ or N/A |        |
-
-**Final Assessment:**
-
-- READY: The story provides sufficient context for implementation
-- NEEDS REVISION: The story requires updates (see issues)
-- BLOCKED: External information required (specify what information)
+# Story Draft Checklist
+
+The Scrum Master should use this checklist to validate that each story contains sufficient context for a developer agent to implement it successfully, while assuming the dev agent has reasonable capabilities to figure things out.
+
+[[LLM: INITIALIZATION INSTRUCTIONS - STORY DRAFT VALIDATION
+
+Before proceeding with this checklist, ensure you have access to:
+
+1. The story document being validated (usually in docs/stories/ or provided directly)
+2. The parent epic context
+3. Any referenced architecture or design documents
+4. Previous related stories if this builds on prior work
+
+IMPORTANT: This checklist validates individual stories BEFORE implementation begins.
+
+VALIDATION PRINCIPLES:
+
+1. Clarity - A developer should understand WHAT to build
+2. Context - WHY this is being built and how it fits
+3. Guidance - Key technical decisions and patterns to follow
+4. Testability - How to verify the implementation works
+5. Self-Contained - Most info needed is in the story itself
+
+REMEMBER: We assume competent developer agents who can:
+
+- Research documentation and codebases
+- Make reasonable technical decisions
+- Follow established patterns
+- Ask for clarification when truly stuck
+
+We're checking for SUFFICIENT guidance, not exhaustive detail.]]
+
+## 1. GOAL & CONTEXT CLARITY
+
+[[LLM: Without clear goals, developers build the wrong thing. Verify:
+
+1. The story states WHAT functionality to implement
+2. The business value or user benefit is clear
+3. How this fits into the larger epic/product is explained
+4. Dependencies are explicit ("requires Story X to be complete")
+5. Success looks like something specific, not vague]]
+
+- [ ] Story goal/purpose is clearly stated
+- [ ] Relationship to epic goals is evident
+- [ ] How the story fits into overall system flow is explained
+- [ ] Dependencies on previous stories are identified (if applicable)
+- [ ] Business context and value are clear
+
+## 2. TECHNICAL IMPLEMENTATION GUIDANCE
+
+[[LLM: Developers need enough technical context to start coding. Check:
+
+1. Key files/components to create or modify are mentioned
+2. Technology choices are specified where non-obvious
+3. Integration points with existing code are identified
+4. Data models or API contracts are defined or referenced
+5. Non-standard patterns or exceptions are called out
+
+Note: We don't need every file listed - just the important ones.]]
+
+- [ ] Key files to create/modify are identified (not necessarily exhaustive)
+- [ ] Technologies specifically needed for this story are mentioned
+- [ ] Critical APIs or interfaces are sufficiently described
+- [ ] Necessary data models or structures are referenced
+- [ ] Required environment variables are listed (if applicable)
+- [ ] Any exceptions to standard coding patterns are noted
+
+## 3. REFERENCE EFFECTIVENESS
+
+[[LLM: References should help, not create a treasure hunt. Ensure:
+
+1. References point to specific sections, not whole documents
+2. The relevance of each reference is explained
+3. Critical information is summarized in the story
+4. References are accessible (not broken links)
+5. Previous story context is summarized if needed]]
+
+- [ ] References to external documents point to specific relevant sections
+- [ ] Critical information from previous stories is summarized (not just referenced)
+- [ ] Context is provided for why references are relevant
+- [ ] References use consistent format (e.g., `docs/filename.md#section`)
+
+## 4. SELF-CONTAINMENT ASSESSMENT
+
+[[LLM: Stories should be mostly self-contained to avoid context switching. Verify:
+
+1. Core requirements are in the story, not just in references
+2. Domain terms are explained or obvious from context
+3. Assumptions are stated explicitly
+4. Edge cases are mentioned (even if deferred)
+5. The story could be understood without reading 10 other documents]]
+
+- [ ] Core information needed is included (not overly reliant on external docs)
+- [ ] Implicit assumptions are made explicit
+- [ ] Domain-specific terms or concepts are explained
+- [ ] Edge cases or error scenarios are addressed
+
+## 5. TESTING GUIDANCE
+
+[[LLM: Testing ensures the implementation actually works. Check:
+
+1. Test approach is specified (unit, integration, e2e)
+2. Key test scenarios are listed
+3. Success criteria are measurable
+4. Special test considerations are noted
+5. Acceptance criteria in the story are testable]]
+
+- [ ] Required testing approach is outlined
+- [ ] Key test scenarios are identified
+- [ ] Success criteria are defined
+- [ ] Special testing considerations are noted (if applicable)
+
+## 6. CODERABBIT INTEGRATION (CONDITIONAL)
+
+[[LLM: CONDITIONAL SECTION - Check `coderabbit_integration.enabled` in `.aios-core/core-config.yaml`
+
+**IF `coderabbit_integration.enabled: false`:**
+- SKIP this entire section (6)
+- Verify the story contains the skip notice:
+  > **CodeRabbit Integration**: Disabled
+- Mark section as N/A in validation result
+- Log: "ℹ️ CodeRabbit validation skipped - disabled in core-config.yaml"
+
+**IF `coderabbit_integration.enabled: true`:**
+- Validate ALL items below
+- Story must have complete CodeRabbit section including Story 6.3.3 Self-Healing
+
+CodeRabbit integration ensures automated code review and quality gates. Verify:
+
+1. The 🤖 CodeRabbit Integration section is present
+2. Story type is correctly identified (Database, API, Frontend, Deployment, Security, Architecture, Integration)
+3. Specialized agents are assigned appropriately (@dev required, type-specific agents as needed)
+4. Quality gates are defined (Pre-Commit required, Pre-PR/Pre-Deployment as applicable)
+5. Self-Healing Configuration (Story 6.3.3) is present with correct mode
+6. Focus areas match the story type]]
+
+**Section Presence:**
+- [ ] 🤖 CodeRabbit Integration section exists
+- [ ] All subsections are populated (Story Type Analysis, Specialized Agents, Quality Gates, Self-Healing, Focus Areas)
+
+**Story Type Analysis:**
+- [ ] Primary story type is correctly identified
+- [ ] Complexity level matches story scope
+- [ ] Secondary types listed if applicable
+
+**Specialized Agent Assignment:**
+- [ ] @dev listed as primary agent (required for all stories)
+- [ ] Type-specific agents assigned appropriately:
+  - Database stories → @db-sage
+  - Frontend stories → @ux-expert
+  - Deployment stories → @github-devops
+  - Security stories → @architect
+
+**Quality Gate Tasks:**
+- [ ] Pre-Commit (@dev) defined - REQUIRED for all stories
+- [ ] Pre-PR (@github-devops) defined if PR will be created
+- [ ] Pre-Deployment (@github-devops) defined for production stories
+
+**Self-Healing Configuration (Story 6.3.3):**
+- [ ] Self-healing configuration section is present
+- [ ] Mode matches primary agent:
+  - @dev: light mode (2 iterations, 15 min, CRITICAL only)
+  - @qa: full mode (3 iterations, 30 min, CRITICAL+HIGH)
+  - @github-devops: check mode (report only)
+- [ ] Severity behavior is documented
+
+**Focus Areas:**
+- [ ] Focus areas match the story type
+- [ ] Type-specific validations are listed
+
+## VALIDATION RESULT
+
+[[LLM: FINAL STORY VALIDATION REPORT
+
+Generate a concise validation report:
+
+1. Quick Summary
+
+   - Story readiness: READY / NEEDS REVISION / BLOCKED
+   - Clarity score (1-10)
+   - Major gaps identified
+
+2. Fill in the validation table with:
+
+   - PASS: Requirements clearly met
+   - PARTIAL: Some gaps but workable
+   - FAIL: Critical information missing
+
+3. Specific Issues (if any)
+
+   - List concrete problems to fix
+   - Suggest specific improvements
+   - Identify any blocking dependencies
+
+4. Developer Perspective
+   - Could YOU implement this story as written?
+   - What questions would you have?
+   - What might cause delays or rework?
+
+Be pragmatic - perfect documentation doesn't exist, but it must be enough to provide the extreme context a dev agent needs to get the work down and not create a mess.]]
+
+| Category                             | Status | Issues |
+| ------------------------------------ | ------ | ------ |
+| 1. Goal & Context Clarity            | _TBD_  |        |
+| 2. Technical Implementation Guidance | _TBD_  |        |
+| 3. Reference Effectiveness           | _TBD_  |        |
+| 4. Self-Containment Assessment       | _TBD_  |        |
+| 5. Testing Guidance                  | _TBD_  |        |
+| 6. CodeRabbit Integration (conditional) | _TBD_ or N/A |        |
+
+**Final Assessment:**
+
+- READY: The story provides sufficient context for implementation
+- NEEDS REVISION: The story requires updates (see issues)
+- BLOCKED: External information required (specify what information)
  

package/.aios-core/product/data/atomic-design-principles.md

@@ -0,0 +1,108 @@
+# Atomic Design Principles
+
+**Source:** Brad Frost's Atomic Design methodology
+**Application:** Atlas component organization
+
+---
+
+## The Five Levels
+
+### Atoms
+**Definition:** Basic building blocks that can't be broken down further.
+
+**Examples:**
+- Button
+- Input
+- Label
+- Icon
+- Heading
+- Text
+
+**Rules:**
+- Standalone, reusable
+- No dependencies on other atoms
+- Uses tokens only (no hardcoded values)
+- Single responsibility
+
+### Molecules
+**Definition:** Groups of atoms functioning together as a unit.
+
+**Examples:**
+- FormField (Label + Input + HelperText)
+- SearchBar (Input + Button)
+- Card Header (Icon + Heading + Text)
+
+**Rules:**
+- Composes atoms (doesn't reimplement)
+- Adds composition logic
+- Atoms remain independent
+
+### Organisms
+**Definition:** Complex UI components composed of molecules and/or atoms.
+
+**Examples:**
+- Navigation (Logo + NavLinks + SearchBar + UserMenu)
+- LoginForm (FormFields + Button + Link)
+- ProductCard (Image + CardHeader + CardBody + Button)
+
+**Rules:**
+- Distinct section of interface
+- Can be reused across templates
+- Manages internal state if needed
+
+### Templates
+**Definition:** Page-level layout without real content.
+
+**Examples:**
+- DashboardLayout
+- ArticleLayout
+- CheckoutFlowLayout
+
+**Rules:**
+- Defines page structure
+- Placeholder content
+- Reusable across pages
+
+### Pages
+**Definition:** Templates with real content.
+
+**Examples:**
+- Homepage
+- Product Detail Page
+- User Dashboard
+
+**Note:** Atlas focuses on atoms → organisms. Pages are application-specific.
+
+---
+
+## Benefits
+
+1. **Consistency:** Reusing atoms ensures UI consistency
+2. **Scalability:** New features built from existing components
+3. **Maintenance:** Fix once, applies everywhere
+4. **Testing:** Test atoms thoroughly, compose with confidence
+5. **Collaboration:** Clear component taxonomy
+
+---
+
+## Atlas Implementation
+
+```
+design-system/
+├── atoms/
+│   ├── Button/
+│   ├── Input/
+│   └── Label/
+├── molecules/
+│   ├── FormField/
+│   └── SearchBar/
+├── organisms/
+│   ├── Navigation/
+│   └── LoginForm/
+└── templates/
+    └── DashboardLayout/
+```
+
+**Atlas builds:** atoms first → molecules → organisms → templates
+
+**Reference:** https://atomicdesign.bradfrost.com/

package/.aios-core/product/data/brainstorming-techniques.md

@@ -1,37 +1,37 @@
-# Brainstorming Techniques Data
-
-## Creative Expansion
-
-1. **What If Scenarios**: Ask one provocative question, get their response, then ask another
-2. **Analogical Thinking**: Give one example analogy, ask them to find 2-3 more
-3. **Reversal/Inversion**: Pose the reverse question, let them work through it
-4. **First Principles Thinking**: Ask "What are the fundamentals?" and guide them to break it down
-
-## Structured Frameworks
-
-5. **SCAMPER Method**: Go through one letter at a time, wait for their ideas before moving to next
-6. **Six Thinking Hats**: Present one hat, ask for their thoughts, then move to next hat
-7. **Mind Mapping**: Start with central concept, ask them to suggest branches
-
-## Collaborative Techniques
-
-8. **"Yes, And..." Building**: They give idea, you "yes and" it, they "yes and" back - alternate
-9. **Brainwriting/Round Robin**: They suggest idea, you build on it, ask them to build on yours
-10. **Random Stimulation**: Give one random prompt/word, ask them to make connections
-
-## Deep Exploration
-
-11. **Five Whys**: Ask "why" and wait for their answer before asking next "why"
-12. **Morphological Analysis**: Ask them to list parameters first, then explore combinations together
-13. **Provocation Technique (PO)**: Give one provocative statement, ask them to extract useful ideas
-
-## Advanced Techniques
-
-14. **Forced Relationships**: Connect two unrelated concepts and ask them to find the bridge
-15. **Assumption Reversal**: Challenge their core assumptions and ask them to build from there
-16. **Role Playing**: Ask them to brainstorm from different stakeholder perspectives
-17. **Time Shifting**: "How would you solve this in 1995? 2030?"
-18. **Resource Constraints**: "What if you had only $10 and 1 hour?"
-19. **Metaphor Mapping**: Use extended metaphors to explore solutions
-20. **Question Storming**: Generate questions instead of answers first
+# Brainstorming Techniques Data
+
+## Creative Expansion
+
+1. **What If Scenarios**: Ask one provocative question, get their response, then ask another
+2. **Analogical Thinking**: Give one example analogy, ask them to find 2-3 more
+3. **Reversal/Inversion**: Pose the reverse question, let them work through it
+4. **First Principles Thinking**: Ask "What are the fundamentals?" and guide them to break it down
+
+## Structured Frameworks
+
+5. **SCAMPER Method**: Go through one letter at a time, wait for their ideas before moving to next
+6. **Six Thinking Hats**: Present one hat, ask for their thoughts, then move to next hat
+7. **Mind Mapping**: Start with central concept, ask them to suggest branches
+
+## Collaborative Techniques
+
+8. **"Yes, And..." Building**: They give idea, you "yes and" it, they "yes and" back - alternate
+9. **Brainwriting/Round Robin**: They suggest idea, you build on it, ask them to build on yours
+10. **Random Stimulation**: Give one random prompt/word, ask them to make connections
+
+## Deep Exploration
+
+11. **Five Whys**: Ask "why" and wait for their answer before asking next "why"
+12. **Morphological Analysis**: Ask them to list parameters first, then explore combinations together
+13. **Provocation Technique (PO)**: Give one provocative statement, ask them to extract useful ideas
+
+## Advanced Techniques
+
+14. **Forced Relationships**: Connect two unrelated concepts and ask them to find the bridge
+15. **Assumption Reversal**: Challenge their core assumptions and ask them to build from there
+16. **Role Playing**: Ask them to brainstorm from different stakeholder perspectives
+17. **Time Shifting**: "How would you solve this in 1995? 2030?"
+18. **Resource Constraints**: "What if you had only $10 and 1 hour?"
+19. **Metaphor Mapping**: Use extended metaphors to explore solutions
+20. **Question Storming**: Generate questions instead of answers first