aios-core 2.1.5 → 2.2.0

package/.aios-core/development/tasks/analyze-brownfield.md

@@ -0,0 +1,456 @@
+---
+
+## Execution Modes
+
+**Choose your execution mode:**
+
+### 1. YOLO Mode - Fast, Autonomous (0-1 prompts)
+- Quick scan with default recommendations
+- Minimal user interaction
+- **Best for:** Initial assessment, quick checks
+
+### 2. Interactive Mode - Balanced, Educational (5-10 prompts) **[DEFAULT]**
+- Detailed analysis with explanation
+- User confirmation on recommendations
+- **Best for:** First-time brownfield integration
+
+### 3. Pre-Flight Planning - Comprehensive Upfront Planning
+- Full conflict analysis
+- Manual review items prioritized
+- **Best for:** Large existing projects, enterprise codebases
+
+**Parameter:** `mode` (optional, default: `interactive`)
+
+---
+
+## Task Definition (AIOS Task Format V1.0)
+
+```yaml
+task: analyzeBrownfield()
+responsible: architect (Architect)
+responsible_type: Agent
+atomic_layer: Analysis
+
+inputs:
+- field: targetDir
+  type: string
+  source: User Input or cwd
+  required: false
+  validation: Valid directory path with existing project
+
+- field: outputFormat
+  type: string
+  source: User Input
+  required: false
+  validation: report|json|summary
+
+- field: executionMode
+  type: string
+  source: User Input
+  required: false
+  validation: yolo|interactive|pre-flight
+
+outputs:
+- field: analysis
+  type: BrownfieldAnalysis
+  destination: Memory/Console
+  persisted: false
+
+- field: report
+  type: string
+  destination: Console or File
+  persisted: optional
+
+- field: recommendations
+  type: array
+  destination: Memory
+  persisted: false
+```
+
+---
+
+## Pre-Conditions
+
+**Purpose:** Validate prerequisites BEFORE task execution (blocking)
+
+**Checklist:**
+
+```yaml
+pre-conditions:
+  - [ ] Target directory exists and contains a project
+    type: pre-condition
+    blocker: true
+    validation: |
+      Check target directory exists and has project markers (package.json, go.mod, etc.)
+    error_message: "Pre-condition failed: No project found in target directory"
+
+  - [ ] Brownfield Analyzer module is available
+    type: pre-condition
+    blocker: true
+    validation: |
+      Verify .aios-core/infrastructure/scripts/documentation-integrity/brownfield-analyzer.js exists
+    error_message: "Pre-condition failed: Brownfield Analyzer module not found"
+```
+
+---
+
+## Post-Conditions
+
+**Purpose:** Validate execution success AFTER task completes
+
+**Checklist:**
+
+```yaml
+post-conditions:
+  - [ ] Analysis completed with tech stack detection
+    type: post-condition
+    blocker: true
+    validation: |
+      Verify analysis.techStack is populated
+    error_message: "Post-condition failed: Tech stack detection incomplete"
+
+  - [ ] Merge strategy determined
+    type: post-condition
+    blocker: true
+    validation: |
+      Verify analysis.mergeStrategy is set
+    error_message: "Post-condition failed: Merge strategy not determined"
+```
+
+---
+
+## Acceptance Criteria
+
+**Purpose:** Definitive pass/fail criteria for task completion
+
+**Checklist:**
+
+```yaml
+acceptance-criteria:
+  - [ ] All project markers analyzed
+    type: acceptance-criterion
+    blocker: true
+    validation: |
+      Assert tech stack, frameworks, standards, workflows analyzed
+    error_message: "Acceptance criterion not met: Incomplete analysis"
+
+  - [ ] Recommendations generated
+    type: acceptance-criterion
+    blocker: true
+    validation: |
+      Assert analysis.recommendations has at least one item
+    error_message: "Acceptance criterion not met: No recommendations generated"
+
+  - [ ] Conflicts identified if present
+    type: acceptance-criterion
+    blocker: false
+    validation: |
+      Assert potential conflicts flagged for review
+    error_message: "Warning: Conflict detection may be incomplete"
+```
+
+---
+
+## Tools
+
+**External/shared resources used by this task:**
+
+- **Tool:** brownfield-analyzer
+  - **Purpose:** Analyze existing project structure and standards
+  - **Source:** .aios-core/infrastructure/scripts/documentation-integrity/brownfield-analyzer.js
+
+- **Tool:** mode-detector
+  - **Purpose:** Collect project markers for analysis
+  - **Source:** .aios-core/infrastructure/scripts/documentation-integrity/mode-detector.js
+
+---
+
+## Scripts
+
+**Agent-specific code for this task:**
+
+- **Script:** brownfield-analyzer.js
+  - **Purpose:** Core analysis functions
+  - **Language:** JavaScript
+  - **Location:** .aios-core/infrastructure/scripts/documentation-integrity/brownfield-analyzer.js
+
+---
+
+## Error Handling
+
+**Strategy:** graceful-degradation
+
+**Common Errors:**
+
+1. **Error:** No Project Markers Found
+   - **Cause:** Empty directory or unrecognized project type
+   - **Resolution:** Check directory contains project files
+   - **Recovery:** Return minimal analysis with recommendations
+
+2. **Error:** Config Parse Error
+   - **Cause:** Malformed config file (package.json, tsconfig.json, etc.)
+   - **Resolution:** Skip problematic file, continue analysis
+   - **Recovery:** Log warning, proceed with partial analysis
+
+3. **Error:** Permission Denied
+   - **Cause:** Cannot read certain directories
+   - **Resolution:** Request elevated permissions or skip
+   - **Recovery:** Note inaccessible areas in manual review items
+
+---
+
+## Performance
+
+**Expected Metrics:**
+
+```yaml
+duration_expected: 30s-2 min (estimated)
+cost_estimated: $0.001-0.002
+token_usage: ~300-1,000 tokens
+```
+
+**Optimization Notes:**
+- File existence checks are fast
+- JSON parsing cached per file
+- Directory structure scan is O(n) for root level
+
+---
+
+## Metadata
+
+```yaml
+story: 6.9
+version: 1.0.0
+dependencies:
+  - documentation-integrity module
+tags:
+  - analysis
+  - brownfield
+  - migration
+updated_at: 2025-12-14
+```
+
+---
+
+tools:
+  - filesystem        # Read project files
+  - brownfield-analyzer  # Core module for this task
+---
+
+# Analyze Brownfield Project
+
+## Purpose
+
+Analyze an existing project to understand its structure, tech stack, coding standards, and CI/CD workflows before AIOS integration. This task provides recommendations for safe integration and identifies potential conflicts.
+
+## Task Instructions
+
+### 1. Run Project Analysis
+
+Execute the brownfield analyzer on the target project:
+
+```javascript
+const { analyzeProject, formatMigrationReport } = require('./.aios-core/infrastructure/scripts/documentation-integrity/brownfield-analyzer');
+
+const targetDir = process.cwd(); // or specified directory
+const analysis = analyzeProject(targetDir);
+```
+
+### 2. Review Analysis Results
+
+The analysis returns comprehensive information about the project:
+
+**BrownfieldAnalysis Structure:**
+
+```typescript
+interface BrownfieldAnalysis {
+  // Basic flags
+  hasExistingStructure: boolean;   // Has src/, lib/, tests/, etc.
+  hasExistingWorkflows: boolean;   // Has CI/CD configurations
+  hasExistingStandards: boolean;   // Has linting/formatting configs
+
+  // Merge strategy
+  mergeStrategy: 'parallel' | 'manual';  // Recommended approach
+
+  // Detected stack
+  techStack: string[];      // ['Node.js', 'TypeScript', 'Python', 'Go', 'Rust']
+  frameworks: string[];     // ['React', 'Vue', 'Angular', 'Next.js', 'Express', etc.]
+  version: string | null;   // Project version from package.json
+
+  // Config paths
+  configs: {
+    eslint: string | null;
+    prettier: string | null;
+    tsconfig: string | null;
+    flake8: string | null;
+    packageJson: string | null;
+    requirements: string | null;
+    goMod: string | null;
+    githubWorkflows: string | null;
+    gitlabCi: string | null;
+  };
+
+  // Detected settings
+  linting: string;      // 'ESLint', 'Flake8', 'none'
+  formatting: string;   // 'Prettier', 'Black', 'none'
+  testing: string;      // 'Jest', 'Vitest', 'pytest', 'none'
+
+  // Integration guidance
+  recommendations: string[];
+  conflicts: string[];
+  manualReviewItems: string[];
+
+  // Summary
+  summary: string;
+}
+```
+
+### 3. Display Migration Report
+
+Show the formatted analysis report:
+
+```javascript
+const report = formatMigrationReport(analysis);
+console.log(report);
+```
+
+**Sample Report Output:**
+
+```text
+╔══════════════════════════════════════════════════════════════════════╗
+║                    BROWNFIELD ANALYSIS REPORT                         ║
+╠══════════════════════════════════════════════════════════════════════╣
+║                                                                      ║
+║  Tech Stack: Node.js, TypeScript                                     ║
+║  Frameworks: React, Next.js                                          ║
+║                                                                      ║
+║  Linting: ESLint                                                     ║
+║  Formatting: Prettier                                                ║
+║  Testing: Jest                                                       ║
+║                                                                      ║
+║  Existing Workflows: Yes                                             ║
+║  Merge Strategy: manual                                              ║
+╠══════════════════════════════════════════════════════════════════════╣
+║  RECOMMENDATIONS                                                     ║
+╠══════════════════════════════════════════════════════════════════════╣
+║                                                                      ║
+║  • Preserve existing ESLint configuration - AIOS will adapt          ║
+║  • Keep existing Prettier settings - AIOS coding-standards.md will d ║
+║  • Review existing CI/CD before adding AIOS workflows                ║
+║  • AIOS will use existing tsconfig.json settings                     ║
+║  • Next.js detected - use pages/ or app/ structure                   ║
+╠══════════════════════════════════════════════════════════════════════╣
+║  📋 MANUAL REVIEW REQUIRED                                           ║
+╠══════════════════════════════════════════════════════════════════════╣
+║                                                                      ║
+║  • Review 3 existing GitHub workflow(s) for potential conflicts      ║
+╚══════════════════════════════════════════════════════════════════════╝
+```
+
+### 4. Interpret Merge Strategy
+
+Based on the analysis, follow the recommended merge strategy:
+
+| Strategy | Meaning | Actions |
+|----------|---------|---------|
+| `parallel` | Safe to proceed with standard AIOS setup | Use `*setup-project-docs` directly |
+| `manual` | Existing CI/CD requires careful review | Review workflows, then proceed |
+
+### 5. Address Manual Review Items
+
+For each item in `analysis.manualReviewItems`:
+
+1. **Review GitHub Workflows:**
+   ```bash
+   # List existing workflows
+   ls -la .github/workflows/
+
+   # Check for potential conflicts with AIOS workflows
+   # Look for: quality-gate.yml, release.yml, staging.yml
+   ```
+
+2. **Review GitLab CI:**
+   ```bash
+   # Check .gitlab-ci.yml for existing stages
+   cat .gitlab-ci.yml | grep -E "^[a-z]+:"
+   ```
+
+3. **Review CircleCI:**
+   ```bash
+   # Check CircleCI config
+   cat .circleci/config.yml
+   ```
+
+### 6. Handle Conflicts
+
+For each item in `analysis.conflicts`:
+
+1. **docs/architecture/ exists:**
+   - Decide: Keep existing or merge with AIOS docs
+   - Option A: Rename existing to `docs/legacy-architecture/`
+   - Option B: Configure AIOS to use alternate path
+
+2. **Other conflicts:**
+   - Document decision in story or task
+   - Consider creating backup before integration
+
+### 7. Proceed with Integration
+
+After analysis and review, proceed based on findings:
+
+**If mergeStrategy is 'parallel':**
+```bash
+# Direct integration
+*setup-project-docs
+```
+
+**If mergeStrategy is 'manual':**
+```bash
+# First review workflows, then
+*setup-project-docs --merge
+```
+
+## Success Criteria
+
+- [ ] Tech stack correctly identified
+- [ ] Frameworks detected from dependencies
+- [ ] Existing code standards found
+- [ ] CI/CD workflows catalogued
+- [ ] Merge strategy determined
+- [ ] Recommendations generated
+- [ ] Conflicts identified
+- [ ] Manual review items listed
+
+## Output Options
+
+**Console Report (default):**
+```bash
+*analyze-brownfield
+```
+
+**JSON Output:**
+```bash
+*analyze-brownfield --format json > analysis.json
+```
+
+**Summary Only:**
+```bash
+*analyze-brownfield --format summary
+# Output: Tech Stack: Node.js, TypeScript | Frameworks: React | Standards: ESLint/Prettier | CI/CD: Existing workflows detected | Recommended Strategy: manual
+```
+
+## Integration with Other Tasks
+
+This task is typically followed by:
+
+1. **`*setup-project-docs`** - Generate project documentation
+2. **`*document-project`** - Create comprehensive brownfield architecture doc
+3. **`*create-brownfield-story`** - Create enhancement stories for existing projects
+
+## Notes
+
+- Analysis is read-only; no files are modified
+- Run this task BEFORE any AIOS integration
+- For large projects, analysis may take 1-2 minutes
+- Recommendations are suggestions, not requirements
+- Use manual review items to plan integration work