@bluefly/openstandardagents 0.1.9

package/.cursor/plans/ossa-enterprise-transformation-plan-0ccaf09b.plan.md

@@ -0,0 +1,373 @@
+<!-- 0ccaf09b-7f4d-4214-b67a-df52fb223782 8c04fcd7-2d58-4707-a5a4-c51db90f0a76 -->
+# Open Standard Agents (OSA) — Enterprise Transformation Plan
+
+## CRITICAL FOCUS: OSSA Schema Enhancement for v0.2.3 Release
+
+The schema is THE GOLD. It must be bulletproof, comprehensive, and integrate seamlessly with all major agent platforms before v0.2.3 release.
+
+## GitLab Issue → MR → Worktree Workflow (Sequential)
+
+### Pre-Setup: Sync All Branches
+
+**TODO: Pull latest from all branches before starting**
+
+- [ ] **Fetch all remote branches**:
+  ```bash
+  git fetch --all --prune
+  ```
+
+- [ ] **Pull latest from main branch**:
+  ```bash
+  git checkout main
+  git pull origin main
+  ```
+
+- [ ] **Pull latest from development branch**:
+  ```bash
+  git checkout development
+  git pull origin development
+  ```
+
+- [ ] **Pull latest from all feature branches**:
+  ```bash
+  git branch -r | grep -v '\->' | while read remote; do git branch --track "${remote#origin/}" "$remote" 2>/dev/null || true; done
+  git fetch --all
+  git pull --all
+  ```
+
+
+### Worktree Setup (Sequential - Each Phase Builds on Previous)
+
+#### Phase 1 Worktree Setup
+
+**TODO: Create Phase 1 worktree with all latest changes merged**
+
+- [ ] **Create GitLab Issue #1**: "Phase 1: OSSA Schema Deep Analysis & Enhancement"
+  - Include all Phase 1 TODOs
+  - Assign to milestone: v0.2.4
+  - Add labels: `schema`, `enhancement`, `critical`, `v0.2.3`
+- [ ] **Click "Create merge request"** on Issue #1
+  - GitLab creates branch: `issue-1-phase-1-ossa-schema-deep-analysis-enhancement`
+  - Target branch: `development`
+- [ ] **Set up Phase 1 worktree**:
+  ```bash
+  # Fetch the new branch
+  git fetch origin issue-1-phase-1-ossa-schema-deep-analysis-enhancement
+  
+  # Create worktree with all latest changes merged
+  git worktree add ~/.cursor/worktrees/open-standard-agents/issue-1-phase-1-ossa-schema-deep-analysis-enhancement issue-1-phase-1-ossa-schema-deep-analysis-enhancement
+  
+  # Switch to worktree
+  cd ~/.cursor/worktrees/open-standard-agents/issue-1-phase-1-ossa-schema-deep-analysis-enhancement
+  
+  # Merge latest from development
+  git merge origin/development
+  
+  # Merge latest from main (if needed)
+  git merge origin/main --no-edit || true
+  
+  # Push merged branch
+  git push origin issue-1-phase-1-ossa-schema-deep-analysis-enhancement
+  ```
+
+- [ ] **Work in Phase 1 worktree**: `~/.cursor/worktrees/open-standard-agents/issue-1-phase-1-ossa-schema-deep-analysis-enhancement`
+
+#### Phase 2 Worktree Setup (Branches from Phase 1)
+
+**TODO: Create Phase 2 worktree branching from Phase 1**
+
+- [ ] **Create GitLab Issue #2**: "Phase 2: Schema Testing & Validation Infrastructure"
+  - Include all Phase 2 TODOs
+  - Assign to milestone: v0.2.5
+  - Add labels: `testing`, `validation`, `critical`, `v0.2.3`
+  - Set dependency: Depends on Issue #1
+- [ ] **Click "Create merge request"** on Issue #2
+  - GitLab creates branch: `issue-2-phase-2-schema-testing-validation-infrastructure`
+  - Target branch: `issue-1-phase-1-ossa-schema-deep-analysis-enhancement` (branches from Phase 1!)
+- [ ] **Set up Phase 2 worktree**:
+  ```bash
+  # Fetch Phase 2 branch
+  git fetch origin issue-2-phase-2-schema-testing-validation-infrastructure
+  
+  # Create worktree branching from Phase 1 worktree
+  cd ~/.cursor/worktrees/open-standard-agents/issue-1-phase-1-ossa-schema-deep-analysis-enhancement
+  git worktree add -b issue-2-phase-2-schema-testing-validation-infrastructure ~/.cursor/worktrees/open-standard-agents/issue-2-phase-2-schema-testing-validation-infrastructure
+  
+  # Switch to Phase 2 worktree
+  cd ~/.cursor/worktrees/open-standard-agents/issue-2-phase-2-schema-testing-validation-infrastructure
+  
+  # Ensure it's based on Phase 1
+  git merge issue-1-phase-1-ossa-schema-deep-analysis-enhancement --no-edit
+  
+  # Push Phase 2 branch
+  git push origin issue-2-phase-2-schema-testing-validation-infrastructure
+  ```
+
+- [ ] **Work in Phase 2 worktree**: `~/.cursor/worktrees/open-standard-agents/issue-2-phase-2-schema-testing-validation-infrastructure`
+
+#### Phase 3 Worktree Setup (Branches from Phase 2)
+
+**TODO: Create Phase 3 worktree branching from Phase 2**
+
+- [ ] **Create GitLab Issue #3**: "Phase 3: Complete Rebranding (OSSA → OSA)"
+  - Include all Phase 3 TODOs
+  - Assign to milestone: v0.2.4
+  - Add labels: `rebranding`, `chore`, `high`, `v0.2.3`
+- [ ] **Click "Create merge request"** on Issue #3
+  - GitLab creates branch: `issue-3-phase-3-complete-rebranding`
+  - Target branch: `issue-2-phase-2-schema-testing-validation-infrastructure` (branches from Phase 2!)
+- [ ] **Set up Phase 3 worktree**:
+  ```bash
+  # Create worktree branching from Phase 2 worktree
+  cd ~/.cursor/worktrees/open-standard-agents/issue-2-phase-2-schema-testing-validation-infrastructure
+  git worktree add -b issue-3-phase-3-complete-rebranding ~/.cursor/worktrees/open-standard-agents/issue-3-phase-3-complete-rebranding
+  
+  cd ~/.cursor/worktrees/open-standard-agents/issue-3-phase-3-complete-rebranding
+  git merge issue-2-phase-2-schema-testing-validation-infrastructure --no-edit
+  git push origin issue-3-phase-3-complete-rebranding
+  ```
+
+
+#### Phase 4-7 Worktree Setup (Each Branches from Previous)
+
+**TODO: Continue sequential worktree pattern**
+
+- [ ] **Phase 4**: Branch from Phase 3
+- [ ] **Phase 5**: Branch from Phase 4
+- [ ] **Phase 6**: Branch from Phase 5
+- [ ] **Phase 7**: Branch from Phase 6
+
+### Worktree Directory Structure
+
+```
+~/.cursor/worktrees/
+└── open-standard-agents/
+    ├── issue-1-phase-1-ossa-schema-deep-analysis-enhancement/  (base)
+    ├── issue-2-phase-2-schema-testing-validation-infrastructure/  (branches from #1)
+    ├── issue-3-phase-3-complete-rebranding/  (branches from #2)
+    ├── issue-4-phase-4-cli-enhancement/  (branches from #3)
+    ├── issue-5-phase-5-website-development/  (branches from #4)
+    ├── issue-6-phase-6-testing-infrastructure/  (branches from #5)
+    └── issue-7-phase-7-gitlab-cicd-project-management/  (branches from #6)
+```
+
+### Workflow Script
+
+**TODO: Create automated worktree setup script**
+
+- [ ] Create `.gitlab/scripts/setup-sequential-worktree.sh`:
+  ```bash
+  #!/bin/bash
+  # Usage: ./setup-sequential-worktree.sh <ISSUE_NUMBER> [PARENT_WORKTREE_PATH]
+  # Sets up worktree branching from previous phase
+  
+  ISSUE_NUM=$1
+  PARENT_WORKTREE=$2  # Optional: path to parent worktree
+  
+  # Fetch all branches first
+  git fetch --all --prune
+  
+  # Get issue details from GitLab API
+  # Create branch name
+  # Create worktree branching from parent
+  # Merge latest changes
+  ```
+
+
+## Phase 1: OSSA Schema Deep Analysis & Enhancement (WEEK 1 - CRITICAL)
+
+[All Phase 1 detailed TODOs - schema audit, platform integration, validation, documentation]
+
+## Phase 2: Schema Testing & Validation Infrastructure (WEEK 2 - CRITICAL)
+
+[All Phase 2 detailed TODOs - test suite, validation service enhancement]
+
+## Phase 3: Complete Rebranding (WEEK 1-2)
+
+[All Phase 3 detailed TODOs - repository updates, codebase rebranding]
+
+## Phase 4: CLI Enhancement (WEEK 3)
+
+[All Phase 4 detailed TODOs - CLI commands implementation]
+
+## Phase 5: Website Development (WEEK 4-5)
+
+[All Phase 5 detailed TODOs - schema explorer, documentation]
+
+## Phase 6: Testing Infrastructure (WEEK 6)
+
+[All Phase 6 detailed TODOs - test coverage expansion]
+
+## Phase 7: GitLab CI/CD & Project Management (WEEK 7)
+
+[All Phase 7 detailed TODOs - GitLab setup, CI/CD pipeline]
+
+## Success Metrics
+
+- ✅ All worktrees set up sequentially
+- ✅ Each phase builds on previous phase
+- ✅ All branches synced before starting
+- ✅ MRs auto-close issues when merged
+- ✅ Schema is bulletproof for v0.2.3 release
+
+## Deployment Steps: GitLab and GitHub Mirroring Setup
+
+**NOTE: Do NOT deploy to GitHub yet - these are setup instructions for future deployment**
+
+### Step 1: Commit and Push to GitLab
+
+```bash
+# Commit all changes
+git add .
+git commit -m "chore: setup GitHub mirroring and clean project structure"
+
+# Push to GitLab
+git push origin development
+```
+
+### Step 2: Create GitHub Repository
+
+1. Go to https://github.com/BlueflyCollective
+2. Click "New repository"
+3. Repository name: `OSSA` (or your preferred name)
+4. Description: "OSSA - Open Standard for Scalable AI Agents"
+5. Visibility: Public
+6. Do NOT initialize with README, .gitignore, or license
+7. Click "Create repository"
+
+### Step 3: Generate GitHub Personal Access Token
+
+1. Go to: https://github.com/settings/tokens
+2. Click "Generate new token (classic)"
+3. Name: `GitLab Mirror - OSSA`
+4. Expiration: Set appropriate expiration (or no expiration)
+5. Scopes: Check `repo` (Full control of private repositories)
+6. Click "Generate token"
+7. Copy the token immediately (you won't see it again)
+
+### Step 4: Configure GitLab Push Mirroring
+
+1. Go to your GitLab project: `https://gitlab.bluefly.io/llm/openstandardagents/-/settings/repository`
+2. Scroll to "Mirroring repositories"
+3. Expand "Push to a remote repository"
+4. Configure:
+
+   - **Git repository URL**: `https://github.com/BlueflyCollective/OSSA.git`
+   - **Mirror direction**: Push
+   - **Authentication method**: Password
+   - **Password**: Paste your GitHub PAT (not your GitHub password)
+   - **Branch filter**: `^(main|development)$`
+   - **Only mirror protected branches**: Unchecked
+   - **Keep divergent refs**: Unchecked
+
+5. Click "Mirror repository"
+6. Click "Trigger" button to perform initial sync
+
+### Step 5: Configure GitLab CI/CD Variables
+
+1. Go to: `https://gitlab.bluefly.io/llm/openstandardagents/-/settings/ci_cd`
+2. Expand "Variables"
+3. Click "Add variable"
+4. Add these variables:
+
+**Variable 1:**
+
+   - Key: `GITHUB_MIRROR_TOKEN`
+   - Value: Your GitHub PAT
+   - Type: Variable
+   - Environment scope: All
+   - Flags: ✅ Protected, ✅ Masked
+   - Click "Add variable"
+
+**Variable 2 (Optional):**
+
+   - Key: `GITHUB_ORG`
+   - Value: `BlueflyCollective`
+   - Type: Variable
+   - Flags: ✅ Protected
+   - Click "Add variable"
+
+**Variable 3 (Optional):**
+
+   - Key: `GITHUB_REPO`
+   - Value: `OSSA` (or your repo name)
+   - Type: Variable
+   - Flags: ✅ Protected
+   - Click "Add variable"
+
+### Step 6: Initial Sync of Existing Branches and Tags
+
+Run these commands locally:
+
+```bash
+# Add GitHub as a remote
+git remote add github https://github.com/BlueflyCollective/OSSA.git
+
+# Push main branch
+git push github main
+
+# Push development branch
+git push github development
+
+# Push all tags
+git push github --tags
+```
+
+### Step 7: Verify Setup
+
+1. Check GitLab mirror status:
+
+   - Go to: Settings → Repository → Mirroring repositories
+   - Verify status shows "Success" or "Running"
+
+2. Verify GitHub repository:
+
+   - Go to: https://github.com/BlueflyCollective/OSSA
+   - Verify `main` and `development` branches exist
+   - Verify tags are present
+
+3. Test automatic mirroring:
+
+   - Make a small commit to `development` branch
+   - Push to GitLab: `git push origin development`
+   - Wait 30-60 seconds
+   - Check GitHub - the commit should appear automatically
+
+4. Test release synchronization:
+
+   - Create a tag in GitLab: `git tag v0.2.4 -m "Test release"`
+   - Push tag: `git push origin v0.2.4`
+   - The CI/CD pipeline will automatically create a GitHub release
+
+### Step 8: Monitor and Maintain
+
+- GitLab mirror status: Check periodically in Settings → Repository → Mirroring repositories
+- CI/CD logs: Check pipeline logs for `mirror:github` job
+- GitHub releases: Verify releases are created automatically when tags are pushed
+
+## How It Works
+
+1. Branch mirroring: GitLab push mirroring automatically syncs `main` and `development` branches to GitHub on every push
+2. Tag mirroring: All tags are automatically synced via GitLab push mirroring
+3. Release synchronization: The CI/CD `mirror:github` job creates GitHub releases when tags are created, syncing release notes from GitLab releases or CHANGELOG.md
+
+## Troubleshooting
+
+- Mirror not syncing: Check mirror status in GitLab, verify GitHub PAT has correct permissions, click "Trigger" to manually sync
+- CI job failing: Check `GITHUB_MIRROR_TOKEN` is set correctly, verify GitHub repository exists, check CI/CD job logs
+- Releases not syncing: Verify tag exists on GitHub, check CI/CD job logs, ensure GitLab release exists (if using GitLab releases)
+
+The project is now set up for automated mirroring between GitLab and GitHub.
+
+### To-dos
+
+- [ ] Resolve v1.0 vs v0.2.3 conflict, merge forward-compatible features, create migration path
+- [ ] Create .agents/ and .cursor/ directories, migrate assets/ and openapi/ to public/, reorganize docs/
+- [ ] Add init, export, import, schema, docs, examples commands with framework support
+- [ ] Create comprehensive examples for Cursor, BuildKit, CrewAI, LangChain, Langflow, OpenAI, Anthropic, MCP, AutoGen, LangGraph, Vercel AI SDK, LlamaIndex
+- [ ] Expand test coverage to 95%+, add framework compatibility tests, integration tests, contract tests
+- [ ] Enhance GitLab CI/CD with quality gates, components, security scanning, performance benchmarks
+- [ ] Build comprehensive Next.js website with schema explorer, docs, examples gallery, playground
+- [ ] Create technical documentation with parameter breakdowns, framework guides, migration guides, troubleshooting
+- [ ] Migrate assets/ and openapi/ to public/, organize schemas and examples for public access
+- [ ] Final code quality review, documentation accuracy check, security audit, performance optimization

package/.cursor/plans/ossa-milestone-organization-and-v0-2-4-release-6dafa4ec.plan.md

@@ -0,0 +1,214 @@
+<!-- 6dafa4ec-9743-4ced-ba80-9a9b0ed7bd06 5a59e316-a66c-420b-9757-7f356aefc6d1 -->
+# OSSA Agent Folder Structure Standard
+
+## Overview
+
+Define a simple, standard folder structure convention for organizing OSSA agents in projects. Similar to how OpenAPI defines where spec files go, OSSA defines where agent manifests go. Tools can then discover agents by scanning these standard locations.
+
+## Standard Definition
+
+### Folder Structure Convention
+
+```
+project-root/
+├── .agents/                    # Project-level agents (version controlled)
+│   └── agent-name/            # Each agent in its own folder
+│       ├── agent.ossa.yaml    # Required: OSSA manifest (or agent.yml)
+│       ├── README.md          # Recommended: Agent documentation
+│       └── data/              # Optional: Agent-specific data files
+│
+└── modules/                    # Example: Drupal modules
+    └── custom-module/
+        └── .agents/           # Module-specific agents
+            └── module-agent/
+                ├── agent.ossa.yaml
+                └── README.md
+```
+
+### Agent Folder Contents
+
+**Required:**
+
+- `agent.ossa.yaml` or `agent.yml` - OSSA manifest file
+
+**Recommended:**
+
+- `README.md` - What the agent does, how to use it
+
+**Optional:**
+
+- `data/` - JSON schemas, example data, configuration files
+- `tests/` - Agent-specific tests
+- `examples/` - Usage examples
+
+### Workspace Discovery (Optional)
+
+For workspace-level orchestration:
+
+```
+project-root/
+└── .agents-workspace/         # Workspace registry (NOT version controlled)
+    └── registry.json          # Auto-generated agent index
+```
+
+## Implementation Plan
+
+### Phase 1: Document the Standard
+
+1. **Create agent folder structure spec**
+
+   - File: `docs/agent-folder-structure.md`
+   - Define required vs optional files
+   - Document naming conventions
+   - Keep it simple - just the convention
+
+2. **Update Project Structure docs**
+
+   - File: `website/content/docs/core-concepts/Project-Structure.md`
+   - Add agent folder structure section
+   - Show Drupal-like ecosystem example
+   - Explain discovery pattern (tools scan for `.agents/` folders)
+
+### Phase 2: Create Multi-Ecosystem Examples
+
+1. **Drupal example**
+
+   - File: `examples/drupal/module-with-agents/`
+   - Show module with `.agents/` folder
+   - Demonstrate discovery pattern
+
+2. **WordPress example**
+
+   - File: `examples/wordpress/plugin-with-agents/`
+   - Show plugin with `.agents/` folder
+   - WordPress-specific agent patterns
+
+3. **Laravel example**
+
+   - File: `examples/laravel/package-with-agents/`
+   - Show Laravel package with `.agents/` folder
+   - Service provider integration
+
+4. **React/Next.js example**
+
+   - File: `examples/react/component-with-agents/`
+   - Show React component library with `.agents/` folder
+   - Component-level agents
+
+5. **Python package example**
+
+   - File: `examples/python/package-with-agents/`
+   - Show Python package with `.agents/` folder
+   - Package distribution pattern
+
+6. **Node.js/npm example**
+
+   - File: `examples/nodejs/package-with-agents/`
+   - Show npm package with `.agents/` folder
+   - Package.json integration
+
+7. **Monorepo example**
+
+   - File: `examples/monorepo/workspace-agents/`
+   - Show workspace-level `.agents-workspace/` with multiple packages
+   - Cross-package agent discovery
+
+### Phase 3: Documentation
+
+1. **Workspace Discovery guide**
+
+   - File: `website/content/docs/core-concepts/Workspace-Discovery.md`
+   - Explain the standard (not implementation)
+   - Show examples across ecosystems
+   - Document how tools discover agents
+
+2. **Ecosystem-specific guides**
+
+   - File: `website/content/docs/ecosystems/drupal-agents.md`
+   - File: `website/content/docs/ecosystems/wordpress-agents.md`
+   - File: `website/content/docs/ecosystems/laravel-agents.md`
+   - File: `website/content/docs/ecosystems/react-agents.md`
+   - File: `website/content/docs/ecosystems/python-agents.md`
+   - File: `website/content/docs/ecosystems/nodejs-agents.md`
+   - File: `website/content/docs/ecosystems/monorepo-agents.md`
+
+3. **Best practices guide**
+
+   - File: `website/content/docs/guides/agent-organization.md`
+   - When to use project-level vs module-level agents
+   - Naming conventions
+   - Versioning strategies
+
+### Phase 4: Playground Enhancements
+
+1. **Agent Discovery Visualizer**
+
+   - Add to playground: Visual tree of discovered agents
+   - Show `.agents/` folder structure
+   - Display agent metadata (name, capabilities, taxonomy)
+
+2. **Workspace Structure Viewer**
+
+   - Add to playground: Interactive workspace explorer
+   - Show hierarchical agent organization
+   - Filter by ecosystem, domain, capability
+
+3. **Agent Capability Browser**
+
+   - Add to playground: Browse agents by capability
+   - Search by taxonomy (domain, subdomain)
+   - Show agent relationships
+
+4. **Discovery Simulator**
+
+   - Add to playground: Simulate agent discovery
+   - Upload workspace structure
+   - See discovered agents and registry
+
+### Phase 5: Update Existing Examples
+
+1. **Update .gitlab/agents/**
+
+   - Ensure all agents follow folder structure
+   - Add README.md to each agent if missing
+   - Show proper organization
+
+## v0.2.4 Features That Support This
+
+- **Taxonomy** - Agents can be categorized for discovery (domain, subdomain)
+- **State Management** - Workspace orchestrator can manage discovered agents
+- **Transport Metadata** - Agents can communicate via standard protocols
+- **Security Scopes** - Fine-grained permissions for workspace access
+
+## Files to Create/Modify
+
+### New Files
+
+- `docs/agent-folder-structure.md` - Standard specification
+- `website/content/docs/core-concepts/Workspace-Discovery.md` - User guide
+- `examples/drupal/module-with-agents/` - Drupal example
+- `examples/wordpress/plugin-with-agents/` - WordPress example
+- `examples/laravel/package-with-agents/` - Laravel example
+- `examples/react/component-with-agents/` - React example
+- `examples/python/package-with-agents/` - Python example
+- `examples/nodejs/package-with-agents/` - Node.js example
+- `examples/monorepo/workspace-agents/` - Monorepo example
+- `website/content/docs/ecosystems/*.md` - Ecosystem-specific guides
+- `website/content/docs/guides/agent-organization.md` - Best practices
+
+### Modified Files
+
+- `website/content/docs/core-concepts/Project-Structure.md` - Add agent folder section
+- `.gitlab/agents/*/README.md` - Ensure all agents have READMEs
+- `website/app/playground/page.tsx` - Add discovery visualizer, workspace viewer, capability browser
+
+### To-dos
+
+- [x] Audit all website pages and documentation for v0.2.4 updates
+- [x] Update all version references from v0.2.3 to v0.2.4 across website
+- [x] Update schema page to show v0.2.4 schema and examples
+- [x] Update specification page with v0.2.4 features
+- [x] Update getting started guides with v0.2.4 examples
+- [x] Update migration guides for v0.2.4
+- [x] Update all examples to use v0.2.4 apiVersion
+- [x] Build out missing documentation for v0.2.4 features