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

package/docs/PLUGIN-ARCHITECTURE.md

@@ -0,0 +1,308 @@
+# ForLoop Plugin Architecture
+
+## Understanding opencode Plugin Storage
+
+This document clarifies where plugin files are stored and how opencode manages plugins.
+
+---
+
+## Plugin Storage Locations
+
+### 🤔 Why Don't You See Files in `./.opencode/` or `~/.config/opencode/`?
+
+**Short answer:** opencode caches plugins elsewhere!
+
+### ✅ Actual Storage Locations
+
+| Location | Purpose | Example Path |
+|----------|---------|--------------|
+| **Plugin Cache** | Where installed plugins live | `~/.cache/opencode/node_modules/` |
+| **Global Config** | Plugin configuration | `~/.config/opencode/opencode.json` |
+| **Project Config** | Project-specific settings | `./opencode.json` |
+| **Plugin State** | Runtime state, tokens | `~/.local/state/opencode/` |
+| **Plugin Data** | Persistent data | `~/.local/share/opencode/` |
+
+---
+
+## How It Works
+
+### 1. Configuration (You Specify)
+
+```json
+{
+  "plugin": ["superpowers@git+https://github.com/obra/superpowers.git"]
+}
+```
+
+This tells opencode: "Install and use the superpowers plugin from this git repo"
+
+### 2. Installation (opencode Handles)
+
+When opencode starts:
+1. Reads `opencode.json` (global or project)
+2. Downloads plugin to cache: `~/.cache/opencode/node_modules/superpowers/`
+3. Loads plugin from cache (not from your project)
+
+### 3. Runtime (Auto-managed)
+
+Plugin loads from cache location automatically. You don't need to know where it is!
+
+---
+
+## Directory Structure
+
+### For Users (What You See)
+
+```
+your-project/
+├── opencode.json          # Plugin configuration
+└── .opencode/             # Your custom skills/hooks (optional)
+    └── skills/            # Your personal skills
+```
+
+### Actually Stored (Hidden from You)
+
+```
+~/.cache/opencode/
+└── node_modules/
+    ├── superpowers/       # Superpowers plugin cached here
+    │   ├── .opencode/
+    │   │   └── plugins/
+    │   │       └── superpowers.js
+    │   ├── skills/
+    │   └── package.json
+    └── @forloop/
+        └── opencode-plugin/  # ForLoop plugin would be here
+
+~/.config/opencode/
+├── opencode.json          # Global configuration
+└── tokens.json            # API tokens
+
+~/.local/state/opencode/   # Runtime state
+~/.local/share/opencode/   # Persistent data
+```
+
+---
+
+## Why This Architecture?
+
+### Benefits
+
+1. **Clean Projects** - No plugin clutter in your codebase
+2. **Global Caching** - Plugins shared across projects
+3. **Auto Updates** - opencode manages plugin versions
+4. **No Symlinks** - No manual file management needed
+5. **Secure** - Tokens stored in user directory, not project
+
+### How It Differs from Traditional npm
+
+**Traditional npm:**
+```
+project/
+├── node_modules/          # Dependencies in project
+│   └── package-name/
+└── package.json
+```
+
+**opencode plugins:**
+```
+~/.cache/opencode/node_modules/  # Shared cache
+└── plugin-name/
+
+project/
+└── opencode.json          # Just configuration
+```
+
+---
+
+## ForLoop Plugin Structure
+
+### Distribution Package
+
+When you install ForLoop plugin via npm or git:
+
+```json
+{
+  "plugin": ["forloop@git+https://github.com/forloop-cc/forloop-opencode-plugin.git"]
+}
+```
+
+**What happens:**
+1. opencode clones to cache: `~/.cache/opencode/node_modules/@forloop/opencode-plugin/`
+2. Loads plugin from cache
+3. Makes tools available in your session
+
+**Package contents:**
+```
+@forloop/opencode-plugin/
+├── plugins/
+│   ├── forloop-plugin.ts          # Main entry
+│   ├── capabilities/
+│   │   ├── config.ts
+│   │   ├── token-storage.ts
+│   │   └── api-client.ts
+│   ├── tools/
+│   │   ├── sprint-tools.ts
+│   │   ├── story-tools.ts
+│   │   └── agent-suggestion-tools.ts
+│   └── hooks/
+│       └── shell-env.ts
+├── skills/
+│   └── forloop-skill.md
+└── package.json
+```
+
+**But you don't need to manage this!** opencode handles it.
+
+---
+
+## Development vs Production
+
+### Development (Your Current Setup)
+
+You have symlinks in your project:
+```
+~/projects/forloop/
+├── .opencode/plugins -> ../forloop-opencode/plugins
+├── forloop-opencode/         # Source code
+└── opencode.json
+```
+
+This is **only for development** - you're manually linking to test changes.
+
+### Production (npm/git installation)
+
+Users just specify in `opencode.json`:
+```json
+{
+  "plugin": ["forloop@git+https://github.com/forloop-cc/forloop-opencode-plugin.git"]
+}
+```
+
+And opencode:
+1. Downloads to cache
+2. Manages updates
+3. Loads automatically
+
+Users **never see the plugin files** - they just use the tools!
+
+---
+
+## Common Questions
+
+### Q: Where are my plugin files?
+
+**A:** In `~/.cache/opencode/node_modules/@forloop/opencode-plugin/`
+
+To check:
+```bash
+ls -la ~/.cache/opencode/node_modules/@forloop/opencode-plugin/
+```
+
+### Q: Do I need to copy plugin files to my project?
+
+**A:** No! Just configure in `opencode.json`:
+```json
+{
+  "plugin": ["forloop@git+https://github.com/forloop-cc/forloop-opencode-plugin.git"]
+}
+```
+
+### Q: How do I update plugins?
+
+**A:** opencode auto-updates git plugins on restart. For npm:
+```bash
+npm update @forloop/opencode-plugin
+```
+
+### Q: Where are tokens stored?
+
+**A:** `~/.config/forloop/tokens.json` (global, not in project)
+
+### Q: Can I have project-specific plugins?
+
+**A:** Yes! Project `opencode.json` overrides global config.
+
+---
+
+## Comparison: Superpowers vs ForLoop
+
+### Superpowers Installation
+
+```json
+{
+  "plugin": ["superpowers@git+https://github.com/obra/superpowers.git"]
+}
+```
+
+**Stored in:** `~/.cache/opencode/node_modules/superpowers/`
+
+**Visible to user:** Only the tools (`skill` tool for using superpowers skills)
+
+### ForLoop Installation
+
+```json
+{
+  "plugin": ["forloop@git+https://github.com/forloop-cc/forloop-opencode-plugin.git"]
+}
+```
+
+**Stored in:** `~/.cache/opencode/node_modules/@forloop/opencode-plugin/`
+
+**Visible to user:** Only the tools (`forloopSprintList`, etc.)
+
+### What You See as a User
+
+Both plugins:
+- ✅ Appear in opencode tool list
+- ✅ Can be used naturally ("List my sprints")
+- ✅ Automatically loaded on startup
+- ❌ **No files in your project folder** (by design!)
+
+---
+
+## For Plugin Developers
+
+### What to Distribute
+
+Your plugin package should include:
+
+```
+your-plugin/
+├── plugins/
+│   └── your-plugin.ts      # Main entry point
+├── package.json            # npm package config
+└── README.md               # Documentation
+```
+
+### What Users See
+
+Users only need to add one line to their `opencode.json`:
+
+```json
+{
+  "plugin": ["your-plugin@git+https://github.com/you/your-plugin.git"]
+}
+```
+
+Everything else is automatic!
+
+---
+
+## Summary
+
+| Aspect | Location | Managed By |
+|--------|----------|------------|
+| Plugin Code | `~/.cache/opencode/node_modules/` | opencode |
+| Configuration | `opencode.json` (project or global) | You |
+| Tokens | `~/.config/forloop/tokens.json` | Plugin |
+| State | `~/.local/state/opencode/` | opencode |
+| Your Skills | `./.opencode/skills/` (optional) | You |
+
+**Key Takeaway:** opencode plugins are **hidden by design** - you configure them in `opencode.json` and use their tools, but don't manage files directly.
+
+---
+
+**Updated:** 2026-03-23
+**Version:** 2.0.0
+

