clawdie-ai/AGENTS.md

Agent Development Guidelines

Date Formatting Convention

All user-facing dates must use European format: dd.mm.yyyy HH:MM:SS

Rationale

• User-facing displays should match European conventions (day first)
• Internal storage uses ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) for machine consumption
• ISO 8601 is sortable, universally parsable, and timezone-aware

Implementation

Shell Scripts (bash)

# CORRECT - European format for logs
date '+%d.%m.%Y %H:%M:%S'

# WRONG - American format
date '+%Y-%m-%d %H:%M:%S'

TypeScript (user-facing display)

// CORRECT - European locale for display
const formatDate = (d: Date) => d.toLocaleString('de-DE', {
  day: '2-digit',
  month: '2-digit',
  year: 'numeric',
  hour: '2-digit',
  minute: '2-digit',
  second: '2-digit'
});

// WRONG - American locale
d.toLocaleString('en-US', { ... })

TypeScript (internal storage/database)

// CORRECT - ISO 8601 for storage, IPC, database timestamps
new Date().toISOString(); // "2024-03-06T14:30:00.000Z"

// Keep these as-is - they are for machine consumption

Files Affected

File	Change
setup.sh:13	date '+%Y-%m-%d %H:%M:%S' → date '+%d.%m.%Y %H:%M:%S'
jail/agent-runner/src/index.ts:258	toLocaleString('en-US', ...) → toLocaleString('de-DE', ...)

Files NOT Affected

The following use toISOString() and should remain unchanged:

• src/db.ts - Database timestamps
• src/ipc.ts - IPC message timestamps
• src/task-scheduler.ts - Task scheduling timestamps
• src/container-runner.ts - Container logs and file naming
• skills-engine/*.ts - State tracking
• setup/register.ts, setup/groups.ts - Registration timestamps
• jail/agent-runner/src/ipc-mcp-stdio.ts - IPC timestamps
• All test files using toISOString()
• All skill modification files in .agent/skills/*/modify/

Before Editing Date-Related Code

1. Determine if date is user-facing (logs, transcripts, UI) or internal (storage, IPC)
2. User-facing → European format (de-DE locale)
3. Internal → ISO 8601 (toISOString())
4. Never mix the two