# 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)

```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)

```typescript
// 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)

```typescript
// 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
