Unified Project Structure

This directory contains all AI-assisted development projects organized by category, regardless of which tool (Kiro, Codev, or BMAD) is being used.

Purpose

The .ai/projects/ directory provides:

Single Source of Truth: All project artifacts in one location
Category-Based Organization: Projects organized by system/domain
Tool Agnostic: Work with any AI tool without duplication
Easy Migration: Simple scripts to move between tools
Metadata Tracking: Know which tools use which projects
Local State: This directory is gitignored and stays local to each developer

Directory Structure

.ai/projects/
├── README.md                                    # This file
├── SCHEMA.md                                    # Metadata schema documentation
├── infrastructure/                              # Infrastructure category
│   ├── central-secret-store/                   # Example Kiro project
│   │   ├── metadata.json                       # Project metadata
│   │   ├── requirements.md                     # Kiro requirements
│   │   ├── design.md                           # Kiro design
│   │   └── tasks.md                            # Kiro tasks
│   └── n8n/                                    # Another infrastructure project
│       └── ...
├── domain-apis/                                 # Domain APIs category
│   └── simple-xml-response/                    # Example Codev project
│       ├── metadata.json                       # Project metadata
│       ├── spec.md                             # Codev spec
│       ├── plan.md                             # Codev plan
│       └── review.md                           # Codev review
├── eda/                                        # EDA category
│   └── argocd-eda-uncoupling/
│       └── ...
├── market-making/                              # Market Making category
│   └── market-maker-dashboard-spot-checks/
│       └── ...
└── ai-dev/                                     # AI Dev category
    └── ai-dev/
        └── ...

Tool Integration

Kiro Integration

Kiro accesses projects via symlinks in .kiro/specs/:

# Symlink structure
.kiro/specs/project-name -> ../../.ai/projects/{category}/{project-name}/
 
# Kiro can access:
.kiro/specs/project-name/requirements.md
.kiro/specs/project-name/design.md
.kiro/specs/project-name/tasks.md

Codev Integration

Codev accesses projects via pointer files in codev/specs/, codev/plans/, and codev/reviews/:

<!-- codev/specs/0001-project-name.link.md -->
# 0001: Project Name
 
> **Note**: This is a pointer file. The actual project artifacts are located at:
> `.ai/projects/{category}/{project-name}/`
 
## Quick Links
 
- [Spec](../../.ai/projects/{category}/{project-name}/spec.md)
- [Plan](../../.ai/projects/{category}/{project-name}/plan.md)
- [Review](../../.ai/projects/{category}/{project-name}/review.md)

BMAD Integration

BMAD (via OpenCode) accesses projects directly in .ai/projects/{category}/{project-name}/:

No symlinks or pointer files needed. BMAD agents (Winston, Amelia, etc.) work directly with the project structure.

Configuration:

BMAD config file: _bmad/bmm/config.yaml
Output location: Points to .ai/projects/ (configured below)
Agents read/write artifacts directly to project folders

BMAD Agent Workflow:

# Load Winston (Architect) via OpenCode
/architect
 
# Winston works on: .ai/projects/{category}/{project-name}/
# Creates: architecture.md, epics-stories.md, etc.
 
# Load Amelia (Developer) in fresh context
/dev
 
# Amelia works on: .ai/projects/{category}/{project-name}/stories/
# Implements code based on story files

Key difference from Kiro/Codev:

BMAD agents are instructed via OpenCode chat to work in .ai/projects/
No intermediate linking mechanism needed
Direct file manipulation in project folders

Project Formats

A project uses exactly one format (or hybrid):

Kiro Format: requirements.md, design.md, tasks.md
Codev Format: spec.md, plan.md, review.md
BMAD Format: brief.md, prd.md, architecture.md, epics-stories.md, stories/
Hybrid Format: Mix artifacts from multiple tools (e.g., Kiro requirements.md + BMAD stories/)

The format is specified in metadata.json and determines which artifacts are present.

BMAD Artifact Lifecycle

BMAD follows a 4-phase workflow with specific artifacts per phase:

Phase 1: Analysis (Optional)

