The .dgidgi Folder

Every DgiDgi-managed project contains a .dgidgi folder that stores project configuration, guidelines, and context for AI agents.

Folder Structure

.dgidgi/
  dgidgi.config.json    # Project configuration (read-only via UI)
  GUIDELINES.md         # Coding guidelines for agents
  CONTEXT.md            # Project context and architecture
  .dgidgiignore         # Files to ignore
  prompts/              # Custom prompts for specific tasks
    code-review.md
    feature-implementation.md
    bug-fix.md

File Descriptions

dgidgi.config.json

Main configuration file for the project. Agents read this but should not modify it directly - changes are made through the DgiDgi UI.

{
  "version": "1.0.0",
  "project": {
    "name": "My Project",
    "description": "Project description",
    "type": "web",
    "framework": "react"
  },
  "agent": {
    "defaultModel": "auto",
    "temperature": 0.7,
    "maxTokens": 4096,
    "allowedTools": ["*"],
    "blockedTools": [],
    "autoApprove": {
      "fileRead": true,
      "fileWrite": false,
      "terminal": false,
      "git": false,
      "deploy": false
    }
  },
  "coding": {
    "style": "project",
    "maxFileLines": 500,
    "maxFunctionLines": 150,
    "maxComplexity": 15
  },
  "runtime": {
    "type": "docker",
    "installCommand": "pnpm install",
    "devCommand": "pnpm dev",
    "buildCommand": "pnpm build"
  },
  "preview": {
    "enabled": true,
    "port": 3000
  },
  "security": {
    "sandboxLevel": "standard",
    "allowNetworkAccess": true
  }
}

GUIDELINES.md

Project-specific coding guidelines that AI agents follow. Customize this to match your team's conventions.

Contents:

• Project overview
• Tech stack
• Naming conventions
• File organization
• Code limits
• Do's and don'ts

CONTEXT.md

Project context and architecture information. Helps agents understand the codebase structure.

Contents:

• Architecture overview
• Key files and their purposes
• Dependencies
• Environment variables
• API endpoints
• Database schema
• Common patterns

.dgidgiignore

Files and directories that agents should not read or modify. Similar to .gitignore.

# Dependencies
node_modules/

# Build outputs
dist/
build/

# Secrets
.env
.env.*

# Large files
*.pdf
*.mp4

prompts/

Custom prompts for specific tasks. Agents use these as templates for common operations.

File	Purpose
code-review.md	Guidelines for reviewing code
feature-implementation.md	Steps for implementing features
bug-fix.md	Process for fixing bugs

File Permissions

File	Agents Can Read	Agents Can Modify
dgidgi.config.json	Yes	No (read-only)
GUIDELINES.md	Yes	Yes
CONTEXT.md	Yes	Yes
.dgidgiignore	Yes	Yes
prompts/*	Yes	Yes

Initialization

When you create a new project in DgiDgi, the .dgidgi folder is automatically created with template files.

Via CLI

dgidgi init

Via API

import { dgidgiFolderService } from "@dgidgi/server";

await dgidgiFolderService.initialize("/path/to/project", {
  projectName: "My Project",
  projectDescription: "A web application",
  projectType: "web",
  framework: "react",
});

Reading Configuration

In Server Code

import { dgidgiFolderService } from "@dgidgi/server";

// Load complete folder info
const info = await dgidgiFolderService.load("/path/to/project");
console.log(info.config);     // DgiDgiConfig
console.log(info.guidelines); // string
console.log(info.context);    // string
console.log(info.prompts);    // Record<string, string>

// Get agent context (combines guidelines + context)
const agentContext = await dgidgiFolderService.getAgentContext("/path/to/project");

// Get specific prompt
const reviewPrompt = await dgidgiFolderService.getPrompt("/path/to/project", "code-review");

// Check if file should be ignored
const ignored = await dgidgiFolderService.shouldIgnore("/path/to/project", "node_modules/package.json");

In Agent Code

Agents automatically receive the .dgidgi folder contents as context:

// In agent execution context
const { guidelines, context, config } = executionContext.dgidgiFolder;

// Use coding standards
if (fileLines > config.coding.maxFileLines) {
  // Split file
}

Best Practices

Customize GUIDELINES.md

Add your team's specific conventions:

## Our Conventions

### API Endpoints
- Always use RESTful naming
- Version all endpoints (/v1/, /v2/)
- Return consistent error formats

### React Components
- Use functional components only
- Extract logic to custom hooks
- Keep components under 200 lines

Keep CONTEXT.md Updated

Update when architecture changes:

## Recent Changes

- 2024-01-15: Migrated from Redux to Zustand
- 2024-01-10: Added WebSocket support for real-time features

Create Custom Prompts

Add prompts for your common tasks:

# Database Migration Prompt

When creating database migrations:

1. Check existing schema in prisma/schema.prisma
2. Create migration with descriptive name
3. Test migration locally before committing
4. Update CONTEXT.md with schema changes

Health Check & Auto-Repair

DgiDgi automatically monitors the .dgidgi folder and repairs it if files are missing or corrupted.

How It Works

When a project is loaded, DgiDgi:

1. Checks folder exists - If missing, creates entire structure
2. Validates required files - Checks for config, guidelines, context, prompts
3. Validates config format - Ensures JSON is valid and has required fields
4. Auto-repairs - Restores missing files from templates

Health Check API

import { dgidgiFolderService } from "@dgidgi/server";

// Check health without repairing
const health = await dgidgiFolderService.healthCheck("/path/to/project");
console.log(health);
// {
//   healthy: false,
//   exists: true,
//   issues: [
//     { type: "missing", file: "GUIDELINES.md", message: "...", autoRepairable: true }
//   ],
//   repaired: false
// }

// Repair issues
const repaired = await dgidgiFolderService.repair("/path/to/project");
console.log(repaired.repaired); // true if any issues were fixed

// Ensure valid (auto-repairs if needed)
const info = await dgidgiFolderService.ensureValid("/path/to/project", {
  projectName: "My Project",
  autoRepair: true,
});

Issue Types

Type	Description	Auto-Repairable
missing	File or folder doesn't exist	Yes (restored from template)
corrupted	File has invalid content	Config: No, Others: Yes
invalid	Wrong file type or structure	Depends on file

What Gets Repaired

File	Repair Action
.dgidgi/ folder	Created with full structure
dgidgi.config.json	Created with defaults (not overwritten if corrupted)
GUIDELINES.md	Restored from template
CONTEXT.md	Restored from template
.dgidgiignore	Restored from template
prompts/	Created with default prompts

Manual Repair

If auto-repair can't fix an issue (e.g., corrupted config), you can:

1. Delete and reinitialize:

   rm -rf .dgidgi
   dgidgi init

2. Fix manually: Edit the problematic file based on the error message

3. Restore from git:

   git checkout .dgidgi/

Git and Version Control

The .dgidgi folder should be committed to version control:

# .gitignore
# Do NOT ignore .dgidgi folder
!.dgidgi/

This ensures:

• Team members share the same project config
• AI agents have consistent guidelines
• Project context is preserved

Multi-Environment Configuration

For different environments, use environment-specific config overrides:

{
  "runtime": {
    "devCommand": "pnpm dev",
    "buildCommand": "pnpm build"
  },
  "security": {
    "sandboxLevel": "standard"
  }
}

Production overrides in DgiDgi dashboard:

• Higher sandbox level
• Restricted network access
• Different deploy provider