create-genia-os 2.4.0 → 3.0.0

package/template/.aiox-core/development/tasks/brownfield-create-story.md

@@ -0,0 +1,364 @@
+---
+
+## 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 (AIOX Task Format V1.0)
+
+```yaml
+task: brownfieldCreateStory()
+responsável: Pax (Balancer)
+responsavel_type: Agente
+atomic_layer: Organism
+
+**Entrada:**
+- campo: task
+  tipo: string
+  origem: User Input
+  obrigatório: true
+  validação: Must be registered task
+
+- campo: parameters
+  tipo: object
+  origem: User Input
+  obrigatório: false
+  validação: Valid task parameters
+
+- campo: mode
+  tipo: string
+  origem: User Input
+  obrigatório: false
+  validação: yolo|interactive|pre-flight
+
+**Saída:**
+- campo: execution_result
+  tipo: object
+  destino: Memory
+  persistido: false
+
+- campo: logs
+  tipo: array
+  destino: File (.ai/logs/*)
+  persistido: true
+
+- campo: state
+  tipo: object
+  destino: State management
+  persistido: true
+```
+
+---
+
+## Pre-Conditions
+
+**Purpose:** Validate prerequisites BEFORE task execution (blocking)
+
+**Checklist:**
+
+```yaml
+pre-conditions:
+  - [ ] Task is registered; required parameters provided; dependencies met
+    tipo: pre-condition
+    blocker: true
+    validação: |
+      Check task is registered; required parameters provided; dependencies met
+    error_message: "Pre-condition failed: Task is registered; required parameters provided; dependencies met"
+```
+
+---
+
+## Post-Conditions
+
+**Purpose:** Validate execution success AFTER task completes
+
+**Checklist:**
+
+```yaml
+post-conditions:
+  - [ ] Task completed; exit code 0; expected outputs created
+    tipo: post-condition
+    blocker: true
+    validação: |
+      Verify task completed; exit code 0; expected outputs created
+    error_message: "Post-condition failed: Task completed; exit code 0; expected outputs created"
+```
+
+---
+
+## Acceptance Criteria
+
+**Purpose:** Definitive pass/fail criteria for task completion
+
+**Checklist:**
+
+```yaml
+acceptance-criteria:
+  - [ ] Task completed as expected; side effects documented
+    tipo: acceptance-criterion
+    blocker: true
+    validação: |
+      Assert task completed as expected; side effects documented
+    error_message: "Acceptance criterion not met: Task completed as expected; side effects documented"
+```
+
+---
+
+## Tools
+
+**External/shared resources used by this task:**
+
+- **Tool:** task-runner
+  - **Purpose:** Task execution and orchestration
+  - **Source:** .aiox-core/core/task-runner.js
+
+- **Tool:** logger
+  - **Purpose:** Execution logging and error tracking
+  - **Source:** .aiox-core/utils/logger.js
+
+---
+
+## Scripts
+
+**Agent-specific code for this task:**
+
+- **Script:** execute-task.js
+  - **Purpose:** Generic task execution wrapper
+  - **Language:** JavaScript
+  - **Location:** .aiox-core/scripts/execute-task.js
+
+---
+
+## Error Handling
+
+**Strategy:** retry
+
+**Common Errors:**
+
+1. **Error:** Task Not Found
+   - **Cause:** Specified task not registered in system
+   - **Resolution:** Verify task name and registration
+   - **Recovery:** List available tasks, suggest similar
+
+2. **Error:** Invalid Parameters
+   - **Cause:** Task parameters do not match expected schema
+   - **Resolution:** Validate parameters against task definition
+   - **Recovery:** Provide parameter template, reject execution
+
+3. **Error:** Execution Timeout
+   - **Cause:** Task exceeds maximum execution time
+   - **Resolution:** Optimize task or increase timeout
+   - **Recovery:** Kill task, cleanup resources, log state
+
+---
+
+## 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 a single user story for very small brownfield enhancements that can be completed in one focused development session. This task is for minimal additions or bug fixes that require existing system integration awareness.
+
+## When to Use This Task
+
+**Use this task when:**
+
+- The enhancement can be completed in a single story
+- No new architecture or significant design is required
+- The change follows existing patterns exactly
+- Integration is straightforward with minimal risk
+- Change is isolated with clear boundaries
+
+**Use brownfield-create-epic when:**
+
+- The enhancement requires 2-3 coordinated stories
+- Some design work is needed
+- Multiple integration points are involved
+
+**Use the full brownfield PRD/Architecture process when:**
+
+- The enhancement requires multiple coordinated stories
+- Architectural planning is needed
+- Significant integration work is required
+
+## Instructions
+
+### 1. Quick Project Assessment
+
+Gather minimal but essential context about the existing project:
+
+**Current System Context:**
+
+- [ ] Relevant existing functionality identified
+- [ ] Technology stack for this area noted
+- [ ] Integration point(s) clearly understood
+- [ ] Existing patterns for similar work identified
+
+**Change Scope:**
+
+- [ ] Specific change clearly defined
+- [ ] Impact boundaries identified
+- [ ] Success criteria established
+
+### 2. Story Creation
+
+Create a single focused story following this structure:
+
+#### Story Title
+
+{{Specific Enhancement}} - Brownfield Addition
+
+#### User Story
+
+As a {{user type}},
+I want {{specific action/capability}},
+So that {{clear benefit/value}}.
+
+#### Story Context
+
+**Existing System Integration:**
+
+- Integrates with: {{existing component/system}}
+- Technology: {{relevant tech stack}}
+- Follows pattern: {{existing pattern to follow}}
+- Touch points: {{specific integration points}}
+
+#### Acceptance Criteria
+
+**Functional Requirements:**
+
+1. {{Primary functional requirement}}
+2. {{Secondary functional requirement (if any)}}
+3. {{Integration requirement}}
+
+**Integration Requirements:** 4. Existing {{relevant functionality}} continues to work unchanged 5. New functionality follows existing {{pattern}} pattern 6. Integration with {{system/component}} maintains current behavior
+
+**Quality Requirements:** 7. Change is covered by appropriate tests 8. Documentation is updated if needed 9. No regression in existing functionality verified
+
+#### Technical Notes
+
+- **Integration Approach:** {{how it connects to existing system}}
+- **Existing Pattern Reference:** {{link or description of pattern to follow}}
+- **Key Constraints:** {{any important limitations or requirements}}
+
+#### Definition of Done
+
+- [ ] Functional requirements met
+- [ ] Integration requirements verified
+- [ ] Existing functionality regression tested
+- [ ] Code follows existing patterns and standards
+- [ ] Tests pass (existing and new)
+- [ ] Documentation updated if applicable
+
+### 3. Risk and Compatibility Check
+
+**Minimal Risk Assessment:**
+
+- **Primary Risk:** {{main risk to existing system}}
+- **Mitigation:** {{simple mitigation approach}}
+- **Rollback:** {{how to undo if needed}}
+
+**Compatibility Verification:**
+
+- [ ] No breaking changes to existing APIs
+- [ ] Database changes (if any) are additive only
+- [ ] UI changes follow existing design patterns
+- [ ] Performance impact is negligible
+
+### 4. Validation Checklist
+
+Before finalizing the story, confirm:
+
+**Scope Validation:**
+
+- [ ] Story can be completed in one development session
+- [ ] Integration approach is straightforward
+- [ ] Follows existing patterns exactly
+- [ ] No design or architecture work required
+
+**Clarity Check:**
+
+- [ ] Story requirements are unambiguous
+- [ ] Integration points are clearly specified
+- [ ] Success criteria are testable
+- [ ] Rollback approach is simple
+
+## Success Criteria
+
+The story creation is successful when:
+
+1. Enhancement is clearly defined and appropriately scoped for single session
+2. Integration approach is straightforward and low-risk
+3. Existing system patterns are identified and will be followed
+4. Rollback plan is simple and feasible
+5. Acceptance criteria include existing functionality verification
+
+## Important Notes
+
+- This task is for VERY SMALL brownfield changes only
+- If complexity grows during analysis, escalate to brownfield-create-epic
+- Always prioritize existing system integrity
+- When in doubt about integration complexity, use brownfield-create-epic instead
+- Stories should take no more than 4 hours of focused development work
+
+## Handoff
+next_agent: @po
+next_command: *validate-story-draft {story-id}
+condition: Brownfield story created from assessment
+alternatives:
+  - agent: @sm, command: *draft, condition: Need additional stories from same assessment
+ 

