amazingteam 3.0.0

package/docs/migration-to-v3.md

@@ -0,0 +1,355 @@
+# Migration Guide: v2 to v3
+
+This guide helps you migrate from AmazingTeam Foundation v2 to v3.
+
+---
+
+## Overview of Changes
+
+### v2 Architecture
+- Foundation files committed to each project
+- ~50+ files in `.ai-team/`, `.opencode/`, `tasks/`, etc.
+- Upgrades require manual copy/merge
+- Difficult to track which version is being used
+
+### v3 Architecture
+- Foundation loaded at runtime from NPM/GitHub
+- Only 2-3 files needed in user repo
+- One-command upgrades
+- Explicit version control
+- Better separation of user customizations
+
+---
+
+## Migration Steps
+
+### Step 1: Backup Your Project
+
+```bash
+# Create a backup branch
+git checkout -b backup-before-v3-migration
+
+# Commit any uncommitted changes
+git add -A && git commit -m "chore: backup before v3 migration"
+
+# Go back to main branch
+git checkout main
+```
+
+### Step 2: Identify Your Customizations
+
+Before migrating, identify what you've customized:
+
+```bash
+# Files you may have customized:
+# - AGENTS.md (global rules)
+# - .ai-team/agents/*.md (agent behaviors)
+# - .ai-team/skills/*/skill.md (custom skills)
+# - .ai-team/commands/*.md (custom commands)
+# - .ai-team/memory/*/ (agent memories)
+# - presets/ (if you created custom presets)
+```
+
+### Step 3: Run Migration Command
+
+```bash
+# Run the migration tool
+npx amazingteam migrate
+
+# This will:
+# 1. Scan for v2 structure
+# 2. Extract your customizations
+# 3. Create amazingteam.config.yaml
+# 4. Generate new workflow file
+# 5. Update .gitignore
+# 6. Remove foundation files from git tracking
+```
+
+### Step 4: Review Generated Files
+
+The migration creates these files:
+
+```
+your-project/
+├── amazingteam.config.yaml      # Your extracted configuration
+├── .github/
+│   └── workflows/
+│       └── amazingteam.yml      # Updated workflow
+└── .gitignore               # Updated to ignore foundation files
+```
+
+Review `amazingteam.config.yaml` and adjust as needed.
+
+### Step 5: Handle Customizations
+
+#### Custom AGENTS.md
+If you modified `AGENTS.md`, you have two options:
+
+**Option A: Overlay in config**
+```yaml
+# amazingteam.config.yaml
+overlay:
+  agents: |
+    # Your custom AGENTS.md additions
+    ## Custom Rules
+    - Your custom rules here
+```
+
+**Option B: Keep local AGENTS.md**
+```bash
+# Keep your custom AGENTS.md
+# It will be used instead of foundation's
+```
+
+#### Custom Skills
+```bash
+# Keep your custom skills in .ai-team/skills/
+# They will be merged with foundation skills
+```
+
+#### Custom Commands
+```yaml
+# Add custom commands in config
+commands:
+  my-custom-command:
+    description: "My custom workflow"
+    sequence:
+      - triage
+      - architect
+      - developer
+```
+
+### Step 6: Remove Foundation Files
+
+```bash
+# The migration tool does this automatically, but verify:
+git rm -r --cached .ai-team/agents/
+git rm -r --cached .ai-team/skills/
+git rm -r --cached .ai-team/commands/
+git rm -r --cached .opencode/skills/
+git rm -r --cached .opencode/commands/
+git rm --cached AGENTS.md
+
+# But KEEP these directories (they contain your data):
+# - .ai-team/memory/ (your agent memories)
+# - tasks/ (your task history)
+```
+
+### Step 7: Update .gitignore
+
+Add these entries to `.gitignore`:
+
+```gitignore
+# AmazingTeam Foundation v3
+.ai-team-local/
+```
+
+### Step 8: Commit Migration
+
+```bash
+git add -A
+git commit -m "chore: migrate to AmazingTeam Foundation v3
+
+- Remove committed foundation files
+- Add amazingteam.config.yaml
+- Update workflow file
+- Update .gitignore
+"
+```
+
+### Step 9: Test Migration
+
+```bash
+# Download foundation locally
+npx amazingteam local
+
+# Verify setup
+npx amazingteam validate
+
+# Check status
+npx amazingteam status
+```
+
+### Step 10: Push and Test in CI
+
+```bash
+git push origin main
+
+# Create a test issue with a command like:
+# /ai status
+```
+
+---
+
+## Detailed Migration Scenarios
+
+### Scenario 1: Minimal Customization
+
+If you only changed presets and have no custom skills/commands:
+
+```yaml
+# amazingteam.config.yaml
+version: "1.0"
+project:
+  name: "my-project"
+  language: "typescript"
+
+build:
+  command: "npm run build"
+  test: "npm test"
+  lint: "npm run lint"
+```
+
+### Scenario 2: Custom Skills
+
+If you created custom skills:
+
+```bash
+# Keep your skills
+mkdir -p .ai-team/skills
+# Your existing skills remain in .ai-team/skills/
+
+# They will be automatically merged with foundation skills
+```
+
+### Scenario 3: Modified AGENTS.md
+
+If you heavily modified `AGENTS.md`:
+
+**Option A: Use as overlay**
+```yaml
+# amazingteam.config.yaml
+overlay:
+  content: |
+    # Your custom additions to AGENTS.md
+    ## Project-Specific Rules
+    - Use specific naming conventions
+    - Follow company coding standards
+```
+
+**Option B: Replace entirely**
+```bash
+# Keep your AGENTS.md as-is
+# It will override foundation's AGENTS.md
+```
+
+### Scenario 4: Custom Memory Content
+
+Your agent memories in `.ai-team/memory/` are preserved:
+
+```bash
+# These directories are NOT removed during migration:
+.ai-team/memory/planner/
+.ai-team/memory/developer/
+# etc.
+```
+
+---
+
+## Breaking Changes
+
+### 1. Skill Path Changes
+
+**v2:**
+```
+.opencode/skills/test-first-feature-dev/SKILL.md
+```
+
+**v3:**
+Skills are loaded from foundation at runtime. Custom skills in `.ai-team/skills/` are merged.
+
+### 2. Command Path Changes
+
+**v2:**
+```
+.opencode/commands/auto.md
+```
+
+**v3:**
+Commands are loaded from foundation. Custom commands defined in `amazingteam.config.yaml`.
+
+### 3. Preset Structure
+
+**v2:**
+Presets were files in `presets/` directory.
+
+**v3:**
+Presets are built-in to foundation. Specify by name:
+
+```yaml
+# amazingteam.config.yaml
+preset: "typescript"  # or "python", "go", "default"
+```
+
+---
+
+## Troubleshooting
+
+### "Migration tool not found"
+
+```bash
+# Install globally first
+npm install -g amazingteam
+
+# Or use npx
+npx amazingteam migrate
+```
+
+### "v2 structure not detected"
+
+The migration tool looks for these markers:
+- `.ai-team/agents/` directory
+- `.opencode/skills/` directory
+- `AGENTS.md` file
+
+If your project uses a different structure, you may need to create `amazingteam.config.yaml` manually.
+
+### "My customizations were lost"
+
+1. Check the `backup-before-v3-migration` branch
+2. Look for extracted customizations in `amazingteam.config.yaml`
+3. Your memories and tasks are preserved in `.ai-team/memory/` and `tasks/`
+
+### "CI fails after migration"
+
+1. Verify `amazingteam.config.yaml` exists
+2. Verify `.github/workflows/amazingteam.yml` exists
+3. Check GitHub Actions logs for specific error
+4. Run `npx amazingteam validate` locally
+
+### "OpenCode can't find commands/skills"
+
+```bash
+# Download foundation locally
+npx amazingteam local
+
+# Verify opencode.jsonc exists
+cat opencode.jsonc
+```
+
+---
+
+## Rollback
+
+If migration causes issues, rollback:
+
+```bash
+# Restore from backup
+git checkout backup-before-v3-migration
+
+# Create a new branch for another migration attempt
+git checkout -b retry-v3-migration
+
+# Try migration again
+npx amazingteam migrate
+```
+
+---
+
+## Getting Help
+
+If you encounter issues:
+
+1. Check the [troubleshooting guide](./quick-start-v3.md#troubleshooting)
+2. Review [config reference](./config-reference.md)
+3. Open an issue at https://github.com/your-org/amazingteam/issues

package/docs/overlay-guide.md

@@ -0,0 +1,156 @@
+# Overlay Guide
+
+This document describes how to create and use overlays for AI Team Foundation.
+
+## What is an Overlay?
+
+An overlay is a set of configuration files that customize the base foundation for a specific technology stack or use case.
+
+Overlays allow the foundation to support different project types without duplicating the entire structure.
+
+## Available Overlays
+
+| Overlay | Description | Use Case |
+|---------|-------------|----------|
+| (none) | Base foundation only | General projects |
+| `cpp-qt-desktop` | C++ Qt desktop applications | Desktop GUI apps |
+| `python-backend` | Python backend services | API services |
+| `web-fullstack` | Full-stack web applications | Web apps |
+| `ai-agent-product` | AI agent products | AI products |
+
+## Using Overlays
+
+### During Initialization
+
+```bash
+# Initialize with Python backend overlay
+./scripts/init_project.sh -o python-backend my-api
+
+# Initialize with C++ Qt overlay
+./scripts/init_project.sh -o cpp-qt-desktop -l cpp my-desktop-app
+```
+
+### Overlay Application Order
+
+1. Base foundation files are copied first
+2. Overlay files are copied, potentially overriding base files
+3. Foundation lock is created with overlay name
+
+## Creating a New Overlay
+
+### Directory Structure
+
+```
+overlays/
+└── my-overlay/
+    ├── .ai-team/
+    │   ├── agents/           # Override or add agents
+    │   ├── skills/           # Add overlay-specific skills
+    │   └── commands/         # Add overlay-specific commands
+    ├── .github/
+    │   └── workflows/        # Override or add workflows
+    ├── docs/
+    │   └──                   # Add overlay-specific docs
+    └── overlay.yaml          # Overlay metadata
+```
+
+### overlay.yaml
+
+```yaml
+name: my-overlay
+description: Description of this overlay
+version: 1.0.0
+compatible_foundation_versions:
+  - "2.0.0"
+  - "2.1.0"
+
+# Files that will override base foundation
+overrides:
+  - .ai-team/agents/developer.md
+  - .github/workflows/ci.yml
+
+# Files that will be added (not override)
+additions:
+  - .ai-team/skills/my-skill/
+  - docs/my-docs/
+```
+
+### Best Practices
+
+1. **Minimal Overrides**: Only override what's necessary
+2. **Document Changes**: Explain why each override is needed
+3. **Version Compatibility**: Specify compatible foundation versions
+4. **Test Thoroughly**: Validate overlay with different foundation versions
+
+## Overlay Examples
+
+### python-backend Overlay
+
+**Purpose**: Python backend service configuration
+
+**Overrides**:
+- `.ai-team/agents/developer.md` - Python-specific implementation guidelines
+- `.github/workflows/ci.yml` - Python test/lint commands
+
+**Additions**:
+- `.ai-team/skills/python-testing/` - Python testing skill
+- `docs/python-style.md` - Python style guide
+
+### cpp-qt-desktop Overlay
+
+**Purpose**: C++ Qt desktop application configuration
+
+**Overrides**:
+- `.ai-team/agents/developer.md` - C++ implementation guidelines
+- `.ai-team/skills/bugfix-playbook/skill.md` - C++ debugging patterns
+- `.github/workflows/ci.yml` - CMake/build commands
+
+**Additions**:
+- `.ai-team/skills/qt-signals-slots/` - Qt patterns skill
+- `docs/qt-conventions.md` - Qt coding conventions
+
+## Maintaining Overlays
+
+### When Foundation Updates
+
+1. Test overlay with new foundation version
+2. Update `compatible_foundation_versions` if compatible
+3. Fix any breaking changes in overridden files
+4. Update overlay version
+
+### Overlay Versioning
+
+Overlays use semantic versioning:
+- **MAJOR**: Breaking changes (incompatible with previous projects)
+- **MINOR**: New features, backward compatible
+- **PATCH**: Bug fixes
+
+## Contributing Overlays
+
+To contribute a new overlay:
+
+1. Create overlay directory structure
+2. Add `overlay.yaml` with metadata
+3. Add documentation
+4. Test with `validate_foundation.sh`
+5. Submit PR with overlay description
+
+## Overlay-Specific Skills
+
+Overlays can add skills for their technology stack:
+
+```
+overlays/python-backend/.ai-team/skills/
+└── python-testing/
+    └── skill.md
+```
+
+When the overlay is applied, these skills are available to all agents.
+
+## Multi-Overlay Projects
+
+Currently, only one overlay can be applied per project. If you need features from multiple overlays:
+
+1. Choose the primary overlay
+2. Manually copy needed files from other overlays
+3. Document in `.foundation/local-overrides.md`

package/docs/patterns/README.md

@@ -0,0 +1,67 @@
+# Implementation Patterns
+
+This directory contains reusable implementation patterns for common scenarios.
+
+## Purpose
+
+- Document proven patterns that work well in this codebase
+- Provide templates for common implementation tasks
+- Share knowledge across tasks and developers
+- Reduce re-invention of solutions
+
+## Pattern Categories
+
+### Architectural Patterns
+
+- Module organization
+- Dependency injection
+- Configuration management
+- Error handling strategies
+
+### Code Patterns
+
+- Repository pattern
+- Service layer pattern
+- Factory pattern
+- Observer pattern
+
+### Testing Patterns
+
+- Test data builders
+- Mock factories
+- Test fixtures
+- Assertion helpers
+
+## Contributing Patterns
+
+When adding a new pattern:
+
+1. Ensure the pattern has been validated in production
+2. Document the problem it solves
+3. Provide a clear example
+4. Note when NOT to use the pattern
+5. Add cross-references to related patterns
+
+## Pattern Template
+
+```markdown
+# [Pattern Name]
+
+## Problem
+[What problem does this pattern solve?]
+
+## Solution
+[Description of the pattern]
+
+## Example
+[Code example]
+
+## When to Use
+[Appropriate scenarios]
+
+## When NOT to Use
+[Inappropriate scenarios]
+
+## Related Patterns
+[Links to related patterns]
+```