amazingteam 3.0.0

package/docs/quick-start-v3.md

@@ -0,0 +1,330 @@
+# AmazingTeam Foundation v3 - Quick Start (Draft)
+
+## Overview
+
+This guide shows how to use AmazingTeam Foundation v3 in your project with minimal setup.
+
+---
+
+## Installation
+
+### Option 1: Initialize in Existing Project
+
+```bash
+# Navigate to your project
+cd my-project
+
+# Initialize AmazingTeam
+npx amazingteam init
+```
+
+### Option 2: Create New Project
+
+```bash
+# Create new project with AmazingTeam
+npx amazingteam init my-new-project
+cd my-new-project
+```
+
+---
+
+## What Gets Created
+
+```
+my-project/
+├── .github/
+│   └── workflows/
+│       └── amazingteam.yml      # GitHub Action workflow
+├── amazingteam.config.yaml      # Your configuration
+└── .gitignore               # Updated (ignores .ai-team-local/)
+```
+
+**That's it!** Only 3 files added to your repository.
+
+---
+
+## Configuration
+
+### Minimal Configuration
+
+```yaml
+# amazingteam.config.yaml
+project:
+  name: "my-project"
+  language: "typescript"
+```
+
+### Full Configuration
+
+```yaml
+# amazingteam.config.yaml
+version: "1.0"
+
+project:
+  name: "my-awesome-app"
+  description: "My awesome application"
+  language: "typescript"
+  framework: "react"
+
+# Build commands (override defaults)
+build:
+  command: "npm run build"
+  test: "npm test"
+  lint: "npm run lint"
+  typecheck: "npm run typecheck"
+
+# Custom rules
+rules:
+  test_coverage_threshold: 80
+  max_function_lines: 30
+  commit_convention: "conventional"
+
+# Agent configuration
+agents:
+  planner: true
+  architect: true
+  developer: true
+  qa: true
+  reviewer: true
+  triage: true
+  ci_analyst: true
+
+# Technology overlay (optional)
+overlay: "web-fullstack"
+```
+
+---
+
+## Usage
+
+### In GitHub (CI/CD)
+
+1. Push your code to GitHub
+2. Create an issue or comment on an issue
+3. Type a command like `/ai implement this feature`
+4. AmazingTeam will process your request
+
+### Local Development
+
+```bash
+# Download foundation for local use
+npx amazingteam local
+
+# This creates .ai-team-local/ with all foundation files
+# Now you can use OpenCode locally with full AmazingTeam capabilities
+```
+
+---
+
+## Upgrading
+
+### Check for Updates
+
+```bash
+npx amazingteam check-update
+
+# Output:
+# Current version: 3.0.0
+# Latest version: 3.1.0
+# 
+# Changes in 3.1.0:
+# - feat: New skill for API documentation
+# - fix: Memory handling improvement
+# 
+# Run `ai-team upgrade` to update
+```
+
+### Upgrade
+
+```bash
+npx amazingteam upgrade
+
+# Output:
+# Upgrading from 3.0.0 to 3.1.0...
+# 
+# Updated files:
+# - .github/workflows/amazingteam.yml
+# 
+# No breaking changes.
+# Upgrade complete!
+```
+
+### Upgrade to Specific Version
+
+```bash
+npx amazingteam upgrade --to 3.0.5
+```
+
+---
+
+## Available Commands
+
+| Command | Description |
+|---------|-------------|
+| `init` | Initialize AmazingTeam in project |
+| `version` | Show current foundation version |
+| `check-update` | Check for available updates |
+| `upgrade` | Upgrade to latest version |
+| `local` | Download foundation for local dev |
+| `validate` | Validate configuration |
+
+---
+
+## Workflow File
+
+The generated `.github/workflows/amazingteam.yml`:
+
+```yaml
+name: AmazingTeam
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+
+jobs:
+  ai-team:
+    if: |
+      startsWith(github.event.comment.body, '/ai') ||
+      startsWith(github.event.comment.body, '/opencode')
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: write
+      pull-requests: write
+      issues: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Setup AmazingTeam
+        uses: your-org/amazingteam-action@v3.0.0  # Version is auto-managed
+        with:
+          config: 'amazingteam.config.yaml'
+
+      - name: Run OpenCode
+        uses: anomalyco/opencode/github@latest
+        env:
+          ALIBABA_CODING_PLAN_API_KEY: ${{ secrets.ALIBABA_CODING_PLAN_API_KEY }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          model: alibaba-coding-plan/glm-5
+```
+
+---
+
+## Comparison: v2 vs v3
+
+| Aspect | v2 | v3 |
+|--------|----|----|
+| Files in user repo | ~50+ files | 2-3 files |
+| Upgrade method | Manual copy/merge | Single command |
+| Foundation location | Committed to repo | Loaded at runtime |
+| Local development | Files already present | `ai-team local` command |
+| Version control | Hard to track | Explicit in workflow |
+
+---
+
+## Migration from v2
+
+If you have an existing v2 project:
+
+```bash
+# Run migration
+npx amazingteam migrate
+
+# This will:
+# 1. Extract your customizations
+# 2. Create amazingteam.config.yaml
+# 3. Update workflow file
+# 4. Add foundation files to .gitignore
+# 5. Remove foundation files from git tracking
+```
+
+---
+
+## FAQ
+
+### Q: What if I need to customize AGENTS.md?
+
+A: You can create a local `AGENTS.md` in your project root. It will override the foundation's AGENTS.md entirely, or you can use the overlay feature in `amazingteam.config.yaml` to add content.
+
+### Q: What if I need custom skills?
+
+A: Create `.ai-team/skills/` in your project. These will be merged with foundation skills at runtime.
+
+### Q: What if CI fails to download foundation?
+
+A: The action caches foundation downloads. If network fails, it uses cache. You can also run `ai-team local` and commit `.ai-team-local/` as fallback.
+
+### Q: Can I use a specific version?
+
+A: Yes, specify version in workflow file or use `ai-team upgrade --to x.x.x`.
+
+### Q: How do I migrate from v2?
+
+A: Run `npx amazingteam migrate`. See [Migration Guide](./migration-to-v3.md) for details.
+
+### Q: Can I use this with private repositories?
+
+A: Yes. The GitHub Action uses `GITHUB_TOKEN` which has access to the current repo. For private foundation packages, use a private NPM registry.
+
+### Q: What happens to my agent memories?
+
+A: Your memories in `.ai-team/memory/` are preserved during migration and upgrades. They are local to your project and not affected by foundation updates.
+
+### Q: Can I disable specific agents?
+
+A: Yes, in your `amazingteam.config.yaml`:
+
+```yaml
+agents:
+  planner: false
+  ci_analyst: false
+```
+
+### Q: How do I add custom build commands?
+
+A: Override in your config:
+
+```yaml
+build:
+  command: "npm run build:prod"
+  test: "npm run test:coverage"
+```
+
+---
+
+## Troubleshooting
+
+### "Foundation download failed"
+
+```bash
+# Try downloading manually
+npx amazingteam local
+
+# If still fails, check network or use VPN
+```
+
+### "Configuration validation failed"
+
+```bash
+# Validate your config
+npx amazingteam validate
+
+# Check for errors and fix
+```
+
+### "OpenCode can't find skills"
+
+```bash
+# Ensure foundation is downloaded
+npx amazingteam local
+
+# Check opencode.jsonc references
+cat opencode.jsonc
+```

