@forloop-cc/forloop-opencode-plugin-planner 2.2.1

package/docs/SKILLS-GAP-ANALYSIS.md

@@ -0,0 +1,157 @@
+# Skills Gap Analysis & Improvements
+
+## Current State Analysis
+
+### ✅ What Skills Document Well
+
+| Skill | Documented Workflow | Status |
+|-------|-------------------|--------|
+| `forloop-context` | Session startup, S3 sync (Step 7) | ✅ Documented |
+| `task-tracking` | Create stories → Write task.md → Upload S3 with doc_folder | ✅ Documented |
+| `plan-documentation` | Create plan → Upload S3 with doc_folder | ✅ Documented |
+| `knowledge-management` | Capture knowledge → Upload S3 with doc_folder | ✅ Documented |
+| `aivy-documents-sync` | Session start sync, post-change sync | ✅ Documented |
+
+### ❌ What Agent Actually Does (Problems)
+
+**The agent definition (`forLoopPlanner.md`) is the PROBLEM.** It has its own simplified workflow that SKIPS critical steps documented in the skills:
+
+| Expected (from Skills) | Agent Does (from Definition) | Gap |
+|------------------------|------------------------------|-----|
+| Sync S3 → local on session start | Only loads local `.forloop/` | ❌ Missing |
+| Create/verify doc_folder before uploads | No mention of doc_folder | ❌ Missing |
+| Upload task.md to S3 with `--storyId` | "Upload task file to S3" (no doc_folder) | ❌ Incomplete |
+| Upload plan.md to S3 with `--storyId` | "Upload to S3" (no doc_folder) | ❌ Incomplete |
+| Upload knowledge to S3 with `--storyId` | No knowledge upload mentioned | ❌ Missing |
+| Verify uploads with `forloopFileList` | No verification step | ❌ Missing |
+
+## Root Cause
+
+**The agent definition is the source of truth for the LLM**, not the skills. The skills provide detailed workflows, but the agent definition gives the high-level instructions. If the agent definition doesn't include a step, the LLM will skip it.
+
+## Required Improvements
+
+### 1. Agent Definition (`agent/forLoopPlanner.md`)
+
+**Add to Session Startup Flow:**
+```markdown
+### Step 0.5: Sync from S3 (MANDATORY)
+
+After loading local context, ALWAYS sync from S3:
+
+```bash
+forloopSyncAivyFolder --sprintId {sprintId}
+forloopSyncS3ToLocal --sprintId {sprintId}
+```
+
+This ensures you have the latest plan, task, and knowledge files from the team.
+```
+
+**Add to Workflow:**
+```markdown
+### Doc Folder Management (ALWAYS BEFORE UPLOADS)
+
+Before uploading ANY file to S3:
+
+1. Ensure doc_folder exists:
+   ```bash
+   forloopSyncAivyFolder --sprintId {sprintId}
+   ```
+
+2. Get doc_folder story ID:
+   ```bash
+   forloopAivyDocGet --sprintId {sprintId}
+   ```
+
+3. Upload with linking:
+   ```bash
+   forloopSyncLocalToS3 \
+     --filePath {path} \
+     --sprintId {sprintId} \
+     --folder project/{plans,tasks,knowledge} \
+     --storyId {docFolderId}
+   ```
+
+4. Verify upload:
+   ```bash
+   forloopFileList --sprintId {sprintId}
+   ```
+```
+
+### 2. Sync Tools (`plugins/tools/sync-tools.ts`)
+
+**Verify `forloopSyncAivyFolder` tool:**
+- Checks if "Aivy Plan Doc" doc_folder exists
+- Creates it if not
+- Returns the doc_folder story ID
+
+**Verify `forloopSyncS3ToLocal` tool:**
+- Downloads all files from S3 `project/plans/`, `project/tasks/`, `project/knowledge/`
+- Saves to `~/.forloop/plan/`, `~/.forloop/task/`, `~/.forloop/knowledge/`
+- Updates manifest.json
+
+**Verify `forloopSyncLocalToS3` tool:**
+- Uploads file to correct S3 folder
+- Links to doc_folder via `storyId` parameter
+- Returns upload confirmation
+
+### 3. Skill Improvements
+
+**forloop-context/SKILL.md:**
+- Make Step 7 (S3 sync) more prominent
+- Add explicit commands with parameters
+- Add error handling for sync failures
+
+**task-tracking/SKILL.md:**
+- Already well-documented, but add verification checklist
+- Emphasize doc_folder linking as MANDATORY
+
+**plan-documentation/SKILL.md:**
+- Already well-documented, but add verification checklist
+- Emphasize doc_folder linking as MANDATORY
+
+## Implementation Priority
+
+1. **HIGH**: Update agent definition (forLoopPlanner.md) - This is the LLM's primary instructions
+2. **HIGH**: Verify sync tools implement doc_folder workflow correctly
+3. **MEDIUM**: Update skills to be more explicit about mandatory steps
+4. **LOW**: Add verification checklists to all skills
+
+## Expected Behavior After Fix
+
+### Session Start
+```
+1. Load local .forloop/ context
+2. Sync from S3 → local (get latest files)
+3. Present combined context summary
+4. Confirm sprint with user
+```
+
+### Creating Plan
+```
+1. Write plan to ~/.forloop/plan/
+2. Update manifest.json
+3. Ensure doc_folder exists (create if needed)
+4. Get doc_folder ID
+5. Upload plan to S3 with --storyId {docFolderId}
+6. Verify upload with forloopFileList
+```
+
+### Creating Stories
+```
+1. Write task.md to ~/.forloop/task/
+2. Update manifest.json
+3. Ensure doc_folder exists (should already exist from plan)
+4. Get doc_folder ID
+5. Upload task.md to S3 with --storyId {docFolderId}
+6. Verify upload with forloopFileList
+```
+
+### Capturing Knowledge
+```
+1. Write knowledge file to ~/.forloop/knowledge/
+2. Ensure doc_folder exists
+3. Get doc_folder ID
+4. Upload to S3 with --storyId {docFolderId}
+5. Verify upload with forloopFileList
+```

