anvil-dev-framework 0.1.6 → 0.1.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (87) hide show
  1. package/README.md +33 -13
  2. package/VERSION +1 -1
  3. package/docs/ANV-263-hook-logging-investigation.md +116 -0
  4. package/docs/INSTALLATION.md +18 -0
  5. package/docs/command-reference.md +302 -2
  6. package/docs/session-workflow.md +62 -9
  7. package/docs/system-architecture.md +569 -0
  8. package/global/commands/anvil-settings.md +3 -1
  9. package/global/commands/audit.md +163 -0
  10. package/global/commands/checklist.md +180 -0
  11. package/global/commands/efficiency.md +356 -0
  12. package/global/commands/evidence.md +99 -32
  13. package/global/commands/insights.md +101 -3
  14. package/global/commands/orient.md +29 -0
  15. package/global/commands/patterns.md +115 -0
  16. package/global/commands/ralph.md +47 -1
  17. package/global/commands/token-budget.md +214 -0
  18. package/global/lib/__pycache__/agent_registry.cpython-314.pyc +0 -0
  19. package/global/lib/__pycache__/claim_service.cpython-314.pyc +0 -0
  20. package/global/lib/__pycache__/coderabbit_service.cpython-314.pyc +0 -0
  21. package/global/lib/__pycache__/context_optimizer.cpython-314.pyc +0 -0
  22. package/global/lib/__pycache__/coordination_service.cpython-314.pyc +0 -0
  23. package/global/lib/__pycache__/doc_coverage_service.cpython-314.pyc +0 -0
  24. package/global/lib/__pycache__/gate_logger.cpython-314.pyc +0 -0
  25. package/global/lib/__pycache__/git_utils.cpython-314.pyc +0 -0
  26. package/global/lib/__pycache__/github_service.cpython-314.pyc +0 -0
  27. package/global/lib/__pycache__/handoff_generator.cpython-314.pyc +0 -0
  28. package/global/lib/__pycache__/hygiene_service.cpython-314.pyc +0 -0
  29. package/global/lib/__pycache__/issue_models.cpython-314.pyc +0 -0
  30. package/global/lib/__pycache__/issue_provider.cpython-314.pyc +0 -0
  31. package/global/lib/__pycache__/linear_data_service.cpython-314.pyc +0 -0
  32. package/global/lib/__pycache__/linear_provider.cpython-314.pyc +0 -0
  33. package/global/lib/__pycache__/local_provider.cpython-314.pyc +0 -0
  34. package/global/lib/__pycache__/optimization_applier.cpython-314.pyc +0 -0
  35. package/global/lib/__pycache__/orient_fast.cpython-314.pyc +0 -0
  36. package/global/lib/__pycache__/quality_service.cpython-314.pyc +0 -0
  37. package/global/lib/__pycache__/ralph_prompt_generator.cpython-314.pyc +0 -0
  38. package/global/lib/__pycache__/ralph_state.cpython-314.pyc +0 -0
  39. package/global/lib/__pycache__/state_manager.cpython-314.pyc +0 -0
  40. package/global/lib/__pycache__/token_analyzer.cpython-314.pyc +0 -0
  41. package/global/lib/__pycache__/token_metrics.cpython-314.pyc +0 -0
  42. package/global/lib/__pycache__/transcript_parser.cpython-314.pyc +0 -0
  43. package/global/lib/__pycache__/verification_runner.cpython-314.pyc +0 -0
  44. package/global/lib/__pycache__/verify_iteration.cpython-314.pyc +0 -0
  45. package/global/lib/__pycache__/verify_subagent.cpython-314.pyc +0 -0
  46. package/global/lib/context_optimizer.py +323 -0
  47. package/global/lib/git_utils.py +267 -0
  48. package/global/lib/issue_models.py +28 -0
  49. package/global/lib/linear_provider.py +217 -16
  50. package/global/lib/optimization_applier.py +582 -0
  51. package/global/lib/orient_fast.py +24 -1
  52. package/global/lib/ralph_state.py +264 -24
  53. package/global/lib/token_analyzer.py +1357 -0
  54. package/global/lib/token_metrics.py +873 -0
  55. package/global/tests/__pycache__/test_context_optimizer.cpython-314-pytest-9.0.2.pyc +0 -0
  56. package/global/tests/__pycache__/test_doc_coverage.cpython-314-pytest-9.0.2.pyc +0 -0
  57. package/global/tests/__pycache__/test_git_utils.cpython-314-pytest-9.0.2.pyc +0 -0
  58. package/global/tests/__pycache__/test_issue_models.cpython-314-pytest-9.0.2.pyc +0 -0
  59. package/global/tests/__pycache__/test_linear_filtering.cpython-314-pytest-9.0.2.pyc +0 -0
  60. package/global/tests/__pycache__/test_linear_provider.cpython-314-pytest-9.0.2.pyc +0 -0
  61. package/global/tests/__pycache__/test_local_provider.cpython-314-pytest-9.0.2.pyc +0 -0
  62. package/global/tests/__pycache__/test_optimization_applier.cpython-314-pytest-9.0.2.pyc +0 -0
  63. package/global/tests/__pycache__/test_token_analyzer.cpython-314-pytest-9.0.2.pyc +0 -0
  64. package/global/tests/__pycache__/test_token_analyzer_phase6.cpython-314-pytest-9.0.2.pyc +0 -0
  65. package/global/tests/__pycache__/test_token_metrics.cpython-314-pytest-9.0.2.pyc +0 -0
  66. package/global/tests/test_context_optimizer.py +321 -0
  67. package/global/tests/test_git_utils.py +160 -0
  68. package/global/tests/test_issue_models.py +40 -0
  69. package/global/tests/test_linear_filtering.py +319 -0
  70. package/global/tests/test_linear_provider.py +125 -0
  71. package/global/tests/test_optimization_applier.py +508 -0
  72. package/global/tests/test_token_analyzer.py +735 -0
  73. package/global/tests/test_token_analyzer_phase6.py +537 -0
  74. package/global/tests/test_token_metrics.py +791 -0
  75. package/global/tools/anvil-memory/src/__tests__/commands.test.ts +238 -1
  76. package/global/tools/anvil-memory/src/commands/ralph-iteration.ts +249 -0
  77. package/global/tools/anvil-memory/src/index.ts +2 -8
  78. package/package.json +1 -1
  79. package/scripts/anvil +7 -2
  80. package/global/tools/anvil-memory/src/__tests__/ccs/context-monitor.test.ts +0 -535
  81. package/global/tools/anvil-memory/src/__tests__/ccs/edge-cases.test.ts +0 -645
  82. package/global/tools/anvil-memory/src/__tests__/ccs/fixtures.ts +0 -363
  83. package/global/tools/anvil-memory/src/__tests__/ccs/index.ts +0 -8
  84. package/global/tools/anvil-memory/src/__tests__/ccs/integration.test.ts +0 -417
  85. package/global/tools/anvil-memory/src/__tests__/ccs/prompt-generator.test.ts +0 -571
  86. package/global/tools/anvil-memory/src/__tests__/ccs/ralph-stop.test.ts +0 -440
  87. package/global/tools/anvil-memory/src/__tests__/ccs/test-utils.ts +0 -252