package/template/.aiox-core/development/tasks/build-autonomous.md

@@ -0,0 +1,199 @@
+# Task: Build Autonomous
+
+> **Command:** `*build-autonomous {story-id}`
+> **Agent:** @dev
+> **Story:** 8.1 - Coder Agent Loop
+> **AC:** AC5
+
+---
+
+## Purpose
+
+Start an autonomous build loop for a story, executing subtasks with automatic retries and self-critique.
+
+This implements the **Coder Agent Loop** pattern from Auto-Claude, providing:
+
+- Automatic retry on failure (max 3 attempts per subtask)
+- Self-critique at implementation milestones
+- Global timeout protection (configurable)
+- Event-driven progress tracking
+- Checkpoint-based recovery integration
+
+---
+
+## Usage
+
+```bash
+*build-autonomous {story-id}
+*build-autonomous {story-id} --worktree    # Use worktree isolation
+*build-autonomous {story-id} --timeout=60  # Set global timeout (minutes)
+```
+
+### Arguments
+
+| Argument | Required | Description                          |
+| -------- | -------- | ------------------------------------ |
+| story-id | Yes      | Story identifier (e.g., "story-8.1") |
+
+### Options
+
+| Option        | Default | Description                  |
+| ------------- | ------- | ---------------------------- |
+| --worktree    | false   | Execute in isolated worktree |
+| --timeout     | 30      | Global timeout in minutes    |
+| --max-retries | 3       | Maximum retries per subtask  |
+
+---
+
+## Workflow
+
+```yaml
+steps:
+  - name: Initialize Build
+    action: |
+      1. Load story file from docs/stories/
+      2. Load implementation plan from plan/implementation.yaml
+      3. Initialize BuildStateManager
+      4. Create build state with status "in_progress"
+    validates:
+      - Story exists and is approved
+      - Implementation plan exists
+      - No conflicting build in progress
+
+  - name: Setup Worktree (if --worktree)
+    action: |
+      1. Create isolated worktree for story
+      2. Set worktree path in build state
+    skip_if: worktree option is false
+
+  - name: Execute Build Loop
+    action: |
+      FOR EACH subtask in implementation.yaml:
+        1. Track attempt start (RecoveryTracker)
+        2. **Code Intelligence IDS G4 Check** (before creating new files):
+           - If `isCodeIntelAvailable()` (from `.aiox-core/core/code-intel`):
+             - Call `checkBeforeWriting(fileName, description)` from `dev-helper`
+             - If duplicates detected: log in decision-log and display as advisory
+             - Does NOT block execution (autonomous mode continues)
+           - If code intelligence not available: skip silently
+        3. Execute subtask (plan-execute-subtask.md workflow)
+        4. Self-critique at steps 5.5 and 6.5
+        5. Verify completion (verify-subtask.md workflow)
+        6. Create checkpoint on success
+
+        IF failure:
+          - Increment attempt count
+          - IF attempts < maxRetries: retry
+          - ELSE: mark as failed, continue or halt
+
+        IF global timeout exceeded:
+          - Mark build as "timed_out"
+          - Save state for resume
+          - HALT
+    outputs:
+      - completedSubtasks
+      - failedSubtasks
+      - totalDuration
+
+  - name: Finalize Build
+    action: |
+      1. Update build state to "completed" or "failed"
+      2. Generate build report
+      3. Update story status
+      4. Cleanup worktree (if used)
+```
+
+---
+
+## Events Emitted
+
+The AutonomousBuildLoop emits these events for monitoring:
+
+| Event              | Payload                       | Description                   |
+| ------------------ | ----------------------------- | ----------------------------- |
+| BUILD_STARTED      | storyId, totalSubtasks        | Build initialization complete |
+| SUBTASK_STARTED    | subtaskId, phase, attempt     | Subtask execution beginning   |
+| SUBTASK_COMPLETED  | subtaskId, duration           | Subtask finished successfully |
+| SUBTASK_FAILED     | subtaskId, error, willRetry   | Subtask execution failed      |
+| CHECKPOINT_CREATED | checkpointId, subtaskId       | Recovery checkpoint saved     |
+| BUILD_SUCCESS      | storyId, duration, stats      | All subtasks completed        |
+| BUILD_FAILED       | storyId, error, failedSubtask | Build halted due to failure   |
+| BUILD_TIMEOUT      | storyId, elapsed, lastSubtask | Global timeout exceeded       |
+
+---
+
+## Output Example
+
+```
+🚀 Starting autonomous build for story-8.1
+
+📋 Plan loaded: 12 subtasks
+⏱️  Global timeout: 30 minutes
+🔄 Max retries: 3
+
+[1/12] Executing: Create component structure
+  ✓ Implemented (attempt 1)
+  ✓ Self-critique passed
+  ✓ Verified
+  📌 Checkpoint: cp-1706500000-abc123
+
+[2/12] Executing: Add state management
+  ✗ Failed (attempt 1): Type error in reducer
+  ✓ Implemented (attempt 2)
+  ✓ Self-critique passed
+  ✓ Verified
+  📌 Checkpoint: cp-1706500060-def456
+
+...
+
+✅ Build completed successfully!
+   Duration: 18m 32s
+   Subtasks: 12/12 completed
+   Retries: 2 total
+```
+
+---
+
+## Error Handling
+
+| Error                 | Resolution                                     |
+| --------------------- | ---------------------------------------------- |
+| Story not found       | Verify story-id and file path                  |
+| Plan not found        | Run spec pipeline first to generate plan       |
+| Build already running | Wait for completion or use \*build-status      |
+| Max retries exceeded  | Review error, fix manually, use \*build-resume |
+| Global timeout        | Use \*build-resume to continue                 |
+
+---
+
+## Integration
+
+- **Uses:**
+  - `AutonomousBuildLoop` from `core/execution/autonomous-build-loop.js`
+  - `BuildStateManager` from `core/execution/build-state-manager.js`
+  - `RecoveryTracker` from `infrastructure/scripts/recovery-tracker.js`
+- **Tasks:**
+  - `plan-execute-subtask.md` - Subtask execution workflow
+  - `verify-subtask.md` - Completion verification
+- **Checklists:**
+  - `self-critique-checklist.md` - Steps 5.5 and 6.5
+
+---
+
+## Related Commands
+
+- `*build-resume {story-id}` - Resume from checkpoint
+- `*build-status {story-id}` - Check build progress
+- `*build-log {story-id}` - View attempt history
+- `*build-cleanup` - Remove abandoned builds
+
+---
+
+_Task file for Story 8.1 - Coder Agent Loop_
+
+## Handoff
+next_agent: @qa
+next_command: *review {story-id}
+condition: Autonomous build completed successfully
+alternatives:
+  - agent: @dev, command: *build-resume {story-id}, condition: Build failed, needs resume