aiwg
Version:
Cognitive architecture for AI-augmented software development with structured memory, ensemble validation, and closed-loop correction. FAIR-aligned artifacts, 84% cost reduction via human-in-the-loop, standards adopted by 100+ organizations.
334 lines (291 loc) • 11.8 kB
Markdown
# .aiwg/ Directory Structure
## Purpose
The `.aiwg/` directory stores all SDLC artifacts, working documents, and process metadata generated during the software development lifecycle. This keeps project-critical artifacts (source code, tests, user docs) separate from process artifacts (planning docs, requirements, architecture decisions).
## Benefits
1. **Clean separation**: User-facing code stays in root, process artifacts in `.aiwg/`
2. **Easy to ignore**: Single `.gitignore` entry ignores all SDLC artifacts if desired
3. **Optional sharing**: Teams can choose to commit `.aiwg/` for transparency or ignore for cleaner repos
4. **Discoverable**: Centralized location for all planning/process documents
5. **Tooling-friendly**: Consistent paths for automated tools and agents
## Directory Structure
```
.aiwg/
├── README.md # This file - explains structure
├── .gitignore # Optional - ignore working artifacts
│
├── intake/ # Project intake forms (Concept → Inception)
│ ├── project-intake.md
│ ├── solution-profile.md
│ └── option-matrix.md
│
├── requirements/ # Requirements artifacts (Inception → Elaboration)
│ ├── vision.md
│ ├── user-stories/
│ │ ├── epic-001-user-auth.md
│ │ └── epic-002-dashboard.md
│ ├── use-cases/
│ │ ├── uc-001-login.md
│ │ └── uc-002-view-orders.md
│ ├── nfr/ # Non-functional requirements
│ │ ├── performance.md
│ │ ├── security.md
│ │ ├── reliability.md
│ │ └── scalability.md
│ └── traceability-matrix.md # Req → Design → Code → Test
│
├── architecture/ # Architecture artifacts (Elaboration)
│ ├── sad.md # Software Architecture Document
│ ├── adrs/ # Architecture Decision Records
│ │ ├── 001-use-react.md
│ │ ├── 002-postgres-database.md
│ │ └── 003-aws-deployment.md
│ ├── diagrams/
│ │ ├── system-context.md
│ │ ├── component-diagram.md
│ │ └── deployment-diagram.md
│ └── api-contracts/
│ ├── rest-api-spec.yaml
│ └── event-schemas.json
│
├── planning/ # Iteration and phase planning
│ ├── phases/
│ │ ├── inception-plan.md
│ │ ├── elaboration-plan.md
│ │ ├── construction-plan.md
│ │ └── transition-plan.md
│ ├── iterations/
│ │ ├── iteration-01-plan.md
│ │ ├── iteration-02-plan.md
│ │ └── iteration-03-plan.md
│ ├── work-packages/ # Detailed work items
│ │ ├── wp-001-setup-infra.md
│ │ └── wp-002-implement-auth.md
│ └── estimates/
│ ├── timeline-estimates.md
│ └── capacity-planning.md
│
├── risks/ # Risk management
│ ├── risk-list.md # Living risk register
│ ├── spikes/ # Technical risk retirement
│ │ ├── spike-001-auth-poc.md
│ │ └── spike-002-load-test.md
│ └── mitigations/
│ └── risk-001-mitigation.md
│
├── testing/ # Test strategy and results
│ ├── test-strategy.md
│ ├── test-plans/
│ │ ├── unit-test-plan.md
│ │ ├── integration-test-plan.md
│ │ └── e2e-test-plan.md
│ ├── test-cases/
│ │ ├── tc-001-login-success.md
│ │ └── tc-002-login-failure.md
│ └── test-results/
│ ├── iteration-01-results.md
│ └── regression-report.md
│
├── security/ # Security artifacts
│ ├── threat-model.md # STRIDE analysis
│ ├── security-requirements.md
│ ├── penetration-test-reports/
│ ├── vulnerability-scans/
│ └── security-gates/
│ ├── gate-inception.md
│ ├── gate-elaboration.md
│ └── gate-construction.md
│
├── quality/ # Quality governance
│ ├── code-reviews/
│ │ ├── review-001-auth-module.md
│ │ └── review-002-api-layer.md
│ ├── retrospectives/
│ │ ├── retro-iteration-01.md
│ │ └── retro-iteration-02.md
│ ├── metrics/
│ │ ├── velocity-tracking.md
│ │ ├── defect-tracking.md
│ │ └── coverage-reports.md
│ └── compliance/
│ ├── gdpr-compliance.md
│ └── sox-compliance.md
│
├── deployment/ # Deployment and operations
│ ├── deployment-plan.md
│ ├── runbooks/
│ │ ├── deployment-runbook.md
│ │ ├── rollback-runbook.md
│ │ └── incident-response.md
│ ├── hypercare/
│ │ ├── hypercare-plan.md
│ │ └── hypercare-log.md
│ └── operations/
│ ├── slo-sli-definitions.md
│ ├── monitoring-setup.md
│ └── alerting-rules.md
│
├── handoffs/ # Phase/track handoff checklists
│ ├── inception-to-elaboration.md
│ ├── elaboration-to-construction.md
│ ├── construction-to-transition.md
│ ├── discovery-to-delivery.md
│ └── delivery-to-ops.md
│
├── gates/ # Quality gate reports
│ ├── lom-report.md # Lifecycle Objective Milestone
│ ├── abm-report.md # Architecture Baseline Milestone
│ ├── ocm-report.md # Operational Capability Milestone
│ └── prm-report.md # Product Release Milestone
│
├── decisions/ # Decision records and rationale
│ ├── ccb-meetings/ # Change Control Board
│ │ ├── ccb-2025-10-01.md
│ │ └── ccb-2025-10-15.md
│ ├── change-requests/
│ │ ├── cr-001-add-feature-x.md
│ │ └── cr-002-change-timeline.md
│ └── impact-assessments/
│ └── ia-001-scope-change.md
│
├── team/ # Team coordination
│ ├── team-profile.yaml # Team composition and skills
│ ├── onboarding/
│ │ ├── onboarding-checklist.md
│ │ └── new-member-guide.md
│ ├── knowledge-transfer/
│ │ ├── kt-001-architecture.md
│ │ └── kt-002-deployment.md
│ └── cross-team-sync/
│ ├── dependency-map.md
│ └── api-contracts-status.md
│
├── working/ # Temporary working files (safe to delete)
│ ├── notes/
│ ├── drafts/
│ └── scratch/
│
└── reports/ # Generated reports
├── project-health.md
├── timeline-forecast.md
├── artifact-index.md # Index of all artifacts
└── traceability-report.md
```
## Recommended .gitignore Strategy
### Option 1: Ignore Working Files Only (Recommended for Teams)
```gitignore
# .aiwg working files (temporary/scratch)
.aiwg/working/
.aiwg/*/drafts/
.aiwg/*/scratch/
# .aiwg generated reports (can be regenerated)
.aiwg/reports/
# Keep all planning/requirements/architecture artifacts committed
```
### Option 2: Ignore Everything (Solo Developers)
```gitignore
# Ignore all SDLC artifacts (use tooling locally only)
.aiwg/
# Exception: Keep intake forms for project context
!.aiwg/intake/
```
### Option 3: Commit Everything (Enterprise/Audit)
```gitignore
# Commit all SDLC artifacts for audit trail
# (no .aiwg/ entries in .gitignore)
```
## Path Conventions for Commands
All SDLC commands use `.aiwg/` as the default base directory:
| Command | Default Output Path | Configurable Via |
|---------|---------------------|------------------|
| intake-wizard | `.aiwg/intake/` | `[intake-directory]` argument |
| intake-from-codebase | `.aiwg/intake/` | `--output` flag |
| flow-concept-to-inception | `.aiwg/requirements/`, `.aiwg/planning/` | `[project-directory]` |
| flow-risk-management-cycle | `.aiwg/risks/` | `[project-directory]` |
| flow-architecture-evolution | `.aiwg/architecture/` | `[project-directory]` |
| flow-test-strategy-execution | `.aiwg/testing/` | `[project-directory]` |
| flow-security-review-cycle | `.aiwg/security/` | `[project-directory]` |
| flow-gate-check | `.aiwg/gates/` | `[project-directory]` |
| flow-handoff-checklist | `.aiwg/handoffs/` | `[project-directory]` |
| flow-change-control | `.aiwg/decisions/` | `[project-directory]` |
| flow-retrospective-cycle | `.aiwg/quality/retrospectives/` | `[project-directory]` |
| flow-deploy-to-production | `.aiwg/deployment/` | `[project-directory]` |
| flow-hypercare-monitoring | `.aiwg/deployment/hypercare/` | `[project-directory]` |
| flow-incident-response | `.aiwg/deployment/operations/` | `[project-directory]` |
| build-artifact-index | `.aiwg/reports/artifact-index.md` | `--output` |
| check-traceability | `.aiwg/reports/traceability-report.md` | `--output` |
| project-health-check | `.aiwg/reports/project-health.md` | `--output` |
## Accessing Artifacts
### Via Commands
```bash
# List all artifacts
aiwg -list-artifacts
# Find specific artifact type
aiwg -find requirements
aiwg -find architecture
aiwg -find risks
# Generate artifact index
aiwg build-artifact-index
```
### Via File System
```bash
# All intake forms
ls .aiwg/intake/
# All ADRs
ls .aiwg/architecture/adrs/
# All test plans
ls .aiwg/testing/test-plans/
# All retrospectives
ls .aiwg/quality/retrospectives/
```
### Via Grep/Search
```bash
# Find all mentions of "authentication"
grep -r "authentication" .aiwg/
# Find all high-priority risks
grep -r "Priority: High" .aiwg/risks/
```
## Generating End-User Documentation
Use the `flow-generate-user-docs` command to extract user-facing documentation from SDLC artifacts:
```bash
# Generate user docs from .aiwg/ artifacts
/flow-generate-user-docs
# Outputs to: docs/ (standard user documentation location)
# Sources from: .aiwg/requirements/, .aiwg/architecture/api-contracts/
```
This creates:
- User guides from use cases
- API documentation from contracts
- Deployment guides from deployment plans
- Troubleshooting guides from runbooks
## Migration from intake/ to .aiwg/intake/
If you have existing `intake/` artifacts:
```bash
# Move existing intake to .aiwg/
mkdir -p .aiwg/intake
mv intake/* .aiwg/intake/
rmdir intake
# Update continues seamlessly
/intake-wizard --complete
```
## Benefits for Different User Types
### Solo Developers
- Add `.aiwg/` to `.gitignore` → keep repos clean
- Use SDLC tooling locally for planning
- Generate docs on-demand when needed
### Small Teams
- Commit `.aiwg/intake/` and `.aiwg/planning/` → shared context
- Ignore `.aiwg/working/` → no clutter
- Use for coordination and handoffs
### Enterprise Teams
- Commit entire `.aiwg/` → full audit trail
- Use for compliance and governance
- Track all decisions and change requests
### Advanced Users
- Browse `.aiwg/` directly for troubleshooting
- Edit artifacts manually if needed
- Generate custom reports from raw data
## See Also
- Project intake: `.aiwg/intake/README.md`
- Architecture decisions: `.aiwg/architecture/README.md`
- Risk management: `.aiwg/risks/README.md`
- Testing strategy: `.aiwg/testing/README.md`