aios-core 2.1.5 → 2.2.0

package/.aios-core/development/tasks/create-brownfield-story.md

@@ -1,727 +1,727 @@
----
-
-## Execution Modes
-
-**Choose your execution mode:**
-
-### 1. YOLO Mode - Fast, Autonomous (0-1 prompts)
-- Autonomous decision making with logging
-- Minimal user interaction
-- **Best for:** Simple, deterministic tasks
-
-### 2. Interactive Mode - Balanced, Educational (5-10 prompts) **[DEFAULT]**
-- Explicit decision checkpoints
-- Educational explanations
-- **Best for:** Learning, complex decisions
-
-### 3. Pre-Flight Planning - Comprehensive Upfront Planning
-- Task analysis phase (identify all ambiguities)
-- Zero ambiguity execution
-- **Best for:** Ambiguous requirements, critical work
-
-**Parameter:** `mode` (optional, default: `interactive`)
-
----
-
-## Task Definition (AIOS Task Format V1.0)
-
-```yaml
-task: createBrownfieldStory()
-responsável: Pax (Balancer)
-responsavel_type: Agente
-atomic_layer: Organism
-
-**Entrada:**
-- campo: name
-  tipo: string
-  origem: User Input
-  obrigatório: true
-  validação: Must be non-empty, lowercase, kebab-case
-
-- campo: options
-  tipo: object
-  origem: User Input
-  obrigatório: false
-  validação: Valid JSON object with allowed keys
-
-- campo: force
-  tipo: boolean
-  origem: User Input
-  obrigatório: false
-  validação: Default: false
-
-**Saída:**
-- campo: created_file
-  tipo: string
-  destino: File system
-  persistido: true
-
-- campo: validation_report
-  tipo: object
-  destino: Memory
-  persistido: false
-
-- campo: success
-  tipo: boolean
-  destino: Return value
-  persistido: false
-```
-
----
-
-## Pre-Conditions
-
-**Purpose:** Validate prerequisites BEFORE task execution (blocking)
-
-**Checklist:**
-
-```yaml
-pre-conditions:
-  - [ ] Target does not already exist; required inputs provided; permissions granted
-    tipo: pre-condition
-    blocker: true
-    validação: |
-      Check target does not already exist; required inputs provided; permissions granted
-    error_message: "Pre-condition failed: Target does not already exist; required inputs provided; permissions granted"
-```
-
----
-
-## Post-Conditions
-
-**Purpose:** Validate execution success AFTER task completes
-
-**Checklist:**
-
-```yaml
-post-conditions:
-  - [ ] Resource created successfully; validation passed; no errors logged
-    tipo: post-condition
-    blocker: true
-    validação: |
-      Verify resource created successfully; validation passed; no errors logged
-    error_message: "Post-condition failed: Resource created successfully; validation passed; no errors logged"
-```
-
----
-
-## Acceptance Criteria
-
-**Purpose:** Definitive pass/fail criteria for task completion
-
-**Checklist:**
-
-```yaml
-acceptance-criteria:
-  - [ ] Resource exists and is valid; no duplicate resources created
-    tipo: acceptance-criterion
-    blocker: true
-    validação: |
-      Assert resource exists and is valid; no duplicate resources created
-    error_message: "Acceptance criterion not met: Resource exists and is valid; no duplicate resources created"
-```
-
----
-
-## Tools
-
-**External/shared resources used by this task:**
-
-- **Tool:** component-generator
-  - **Purpose:** Generate new components from templates
-  - **Source:** .aios-core/scripts/component-generator.js
-
-- **Tool:** file-system
-  - **Purpose:** File creation and validation
-  - **Source:** Node.js fs module
-
----
-
-## Scripts
-
-**Agent-specific code for this task:**
-
-- **Script:** create-component.js
-  - **Purpose:** Component creation workflow
-  - **Language:** JavaScript
-  - **Location:** .aios-core/scripts/create-component.js
-
----
-
-## Error Handling
-
-**Strategy:** retry
-
-**Common Errors:**
-
-1. **Error:** Resource Already Exists
-   - **Cause:** Target file/resource already exists in system
-   - **Resolution:** Use force flag or choose different name
-   - **Recovery:** Prompt user for alternative name or force overwrite
-
-2. **Error:** Invalid Input
-   - **Cause:** Input name contains invalid characters or format
-   - **Resolution:** Validate input against naming rules (kebab-case, lowercase, no special chars)
-   - **Recovery:** Sanitize input or reject with clear error message
-
-3. **Error:** Permission Denied
-   - **Cause:** Insufficient permissions to create resource
-   - **Resolution:** Check file system permissions, run with elevated privileges if needed
-   - **Recovery:** Log error, notify user, suggest permission fix
-
----
-
-## Performance
-
-**Expected Metrics:**
-
-```yaml
-duration_expected: 5-15 min (estimated)
-cost_estimated: $0.003-0.010
-token_usage: ~3,000-10,000 tokens
-```
-
-**Optimization Notes:**
-- Break into smaller workflows; implement checkpointing; use async processing where possible
-
----
-
-## Metadata
-
-```yaml
-story: N/A
-version: 1.0.0
-dependencies:
-  - N/A
-tags:
-  - creation
-  - setup
-updated_at: 2025-11-17
-```
-
----
-
-tools:
-  - github-cli
-checklists:
-  - po-master-checklist.md
----
-
-# Create Brownfield Story Task
-
-## Purpose
-
-Create detailed, implementation-ready stories for brownfield projects where traditional sharded PRD/architecture documents may not exist. This task bridges the gap between various documentation formats (document-project output, brownfield PRDs, epics, or user documentation) and executable stories for the Dev agent.
-
-## When to Use This Task
-
-**Use this task when:**
-
-- Working on brownfield projects with non-standard documentation
-- Stories need to be created from document-project output
-- Working from brownfield epics without full PRD/architecture
-- Existing project documentation doesn't follow AIOS v4+ structure
-- Need to gather additional context from user during story creation
-
-**Use create-next-story when:**
-
-- Working with properly sharded PRD and v4 architecture documents
-- Following standard greenfield or well-documented brownfield workflow
-- All technical context is available in structured format
-
-## Task Execution Instructions
-
-### 0. Documentation Context
-
-Check for available documentation in this order:
-
-1. **Sharded PRD/Architecture** (docs/prd/, docs/architecture/)
-   - If found, recommend using create-next-story task instead
-
-2. **Brownfield Architecture Document** (docs/brownfield-architecture.md or similar)
-   - Created by document-project task
-   - Contains actual system state, technical debt, workarounds
-
-3. **Brownfield PRD** (docs/prd.md)
-   - May contain embedded technical details
-
-4. **Epic Files** (docs/epics/ or similar)
-   - Created by brownfield-create-epic task
-
-5. **User-Provided Documentation**
-   - Ask user to specify location and format
-
-### 1. Story Identification and Context Gathering
-
-#### 1.1 Identify Story Source
-
-Based on available documentation:
-
-- **From Brownfield PRD**: Extract stories from epic sections
-- **From Epic Files**: Read epic definition and story list
-- **From User Direction**: Ask user which specific enhancement to implement
-- **No Clear Source**: Work with user to define the story scope
-
-#### 1.2 Gather Essential Context
-
-CRITICAL: For brownfield stories, you MUST gather enough context for safe implementation. Be prepared to ask the user for missing information.
-
-**Required Information Checklist:**
-
-- [ ] What existing functionality might be affected?
-- [ ] What are the integration points with current code?
-- [ ] What patterns should be followed (with examples)?
-- [ ] What technical constraints exist?
-- [ ] Are there any "gotchas" or workarounds to know about?
-
-If any required information is missing, list the missing information and ask the user to provide it.
-
-### 2. Extract Technical Context from Available Sources
-
-#### 2.1 From Document-Project Output
-
-If using brownfield-architecture.md from document-project:
-
-- **Technical Debt Section**: Note any workarounds affecting this story
-- **Key Files Section**: Identify files that will need modification
-- **Integration Points**: Find existing integration patterns
-- **Known Issues**: Check if story touches problematic areas
-- **Actual Tech Stack**: Verify versions and constraints
-
-## Configuration Dependencies
-
-This task requires the following configuration keys from `core-config.yaml`:
-
-- **`qaLocation`**: QA output directory (typically docs/qa) - Required to write quality reports
-
-**Loading Config:**
-```javascript
-const yaml = require('js-yaml');
-const fs = require('fs');
-const path = require('path');
-
-const configPath = path.join(__dirname, '../../.aios-core/core-config.yaml');
-const config = yaml.load(fs.readFileSync(configPath, 'utf8'));
-
-const qaLocation = config.qa?.qaLocation || 'docs/qa';
-```
-
-#### 2.2 From Brownfield PRD
-
-If using brownfield PRD:
-
-- **Technical Constraints Section**: Extract all relevant constraints
-- **Integration Requirements**: Note compatibility requirements
-- **Code Organization**: Follow specified patterns
-- **Risk Assessment**: Understand potential impacts
-
-#### 2.3 From User Documentation
-
-Ask the user to help identify:
-
-- Relevant technical specifications
-- Existing code examples to follow
-- Integration requirements
-- Testing approaches used in the project
-
-### 3. Story Creation with Progressive Detail Gathering
-
-#### 3.1 Create Initial Story Structure
-
-Start with the story template, filling in what's known:
-
-```markdown
-# Story {{Enhancement Title}}
-
-## Status: Draft
-
-## Story
-
-As a {{user_type}},
-I want {{enhancement_capability}},
-so that {{value_delivered}}.
-
-## Context Source
-
-- Source Document: {{document name/type}}
-- Enhancement Type: {{single feature/bug fix/integration/etc}}
-- Existing System Impact: {{brief assessment}}
-```
-
-#### 3.2 Develop Acceptance Criteria
-
-Critical: For brownfield, ALWAYS include criteria about maintaining existing functionality
-
-Standard structure:
-
-1. New functionality works as specified
-2. Existing {{affected feature}} continues to work unchanged  
-3. Integration with {{existing system}} maintains current behavior
-4. No regression in {{related area}}
-5. Performance remains within acceptable bounds
-
-#### 3.3 Gather Technical Guidance
-
-Critical: This is where you'll need to be interactive with the user if information is missing
-
-Create Dev Technical Guidance section with available information:
-
-```markdown
-## Dev Technical Guidance
-
-### Existing System Context
-[Extract from available documentation]
-
-### Integration Approach
-[Based on patterns found or ask user]
-
-### Technical Constraints
-[From documentation or user input]
-
-### Missing Information
-
-Critical: List anything you couldn't find that dev will need and ask for the missing information
-
-### 4. Task Generation with Safety Checks
-
-#### 4.1 Generate Implementation Tasks
-
-Based on gathered context, create tasks that:
-
-- Include exploration tasks if system understanding is incomplete
-- Add verification tasks for existing functionality
-- Include rollback considerations
-- Reference specific files/patterns when known
-
-Example task structure for brownfield:
-
-```markdown
-## Tasks / Subtasks
-
-- [ ] Task 1: Analyze existing {{component/feature}} implementation
-  - [ ] Review {{specific files}} for current patterns
-  - [ ] Document integration points
-  - [ ] Identify potential impacts
-
-- [ ] Task 2: Implement {{new functionality}}
-  - [ ] Follow pattern from {{example file}}
-  - [ ] Integrate with {{existing component}}
-  - [ ] Maintain compatibility with {{constraint}}
-
-- [ ] Task 3: Verify existing functionality
-  - [ ] Test {{existing feature 1}} still works
-  - [ ] Verify {{integration point}} behavior unchanged
-  - [ ] Check performance impact
-
-- [ ] Task 4: Add tests
-  - [ ] Unit tests following {{project test pattern}}
-  - [ ] Integration test for {{integration point}}
-  - [ ] Update existing tests if needed
-```
-
-#### 4.4 Predict Quality Requirements and Agent Assignment
-
-**CRITICAL FOR BROWNFIELD:** This step populates the `🤖 CodeRabbit Integration` section with brownfield-specific quality gates. Brownfield stories have HIGHER RISK due to integration complexity, so quality planning is essential.
-
-**Integration Point Analysis:**
-
-Analyze the story's integration risks based on:
-- What existing functionality will be modified?
-- How many integration points are affected?
-- Is this touching core/critical functionality?
-- What is the blast radius of potential bugs?
-
-**Brownfield-Specific Agent Assignment Rules:**
-
-**If modifying existing database:**
-- **Assign**: @db-sage, @dev
-- **Rationale**: Database changes in brownfield require expert review for:
-  - Existing data migration impacts
-  - RLS policy compatibility
-  - Index performance on existing data
-  - Foreign key constraint conflicts
-- **Quality Gates**: Pre-Commit (schema validation), Pre-PR (SQL review), Pre-Deployment (migration testing)
-
-**If changing existing APIs:**
-- **Assign**: @architect, @dev
-- **Rationale**: API changes risk breaking existing clients:
-  - Backward compatibility validation
-  - Contract versioning requirements
-  - Breaking change identification
-  - Client impact assessment
-- **Quality Gates**: Pre-Commit (contract validation), Pre-PR (backward compat check)
-
-**If touching deployment/infrastructure:**
-- **Assign**: @github-devops, @dev
-- **Rationale**: Infrastructure changes need rollback safety:
-  - Environment-specific configuration validation
-  - Rollback procedure verification
-  - Zero-downtime deployment planning
-  - Feature flag implementation if needed
-- **Quality Gates**: Pre-Commit (config validation), Pre-Deployment (deep scan with rollback plan)
-
-**If affecting existing UI/UX:**
-- **Assign**: @ux-expert, @dev
-- **Rationale**: UI changes must maintain user experience consistency:
-  - Design system compliance
-  - Accessibility standards maintained
-  - User workflow continuity
-  - Browser compatibility preserved
-- **Quality Gates**: Pre-Commit (a11y validation), Pre-PR (UX consistency check)
-
-**Risk-Based Quality Gate Determination:**
-
-**HIGH RISK** (affects core functionality, many integration points, production-critical):
-- **Quality Gates**: Pre-Commit + Pre-PR + Pre-Deployment
-- **Additional Requirements**:
-  - Feature flag implementation recommended
-  - Phased rollout strategy
-  - Detailed rollback procedure
-  - Monitoring and alerting plan
-- **Focus Areas**:
-  - Regression prevention (existing functionality MUST work)
-  - Integration safety (new code doesn't break old code)
-  - Rollback readiness (changes are reversible)
-  - Performance impact (no degradation to existing features)
-
-**MEDIUM RISK** (new feature with isolated scope, some integration):
-- **Quality Gates**: Pre-Commit + Pre-PR
-- **Additional Requirements**:
-  - Integration testing with existing features
-  - Unit tests for new and affected code
-  - Documentation updates
-- **Focus Areas**:
-  - Integration points validated
-  - Existing patterns followed
-  - Error handling comprehensive
-
-**LOW RISK** (documentation, tests only, isolated bug fix):
-- **Quality Gates**: Pre-Commit
-- **Additional Requirements**:
-  - Standard code review
-  - Basic testing
-- **Focus Areas**:
-  - Code quality standards
-  - Documentation clarity
-
-**CodeRabbit Focus for Brownfield:**
-
-Regardless of story type, ALL brownfield stories must include these focus areas:
-
-```yaml
-🤖 CodeRabbit Integration:
-
-  Story Type Analysis:
-    Primary Type: [Database|API|Frontend|Deployment|Security|Integration]
-    Secondary Type(s): [Additional types]
-    Complexity: [Low|Medium|High]
-    Risk Level: [LOW RISK|MEDIUM RISK|HIGH RISK] ← Brownfield-specific
-    Integration Points: [List of systems/components affected] ← Brownfield-specific
-
-  Specialized Agent Assignment:
-    Primary Agents:
-      - @dev (always required)
-      - @[integration-specific-agent] (based on affected systems)
-
-    Supporting Agents:
-      - @[supporting-agent-1] (if multiple systems)
-      - @[supporting-agent-2] (if cross-cutting concerns)
-
-  Quality Gate Tasks:
-    - [ ] Pre-Commit (@dev): Run `coderabbit --prompt-only -t uncommitted` before story complete
-    - [ ] Pre-PR (@github-devops): Run `coderabbit --prompt-only --base main` before PR creation
-    - [ ] Pre-Deployment (@github-devops): Run `coderabbit --prompt-only -t committed --base HEAD~10` before production deploy (HIGH RISK stories only)
-
-  CodeRabbit Focus Areas:
-    Primary Focus (Brownfield-Specific):
-      - Regression prevention: Existing functionality preserved
-      - Integration safety: New code doesn't break existing code
-      - Rollback readiness: Changes are reversible
-      - [Type-specific focus from detection rules]
-
-    Secondary Focus:
-      - [Type-specific focus areas]
-      - Performance impact: No degradation to existing features
-      - Error handling: Graceful degradation for integration failures
-```
-
-**Brownfield Example (HIGH RISK Database + API Story):**
-
-```yaml
-🤖 CodeRabbit Integration:
-
-  Story Type Analysis:
-    Primary Type: Database
-    Secondary Type(s): API
-    Complexity: High (schema changes + multiple API endpoints)
-    Risk Level: HIGH RISK (affects core payment processing functionality)
-    Integration Points:
-      - Payment service API
-      - Transaction database tables
-      - External payment gateway webhook
-      - User notification system
-
-  Specialized Agent Assignment:
-    Primary Agents:
-      - @dev (pre-commit reviews)
-      - @db-sage (schema changes, RLS policies, existing data migration)
-      - @architect (API contract changes, backward compatibility)
-
-    Supporting Agents:
-      - @github-devops (phased rollout, rollback procedure)
-
-  Quality Gate Tasks:
-    - [ ] Pre-Commit (@dev): Run before story complete
-    - [ ] Pre-PR (@github-devops): Run before PR creation
-    - [ ] Pre-Deployment (@github-devops): Run before production deploy with rollback plan validation
-
-  CodeRabbit Focus Areas:
-    Primary Focus (Brownfield-Specific):
-      - Regression prevention: Existing payment flows MUST work identically
-      - Integration safety: New schema compatible with existing queries
-      - Rollback readiness: Migration reversible without data loss
-      - Service filters on ALL queries (.eq('service', 'ttcx'))
-      - Schema compliance with existing patterns
-
-    Secondary Focus:
-      - API backward compatibility: v1 clients still supported
-      - Performance: No degradation to existing payment processing
-      - Error handling: Graceful fallback for gateway failures
-      - RLS policies: Consistent with existing security model
-      - Migration testing: Validated on copy of production data structure
-```
-
-**Integration-Specific Considerations:**
-
-When story involves specific integration patterns:
-
-**Database Integration:**
-- Focus: Existing data compatibility, migration safety, RLS policy consistency
-- Validation: Run migration on production-like data, verify all existing queries still work
-
-**API Integration:**
-- Focus: Contract versioning, backward compatibility, client impact assessment
-- Validation: Integration tests with existing API clients, contract testing
-
-**Frontend Integration:**
-- Focus: User workflow continuity, design system compliance, accessibility preservation
-- Validation: Visual regression testing, user acceptance testing on existing flows
-
-**External System Integration:**
-- Focus: Graceful degradation, retry logic, error handling, monitoring
-- Validation: Failure scenario testing, circuit breaker validation
-
-**Log Completion:**
-- After populating this section, log: "✅ Brownfield story analysis complete: [Primary Type] | Risk Level: [RISK] | Integration Points: [count] | Agents assigned: [agent list]"
-
-### 5. Risk Assessment and Mitigation
-
-CRITICAL: for brownfield - always include risk assessment
-
-Add section for brownfield-specific risks:
-
-```markdown
-## Risk Assessment
-
-### Implementation Risks
-- **Primary Risk**: {{main risk to existing system}}
-- **Mitigation**: {{how to address}}
-- **Verification**: {{how to confirm safety}}
-
-### Rollback Plan
-- {{Simple steps to undo changes if needed}}
-
-### Safety Checks
-- [ ] Existing {{feature}} tested before changes
-- [ ] Changes can be feature-flagged or isolated
-- [ ] Rollback procedure documented
-```
-
-### 6. Final Story Validation
-
-Before finalizing:
-
-1. **Completeness Check**:
-   - [ ] Story has clear scope and acceptance criteria
-   - [ ] Technical context is sufficient for implementation
-   - [ ] Integration approach is defined
-   - [ ] Risks are identified with mitigation
-
-2. **Safety Check**:
-   - [ ] Existing functionality protection included
-   - [ ] Rollback plan is feasible
-   - [ ] Testing covers both new and existing features
-
-3. **Information Gaps**:
-   - [ ] All critical missing information gathered from user
-   - [ ] Remaining unknowns documented for dev agent
-   - [ ] Exploration tasks added where needed
-
-### 7. Story Output Format
-
-Save the story with appropriate naming:
-
-- If from epic: `docs/stories/epic-{n}-story-{m}.md`
-- If standalone: `docs/stories/brownfield-{feature-name}.md`
-- If sequential: Follow existing story numbering
-
-Include header noting documentation context:
-
-```markdown
-# Story: {{Title}}
-
-<!-- Source: {{documentation type used}} -->
-<!-- Context: Brownfield enhancement to {{existing system}} -->
-
-## Status: Draft
-[Rest of story content...]
-```
-
-### 8. Handoff Communication
-
-Provide clear handoff to the user:
-
-```text
-Brownfield story created: {{story title}}
-
-Source Documentation: {{what was used}}
-Story Location: {{file path}}
-
-Key Integration Points Identified:
-- {{integration point 1}}
-- {{integration point 2}}
-
-Risks Noted:
-- {{primary risk}}
-
-{{If missing info}}: 
-Note: Some technical details were unclear. The story includes exploration tasks to gather needed information during implementation.
-
-Next Steps:
-1. Review story for accuracy
-2. Verify integration approach aligns with your system
-3. Approve story or request adjustments
-4. Dev agent can then implement with safety checks
-```
-
-## Success Criteria
-
-The brownfield story creation is successful when:
-
-1. Story can be implemented without requiring dev to search multiple documents
-2. Integration approach is clear and safe for existing system
-3. All available technical context has been extracted and organized
-4. Missing information has been identified and addressed
-5. Risks are documented with mitigation strategies
-6. Story includes verification of existing functionality
-7. Rollback approach is defined
-
-## Important Notes
-
-- This task is specifically for brownfield projects with non-standard documentation
-- Always prioritize existing system stability over new features
-- When in doubt, add exploration and verification tasks
-- It's better to ask the user for clarification than make assumptions
-- Each story should be self-contained for the dev agent
-- Include references to existing code patterns when available
+---
+
+## Execution Modes
+
+**Choose your execution mode:**
+
+### 1. YOLO Mode - Fast, Autonomous (0-1 prompts)
+- Autonomous decision making with logging
+- Minimal user interaction
+- **Best for:** Simple, deterministic tasks
+
+### 2. Interactive Mode - Balanced, Educational (5-10 prompts) **[DEFAULT]**
+- Explicit decision checkpoints
+- Educational explanations
+- **Best for:** Learning, complex decisions
+
+### 3. Pre-Flight Planning - Comprehensive Upfront Planning
+- Task analysis phase (identify all ambiguities)
+- Zero ambiguity execution
+- **Best for:** Ambiguous requirements, critical work
+
+**Parameter:** `mode` (optional, default: `interactive`)
+
+---
+
+## Task Definition (AIOS Task Format V1.0)
+
+```yaml
+task: createBrownfieldStory()
+responsável: Pax (Balancer)
+responsavel_type: Agente
+atomic_layer: Organism
+
+**Entrada:**
+- campo: name
+  tipo: string
+  origem: User Input
+  obrigatório: true
+  validação: Must be non-empty, lowercase, kebab-case
+
+- campo: options
+  tipo: object
+  origem: User Input
+  obrigatório: false
+  validação: Valid JSON object with allowed keys
+
+- campo: force
+  tipo: boolean
+  origem: User Input
+  obrigatório: false
+  validação: Default: false
+
+**Saída:**
+- campo: created_file
+  tipo: string
+  destino: File system
+  persistido: true
+
+- campo: validation_report
+  tipo: object
+  destino: Memory
+  persistido: false
+
+- campo: success
+  tipo: boolean
+  destino: Return value
+  persistido: false
+```
+
+---
+
+## Pre-Conditions
+
+**Purpose:** Validate prerequisites BEFORE task execution (blocking)
+
+**Checklist:**
+
+```yaml
+pre-conditions:
+  - [ ] Target does not already exist; required inputs provided; permissions granted
+    tipo: pre-condition
+    blocker: true
+    validação: |
+      Check target does not already exist; required inputs provided; permissions granted
+    error_message: "Pre-condition failed: Target does not already exist; required inputs provided; permissions granted"
+```
+
+---
+
+## Post-Conditions
+
+**Purpose:** Validate execution success AFTER task completes
+
+**Checklist:**
+
+```yaml
+post-conditions:
+  - [ ] Resource created successfully; validation passed; no errors logged
+    tipo: post-condition
+    blocker: true
+    validação: |
+      Verify resource created successfully; validation passed; no errors logged
+    error_message: "Post-condition failed: Resource created successfully; validation passed; no errors logged"
+```
+
+---
+
+## Acceptance Criteria
+
+**Purpose:** Definitive pass/fail criteria for task completion
+
+**Checklist:**
+
+```yaml
+acceptance-criteria:
+  - [ ] Resource exists and is valid; no duplicate resources created
+    tipo: acceptance-criterion
+    blocker: true
+    validação: |
+      Assert resource exists and is valid; no duplicate resources created
+    error_message: "Acceptance criterion not met: Resource exists and is valid; no duplicate resources created"
+```
+
+---
+
+## Tools
+
+**External/shared resources used by this task:**
+
+- **Tool:** component-generator
+  - **Purpose:** Generate new components from templates
+  - **Source:** .aios-core/scripts/component-generator.js
+
+- **Tool:** file-system
+  - **Purpose:** File creation and validation
+  - **Source:** Node.js fs module
+
+---
+
+## Scripts
+
+**Agent-specific code for this task:**
+
+- **Script:** create-component.js
+  - **Purpose:** Component creation workflow
+  - **Language:** JavaScript
+  - **Location:** .aios-core/scripts/create-component.js
+
+---
+
+## Error Handling
+
+**Strategy:** retry
+
+**Common Errors:**
+
+1. **Error:** Resource Already Exists
+   - **Cause:** Target file/resource already exists in system
+   - **Resolution:** Use force flag or choose different name
+   - **Recovery:** Prompt user for alternative name or force overwrite
+
+2. **Error:** Invalid Input
+   - **Cause:** Input name contains invalid characters or format
+   - **Resolution:** Validate input against naming rules (kebab-case, lowercase, no special chars)
+   - **Recovery:** Sanitize input or reject with clear error message
+
+3. **Error:** Permission Denied
+   - **Cause:** Insufficient permissions to create resource
+   - **Resolution:** Check file system permissions, run with elevated privileges if needed
+   - **Recovery:** Log error, notify user, suggest permission fix
+
+---
+
+## Performance
+
+**Expected Metrics:**
+
+```yaml
+duration_expected: 5-15 min (estimated)
+cost_estimated: $0.003-0.010
+token_usage: ~3,000-10,000 tokens
+```
+
+**Optimization Notes:**
+- Break into smaller workflows; implement checkpointing; use async processing where possible
+
+---
+
+## Metadata
+
+```yaml
+story: N/A
+version: 1.0.0
+dependencies:
+  - N/A
+tags:
+  - creation
+  - setup
+updated_at: 2025-11-17
+```
+
+---
+
+tools:
+  - github-cli
+checklists:
+  - po-master-checklist.md
+---
+
+# Create Brownfield Story Task
+
+## Purpose
+
+Create detailed, implementation-ready stories for brownfield projects where traditional sharded PRD/architecture documents may not exist. This task bridges the gap between various documentation formats (document-project output, brownfield PRDs, epics, or user documentation) and executable stories for the Dev agent.
+
+## When to Use This Task
+
+**Use this task when:**
+
+- Working on brownfield projects with non-standard documentation
+- Stories need to be created from document-project output
+- Working from brownfield epics without full PRD/architecture
+- Existing project documentation doesn't follow AIOS v4+ structure
+- Need to gather additional context from user during story creation
+
+**Use create-next-story when:**
+
+- Working with properly sharded PRD and v4 architecture documents
+- Following standard greenfield or well-documented brownfield workflow
+- All technical context is available in structured format
+
+## Task Execution Instructions
+
+### 0. Documentation Context
+
+Check for available documentation in this order:
+
+1. **Sharded PRD/Architecture** (docs/prd/, docs/architecture/)
+   - If found, recommend using create-next-story task instead
+
+2. **Brownfield Architecture Document** (docs/brownfield-architecture.md or similar)
+   - Created by document-project task
+   - Contains actual system state, technical debt, workarounds
+
+3. **Brownfield PRD** (docs/prd.md)
+   - May contain embedded technical details
+
+4. **Epic Files** (docs/epics/ or similar)
+   - Created by brownfield-create-epic task
+
+5. **User-Provided Documentation**
+   - Ask user to specify location and format
+
+### 1. Story Identification and Context Gathering
+
+#### 1.1 Identify Story Source
+
+Based on available documentation:
+
+- **From Brownfield PRD**: Extract stories from epic sections
+- **From Epic Files**: Read epic definition and story list
+- **From User Direction**: Ask user which specific enhancement to implement
+- **No Clear Source**: Work with user to define the story scope
+
+#### 1.2 Gather Essential Context
+
+CRITICAL: For brownfield stories, you MUST gather enough context for safe implementation. Be prepared to ask the user for missing information.
+
+**Required Information Checklist:**
+
+- [ ] What existing functionality might be affected?
+- [ ] What are the integration points with current code?
+- [ ] What patterns should be followed (with examples)?
+- [ ] What technical constraints exist?
+- [ ] Are there any "gotchas" or workarounds to know about?
+
+If any required information is missing, list the missing information and ask the user to provide it.
+
+### 2. Extract Technical Context from Available Sources
+
+#### 2.1 From Document-Project Output
+
+If using brownfield-architecture.md from document-project:
+
+- **Technical Debt Section**: Note any workarounds affecting this story
+- **Key Files Section**: Identify files that will need modification
+- **Integration Points**: Find existing integration patterns
+- **Known Issues**: Check if story touches problematic areas
+- **Actual Tech Stack**: Verify versions and constraints
+
+## Configuration Dependencies
+
+This task requires the following configuration keys from `core-config.yaml`:
+
+- **`qaLocation`**: QA output directory (typically docs/qa) - Required to write quality reports
+
+**Loading Config:**
+```javascript
+const yaml = require('js-yaml');
+const fs = require('fs');
+const path = require('path');
+
+const configPath = path.join(__dirname, '../../.aios-core/core-config.yaml');
+const config = yaml.load(fs.readFileSync(configPath, 'utf8'));
+
+const qaLocation = config.qa?.qaLocation || 'docs/qa';
+```
+
+#### 2.2 From Brownfield PRD
+
+If using brownfield PRD:
+
+- **Technical Constraints Section**: Extract all relevant constraints
+- **Integration Requirements**: Note compatibility requirements
+- **Code Organization**: Follow specified patterns
+- **Risk Assessment**: Understand potential impacts
+
+#### 2.3 From User Documentation
+
+Ask the user to help identify:
+
+- Relevant technical specifications
+- Existing code examples to follow
+- Integration requirements
+- Testing approaches used in the project
+
+### 3. Story Creation with Progressive Detail Gathering
+
+#### 3.1 Create Initial Story Structure
+
+Start with the story template, filling in what's known:
+
+```markdown
+# Story {{Enhancement Title}}
+
+## Status: Draft
+
+## Story
+
+As a {{user_type}},
+I want {{enhancement_capability}},
+so that {{value_delivered}}.
+
+## Context Source
+
+- Source Document: {{document name/type}}
+- Enhancement Type: {{single feature/bug fix/integration/etc}}
+- Existing System Impact: {{brief assessment}}
+```
+
+#### 3.2 Develop Acceptance Criteria
+
+Critical: For brownfield, ALWAYS include criteria about maintaining existing functionality
+
+Standard structure:
+
+1. New functionality works as specified
+2. Existing {{affected feature}} continues to work unchanged  
+3. Integration with {{existing system}} maintains current behavior
+4. No regression in {{related area}}
+5. Performance remains within acceptable bounds
+
+#### 3.3 Gather Technical Guidance
+
+Critical: This is where you'll need to be interactive with the user if information is missing
+
+Create Dev Technical Guidance section with available information:
+
+```markdown
+## Dev Technical Guidance
+
+### Existing System Context
+[Extract from available documentation]
+
+### Integration Approach
+[Based on patterns found or ask user]
+
+### Technical Constraints
+[From documentation or user input]
+
+### Missing Information
+
+Critical: List anything you couldn't find that dev will need and ask for the missing information
+
+### 4. Task Generation with Safety Checks
+
+#### 4.1 Generate Implementation Tasks
+
+Based on gathered context, create tasks that:
+
+- Include exploration tasks if system understanding is incomplete
+- Add verification tasks for existing functionality
+- Include rollback considerations
+- Reference specific files/patterns when known
+
+Example task structure for brownfield:
+
+```markdown
+## Tasks / Subtasks
+
+- [ ] Task 1: Analyze existing {{component/feature}} implementation
+  - [ ] Review {{specific files}} for current patterns
+  - [ ] Document integration points
+  - [ ] Identify potential impacts
+
+- [ ] Task 2: Implement {{new functionality}}
+  - [ ] Follow pattern from {{example file}}
+  - [ ] Integrate with {{existing component}}
+  - [ ] Maintain compatibility with {{constraint}}
+
+- [ ] Task 3: Verify existing functionality
+  - [ ] Test {{existing feature 1}} still works
+  - [ ] Verify {{integration point}} behavior unchanged
+  - [ ] Check performance impact
+
+- [ ] Task 4: Add tests
+  - [ ] Unit tests following {{project test pattern}}
+  - [ ] Integration test for {{integration point}}
+  - [ ] Update existing tests if needed
+```
+
+#### 4.4 Predict Quality Requirements and Agent Assignment
+
+**CRITICAL FOR BROWNFIELD:** This step populates the `🤖 CodeRabbit Integration` section with brownfield-specific quality gates. Brownfield stories have HIGHER RISK due to integration complexity, so quality planning is essential.
+
+**Integration Point Analysis:**
+
+Analyze the story's integration risks based on:
+- What existing functionality will be modified?
+- How many integration points are affected?
+- Is this touching core/critical functionality?
+- What is the blast radius of potential bugs?
+
+**Brownfield-Specific Agent Assignment Rules:**
+
+**If modifying existing database:**
+- **Assign**: @db-sage, @dev
+- **Rationale**: Database changes in brownfield require expert review for:
+  - Existing data migration impacts
+  - RLS policy compatibility
+  - Index performance on existing data
+  - Foreign key constraint conflicts
+- **Quality Gates**: Pre-Commit (schema validation), Pre-PR (SQL review), Pre-Deployment (migration testing)
+
+**If changing existing APIs:**
+- **Assign**: @architect, @dev
+- **Rationale**: API changes risk breaking existing clients:
+  - Backward compatibility validation
+  - Contract versioning requirements
+  - Breaking change identification
+  - Client impact assessment
+- **Quality Gates**: Pre-Commit (contract validation), Pre-PR (backward compat check)
+
+**If touching deployment/infrastructure:**
+- **Assign**: @github-devops, @dev
+- **Rationale**: Infrastructure changes need rollback safety:
+  - Environment-specific configuration validation
+  - Rollback procedure verification
+  - Zero-downtime deployment planning
+  - Feature flag implementation if needed
+- **Quality Gates**: Pre-Commit (config validation), Pre-Deployment (deep scan with rollback plan)
+
+**If affecting existing UI/UX:**
+- **Assign**: @ux-expert, @dev
+- **Rationale**: UI changes must maintain user experience consistency:
+  - Design system compliance
+  - Accessibility standards maintained
+  - User workflow continuity
+  - Browser compatibility preserved
+- **Quality Gates**: Pre-Commit (a11y validation), Pre-PR (UX consistency check)
+
+**Risk-Based Quality Gate Determination:**
+
+**HIGH RISK** (affects core functionality, many integration points, production-critical):
+- **Quality Gates**: Pre-Commit + Pre-PR + Pre-Deployment
+- **Additional Requirements**:
+  - Feature flag implementation recommended
+  - Phased rollout strategy
+  - Detailed rollback procedure
+  - Monitoring and alerting plan
+- **Focus Areas**:
+  - Regression prevention (existing functionality MUST work)
+  - Integration safety (new code doesn't break old code)
+  - Rollback readiness (changes are reversible)
+  - Performance impact (no degradation to existing features)
+
+**MEDIUM RISK** (new feature with isolated scope, some integration):
+- **Quality Gates**: Pre-Commit + Pre-PR
+- **Additional Requirements**:
+  - Integration testing with existing features
+  - Unit tests for new and affected code
+  - Documentation updates
+- **Focus Areas**:
+  - Integration points validated
+  - Existing patterns followed
+  - Error handling comprehensive
+
+**LOW RISK** (documentation, tests only, isolated bug fix):
+- **Quality Gates**: Pre-Commit
+- **Additional Requirements**:
+  - Standard code review
+  - Basic testing
+- **Focus Areas**:
+  - Code quality standards
+  - Documentation clarity
+
+**CodeRabbit Focus for Brownfield:**
+
+Regardless of story type, ALL brownfield stories must include these focus areas:
+
+```yaml
+🤖 CodeRabbit Integration:
+
+  Story Type Analysis:
+    Primary Type: [Database|API|Frontend|Deployment|Security|Integration]
+    Secondary Type(s): [Additional types]
+    Complexity: [Low|Medium|High]
+    Risk Level: [LOW RISK|MEDIUM RISK|HIGH RISK] ← Brownfield-specific
+    Integration Points: [List of systems/components affected] ← Brownfield-specific
+
+  Specialized Agent Assignment:
+    Primary Agents:
+      - @dev (always required)
+      - @[integration-specific-agent] (based on affected systems)
+
+    Supporting Agents:
+      - @[supporting-agent-1] (if multiple systems)
+      - @[supporting-agent-2] (if cross-cutting concerns)
+
+  Quality Gate Tasks:
+    - [ ] Pre-Commit (@dev): Run `coderabbit --prompt-only -t uncommitted` before story complete
+    - [ ] Pre-PR (@github-devops): Run `coderabbit --prompt-only --base main` before PR creation
+    - [ ] Pre-Deployment (@github-devops): Run `coderabbit --prompt-only -t committed --base HEAD~10` before production deploy (HIGH RISK stories only)
+
+  CodeRabbit Focus Areas:
+    Primary Focus (Brownfield-Specific):
+      - Regression prevention: Existing functionality preserved
+      - Integration safety: New code doesn't break existing code
+      - Rollback readiness: Changes are reversible
+      - [Type-specific focus from detection rules]
+
+    Secondary Focus:
+      - [Type-specific focus areas]
+      - Performance impact: No degradation to existing features
+      - Error handling: Graceful degradation for integration failures
+```
+
+**Brownfield Example (HIGH RISK Database + API Story):**
+
+```yaml
+🤖 CodeRabbit Integration:
+
+  Story Type Analysis:
+    Primary Type: Database
+    Secondary Type(s): API
+    Complexity: High (schema changes + multiple API endpoints)
+    Risk Level: HIGH RISK (affects core payment processing functionality)
+    Integration Points:
+      - Payment service API
+      - Transaction database tables
+      - External payment gateway webhook
+      - User notification system
+
+  Specialized Agent Assignment:
+    Primary Agents:
+      - @dev (pre-commit reviews)
+      - @db-sage (schema changes, RLS policies, existing data migration)
+      - @architect (API contract changes, backward compatibility)
+
+    Supporting Agents:
+      - @github-devops (phased rollout, rollback procedure)
+
+  Quality Gate Tasks:
+    - [ ] Pre-Commit (@dev): Run before story complete
+    - [ ] Pre-PR (@github-devops): Run before PR creation
+    - [ ] Pre-Deployment (@github-devops): Run before production deploy with rollback plan validation
+
+  CodeRabbit Focus Areas:
+    Primary Focus (Brownfield-Specific):
+      - Regression prevention: Existing payment flows MUST work identically
+      - Integration safety: New schema compatible with existing queries
+      - Rollback readiness: Migration reversible without data loss
+      - Service filters on ALL queries (.eq('service', 'ttcx'))
+      - Schema compliance with existing patterns
+
+    Secondary Focus:
+      - API backward compatibility: v1 clients still supported
+      - Performance: No degradation to existing payment processing
+      - Error handling: Graceful fallback for gateway failures
+      - RLS policies: Consistent with existing security model
+      - Migration testing: Validated on copy of production data structure
+```
+
+**Integration-Specific Considerations:**
+
+When story involves specific integration patterns:
+
+**Database Integration:**
+- Focus: Existing data compatibility, migration safety, RLS policy consistency
+- Validation: Run migration on production-like data, verify all existing queries still work
+
+**API Integration:**
+- Focus: Contract versioning, backward compatibility, client impact assessment
+- Validation: Integration tests with existing API clients, contract testing
+
+**Frontend Integration:**
+- Focus: User workflow continuity, design system compliance, accessibility preservation
+- Validation: Visual regression testing, user acceptance testing on existing flows
+
+**External System Integration:**
+- Focus: Graceful degradation, retry logic, error handling, monitoring
+- Validation: Failure scenario testing, circuit breaker validation
+
+**Log Completion:**
+- After populating this section, log: "✅ Brownfield story analysis complete: [Primary Type] | Risk Level: [RISK] | Integration Points: [count] | Agents assigned: [agent list]"
+
+### 5. Risk Assessment and Mitigation
+
+CRITICAL: for brownfield - always include risk assessment
+
+Add section for brownfield-specific risks:
+
+```markdown
+## Risk Assessment
+
+### Implementation Risks
+- **Primary Risk**: {{main risk to existing system}}
+- **Mitigation**: {{how to address}}
+- **Verification**: {{how to confirm safety}}
+
+### Rollback Plan
+- {{Simple steps to undo changes if needed}}
+
+### Safety Checks
+- [ ] Existing {{feature}} tested before changes
+- [ ] Changes can be feature-flagged or isolated
+- [ ] Rollback procedure documented
+```
+
+### 6. Final Story Validation
+
+Before finalizing:
+
+1. **Completeness Check**:
+   - [ ] Story has clear scope and acceptance criteria
+   - [ ] Technical context is sufficient for implementation
+   - [ ] Integration approach is defined
+   - [ ] Risks are identified with mitigation
+
+2. **Safety Check**:
+   - [ ] Existing functionality protection included
+   - [ ] Rollback plan is feasible
+   - [ ] Testing covers both new and existing features
+
+3. **Information Gaps**:
+   - [ ] All critical missing information gathered from user
+   - [ ] Remaining unknowns documented for dev agent
+   - [ ] Exploration tasks added where needed
+
+### 7. Story Output Format
+
+Save the story with appropriate naming:
+
+- If from epic: `docs/stories/epic-{n}-story-{m}.md`
+- If standalone: `docs/stories/brownfield-{feature-name}.md`
+- If sequential: Follow existing story numbering
+
+Include header noting documentation context:
+
+```markdown
+# Story: {{Title}}
+
+<!-- Source: {{documentation type used}} -->
+<!-- Context: Brownfield enhancement to {{existing system}} -->
+
+## Status: Draft
+[Rest of story content...]
+```
+
+### 8. Handoff Communication
+
+Provide clear handoff to the user:
+
+```text
+Brownfield story created: {{story title}}
+
+Source Documentation: {{what was used}}
+Story Location: {{file path}}
+
+Key Integration Points Identified:
+- {{integration point 1}}
+- {{integration point 2}}
+
+Risks Noted:
+- {{primary risk}}
+
+{{If missing info}}: 
+Note: Some technical details were unclear. The story includes exploration tasks to gather needed information during implementation.
+
+Next Steps:
+1. Review story for accuracy
+2. Verify integration approach aligns with your system
+3. Approve story or request adjustments
+4. Dev agent can then implement with safety checks
+```
+
+## Success Criteria
+
+The brownfield story creation is successful when:
+
+1. Story can be implemented without requiring dev to search multiple documents
+2. Integration approach is clear and safe for existing system
+3. All available technical context has been extracted and organized
+4. Missing information has been identified and addressed
+5. Risks are documented with mitigation strategies
+6. Story includes verification of existing functionality
+7. Rollback approach is defined
+
+## Important Notes
+
+- This task is specifically for brownfield projects with non-standard documentation
+- Always prioritize existing system stability over new features
+- When in doubt, add exploration and verification tasks
+- It's better to ask the user for clarification than make assumptions
+- Each story should be self-contained for the dev agent
+- Include references to existing code patterns when available