aios-core 2.1.0

package/.aios-core/development/tasks/po-sync-story-to-clickup.md

@@ -0,0 +1,457 @@
+---
+tools:
+  - clickup  # Required for ClickUp synchronization
+checklists:
+  - po-master-checklist.md
+---
+
+# sync-story-to-clickup
+
+**Purpose:** Manually force synchronization of a local story file to ClickUp. Use this when you've edited a story file directly (via Edit tool) and need to ensure changes are reflected in ClickUp.
+
+**When to Use:**
+- After making changes to story file that didn't automatically sync
+- When you want to force-push current story state to ClickUp
+- After manual edits that bypassed story-manager utilities
+- When sync seems out of date (check frontmatter last_sync timestamp)
+
+## 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: poSyncStoryToClickup()
+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 Inputs
+
+```yaml
+required:
+  - story_id: '{epic}.{story}' # e.g., "99.2" or "5.2.2"
+
+optional:
+  - force: false # If true, sync even if no changes detected
+```
+
+## Prerequisites
+
+- Story file must exist in `docs/stories/`
+- Story must have ClickUp metadata in frontmatter (clickup.task_id)
+- ClickUp MCP tool must be available and authenticated
+
+## Task Execution Steps
+
+### Step 1: Locate Story File
+
+- Find story file in `docs/stories/` matching story_id pattern
+- Expected format: `{epic}.{story}.*.md`
+- If multiple files found, show list and ask user to clarify
+- If no file found, ERROR and exit
+
+### Step 2: Parse Story File
+
+- Read current story file content
+- Extract frontmatter with YAML parser
+- Verify `clickup.task_id` exists in frontmatter
+- If task_id missing:
+  - ERROR: "Story has no ClickUp integration metadata"
+  - Suggest: Check if story was created via ClickUp workflow
+  - EXIT task
+
+### Step 3: Prepare Sync Data
+
+Extract from story file:
+- Full markdown content (for description update)
+- Current status from frontmatter
+- Tasks/checkboxes (for change detection)
+- File List section
+- Dev Notes section
+- Acceptance Criteria section
+
+### Step 4: Sync to ClickUp
+
+**CRITICAL:** Use the story-manager module for proper sync
+
+```javascript
+const { saveStoryFile } = require('../../common/scripts/story-manager');
+
+// Read current content
+const currentContent = await fs.readFile(storyFilePath, 'utf-8');
+
+// Force sync by re-saving with skipSync=false
+await saveStoryFile(storyFilePath, currentContent, false);
+```
+
+**What This Does:**
+1. Detects changes between previous and current content
+2. Updates ClickUp task description with full markdown
+3. Updates story-status custom field if status changed
+4. Adds changelog comment if tasks completed or files added
+5. Updates last_sync timestamp in frontmatter
+
+### Step 5: Verify Sync Success
+
+- Check that last_sync timestamp was updated in frontmatter
+- Log sync results:
+  - Status changes detected
+  - Number of tasks completed
+  - Files added
+  - Other changes synced
+
+### Step 6: Output Results
+
+Display formatted summary:
+
+```markdown
+✅ Story {story_id} synchronized to ClickUp
+
+**Task ID:** {task_id}
+**Task URL:** {url}
+**Last Sync:** {timestamp}
+
+**Changes Synced:**
+- Status: {old_status} → {new_status} (if changed)
+- Tasks completed: {count}
+- Files added: {count}
+- Dev Notes updated: {yes/no}
+- Acceptance Criteria updated: {yes/no}
+
+**ClickUp Updates:**
+- Task description updated with full story markdown
+- story-status custom field updated
+- Changelog comment added to task
+```
+
+## Error Handling
+
+**Error: Story file not found**
+```
+❌ Story file not found for ID: {story_id}
+
+Please check:
+- Story ID format correct? (e.g., "99.2" not "Story 99.2")
+- Story file exists in docs/stories/?
+- File naming follows pattern: {epic}.{story}.*.md
+```
+
+**Error: No ClickUp metadata**
+```
+❌ Story has no ClickUp integration
+
+This story was not created via ClickUp workflow and has no task_id.
+
+To integrate with ClickUp:
+1. Create ClickUp task manually in Backlog list
+2. Add frontmatter metadata:
+   clickup:
+     task_id: "your-task-id"
+     epic_task_id: "parent-epic-id"
+     list: "Backlog"
+     url: "https://app.clickup.com/t/task-id"
+```
+
+**Error: ClickUp API failure**
+```
+❌ Failed to sync to ClickUp: {error_message}
+
+Please check:
+- ClickUp MCP tool is authenticated
+- Task ID is valid and accessible
+- Network connection is stable
+- ClickUp API is operational
+
+You can verify task manually at:
+{task_url}
+```
+
+**Error: No changes detected (with force=false)**
+```
+ℹ️  No changes detected - sync not needed
+
+Story is already synchronized with ClickUp.
+Last sync: {timestamp}
+
+Use force=true to sync anyway:
+*sync-story {story_id} --force
+```
+
+## Usage Examples
+
+### Basic Sync
+```
+*sync-story 99.2
+```
+
+### Force Sync (even if no changes)
+```
+*sync-story 5.2.2 --force
+```
+
+### After Manual Edits
+```
+# Scenario: You used Edit tool to update story file
+1. Edit story file with changes
+2. Run: *sync-story {story_id}
+3. Verify sync success message
+4. Check ClickUp UI to confirm updates
+```
+
+## Integration Notes
+
+**For PO Agent:**
+- Add to po.md commands: `sync-story {story}`: Force sync story to ClickUp
+- Use after manual story edits or when validation updates story
+
+**For Dev Agent:**
+- Add to dev.md commands: `sync-story {story}`: Force sync story to ClickUp
+- Use after marking tasks complete or updating File List
+
+**For QA Agent:**
+- Add to qa.md commands: `sync-story {story}`: Force sync story to ClickUp
+- Use after adding QA Results section
+
+**Best Practice:**
+- Agents should use story-manager utilities when possible (automatic sync)
+- Use this task only when direct file edits were made
+- Check last_sync timestamp to verify sync freshness
+
+## Technical Implementation
+
+**Dependencies:**
+- `common/scripts/story-manager.js` - saveStoryFile function
+- `common/scripts/story-update-hook.js` - detectChanges, syncStoryToClickUp
+- `common/scripts/clickup-helpers.js` - ClickUp API wrappers
+- ClickUp MCP tool (via global.mcp__clickup__* or tool-resolver)
+
+**Process Flow:**
+```
+Task invoked
+    ↓
+Read story file
+    ↓
+Parse frontmatter for task_id
+    ↓
+Call story-manager.saveStoryFile()
+    ↓
+    ├─ detectChanges() identifies diffs
+    ├─ syncStoryToClickUp() orchestrates updates
+    ├─ updateTaskDescription() if AC/content changed
+    ├─ updateStoryStatus() if status changed
+    └─ addTaskComment() with changelog
+    ↓
+Update last_sync timestamp
+    ↓
+Return sync results
+```
+
+## Testing This Task
+
+**Manual Test:**
+1. Edit Story 99.2 directly (mark a checkbox)
+2. Note current last_sync timestamp
+3. Run: `*sync-story 99.2`
+4. Verify:
+   - last_sync timestamp updated
+   - ClickUp task shows changelog comment
+   - Checkbox change reflected in ClickUp
+   - Task description updated
+
+**Automated Test:** `tests/tasks/sync-story-to-clickup.test.js`
+
+---
+
+*Task created to provide manual sync control for ClickUp integration*