Working Through a Milestone

Before Starting

1. •Review the last commit: git show HEAD
2. •Run tests to see current state: mise test
3. •Read relevant test files in testcases/ to understand expected behavior
4. •CRITICAL: Assess host interface sufficiency
   • •Review src/tclc.h (TclHostOps) to understand available primitives
   • •Determine if the feature can be implemented using existing ops
   • •If TclHostOps needs to be extended: STOP IMMEDIATELY and inform the user
   • •Do not proceed until you have received explicit approval and direction

Implementation Loop

For each failing test:

1. •Identify what's missing - parse test output to understand the gap
2. •C interpreter changes (in src/):
   • •Create new builtin_*.c file if adding a command
   • •Add declarations to internal.h
   • •Register command in interp.c builtins table
   • •Implement using TclHostOps primitives only
3. •Go host changes (in interp/):
   • •Implement callbacks in callbacks.go
   • •Add state to Interp struct in tclc.go if needed
   • •Follow shimmering rules in interp/CLAUDE.md
4. •Run tests: mise test
5. •Iterate until tests pass

Key Patterns

• •List operations mutate: Use ops->list.from() to copy before iterating
• •String lengths: Count carefully, don't include null terminator
• •Shimmering: Use Get*() methods in Go for type conversion, never access Object fields directly
• •Error messages: Match TCL's exact format (check test expectations)

After All Tests Pass

1. •Run tests multiple times to verify stability
2. •Commit with detailed message explaining:
   • •What was implemented
   • •Key implementation details
   • •Important learnings for future work
3. •Use the format from CLAUDE.md (heredoc, co-author line)

File Checklist for New Commands

• • src/builtin_<cmd>.c - implementation
• • src/internal.h - declaration
• • src/interp.c - registration
• • interp/callbacks.go - host callbacks (if new ops needed)
• • interp/tclc.go - state/structs (if needed)