# lilflow

## Stack

- **Language/Runtime:** Unknown

## Build & Test Commands

```bash
# No recognized stack — add build/test commands here
```

## Project Structure

```
lilflow/
├── src/           # Source code
├── tests/         # Test files
├── docs/          # Documentation
└── .claude/       # Codeharness state
```

## Conventions

- All changes must pass tests before commit
- Maintain test coverage targets
- Follow existing code style and patterns
## Harness Files

- `AGENTS.md` is the primary repo-local instruction file for coding agents
- `commands/` contains harness command playbooks the agent can read and execute directly
- `skills/` contains focused harness skills and operating procedures
- Install BMAD with `npx bmad-method install --yes --modules bmm --tools claude-code` for Claude Code

<!-- CODEHARNESS-PATCH-START:dev-workflow-enforcement -->

## Harness Enforcement (codeharness)

During implementation, the agent MUST:

### Observability
- Query VictoriaLogs after running the application to check for errors
- Verify OTLP instrumentation is active in new code paths
- Use `curl localhost:9428/select/logsql/query?query=level:error` to check for runtime errors

### Documentation
- Create or update per-subsystem AGENTS.md for any new modules (max 100 lines)
- Update exec-plan at `docs/exec-plans/active/{story-id}.md` with progress
- Ensure inline code documentation for new public APIs

### Testing
- Write tests AFTER implementation, BEFORE verification
- Achieve 100% project-wide test coverage
- All tests must pass before proceeding to verification

### Verification
- Run `/harness-verify` to produce proof document
- Do NOT mark story complete without passing verification

<!-- CODEHARNESS-PATCH-END:dev-workflow-enforcement -->

<!-- CODEHARNESS-PATCH-START:code-review-harness -->

## Harness Review Checklist (codeharness)

In addition to standard code review, verify:

### Documentation
- [ ] AGENTS.md files are fresh for all changed modules
- [ ] Exec-plan updated with story progress
- [ ] Inline documentation present for new public APIs

### Testing
- [ ] Tests exist for all new code
- [ ] Project-wide test coverage is 100%
- [ ] No skipped or disabled tests
- [ ] Test coverage report is present

### Verification
- [ ] Proof document exists at `verification/{story-id}-proof.md`
- [ ] Proof document covers all acceptance criteria
- [ ] Evidence is reproducible

<!-- CODEHARNESS-PATCH-END:code-review-harness -->

<!-- CODEHARNESS-PATCH-START:sprint-planning-harness -->

## Harness Pre-Sprint Checklist (codeharness)

Before starting the sprint, verify:

### Planning Docs
- [ ] PRD is current and reflects latest decisions
- [ ] Architecture doc is current (ARCHITECTURE.md)
- [ ] Epics and stories are fully defined with Given/When/Then ACs

### Test Infrastructure
- [ ] Coverage tool configured for the stack (c8/istanbul, coverage.py)
- [ ] Baseline coverage recorded in `.claude/codeharness.local.md`
- [ ] Test runner configured and working

### Harness Infrastructure
- [ ] Harness initialized (`/harness-init` completed)
- [ ] Docker stack healthy (VictoriaMetrics responding)
- [ ] OTLP instrumentation installed
- [ ] Hooks registered and active

<!-- CODEHARNESS-PATCH-END:sprint-planning-harness -->

<!-- CODEHARNESS-PATCH-START:retro-harness -->

## Harness Analysis (codeharness)

The retrospective MUST analyze the following in addition to standard retro topics:

### Verification Effectiveness
- Pass rates per story (how many stories verified on first attempt?)
- Common failure patterns (what types of verification fail most?)
- Iteration counts per story (how many implement→verify→fix loops?)
- Average iterations vs target (<3)

### Documentation Health
- Stale doc count (AGENTS.md files not updated since code changed)
- Quality grades per module (A/B/C/D/F)
- Doc-gardener findings summary
- Documentation debt trends (improving or degrading?)

### Test Quality
- Coverage trends per story (baseline → final, deltas)
- Tests that caught real bugs vs tests that never failed
- Flaky test detection (tests that pass/fail inconsistently)
- Test suite execution time trends

### Follow-up Items
Convert each finding into an actionable item:
- Code/test issues → new story for next sprint
- Process improvements → BMAD workflow patch
- Verification gaps → enforcement config update

<!-- CODEHARNESS-PATCH-END:retro-harness -->