113 lines
6.9 KiB
Markdown
113 lines
6.9 KiB
Markdown
# Task Board for AI Agents
|
|
|
|
> Pick a task, implement it, test it, commit it. Each task is self-contained.
|
|
|
|
## Legend
|
|
- 🔴 Large — 1+ week
|
|
- 🟡 Medium — 2-5 days
|
|
- 🟢 Small — few hours
|
|
- ⬜ Not started / 🔄 In progress / ✅ Done
|
|
|
|
---
|
|
|
|
## Phase 4: AI-Native Tooling (Complete)
|
|
|
|
| ID | Task | Status | Complexity | Files | Acceptance Criteria |
|
|
|---|---|---|---|---|---|
|
|
| T4.1 | JSON REPL mode | ✅ | 🟡 | `src/repl.nim` | `./cljnim repl --json` works, structured I/O |
|
|
| T4.2 | Batch evaluation | ✅ | 🟢 | `src/repl.nim` | `{"op":"eval-batch","forms":["(defn f[x]x)","(f 42)"]}` works |
|
|
| T4.3 | File operations | ✅ | 🟡 | `lib/cljnim_runtime.nim`, `src/emitter.nim` | `(file/read)`, `(file/write)`, `(file/ls)` work |
|
|
| T4.4 | Git operations | ✅ | 🟡 | `lib/cljnim_runtime.nim`, `src/emitter.nim` | `(git/status)`, `(git/commit)`, `(git/push)` work |
|
|
| T4.5 | nREPL protocol | ✅ | 🟡 | `src/repl.nim` | REPL speaks JSON over TCP with `--tcp PORT`. |
|
|
| T4.6 | Tool-call format | ✅ | 🟢 | `src/repl.nim` | Accept `{"tool":"cljnim/eval","args":{"form":"..."}}`. |
|
|
|
|
---
|
|
|
|
## Phase 5: Persistent Data Structures
|
|
|
|
| ID | Task | Status | Complexity | Files | Acceptance Criteria |
|
|
|---|---|---|---|---|---|
|
|
| T5.1 | HAMT Vector — core structure | ✅ | 🔴 | New: `lib/cljnim_pvec.nim`, `lib/cljnim_runtime.nim` | `PersistentVector` with 32-way trie, structural sharing. `nth` in O(log₃₂ n). 14 tests. |
|
|
| T5.2 | HAMT Vector — integration | ✅ | 🔴 | `lib/cljnim_runtime.nim`, `src/emitter.nim` | `ckVector` uses HAMT. All 51 `vecData` usages migrated. |
|
|
| T5.3 | HAMT Map | ✅ | 🔴 | New: `lib/cljnim_pmap.nim`, `lib/cljnim_runtime.nim` | Persistent Hash Map with HAMT. `assoc`, `dissoc`, `get` in O(log₃₂ n). 16 tests. |
|
|
| T5.4 | Persistent Set | ✅ | 🟡 | `lib/cljnim_runtime.nim` | Set backed by Persistent Hash Map. `conj`, `disj`, `contains?`, `get`, `count`. Reader emits `(set [items])`. |
|
|
| T5.5 | Transients | ✅ | 🟡 | `lib/cljnim_runtime.nim` | `transient`, `persistent!`, `conj!`, `assoc!` for batch mutations. Use with `let`. |
|
|
|
|
**Why HAMT matters**: Current Vector is a Nim `seq` — every `conj` copies the entire array (O(n)). Real Clojure uses Hash Array Mapped Trie for O(log₃₂ n) updates with structural sharing.
|
|
|
|
**Starting point for T5.1**: Read `lib/cljnim_vector.nim` (if exists) or research Clojure's `PersistentVector.java`. Key concepts: 32-way branching, path copying, tail optimization.
|
|
|
|
---
|
|
|
|
## Phase 6: Clojure Core Library
|
|
|
|
| ID | Task | Status | Complexity | Files | Acceptance Criteria |
|
|
|---|---|---|---|---|---|
|
|
| T6.1 | `str` — string concatenation | ✅ | 🟢 | `lib/cljnim_runtime.nim`, `src/emitter.nim` | `(str "a" 1 true)` → `"a1true"`. `cljStrConcat` in runtime. |
|
|
| T6.2 | `pr-str` — readable representation | ✅ | 🟢 | `lib/cljnim_runtime.nim` | `(pr-str [1 2 3])` → `"[1 2 3]"`. `cljPrStrConcat` in runtime. |
|
|
| T6.3 | `slurp` — read file to string | ✅ | 🟢 | `lib/cljnim_runtime.nim`, `src/emitter.nim` | `(slurp "file.txt")` returns content. Maps to `cljFileRead`. |
|
|
| T6.4 | `spit` — write string to file | ✅ | 🟢 | `lib/cljnim_runtime.nim`, `src/emitter.nim` | `(spit "file.txt" "content")` writes file. Maps to `cljFileWrite`. |
|
|
| T6.5 | `read-line` — read from stdin | ✅ | 🟢 | `lib/cljnim_runtime.nim` | `(read-line)` reads one line from stdin. |
|
|
| T6.6 | `range` — lazy number sequence | ✅ | 🟡 | `lib/cljnim_runtime.nim` | `(range 10)`, `(range 1 10)`, `(range 1 10 2)`. Eager with 3-arg. |
|
|
| T6.7 | `repeat`, `cycle`, `iterate` | ✅ | 🟡 | `lib/cljnim_runtime.nim` | `(repeat n x)`, `(cycle n coll)`, `(iterate n f x)`. Eager. |
|
|
| T6.8 | `take`, `drop` — seq slicing | ✅ | 🟢 | `lib/cljnim_runtime.nim` | `(take 5 (range 100))`, `(drop 5 [1 2 3 4 5])`. |
|
|
| T6.9 | `partition`, `interleave` | ✅ | 🟢 | `lib/cljnim_runtime.nim` | `(partition 2 [1 2 3 4])`, `(interleave [1 2] [3 4])`. |
|
|
| T6.10 | `meta`, `with-meta`, `vary-meta` | ✅ | 🟡 | `lib/cljnim_runtime.nim`, `src/emitter.nim` | Metadata support on vars, functions, collections. |
|
|
| T6.11 | `type`, `instance?` | ✅ | 🟢 | `lib/cljnim_runtime.nim` | `(type 42)` → `:integer`. `(instance? :integer 42)` → true. |
|
|
|
|
---
|
|
|
|
## Phase 7: Project Compilation
|
|
|
|
| ID | Task | Status | Complexity | Files | Acceptance Criteria |
|
|
|---|---|---|---|---|---|
|
|
| T7.1 | `ns` declaration parsing | ✅ | 🟡 | `src/emitter.nim` | `(ns my.app (:require [other.lib :as lib]))` parses, extracts aliases, resolves. |
|
|
| T7.2 | Multi-file compilation | ✅ | 🔴 | `src/cljnim.nim`, `src/emitter.nim` | `./cljnim run app.clj` finds required files (hyphen→underscore), inlines defs. |
|
|
| T7.3 | Module caching | ✅ | 🟡 | `src/cljnim.nim` | Compiled `.nim` files cached in `nimcache/`. Rebuild only if source changed. |
|
|
| T7.4 | Dependency resolution | ✅ | 🔴 | New: `src/deps.nim`, `tests/test_deps.nim` | Read `deps.edn` format. Download Git deps to `.deps/`. `cljnim deps` command. 12 tests. |
|
|
|
|
---
|
|
|
|
## Phase 8: Self-Hosted REPL
|
|
|
|
| ID | Task | Status | Complexity | Files | Acceptance Criteria |
|
|
|---|---|---|---|---|---|
|
|
| T8.1 | In-memory compilation | ✅ | 🔴 | `src/eval.nim`, `src/repl.nim` | Tree-walking interpreter evaluates common forms in <1ms, no temp files. Falls back to compilation for complex cases. 66 tests. |
|
|
| T8.2 | Fast REPL startup | ✅ | 🟡 | `src/eval.nim`, `src/repl.nim` | REPL eval in ~0.02ms (vs 1133ms compiled). Sub-millisecond for arithmetic, collections, higher-order fns. |
|
|
| T8.3 | Hot code reloading | ✅ | 🟡 | `src/eval.nim` | `def`/`defn` update environment immediately. Redefined functions used by all callers at call time. |
|
|
|
|
---
|
|
|
|
## Phase 9: Concurrency
|
|
|
|
| ID | Task | Status | Complexity | Files | Acceptance Criteria |
|
|
|---|---|---|---|---|---|
|
|
| T9.1 | Atoms (CAS) | ✅ | 🟡 | `lib/cljnim_runtime.nim` | `(def a (atom 0))`, `(swap! a inc)`, `(reset! a 42)`, `(deref a)`. Already implemented. |
|
|
| T9.2 | Agents | ⬜ | 🟡 | `lib/cljnim_runtime.nim` | `(def ag (agent 0))`, `(send ag inc)`. Async execution. |
|
|
| T9.3 | core.async channels | ⬜ | 🔴 | New: `lib/cljnim_async.nim` | `(chan)`, `(>! ch val)`, `(<! ch)`, `(go ...)`. Simplified version. |
|
|
|
|
---
|
|
|
|
## Quick Wins (do these first!)
|
|
|
|
These tasks are **small, well-defined, and high impact**:
|
|
|
|
1. **T6.1 `str`** ✅ — Done. `cljStrConcat` in runtime, `str` mapping in emitter.
|
|
2. **T6.3 `slurp`** ✅ — Done. ``(slurp "file.txt")`` works.
|
|
3. **T6.4 `spit`** ✅ — Done. ``(spit "file.txt" "content")`` works.
|
|
4. **T6.8 `take`, `drop`** ✅ — Done. `cljTake`, `cljDrop` in runtime, emitter mappings.
|
|
5. **T6.11 `type`, `instance?`** ✅ — Done. `cljType`, `cljInstanceP` in runtime.
|
|
6. **T4.6 Tool-call format** ⬜ — Wrap REPL input parser to accept `{"tool":...}`.
|
|
|
|
---
|
|
|
|
## How to claim a task
|
|
|
|
1. Read this file
|
|
2. Pick an unclaimed task (marked ⬜)
|
|
3. Implement it
|
|
4. Run `make test && make check`
|
|
5. Update this file: change ⬜ to ✅
|
|
6. Commit: `(git/commit "T6.1: Add str function")`
|
|
7. Push: `(git/push)`
|