aios-core 2.1.5 → 2.2.0

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

@@ -0,0 +1,440 @@
+---
+
+## 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()
+responsible: dev (Developer)
+responsible_type: Agent
+atomic_layer: Documentation
+
+inputs:
+- field: targetDir
+  type: string
+  source: User Input or cwd
+  required: false
+  validation: Valid directory path
+
+- field: projectName
+  type: string
+  source: User Input or package.json
+  required: false
+  validation: Non-empty string
+
+- field: mode
+  type: string
+  source: User Input
+  required: false
+  validation: greenfield|brownfield|framework-dev
+
+- field: executionMode
+  type: string
+  source: User Input
+  required: false
+  validation: yolo|interactive|pre-flight
+
+outputs:
+- field: docs_generated
+  type: array
+  destination: docs/architecture/
+  persisted: true
+
+- field: core_config
+  type: file
+  destination: .aios-core/core-config.yaml
+  persisted: true
+
+- field: gitignore
+  type: file
+  destination: .gitignore
+  persisted: true
+```
+
+---
+
+## Pre-Conditions
+
+**Purpose:** Validate prerequisites BEFORE task execution (blocking)
+
+**Checklist:**
+
+```yaml
+pre-conditions:
+  - [ ] Target directory exists and is writable
+    type: pre-condition
+    blocker: true
+    validation: |
+      Check target directory exists and has write permissions
+    error_message: "Pre-condition failed: Target directory not accessible"
+
+  - [ ] Documentation Integrity module is available
+    type: pre-condition
+    blocker: true
+    validation: |
+      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 docs/architecture/
+    type: post-condition
+    blocker: true
+    validation: |
+      Verify source-tree.md, coding-standards.md, tech-stack.md exist in docs/architecture/
+    error_message: "Post-condition failed: Documentation files not created"
+
+  - [ ] core-config.yaml created with valid deployment section
+    type: post-condition
+    blocker: true
+    validation: |
+      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
+    type: acceptance-criterion
+    blocker: true
+    validation: |
+      Assert docs contain project-specific content, not placeholders
+    error_message: "Acceptance criterion not met: Docs contain unresolved placeholders"
+
+  - [ ] .gitignore properly configured for project
+    type: acceptance-criterion
+    blocker: true
+    validation: |
+      Assert .gitignore includes AIOS ignores and tech stack ignores
+    error_message: "Acceptance criterion not met: .gitignore incomplete"
+
+  - [ ] Configuration-Driven Architecture pattern applied
+    type: acceptance-criterion
+    blocker: true
+    validation: |
+      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
+   - `AWS`: AWS (S3/CloudFront, ECS, Lambda)
+   - `Railway`: Railway.app
+   - `Docker`: Docker-based deployment
+   - `None`: No deployment platform configured
+
+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 |
+|------|---------|
+| `docs/architecture/source-tree.md` | Project structure documentation |
+| `docs/architecture/coding-standards.md` | Coding conventions and patterns |
+| `docs/architecture/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,
+  stagingBranch: 'staging',
+  productionBranch: 'main',
+  qualityGates: {
+    lint: true,
+    typecheck: true,
+    tests: true,
+    security: 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.isValid) {
+  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 `docs/architecture/`
+- [ ] `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:
+
+```text
+Project Documentation Setup Complete
+=====================================
+Mode: greenfield
+Project: my-awesome-app
+
+Generated Files:
+  ✓ docs/architecture/source-tree.md
+  ✓ docs/architecture/coding-standards.md
+  ✓ docs/architecture/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