3cfaa1e1d3
Phase 1 delivers the complete durability and storage layer:
- WAL with crash recovery: Append-only journal with BLAKE3 checksums,
fsync guarantees, and proper seek-to-EOF on reopen
- Storage engine: sled-backed KVStore with scan_prefix for range queries
- Content-addressed storage: H:{hash}, V:{hash}, E:{hash} key patterns
- Ingestor: Background worker tailing WAL, writing to KV with 8-byte
aligned record headers for rkyv zero-copy deserialization
- Comprehensive tests: 31 tests covering crash recovery, round-trips,
and multi-cycle durability
New crates: stemedb-wal, stemedb-storage, stemedb-ingest
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
160 lines
5.3 KiB
Markdown
160 lines
5.3 KiB
Markdown
---
|
|
description: Implement a task with vision alignment, design thinking, quality gates, and simulation coverage
|
|
argument-hint: <task-description>
|
|
---
|
|
|
|
# Implement Task: $ARGUMENTS
|
|
|
|
You are implementing a task for Episteme (StemeDB). Follow this rigorous process.
|
|
|
|
---
|
|
|
|
## Phase 1: Vision Alignment
|
|
|
|
**Read and internalize the vision:**
|
|
- Read `vision.md` to understand the core philosophy
|
|
- Read `architecture.md` to understand the system design
|
|
- Read `roadmap.md` to understand where we're headed
|
|
|
|
**Answer before proceeding:**
|
|
1. How does this task align with "Git for Truth" and the probabilistic knowledge lattice?
|
|
2. Does this task respect append-only semantics?
|
|
3. Which architectural tier does this touch (Spine, Lattice, or Cortex)?
|
|
|
|
If the task conflicts with the vision, STOP and explain the conflict to the user.
|
|
|
|
---
|
|
|
|
## Phase 2: Code Understanding
|
|
|
|
**Explore the existing codebase:**
|
|
1. Use the Explore agent to find all files relevant to this task
|
|
2. Read the existing code thoroughly - understand patterns, not just syntax
|
|
3. Check `ai-lookup/` for documented facts about related components
|
|
4. Check `.claude/guides/` for relevant procedures
|
|
|
|
**Document your understanding:**
|
|
- What existing code does this task interact with?
|
|
- What patterns are already established that we must follow?
|
|
- Are there any technical debts or constraints to be aware of?
|
|
|
|
---
|
|
|
|
## Phase 3: Design Thinking
|
|
|
|
**Apply best practices and principles from "Philosophy of Software Design" by John Ousterhout:**
|
|
|
|
1. **Complexity is the enemy.** Design for simplicity, not cleverness.
|
|
2. **Deep modules over shallow modules.** Hide complexity behind simple interfaces.
|
|
3. **Define errors out of existence.** Design APIs so invalid states are unrepresentable.
|
|
4. **Strategic vs tactical programming.** We're building for the long term, not quick wins.
|
|
5. **Comments should describe what isn't obvious.** Code tells how, comments tell why.
|
|
|
|
**Design the implementation:**
|
|
1. What is the minimal interface that solves this problem?
|
|
2. What complexity can we hide inside the module?
|
|
3. How will this decision look in 2 years? 5 years?
|
|
4. What are the failure modes and how do we handle them defensively?
|
|
|
|
**Write down your design before coding:**
|
|
- The public interface (traits, structs, functions)
|
|
- The internal implementation strategy
|
|
- Error handling approach
|
|
- Test strategy
|
|
|
|
---
|
|
|
|
## Phase 4: Agent Selection & Implementation
|
|
|
|
**Select the appropriate specialized agent based on the task domain:**
|
|
|
|
| Domain | Agent | Use When |
|
|
|--------|-------|----------|
|
|
| Storage, WAL, LSM | `storage-engine-architect` | Write path, durability, crash recovery |
|
|
| Graph structures, concurrency | `rust-graph-engine-architect` | Lock-free structures, cache optimization |
|
|
| Lens system, queries | `stemedb-lens-architect` | Query resolution, ranking algorithms |
|
|
| Defensive patterns | `defensive-systems-architect` | Rate limiting, hostile input, circuit breakers |
|
|
| General Rust features | `primary-developer` | Feature implementation, refactoring |
|
|
|
|
**Delegate to the agent:**
|
|
Use the Task tool to spawn the selected agent with:
|
|
- The task description
|
|
- Your design from Phase 3
|
|
- Specific files to modify
|
|
- Constraints and patterns to follow
|
|
|
|
---
|
|
|
|
## Phase 5: Quality Gates
|
|
|
|
**Run all quality checks:**
|
|
|
|
```bash
|
|
make quality
|
|
```
|
|
|
|
This runs:
|
|
- `cargo fmt --check` - Formatting
|
|
- `cargo clippy -- -D warnings` - Linting (zero warnings policy)
|
|
- `jscpd` - Code duplication detection
|
|
- `cargo test` - All tests pass
|
|
|
|
**Code review checklist:**
|
|
- [ ] No `unwrap()` or `expect()` in production code
|
|
- [ ] All public APIs have doc comments
|
|
- [ ] Error types are descriptive and actionable
|
|
- [ ] New code follows existing patterns
|
|
- [ ] No hardcoded values that should be configurable
|
|
|
|
If any quality gate fails, fix the issues before proceeding.
|
|
|
|
---
|
|
|
|
## Phase 6: Simulation Coverage (steme-sim)
|
|
|
|
**Every feature must be representable in the simulation.**
|
|
|
|
The simulation (`stemedb-sim` / The Arena) validates StemeDB under adversarial conditions. Check `simulation-vision.md` for context.
|
|
|
|
**Update the simulation to cover this feature:**
|
|
|
|
1. **Which agent persona exercises this feature?**
|
|
- Scientist (truth-seeking)
|
|
- Troll (adversarial)
|
|
- Believer (consensus-following)
|
|
- Skeptic (variance-detecting)
|
|
- Historian (context-preserving)
|
|
|
|
2. **What scenario tests this feature?**
|
|
- Create or extend a scenario in the simulation config
|
|
- Define success criteria (what should happen vs. what shouldn't)
|
|
|
|
3. **What metrics should we track?**
|
|
- Add any new observability to the simulation metrics
|
|
|
|
**If the simulation doesn't exist yet:**
|
|
- Document how this feature WOULD be tested in the simulation
|
|
- Add a TODO in `simulation-vision.md` under Implementation Plan
|
|
|
|
---
|
|
|
|
## Phase 7: Documentation
|
|
|
|
**Update documentation:**
|
|
- [ ] If new types/concepts: add to `ai-lookup/`
|
|
- [ ] If new procedures: add to `.claude/guides/`
|
|
- [ ] Update `CLAUDE.md` routing if this is a major feature
|
|
- [ ] Ensure code comments explain WHY, not just HOW
|
|
|
|
---
|
|
|
|
## Output
|
|
|
|
When complete, provide:
|
|
1. **Summary**: What was implemented and why
|
|
2. **Files Changed**: List of modified files
|
|
3. **Design Decisions**: Key decisions and their rationale (referencing Philosophy of Software Design)
|
|
4. **Quality Status**: Output of `make quality`
|
|
5. **Simulation Coverage**: How this feature is validated in the simulation
|
|
6. **Follow-up**: Any remaining work or known limitations
|