brief.md - Product brief (guided facilitation)
research/*.md - Market/domain/technical research documents

Phase 2: Planning (Required)

prd.md - Product Requirements Document
ux-design.md - UX design specifications (if UI-focused)

Phase 3: Solutioning (Required)

architecture.md - Technical architecture decisions
epics-stories.md - Epics and user stories breakdown
implementation-readiness.md - Readiness gate report

Phase 4: Implementation (Required)

stories/ - Directory of story files
- story-{epic}-{number}.md - Individual story with tasks/subtasks
- sprint-status.yaml - Sprint tracking and progress
retrospective.md - Epic/sprint retrospectives (optional)

Anytime Artifacts:

diagrams/*.excalidraw - Architecture/dataflow/wireframe diagrams
tech-spec.md - Quick spec for simple tasks (bypasses full workflow)

Metadata Schema

See SCHEMA.md for the complete metadata.json schema.

Helper Scripts

Located in workspace-root/scripts/:

create-project.sh - Create a new project
list-projects.sh - List all projects
migrate-project.sh - Migrate projects between tools
sync-metadata.sh - Update metadata.json files
categorize-projects.sh - Set project categories
reorganize-projects.sh - Reorganize into category structure

Usage Examples

Create a New Kiro Project

./scripts/create-project.sh my-feature kiro infrastructure

Create a New Codev Project

./scripts/create-project.sh my-feature codev domain-apis

Create a New BMAD Project

./scripts/create-project.sh my-feature bmad infrastructure

Creates structure:

.ai/projects/infrastructure/my-feature/
├── metadata.json (format: "bmad", bmadPhase: "1-analysis")
└── README.md

Then work with BMAD agents via OpenCode:

# Architecture phase
/architect
> Create architecture for .ai/projects/infrastructure/my-feature/
 
# Implementation phase
/dev
> Implement story at .ai/projects/infrastructure/my-feature/stories/story-001.md

List All Projects

./scripts/list-projects.sh

List Projects by Category

./scripts/list-projects.sh --category infrastructure

Migrate a Project Between Tools

# Kiro → Codev
./scripts/migrate-project.sh my-feature kiro codev
 
# Kiro → BMAD
./scripts/migrate-project.sh my-feature kiro bmad
 
# Codev → BMAD
./scripts/migrate-project.sh my-feature codev bmad

Hybrid Tool Usage

Scenario: Start with Kiro, Continue with BMAD

A project can evolve across tools by adding artifacts:

.ai/projects/infrastructure/n8n-platform/
├── metadata.json (format: "hybrid")
├── requirements.md          # Created by Kiro
├── design.md                # Created by Kiro
├── architecture.md          # Added by BMAD (Winston)
├── epics-stories.md         # Added by BMAD (John PM)
└── stories/                 # BMAD implementation
    ├── story-001.md         # Amelia (Dev)
    └── story-002.md

Update metadata.json:

{
  "format": "hybrid",
  "artifacts": [
    "requirements.md",
    "design.md", 
    "architecture.md",
    "epics-stories.md",
    "stories/story-001.md",
    "stories/story-002.md"
  ],
  "tools": ["kiro", "bmad"]
}

Why hybrid?

Leverage existing Kiro/Codev artifacts
Add BMAD’s structured implementation tracking
Single project folder with all history
Agents can reference all artifacts

Benefits

No Duplication: Single location for all project artifacts
Clear Organization: Category-based structure reflects system architecture
Tool Flexibility: Switch between Kiro, Codev, and BMAD without moving files
Consistent Structure: All projects follow the same organization
Easy Discovery: All projects organized by category
Local State: Each developer has their own project state
Hybrid Support: Mix and match tools on the same project
Direct Agent Access: BMAD agents work directly in .ai/projects/ (no indirection)

Notes

This directory is gitignored - projects stay local to each developer
Kiro, Codev, and BMAD can all read/write to the same project (hybrid mode)
Metadata tracks which tools are using which projects
Integration patterns:
- Kiro: Symlinks in .kiro/specs/
- Codev: Pointer files in codev/specs/, codev/plans/, codev/reviews/
- BMAD: Direct access via OpenCode agent instructions
Projects are organized by category (system/domain), not by repository
A project may span multiple repositories but belongs to one category
BMAD agents are instructed to work directly in .ai/projects/{category}/{project-name}/

BMAD Configuration

To enable BMAD to work with .ai/projects/, update _bmad/bmm/config.yaml:

# BMM Module Configuration
project_name: workspace-root
user_skill_level: intermediate
 
# Point to .ai central structure
planning_artifacts: "{project-root}/.ai/projects"
implementation_artifacts: "{project-root}/.ai/projects"
project_knowledge: "{project-root}/docs"
 
# Core Configuration Values
user_name: Craig
communication_language: English
document_output_language: English
output_folder: "{project-root}/.ai/projects"

Important: When working with BMAD agents via OpenCode:

Always specify the full project path: .ai/projects/{category}/{project-name}/
BMAD agents will create artifacts directly in the project folder
No need to reference _bmad-output/ - that’s only for non-integrated usage
Agents follow the 4-phase workflow and create artifacts accordingly
See _bmad/AGENT-GUIDE.md for detailed agent instructions

Tool Orchestration Patterns

Pattern 1: Sequential Tool Usage

Phase 1: Kiro (requirements, design)
  ↓
Phase 2: BMAD (architecture, implementation)
  ↓
Phase 3: Code review with any tool

Pattern 2: Parallel Tool Usage

Kiro: requirements.md, tasks.md
BMAD: architecture.md, stories/ (at the same time)
Result: Hybrid project with best of both

Pattern 3: Tool Migration

Start: Codev (spec.md, plan.md, review.md)
Migration: Copy key sections to brief.md, prd.md
Continue: BMAD (architecture.md, stories/)
Result: Evolved from Codev to BMAD with history preserved

Techcle Wiki

Explorer

README