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