package/docs/releases/README.md

@@ -0,0 +1,64 @@
+# Releases
+
+This directory contains release documentation, checklists, and history.
+
+## Purpose
+
+- Document release procedures
+- Track release history
+- Provide release checklists
+- Record release decisions
+
+## Contents
+
+### Release Procedures
+
+- Release checklist
+- Version bumping guide
+- Deployment procedures
+- Rollback procedures
+
+### Release History
+
+- RELEASE_NOTES.md - Changelog of releases
+- release-log/ - Detailed release records
+
+### Release Criteria
+
+- Quality gates
+- Security requirements
+- Performance requirements
+- Documentation requirements
+
+## Release Process
+
+1. **Prepare**
+   - Update CHANGELOG
+   - Update version numbers
+   - Run full test suite
+   - Complete security scan
+
+2. **Validate**
+   - Run release readiness check
+   - Get required approvals
+   - Verify documentation
+
+3. **Release**
+   - Create release branch/tag
+   - Deploy to staging
+   - Smoke test
+   - Deploy to production
+   - Monitor
+
+4. **Post-Release**
+   - Update documentation
+   - Announce release
+   - Monitor for issues
+
+## Version Numbering
+
+We follow Semantic Versioning (MAJOR.MINOR.PATCH):
+
+- **MAJOR**: Breaking changes
+- **MINOR**: New features (backward compatible)
+- **PATCH**: Bug fixes (backward compatible)

