amazingteam 3.0.0

package/docs/blocker_resolution_design.md

@@ -0,0 +1,372 @@
+# Issue Blocker Resolution Design
+
+## Overview
+
+This document defines the process for handling blockers encountered during automated workflow execution.
+
+## Problem Handling Flow
+
+```
+Workflow Execution
+        │
+        ▼ (Encounter Problem)
+┌───────────────┐
+│ Problem Detect│
+└───────┬───────┘
+        │
+        ▼
+┌───────────────┐
+│   Dispatch    │
+│ to CI Analyst │
+│   (Diagnose)  │
+└───────┬───────┘
+        │
+        ▼
+┌───────────────┐
+│ Classification│
+│  & Analysis   │
+└───────┬───────┘
+        │
+        ▼
+   ┌────┴────┐
+   │Decision │
+   └────┬────┘
+        │
+   ┌────┴────────────────┐
+   ↓                     ↓
+Can Resolve           Cannot Resolve
+Now                    │
+   │                     ▼
+   │            ┌────────────────┐
+   │            │ Create Sub-issue│
+   │            │   (Blocker)     │
+   │            └───────┬────────┘
+   │                    │
+   │                    ▼
+   │               ┌────┴────┐
+   │               │ Needs   │
+   │               │ Human?  │
+   │               └────┬────┘
+   │                    │
+   │           ┌────────┴────────┐
+   │           ↓                 ↓
+   │          Yes               No
+   │           │                 │
+   │           ▼                 ▼
+   │    ┌─────────────┐   ┌─────────────┐
+   │    │ Notify Human│   │ Auto-resolve│
+   │    │ (Wait)      │   │ Sub-issue   │
+   │    └──────┬──────┘   └──────┬──────┘
+   │           │                 │
+   │           │                 ▼
+   │           │          Sub-issue Done
+   │           │                 │
+   │           └────────┬────────┘
+   │                    │
+   └────────────────────┤
+                        ▼
+               Resume Original Task
+```
+
+## Blocker Categories
+
+### Category 1: Auto-Resolvable
+
+| Blocker Type | Description | Resolution |
+|--------------|-------------|------------|
+| Code Error | Syntax, type errors | Auto-fix by Developer |
+| Missing Import | Import statement missing | Auto-add import |
+| Test Failure | Logic error in test | Auto-fix test |
+| Lint Error | Style violation | Auto-fix with linter |
+| Missing Dependency | Package not installed | Auto-install |
+| Config Error | Wrong configuration | Auto-correct |
+
+### Category 2: Sub-issue Resolvable (AI)
+
+| Blocker Type | Description | Action |
+|--------------|-------------|--------|
+| Complex Bug | Requires investigation | Create sub-issue, auto-resolve |
+| API Change | External API changed | Create sub-issue, adapt code |
+| Performance Issue | Slow performance | Create sub-issue, optimize |
+| Missing Feature | Prerequisite not implemented | Create sub-issue, implement |
+
+### Category 3: Human Required
+
+| Blocker Type | Description | Action |
+|--------------|-------------|--------|
+| Permission Denied | No access to resource | Notify human, wait |
+| Secret Missing | API key or credential needed | Notify human, wait |
+| Architecture Decision | Major design choice | Notify human, wait |
+| External Dependency | Third-party service down | Notify human, wait |
+| Business Logic Unclear | Requirements ambiguous | Notify human, wait |
+| Security Issue | Potential vulnerability | Notify human, wait |
+
+## Decision Matrix
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    BLOCKER RESOLUTION MATRIX                     │
+├─────────────────┬───────────────┬─────────────┬────────────────┤
+│     Factor      │    Low        │   Medium    │     High       │
+├─────────────────┼───────────────┼─────────────┼────────────────┤
+│ Complexity      │ Auto-fix now  │ Sub-issue   │ Notify Human   │
+│ Risk            │ Auto-fix now  │ Sub-issue   │ Notify Human   │
+│ External Dep    │ Sub-issue     │ Sub-issue   │ Notify Human   │
+│ Permission      │ Sub-issue     │ Notify Human│ Notify Human   │
+│ Business Impact │ Auto-fix now  │ Sub-issue   │ Notify Human   │
+└─────────────────┴───────────────┴─────────────┴────────────────┘
+```
+
+## Process Details
+
+### Step 1: Problem Detection
+
+When workflow encounters an error:
+1. Capture error context
+2. Save current workflow state
+3. Pause workflow execution
+4. Dispatch to CI Analyst
+
+### Step 2: Diagnosis (CI Analyst)
+
+CI Analyst performs:
+1. Analyze error logs
+2. Identify root cause
+3. Classify blocker type
+4. Determine resolution path
+5. Estimate resolution effort
+
+Output:
+```markdown
+## Blocker Analysis
+
+- **Type**: [code/infra/permission/external/unknown]
+- **Severity**: [low/medium/high/critical]
+- **Complexity**: [simple/moderate/complex]
+- **Risk Level**: [low/medium/high]
+- **Can Auto-Resolve**: [yes/no/partial]
+- **Needs Human**: [yes/no]
+
+### Root Cause
+[Description]
+
+### Recommended Action
+- [ ] Auto-fix now
+- [ ] Create sub-issue (AI resolve)
+- [ ] Create sub-issue (Human required)
+- [ ] Notify human immediately
+```
+
+### Step 3: Resolution Path
+
+#### Path A: Auto-Resolve Now
+
+For simple, low-risk blockers:
+1. Developer fixes the issue
+2. Continue workflow immediately
+3. Log the fix
+
+#### Path B: Create Sub-issue (AI Resolve)
+
+For moderate complexity blockers:
+1. Create blocker sub-issue
+2. Execute sub-issue resolution
+3. Verify fix
+4. Continue original workflow
+
+#### Path C: Notify Human
+
+For blockers requiring human intervention:
+1. Create blocker sub-issue
+2. Send notification
+3. Pause workflow
+4. Wait for human resolution
+5. Resume after human input
+
+## Sub-issue Creation
+
+### Blocker Sub-issue Template
+
+```bash
+gh issue create \
+  --title "[Blocker] {blocker_description}" \
+  --body "## Parent Issue
+#{parent_issue_id}
+
+## Blocking Reason
+{why this blocks the workflow}
+
+## Analysis
+- **Type**: {type}
+- **Severity**: {severity}
+- **Complexity**: {complexity}
+
+## Root Cause
+{root_cause}
+
+## Recommended Resolution
+{suggested_fix}
+
+## Requires Human
+{yes/no}
+
+## Reason for Human Involvement
+{if yes, explain why AI cannot resolve}
+
+## Acceptance Criteria
+- [ ] Blocker resolved
+- [ ] Workflow can resume
+
+## Impact
+- **Blocked Issue**: #{parent_issue_id}
+- **Blocked Workflow Phase**: {phase}
+- **Time Sensitive**: {yes/no}" \
+  --label "type:blocker,priority:{priority}"
+```
+
+## Human Notification
+
+### Notification Channels
+
+| Channel | When to Use |
+|---------|-------------|
+| Issue Comment | Always (primary) |
+| Email | Critical blockers, time-sensitive |
+| Slack/Teams | Critical blockers requiring immediate attention |
+
+### Notification Template
+
+```markdown
+## ⚠️ Workflow Blocked - Human Attention Required
+
+**Issue**: #{issue_id} - {issue_title}
+**Blocker**: #{blocker_issue_id} - {blocker_title}
+
+### Summary
+{brief description of the blocker}
+
+### Why Human is Needed
+{explanation of why AI cannot resolve}
+
+### Suggested Actions
+1. {action_1}
+2. {action_2}
+
+### Resume Command
+After resolving the blocker, comment:
+```
+/oc /resume
+```
+
+### Time Sensitivity
+{critical/high/medium/low}
+
+---
+*This is an automated notification from the AI Team workflow.*
+```
+
+## Resume Workflow
+
+After blocker resolution:
+1. Verify blocker is resolved
+2. Restore workflow state
+3. Continue from last successful step
+4. Log resolution
+
+### Resume Command
+
+```markdown
+/oc /resume
+
+# Or with additional context
+/oc /resume
+The permission issue has been fixed. Please continue.
+```
+
+## Examples
+
+### Example 1: Auto-Resolvable
+
+```
+Error: Cannot find module './utils'
+
+CI Analyst Diagnosis:
+- Type: code
+- Severity: low
+- Can Auto-Resolve: yes
+- Action: Add missing import
+
+Resolution: Developer adds import, workflow continues.
+```
+
+### Example 2: Sub-issue (AI Resolve)
+
+```
+Error: API endpoint /v2/users not found
+
+CI Analyst Diagnosis:
+- Type: external
+- Severity: medium
+- Can Auto-Resolve: no (requires code change)
+- Needs Human: no
+- Action: Create sub-issue to update API endpoint
+
+Resolution:
+1. Create sub-issue #205: Update API endpoint to /v3/users
+2. Developer implements fix
+3. Tests pass
+4. Resume original workflow
+```
+
+### Example 3: Human Required
+
+```
+Error: Permission denied: Cannot push to protected branch 'main'
+
+CI Analyst Diagnosis:
+- Type: permission
+- Severity: high
+- Can Auto-Resolve: no
+- Needs Human: yes (branch protection rules)
+- Action: Notify human
+
+Resolution:
+1. Create blocker sub-issue #206
+2. Post notification on parent issue
+3. Send email if critical
+4. Wait for human to:
+   - Temporarily disable branch protection
+   - OR grant required permissions
+   - OR provide alternative approach
+5. Human comments `/oc /resume`
+6. Continue workflow
+```
+
+## Integration with /auto Command
+
+The `/auto` command integrates blocker handling:
+
+```markdown
+## /auto Command Flow with Blockers
+
+1. Triage → Design → Implement
+2. If blocker encountered:
+   a. Pause
+   b. Dispatch to CI Analyst
+   c. Diagnose
+   d. Resolve (auto/sub-issue/human)
+   e. Resume
+3. Continue: Test → Create PR
+```
+
+## Metrics
+
+Track blocker metrics for improvement:
+
+| Metric | Description |
+|--------|-------------|
+| Blocker Rate | Blockers per issue |
+| Auto-Resolve Rate | % auto-resolved |
+| Human Intervention Rate | % requiring human |
+| Avg Resolution Time | Time to unblock |
+| Common Blocker Types | Most frequent blockers |

package/docs/bootstrap-model.md

@@ -0,0 +1,356 @@
+# Bootstrap Model
+
+This document describes the self-bootstrap capability of AI Team Foundation.
+
+## Philosophy
+
+The foundation repository supports **controlled operational bootstrap**, not uncontrolled autonomous mutation.
+
+### The Foundation Should Be Able To
+
+- Initialize new downstream projects
+- Validate its own integrity
+- Validate downstream project setup
+- Plan controlled upgrades
+- Apply safe, reviewable upgrades
+- Generate operational documentation
+
+### The Foundation Should NOT Automatically
+
+- Rewrite its own core governance
+- Rewrite durable truth documents casually
+- Upgrade all downstream projects without approval
+- Merge downstream customizations back into foundation
+- Overwrite protected project-specific configuration
+
+## Capability Categories
+
+### 1. Initialization Capability
+
+**Purpose**: Create new downstream project repositories from the foundation.
+
+**Responsibilities**:
+- Copy base structure
+- Apply selected overlay (if any)
+- Initialize `.ai-team/`, `.github/`, `docs/`, `tasks/`
+- Create foundation lock metadata
+
+**Script**: `scripts/init_project.sh`
+
+**When to Use**:
+- Starting a new project
+- Creating a project from a specific overlay
+
+---
+
+### 2. Validation Capability
+
+**Purpose**: Check structural completeness and policy compliance.
+
+**Responsibilities**:
+- Verify required directories
+- Verify required templates
+- Verify agent/skill/command files
+- Verify version metadata
+
+**Scripts**:
+- `scripts/validate_foundation.sh` - Validate foundation itself
+- `scripts/validate_project_setup.sh` - Validate downstream project
+
+**When to Use**:
+- After initialization
+- After upgrade
+- In CI pipeline
+- Before release
+
+---
+
+### 3. Upgrade Planning Capability
+
+**Purpose**: Compare downstream project with foundation release.
+
+**Responsibilities**:
+- Detect missing files
+- Detect outdated templates
+- Detect local overrides
+- Classify upgrade risk
+- Generate upgrade report
+
+**Script**: `scripts/plan_upgrade.sh`
+
+**When to Use**:
+- When new foundation version is released
+- Before applying upgrades
+- To audit project drift
+
+---
+
+### 4. Controlled Upgrade Capability
+
+**Purpose**: Apply upgrades after review and approval.
+
+**Responsibilities**:
+- Create missing directories
+- Add new template files
+- Patch allowed files
+- Preserve local overrides
+- Log upgrade history
+
+**Script**: `scripts/upgrade_foundation.sh`
+
+**Approval Gates**:
+- Class A: May be automatic
+- Class B: Requires review
+- Class C: Requires explicit approval
+
+---
+
+### 5. Documentation Generation Capability
+
+**Purpose**: Generate operational documentation.
+
+**Responsibilities**:
+- Generate structure docs
+- Generate role/skill inventories
+- Generate version docs
+
+**Script**: `scripts/generate_docs.sh`
+
+**When to Use**:
+- After major changes
+- For documentation updates
+- To audit current state
+
+---
+
+## Operating Modes
+
+### Mode A: init
+
+Initialize a new project.
+
+```bash
+./scripts/init_project.sh my-project
+./scripts/init_project.sh -o python-backend my-api
+```
+
+**Behavior**:
+- Creates new scaffold
+- Applies base templates
+- Applies selected overlay
+- Creates lock metadata
+- Does NOT touch business code
+
+---
+
+### Mode B: validate
+
+Validate structure (read-only).
+
+```bash
+./scripts/validate_foundation.sh
+./scripts/validate_project_setup.sh /path/to/project
+```
+
+**Behavior**:
+- Read-only
+- No changes applied
+- Returns validation report
+- Identifies missing or inconsistent elements
+
+---
+
+### Mode C: plan-upgrade
+
+Analyze upgrade requirements (read-only).
+
+```bash
+./scripts/plan_upgrade.sh /path/to/project
+```
+
+**Behavior**:
+- Read-only
+- Compares against foundation version
+- Classifies changes
+- Generates upgrade report
+- Identifies conflicts
+
+---
+
+### Mode D: apply-upgrade
+
+Perform controlled upgrade.
+
+```bash
+./scripts/upgrade_foundation.sh /path/to/project
+./scripts/upgrade_foundation.sh --dry-run /path/to/project
+```
+
+**Behavior**:
+- Applies only allowed changes
+- Preserves local overrides
+- Stops on protected conflicts
+- Writes upgrade history
+- Updates lock metadata
+
+---
+
+## File Classification
+
+### Class A: Auto-Generatable
+
+Safe to create or replace automatically.
+
+**Examples**:
+- Empty directory placeholders
+- Task templates
+- Issue templates
+- Base workflow drafts
+- Missing skill skeletons
+
+**Upgrade Policy**: May be automatically created/replaced.
+
+---
+
+### Class B: Review Required
+
+Can receive update proposals, but not silently overwritten.
+
+**Examples**:
+- `AGENTS.md`
+- Agent prompt files
+- Command files
+- Skill definitions
+- Workflow files
+
+**Upgrade Policy**: Generate diff, human reviews, then apply.
+
+---
+
+### Class C: Protected
+
+Must not be changed automatically without explicit approval.
+
+**Examples**:
+- `docs/architecture/`
+- `docs/decisions/`
+- Governance policy
+- Standards policy
+
+**Upgrade Policy**: Human-reviewed only. Never auto-modified.
+
+---
+
+## Approval Gates
+
+### Gate 1: Additive Scaffold
+
+**Examples**:
+- Create missing folder
+- Create missing template file
+
+**Approval**: May be automatic
+
+---
+
+### Gate 2: Patch Proposal
+
+**Examples**:
+- Update `AGENTS.md`
+- Update agent prompts
+- Update workflow templates
+
+**Approval**: Generate diff → Human review → Apply
+
+---
+
+### Gate 3: Protected Knowledge
+
+**Examples**:
+- Update `docs/architecture/`
+- Update `docs/decisions/`
+- Update governance policy
+
+**Approval**: Human approval required before any write
+
+---
+
+### Gate 4: Multi-Project Rollout
+
+**Examples**:
+- Applying new foundation version to many projects
+
+**Approval**: Per-project or explicitly approved batch process only
+
+---
+
+## Safe Operations
+
+✅ **Allowed**:
+- Create missing directories
+- Create missing template files
+- Generate documentation
+- Validate repository structure
+- Compare versions
+- Generate upgrade plans
+- Apply additive upgrades to safe file classes
+- Update lock metadata
+- Update upgrade history
+
+❌ **Blocked by Default**:
+- Rewrite durable truth docs automatically
+- Overwrite local project overrides without confirmation
+- Rewrite role policy arbitrarily
+- Rewrite foundation governance without approval
+- Mass-upgrade all downstream projects automatically
+- Auto-merge downstream changes back into foundation
+
+---
+
+## Anti-Patterns
+
+### Anti-Pattern 1: Infinite Self-Rewrite
+
+The foundation automatically rewrites its own governance and role policies.
+
+**Why Bad**: Destroys stability and traceability.
+
+---
+
+### Anti-Pattern 2: Automatic Global Rollout
+
+A new foundation version pushes itself to every downstream project automatically.
+
+**Why Bad**: Different projects have different risks and customizations.
+
+---
+
+### Anti-Pattern 3: Foundation as Business Repo
+
+The foundation stores real project tasks and project-specific memory.
+
+**Why Bad**: Breaks reusability.
+
+---
+
+### Anti-Pattern 4: No Lock File
+
+Downstream projects do not record which foundation version they use.
+
+**Why Bad**: Upgrades become chaotic.
+
+---
+
+### Anti-Pattern 5: No File Classification
+
+All files are treated as equally safe to overwrite.
+
+**Why Bad**: Critical governance or customized files get damaged.
+
+---
+
+## Summary
+
+**The foundation should be self-bootstrapping, but not self-governing without human oversight.**
+
+This is the correct balance for a reusable AI team foundation product.