package/docs/USER-INTERACTION-MODEL.md

@@ -0,0 +1,106 @@
+# How Users Interact with ForLoop Plugin
+
+## Understanding the Architecture
+
+The ForLoop Plugin is **NOT a CLI tool** that you run directly. It's an **opencode plugin** that extends opencode's capabilities.
+
+### ❌ What Users DON'T Do
+
+```bash
+# These DON'T work:
+node plugins/tools/sprint-tools.ts          ✗
+npm run forloopSprintList                 ✗
+./plugins/forloop-plugin.ts                 ✗
+```
+
+### ✅ What Users DO Instead
+
+Users interact through **opencode chat** using tool commands:
+
+```bash
+# 1. Start opencode
+opencode
+
+# 2. In the chat, use tool commands:
+forloopSprintList
+forloopStoryCreate --title "As a user, I want to login" --sprintId 14
+forloopAgentBreakdown --storyId 78
+```
+
+## Execution Flow
+
+```
+┌─────────────┐      ┌──────────────┐      ┌─────────────┐
+│   User      │      │   opencode   │      │  ForLoop    │
+│             │      │              │      │   Plugin    │
+└──────┬──────┘      └──────┬───────┘      └──────┬──────┘
+       │                    │                      │
+       │ 1. Type command    │                      │
+       │───────────────────>│                      │
+       │                    │                      │
+       │                    │ 2. Route to plugin   │
+       │                    │─────────────────────>│
+       │                    │                      │
+       │                    │                      │ 3. Execute
+       │                    │                      │ (TypeScript code)
+       │                    │                      │
+       │                    │ 4. Return result     │
+       │                    │<─────────────────────│
+       │                    │                      │
+       │ 5. Show output     │                      │
+       │<───────────────────│                      │
+       │                    │                      │
+```
+
+## Tool Commands vs TypeScript Functions
+
+| TypeScript Function | User Command |
+|---------------------|--------------|
+| `createSprintListTool()` | `forloopSprintList` |
+| `createStoryCreateTool()` | `forloopStoryCreate --title "..."` |
+| `createAgentBreakdownTool()` | `forloopAgentBreakdown --storyId 78` |
+
+## For Developers
+
+If you're **developing** the plugin:
+
+```bash
+# 1. Make changes to TypeScript files
+edit plugins/tools/sprint-tools.ts
+
+# 2. Run tests
+npm run test:unit
+
+# 3. Install locally to test
+npm run install:local
+
+# 4. Test in opencode
+opencode
+> forloopSprintList
+```
+
+If you're **using** the plugin:
+
+```bash
+# Just use opencode chat
+opencode
+> forloopSprintList
+
+# That's it! No TypeScript knowledge needed.
+```
+
+## Summary
+
+| Aspect | Developer | End User |
+|--------|-----------|----------|
+| Touches TypeScript? | ✅ Yes | ❌ No |
+| Runs `npm` commands? | ✅ Yes | ❌ No |
+| Uses `forloop.*` commands? | ✅ Yes | ✅ Yes |
+| Needs to understand plugin architecture? | ✅ Yes | ❌ No |
+
+**End users only need to know:**
+1. Install the plugin
+2. Set up API token
+3. Use `forloop.*` commands in opencode chat
+
+That's it!