package/docs/runbooks/ci/README.md

@@ -0,0 +1,62 @@
+# CI Runbooks
+
+This directory contains operational runbooks for CI/CD issues.
+
+## Purpose
+
+- Provide step-by-step guides for common CI issues
+- Enable quick resolution of CI failures
+- Document infrastructure-specific procedures
+- Share knowledge across the team
+
+## Available Runbooks
+
+### Build Issues
+
+- `build-debug.md` - Debugging build failures
+- `dependencies.md` - Dependency resolution issues
+- `memory.md` - Out of memory issues
+
+### Test Issues
+
+- `flaky-tests.md` - Investigating and fixing flaky tests
+- `timeouts.md` - Test timeout issues
+- `environment.md` - Test environment setup
+
+### Infrastructure Issues
+
+- `resources.md` - Resource limit management
+- `network.md` - Network connectivity issues
+- `permissions.md` - Permission and access issues
+
+## Runbook Template
+
+```markdown
+# [Runbook Title]
+
+## Symptoms
+[How to identify this issue]
+
+## Investigation Steps
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+
+## Resolution
+[How to fix the issue]
+
+## Prevention
+[How to prevent recurrence]
+
+## Escalation
+[When and how to escalate]
+```
+
+## Using Runbooks
+
+1. Identify the issue type from symptoms
+2. Find the appropriate runbook
+3. Follow investigation steps
+4. Apply resolution
+5. Document any new findings
+6. Update runbook if needed

package/docs/runbooks/ci/build-debug.md

@@ -0,0 +1,120 @@
+# Build Debug Runbook
+
+## Symptoms
+
+- Build fails with compilation errors
+- Build fails with dependency errors
+- Build succeeds locally but fails in CI
+- Build timing out
+
+## Investigation Steps
+
+### 1. Check Error Messages
+
+```bash
+# Review the error output
+# Look for:
+# - Specific file and line numbers
+# - Missing imports
+# - Type mismatches
+# - Module resolution failures
+```
+
+### 2. Check Environment Differences
+
+```bash
+# Compare local and CI environments
+node --version
+npm --version
+
+# Check lock file
+git diff package-lock.json
+
+# Check for environment-specific config
+git diff .env.example
+```
+
+### 3. Dependency Issues
+
+```bash
+# Clear caches and reinstall
+rm -rf node_modules
+rm package-lock.json
+npm install
+
+# Check for peer dependency issues
+npm ls
+```
+
+### 4. Check for Missing Files
+
+```bash
+# Verify all referenced files exist
+# Check for case-sensitivity issues
+# Verify import paths
+```
+
+## Common Issues and Fixes
+
+### TypeScript Errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| Cannot find module | Missing import or file | Add import or create file |
+| Type 'X' is not assignable | Type mismatch | Fix type or add assertion |
+| Property does not exist | Missing property | Add property or fix access |
+
+### Dependency Errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| ERESOLVE | Dependency conflict | Update dependencies or use --legacy-peer-deps |
+| 404 Not Found | Package doesn't exist | Check package name |
+| Permission denied | NPM registry auth | Check .npmrc |
+
+### Memory Issues
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| JavaScript heap out of memory | Large build | Increase NODE_OPTIONS |
+| FATAL ERROR | Process killed | Reduce parallelism |
+
+## Resolution
+
+### Fix Compilation Errors
+
+1. Identify error location from output
+2. Fix the specific issue
+3. Run build locally to verify
+4. Commit and push
+
+### Fix Dependency Issues
+
+1. Check package.json for conflicts
+2. Update lock file
+3. Test installation from scratch
+4. Commit lock file changes
+
+### Fix Environment Issues
+
+1. Update CI configuration
+2. Add missing environment variables
+3. Update Node.js version if needed
+4. Test in CI
+
+## Prevention
+
+- Keep dependencies updated
+- Use strict TypeScript config
+- Run lint and typecheck in CI
+- Keep build scripts simple
+- Document build requirements
+
+## Escalation
+
+If unable to resolve:
+
+1. Document all investigation steps
+2. Note exact error messages
+3. Check CI analyst memory for similar issues
+4. Create issue with full context

