amazingteam 3.0.0

package/scripts/generate_docs.sh

@@ -0,0 +1,200 @@
+#!/bin/bash
+# generate_docs.sh
+# Generate documentation for the foundation
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+FOUNDATION_ROOT="$(dirname "$SCRIPT_DIR")"
+
+# Colors
+CYAN='\033[0;36m'
+GREEN='\033[0;32m'
+NC='\033[0m'
+
+VERSION=$(cat "$FOUNDATION_ROOT/VERSION" 2>/dev/null || echo "unknown")
+OUTPUT_DIR="$FOUNDATION_ROOT/docs/generated"
+
+echo -e "${CYAN}══════════════════════════════════════════════════${NC}"
+echo -e "${CYAN}  AI Team Foundation Documentation Generator${NC}"
+echo -e "${CYAN}══════════════════════════════════════════════════${NC}"
+echo ""
+
+mkdir -p "$OUTPUT_DIR"
+
+# Generate role inventory
+echo -e "${CYAN}Generating role inventory...${NC}"
+cat > "$OUTPUT_DIR/role-inventory.md" << EOF
+# Role Inventory
+
+Generated: $(date -I)
+Foundation Version: $VERSION
+
+## Core Roles
+
+| Role | File | Description |
+|------|------|-------------|
+| Planner | .ai-team/agents/planner.md | Task decomposition and workflow orchestration |
+| Architect | .ai-team/agents/architect.md | Design technical approach and impact boundaries |
+| Developer | .ai-team/agents/developer.md | Implement approved changes |
+| QA | .ai-team/agents/qa.md | Validate functionality and regression safety |
+| Reviewer | .ai-team/agents/reviewer.md | Assess correctness and maintainability |
+| Triage | .ai-team/agents/triage.md | Classify work and perform first-pass debug |
+| CI Analyst | .ai-team/agents/ci-analyst.md | Investigate CI failure patterns |
+
+## Memory Areas
+
+| Role | Memory Directory | Purpose |
+|------|------------------|---------|
+| Planner | .ai-team/memory/planner/ | Task decomposition patterns |
+| Architect | .ai-team/memory/architect/ | Architecture decisions |
+| Developer | .ai-team/memory/developer/ | Implementation patterns |
+| QA | .ai-team/memory/qa/ | Test strategy and cases |
+| Reviewer | .ai-team/memory/reviewer/ | Quality rules and risks |
+| Triage | .ai-team/memory/triage/ | Classification heuristics |
+| CI Analyst | .ai-team/memory/ci-analyst/ | Failure patterns |
+| Failures | .ai-team/memory/failures/ | Shared failure library |
+EOF
+echo -e "${GREEN}  Created: role-inventory.md${NC}"
+
+# Generate skill inventory
+echo -e "${CYAN}Generating skill inventory...${NC}"
+cat > "$OUTPUT_DIR/skill-inventory.md" << EOF
+# Skill Inventory
+
+Generated: $(date -I)
+Foundation Version: $VERSION
+
+## Understanding Skills
+
+| Skill | Directory | Purpose |
+|-------|-----------|---------|
+| repo-architecture-reader | .ai-team/skills/repo-architecture-reader/ | Quickly understand repository structure |
+
+## Execution Skills
+
+| Skill | Directory | Purpose |
+|-------|-----------|---------|
+| task-breakdown-and-dispatch | .ai-team/skills/task-breakdown-and-dispatch/ | Decompose tasks into subtasks |
+| bugfix-playbook | .ai-team/skills/bugfix-playbook/ | Systematic bug fixing |
+| test-first-feature-dev | .ai-team/skills/test-first-feature-dev/ | TDD approach for features |
+| safe-refactor-checklist | .ai-team/skills/safe-refactor-checklist/ | Safe refactoring checklist |
+
+## Validation Skills
+
+| Skill | Directory | Purpose |
+|-------|-----------|---------|
+| issue-triage | .ai-team/skills/issue-triage/ | Issue classification |
+| ci-failure-analysis | .ai-team/skills/ci-failure-analysis/ | CI failure investigation |
+| regression-checklist | .ai-team/skills/regression-checklist/ | Regression testing |
+| release-readiness-check | .ai-team/skills/release-readiness-check/ | Pre-release validation |
+EOF
+echo -e "${GREEN}  Created: skill-inventory.md${NC}"
+
+# Generate command inventory
+echo -e "${CYAN}Generating command inventory...${NC}"
+cat > "$OUTPUT_DIR/command-inventory.md" << EOF
+# Command Inventory
+
+Generated: $(date -I)
+Foundation Version: $VERSION
+
+## Available Commands
+
+| Command | Agent | Purpose |
+|---------|-------|---------|
+| /triage | Triage | Classify and investigate issue |
+| /design | Architect | Analyze requirements and design |
+| /implement | Developer | Implement changes |
+| /test | QA | Run tests and validate |
+| /review | Reviewer | Review code |
+| /ci-analyze | CI Analyst | Analyze CI failures |
+| /release-check | Reviewer | Validate release readiness |
+
+## Usage
+
+In a GitHub Issue or PR comment:
+
+\`\`\`
+/opencode use <agent> to <action>
+\`\`\`
+
+Examples:
+\`\`\`
+/opencode use architect to design this feature
+/opencode use developer to implement the solution
+/opencode use qa to validate the changes
+\`\`\`
+EOF
+echo -e "${GREEN}  Created: command-inventory.md${NC}"
+
+# Generate structure overview
+echo -e "${CYAN}Generating structure overview...${NC}"
+cat > "$OUTPUT_DIR/structure-overview.md" << EOF
+# Foundation Structure Overview
+
+Generated: $(date -I)
+Foundation Version: $VERSION
+
+## Directory Structure
+
+\`\`\`
+ai-team-foundation/
+├── .ai-team/                 # AI Team core configuration
+│   ├── agents/               # Agent definitions (7 roles)
+│   ├── skills/               # Skill definitions (9 skills)
+│   ├── commands/             # Command definitions (7 commands)
+│   ├── memory/               # Memory templates (8 areas)
+│   └── opencode.template.jsonc
+│
+├── .github/                  # GitHub configuration
+│   ├── workflows/            # GitHub Actions workflows
+│   └── ISSUE_TEMPLATE/       # Issue templates
+│
+├── docs/                     # Documentation
+│   ├── architecture/         # Architecture documents
+│   ├── decisions/            # Decision records (ADRs)
+│   ├── patterns/             # Implementation patterns
+│   ├── releases/             # Release documentation
+│   └── runbooks/ci/          # CI operational runbooks
+│
+├── scripts/                  # Bootstrap scripts
+│   ├── init_project.sh
+│   ├── validate_foundation.sh
+│   ├── validate_project_setup.sh
+│   ├── plan_upgrade.sh
+│   ├── upgrade_foundation.sh
+│   ├── diff_foundation_vs_project.sh
+│   └── generate_docs.sh
+│
+├── overlays/                 # Technology overlays
+│
+├── tasks/                    # Task templates
+│   └── _template/
+│
+├── VERSION                   # Current version
+├── CHANGELOG.md              # Version history
+├── AGENTS.md                 # Global rules
+└── README.md                 # Project overview
+\`\`\`
+
+## File Classification
+
+| Class | Description | Upgrade Behavior |
+|-------|-------------|------------------|
+| A | Auto-generatable | Safe to create/replace automatically |
+| B | Review required | Generate diff, human reviews before applying |
+| C | Protected | Human approval mandatory, never auto-modified |
+
+## Key Files
+
+- **VERSION**: Current foundation version
+- **CHANGELOG.md**: Version history and migration notes
+- **AGENTS.md**: Global rules for all AI agents
+- **opencode.template.jsonc**: Template for project configuration
+EOF
+echo -e "${GREEN}  Created: structure-overview.md${NC}"
+
+echo ""
+echo -e "${GREEN}Documentation generated in: $OUTPUT_DIR/${NC}"
+echo ""

package/scripts/init_project.sh

@@ -0,0 +1,455 @@
+#!/bin/bash
+# init_project.sh
+# Initialize a new downstream project from the foundation base
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+FOUNDATION_ROOT="$(dirname "$SCRIPT_DIR")"
+
+# Default values
+PROJECT_NAME=""
+PROJECT_PATH=""
+OVERLAY=""
+LANGUAGE="typescript"
+FRAMEWORK="node"
+DESCRIPTION=""
+FORCE=false
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+CYAN='\033[0;36m'
+NC='\033[0m' # No Color
+
+usage() {
+    echo "Usage: $0 [OPTIONS] <project-name>"
+    echo ""
+    echo "Initialize a new downstream project from AI Team Foundation."
+    echo ""
+    echo "Options:"
+    echo "  -p, --path <path>       Target directory path (default: ./<project-name>)"
+    echo "  -o, --overlay <name>    Apply overlay (cpp-qt-desktop, python-backend, web-fullstack)"
+    echo "  -l, --language <lang>   Programming language (default: typescript)"
+    echo "  -f, --framework <name>  Framework name (default: node)"
+    echo "  -d, --description <d>   Project description"
+    echo "  --force                 Overwrite existing directory"
+    echo "  -h, --help              Show this help message"
+    echo ""
+    echo "Examples:"
+    echo "  $0 my-awesome-project"
+    echo "  $0 -o python-backend -l python my-api"
+    echo "  $0 -o cpp-qt-desktop -l cpp my-desktop-app"
+}
+
+parse_args() {
+    while [[ $# -gt 0 ]]; do
+        case $1 in
+            -p|--path)
+                PROJECT_PATH="$2"
+                shift 2
+                ;;
+            -o|--overlay)
+                OVERLAY="$2"
+                shift 2
+                ;;
+            -l|--language)
+                LANGUAGE="$2"
+                shift 2
+                ;;
+            -f|--framework)
+                FRAMEWORK="$2"
+                shift 2
+                ;;
+            -d|--description)
+                DESCRIPTION="$2"
+                shift 2
+                ;;
+            --force)
+                FORCE=true
+                shift
+                ;;
+            -h|--help)
+                usage
+                exit 0
+                ;;
+            *)
+                if [[ -z "$PROJECT_NAME" ]]; then
+                    PROJECT_NAME="$1"
+                fi
+                shift
+                ;;
+        esac
+    done
+}
+
+log_info() {
+    echo -e "${CYAN}[INFO]${NC} $1"
+}
+
+log_success() {
+    echo -e "${GREEN}[SUCCESS]${NC} $1"
+}
+
+log_warning() {
+    echo -e "${YELLOW}[WARNING]${NC} $1"
+}
+
+log_error() {
+    echo -e "${RED}[ERROR]${NC} $1"
+}
+
+check_prerequisites() {
+    if [[ -z "$PROJECT_NAME" ]]; then
+        log_error "Project name is required"
+        usage
+        exit 1
+    fi
+    
+    if [[ -z "$PROJECT_PATH" ]]; then
+        PROJECT_PATH="./$PROJECT_NAME"
+    fi
+    
+    if [[ -d "$PROJECT_PATH" ]] && [[ "$FORCE" != true ]]; then
+        log_error "Directory $PROJECT_PATH already exists. Use --force to overwrite."
+        exit 1
+    fi
+    
+    if [[ -n "$OVERLAY" ]] && [[ ! -d "$FOUNDATION_ROOT/overlays/$OVERLAY" ]]; then
+        log_error "Overlay '$OVERLAY' not found"
+        log_info "Available overlays:"
+        ls -1 "$FOUNDATION_ROOT/overlays" 2>/dev/null || echo "  (none)"
+        exit 1
+    fi
+}
+
+read_version() {
+    VERSION=$(cat "$FOUNDATION_ROOT/VERSION" 2>/dev/null || echo "unknown")
+}
+
+create_directory_structure() {
+    log_info "Creating directory structure..."
+    
+    # Core directories
+    mkdir -p "$PROJECT_PATH/.ai-team/agents"
+    mkdir -p "$PROJECT_PATH/.ai-team/skills"
+    mkdir -p "$PROJECT_PATH/.ai-team/commands"
+    mkdir -p "$PROJECT_PATH/.ai-team/memory"
+    
+    # Memory directories for all roles
+    mkdir -p "$PROJECT_PATH/.ai-team/memory/planner"
+    mkdir -p "$PROJECT_PATH/.ai-team/memory/architect"
+    mkdir -p "$PROJECT_PATH/.ai-team/memory/developer"
+    mkdir -p "$PROJECT_PATH/.ai-team/memory/qa"
+    mkdir -p "$PROJECT_PATH/.ai-team/memory/reviewer"
+    mkdir -p "$PROJECT_PATH/.ai-team/memory/triage"
+    mkdir -p "$PROJECT_PATH/.ai-team/memory/ci-analyst"
+    mkdir -p "$PROJECT_PATH/.ai-team/memory/failures"
+    
+    # GitHub directories
+    mkdir -p "$PROJECT_PATH/.github/workflows"
+    mkdir -p "$PROJECT_PATH/.github/ISSUE_TEMPLATE"
+    
+    # Documentation directories
+    mkdir -p "$PROJECT_PATH/docs/architecture"
+    mkdir -p "$PROJECT_PATH/docs/decisions"
+    mkdir -p "$PROJECT_PATH/docs/patterns"
+    mkdir -p "$PROJECT_PATH/docs/releases"
+    mkdir -p "$PROJECT_PATH/docs/runbooks/ci"
+    
+    # Task directories
+    mkdir -p "$PROJECT_PATH/tasks/_template"
+    
+    # Foundation metadata
+    mkdir -p "$PROJECT_PATH/.foundation"
+    
+    # Source directories
+    mkdir -p "$PROJECT_PATH/src"
+    mkdir -p "$PROJECT_PATH/tests"
+}
+
+copy_base_templates() {
+    log_info "Copying base templates..."
+    
+    # Copy .ai-team structure
+    if [[ -d "$FOUNDATION_ROOT/.ai-team" ]]; then
+        cp -r "$FOUNDATION_ROOT/.ai-team/agents"/* "$PROJECT_PATH/.ai-team/agents/" 2>/dev/null || true
+        cp -r "$FOUNDATION_ROOT/.ai-team/skills"/* "$PROJECT_PATH/.ai-team/skills/" 2>/dev/null || true
+        cp -r "$FOUNDATION_ROOT/.ai-team/commands"/* "$PROJECT_PATH/.ai-team/commands/" 2>/dev/null || true
+        cp -r "$FOUNDATION_ROOT/.ai-team/memory"/* "$PROJECT_PATH/.ai-team/memory/" 2>/dev/null || true
+        cp "$FOUNDATION_ROOT/.ai-team/opencode.template.jsonc" "$PROJECT_PATH/.ai-team/" 2>/dev/null || true
+    fi
+    
+    # Copy GitHub workflows
+    if [[ -d "$FOUNDATION_ROOT/.github/workflows" ]]; then
+        cp -r "$FOUNDATION_ROOT/.github/workflows"/* "$PROJECT_PATH/.github/workflows/" 2>/dev/null || true
+    fi
+    
+    # Copy Issue templates
+    if [[ -d "$FOUNDATION_ROOT/.github/ISSUE_TEMPLATE" ]]; then
+        cp -r "$FOUNDATION_ROOT/.github/ISSUE_TEMPLATE"/* "$PROJECT_PATH/.github/ISSUE_TEMPLATE/" 2>/dev/null || true
+    fi
+    
+    # Copy PR template
+    cp "$FOUNDATION_ROOT/.github/pull_request_template.md" "$PROJECT_PATH/.github/" 2>/dev/null || true
+    
+    # Copy task templates
+    if [[ -d "$FOUNDATION_ROOT/tasks/_template" ]]; then
+        cp -r "$FOUNDATION_ROOT/tasks/_template"/* "$PROJECT_PATH/tasks/_template/" 2>/dev/null || true
+    fi
+    
+    # Copy AGENTS.md
+    cp "$FOUNDATION_ROOT/AGENTS.md" "$PROJECT_PATH/" 2>/dev/null || true
+}
+
+apply_overlay() {
+    if [[ -z "$OVERLAY" ]]; then
+        return
+    fi
+    
+    log_info "Applying overlay: $OVERLAY"
+    
+    OVERLAY_PATH="$FOUNDATION_ROOT/overlays/$OVERLAY"
+    
+    if [[ ! -d "$OVERLAY_PATH" ]]; then
+        log_warning "Overlay directory not found, skipping..."
+        return
+    fi
+    
+    # Copy overlay files (these may override base files)
+    if [[ -d "$OVERLAY_PATH/.ai-team" ]]; then
+        cp -r "$OVERLAY_PATH/.ai-team"/* "$PROJECT_PATH/.ai-team/" 2>/dev/null || true
+    fi
+    
+    if [[ -d "$OVERLAY_PATH/.github" ]]; then
+        cp -r "$OVERLAY_PATH/.github"/* "$PROJECT_PATH/.github/" 2>/dev/null || true
+    fi
+    
+    if [[ -d "$OVERLAY_PATH/docs" ]]; then
+        cp -r "$OVERLAY_PATH/docs"/* "$PROJECT_PATH/docs/" 2>/dev/null || true
+    fi
+}
+
+create_foundation_lock() {
+    log_info "Creating foundation lock file..."
+    
+    cat > "$PROJECT_PATH/.foundation/foundation.lock" << EOF
+foundation_repo: ai-team-foundation
+foundation_version: $VERSION
+overlay: ${OVERLAY:-none}
+initialized_at: $(date -I)
+last_upgrade_at: $(date -I)
+upgrade_policy: controlled
+language: $LANGUAGE
+framework: $FRAMEWORK
+EOF
+}
+
+create_upgrade_history() {
+    cat > "$PROJECT_PATH/.foundation/upgrade-history.md" << EOF
+# Upgrade History
+
+This file records all foundation upgrades applied to this project.
+
+## Initial Setup
+
+- **Date**: $(date -I)
+- **Foundation Version**: $VERSION
+- **Overlay**: ${OVERLAY:-none}
+- **Action**: Initial project creation
+
+EOF
+}
+
+create_local_overrides() {
+    cat > "$PROJECT_PATH/.foundation/local-overrides.md" << EOF
+# Local Overrides
+
+This file documents project-specific customizations that should be preserved during upgrades.
+
+## Customizations
+
+<!-- Document any local changes to templates, workflows, or configuration -->
+
+- [ ] Custom AGENTS.md additions
+- [ ] Custom workflows
+- [ ] Custom skills or commands
+- [ ] Project-specific memory rules
+
+EOF
+}
+
+create_project_config() {
+    log_info "Creating project configuration..."
+    
+    cat > "$PROJECT_PATH/ai-team.config.yaml" << EOF
+# AI Team Project Configuration
+# This file is project-specific and will not be overwritten during upgrades
+
+project:
+  name: "$PROJECT_NAME"
+  description: "${DESCRIPTION:-My awesome project}"
+  language: "$LANGUAGE"
+  framework: "$FRAMEWORK"
+
+ai_team:
+  version: "$VERSION"
+  
+  agents:
+    planner: true
+    architect: true
+    developer: true
+    qa: true
+    reviewer: true
+    triage: true
+    ci_analyst: true
+
+  memory:
+    enabled: true
+    isolation: true
+    failures_library: true
+
+  task_system:
+    enabled: true
+    state_machine: true
+
+rules:
+  coding:
+    max_function_lines: 30
+    test_coverage_threshold: 80
+  
+  git:
+    commit_convention: "conventional"
+  
+  governance:
+    protected_paths:
+      - "docs/architecture/"
+      - "docs/decisions/"
+
+# Add project-specific configuration below
+EOF
+}
+
+generate_opencode_config() {
+    log_info "Generating opencode.jsonc..."
+    
+    if [[ -f "$FOUNDATION_ROOT/.ai-team/opencode.template.jsonc" ]]; then
+        # Replace template variables
+        sed -e "s/{{AI_TEAM_VERSION}}/$VERSION/g" \
+            -e "s/{{PROJECT_NAME}}/$PROJECT_NAME/g" \
+            -e "s/{{PROJECT_DESCRIPTION}}/${DESCRIPTION:-My awesome project}/g" \
+            -e "s/{{LANGUAGE}}/$LANGUAGE/g" \
+            -e "s/{{FRAMEWORK}}/$FRAMEWORK/g" \
+            "$FOUNDATION_ROOT/.ai-team/opencode.template.jsonc" \
+            > "$PROJECT_PATH/opencode.jsonc"
+    fi
+}
+
+create_readme() {
+    log_info "Creating README.md..."
+    
+    cat > "$PROJECT_PATH/README.md" << EOF
+# $PROJECT_NAME
+
+${DESCRIPTION:-}
+
+## AI Team
+
+This project uses [AI Team Foundation](https://github.com/your-org/ai-team-foundation) v$VERSION.
+
+### Quick Start
+
+1. Configure GitHub Secrets:
+   - \`ALIBABA_CODING_PLAN_API_KEY\` or \`OPENCODE_API_KEY\`
+
+2. Create an Issue using a template
+
+3. Trigger AI:
+   \`\`\`
+   /opencode use architect to analyze this issue
+   \`\`\`
+
+### Available Commands
+
+| Command | Agent | Purpose |
+|---------|-------|---------|
+| \`/triage\` | Triage | Issue classification |
+| \`/design\` | Architect | Design solution |
+| \`/implement\` | Developer | Implement changes |
+| \`/test\` | QA | Validate implementation |
+| \`/review\` | Reviewer | Code review |
+| \`/ci-analyze\` | CI Analyst | CI failure analysis |
+| \`/release-check\` | Reviewer | Release readiness |
+
+## Development
+
+\`\`\`bash
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Run linting
+npm run lint
+
+# Validate AI Team setup
+node scripts/validate_project_setup.cjs
+\`\`\`
+
+## License
+
+MIT
+EOF
+}
+
+print_next_steps() {
+    echo ""
+    log_success "Project initialized successfully!"
+    echo ""
+    echo -e "${CYAN}Project created at:${NC} $PROJECT_PATH"
+    echo ""
+    echo -e "${CYAN}Next steps:${NC}"
+    echo "  1. cd $PROJECT_PATH"
+    echo "  2. Review and customize ai-team.config.yaml"
+    echo "  3. Add your GitHub secrets (ALIBABA_CODING_PLAN_API_KEY)"
+    echo "  4. Create your first issue!"
+    echo ""
+    echo -e "${CYAN}Foundation version:${NC} $VERSION"
+    if [[ -n "$OVERLAY" ]]; then
+        echo -e "${CYAN}Overlay:${NC} $OVERLAY"
+    fi
+    echo ""
+}
+
+# Main execution
+main() {
+    parse_args "$@"
+    check_prerequisites
+    read_version
+    
+    log_info "Initializing project: $PROJECT_NAME"
+    log_info "Foundation version: $VERSION"
+    
+    # Remove existing if force
+    if [[ "$FORCE" == true ]] && [[ -d "$PROJECT_PATH" ]]; then
+        log_warning "Removing existing directory..."
+        rm -rf "$PROJECT_PATH"
+    fi
+    
+    create_directory_structure
+    copy_base_templates
+    apply_overlay
+    create_foundation_lock
+    create_upgrade_history
+    create_local_overrides
+    create_project_config
+    generate_opencode_config
+    create_readme
+    
+    print_next_steps
+}
+
+main "$@"