# .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`