# CLAUDE.md — Winkers Conventions Update

## What This Is

Adding a convention rules subsystem to Winkers. Project conventions (coding standards, patterns, architectural decisions) are stored as structured rules and served to AI agents through MCP tools with full observability.

The core idea: if conventions are delivered *only* through tool calls, the tool call trace is the attribution log. We can measure which rules agents actually use, which they ignore, and where they're confidently wrong.

## Relationship to Existing Winkers

```
architecture.json  → structure (computed from code)
semantic.json      → intent (human-written, zone purposes, business logic)
rules/       → rules (NEW — coding standards, auto-detected + manual)
```

Conventions are a peer to architecture and semantic, not a replacement. Some content currently in semantic.json (conventions, coding standards) should migrate here. The graph stays in architecture.json, intent stays in semantic.json, rules move to rules/.

## Implementation Order (strict)

1. Data model: `.winkers/rules/` schema, rules.json, overview.md generator
2. MCP tools: 4 tools added to existing server (topics/get/apply/decide)
3. Auto-detection: 3-4 detectors using tree-sitter (extend `winkers init`)
4. CLI: `rules list`, `add`, `compile`
5. Trace analyzer: `rules analyze` → metrics + insights.md
6. Hook integration: extend PreToolUse + add PostSession
7. Suggest: `rules suggest` (LLM-based, needs trace data)
8. Migration: `rules migrate-from-semantic`

## Conventions for This Work

- Follow existing Winkers code patterns, file organization, CLI structure
- Convention tools are namespaced: `convention_topics`, `convention_get`, etc.
- Use existing tree-sitter infrastructure for auto-detection — don't reinvent
- Trace format is JSONL, one event per line, append-only
- All new CLI commands support `--help` and `--json` output flag
- Rules have stable integer IDs, never reused after deletion

## What NOT to Do

- Don't modify architecture.json or semantic.json schemas
- Don't make convention_decide a hard blocker — soft nudge only
- Don't write rule stats from MCP server at runtime — only CLI analyze updates stats
- Don't auto-create rules without user confirmation
- Don't put trace files in git (add to .gitignore)
- Don't break existing winkers init / winkers improve workflows — extend them
