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

package/README.md

@@ -7,6 +7,8 @@
 
 **AI-powered sprint planning, story management, and task automation for opencode**
 
+[English](README.md) · [中文](README_zh.md) · [日本語](README_ja.md)
+
 [Quick Install](#quick-install) · [How It Works](#how-it-works) · [Capabilities](#capabilities) · [FAQ](#faq)
 
 </div>
@@ -64,6 +66,16 @@ curl -fsSL https://raw.githubusercontent.com/forloop-cc/forloop-opencode-plugin-
 - A [ForLoop](https://forloop.cc) account with an API token ([create one here](https://forloop.cc/profile?tab=api-tokens))
 - Token scopes: `sprint:read`, `sprint:write`, `story:read`, `story:write`, `agent:query`, `profile:read`
 
+### Quick Start
+
+```bash
+opencode --agent forLoopPlanner
+```
+
+Or launch opencode normally and press **Tab** to switch to the **ForLoop Planner** agent from the agent picker.
+
+The `forLoopPlanner` agent uses the plugin's built-in tools for full sprint, story, and file management. For environments without the opencode plugin installed, use `forLoopPlannerCLI` which works with the standalone `forloop` CLI binary.
+
 ### Set Your Token
 
 **Easiest — ask the agent:**

package/docs/superpowers/specs/2026-06-08-plugin-test-docker-design.md

@@ -0,0 +1,110 @@
+# Plugin Docker Integration Test Design
+
+**Date:** 2026-06-08
+**Status:** Approved
+**Context:** end-to-end verification of the ForLoop plugin install flow in a clean environment
+
+## Purpose
+
+Verify that the one-line install command (`curl -fsSL .../install.sh | bash`) produces a working plugin installation with correct agent/skill discovery, and that the planner agent loads correctly and is self-aware of its tools and skills.
+
+## Architecture
+
+```
+┌──────────────────────────────────────────┐
+│              Docker Container            │
+│  Ubuntu 22.04 (clean, no mounts)         │
+│                                          │
+│  1. Install deps (curl, git, jq, node)  │
+│  2. Install opencode (official script)   │
+│  3. Install plugin  (official script)    │
+│  4. Verify installation structure        │
+│  5. Verify planner agent self-awareness  │
+│                                          │
+│  Entrypoint: test.sh                     │
+│  Exit code: 0 = pass, non-zero = fail    │
+└──────────────────────────────────────────┘
+```
+
+**Key constraint:** no volume mounts, no pre-installed dependencies. Everything installed from the internet inside the container, matching the real user experience.
+
+## Files
+
+```
+forloop-opencode-plugin-planner/
+  test/
+    Dockerfile    # Builds container with Ubuntu + all deps
+    test.sh       # Verification script (entrypoint)
+```
+
+## Install Flow
+
+The Docker container installs in this order:
+
+1. **System deps:** `apt-get install -y curl git jq ca-certificates gnupg`
+2. **Node.js 20:** via NodeSource setup script
+3. **OpenCode:** `curl -fsSL https://opencode.ai/install.sh | bash`
+4. **ForLoop plugin:** `curl -fsSL https://raw.githubusercontent.com/forloop-cc/forloop-opencode-plugin-planner/main/install.sh | bash`
+5. **API token:** NOT configured (test runs without token)
+
+## Verification Stages
+
+### Stage A: Plugin Registration
+**Assert:** `~/.config/opencode/opencode.json` exists and contains the plugin entry in the `plugin` array.
+
+### Stage B: Agents Installed
+**Assert:** 3 agent `.md` files are symlinked in `~/.config/opencode/agents/`:
+- `forLoopPlanner.md`
+- `forLoopPlannerCLI.md`
+- `forLoopStoryEvaluator.md`
+
+### Stage C: Skills Installed
+**Assert:** 16 skill directories are symlinked in `~/.config/opencode/skills/`, each containing a `SKILL.md`:
+- agent-auto-assignment, aivy-documents-sync, file-management, forloop-cli, forloop-context, forloop-skill, knowledge-management, plan-documentation, sprint-planning, story-creation, story-points, task-tracking, tech-stack-default, template-based-tasks, user-management, verification-before-completion
+
+### Stage D: Planner Self-Awareness (Workflow)
+**Assert:** `opencode run --agent forLoopPlanner "who are you and what is your workflow"` produces output that:
+- Identifies itself as the ForLoop Planner agent
+- Mentions its 7-phase workflow (or at minimum: context loading, sprint review, planning, execution)
+- References ForLoop platform (sprints, stories, agents)
+
+### Stage E: Tool Discovery
+**Assert:** `opencode run --agent forLoopPlanner "what tools and skills do you have"` produces output that:
+- Lists or references ForLoop plugin tools (forloopSprintList, forloopStoryCreate, forloopAgentQuery, etc.)
+- References skills loaded from the plugin (sprint-planning, task-tracking, file-management, forloop-skill)
+
+## No Token Behavior
+
+Since no API token is configured, the planner will note this and offer to help the user set one. This is expected and acceptable — the test verifies installation correctness and agent self-awareness, not actual API calls.
+
+## Test Script Output
+
+The test script prints pass/fail for each stage:
+
+```
+=== Stage A: Plugin Registration ===
+PASS: Plugin registered in opencode.json
+
+=== Stage B: Agents ===
+PASS: 3 agents installed (forLoopPlanner, forLoopPlannerCLI, forLoopStoryEvaluator)
+
+=== Stage C: Skills ===
+PASS: 16 skills installed
+
+=== Stage D: Planner Self-Awareness ===
+PASS: Planner identifies itself and workflow
+
+=== Stage E: Tool Discovery ===
+PASS: Tools and skills discovered
+
+=== ALL TESTS PASSED ===
+```
+
+On failure, prints the actual vs expected and exits with code 1.
+
+## Build and Run
+
+```bash
+docker build -t forloop-plugin-test -f test/Dockerfile .
+docker run --rm forloop-plugin-test
+```

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@forloop-cc/forloop-opencode-plugin-planner",
-  "version": "2.2.1",
+  "version": "2.2.5",
   "description": "ForLoop integration plugin for opencode — Sprint, story, and agent tools for the ForLoop platform",
   "type": "module",
   "license": "MIT",

package/plugins/capabilities/mime-types.ts

@@ -0,0 +1,25 @@
+const MIME_TYPES: Record<string, string> = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.pdf': 'application/pdf',
+  '.txt': 'text/plain',
+  '.md': 'text/markdown',
+  '.json': 'application/json',
+  '.csv': 'text/csv',
+  '.mp4': 'video/mp4',
+  '.mp3': 'audio/mpeg',
+};
+
+export function contentTypeFromExtension(ext: string): string {
+  return MIME_TYPES[String(ext || '').toLowerCase()] || 'application/octet-stream';
+}
+
+export function formatFileSize(bytes: number): string {
+  if (bytes === 0) return '0 Bytes';
+  const k = 1024;
+  const sizes = ['Bytes', 'KB', 'MB', 'GB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
+}

package/plugins/tools/file-tools.ts

@@ -1,6 +1,7 @@
 import { tool } from '@opencode-ai/plugin';
 import { ForLoopAPIClient } from '../capabilities/api-client';
 import { validateToken } from '../capabilities/auth';
+import { contentTypeFromExtension, formatFileSize } from '../capabilities/mime-types';
 import * as fs from 'fs';
 import * as path from 'path';
 
@@ -41,21 +42,7 @@ export function createFileUploadTool(client: ForLoopAPIClient) {
         const ext = path.extname(fileName);
         const fileSize = fileContent.length;
 
-        // Determine content type
-        const mimeTypes: Record<string, string> = {
-          '.png': 'image/png',
-          '.jpg': 'image/jpeg',
-          '.jpeg': 'image/jpeg',
-          '.gif': 'image/gif',
-          '.pdf': 'application/pdf',
-          '.txt': 'text/plain',
-          '.md': 'text/markdown',
-          '.json': 'application/json',
-          '.csv': 'text/csv',
-          '.mp4': 'video/mp4',
-          '.mp3': 'audio/mpeg',
-        };
-        const contentType = mimeTypes[ext] || 'application/octet-stream';
+        const contentType = contentTypeFromExtension(ext);
 
         // Get presigned URL
         const presign = await client.createPresignedUpload({
@@ -91,19 +78,11 @@ export function createFileUploadTool(client: ForLoopAPIClient) {
           storyId: args.storyId,
         });
 
-        const formatSize = (bytes: number) => {
-          if (bytes === 0) return '0 Bytes';
-          const k = 1024;
-          const sizes = ['Bytes', 'KB', 'MB', 'GB'];
-          const i = Math.floor(Math.log(bytes) / Math.log(k));
-          return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
-        };
-
         return [
           `✅ File uploaded successfully!`,
           '',
           `**File**: ${fileName}`,
-          `**Size**: ${formatSize(fileSize)}`,
+          `**Size**: ${formatFileSize(fileSize)}`,
           `**URL**: ${complete.url}`,
           args.description ? `**Description**: ${args.description}` : null,
           args.folder ? `**Folder**: ${args.folder}` : null,
@@ -137,18 +116,10 @@ export function createFileListTool(client: ForLoopAPIClient) {
           return '🗂️ No files found in this sprint.';
         }
 
-        const formatSize = (bytes: number) => {
-          if (bytes === 0) return '0 Bytes';
-          const k = 1024;
-          const sizes = ['Bytes', 'KB', 'MB', 'GB'];
-          const i = Math.floor(Math.log(bytes) / Math.log(k));
-          return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
-        };
-
         const lines: string[] = [`🗂️ Files in Sprint #${args.sprintId}:`, ''];
-        
+
         for (const file of files) {
-          const size = formatSize(file.size);
+          const size = formatFileSize(file.size);
           const uploadedBy = file.uploader?.name || file.uploaderId ? `by ${file.uploader?.name || `User #${file.uploaderId}`}` : '';
           const date = file.createdAt ? new Date(file.createdAt).toLocaleDateString() : '';
           

package/plugins/tools/schedule-tools.ts

@@ -52,7 +52,7 @@ export function createScheduleTool(client: ForLoopAPIClient) {
         }
 
         // Build schedule metadata
-        const scheduleMetadata = {
+        const scheduleMetadata = JSON.stringify({
           title: args.title,
           description: args.description,
           startAt: args.startAt,
@@ -60,7 +60,7 @@ export function createScheduleTool(client: ForLoopAPIClient) {
           timezone: args.timezone,
           videoUrl: args.videoUrl,
           location: args.location,
-        };
+        });
 
         // Create schedule story
         const story = await client.createStory({
@@ -68,7 +68,7 @@ export function createScheduleTool(client: ForLoopAPIClient) {
           description: args.description,
           sprintId: resolution.sprintId,
           type: 'schedule',
-          metadata: JSON.stringify(scheduleMetadata),
+          metadata: scheduleMetadata,
           status: 'todo',
         });
 
@@ -148,14 +148,14 @@ export function createScheduleUpdateTool(client: ForLoopAPIClient) {
         const existingMetadata = story.metadata ? JSON.parse(story.metadata) : {};
         
         // Update with new values
-        const updatedMetadata = {
+        const updatedMetadata = JSON.stringify({
           ...existingMetadata,
           title: args.title !== undefined ? args.title : existingMetadata.title,
           description: args.description !== undefined ? args.description : existingMetadata.description,
           startAt: args.startAt !== undefined ? args.startAt : existingMetadata.startAt,
           endAt: args.endAt !== undefined ? args.endAt : existingMetadata.endAt,
           videoUrl: args.videoUrl !== undefined ? args.videoUrl : existingMetadata.videoUrl,
-        };
+        });
 
         // Update story
         await client.updateStory(args.storyId, {

package/plugins/tools/sprint-tools.ts

@@ -96,7 +96,10 @@ export function createSprintListTool(client: ForLoopAPIClient) {
       if (args.organizationId) params.organizationId = String(args.organizationId);
       
       try {
-        const sprints = await client.listSprints(params);
+        const sprints = await client.listSprints({
+          organizationId: args.organizationId,
+          includeSystemOrg: args.includeSystemOrg ?? true,
+        });
 
         if (!sprints.length) {
           return 'No sprints found.';

package/plugins/tools/sync-tools.ts

@@ -2,6 +2,7 @@ import { tool } from '@opencode-ai/plugin';
 import { ForLoopAPIClient } from '../capabilities/api-client';
 import { validateToken } from '../capabilities/auth';
 import { resolveSprintId, getForloopRoot as getForloopRootPath } from '../capabilities/context-resolver';
+import { contentTypeFromExtension } from '../capabilities/mime-types';
 import * as fs from 'fs';
 import * as path from 'path';
 
@@ -363,23 +364,6 @@ export function createLocalToS3SyncTool(client: ForLoopAPIClient) {
   });
 }
 
-function contentTypeFromExtension(ext: string): string {
-  const map: Record<string, string> = {
-    '.png': 'image/png',
-    '.jpg': 'image/jpeg',
-    '.jpeg': 'image/jpeg',
-    '.gif': 'image/gif',
-    '.pdf': 'application/pdf',
-    '.txt': 'text/plain',
-    '.md': 'text/markdown',
-    '.json': 'application/json',
-    '.csv': 'text/csv',
-    '.mp4': 'video/mp4',
-    '.mp3': 'audio/mpeg',
-  };
-  return map[String(ext || '').toLowerCase()] || 'application/octet-stream';
-}
-
 function resolveForloopRoot(contextDir?: string, sprintId?: number): string {
   if (sprintId !== undefined) {
     return getForloopRootPath(sprintId);

package/plugins/tools/template-tools.ts

@@ -22,8 +22,14 @@ export function createTemplateListTool(client: ForLoopAPIClient) {
         for (const t of templates) {
           if (t.deletedAt) continue; // Skip deleted templates
           
-          const fields = JSON.parse(t.fields);
-          const fieldNames = fields.map((f: any) => f.label).join(', ');
+          const fieldNames = (() => {
+            try {
+              const fields = JSON.parse(t.fields);
+              return fields.map((f: any) => f.label).join(', ');
+            } catch {
+              return 'N/A';
+            }
+          })();
           
           lines.push(`📝 **${t.name}** (\`${t.slug}\`)`);
           lines.push(`   ${t.description}`);

package/update.sh

@@ -129,7 +129,6 @@ echo ""
 
 check_jq || exit 1
 
-local config_file
 config_file="$(find_config)" || {
     print_error "No opencode.json found"
     echo ""
@@ -141,7 +140,6 @@ config_file="$(find_config)" || {
     exit 1
 }
 
-local plugin_entry
 plugin_entry="$(find_plugin_entry "$config_file")"
 
 if [ -z "$plugin_entry" ]; then