package/docs/system-architecture.md ADDED
@@ -0,0 +1,569 @@
1
+ # Anvil System Architecture
2
+
3
+ > The complete integration of Linear + CodeRabbit + Claude Code + Anvil Memory
4
+
5
+ ---
6
+
7
+ ## The Big Picture
8
+
9
+ Anvil is an **orchestration layer** that connects four powerful systems into a unified AI-assisted development workflow:
10
+
11
+ ```
12
+ ┌─────────────────────────────────────────────────────────────┐
13
+ │ DEVELOPER WORKFLOW │
14
+ │ │
15
+ │ /orient → /ready → /plan → [implement] → /evidence → PR │
16
+ └─────────────────────────────────────────────────────────────┘
17
+ │
18
+ ▼
19
+ ┌──────────────────────────────────────────────────────────────────────────────────────────────────┐
20
+ │ │
21
+ │ ╔════════════════════════╗ │
22
+ │ ║ ANVIL LAYER ║ │
23
+ │ ║ ───────────────────── ║ │
24
+ │ ║ Commands │ Hooks │ Lib ║ │
25
+ │ ╚════════════════════════╝ │
26
+ │ │ │
27
+ │ ┌───────────────────────────────┼───────────────────────────────┐ │
28
+ │ │ │ │ │
29
+ │ ▼ ▼ ▼ │
30
+ │ ┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐ │
31
+ │ │ LINEAR │ │ CLAUDE CODE │ │ CODERABBIT │ │
32
+ │ │ ───────────────── │ │ ───────────────── │ │ ───────────────── │ │
33
+ │ │ Issue Tracking │◄─────►│ AI Agent Engine │◄─────►│ Code Review │ │
34
+ │ │ Sprint Planning │ │ Tool Execution │ │ Security Scans │ │
35
+ │ │ Team Coordination │ │ Transcript Memory │ │ Pre-merge Checks │ │
36
+ │ └─────────────────────┘ └─────────────────────┘ └─────────────────────┘ │
37
+ │ │ │ │ │
38
+ │ │ │ │ │
39
+ │ └───────────────────────────────┼───────────────────────────────┘ │
40
+ │ │ │
41
+ │ ▼ │
42
+ │ ┌─────────────────────┐ │
43
+ │ │ ANVIL MEMORY │ │
44
+ │ │ ───────────────── │ │
45
+ │ │ Observations │ │
46
+ │ │ Cross-session │ │
47
+ │ │ Decision History │ │
48
+ │ └─────────────────────┘ │
49
+ │ │
50
+ └──────────────────────────────────────────────────────────────────────────────────────────────────┘
51
+ │
52
+ ▼
53
+ ┌─────────────────────────────────────────────────────────────┐
54
+ │ GITHUB + CI/CD │
55
+ │ │
56
+ │ Branch → PR → Merge Queue → Deploy │
57
+ └─────────────────────────────────────────────────────────────┘
58
+ ```
59
+
60
+ ---
61
+
62
+ ## Data Flow: Issue to Deployment
63
+
64
+ ```
65
+ LINEAR CLAUDE CODE CODERABBIT GITHUB
66
+ │ │ │ │
67
+ │ ┌────────────────────────┼────────────────────────────┼────────────────────────┤
68
+ │ │ │ │ │
69
+ ▼ ▼ ▼ ▼ ▼
70
+ ┌─────────┐ /ready ┌─────────┐ implement ┌─────────┐ merge ┌─────────┐
71
+ │ TODO │ ──────────────► │ IN │ ───────────────► │ IN │ ───────────► │ DONE │
72
+ │ │ │PROGRESS │ │ REVIEW │ │ │
73
+ └─────────┘ └─────────┘ └─────────┘ └─────────┘
74
+ │ │ │ │
75
+ │ │ │ │
76
+ │ ▼ ▼ │
77
+ │ ┌─────────────┐ ┌─────────────┐ │
78
+ │ │ Memory │ │ Review │ │
79
+ │ │ Records │ │ Comments │ │
80
+ │ │ Decisions │ │ Blocking │ │
81
+ │ └─────────────┘ └─────────────┘ │
82
+ │ │ │ │
83
+ │ ▼ │ │
84
+ │ ┌─────────────┐ │ │
85
+ │ │ /handoff │◄────────────────────┘ │
86
+ │ │ Document │ │
87
+ │ └─────────────┘ │
88
+ │ │ │
89
+ └───────────────────────────┴─────────────────────────────────────────────────────┘
90
+ AUTO-SYNC
91
+ ```
92
+
93
+ ---
94
+
95
+ ## Component Deep Dives
96
+
97
+ ### 1. Linear Integration
98
+
99
+ Linear is the **single source of truth** for what needs to be done.
100
+
101
+ ```
102
+ ┌──────────────────────────────────────────────────────────────┐
103
+ │ LINEAR │
104
+ ├──────────────────────────────────────────────────────────────┤
105
+ │ │
106
+ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
107
+ │ │ Backlog │ ─► │ Todo │ ─► │ In │ ─► │ Done │ │
108
+ │ │ │ │ │ │Progress │ │ │ │
109
+ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │
110
+ │ │ │ ▲ ▲ │
111
+ │ │ │ │ │ │
112
+ │ ▼ ▼ │ │ │
113
+ │ /discover /ready PR Opens PR Merges │
114
+ │ (new work) (pick work) (auto-sync) (auto-sync) │
115
+ │ │
116
+ └──────────────────────────────────────────────────────────────┘
117
+ │
118
+ ▼
119
+ ┌──────────────────────────┐
120
+ │ Configuration │
121
+ │ .claude/linear.yaml │
122
+ │ ────────────────── │
123
+ │ team_key: "ANV" │
124
+ │ team_id: <uuid> │
125
+ │ issue_prefix: "ANV" │
126
+ └──────────────────────────┘
127
+ ```
128
+
129
+ **Key Commands:**
130
+ | Command | Purpose |
131
+ |---------|---------|
132
+ | `/linear-setup` | Configure team and project |
133
+ | `/ready` | List unblocked Todo issues |
134
+ | `/tasks` | Create Linear sub-issues from plan |
135
+ | `/discover` | File new work to Backlog |
136
+
137
+ **Auto-Sync Triggers:**
138
+ - PR title contains `(ANV-123)` → Links to issue
139
+ - PR opens → Issue moves to "In Progress"
140
+ - PR merges → Issue moves to "Done"
141
+ - Commit message contains `ANV-123` → Links commit
142
+
143
+ ---
144
+
145
+ ### 2. CodeRabbit Integration
146
+
147
+ CodeRabbit is the **automated code reviewer** that catches issues before humans see the PR.
148
+
149
+ ```
150
+ ┌──────────────────────────────────────────────────────────────┐
151
+ │ CODERABBIT │
152
+ ├──────────────────────────────────────────────────────────────┤
153
+ │ │
154
+ │ PR Created │
155
+ │ │ │
156
+ │ ▼ │
157
+ │ ┌─────────────────────────────────────────────────────┐ │
158
+ │ │ PATH-BASED REVIEW RULES │ │
159
+ │ ├─────────────────────────────────────────────────────┤ │
160
+ │ │ src/app/api/** → Security, auth, rate limits │ │
161
+ │ │ src/components/** → A11y, performance, types │ │
162
+ │ │ **/*.test.ts → Coverage, edge cases │ │
163
+ │ │ global/lib/*.py → Type hints, error handling │ │
164
+ │ │ global/commands/** → Clear docs, examples │ │
165
+ │ └─────────────────────────────────────────────────────┘ │
166
+ │ │ │
167
+ │ ▼ │
168
+ │ ┌─────────────────────────────────────────────────────┐ │
169
+ │ │ PRE-MERGE CHECKS │ │
170
+ │ ├─────────────────────────────────────────────────────┤ │
171
+ │ │ ✓ linear_issue_linked (ANV-XXX in title) │ │
172
+ │ │ ✓ no_console_log (no console.log) │ │
173
+ │ │ ✓ type_safety (TypeScript strict) │ │
174
+ │ │ ✓ docstrings (public APIs documented) │ │
175
+ │ └─────────────────────────────────────────────────────┘ │
176
+ │ │ │
177
+ │ ▼ │
178
+ │ ┌─────────────────────────────────────────────────────┐ │
179
+ │ │ SECURITY SCANNERS │ │
180
+ │ ├─────────────────────────────────────────────────────┤ │
181
+ │ │ ruff │ semgrep │ gitleaks │ shellcheck │ │
182
+ │ │ (Python) │ (SAST) │ (secrets) │ (bash) │ │
183
+ │ └─────────────────────────────────────────────────────┘ │
184
+ │ │
185
+ └──────────────────────────────────────────────────────────────┘
186
+ │
187
+ ▼
188
+ ┌──────────────────────────┐
189
+ │ Configuration │
190
+ │ .coderabbit.yaml │
191
+ │ ────────────────── │
192
+ │ reviews: enabled │
193
+ │ linear_kb: ANV team │
194
+ │ auto_reply: true │
195
+ └──────────────────────────┘
196
+ ```
197
+
198
+ **Integration Points:**
199
+ - Linear knowledge base enabled for context
200
+ - Path-specific review instructions
201
+ - Custom pre-merge check rules
202
+ - Automated response to review comments
203
+
204
+ ---
205
+
206
+ ### 3. Claude Code + Anvil Layer
207
+
208
+ Claude Code is the **AI engine**. Anvil is the **orchestration layer** that gives it structure.
209
+
210
+ ```
211
+ ┌──────────────────────────────────────────────────────────────┐
212
+ │ CLAUDE CODE │
213
+ ├──────────────────────────────────────────────────────────────┤
214
+ │ │
215
+ │ ┌─────────────────────────────────────────────────────┐ │
216
+ │ │ TOOL EXECUTION │ │
217
+ │ │ ───────────────────────────────────────────────── │ │
218
+ │ │ Read │ Write │ Edit │ Bash │ Glob │ Grep │ Task │ │
219
+ │ └─────────────────────────────────────────────────────┘ │
220
+ │ │ │
221
+ │ ▼ │
222
+ │ ┌─────────────────────────────────────────────────────┐ │
223
+ │ │ ANVIL HOOK SYSTEM │ │
224
+ │ ├─────────────────────────────────────────────────────┤ │
225
+ │ │ │ │
226
+ │ │ SessionStart ──► Load context, handoffs, issues │ │
227
+ │ │ │ │
228
+ │ │ PreToolUse ────► Safety checks, dangerous cmd │ │
229
+ │ │ blocking, logging │ │
230
+ │ │ │ │
231
+ │ │ PostToolUse ───► Token tracking, TTS announce, │ │
232
+ │ │ memory recording │ │
233
+ │ │ │ │
234
+ │ │ Stop ──────────► Session summary, handoff gen, │ │
235
+ │ │ TTS announcement │ │
236
+ │ │ │ │
237
+ │ │ PreCompact ────► Backup transcript before │ │
238
+ │ │ context window trim │ │
239
+ │ │ │ │
240
+ │ └─────────────────────────────────────────────────────┘ │
241
+ │ │ │
242
+ │ ▼ │
243
+ │ ┌─────────────────────────────────────────────────────┐ │
244
+ │ │ ANVIL COMMANDS (37+) │ │
245
+ │ ├─────────────────────────────────────────────────────┤ │
246
+ │ │ │ │
247
+ │ │ SESSION /orient /ready /sprint /handoff │ │
248
+ │ │ │ │
249
+ │ │ WORKFLOW /explore /spec /plan /tasks │ │
250
+ │ │ /change /discover /clarify │ │
251
+ │ │ │ │
252
+ │ │ QUALITY /validate /evidence /checklist │ │
253
+ │ │ │ │
254
+ │ │ TOKENS /audit /efficiency /token-budget │ │
255
+ │ │ │ │
256
+ │ │ POWER /ralph start /ralph status │ │
257
+ │ │ │ │
258
+ │ └─────────────────────────────────────────────────────┘ │
259
+ │ │
260
+ └──────────────────────────────────────────────────────────────┘
261
+ ```
262
+
263
+ **Directory Structure:**
264
+ ```
265
+ ~/.claude/ # Global (all projects)
266
+ ├── commands/ # 37 slash commands
267
+ ├── templates/ # Spec, plan, handoff templates
268
+ ├── skills/ # Domain knowledge modules
269
+ └── lib/ # Python services
270
+
271
+ .claude/ # Project-specific
272
+ ├── CLAUDE.md # Project instructions
273
+ ├── constitution.md # Non-negotiable principles
274
+ ├── commands/ # Project command overrides
275
+ ├── hooks/ # 8 lifecycle hooks
276
+ ├── specs/ # Feature specifications
277
+ ├── handoffs/ # Session continuity
278
+ └── linear.yaml # Linear configuration
279
+ ```
280
+
281
+ ---
282
+
283
+ ### 4. Anvil Memory System
284
+
285
+ Memory is the **cross-session persistence layer** that prevents re-learning.
286
+
287
+ ```
288
+ ┌──────────────────────────────────────────────────────────────┐
289
+ │ MEMORY LAYERS │
290
+ ├──────────────────────────────────────────────────────────────┤
291
+ │ │
292
+ │ ┌────────────────────────────────────────────────────┐ │
293
+ │ │ Layer 1: SPECIFICATION MEMORY │ │
294
+ │ │ ──────────────────────────────── │ │
295
+ │ │ .claude/specs/current/ ← What to build │ │
296
+ │ │ .claude/specs/archived/ ← What was built │ │
297
+ │ └────────────────────────────────────────────────────┘ │
298
+ │ │ │
299
+ │ ┌────────────────────────────────────────────────────┐ │
300
+ │ │ Layer 2: TASK MEMORY │ │
301
+ │ │ ──────────────────────────────── │ │
302
+ │ │ Linear Issues ← What needs doing │ │
303
+ │ │ .claude/linear.yaml ← Team configuration │ │
304
+ │ └────────────────────────────────────────────────────┘ │
305
+ │ │ │
306
+ │ ┌────────────────────────────────────────────────────┐ │
307
+ │ │ Layer 3: SESSION MEMORY │ │
308
+ │ │ ──────────────────────────────── │ │
309
+ │ │ Observations ← What happened │ │
310
+ │ │ Decisions ← Why we chose this │ │
311
+ │ │ Discoveries ← What we learned │ │
312
+ │ └────────────────────────────────────────────────────┘ │
313
+ │ │ │
314
+ │ ┌────────────────────────────────────────────────────┐ │
315
+ │ │ Layer 4: HANDOFF MEMORY │ │
316
+ │ │ ──────────────────────────────── │ │
317
+ │ │ .claude/handoffs/ ← Where we left off │ │
318
+ │ │ .claude/retros/ ← What we learned │ │
319
+ │ └────────────────────────────────────────────────────┘ │
320
+ │ │ │
321
+ │ ┌────────────────────────────────────────────────────┐ │
322
+ │ │ Layer 5: CONVENTION MEMORY │ │
323
+ │ │ ──────────────────────────────── │ │
324
+ │ │ CLAUDE.md ← How to build here │ │
325
+ │ │ constitution.md ← Non-negotiables │ │
326
+ │ │ Skills ← Domain knowledge │ │
327
+ │ └────────────────────────────────────────────────────┘ │
328
+ │ │
329
+ └──────────────────────────────────────────────────────────────┘
330
+ ```
331
+
332
+ **Observation Types:**
333
+ ```
334
+ ┌─────────────────┬───────────────────────────────────────────┐
335
+ │ Type │ Example │
336
+ ├─────────────────┼───────────────────────────────────────────┤
337
+ │ feature │ Implemented auth flow with JWT │
338
+ │ bugfix │ Fixed race condition in upload queue │
339
+ │ refactor │ Extracted validation into shared module │
340
+ │ decision │ Chose SQLite over PostgreSQL for memory │
341
+ │ discovery │ Found undocumented API rate limit │
342
+ │ learning │ Pre-compact hook needs explicit backup │
343
+ └─────────────────┴───────────────────────────────────────────┘
344
+ ```
345
+
346
+ ---
347
+
348
+ ## Complete Session Lifecycle
349
+
350
+ ```
351
+ ┌────────────────────────────────────────────────────────────────────────────┐
352
+ │ SESSION LIFECYCLE │
353
+ └────────────────────────────────────────────────────────────────────────────┘
354
+
355
+ START WORK END
356
+ │ │ │
357
+ ▼ ▼ ▼
358
+ ┌─────────┐ ┌──────────┐ ┌─────────┐
359
+ │ Session │ │ Tool │ │ Stop │
360
+ │ Start │ │ Use │ │ Hook │
361
+ │ Hook │ │ Hooks │ │ │
362
+ └────┬────┘ └────┬─────┘ └────┬────┘
363
+ │ │ │
364
+ ▼ ▼ ▼
365
+ ┌─────────────┐ ┌───────────────┐ ┌──────────────┐
366
+ │ Load: │ │ Pre-tool: │ │ Generate: │
367
+ │ • Handoffs │ │ • Safety │ │ • Summary │
368
+ │ • Issues │ │ • Logging │ │ • Handoff │
369
+ │ • Context │ │ │ │ │
370
+ └──────┬──────┘ │ Post-tool: │ │ Record: │
371
+ │ │ • Tokens │ │ • Session │
372
+ ▼ │ • TTS │ │ • Decisions │
373
+ ┌─────────────┐ │ • Memory │ │ │
374
+ │ /orient │ └───────────────┘ │ Announce: │
375
+ │ /ready │ │ │ • TTS done │
376
+ │ /validate │ │ └──────────────┘
377
+ └─────────────┘ │
378
+ │ │
379
+ ▼ ▼
380
+ ┌──────────────────────────────────────────────────────────────┐
381
+ │ │
382
+ │ /explore → /spec → /plan → [code] → /evidence → PR │
383
+ │ │
384
+ │ At each step: │
385
+ │ • Memory records observations │
386
+ │ • Linear tracks status │
387
+ │ • Hooks log activity │
388
+ │ │
389
+ └──────────────────────────────────────────────────────────────┘
390
+ │
391
+ ▼
392
+ ┌─────────────────────────────────────────────────────────────┐
393
+ │ PR CREATED │
394
+ │ │
395
+ │ Title: feat(auth): add JWT refresh (ANV-123) │
396
+ │ │ │
397
+ │ ▼ │
398
+ │ ┌─────────────────────────────────────────────────────┐ │
399
+ │ │ Linear auto-sync: ANV-123 → "In Review" │ │
400
+ │ │ CodeRabbit: automated review triggered │ │
401
+ │ │ CI/CD: tests, lint, build │ │
402
+ │ └─────────────────────────────────────────────────────┘ │
403
+ │ │
404
+ │ On Merge: │
405
+ │ • Linear: ANV-123 → "Done" │
406
+ │ • Deploy: production via Vercel │
407
+ │ │
408
+ └─────────────────────────────────────────────────────────────┘
409
+ ```
410
+
411
+ ---
412
+
413
+ ## Quality Gates
414
+
415
+ ```
416
+ ┌──────────────────────────────────────────────────────────────┐
417
+ │ QUALITY GATES │
418
+ ├──────────────────────────────────────────────────────────────┤
419
+ │ │
420
+ │ GATE 1: PRE-WORK ┌─────────────────┐ │
421
+ │ ───────────────── │ /validate │ │
422
+ │ ✓ Git working tree clean │ ───────────── │ │
423
+ │ ✓ On correct branch │ All ✓ = Go │ │
424
+ │ ✓ Tests passing │ Any ✗ = Stop │ │
425
+ │ ✓ Types passing └─────────────────┘ │
426
+ │ │
427
+ │ ────────────────────────────────────────────────────────── │
428
+ │ │
429
+ │ GATE 2: DURING WORK ┌─────────────────┐ │
430
+ │ ────────────────── │ Continuous │ │
431
+ │ ✓ Read before write │ ───────────── │ │
432
+ │ ✓ Cite file paths │ Hooks enforce │ │
433
+ │ ✓ Update Linear status │ Memory records │ │
434
+ │ ✓ File discoveries └─────────────────┘ │
435
+ │ │
436
+ │ ────────────────────────────────────────────────────────── │
437
+ │ │
438
+ │ GATE 3: PRE-PR ┌─────────────────┐ │
439
+ │ ───────────── │ /evidence │ │
440
+ │ ✓ All tests pass │ ───────────── │ │
441
+ │ ✓ Lint clean │ Captures: │ │
442
+ │ ✓ Types clean │ • Test output │ │
443
+ │ ✓ Build succeeds │ • Lint output │ │
444
+ │ │ • Screenshots │ │
445
+ │ └─────────────────┘ │
446
+ │ │
447
+ │ ────────────────────────────────────────────────────────── │
448
+ │ │
449
+ │ GATE 4: POST-PR ┌─────────────────┐ │
450
+ │ ──────────── │ Automated │ │
451
+ │ ✓ CodeRabbit review passes │ ───────────── │ │
452
+ │ ✓ Semgrep security scan │ CodeRabbit │ │
453
+ │ ✓ CI/CD pipeline green │ CI/CD │ │
454
+ │ ✓ Human approval (if required) │ Merge Queue │ │
455
+ │ └─────────────────┘ │
456
+ │ │
457
+ └──────────────────────────────────────────────────────────────┘
458
+ ```
459
+
460
+ ---
461
+
462
+ ## Token Economics
463
+
464
+ ```
465
+ ┌──────────────────────────────────────────────────────────────┐
466
+ │ TOKEN MANAGEMENT │
467
+ ├──────────────────────────────────────────────────────────────┤
468
+ │ │
469
+ │ /audit /token-budget │
470
+ │ ────── ───────────── │
471
+ │ Real-time analysis: Session limits: │
472
+ │ • Current usage • Max tokens per session │
473
+ │ • Cost breakdown • Warning thresholds │
474
+ │ • Efficiency score • Auto-alerts │
475
+ │ │
476
+ │ /efficiency Context Optimization │
477
+ │ ─────────── ──────────────────── │
478
+ │ Historical patterns: • PreCompact backup │
479
+ │ • Tool usage ratios • Selective file loading │
480
+ │ • Read/write balance • Summary compression │
481
+ │ • Improvement trends • Memory reuse vs reload │
482
+ │ │
483
+ │ ┌────────────────────────────────────────────────────┐ │
484
+ │ │ Memory saves tokens by avoiding re-research │ │
485
+ │ │ │ │
486
+ │ │ Example from session context: │ │
487
+ │ │ • 50 observations available │ │
488
+ │ │ • 15,967 tokens to read │ │
489
+ │ │ • 149,512 tokens of work captured │ │
490
+ │ │ • 89% savings from reuse │ │
491
+ │ └────────────────────────────────────────────────────┘ │
492
+ │ │
493
+ └──────────────────────────────────────────────────────────────┘
494
+ ```
495
+
496
+ ---
497
+
498
+ ## TTS Announcements
499
+
500
+ ```
501
+ ┌──────────────────────────────────────────────────────────────┐
502
+ │ TEXT-TO-SPEECH SYSTEM │
503
+ ├──────────────────────────────────────────────────────────────┤
504
+ │ │
505
+ │ Engine Priority: │
506
+ │ │
507
+ │ ┌─────────────────────────────────────────────────────┐ │
508
+ │ │ 1. MLX Audio (Kokoro-82M) ← Local, fast, quality │ │
509
+ │ │ └── Requires Apple Silicon │ │
510
+ │ │ │ │
511
+ │ │ 2. ElevenLabs ← Cloud, high quality │ │
512
+ │ │ └── Requires API key │ │
513
+ │ │ │ │
514
+ │ │ 3. OpenAI TTS ← Cloud, reliable │ │
515
+ │ │ └── Requires API key │ │
516
+ │ │ │ │
517
+ │ │ 4. pyttsx3 ← Local fallback │ │
518
+ │ │ └── Cross-platform │ │
519
+ │ │ │ │
520
+ │ │ 5. macOS say ← Final fallback │ │
521
+ │ │ └── macOS only │ │
522
+ │ └─────────────────────────────────────────────────────┘ │
523
+ │ │
524
+ │ Announces: │
525
+ │ • "Tests passing" / "Tests failed" │
526
+ │ • "Build complete" │
527
+ │ • "Plan complete, ready for review" │
528
+ │ • "Session ending" │
529
+ │ • Subagent completions │
530
+ │ │
531
+ └──────────────────────────────────────────────────────────────┘
532
+ ```
533
+
534
+ ---
535
+
536
+ ## Quick Reference: Integration Touch Points
537
+
538
+ | System | Config File | Key Integration |
539
+ |--------|-------------|-----------------|
540
+ | **Linear** | `.claude/linear.yaml` | Issue tracking, sprint planning |
541
+ | **CodeRabbit** | `.coderabbit.yaml` | Automated code review |
542
+ | **Claude Code** | `CLAUDE.md`, `.claude/` | AI agent instructions |
543
+ | **Memory** | `.anvil/memory.db` | Cross-session persistence |
544
+ | **Hooks** | `.claude/hooks/` | Lifecycle automation |
545
+ | **GitHub** | PR title format | Issue linking, auto-close |
546
+
547
+ ---
548
+
549
+ ## Cost Breakdown
550
+
551
+ ```
552
+ ┌──────────────────────────────────────────────────────────────┐
553
+ │ MONTHLY COSTS │
554
+ ├──────────────────────────────────────────────────────────────┤
555
+ │ │
556
+ │ Claude Pro/Max $100-200/month │
557
+ │ Linear (Solo) $0 (free tier) │
558
+ │ CodeRabbit Pro $12/month │
559
+ │ GitHub $0 (free for public) │
560
+ │ Vercel $0-20/month │
561
+ │ ───────────────────────────────────── │
562
+ │ Total ~$112-232/month │
563
+ │ │
564
+ └──────────────────────────────────────────────────────────────┘
565
+ ```
566
+
567
+ ---
568
+
569
+ *For detailed implementation guides, see individual documentation files in `/docs/`.*
package/global/commands/anvil-settings.md CHANGED
@@ -36,9 +36,11 @@
36
36
  | `autoRetro` | `off` | Prompt for `/retro` at session end |
37
37
  | `autoHealthcheck` | `off` | Run `/healthcheck` at session end |
38
38
  | `statusline` | `full` | Statusline display variant (`full`, `minimal`, `off`) |
39
- | `codeReview` | `off` | Enable code review integration |
39
+ | `codeReview` | `on` | Enable code review integration |
40
40
  | `codeReview.tool` | `coderabbit` | Code review tool to use |
41
41
  | `codeReview.enforcement` | `soft` | Enforcement level (`soft` = prompt, `hard` = block) |
42
+ | `codeReview.prePR` | `on` | Run code review automatically in `/evidence` |
43
+ | `statusline.showCodeRabbit` | `on` | Show CodeRabbit status in statusline (CR:N) |
42
44
  | `hud` | `on` | Enable HUD features (agent registry, dashboard) |
43
45
  | `hud.mode` | `sidebar` | HUD mode (`sidebar` for TUI, `statusline-only` for minimal) |
44
46
  | `hud.showAgentCount` | `on` | Show agent count in statusline |