aios-core 2.1.1 → 2.1.2

package/.aios-core/development/tasks/setup-project-docs.md

@@ -0,0 +1,444 @@
+---
+
+## Execution Modes
+
+**Choose your execution mode:**
+
+### 1. YOLO Mode - Fast, Autonomous (0-1 prompts)
+- Autonomous decision making with logging
+- Minimal user interaction
+- **Best for:** Greenfield projects, quick setup
+
+### 2. Interactive Mode - Balanced, Educational (5-10 prompts) **[DEFAULT]**
+- Explicit decision checkpoints
+- Educational explanations
+- **Best for:** Brownfield projects, complex configurations
+
+### 3. Pre-Flight Planning - Comprehensive Upfront Planning
+- Task analysis phase (identify all ambiguities)
+- Zero ambiguity execution
+- **Best for:** Critical projects, enterprise setups
+
+**Parameter:** `mode` (optional, default: `interactive`)
+
+---
+
+## Task Definition (AIOS Task Format V1.0)
+
+```yaml
+task: setupProjectDocs()
+responsável: dev (Developer)
+responsavel_type: Agente
+atomic_layer: Documentation
+
+**Entrada:**
+- campo: targetDir
+  tipo: string
+  origem: User Input or cwd
+  obrigatório: false
+  validação: Valid directory path
+
+- campo: projectName
+  tipo: string
+  origem: User Input or package.json
+  obrigatório: false
+  validação: Non-empty string
+
+- campo: mode
+  tipo: string
+  origem: User Input
+  obrigatório: false
+  validação: greenfield|brownfield|framework-dev
+
+- campo: executionMode
+  tipo: string
+  origem: User Input
+  obrigatório: false
+  validação: yolo|interactive|pre-flight
+
+**Saída:**
+- campo: docs_generated
+  tipo: array
+  destino: .aios-core/docs/
+  persistido: true
+
+- campo: core_config
+  tipo: file
+  destino: .aios-core/core-config.yaml
+  persistido: true
+
+- campo: gitignore
+  tipo: file
+  destino: .gitignore
+  persistido: true
+```
+
+---
+
+## Pre-Conditions
+
+**Purpose:** Validate prerequisites BEFORE task execution (blocking)
+
+**Checklist:**
+
+```yaml
+pre-conditions:
+  - [ ] Target directory exists and is writable
+    tipo: pre-condition
+    blocker: true
+    validação: |
+      Check target directory exists and has write permissions
+    error_message: "Pre-condition failed: Target directory not accessible"
+
+  - [ ] Documentation Integrity module is available
+    tipo: pre-condition
+    blocker: true
+    validação: |
+      Verify .aios-core/infrastructure/scripts/documentation-integrity/index.js exists
+    error_message: "Pre-condition failed: Documentation Integrity module not found"
+```
+
+---
+
+## Post-Conditions
+
+**Purpose:** Validate execution success AFTER task completes
+
+**Checklist:**
+
+```yaml
+post-conditions:
+  - [ ] Project docs created in .aios-core/docs/
+    tipo: post-condition
+    blocker: true
+    validação: |
+      Verify source-tree.md, coding-standards.md, tech-stack.md exist
+    error_message: "Post-condition failed: Documentation files not created"
+
+  - [ ] core-config.yaml created with valid deployment section
+    tipo: post-condition
+    blocker: true
+    validação: |
+      Verify .aios-core/core-config.yaml exists and has deployment configuration
+    error_message: "Post-condition failed: core-config.yaml not properly configured"
+```
+
+---
+
+## Acceptance Criteria
+
+**Purpose:** Definitive pass/fail criteria for task completion
+
+**Checklist:**
+
+```yaml
+acceptance-criteria:
+  - [ ] All documentation files generated from templates
+    tipo: acceptance-criterion
+    blocker: true
+    validação: |
+      Assert docs contain project-specific content, not placeholders
+    error_message: "Acceptance criterion not met: Docs contain unresolved placeholders"
+
+  - [ ] .gitignore properly configured for project
+    tipo: acceptance-criterion
+    blocker: true
+    validação: |
+      Assert .gitignore includes AIOS ignores and tech stack ignores
+    error_message: "Acceptance criterion not met: .gitignore incomplete"
+
+  - [ ] Configuration-Driven Architecture pattern applied
+    tipo: acceptance-criterion
+    blocker: true
+    validação: |
+      Assert core-config.yaml contains project-specific values
+    error_message: "Acceptance criterion not met: core-config.yaml not configuration-driven"
+```
+
+---
+
+## Tools
+
+**External/shared resources used by this task:**
+
+- **Tool:** documentation-integrity
+  - **Purpose:** Mode detection, doc generation, config generation
+  - **Source:** .aios-core/infrastructure/scripts/documentation-integrity/index.js
+
+- **Tool:** deployment-config-loader
+  - **Purpose:** Load and validate deployment configuration
+  - **Source:** .aios-core/infrastructure/scripts/documentation-integrity/deployment-config-loader.js
+
+---
+
+## Scripts
+
+**Agent-specific code for this task:**
+
+- **Script:** mode-detector.js
+  - **Purpose:** Detect installation mode from project markers
+  - **Language:** JavaScript
+  - **Location:** .aios-core/infrastructure/scripts/documentation-integrity/mode-detector.js
+
+- **Script:** doc-generator.js
+  - **Purpose:** Generate project documentation from templates
+  - **Language:** JavaScript
+  - **Location:** .aios-core/infrastructure/scripts/documentation-integrity/doc-generator.js
+
+- **Script:** config-generator.js
+  - **Purpose:** Generate core-config.yaml
+  - **Language:** JavaScript
+  - **Location:** .aios-core/infrastructure/scripts/documentation-integrity/config-generator.js
+
+- **Script:** gitignore-generator.js
+  - **Purpose:** Generate or merge .gitignore
+  - **Language:** JavaScript
+  - **Location:** .aios-core/infrastructure/scripts/documentation-integrity/gitignore-generator.js
+
+---
+
+## Error Handling
+
+**Strategy:** fallback-defaults
+
+**Common Errors:**
+
+1. **Error:** Mode Detection Failed
+   - **Cause:** Unable to determine project type from markers
+   - **Resolution:** Use default mode (greenfield) or prompt user
+   - **Recovery:** Provide mode selection options
+
+2. **Error:** Template Not Found
+   - **Cause:** Template file missing from templates directory
+   - **Resolution:** Check template paths in templates/project-docs/
+   - **Recovery:** Use inline fallback templates
+
+3. **Error:** Config Write Failed
+   - **Cause:** Permission denied or disk full
+   - **Resolution:** Check directory permissions
+   - **Recovery:** Output config to console for manual creation
+
+---
+
+## Performance
+
+**Expected Metrics:**
+
+```yaml
+duration_expected: 1-3 min (estimated)
+cost_estimated: $0.001-0.003
+token_usage: ~500-2,000 tokens
+```
+
+**Optimization Notes:**
+- Uses template-based generation for fast execution
+- Minimal file I/O with batched writes
+- Configuration-Driven Architecture reduces runtime decisions
+
+---
+
+## Metadata
+
+```yaml
+story: 6.9
+version: 1.0.0
+dependencies:
+  - documentation-integrity module
+tags:
+  - documentation
+  - setup
+  - configuration
+updated_at: 2025-12-14
+```
+
+---
+
+tools:
+  - filesystem        # Read/write project files
+  - documentation-integrity  # Core module for this task
+---
+
+# Setup Project Documentation
+
+## Purpose
+
+Generate project-specific documentation and configuration using the Documentation Integrity System. This task creates the foundational docs that enable AI agents to understand project structure, coding standards, and deployment configuration.
+
+## Task Instructions
+
+### 1. Detect Installation Mode
+
+First, determine the installation mode based on project markers:
+
+```javascript
+const { detectInstallationMode, collectMarkers } = require('./.aios-core/infrastructure/scripts/documentation-integrity');
+
+const targetDir = process.cwd(); // or specified directory
+const detected = detectInstallationMode(targetDir);
+const markers = collectMarkers(targetDir);
+
+console.log(`Detected Mode: ${detected.mode}`);
+console.log(`Confidence: ${detected.confidence}`);
+console.log(`Reason: ${detected.reason}`);
+```
+
+**Mode Descriptions:**
+
+| Mode | Description | Actions |
+|------|-------------|---------|
+| `framework-dev` | Contributing to aios-core itself | Skip project setup, use existing config |
+| `greenfield` | New empty project | Full scaffolding, deployment config wizard |
+| `brownfield` | Existing project | Analyze and adapt, merge configurations |
+
+### 2. Elicit Deployment Configuration (Greenfield/Brownfield)
+
+For greenfield and brownfield projects, gather deployment preferences:
+
+**Key Questions:**
+
+1. **Deployment Workflow:**
+   - `staging-first`: All changes go to staging before production
+   - `direct-to-main`: Feature branches merge directly to main
+
+2. **Deployment Platform:**
+   - `vercel`: Vercel deployment
+   - `netlify`: Netlify deployment
+   - `aws`: AWS (S3/CloudFront, ECS, Lambda)
+   - `gcp`: Google Cloud Platform
+   - `azure`: Microsoft Azure
+   - `railway`: Railway.app
+   - `custom`: Custom deployment scripts
+
+3. **Branch Configuration:**
+   - Staging branch name (default: `staging`)
+   - Production branch name (default: `main`)
+
+4. **Quality Gates:**
+   - Enable lint check? (default: yes)
+   - Enable typecheck? (default: yes for TypeScript projects)
+   - Enable tests? (default: yes)
+   - Enable security scan? (default: no)
+
+### 3. Generate Documentation
+
+Using the gathered context, generate project documentation:
+
+```javascript
+const { buildDocContext, generateDocs } = require('./.aios-core/infrastructure/scripts/documentation-integrity');
+
+const context = buildDocContext(projectName, mode, markers, {
+  // Custom overrides if needed
+});
+
+const result = generateDocs(targetDir, context, {
+  dryRun: false,  // Set true to preview
+});
+
+console.log(`Generated ${result.filesCreated.length} documentation files`);
+```
+
+**Files Generated:**
+
+| File | Purpose |
+|------|---------|
+| `.aios-core/docs/source-tree.md` | Project structure documentation |
+| `.aios-core/docs/coding-standards.md` | Coding conventions and patterns |
+| `.aios-core/docs/tech-stack.md` | Technology stack reference |
+
+### 4. Generate Core Configuration
+
+Create the core-config.yaml with deployment settings:
+
+```javascript
+const { buildConfigContext, generateConfig, DeploymentWorkflow, DeploymentPlatform } = require('./.aios-core/infrastructure/scripts/documentation-integrity');
+
+const configContext = buildConfigContext(projectName, mode, {
+  workflow: DeploymentWorkflow.STAGING_FIRST,
+  platform: DeploymentPlatform.VERCEL,
+  branches: {
+    staging: 'staging',
+    production: 'main',
+  },
+  quality_gates: {
+    lint: true,
+    typecheck: true,
+    tests: true,
+    security_scan: false,
+  },
+});
+
+const configResult = generateConfig(targetDir, mode, configContext);
+```
+
+### 5. Generate/Merge .gitignore
+
+Handle .gitignore based on project state:
+
+```javascript
+const { generateGitignoreFile, hasAiosIntegration } = require('./.aios-core/infrastructure/scripts/documentation-integrity');
+
+const gitignoreResult = generateGitignoreFile(targetDir, markers, {
+  projectName,
+  merge: mode === 'brownfield',  // Merge with existing for brownfield
+});
+
+console.log(`Gitignore ${gitignoreResult.mode}: ${gitignoreResult.path}`);
+```
+
+### 6. Verify Configuration-Driven Architecture
+
+Confirm the deployment config can be loaded by other tasks:
+
+```javascript
+const { loadDeploymentConfig, validateDeploymentConfig } = require('./.aios-core/infrastructure/scripts/documentation-integrity');
+
+const deployConfig = loadDeploymentConfig(targetDir);
+const validation = validateDeploymentConfig(deployConfig);
+
+if (validation.valid) {
+  console.log('Configuration-Driven Architecture ready');
+  console.log(`Workflow: ${deployConfig.workflow}`);
+  console.log(`Platform: ${deployConfig.platform}`);
+} else {
+  console.error('Configuration validation failed:', validation.errors);
+}
+```
+
+## Success Criteria
+
+- [ ] Installation mode correctly detected
+- [ ] Project documentation generated in `.aios-core/docs/`
+- [ ] `core-config.yaml` created with deployment section
+- [ ] `.gitignore` properly configured (created or merged)
+- [ ] Configuration passes validation
+- [ ] No unresolved template placeholders in generated files
+
+## Output
+
+After successful execution:
+
+```
+Project Documentation Setup Complete
+=====================================
+Mode: greenfield
+Project: my-awesome-app
+
+Generated Files:
+  ✓ .aios-core/docs/source-tree.md
+  ✓ .aios-core/docs/coding-standards.md
+  ✓ .aios-core/docs/tech-stack.md
+  ✓ .aios-core/core-config.yaml
+  ✓ .gitignore (created)
+
+Deployment Configuration:
+  Workflow: staging-first
+  Platform: vercel
+  Quality Gates: lint, typecheck, tests
+```
+
+## Notes
+
+- This task implements the Configuration-Driven Architecture pattern
+- Tasks read project-specific values from `core-config.yaml`
+- For brownfield projects, existing configurations are preserved
+- Use `*analyze-brownfield` task first for complex existing projects

