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

package/README.md

@@ -0,0 +1,211 @@
+<div align="center">
+
+<img src="docs/images/forloop-opencode-header.png" alt="ForLoop Plugin for opencode" width="800">
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Stars](https://img.shields.io/github/stars/forloop-cc/forloop-opencode-plugin-planner?style=flat-square)](https://github.com/forloop-cc/forloop-opencode-plugin-planner/stargazers)
+
+**AI-powered sprint planning, story management, and task automation for opencode**
+
+[Quick Install](#quick-install) · [How It Works](#how-it-works) · [Capabilities](#capabilities) · [FAQ](#faq)
+
+</div>
+
+***
+
+## What is This?
+
+The **ForLoop Plugin** connects [opencode](https://opencode.ai) AI agents to your [ForLoop](https://forloop.cc) workspace. Describe what you need in plain language — the agent plans, creates stories, estimates effort, and tracks progress automatically. No commands to memorize.
+
+***
+
+## About ForLoop
+
+[ForLoop](https://forloop.cc) is an **AI agent platform** for autonomous development and deployment. Think of it as your team's command center — a shared space where AI agents and humans collaborate on sprints, stories, and shipping code.
+
+**Key features:**
+
+- **AI Agents as team members** — specialized agents plan, code, review, and deploy. They create real branches, commits, and pull requests.
+- **Sprint boards** — drag-and-drop story management with real-time collaboration, AI estimation, and progress tracking.
+- **Autopilot development** — agents work through your sprint board automatically, with you reviewing and approving at every checkpoint.
+- **Spaces** — shared workspaces with integrated Zoom meetings, AI transcription, and a searchable cross-org knowledge base.
+- **Human-in-the-loop safety** — all AI-proposed changes go through review. Nothing ships without your approval.
+
+**This plugin** brings the collaboration features — sprint planning, story management, file uploads, and team coordination — directly into your opencode IDE.
+
+***
+
+## Quick Install
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/forloop-cc/forloop-opencode-plugin-planner/main/install.sh | bash
+```
+
+The installer clones the plugin, installs dependencies, and configures opencode. Works on macOS, Linux, and Windows (Git Bash).
+
+**Install options:**
+
+```bash
+curl -fsSL .../install.sh | bash              # Interactive (local by default)
+curl -fsSL .../install.sh | bash -s -- -g     # Global (~/.config/opencode/)
+curl -fsSL .../install.sh | bash -s -- -g -n  # Global via npm package
+```
+opencode downloads and caches the plugin on startup — no manual git clone or npm install needed.
+
+**Update later:**
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/forloop-cc/forloop-opencode-plugin-planner/main/update.sh | bash
+```
+
+### Prerequisites
+
+- [opencode](https://opencode.ai) CLI installed
+- 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`
+
+### Set Your Token
+
+**Easiest — ask the agent:**
+```
+"ForLoop Planner, please set my API token"
+```
+The agent will guide you through the setup.
+
+**Manual setup:**
+Create `~/.config/forloop/tokens.json`:
+```json
+{
+  "default": "floop_your_token_here",
+  "lastUpdated": "2026-01-01T00:00:00.000Z"
+}
+```
+The token file is stored at `~/.config/forloop/tokens.json` with restricted permissions. Edit or replace it anytime to rotate tokens.
+
+***
+
+## How It Works
+
+<img src="docs/images/forloop-opencode-flow.png" alt="ForLoop Plugin workflow" width="800">
+
+1. **You describe** what you need in plain language
+2. **The agent** picks the right skills and tools automatically
+3. **The plugin** connects to your ForLoop workspace via your API token
+4. **Results** flow back — sprints planned, stories created, tasks tracked
+
+***
+
+## What You Can Ask Agents to Do
+
+### Sprint Planning
+
+| Agent can...                                      | Try saying...                                             |
+| ------------------------------------------------- | --------------------------------------------------------- |
+| Create and configure sprints with dates and goals | *"Set up sprint 15 starting next Monday, two weeks long"* |
+| Review sprint status and progress                 | *"How is sprint 14 going? Show me all the stories"*       |
+| Update sprint details mid-cycle                   | *"Extend sprint 14 by one more week"*                     |
+
+### Story Management
+
+| Agent can...                             | Try saying...                                                              |
+| ---------------------------------------- | -------------------------------------------------------------------------- |
+| Create stories from scratch or templates | *"Create a story for adding user authentication"*                          |
+| Break down large stories into tasks      | *"Break down story #78 into smaller tasks"*                                |
+| Update story status, priority, points    | *"Mark story #78 as done and estimate the next one at 5 points"*           |
+| Create stories from templates            | *"Create a basic task for the developer agent to implement the login API"* |
+
+### AI-Assisted Planning
+
+| Agent can...                                  | Try saying...                                                 |
+| --------------------------------------------- | ------------------------------------------------------------- |
+| Get story breakdowns and implementation plans | *"Break down story #78 into subtasks"*                        |
+| Estimate story point complexity               | *"Estimate the points for my login feature"*                  |
+| Get sprint-level suggestions                  | *"Suggest how to organize the remaining stories this sprint"* |
+| Review conversation history                   | *"Show me what we discussed about sprint 14"*                 |
+
+### Files & Documents
+
+| Agent can...                   | Try saying...                                             |
+| ------------------------------ | --------------------------------------------------------- |
+| Upload files to sprint storage | *"Upload requirements.pdf to sprint 14"*                  |
+| List and manage sprint files   | *"Show me all files in sprint 14"*                        |
+| Create document folders        | *"Create a docs folder for sprint 15"*                    |
+| Download files                 | *"Get me the download link for the architecture diagram"* |
+
+### Teams & Organizations
+
+| Agent can...                 | Try saying...                                    |
+| ---------------------------- | ------------------------------------------------ |
+| View organization membership | *"Show me who's on the Engineering team"*        |
+| Check usage quotas           | *"How many stories do we have left this month?"* |
+| Manage team settings         | *"Create a new organization called Design Team"* |
+
+***
+
+## Plugin Capabilities
+
+The plugin provides these tools to opencode agents. Agents use them automatically — you don't call them directly. For agent definitions and skills, see the [forloop-agents-skills](https://github.com/forloop-cc/forloop-agents-skills) repo.
+
+**Sprint Management** — create, update, list, and delete sprints with full metadata\
+**Story Operations** — full CRUD for stories with template support, priority, and points\
+**AI Agent Tools** — story breakdown, point estimation, sprint suggestions, conversation history\
+**File Management** — S3-backed upload, download, listing, and document folders\
+**Organization Management** — teams, membership, and quota tracking\
+**Scheduling** — create and manage sprint meetings with video links
+
+***
+
+## Agents & Skills
+
+Agents and skills are maintained in a separate repo: **[forloop-agents-skills](https://github.com/forloop-cc/forloop-agents-skills)**. The installer (above) sets them up automatically. For manual setup:
+
+```bash
+git clone https://github.com/forloop-cc/forloop-agents-skills.git ~/.config/forloop/agents-skills
+ln -sf ~/.config/forloop/agents-skills/agents/*.md ~/.config/opencode/agents/
+ln -sfn ~/.config/forloop/agents-skills/skills/*/ ~/.config/opencode/skills/
+```
+
+The repo includes 2 agents and 15 skills covering sprint planning, story creation, task tracking, file management, and more. See the [repo README](https://github.com/forloop-cc/forloop-agents-skills) for the full list.
+
+### Included Agents
+
+| Agent                                          | Best for...                                                     |
+| ---------------------------------------------- | --------------------------------------------------------------- |
+| **ForLoop Planner** (`@forLoopPlanner`)        | Sprint planning, story creation, task breakdown, sprint reviews |
+| **Story Evaluator** (`@forLoopStoryEvaluator`) | Point estimation, complexity analysis                           |
+
+***
+
+## FAQ
+
+**How do I use this?** Start opencode, switch to the ForLoop Planner agent (TAB), and describe what you need. The agent handles everything.
+
+**What's opencode?** A free, open-source AI coding assistant. [Install here](https://opencode.ai).
+
+**Do I need to memorize commands?** No. The agents use the tools automatically. Just talk to them.
+
+**Where is my token stored?** `~/.config/forloop/tokens.json` with restricted file permissions.
+
+**Can I auto-detect my sprint?** Yes — name your git branch `sprint-XXX` or set `FORLOOP_SPRINT_ID=14`.
+
+**How do I uninstall?** Remove the plugin entry from your `opencode.json` plugin array. For agents and skills, delete the symlinks from `~/.config/opencode/agents/` and `~/.config/opencode/skills/`.
+
+**Does this work on Windows?** Yes — use Git Bash or WSL.
+
+***
+
+## Contributing
+
+Issues and PRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+***
+
+## Security
+
+See [SECURITY.md](SECURITY.md). Never commit API tokens. Use minimum required scopes.
+
+***
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/SECURITY.md

@@ -0,0 +1,69 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 2.x.x   | :white_check_mark: |
+| 1.x.x   | :x:                |
+
+## Reporting a Vulnerability
+
+We take the security of the ForLoop Plugin seriously. If you believe you've found a security vulnerability, please follow these steps:
+
+### How to Report
+
+1. **DO NOT** create a public GitHub issue for security vulnerabilities
+2. Email your findings to: [security@forloop.cc](mailto:security@forloop.cc)
+3. Include the following information:
+   - Description of the vulnerability
+   - Steps to reproduce the issue
+   - Potential impact
+   - Suggested fix (if any)
+   - Your contact information
+
+### What to Expect
+
+- **Initial response**: Within 48 hours
+- **Status update**: Within 5 business days
+- **Resolution timeline**: Depends on severity and complexity
+
+### Security Best Practices
+
+When using the ForLoop Plugin:
+
+1. **Token Security**
+   - Never commit API tokens to version control
+   - Use environment variables or secure token storage
+   - Rotate tokens regularly
+   - Use minimum required scopes
+
+2. **Plugin Updates**
+   - Keep the plugin updated to the latest version
+   - Review changelog for security fixes
+   - Enable automatic updates when possible
+
+3. **Access Control**
+   - Use organization-level tokens for team projects
+   - Limit token permissions to required scopes only
+   - Revoke unused or old tokens
+
+### Known Security Measures
+
+The plugin implements the following security features:
+
+- Token storage with restricted file permissions (0o600)
+- API token validation before requests
+- Support for scoped API tokens
+- Secure token exchange for Lambda execution
+- No sensitive data in logs
+
+### Security Audit Log
+
+Check the [security advisories](https://github.com/forloop-cc/forloop-opencode-plugin/security/advisories) page for past security issues and resolutions.
+
+## Responsible Disclosure
+
+We appreciate responsible disclosure and will credit reporters (with permission) in our security advisories.
+
+Thank you for helping keep the ForLoop Plugin secure!

package/docs/CONFIGURATION.md

@@ -0,0 +1,283 @@
+# ForLoop Plugin Configuration
+
+## Environment Configuration
+
+The plugin supports multiple environments, but defaults to **production** so public releases never accidentally connect to dev.
+
+### Default Environments
+
+| Environment | API URL | Use Case |
+|-------------|---------|----------|
+| **development** | `https://api.dev.forloop.cc` | Internal testing only (explicit opt-in) |
+| **production** | `https://api.forloop.cc` | Production use, npm releases |
+
+### Configuration Priority (highest to lowest)
+
+1. **Environment Variable** - `FORLOOP_API_URL`
+2. **Environment Selector** - `FORLOOP_ENV=production|development`
+3. **Project Config** - `opencode.json` → `forloop.apiUrl`
+4. **Global Config** - `~/.config/opencode/config.json` → `forloop.apiUrl`
+5. **Default** - `https://api.forloop.cc`
+
+### Dev Safety Gate
+
+To use the dev API (`api.dev.forloop.cc`), you must explicitly enable it:
+
+- `FORLOOP_ALLOW_DEV=true` (recommended)
+- or `opencode.json` / global config `forloop.allowDev: true`
+
+If a dev URL is configured without the allow flag, the plugin will fall back to production.
+
+---
+
+## Configuration Methods
+
+### Method 1: Environment Variable (Recommended for Development)
+
+```bash
+# Internal dev testing (explicit opt-in)
+export FORLOOP_ALLOW_DEV=true
+export FORLOOP_API_URL=https://api.dev.forloop.cc
+
+# Or add to .env file (do not commit)
+cat >> .env << 'EOF'
+FORLOOP_ALLOW_DEV=true
+FORLOOP_API_URL=https://api.dev.forloop.cc
+EOF
+
+# Or use opencode with env
+FORLOOP_ALLOW_DEV=true FORLOOP_API_URL=https://api.dev.forloop.cc opencode
+```
+
+### Method 2: opencode.json (Project-specific)
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["forloop@git+https://github.com/forloop-cc/forloop-opencode-plugin.git"],
+  "forloop": {
+    "apiUrl": "https://api.dev.forloop.cc",
+    "allowDev": true,
+    "tokenStorage": "global",
+    "debug": true
+  }
+}
+```
+
+### Method 3: Global Config (All Projects)
+
+Edit `~/.config/opencode/config.json`:
+
+```json
+{
+  "forloop": {
+    "apiUrl": "https://api.dev.forloop.cc",
+    "allowDev": true
+  }
+}
+```
+
+### Method 4: Environment Selector (Recommended)
+
+```bash
+# Production (default)
+FORLOOP_ENV=production opencode
+
+# Development (internal only; requires allow)
+FORLOOP_ENV=development FORLOOP_ALLOW_DEV=true opencode
+```
+
+---
+
+## Usage Examples
+
+### Development Workflow
+
+```bash
+# 1. Clone the plugin for local development
+git clone https://github.com/forloop-cc/forloop-opencode-plugin.git
+cd forloop-opencode-plugin
+
+# 2. Set development environment
+export FORLOOP_API_URL=https://api.dev.forloop.cc
+export NODE_ENV=development
+
+# 3. Use the plugin (it will connect to dev API)
+opencode
+```
+
+### Testing Against Dev Environment
+
+```bash
+# Quick test without permanent config
+FORLOOP_API_URL=https://api.dev.forloop.cc opencode run "forloopSprintList"
+```
+
+### Production Deployment
+
+When publishing to npm, the default is production:
+
+```json
+{
+  "plugin": ["forloop@git+https://github.com/forloop-cc/forloop-opencode-plugin.git"]
+}
+```
+
+Users will connect to `https://api.forloop.cc` by default.
+
+---
+
+## Debug Mode
+
+Enable debug logging to see what's happening:
+
+```bash
+# Via environment variable
+export FORLOOP_DEBUG=true
+
+# Or in opencode.json
+{
+  "forloop": {
+    "debug": true
+  }
+}
+```
+
+This will log:
+```
+[ForLoop Config] {
+  apiUrl: 'https://api.forloop.cc',
+  environment: 'production',
+  debug: true
+}
+```
+
+---
+
+## Environment Detection
+
+The plugin automatically detects the environment:
+
+```typescript
+// Internal config detection
+if (apiUrl.includes('dev.forloop.cc')) {
+  environment = 'development';
+} else if (apiUrl.includes('api.forloop.cc')) {
+  environment = 'production';
+} else {
+  environment = 'custom';
+}
+```
+
+You'll see this in console output:
+```
+[ForLoop] Plugin initialized - development (https://api.dev.forloop.cc)
+```
+
+---
+
+## Quick Reference
+
+### Switch to Dev Environment
+
+```bash
+export FORLOOP_ALLOW_DEV=true
+export FORLOOP_API_URL=https://api.dev.forloop.cc
+```
+
+### Switch to Production
+
+```bash
+unset FORLOOP_API_URL  # Uses default production
+```
+
+### Check Current Config
+
+The plugin logs the environment on startup:
+```
+[ForLoop] Plugin initialized - development (https://api.dev.forloop.cc)
+```
+
+---
+
+## Best Practices
+
+### For Development
+- Use `FORLOOP_API_URL` environment variable
+- Enable debug mode for troubleshooting
+- Use dev API (`api.dev.forloop.cc`)
+- Store config in project `.env` (not committed to git)
+
+### For Production
+- Use default configuration (no env vars needed)
+- Default API is `api.forloop.cc`
+- Keep debug mode off
+- Document any custom configs for your team
+
+### For npm Distribution
+- Default to production in package
+- Allow override via env variables
+- Document all configuration options
+- Provide development setup instructions
+
+---
+
+## Troubleshooting
+
+### Wrong environment showing
+
+Check configuration priority:
+```bash
+echo "FORLOOP_API_URL: $FORLOOP_API_URL"
+echo "NODE_ENV: $NODE_ENV"
+cat opencode.json | grep -A5 "forloop"
+```
+
+### Can't connect to API
+
+Verify the endpoint:
+```bash
+curl -s https://api.dev.forloop.cc/health
+curl -s https://api.forloop.cc/health
+```
+
+### Config not loading
+
+Restart opencode after changing config:
+```bash
+# opencode caches plugins, restart to reload
+exit
+opencode
+```
+
+---
+
+## Advanced: Custom API Endpoint
+
+You can point to any API endpoint:
+
+```json
+{
+  "forloop": {
+    "apiUrl": "https://your-custom-api.example.com"
+  }
+}
+```
+
+This will be detected as `environment: 'custom'`.
+
+---
+
+## Environment Variables Summary
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `FORLOOP_API_URL` | Override API endpoint | `https://api.dev.forloop.cc` |
+| `NODE_ENV` | Auto-detect environment | `development` or `production` |
+| `FORLOOP_DEBUG` | Enable debug logging | `true` |
+| `DEV` | Shortcut for dev mode | `true` |
+
+---
+
+**Updated:** 2026-03-23
+**Version:** 2.0.0

package/docs/DEVELOPER-VS-USER.md

@@ -0,0 +1,129 @@
+# Developer vs User Perspective
+
+This document clarifies the difference between **developing** the plugin and **using** the plugin.
+
+## Plugin Development (You write TypeScript)
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│  Developer Workspace                                          │
+│                                                               │
+│  plugins/                                                    │
+│  ├── forloop-plugin.ts         ← Main entry point           │
+│  ├── tools/                                                   │
+│  │   ├── sprint-tools.ts       ← You edit these            │
+│  │   ├── story-tools.ts        ← TypeScript functions      │
+│  │   └── agent-tools.ts                                       │
+│  ├── capabilities/                                            │
+│  │   ├── api-client.ts         ← API calls                 │
+│  │   └── auth.ts               ← Authentication            │
+│  └── hooks/                                                   │
+│      └── shell-env.ts                                         │
+│                                                               │
+│  Development commands:                                        │
+│  - npm run test:unit         # Run tests                     │
+│  - npm run lint              # Check code quality            │
+│  - npm run install:local     # Install for testing           │
+│  - npm publish               # Publish to npm                │
+└──────────────────────────────────────────────────────────────┘
+```
+
+## Plugin Usage (You type commands in chat)
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│  User's opencode Chat                                         │
+│                                                               │
+│  $ opencode                                                   │
+│  ─────────────────────────────────────────────────────────   │
+│                                                               │
+│  You: forloopSprintList                                     │
+│       └─ Lists all sprints                                   │
+│                                                               │
+│  You: forloopStoryCreate                                    │
+│       --title "As a user, I want to login"                    │
+│       --sprintId 14                                           │
+│       └─ Creates a new story                                  │
+│                                                               │
+│  You: forloopAgentBreakdown --storyId 78                    │
+│       └─ Gets AI breakdown of story                          │
+│                                                               │
+│  You never see or touch the TypeScript code!                 │
+└──────────────────────────────────────────────────────────────┘
+```
+
+## Comparison Table
+
+| Aspect | Plugin Developer | Plugin User |
+|--------|-----------------|-------------|
+| **Edit TypeScript files** | ✅ Yes | ❌ No |
+| **Run npm commands** | ✅ Yes | ❌ No |
+| **Use `forloop.*` tools** | ✅ Yes (for testing) | ✅ Yes (main usage) |
+| **Need Node.js installed** | ✅ Yes | ⚠️ Only for opencode |
+| **Need opencode installed** | ✅ Yes | ✅ Yes |
+| **Need ForLoop account** | ✅ Yes | ✅ Yes |
+| **Read this plugin's code** | ✅ Yes | ❌ No |
+
+## Installation Paths
+
+### Developers (Full Setup)
+```bash
+# Clone repository
+git clone https://github.com/forloop-cc/forloop-opencode-plugin.git
+
+# Install dependencies
+cd forloop-opencode-plugin
+npm install
+
+# Run tests
+npm test
+
+# Install locally for development
+npm run install:local
+
+# Test in opencode
+opencode
+> forloopSprintList
+```
+
+### Users (Simple Setup)
+```bash
+# Option 1: One-line install
+curl -fsSL https://raw.githubusercontent.com/forloop-cc/forloop-opencode-plugin/main/install.sh | bash
+
+# Option 2: npm
+npm install @forloop/opencode-plugin
+
+# Then just use in opencode
+opencode
+> forloopSprintList
+```
+
+## When Do You Need TypeScript Knowledge?
+
+| Scenario | TypeScript Required? |
+|----------|---------------------|
+| Using existing tools | ❌ No |
+| Creating new stories | ❌ No |
+| Managing sprints | ❌ No |
+| Getting AI suggestions | ❌ No |
+| **Adding new tools** | ✅ Yes |
+| **Modifying existing tools** | ✅ Yes |
+| **Contributing to plugin** | ✅ Yes |
+| **Fixing bugs in plugin** | ✅ Yes |
+
+## Summary
+
+**As a USER:**
+- Think of this like a "skill" or "power-up" for opencode
+- You just use the commands in chat
+- No coding required
+
+**As a DEVELOPER:**
+- You're extending opencode's capabilities
+- You write TypeScript that opencode will execute
+- You test, publish, and maintain the plugin
+
+---
+
+**Questions?** See [How Users Interact](USER-INTERACTION-MODEL.md) for more details.