aios-core
Version:
Synkra AIOS: AI-Orchestrated System for Full Stack Development - Core Framework
457 lines (345 loc) • 13.8 kB
Markdown
## 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