amazingteam 3.0.0

package/docs/runbooks/getting-started.md

@@ -0,0 +1,81 @@
+# Getting Started
+
+## Prerequisites
+
+- Node.js 20+
+- npm or yarn
+- Git
+- GitHub account
+
+## Installation
+
+1. Clone the repository:
+```bash
+git clone https://github.com/your-org/amazingteam.git
+cd amazingteam
+```
+
+2. Install dependencies:
+```bash
+npm install
+```
+
+3. Set up environment:
+```bash
+cp .env.example .env
+```
+
+## Usage
+
+### Creating an Issue
+
+1. Go to Issues → New Issue
+2. Select a template (Feature, Bug, Tech Task)
+3. Fill in the required fields
+4. The AI team will automatically analyze the issue
+
+### Triggering AI Work
+
+Comment on an issue:
+```
+/opencode use architect to analyze this issue
+```
+
+Available commands:
+- `/design` - Analyze and design
+- `/implement` - Implement changes
+- `/test` - Run tests
+- `/review` - Review code
+
+### Workflow
+
+1. Create an issue with the template
+2. AI Architect analyzes and designs
+3. AI Developer implements
+4. AI QA validates
+5. AI Reviewer reviews
+6. Human approves and merges
+
+## Development
+
+### Running Tests
+
+```bash
+npm test
+```
+
+### Linting
+
+```bash
+npm run lint
+```
+
+### Building
+
+```bash
+npm run build
+```
+
+## Configuration
+
+See `.opencode/opencode.jsonc` for AI configuration.

package/docs/upgrade-policy.md