package/.aios-core/infrastructure/scripts/documentation-integrity/brownfield-analyzer.js

@@ -152,7 +152,7 @@ function analyzeTechStack(targetDir, analysis) {
       try {
         const requirements = fs.readFileSync(
           path.join(targetDir, 'requirements.txt'),
-          'utf8'
+          'utf8',
         );
 
         if (requirements.includes('django')) analysis.frameworks.push('Django');
@@ -267,7 +267,7 @@ function analyzeWorkflows(targetDir, analysis) {
       const workflows = fs.readdirSync(githubWorkflowsDir);
       if (workflows.length > 0) {
         analysis.manualReviewItems.push(
-          `Review ${workflows.length} existing GitHub workflow(s) for potential conflicts`
+          `Review ${workflows.length} existing GitHub workflow(s) for potential conflicts`,
         );
       }
     } catch {
@@ -327,7 +327,7 @@ function analyzeDirectoryStructure(targetDir, analysis) {
     const archDir = path.join(targetDir, 'docs', 'architecture');
     if (fs.existsSync(archDir)) {
       analysis.conflicts.push(
-        'docs/architecture/ already exists - AIOS docs may need different location'
+        'docs/architecture/ already exists - AIOS docs may need different location',
       );
     }
   }
@@ -342,7 +342,7 @@ function generateRecommendations(analysis) {
   // Linting recommendations
   if (analysis.linting !== 'none') {
     analysis.recommendations.push(
-      `Preserve existing ${analysis.linting} configuration - AIOS will adapt`
+      `Preserve existing ${analysis.linting} configuration - AIOS will adapt`,
     );
   } else {
     analysis.recommendations.push('Consider adding ESLint/Flake8 for code quality');
@@ -351,7 +351,7 @@ function generateRecommendations(analysis) {
   // Formatting recommendations
   if (analysis.formatting !== 'none') {
     analysis.recommendations.push(
-      `Keep existing ${analysis.formatting} settings - AIOS coding-standards.md will document them`
+      `Keep existing ${analysis.formatting} settings - AIOS coding-standards.md will document them`,
     );
   }
 
@@ -438,7 +438,7 @@ function formatMigrationReport(analysis) {
   // Workflows
   lines.push(`║${''.padEnd(width)}║`);
   lines.push(
-    `║  Existing Workflows: ${(analysis.hasExistingWorkflows ? 'Yes' : 'No').padEnd(width - 24)}║`
+    `║  Existing Workflows: ${(analysis.hasExistingWorkflows ? 'Yes' : 'No').padEnd(width - 24)}║`,
   );
   lines.push(`║  Merge Strategy: ${analysis.mergeStrategy.padEnd(width - 20)}║`);
 

package/.aios-core/infrastructure/scripts/documentation-integrity/gitignore-generator.js

@@ -113,7 +113,7 @@ function generateGitignore(markers, options = {}) {
   // Add project header
   const projectName = options.projectName || 'Project';
   sections.push(`# ${projectName} .gitignore`);
-  sections.push(`# Generated by AIOS Documentation Integrity System`);
+  sections.push('# Generated by AIOS Documentation Integrity System');
   sections.push(`# Date: ${new Date().toISOString().split('T')[0]}`);
   sections.push(`# Tech Stack: ${techStacks.join(', ') || 'Generic'}`);
   sections.push('');
@@ -139,7 +139,7 @@ function generateGitignore(markers, options = {}) {
  * @param {Object} [options] - Merge options
  * @returns {string} Merged gitignore content
  */
-function mergeGitignore(existingContent, options = {}) {
+function mergeGitignore(existingContent, _options = {}) {
   // Check if AIOS section already exists
   if (existingContent.includes('AIOS Integration Section')) {
     console.log('AIOS section already exists in .gitignore, skipping merge');
@@ -172,7 +172,7 @@ function mergeGitignore(existingContent, options = {}) {
   // Replace date placeholder
   mergeSection = mergeSection.replace(
     '{{GENERATED_DATE}}',
-    new Date().toISOString().split('T')[0]
+    new Date().toISOString().split('T')[0],
   );
 
   // Append to existing content
@@ -262,7 +262,6 @@ function parseGitignore(content) {
     comments: [],
   };
 
-  let currentSection = 'patterns';
   let aiosStart = -1;
   let aiosEnd = -1;
 

package/.aios-core/infrastructure/scripts/documentation-integrity/mode-detector.js

@@ -285,19 +285,19 @@ function validateModeSelection(selectedMode, detected) {
   if (selectedMode !== detected.mode) {
     if (selectedMode === InstallationMode.GREENFIELD && !detected.markers.isEmpty) {
       result.warnings.push(
-        'Selected greenfield but directory is not empty. Existing files may be overwritten.'
+        'Selected greenfield but directory is not empty. Existing files may be overwritten.',
       );
     }
 
     if (selectedMode === InstallationMode.FRAMEWORK_DEV && !detected.markers.isAiosCoreRepo) {
       result.warnings.push(
-        'Selected framework-dev but this does not appear to be the aios-core repository.'
+        'Selected framework-dev but this does not appear to be the aios-core repository.',
       );
     }
 
     if (selectedMode === InstallationMode.BROWNFIELD && detected.markers.isEmpty) {
       result.warnings.push(
-        'Selected brownfield but directory is empty. Consider using greenfield instead.'
+        'Selected brownfield but directory is empty. Consider using greenfield instead.',
       );
       result.suggestions.push(InstallationMode.GREENFIELD);
     }

package/.aios-core/infrastructure/scripts/llm-routing/install-llm-routing.js

@@ -70,7 +70,7 @@ function installLLMRouting(options = {}) {
     projectRoot = process.cwd(),
     templatesDir = path.join(__dirname, 'templates'),
     onProgress = console.log,
-    onError = console.error
+    onError = console.error,
   } = options;
 
   const result = {
@@ -78,7 +78,7 @@ function installLLMRouting(options = {}) {
     installDir: null,
     filesInstalled: [],
     envCreated: false,
-    errors: []
+    errors: [],
   };
 
   // Check templates exist
@@ -143,7 +143,7 @@ function installLLMRouting(options = {}) {
     try {
       fs.copyFileSync(envExample, envFile);
       result.envCreated = true;
-      onProgress(`✅ Created .env from .env.example`);
+      onProgress('✅ Created .env from .env.example');
     } catch (error) {
       result.success = false;
       result.errors.push(`Failed to create .env: ${error.message}`);
@@ -180,7 +180,7 @@ function updateClaudeConfig() {
     config.aiosLLMRouting = {
       version: LLM_ROUTING_VERSION,
       installedAt: new Date().toISOString(),
-      commands: ['claude-max', 'claude-free']
+      commands: ['claude-max', 'claude-free'],
     };
 
     fs.writeFileSync(claudeConfigPath, JSON.stringify(config, null, 2));
@@ -250,7 +250,7 @@ module.exports = {
   isLLMRoutingInstalled,
   getInstallDir,
   getInstallationSummary,
-  LLM_ROUTING_VERSION
+  LLM_ROUTING_VERSION,
 };
 
 // Run if executed directly
@@ -259,7 +259,7 @@ if (require.main === module) {
 
   const result = installLLMRouting({
     projectRoot: process.cwd(),
-    templatesDir: path.join(__dirname, 'templates')
+    templatesDir: path.join(__dirname, 'templates'),
   });
 
   const summary = getInstallationSummary(result);

package/.aios-core/infrastructure/scripts/source-tree-guardian/manifest-generator.js

@@ -205,7 +205,7 @@ class ManifestGenerator {
       this.projectRoot,
       'docs',
       'architecture',
-      'source-tree-manifest.json'
+      'source-tree-manifest.json',
     );
     this.maxDepth = options.maxDepth || 10;
   }
@@ -252,7 +252,7 @@ class ManifestGenerator {
     // Count by category
     manifest.categories = await countFilesByCategory(this.projectRoot);
     manifest.summary.categories = Object.fromEntries(
-      Object.entries(manifest.categories).map(([k, v]) => [k, v.count])
+      Object.entries(manifest.categories).map(([k, v]) => [k, v.count]),
     );
 
     manifest.duration = Date.now() - startTime;

package/.aios-core/infrastructure/scripts/source-tree-guardian/validator.js

@@ -181,7 +181,7 @@ function validateFilePlacement(filePath, rules, projectRoot) {
         // Check exclusions for this violation
         if (violation.exclude_patterns) {
           const excluded = violation.exclude_patterns.some((p) =>
-            matchesPattern(relativePath, p)
+            matchesPattern(relativePath, p),
           );
           if (excluded) {
             continue;

package/.claude/rules/mcp-usage.md

@@ -0,0 +1,54 @@
+---
+paths: **/*
+---
+
+# MCP Server Usage Rules
+
+## CRITICAL: Tool Selection Priority
+
+ALWAYS prefer native Claude Code tools over MCP servers:
+
+| Task | USE THIS | NOT THIS |
+|------|----------|----------|
+| Read files | `Read` tool | docker-gateway |
+| Write files | `Write` / `Edit` tools | docker-gateway |
+| Run commands | `Bash` tool | docker-gateway |
+| Search files | `Glob` tool | docker-gateway |
+| Search content | `Grep` tool | docker-gateway |
+| List directories | `Bash(ls)` or `Glob` | docker-gateway |
+
+## docker-gateway (Desktop Commander) Restrictions
+
+### ONLY use docker-gateway when:
+1. User explicitly says "use docker" or "use container"
+2. User explicitly mentions "Desktop Commander"
+3. Task specifically requires Docker container operations
+4. User asks to run something inside a Docker container
+
+### NEVER use docker-gateway for:
+- Reading local files (use `Read` tool)
+- Writing local files (use `Write` or `Edit` tools)
+- Running shell commands (use `Bash` tool)
+- Searching files (use `Glob` or `Grep` tools)
+- Listing directories (use `Bash(ls)` or `Glob`)
+- Running Node.js or Python scripts (use `Bash` tool)
+
+## playwright MCP Restrictions
+
+### ONLY use playwright when:
+1. User explicitly asks for browser automation
+2. User wants to take screenshots of web pages
+3. User needs to interact with a website
+4. Task requires web scraping or testing
+
+### NEVER use playwright for:
+- General file operations
+- Running commands
+- Anything not related to web browsers
+
+## Rationale
+
+- Native tools execute on the LOCAL system (Windows)
+- docker-gateway executes inside Docker containers (Linux)
+- Using docker-gateway for local operations causes path mismatches and failures
+- Native tools are faster and more reliable for local operations

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aios-core",
-  "version": "2.1.1",
+  "version": "2.1.2",
   "description": "AIOS: AI-Orchestrated System for Full Stack Development - Core Framework",
   "main": "index.js",
   "module": "index.esm.js",