aios-core 2.1.0

package/.aios-core/development/tasks/po-backlog-add.md

@@ -0,0 +1,370 @@
+# PO Task: Add Backlog Item
+
+**Agent:** @po
+**Command:** `*backlog-add`
+**Purpose:** Add item to story backlog (follow-up, technical debt, or enhancement)
+**Created:** 2025-01-16 (Story 6.1.2.6)
+
+---
+
+## 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: poBacklogAdd()
+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:** .aios-core/core/task-runner.js
+
+- **Tool:** logger
+  - **Purpose:** Execution logging and error tracking
+  - **Source:** .aios-core/utils/logger.js
+
+---
+
+## Scripts
+
+**Agent-specific code for this task:**
+
+- **Script:** execute-task.js
+  - **Purpose:** Generic task execution wrapper
+  - **Language:** JavaScript
+  - **Location:** .aios-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:
+  - product-management
+  - planning
+updated_at: 2025-11-17
+```
+
+---
+
+
+## Task Flow
+
+### 1. Elicit Item Details
+```yaml
+elicit: true
+questions:
+  - Type of item?
+    options:
+      - F: Follow-up (📌) - Post-story action item
+      - T: Technical Debt (🔧) - Code quality or architecture improvement
+      - E: Enhancement (✨) - Feature improvement or optimization
+
+  - Title (1-line description):
+    input: text
+    validation: min 10 chars, max 100 chars
+
+  - Detailed Description (optional):
+    input: textarea
+    validation: max 500 chars
+
+  - Priority:
+    options:
+      - Critical (🔴)
+      - High (🟠)
+      - Medium (🟡)
+      - Low (🟢)
+    default: Medium
+
+  - Related Story ID (optional):
+    input: text
+    example: "6.1.2.6"
+    validation: story file must exist if provided
+
+  - Tags (optional, comma-separated):
+    input: text
+    example: "testing, performance, security"
+
+  - Estimated Effort (optional):
+    input: text
+    example: "2 hours", "1 day", "1 week"
+    default: "TBD"
+```
+
+### 2. Validate Input
+```javascript
+// Validate story exists if relatedStory provided
+if (relatedStory) {
+  const storyPath = `docs/stories/**/*${relatedStory}*.md`;
+  const matches = await glob(storyPath);
+
+  if (matches.length === 0) {
+    throw new Error(`Story not found: ${relatedStory}`);
+  }
+
+  if (matches.length > 1) {
+    console.log('⚠️ Multiple stories matched, using first:');
+    matches.forEach(m => console.log(`  - ${m}`));
+  }
+}
+
+// Parse tags
+const tags = tagsInput ? tagsInput.split(',').map(t => t.trim()) : [];
+```
+
+### 3. Add Item to Backlog
+```javascript
+const { BacklogManager } = require('.aios-core/scripts/backlog-manager');
+
+const manager = new BacklogManager('docs/stories/backlog.md');
+await manager.load();
+
+const item = await manager.addItem({
+  type: itemType,
+  title: title,
+  description: description || '',
+  priority: priority,
+  relatedStory: relatedStory || null,
+  createdBy: '@po',
+  tags: tags,
+  estimatedEffort: estimatedEffort
+});
+
+console.log(`✅ Backlog item added: ${item.id}`);
+console.log(`   Type: ${itemType} | Priority: ${priority}`);
+console.log(`   ${title}`);
+```
+
+### 4. Regenerate Backlog File
+```javascript
+await manager.generateBacklogFile();
+
+console.log('✅ Backlog updated: docs/stories/backlog.md');
+```
+
+### 5. Summary Output
+```markdown
+## 🎯 Backlog Item Added
+
+**ID:** ${item.id}
+**Type:** ${itemTypeEmoji} ${itemTypeName}
+**Title:** ${title}
+**Priority:** ${priorityEmoji} ${priority}
+**Related Story:** ${relatedStory || 'None'}
+**Estimated Effort:** ${estimatedEffort}
+**Tags:** ${tags.join(', ') || 'None'}
+
+**Next Steps:**
+- Review in backlog: docs/stories/backlog.md
+- Prioritize with `*backlog-prioritize ${item.id}`
+- Schedule with `*backlog-schedule ${item.id}`
+```
+
+---
+
+## Example Usage
+
+```bash
+# Interactive mode (recommended)
+*backlog-add
+
+# Example responses:
+Type: F
+Title: Add integration tests for story index generator
+Description: Story 6.1.2.6 implementation needs integration tests
+Priority: High
+Related Story: 6.1.2.6
+Tags: testing, integration, story-6.1.2.6
+Effort: 3 hours
+```
+
+---
+
+## Error Handling
+
+- **Story not found:** Warn user, allow to proceed without related story
+- **Invalid type:** Show valid options (F, T, E)
+- **Invalid priority:** Default to Medium
+- **Backlog file locked:** Retry 3x with 1s delay
+
+---
+
+## Testing
+
+```bash
+# Test with sample data
+*backlog-add
+# Fill in sample data and verify:
+# - Item added to docs/stories/backlog.json
+# - Backlog file regenerated at docs/stories/backlog.md
+# - Item appears in correct section by type
+# - Priority sorting works
+```
+
+---
+
+**Related Tasks:**
+- `po-stories-index.md` - Regenerate story index
+- `po-backlog-review.md` - Review and prioritize backlog
+- `po-backlog-schedule.md` - Schedule backlog items