@@ -0,0 +1,188 @@
+# Upgrade Policy
+
+This document defines the upgrade policy for AI Team Foundation.
+
+## Versioning
+
+AI Team Foundation follows [Semantic Versioning](https://semver.org/):
+
+- **MAJOR** version: Breaking changes requiring migration
+- **MINOR** version: New features, backward compatible
+- **PATCH** version: Bug fixes, backward compatible
+
+## Upgrade Types
+
+### Automatic Upgrades
+
+The following changes can be applied automatically:
+
+| Change Type | Class | Example |
+|-------------|-------|---------|
+| New agent added | B | Adding `ci-analyst.md` |
+| New skill added | B | Adding `regression-checklist` |
+| New command added | B | Adding `/release-check` |
+| New memory directory | A | Adding `.ai-team/memory/triage/` |
+| New documentation zone | A | Adding `docs/patterns/` |
+| Task template additions | A | Adding `release.md` template |
+| Bug fixes to templates | B | Fixing typos in agent prompts |
+
+### Review-Required Upgrades
+
+The following changes require review before applying:
+
+| Change Type | Class | Action |
+|-------------|-------|--------|
+| Agent prompt changes | B | Generate diff, review, then apply |
+| Skill procedure changes | B | Generate diff, review, then apply |
+| Command workflow changes | B | Generate diff, review, then apply |
+| Workflow file changes | B | Generate diff, review, then apply |
+| AGENTS.md updates | B | Generate diff, review, then apply |
+
+### Manual-Approval Upgrades
+
+The following changes require explicit human approval:
+
+| Change Type | Class | Action |
+|-------------|-------|--------|
+| Architecture document changes | C | Manual review and approval |
+| Decision record changes | C | Manual review and approval |
+| Governance policy changes | C | Manual review and approval |
+| Breaking changes | Special | Migration guide required |
+
+## Upgrade Process
+
+### Step 1: Plan
+
+```bash
+./scripts/plan_upgrade.sh /path/to/project
+```
+
+This generates an upgrade plan showing:
+- Missing files
+- Outdated files
+- Protected files
+- Risk assessment
+
+### Step 2: Review
+
+Review the generated upgrade plan at:
+```
+/path/to/project/.foundation/upgrade-plan.md
+```
+
+Key questions:
+- Are there protected files affected?
+- Are there local customizations that might be overwritten?
+- Is this a breaking change?
+
+### Step 3: Apply
+
+```bash
+# Safe upgrade (skips protected files)
+./scripts/upgrade_foundation.sh /path/to/project
+
+# Force upgrade (use with caution)
+./scripts/upgrade_foundation.sh --force /path/to/project
+
+# Dry run (preview changes)
+./scripts/upgrade_foundation.sh --dry-run /path/to/project
+```
+
+### Step 4: Validate
+
+```bash
+./scripts/validate_project_setup.sh /path/to/project
+```
+
+### Step 5: Test
+
+Run the project's test suite to verify everything works.
+
+### Step 6: Commit
+
+```bash
+git add .
+git commit -m "chore: upgrade ai-team-foundation to v2.0.0"
+```
+
+## Protected Paths
+
+The following paths are protected and will never be automatically modified:
+
+- `docs/architecture/` - Project architecture documentation
+- `docs/decisions/` - Architecture decision records (ADRs)
+- Any files listed in `.foundation/local-overrides.md`
+
+## Local Overrides
+
+Projects can specify local customizations that should be preserved:
+
+```markdown
+# .foundation/local-overrides.md
+
+## Custom AGENTS.md Additions
+- Added custom build commands section
+- Added project-specific naming conventions
+
+## Custom Workflows
+- Modified ci.yml to add integration tests
+- Added custom deployment workflow
+
+## Custom Skills
+- Added project-specific skill: database-migration
+```
+
+## Breaking Changes
+
+When a new version contains breaking changes:
+
+1. The CHANGELOG.md will have a "Breaking Changes" section
+2. A migration guide will be provided
+3. The upgrade script will require `--force` flag
+4. Manual review is mandatory
+
+### Breaking Change Examples
+
+- Agent interface changes (new required fields)
+- Command signature changes
+- Memory structure reorganization
+- Required configuration changes
+
+## Rollback
+
+If an upgrade causes issues:
+
+1. Restore from backup:
+   ```bash
+   cp -r .foundation/backup-TIMESTAMP/.ai-team ./
+   ```
+
+2. Revert the commit:
+   ```bash
+   git revert HEAD
+   ```
+
+3. Report the issue for investigation
+
+## Version Support
+
+| Version | Status | Support Ends |
+|---------|--------|--------------|
+| 2.x | Current | - |
+| 1.x | Maintenance | 2024-12-31 |
+
+## Upgrade Frequency
+
+Recommended upgrade frequency:
+
+- **Critical security fixes**: Immediately
+- **Bug fixes**: Within 1 week
+- **Minor features**: Within 1 month
+- **Major versions**: After thorough review
+
+## Questions?
+
+For questions about upgrades:
+1. Check CHANGELOG.md for details
+2. Review the upgrade plan
+3. Create an issue with `[UPGRADE]` label

package/docs/versioning.md

@@ -0,0 +1,199 @@
+# Versioning Policy
+
+This document describes how AI Team Foundation handles versioning and upgrades.
+
+## Version Format
+
+AI Team Foundation uses [Semantic Versioning](https://semver.org/) with the format `MAJOR.MINOR.PATCH`:
+
+- **MAJOR**: Breaking changes that require manual intervention
+- **MINOR**: New features, backward compatible
+- **PATCH**: Bug fixes, backward compatible
+
+## Version Increment Rules
+
+### Conservative Update Policy
+
+**Do NOT rush version increments.** Accumulate changes before releasing.
+
+| Change Type | Increment | Min Changes Required | Wait Period |
+|-------------|-----------|---------------------|-------------|
+| Bug fix | PATCH | 3+ fixes OR 1 critical fix | As needed |
+| New feature | MINOR | 2+ features OR 1 major feature | Monthly |
+| Breaking change | MAJOR | Only when unavoidable | Yearly |
+
+### Release Cadence
+
+| Type | Frequency | Example |
+|------|-----------|---------|
+| **PATCH** | As needed (bug fixes) | v2.2.0 → v2.2.1 |
+| **MINOR** | Monthly or when significant features accumulated | v2.2.0 → v2.3.0 |
+| **MAJOR** | Yearly or when breaking changes required | v2.x.x → v3.0.0 |
+
+### Stability Rules
+
+1. **Batch Changes**: Group related changes into a single release
+   - Good: Multiple bug fixes → one PATCH release
+   - Good: Multiple new features → one MINOR release
+   - Bad: Every small change → new version
+
+2. **Stability Period**: After a MAJOR release, wait at least 2 weeks before the next MINOR release.
+
+3. **No Premature Releases**: Don't release for every small change.
+
+### Exceptions
+
+The version policy may be overridden in these cases:
+
+1. **Security Fix**: Immediate PATCH release regardless of threshold
+2. **Critical Bug**: Immediate PATCH release for breaking issues
+3. **User Request**: If users explicitly request a release
+
+## Version Files
+
+### VERSION
+
+Single-line file containing the current version:
+
+```
+2.0.0
+```
+
+### CHANGELOG.md
+
+Documents all changes in each release:
+
+- New features
+- Changed files
+- Deprecated elements
+- Breaking changes
+- Migration notes
+
+## Upgrade Paths
+
+### Patch Upgrades (2.0.0 → 2.0.1)
+
+**Risk Level**: Low
+
+- Bug fixes only
+- No structural changes
+- Safe to apply automatically
+
+**Action**: Run `upgrade_foundation.sh --auto`
+
+### Minor Upgrades (2.0.0 → 2.1.0)
+
+**Risk Level**: Medium
+
+- New features added
+- New files may be created
+- Existing files may receive additions
+
+**Action**: 
+1. Run `plan_upgrade.sh` to see changes
+2. Review the upgrade plan
+3. Run `upgrade_foundation.sh`
+
+### Major Upgrades (2.0.0 → 3.0.0)
+
+**Risk Level**: High
+
+- Breaking changes possible
+- Manual migration may be required
+- Structure changes possible
+
+**Action**:
+1. Read CHANGELOG.md migration notes
+2. Run `diff_foundation_vs_project.sh`
+3. Manually resolve conflicts
+4. Run `upgrade_foundation.sh --careful`
+5. Test thoroughly
+
+## Foundation Lock File
+
+Each downstream project has `.foundation/foundation.lock`:
+
+```yaml
+foundation_repo: ai-team-foundation
+foundation_version: 2.0.0
+overlay: python-backend
+initialized_at: 2026-03-14
+last_upgrade_at: 2026-03-20
+upgrade_policy: controlled
+```
+
+This file tracks:
+- Which foundation version the project was initialized from
+- Which overlay was applied
+- When upgrades were last applied
+
+## Upgrade History
+
+Each downstream project has `.foundation/upgrade-history.md`:
+
+```markdown
+## Upgrade 2026-03-20
+
+- **From**: 2.0.0
+- **To**: 2.1.0
+- **Type**: Minor
+- **Files Added**: 3
+- **Files Modified**: 2
+- **Files Skipped**: 1 (protected)
+- **Conflicts**: 0
+- **Manual Decisions**: None
+```
+
+## Checking for Updates
+
+```bash
+# Check current version
+cat VERSION
+
+# Check your project's foundation version
+cat .foundation/foundation.lock
+
+# Compare versions
+./scripts/plan_upgrade.sh
+```
+
+## Breaking Change Policy
+
+When a breaking change is introduced:
+
+1. **Announce in CHANGELOG.md** with migration instructions
+2. **Provide migration script** if applicable
+3. **Support previous version** for one major release cycle
+4. **Document in upgrade notes** specific actions required
+
+## Overlay Compatibility
+
+Each overlay specifies compatible foundation versions:
+
+```yaml
+# overlays/python-backend/overlay.yaml
+compatible_foundation_versions:
+  - "2.0.0"
+  - "2.1.0"
+```
+
+Before applying an upgrade, validate overlay compatibility:
+
+```bash
+./scripts/validate_project_setup.sh
+```
+
+## Version Lifecycle
+
+| Version Stage | Description | Support Level |
+|--------------|-------------|---------------|
+| Current | Latest release | Full support |
+| Previous | Prior major | Security fixes |
+| Deprecated | EOL versions | No support |
+
+## Deprecation Policy
+
+1. **Announce deprecation** 3 months in advance
+2. **Document migration path** 
+3. **Provide deprecation warnings** in upgrade scripts
+4. **Remove in next major version**

package/overlays/README.md

@@ -0,0 +1,30 @@
+# Overlays
+
+This directory contains technology-specific overlays for AI Team Foundation.
+
+## What is an Overlay?
+
+An overlay customizes the base foundation for a specific technology stack or use case. When initializing a new project, you can select an overlay to apply technology-specific configurations.
+
+## Available Overlays
+
+| Directory | Description |
+|-----------|-------------|
+| `cpp-qt-desktop/` | C++ Qt desktop application |
+| `python-backend/` | Python backend service |
+| `web-fullstack/` | Full-stack web application |
+| `ai-agent-product/` | AI agent product |
+
+## Usage
+
+```bash
+# List available overlays
+ls -la
+
+# Use an overlay during initialization
+../scripts/init_project.sh -o python-backend my-project
+```
+
+## Creating an Overlay
+
+See [docs/overlay-guide.md](../docs/overlay-guide.md) for details on creating new overlays.

package/overlays/ai-agent-product/.ai-team/skills/llm-integration/skill.md

@@ -0,0 +1,99 @@
+# LLM Integration Skill
+
+## Purpose
+
+Guide for integrating Large Language Models into applications.
+
+## Framework Choice
+
+- **LangChain**: Full-featured LLM framework
+- **LlamaIndex**: RAG-focused
+- **Direct API**: OpenAI/Anthropic SDKs
+
+## Basic Integration
+
+```python
+from langchain_openai import ChatOpenAI
+from langchain.schema import HumanMessage, SystemMessage
+
+llm = ChatOpenAI(model="gpt-4", temperature=0.7)
+
+response = llm.invoke([
+    SystemMessage(content="You are a helpful assistant."),
+    HumanMessage(content="Hello!")
+])
+```
+
+## Prompt Engineering
+
+### System Prompts
+
+```python
+SYSTEM_PROMPT = """You are an expert code reviewer.
+Analyze code for:
+- Security vulnerabilities
+- Performance issues
+- Best practice violations
+
+Respond in JSON format."""
+```
+
+### Few-Shot Examples
+
+```python
+examples = [
+    {"input": "def add(a, b): return a + b", 
+     "output": "Valid: Simple addition function"},
+    {"input": "eval(user_input)", 
+     "output": "Critical: Code injection risk"},
+]
+```
+
+## RAG Patterns
+
+### Vector Store Integration
+
+```python
+from langchain.vectorstores import Chroma
+from langchain.embeddings import OpenAIEmbeddings
+
+embeddings = OpenAIEmbeddings()
+vectorstore = Chroma.from_documents(documents, embeddings)
+
+results = vectorstore.similarity_search(query, k=4)
+```
+
+### Retrieval Chain
+
+```python
+from langchain.chains import RetrievalQA
+
+qa_chain = RetrievalQA.from_chain_type(
+    llm=llm,
+    retriever=vectorstore.as_retriever(),
+    return_source_documents=True
+)
+```
+
+## Cost Optimization
+
+1. Use smaller models for simple tasks
+2. Implement caching for repeated queries
+3. Batch requests when possible
+4. Monitor token usage
+
+## Error Handling
+
+```python
+from openai import RateLimitError, APIError
+
+try:
+    response = llm.invoke(messages)
+except RateLimitError:
+    # Implement backoff retry
+    time.sleep(60)
+    response = llm.invoke(messages)
+except APIError as e:
+    logger.error(f"API Error: {e}")
+    raise
+```

package/overlays/ai-agent-product/docs/ai-agent-architecture.md

@@ -0,0 +1,68 @@
+# AI Agent Architecture
+
+## Overview
+
+This document describes the architecture for AI agent products.
+
+## Core Components
+
+```
+┌─────────────────────────────────────────────┐
+│                  API Layer                   │
+│            (FastAPI / Next.js)               │
+└─────────────────┬───────────────────────────┘
+                  │
+┌─────────────────▼───────────────────────────┐
+│              Agent Layer                     │
+│  ┌─────────┐ ┌─────────┐ ┌─────────┐       │
+│  │ Agent 1 │ │ Agent 2 │ │ Agent 3 │       │
+│  └────┬────┘ └────┬────┘ └────┬────┘       │
+└───────┼──────────┼──────────┼──────────────┘
+        │          │          │
+┌───────▼──────────▼──────────▼──────────────┐
+│            LLM Provider                     │
+│         (OpenAI / Anthropic)                │
+└─────────────────────────────────────────────┘
+```
+
+## Agent Types
+
+| Agent | Purpose | Model |
+|-------|---------|-------|
+| Orchestrator | Route requests | GPT-4 |
+| Researcher | Gather information | GPT-4 |
+| Coder | Write/modify code | GPT-4 |
+| Reviewer | Quality checks | GPT-3.5 |
+
+## Memory Architecture
+
+### Short-term Memory
+- Conversation context
+- Current task state
+- Working variables
+
+### Long-term Memory
+- Vector database (Chroma/Pinecone)
+- User preferences
+- Historical decisions
+
+## RAG Pipeline
+
+```python
+# Retrieval-Augmented Generation flow
+query -> embedding -> vector_search -> context
+context + query -> LLM -> response
+```
+
+## Deployment
+
+- Container: Docker
+- Orchestration: Kubernetes
+- Monitoring: LangSmith / custom
+
+## Security Considerations
+
+1. Never log API keys or user data
+2. Sanitize inputs before embedding
+3. Rate limit API endpoints
+4. Audit agent actions

package/overlays/ai-agent-product/overlay.yaml

@@ -0,0 +1,26 @@
+name: ai-agent-product
+description: AI agent product configuration
+version: 1.0.0
+compatible_foundation_versions:
+  - "2.0.0"
+
+overrides:
+  - .ai-team/agents/developer.md
+  - .ai-team/agents/architect.md
+  - .github/workflows/ci.yml
+
+additions:
+  - .ai-team/skills/llm-integration/
+  - .ai-team/skills/prompt-engineering/
+  - .ai-team/skills/rag-patterns/
+  - docs/ai-agent-architecture.md
+
+language: python
+framework: langchain
+package_manager: poetry
+
+environment:
+  python_version: "3.11"
+  llm_framework: langchain
+  vector_db: chromadb
+  embedding_model: openai