# CharacterGarden – AI-Oriented Design Spec (Copilot-Ready)

## 0. Purpose

This document defines **hard contracts and system boundaries** for CharacterGarden.

Goal: enable an AI coding assistant (e.g. Copilot) to implement the system step-by-step without ambiguity.

Core principle:

> The application owns truth. The LLM only translates and narrates.

---

## 1. System Overview

### Pipeline

```
Prose Input
→ Intent Extraction
→ Canonical Actions
→ Truth Engine Validation
→ State Changes + Events
→ Memory Storage
→ Narration Output
```

---

## 2. Core Contracts (STRICT)

### 2.1 Entity

```
Entity {
  id: string
  type: string
  name: string
  attributes: object
}
```

### 2.2 Action (Canonical)

```
Action {
  actor: string (entity id)
  verb: string (enum)
  target?: string (entity id)
  params?: object
}
```

Allowed verbs (MVP):

```
move, open, close, take, drop, use, inspect, speak
```

### 2.3 Validation Result

```
ValidationResult {
  accepted: Action[]
  rejected: { action: Action, reason: string }[]
  state_changes: StateChange[]
}
```

### 2.4 State Change

```
StateChange {
  entity_id: string
  field: string
  old_value: any
  new_value: any
}
```

### 2.5 Event

```
Event {
  id: string
  turn: number
  action: Action
  result: "success" | "fail"
  timestamp: number
}
```

---

## 3. Truth Rules

1. Only the **Truth Engine** can modify world state
2. LLM output is NEVER directly trusted
3. Every state change must be traceable to an Event
4. Invalid actions must return explicit failure reasons

---

## 4. Memory Model

Memory is NOT a single blob.

### Types

#### 4.1 Turn

Raw input/output

#### 4.2 Event

Accepted or rejected actions

#### 4.3 Fact

Current world state (derived, not duplicated)

#### 4.4 Belief

```
Belief {
  entity_id: string
  claim: string
  confidence: number
}
```

#### 4.5 Summary

Compressed narrative context

---

## 5. Services

### 5.1 App (Core Service)

Responsibilities:

* orchestrate turns
* call LLM (optional)
* run truth engine
* manage memory

Tech: Node.js (Express or Fastify)

---

### 5.2 Truth Engine (Module inside App)

Responsibilities:

* validate actions
* enforce rules
* apply state changes
* emit events

NO LLM USAGE

---

### 5.3 LLM Adapter (Optional)

Responsibilities:

* extract actions from prose
* resolve references
* generate narration
* summarize memory

Backend: Ollama

---

### 5.4 Frontend

Responsibilities:

* send input
* display output
* optionally inspect state/events

Minimal React or Vue app

---

## 6. Turn Flow (IMPLEMENT EXACTLY)

```
1. Receive user input (string)
2. Store raw turn
3. Extract actions (LLM or fallback parser)
4. Validate actions (truth engine)
5. Apply accepted changes
6. Store events
7. Generate narration
8. Return response
```

---

## 7. Storage

### SQLite (MVP)

Tables:

* entities
* events
* turns
* beliefs
* summaries

File location:

```
/data/sqlite/app.db
```

---

## 8. Docker Design

### Services

```
services:
  app
  frontend
  ollama (optional)
```

### Principles

* No host dependencies beyond Docker
* Persist only `/data`
* Use `.env` for config
* No hidden setup scripts

---

## 9. Folder Structure

```
charactergarden/
  docker-compose.yml
  .env
  app/
  frontend/
  data/
    sqlite/
```

---

## 10. MVP Scope

STRICT LIMITS:

* 1–2 rooms
* ≤3 characters
* ≤10 actions
* no complex AI autonomy
* no multi-agent loops yet

---

## 11. Non-Goals (DO NOT BUILD YET)

* microservices
* distributed systems
* plugin frameworks
* advanced agent loops
* cloud dependencies

---

## 12. Development Workflow Rule

A root-level file named `thoughts.md` must exist and be maintained throughout development.

Purpose of `thoughts.md`:

* record current implementation status
* record the next planned steps
* record blockers, assumptions, and unresolved questions
* summarize architectural decisions already made
* preserve continuity across editor sessions or context loss

Rules for `thoughts.md`:

* update it after each meaningful implementation step
* keep entries concise and factual
* do not use it for chain-of-thought dumping or vague brainstorming
* use it as a project progress log and working memory
* when resuming work, review `thoughts.md` first before making changes
* when changing architecture, record what changed and why
* when a task is incomplete, note exactly what remains

Recommended structure:

```md
# thoughts.md

## Current Status
- what is implemented
- what is partially implemented
- what is broken or unverified

## Current Architecture Decisions
- key decisions and constraints

## Next Steps
- ordered checklist of immediate tasks

## Open Questions
- unresolved design or implementation questions

## Session Notes
- short dated notes describing recent progress
```

Copilot instruction:

> Before starting work, read `thoughts.md`. After completing any meaningful change, update `thoughts.md` to reflect current status, next steps, and any unresolved issues.

## 13. Development Order

1. Define entities + actions
2. Implement truth engine
3. Add SQLite persistence
4. Build API endpoints
5. Add minimal UI
6. Add LLM integration

---

## 14. Key Rule

> If the system works without an LLM, the architecture is correct.

---

## 15. Expected Behavior

* deterministic state
* explainable failures
* replayable sessions
* inspectable memory

---

## 16. Future Extensions (NOT NOW)

* branching timelines
* advanced belief systems
* multi-agent arbitration
* long-term memory compression

---

## END SPEC