@@ -4,7 +4,7 @@ Help coding agents work safely and consistently in this repo.
44
55 ## Important References
66
7-**Design Document**: `client-refaction-design.md` - Primary source of truth for architecture and design decisions
7+**Design Document**: `docs/2026-02-03-client-refactor-design.md` - Primary source of truth for architecture and design decisions
88
99 **Game Server WebSocket API**: https://www.spacemolt.com/api.md
1010
@@ -19,15 +19,18 @@ ollama-spacemolt-workspace/
1919 │ ├── src/ # Source code
2020 │ ├── tests/ # Unit tests
2121 │ └── package.json
22-├── client-refaction-design.md # Sacred design document
22+├── scripts/
23+│ └── strip-comments.ts # Comment removal script
24+├── docs/
25+│ └── 2026-02-03-client-refactor-design.md # Sacred design document
2326 ├── package.json # Workspace root
2427 ├── tsconfig.json # Base TypeScript config
25-└── biome.json # Workspace-level formatting/linting
28+└── .prettierrc.json # Prettier configuration
2629 ```
2730
2831 ## Design Principles
2932
30-From `client-refaction-design.md`:
33+From `docs/2026-02-03-client-refactor-design.md`:
3134
3235 1. **Reduce abstraction** - Minimize layers between client and server
3336 2. **Direct connection** - Connect to WebSocket without intermediate libraries
@@ -47,9 +50,10 @@ bun install
4750 bun run check
4851
4952 # Individual checks
50-bun run check:format
51-bun run check:lint
52-bun run check:test
53+bun run strip-comments # Strip comments from TypeScript files
54+bun run check:format # Format with Prettier
55+bun run check:lint # TypeScript compilation check
56+bun run check:test # Run tests
5357 ```
5458
5559 ### Client Package
@@ -67,23 +71,29 @@ bun run start
6771 ## Code Style Guidelines
6872
6973 ### Formatting
70-- Use Biome for all formatting and linting
74+
75+- Use Prettier for all formatting
76+- TypeScript compilation (`tsc --noEmit`) for linting
7177 - Tabs for indentation (2-space width)
72-- Let Biome handle style automatically
78+- 100 character line width
79+- Semicolons, double quotes, trailing commas
7380
7481 ### Naming Conventions
82+
7583 - Types/interfaces: `PascalCase`
7684 - Functions and variables: `camelCase`
7785 - Constants: `SCREAMING_SNAKE_CASE`
7886 - File names: `kebab-case.ts`
7987
8088 ### TypeScript
89+
8190 - `strict` mode enabled
8291 - Avoid `any`, use `unknown` then narrow
8392 - Explicit return types for public functions
8493 - Prefer `null` over `undefined` for absent values
8594
8695 ### Testing
96+
8797 - Use Bun's built-in test runner (`bun test`)
8898 - Target: 80% coverage for client code
8999 - Unit tests for core logic
@@ -92,11 +102,37 @@ bun run start
92102 ## Database
93103
94104 SQLite via `bun:sqlite`:
105+
95106 - Pattern: `memory-{instance-id}.sqlite`
96107 - Two tables: `account_details`, `messages`
97108 - Maximum 5000 messages, sorted by tick
98109 - Unique instance ID per client (4 characters)
99110
111+## Tick Processing
112+
113+The client uses a server-driven tick system with critical safety mechanisms:
114+
115+**Processing Lock:**
116+
117+- Only one tick can process at a time (enforced by `isProcessingTick` flag)
118+- If a new tick arrives while previous tick is still processing, it is skipped
119+- Prevents parallel LLM calls that would violate game server rate limits
120+- Skipped ticks are logged but not saved to database
121+
122+**Flow:**
123+
124+1. Server sends tick message every ~10 seconds
125+2. Client checks if currently processing (`isProcessingTick`)
126+3. If processing: log skip and return
127+4. If not: set lock, process tick (LLM call + command send), release lock
128+
129+**Why this matters:**
130+
131+- LLM calls can take 8-12 seconds (variable)
132+- Tick interval is 10 seconds (fixed)
133+- Without lock: overlapping ticks cause rate limiting errors
134+- With lock: sequential processing matches game server expectations
135+
100136 ## Error Handling
101137
102138 - Neutral, factual language only
@@ -106,16 +142,68 @@ SQLite via `bun:sqlite`:
106142
107143 ## Development Workflow
108144
109-1. Read `client-refaction-design.md` for context
145+1. Read `docs/2026-02-03-client-refactor-design.md` for context
110146 2. Make changes aligned with design principles
111-3. Run `bun run check` before committing
147+3. Run `bun run check` before committing (strips comments, formats, lints, tests)
112148 4. Keep abstractions minimal
113149 5. Test with real game server when possible
114150
151+## Code Quality
152+
153+### No Comments Policy
154+
155+**Comments are automatically stripped from all TypeScript files during the check process.** This prevents outdated comments from misleading future agents as code evolves.
156+
157+**Why this matters for AI agents:**
158+
159+- Agents make edits in chunks and often miss contextual comments
160+- Outdated comments create false assumptions about code behavior
161+- Comments can contradict actual implementation after refactoring
162+- Self-documenting code is more reliable than potentially stale documentation
163+
164+**When comments are stripped:**
165+
166+- During `bun run check` (after formatting, before linting)
167+- Applies to all `.ts` files in `packages/*/src/**` and `packages/*/tests/**`
168+- ALL comments are removed: single-line (`//`), multi-line (`/* */`), JSDoc
169+
170+**Write self-documenting code instead:**
171+
172+- Clear variable and function names that explain intent
173+- Small, focused functions (easier to understand at a glance)
174+- Type annotations for function signatures
175+- Well-structured code organization
176+- Descriptive constant names instead of magic numbers
177+
178+**Example - Instead of:**
179+
180+```typescript
181+const d = Math.sqrt((x2 - x1) ** 2 + (y2 - y1) ** 2);
182+```
183+
184+**Write:**
185+
186+```typescript
187+function calculateDistance(point1: Point, point2: Point): number {
188+ const deltaX = point2.x - point1.x;
189+ const deltaY = point2.y - point1.y;
190+ return Math.sqrt(deltaX ** 2 + deltaY ** 2);
191+}
192+```
193+
194+**Where to document:**
195+
196+- Design decisions → `docs/2026-02-03-client-refactor-design.md`
197+- Architecture patterns → `AGENTS.md` (this file)
198+- User instructions → `README.md`
199+- API reference → Markdown files or separate docs
200+
115201 ## What NOT to Do
116202
117203 - Do not add intermediate translation layers
118204 - Do not add behavioral bias outside `prompt` field
119-- Do not modify sacred `client-refaction-design.md`
205+- Do not modify sacred `docs/2026-02-03-client-refactor-design.md`
120206 - Do not commit `*.sqlite` or `*.log` files
121207 - Do not create backward compatibility with old implementation
208+- **Do not access files outside of the repo root** - All file operations must stay within `/home/xonecas/src/ollama-spacemolt-player`
209+- **Run all commands in the repo root** - Use the `workdir` parameter if needed, but default to repo root