aios-core 2.1.6 → 2.2.0

package/.aios-core/development/tasks/create-task.md

@@ -1,372 +1,372 @@
----
-
-## 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: createTask()
-responsável: Orion (Commander)
-responsavel_type: Agente
-atomic_layer: Config
-
-**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:** abort
-
-**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: 2-10 min (estimated)
-cost_estimated: $0.001-0.008
-token_usage: ~800-2,500 tokens
-```
-
-**Optimization Notes:**
-- Validate configuration early; use atomic writes; implement rollback checkpoints
-
----
-
-## Metadata
-
-```yaml
-story: N/A
-version: 1.0.0
-dependencies:
-  - N/A
-tags:
-  - creation
-  - setup
-updated_at: 2025-11-17
-```
-
----
-
-tools:
-  - github-cli
-# TODO: Create task-validation-checklist.md for validation (follow-up story needed)
-# checklists:
-#   - task-validation-checklist.md
----
-
-# Create Task
-
-## Purpose
-To create a new task file that defines executable workflows for agents, with proper structure, elicitation steps, and validation.
-
-## Prerequisites
-- User authorization verified
-- Task purpose clearly defined
-- Understanding of task workflow requirements
-
-## Interactive Elicitation Process
-
-### Step 1: Task Definition
-```
-ELICIT: Task Basic Information
-
-1. What agent(s) will use this task?
-   Examples: "ux-design-expert", "db-sage", "dev", "pm, po, sm" (multiple)
-
-   → If SINGLE agent: Task is agent-specific (will apply naming convention)
-   → If MULTIPLE agents: Task is shared (no prefix)
-
-2. What is the task name?
-
-   IF agent-specific (single agent):
-     → Suggested format: "{agent-id}-{action}"
-     → Examples: "ux-user-research", "db-apply-migration", "dev-develop-story"
-     → Validation: Must start with "{agent-id}-"
-
-   IF shared (multiple agents):
-     → Use descriptive name WITHOUT agent prefix
-     → Examples: "create-doc", "execute-checklist", "manage-story-backlog"
-     → Validation: Must NOT have agent-specific prefix
-
-3. What is the primary purpose of this task?
-
-4. What are the prerequisites for running this task?
-```
-
-**NAMING CONVENTION (CRITICAL):**
-- Agent-specific tasks: `{agent-id}-{task-name}.md`
-- Shared tasks: `{task-name}.md` (no prefix)
-- Use component-generator.applyNamingConvention() to apply automatically
-
-### Step 2: Task Workflow
-```
-ELICIT: Task Workflow Steps
-1. Does this task require user interaction? (yes/no)
-2. What are the main steps in this task? (numbered list)
-3. What inputs does the task need?
-4. What outputs does the task produce?
-5. Are there decision points requiring user input?
-```
-
-### Step 3: Elicitation Requirements
-```
-ELICIT: Interactive Elements (if applicable)
-1. What information needs to be collected from users?
-2. How should prompts be structured?
-3. What validation is needed for user inputs?
-4. Are there default values or suggestions?
-```
-
-### Step 4: Dependencies and Integration
-```
-ELICIT: Task Dependencies
-1. Does this task depend on other tasks?
-2. What templates does it use (if any)?
-3. Does it need memory layer access?
-4. What files/resources does it need to access?
-```
-
-## Implementation Steps
-
-1. **Validate Task Name**
-   - Check name doesn't already exist
-   - Validate format (lowercase, hyphens)
-   - Ensure descriptive and clear naming
-
-2. **Structure Task Content**
-   ```markdown
-   # {Task Title}
-   
-   ## Purpose
-   {Clear description of what the task accomplishes}
-   
-   ## Prerequisites
-   {List of requirements before task execution}
-   
-   ## Interactive Elicitation Process
-   {If elicit=true, define all prompts and user interactions}
-   
-   ## Implementation Steps
-   {Numbered steps for task execution}
-   
-   ## Validation Checklist
-   {Checklist items to verify task completion}
-   
-   ## Error Handling
-   {How to handle common errors}
-   
-   ## Success Output
-   {What user sees on successful completion}
-   ```
-
-3. **Add Security Considerations**
-   - Input validation rules
-   - File access restrictions
-   - Safe command execution
-   - Output sanitization
-
-4. **Create Task File**
-   - Generate path: `.aios-core/tasks/{task-name}.md`
-   - Write formatted task definition
-   - Ensure proper markdown structure
-
-5. **Update Memory Layer**
-   ```javascript
-   await memoryClient.addMemory({
-     type: 'task_created',
-     name: taskName,
-     path: taskPath,
-     creator: currentUser,
-     timestamp: new Date().toISOString(),
-     metadata: {
-       purpose: taskPurpose,
-       agents: associatedAgents,
-       interactive: hasElicitation
-     }
-   });
-   ```
-
-6. **Generate Usage Examples**
-   - Show how to reference in agent files
-   - Provide command examples
-   - Document expected outputs
-
-## Validation Checklist
-- [ ] Task name is unique and valid
-- [ ] Purpose clearly stated
-- [ ] Steps are numbered and clear
-- [ ] Elicitation prompts well-defined
-- [ ] Error handling included
-- [ ] Success criteria defined
-- [ ] Memory layer updated
-
-## Error Handling
-- If task exists: Offer to update or create variant
-- If validation fails: Show specific issues
-- If dependencies missing: List required files
-- If write fails: Check permissions
-
-## Success Output
-```
-✅ Task '{task-name}' created successfully!
-📁 Location: .aios-core/tasks/{task-name}.md
-📝 Integration example:
-   dependencies:
-     tasks:
-       - {task-name}.md
-🔗 Agents using this task: {agent-list}
+---
+
+## 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: createTask()
+responsável: Orion (Commander)
+responsavel_type: Agente
+atomic_layer: Config
+
+**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:** abort
+
+**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: 2-10 min (estimated)
+cost_estimated: $0.001-0.008
+token_usage: ~800-2,500 tokens
+```
+
+**Optimization Notes:**
+- Validate configuration early; use atomic writes; implement rollback checkpoints
+
+---
+
+## Metadata
+
+```yaml
+story: N/A
+version: 1.0.0
+dependencies:
+  - N/A
+tags:
+  - creation
+  - setup
+updated_at: 2025-11-17
+```
+
+---
+
+tools:
+  - github-cli
+# TODO: Create task-validation-checklist.md for validation (follow-up story needed)
+# checklists:
+#   - task-validation-checklist.md
+---
+
+# Create Task
+
+## Purpose
+To create a new task file that defines executable workflows for agents, with proper structure, elicitation steps, and validation.
+
+## Prerequisites
+- User authorization verified
+- Task purpose clearly defined
+- Understanding of task workflow requirements
+
+## Interactive Elicitation Process
+
+### Step 1: Task Definition
+```
+ELICIT: Task Basic Information
+
+1. What agent(s) will use this task?
+   Examples: "ux-design-expert", "db-sage", "dev", "pm, po, sm" (multiple)
+
+   → If SINGLE agent: Task is agent-specific (will apply naming convention)
+   → If MULTIPLE agents: Task is shared (no prefix)
+
+2. What is the task name?
+
+   IF agent-specific (single agent):
+     → Suggested format: "{agent-id}-{action}"
+     → Examples: "ux-user-research", "db-apply-migration", "dev-develop-story"
+     → Validation: Must start with "{agent-id}-"
+
+   IF shared (multiple agents):
+     → Use descriptive name WITHOUT agent prefix
+     → Examples: "create-doc", "execute-checklist", "manage-story-backlog"
+     → Validation: Must NOT have agent-specific prefix
+
+3. What is the primary purpose of this task?
+
+4. What are the prerequisites for running this task?
+```
+
+**NAMING CONVENTION (CRITICAL):**
+- Agent-specific tasks: `{agent-id}-{task-name}.md`
+- Shared tasks: `{task-name}.md` (no prefix)
+- Use component-generator.applyNamingConvention() to apply automatically
+
+### Step 2: Task Workflow
+```
+ELICIT: Task Workflow Steps
+1. Does this task require user interaction? (yes/no)
+2. What are the main steps in this task? (numbered list)
+3. What inputs does the task need?
+4. What outputs does the task produce?
+5. Are there decision points requiring user input?
+```
+
+### Step 3: Elicitation Requirements
+```
+ELICIT: Interactive Elements (if applicable)
+1. What information needs to be collected from users?
+2. How should prompts be structured?
+3. What validation is needed for user inputs?
+4. Are there default values or suggestions?
+```
+
+### Step 4: Dependencies and Integration
+```
+ELICIT: Task Dependencies
+1. Does this task depend on other tasks?
+2. What templates does it use (if any)?
+3. Does it need memory layer access?
+4. What files/resources does it need to access?
+```
+
+## Implementation Steps
+
+1. **Validate Task Name**
+   - Check name doesn't already exist
+   - Validate format (lowercase, hyphens)
+   - Ensure descriptive and clear naming
+
+2. **Structure Task Content**
+   ```markdown
+   # {Task Title}
+   
+   ## Purpose
+   {Clear description of what the task accomplishes}
+   
+   ## Prerequisites
+   {List of requirements before task execution}
+   
+   ## Interactive Elicitation Process
+   {If elicit=true, define all prompts and user interactions}
+   
+   ## Implementation Steps
+   {Numbered steps for task execution}
+   
+   ## Validation Checklist
+   {Checklist items to verify task completion}
+   
+   ## Error Handling
+   {How to handle common errors}
+   
+   ## Success Output
+   {What user sees on successful completion}
+   ```
+
+3. **Add Security Considerations**
+   - Input validation rules
+   - File access restrictions
+   - Safe command execution
+   - Output sanitization
+
+4. **Create Task File**
+   - Generate path: `.aios-core/tasks/{task-name}.md`
+   - Write formatted task definition
+   - Ensure proper markdown structure
+
+5. **Update Memory Layer**
+   ```javascript
+   await memoryClient.addMemory({
+     type: 'task_created',
+     name: taskName,
+     path: taskPath,
+     creator: currentUser,
+     timestamp: new Date().toISOString(),
+     metadata: {
+       purpose: taskPurpose,
+       agents: associatedAgents,
+       interactive: hasElicitation
+     }
+   });
+   ```
+
+6. **Generate Usage Examples**
+   - Show how to reference in agent files
+   - Provide command examples
+   - Document expected outputs
+
+## Validation Checklist
+- [ ] Task name is unique and valid
+- [ ] Purpose clearly stated
+- [ ] Steps are numbered and clear
+- [ ] Elicitation prompts well-defined
+- [ ] Error handling included
+- [ ] Success criteria defined
+- [ ] Memory layer updated
+
+## Error Handling
+- If task exists: Offer to update or create variant
+- If validation fails: Show specific issues
+- If dependencies missing: List required files
+- If write fails: Check permissions
+
+## Success Output
+```
+✅ Task '{task-name}' created successfully!
+📁 Location: .aios-core/tasks/{task-name}.md
+📝 Integration example:
+   dependencies:
+     tasks:
+       - {task-name}.md
+🔗 Agents using this task: {agent-list}
 ```