package/docs/runbooks/ci/flaky-tests.md

@@ -0,0 +1,127 @@
+# Flaky Test Investigation
+
+## Symptoms
+
+- Test passes sometimes, fails sometimes
+- Failure not related to code changes
+- Tests fail in CI but pass locally (or vice versa)
+- Failures cluster around certain times or conditions
+
+## Common Causes
+
+### Race Conditions
+- Async operations not properly awaited
+- Shared mutable state
+- Timing-dependent assertions
+
+### Test Isolation Issues
+- Tests modifying shared state
+- Order-dependent tests
+- Resource cleanup not happening
+
+### Environment Issues
+- Resource exhaustion
+- Network timing
+- External service availability
+
+## Investigation Steps
+
+### 1. Gather Information
+
+```bash
+# Run the test multiple times
+npm test -- --testNamePattern="test name" --runInBand --detectOpenHandles
+
+# Run with verbose output
+npm test -- --verbose --testNamePattern="test name"
+
+# Check test isolation
+npm test -- --testNamePattern="test name" --runInBand
+```
+
+### 2. Check for Race Conditions
+
+- Look for unawaited promises
+- Check for setTimeout/setInterval usage
+- Review async/await usage
+- Look for shared mutable state
+
+### 3. Check Test Isolation
+
+- Verify beforeEach/afterEach cleanup
+- Check for global state modifications
+- Look for database/file side effects
+- Verify mock reset
+
+### 4. Check Environment
+
+- Review resource usage
+- Check CI configuration
+- Verify external service mocks
+- Review timeout settings
+
+## Resolution Strategies
+
+### Fix the Root Cause
+
+```typescript
+// Bad: Race condition
+it('should work', () => {
+  doSomethingAsync();
+  expect(result).toBe('expected'); // Too early!
+});
+
+// Good: Properly await
+it('should work', async () => {
+  await doSomethingAsync();
+  expect(result).toBe('expected');
+});
+```
+
+### Improve Test Isolation
+
+```typescript
+// Ensure cleanup
+afterEach(() => {
+  jest.clearAllMocks();
+  // Reset any global state
+});
+```
+
+### Add Retries (Last Resort)
+
+```typescript
+// jest.config.js
+module.exports = {
+  testRetry: {
+    maxRetries: 3,
+    retryDelay: 1000,
+  },
+};
+```
+
+## Prevention
+
+- Always properly await async operations
+- Clean up in afterEach hooks
+- Avoid shared mutable state
+- Use deterministic test data
+- Mock external services completely
+
+## Escalation
+
+If unable to resolve:
+
+1. Add to flaky test registry
+2. Create issue with investigation notes
+3. Tag with `flaky-test` label
+4. Assign to CI Analyst
+
+## Quick Reference
+
+| Symptom | Likely Cause | Quick Fix |
+|---------|--------------|-----------|
+| Random assertion failures | Race condition | Add await |
+| State leaks between tests | Poor isolation | Add cleanup |
+| CI-only failures | Environment | Check resources |
+| Timeout failures | Slow operations | Increase timeout |