package/docs/file-management/2026-04-12-forloop-aivy-documents-sync.md

@@ -0,0 +1,395 @@
+# ForLoop Aivy Documents - Auto-Sync Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Implement automatic bidirectional file synchronization between local `~/.forloop/` folder and S3, with auto-creation of "ForLoop Aivy Documents" doc_folder for organized file management.
+
+**Architecture:** Enhance existing skills with sync capabilities - extends forloop-context skill for S3→local sync at session start, and enhances knowledge-management/plan-documentation/task-tracking skills for local→S3 sync on file changes.
+
+**Tech Stack:** TypeScript, ForLoop plugin tools, AWS S3, Express.js backend
+
+---
+
+## Requirements Summary
+
+Based on user requirements:
+
+1. **Doc Folder Auto-Creation**: Agent checks if doc_folder "ForLoop Aivy Documents" exists in working sprint, creates if not
+2. **S3 → Local Sync**: At session start (after manifest.json confirms active sprint), sync files from S3 to local `~/.forloop/`
+3. **Local → S3 Sync**: Immediate sync whenever files are created/updated/removed under `~/.forloop/*`
+4. **S3 Structure**: Keep current structure: `sprint/{id}/project/{plans,knowledge,tasks}/`
+
+---
+
+## File Structure
+
+### New Files to Create
+
+1. **Skill:** `forloop-opencode-plugin-planner/skills/aivy-documents-sync/SKILL.md`
+   - Auto-sync skill for bidirectional synchronization
+   - Integrates with forloop-context for session startup
+   - Handles doc_folder creation and file tracking
+
+2. **Plugin Tool:** `forloop-opencode-plugin-planner/plugins/tools/sync-tools.ts`
+   - `createSyncTool()` - Main sync orchestration
+   - `createDocFolderCheckTool()` - Auto-create doc_folder
+   - Helper functions for file comparison
+
+3. **Test File:** `forloop-opencode-plugin-planner/test/suites/integration/sync-api.test.ts`
+   - Integration tests for sync functionality
+
+### Modified Files
+
+1. **forloop-context/SKILL.md** - Add sync step after loading manifest
+2. **knowledge-management/SKILL.md** - Add sync trigger after file creation
+3. **plan-documentation/SKILL.md** - Add sync trigger after file creation
+4. **task-tracking/SKILL.md** - Add sync trigger after file creation
+5. **file-tools.ts** - Add sync tracking capabilities
+6. **api-client.ts** - Add file comparison/download methods
+
+---
+
+## Implementation Tasks
+
+### Task 1: Create Sync Tools Plugin
+
+**Files:**
+- Create: `forloop-opencode-plugin-planner/plugins/tools/sync-tools.ts`
+- Modify: `forloop-opencode-plugin-planner/plugins/forloop-plugin.ts:106-108`
+- Test: `forloop-opencode-plugin-planner/test/suites/unit/sync-tools.test.ts`
+
+- [ ] **Step 1: Create sync-tools.ts with doc_folder check tool**
+
+```typescript
+import { tool } from '@opencode-ai/plugin';
+import { ForLoopAPIClient } from '../capabilities/api-client';
+import { validateToken } from '../capabilities/auth';
+import { resolveSprintId } from '../capabilities/context-resolver';
+
+export function createDocFolderCheckTool(client: ForLoopAPIClient) {
+  return tool({
+    description: 'Check and auto-create "ForLoop Aivy Documents" doc_folder in sprint',
+    args: {
+      sprintId: tool.schema.number()
+        .optional()
+        .describe('Target sprint ID (auto-detected from context)'),
+    },
+    async execute(args, context) {
+      const tokenResult = await validateToken();
+      if (!tokenResult.valid) {
+        return tokenResult.error;
+      }
+      client.setToken?.(tokenResult.token);
+
+      try {
+        // Resolve sprint ID
+        const resolution = await resolveSprintId(args.sprintId, context.directory);
+        if (!resolution.sprintId) {
+          return '❌ No sprint ID available. Please select a sprint first.';
+        }
+
+        // Get sprint details including stories
+        const sprint = await client.getSprint(resolution.sprintId);
+        
+        // Check if "ForLoop Aivy Documents" doc_folder exists
+        const docFolderStory = sprint.stories?.find((story: any) => 
+          story.type === 'doc_folder' && 
+          story.title === 'ForLoop Aivy Documents'
+        );
+
+        if (docFolderStory) {
+          return `✅ "ForLoop Aivy Documents" folder already exists (Story #${docFolderStory.id})`;
+        }
+
+        // Create doc_folder if not exists
+        const newFolder = await client.createStory({
+          title: 'ForLoop Aivy Documents',
+          description: ' Auto-created folder for ForLoop Aivy planning documents and sync',
+          sprintId: resolution.sprintId,
+          type: 'doc_folder',
+          metadata: JSON.stringify({
+            permissions: 'team',
+            autoCreated: true,
+            purpose: 'aivy-sync',
+          }),
+          status: 'todo',
+        });
+
+        return `✅ Created "ForLoop Aivy Documents" folder (Story #${newFolder.id})`;
+      } catch (error: any) {
+        return `❌ Error: ${error.message}`;
+      }
+    },
+  });
+}
+```
+
+- [ ] **Step 2: Add createS3ToLocalSyncTool function**
+
+```typescript
+export function createS3ToLocalSyncTool(client: ForLoopAPIClient) {
+  return tool({
+    description: 'Sync files from S3 to local ~/.forloop/ folder',
+    args: {
+      sprintId: tool.schema.number()
+        .optional()
+        .describe('Target sprint ID'),
+      syncKnowledge: tool.schema.boolean()
+        .default(true)
+        .describe('Sync knowledge files'),
+      syncPlans: tool.schema.boolean()
+        .default(true)
+        .describe('Sync plan files'),
+      syncTasks: tool.schema.boolean()
+        .default(true)
+        .describe('Sync task files'),
+    },
+    async execute(args, context) {
+      const tokenResult = await validateToken();
+      if (!tokenResult.valid) {
+        return tokenResult.error;
+      }
+      client.setToken?.(tokenResult.token);
+
+      try {
+        const resolution = await resolveSprintId(args.sprintId, context.directory);
+        if (!resolution.sprintId) {
+          return '❌ No sprint ID available.';
+        }
+
+        // Get files from S3
+        const s3Files = await client.getSprintFiles(resolution.sprintId);
+        
+        // Filter files by folder pattern
+        const knowledgeFiles = s3Files.filter((f: any) => 
+          f.url?.includes('/project/knowledge/')
+        );
+        const planFiles = s3Files.filter((f: any) => 
+          f.url?.includes('/project/plans/')
+        );
+        const taskFiles = s3Files.filter((f: any) => 
+          f.url?.includes('/project/tasks/')
+        );
+
+        // Download and save locally
+        const homeDir = process.env.HOME || '/tmp/home';
+        let syncedCount = 0;
+
+        if (args.syncKnowledge) {
+          for (const file of knowledgeFiles) {
+            const downloadUrl = await client.getFileOpenUrl(file.id);
+            const fileName = file.originalName || file.filename;
+            // Save to ~/.forloop/knowledge/
+            // Increment syncedCount
+          }
+        }
+
+        // Repeat for plans and tasks...
+
+        return `✅ Synced ${syncedCount} files from S3 to ~/.forloop/`;
+      } catch (error: any) {
+        return `❌ Error: ${error.message}`;
+      }
+    },
+  });
+}
+```
+
+- [ ] **Step 3: Add createLocalToS3SyncTool function**
+
+```typescript
+export function createLocalToS3SyncTool(client: ForLoopAPIClient) {
+  return tool({
+    description: 'Sync local ~/.forloop/ files to S3',
+    args: {
+      filePath: tool.schema.string()
+        .describe('Local file path to sync'),
+      sprintId: tool.schema.number()
+        .optional()
+        .describe('Target sprint ID'),
+    },
+    async execute(args, context) {
+      // Implementation for immediate sync of individual files
+      // Used by knowledge-management, plan-documentation, task-tracking skills
+    },
+  });
+}
+```
+
+- [ ] **Step 4: Register tools in forloop-plugin.ts**
+
+**File:** `forloop-opencode-plugin-planner/plugins/forloop-plugin.ts`
+
+**Locate lines 106-108:**
+```typescript
+'forloopFileUpload': createFileUploadTool(client),
+'forloopFileList': createFileListTool(client),
+```
+
+**Add after file tools:**
+```typescript
+'forloop.sync.folder': createDocFolderCheckTool(client),
+'forloopSyncS3ToLocal': createS3ToLocalSyncTool(client),
+'forloopSyncLocalToS3': createLocalToS3SyncTool(client),
+```
+
+- [ ] **Step 5: Write unit tests**
+
+**File:** `forloop-opencode-plugin-planner/test/suites/unit/sync-tools.test.ts`
+
+```typescript
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { 
+  createDocFolderCheckTool,
+  createS3ToLocalSyncTool,
+  createLocalToS3SyncTool,
+} from '../../../plugins/tools/sync-tools';
+
+describe('Sync Tools', () => {
+  const mockClient = {
+    getSprint: vi.fn(),
+    createStory: vi.fn(),
+    getSprintFiles: vi.fn(),
+    getFileOpenUrl: vi.fn(),
+    // ... other mocks
+  };
+
+  describe('forloop.sync.folder', () => {
+    it('should detect existing doc_folder', async () => {
+      mockClient.getSprint.mockResolvedValue({
+        id: 14,
+        stories: [
+          { id: 101, type: 'doc_folder', title: 'ForLoop Aivy Documents' }
+        ]
+      });
+
+      const tool = createDocFolderCheckTool(mockClient as any);
+      const result = await tool.executor({ sprintId: 14 }, { directory: '.' });
+      
+      expect(result).toContain('already exists');
+      expect(mockClient.createStory).not.toHaveBeenCalled();
+    });
+
+    it('should create doc_folder if not exists', async () => {
+      mockClient.getSprint.mockResolvedValue({
+        id: 14,
+        stories: []
+      });
+      
+      mockClient.createStory.mockResolvedValue({
+        id: 102,
+        title: 'ForLoop Aivy Documents',
+        type: 'doc_folder'
+      });
+
+      const tool = createDocFolderCheckTool(mockClient as any);
+      const result = await tool.executor({ sprintId: 14 }, { directory: '.' });
+      
+      expect(result).toContain('Created');
+      expect(mockClient.createStory).toHaveBeenCalledWith(expect.objectContaining({
+        title: 'ForLoop Aivy Documents',
+        type: 'doc_folder'
+      }));
+    });
+  });
+});
+```
+
+- [ ] **Step 6: Run tests**
+
+```bash
+cd forloop-opencode-plugin-planner
+npm run test:unit -- sync-tools
+```
+
+Expected: All tests PASS
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add plugins/tools/sync-tools.ts plugins/forloop-plugin.ts test/suites/unit/sync-tools.test.ts
+git commit -m "feat: add ForLoop Aivy documents sync tools"
+```
+
+---
+
+### Task 2: Create Auto-Sync Skill
+
+**Files:**
+- Create: `forloop-opencode-plugin-planner/skills/aivy-documents-sync/SKILL.md`
+- Modify: `forloop-opencode-plugin-planner/skills/forloop-context/SKILL.md:28-54`
+
+- [ ] **Step 1: Create aivy-documents-sync skill**
+
+Create comprehensive skill document (see full content in planning document) covering:
+- Session startup sync workflow
+- File change sync triggers
+- Integration with existing skills
+- Sync manifest tracking
+- Error handling
+- Conflict resolution
+
+- [ ] **Step 2: Update forloop-context skill**
+
+**File:** `forloop-opencode-plugin-planner/skills/forloop-context/SKILL.md`
+
+Add Step 7 after "Present to user":
+```markdown
+### Step 7: Auto-Sync Files (NEW)
+1. Check and create doc_folder: `forloop.sync.folder --sprintId {id}`
+2. Sync S3 to local: `forloopSyncS3ToLocal --sprintId {id}`
+3. Report sync status
+```
+
+- [ ] **Step 3: Update other skills**
+
+Add sync tracking steps to:
+- knowledge-management/SKILL.md (after upload)
+- plan-documentation/SKILL.md (after upload)
+- task-tracking/SKILL.md (after upload)
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add skills/*.md
+git commit -m "feat: add ForLoop Aivy auto-sync skill"
+```
+
+---
+
+### Task 3: Extend API Client
+
+**Files:**
+- Modify: `forloop-opencode-plugin-planner/plugins/capabilities/api-client.ts`
+
+- [ ] **Step 1: Add downloadFile method**
+- [ ] **Step 2: Add compareFiles method**
+- [ ] **Step 3: Commit**
+
+---
+
+### Task 4: Write Integration Tests
+
+**Files:**
+- Create: `forloop-opencode-plugin-planner/test/suites/integration/sync-api.test.ts`
+
+- [ ] **Step 1: Create test file**
+- [ ] **Step 2: Run tests**
+- [ ] **Step 3: Commit**
+
+---
+
+## Execution Handoff
+
+**Plan complete. Two execution options:**
+
+**1. Subagent-Driven (recommended)** - Fresh subagent per task, review between tasks, fast iteration
+
+**2. Inline Execution** - Execute tasks in this session with checkpoints
+
+**Which approach?**
+
+---
+
+**Created:** 2026-04-12  
+**Version:** 1.0.0