package/docs/QUICKSTART-NON-DEV.md

@@ -0,0 +1,94 @@
+# Quick Start for Non-Developers
+
+**No coding required!** This guide is for users who just want to use the plugin, not develop it.
+
+## Prerequisites (5 minutes)
+
+1. **Install opencode** (free, open-source)
+   ```bash
+   curl -fsSL https://opencode.ai/install.sh | bash
+   ```
+
+2. **Create ForLoop account**
+   - Go to [forloop.cc](https://forloop.cc)
+   - Sign up for free
+
+3. **Create API token**
+   - Go to [forloop.cc/profile?tab=api-tokens](https://forloop.cc/profile?tab=api-tokens)
+   - Click "Create New Token"
+   - Select scopes: `sprint:read`, `sprint:write`, `story:read`, `story:write`, `agent:query`, `profile:read`
+   - Copy the token (starts with `floop_`)
+
+## Install Plugin (2 options)
+
+### Option 1: One-Line Install (Easiest)
+```bash
+curl -fsSL https://raw.githubusercontent.com/forloop-cc/forloop-opencode-plugin/main/install.sh | bash
+```
+
+### Option 2: npm Install
+```bash
+npm install @forloop/opencode-plugin
+```
+
+## Set Your Token
+
+In opencode chat, run:
+```
+forloopTokenSet --token floop_YOUR_TOKEN_HERE
+```
+
+## You're Ready! 🎉
+
+Just use commands in opencode chat:
+
+### List Sprints
+```
+forloopSprintList
+```
+
+### Create a Story
+```
+forloopStoryCreate --title "As a user, I want to login" --sprintId 14 --priority high
+```
+
+### Get AI Help
+```
+forloopAgentBreakdown --storyId 78
+```
+
+## Common Commands Cheat Sheet
+
+| What You Want to Do | Command |
+|---------------------|---------|
+| See all sprints | `forloopSprintList` |
+| See sprint details | `forloopSprintGet --sprintId 14` |
+| Create story | `forloopStoryCreate --title "..." --sprintId 14` |
+| Update story | `forloopStoryUpdate --storyId 78 --status done` |
+| Get AI breakdown | `forloopAgentBreakdown --storyId 78` |
+| Get AI estimate | `forloopAgentEstimate --storyId 78` |
+| Check your token | `forloopTokenGet` |
+
+## That's It!
+
+**You don't need to:**
+- ❌ Know TypeScript
+- ❌ Run npm commands
+- ❌ Edit code
+- ❌ Understand plugin architecture
+
+**Just:**
+- ✅ Install opencode
+- ✅ Install plugin
+- ✅ Set token
+- ✅ Use commands in chat
+
+## Need Help?
+
+- **FAQ**: See [README.md](../README.md#faq)
+- **Full Documentation**: [docs/](../docs/)
+- **Issues**: [GitHub Issues](https://github.com/forloop-cc/forloop-opencode-plugin/issues)
+
+---
+
+**For Developers:** If you want to modify or extend the plugin, see [Developer vs User](DEVELOPER-VS-USER.md).

package/docs/README-FOR-HUMANS-AND-AI.md

@@ -0,0 +1,109 @@
+# Documentation for Both Humans and AI
+
+## Understanding This Plugin's Documentation
+
+The ForLoop opencode plugin documentation is designed to be read by **both humans and AI agents**.
+
+### Usage Examples Section - Who Is It For?
+
+**Both! Here's how each uses it:**
+
+#### For AI Agents 🤖
+
+The Usage Examples section helps AI understand:
+- **Tool invocation syntax**: How to properly call each tool
+- **Parameter patterns**: Which arguments are required vs optional
+- **Context matching**: When to suggest which tool based on user requests
+
+**Example AI behavior:**
+```
+User: "How do I break down this story?"
+AI reads docs → Finds forloopAgentBreakdown → Suggests: 
+"Use: forloopAgentBreakdown --storyId 456"
+```
+
+#### For Humans 👤
+
+The same section helps humans:
+- **Quick reference**: Copy-paste ready commands
+- **Parameter guide**: See what options are available
+- **Learning pattern**: Understand tool capabilities
+
+**Example human use:**
+```bash
+# Copy from docs, modify for your needs
+forloopAgentBreakdown --storyId 456
+```
+
+---
+
+## Documentation Layers
+
+### Layer 1: Quick Installation (Human-focused)
+
+```json
+{
+  "plugin": ["forloop@git+https://github.com/forloop-cc/forloop-opencode-plugin.git"]
+}
+```
+
+**Purpose**: Get started in 10 seconds
+
+### Layer 2: Tool Tables (AI-parseable)
+
+```markdown
+| Tool | Description |
+|------|-------------|
+| `forloopStoryCreate` | Create a new story |
+```
+
+**Purpose**: Easy lookup for both humans and AI
+
+### Layer 3: Usage Examples (Dual-purpose)
+
+```bash
+forloopStoryCreate --title "Feature" --sprintId 123
+```
+
+**Purpose**: 
+- AI learns invocation patterns
+- Humans get copy-paste templates
+
+### Layer 4: Context Notes (AI decision-making)
+
+```markdown
+**When to use:**
+- User wants to create a story
+- User has sprint context
+```
+
+**Purpose**: Helps AI decide when to suggest tools
+
+---
+
+## For Plugin Authors
+
+When writing documentation for opencode plugins:
+
+1. **Structure consistently** - Headers, tables, code blocks
+2. **Be explicit** - Clear parameter descriptions
+3. **Include examples** - For both AI learning and human reference
+4. **Add usage context** - "When to use" sections help AI
+
+---
+
+## For Users
+
+Don't worry about AI reading the docs! The documentation is:
+- ✅ **Human-readable** first
+- ✅ **AI-parseable** to enhance help
+- ✅ **Search-friendly** for both
+
+When you ask "How do I use ForLoop?", opencode reads this to:
+1. Find relevant tools
+2. Show correct syntax
+3. Guide you through the process
+
+---
+
+**Summary**: Usage Examples are for **both** - AI learns how to invoke tools, humans get ready-to-use commands! 🎯

package/docs/README.md

@@ -0,0 +1,70 @@
+# ForLoop Plugin Documentation
+
+Welcome to the ForLoop Plugin documentation. This folder contains comprehensive guides for using and contributing to the plugin.
+
+## 🚀 Quick Links
+
+**Just want to use the plugin?**
+- 👉 [Quick Start for Non-Developers](QUICKSTART-NON-DEV.md) - Start here!
+- 📖 [How Users Interact](USER-INTERACTION-MODEL.md) - Understand the architecture
+- 👥 [Developer vs User](DEVELOPER-VS-USER.md) - Which are you?
+
+## 📖 Documentation Structure
+
+### Getting Started
+- [Installation Guide](installation/) - Install the plugin
+- [Quick Start](../README.md#quick-start) - Get up and running fast
+- [Configuration](CONFIGURATION.md) - Configure the plugin
+
+### Tool Reference
+- [Sprint Tools](tools/sprints.md) - Sprint management operations
+- [Story Tools](tools/stories.md) - Story CRUD operations
+- [Agent Tools](tools/agents.md) - AI agent interactions
+- [File Tools](tools/files.md) - File upload and management
+
+### Skills
+- [Skills Overview](skills/overview.md) - Understanding skills
+- [Creating Skills](skills/creating-skills.md) - Build your own skills
+- [Skill Reference](skills/skill-reference.md) - All available skills
+
+### Agents
+- [Agents Overview](agents/overview.md) - Understanding agents
+- [Creating Agents](agents/creating-agents.md) - Build custom agents
+
+### Contributing
+- [Contributing Guide](contributing/guide.md) - How to contribute
+- [Code Style](contributing/code-style.md) - Coding standards
+- [Testing Guide](contributing/testing.md) - Writing tests
+
+### API Reference
+- [API Specification](API_SPECIFICATION.md) - API endpoints
+- [Error Codes](api/error-codes.md) - Error reference
+
+## 📚 Key Documents
+
+| Document | Description |
+|----------|-------------|
+| [README](../README.md) | User documentation and quick start |
+| [CONTRIBUTING](../CONTRIBUTING.md) | Contribution guidelines |
+| [CHANGELOG](../CHANGELOG.md) | Version history and changes |
+| [STRUCTURE](../STRUCTURE.md) | Project structure overview |
+| [SECURITY](../SECURITY.md) | Security policy |
+
+## 🆘 Need Help?
+
+- **Issues**: [GitHub Issues](https://github.com/forloop-cc/forloop-opencode-plugin/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/forloop-cc/forloop-opencode-plugin/discussions)
+- **Website**: [forloop.cc](https://forloop.cc)
+
+## 📝 Documentation Guidelines
+
+When adding documentation:
+- Use clear, concise language
+- Include code examples where relevant
+- Link to related documents
+- Keep formatting consistent
+- Update the table of contents
+
+---
+
+*Last updated: 2026-04-17*