docs(agents): fix factual errors, add mise tasks, improve agent efficiency by richardthe3rd · Pull Request #259 · richardthe3rd/cambridge-beer-festival-app

richardthe3rd · 2026-05-11T22:01:23Z

Summary

AGENTS.md restructured: project context first, single Commands section referencing mise tasks ls, Engineering Standards moved to end. Down from ~927 to ~510 lines.
CLAUDE.md reduced to @AGENTS.md (Claude Code memory import syntax — loads AGENTS.md into context automatically)
.github/copilot-instructions.md trimmed: removed duplicated mise commands/workflows (Copilot now reads AGENTS.md directly per Aug 2025 changelog); kept coding conventions, utils/widget catalogue, JSON patterns

mise.toml changes (behaviour)

Add check task: pre-commit gate running generate → analyze + test
Add goldens:update task: regenerate golden screenshots (optional file arg)
test and analyze tasks: save output to temp file via tee, print path before run and grep hint after, preserve exit codes via set -o pipefail + explicit exit $EXIT_CODE

Factual fixes

Infrastructure list: StorageService → actual class names (FavoritesService, RatingsService, FestivalStorageService)
Linter rules list: add missing prefer_const_declarations, reword as "among others"
copilot-instructions.md accessibility reference: CLAUDE.md → AGENTS.md

https://claude.ai/code/session_015rZFtTwYwLn5Z8zQrk4sgM

…UDE.md - AGENTS.md: playwright-setup → setup:playwright (correct task name) - AGENTS.md: fix 'mise run test <file>' → 'mise exec flutter -- flutter test <file>' - AGENTS.md: validate:festivals raw command → ./bin/mise run validate:festivals - AGENTS.md: DrinkSort location beer_provider.dart → lib/domain/models/drink_sort.dart - AGENTS.md: sort step 2 now points to DrinkSortService, not _applyFiltersAndSort - CLAUDE.md: build:web and serve:release in deep links section missing MISE_ENV=dev - CLAUDE.md: domain/ dir tree missing models/ and repositories/ subdirectories - CLAUDE.md: infrastructure services corrected (StorageService, TastingLogService, EnvironmentService) https://claude.ai/code/session_015rZFtTwYwLn5Z8zQrk4sgM

Copilot coding agent now reads AGENTS.md directly, so the mise commands, common workflows, build steps, and raw Flutter command sections were pure duplication that was drifting out of sync. Kept: coding conventions, utils/widget catalogue, JSON parsing patterns, API reference, Playwright limitations, deployment topology, and security. Also fixed: domain/ layer added to project structure, API doc paths (docs/api/ → docs/code/api/), broken bottom doc links removed, GitHub Pages base-href artefact removed, install task reference removed. https://claude.ai/code/session_015rZFtTwYwLn5Z8zQrk4sgM

…md import CLAUDE.md now imports AGENTS.md via @AGENTS.md rather than duplicating the mise commands, environments, task lists, deep links, and validation workflow sections. Retained: architecture, code style, accessibility, model patterns, provider usage, common modifications, API details, and release process. Also fixed during rewrite: domain/ structure complete, service list accurate, sort option instructions point to correct files. https://claude.ai/code/session_015rZFtTwYwLn5Z8zQrk4sgM

… @AGENTS.md Architecture, directory structure, accessibility requirements, JSON parsing patterns, provider usage, and release process all moved from CLAUDE.md into AGENTS.md — useful to any coding agent, not Claude-specific. CLAUDE.md is now a single line: @AGENTS.md AGENTS.md additions: - Full directory structure with domain/ layer - Layered architecture description (domain, state, infrastructure, data) - Accessibility requirements with code examples - JSON parsing pattern for type-variant API fields - Provider usage examples and key methods - Release process (CalVer + tag workflow) - analysis_options.yaml added to Do Not Modify https://claude.ai/code/session_015rZFtTwYwLn5Z8zQrk4sgM

- Move Project Context + Architecture + Directory Structure to the top - Collapse Quick Start + Task Discovery Guide into one Commands section - Remove duplicate ./bin/mise tasks ls commands - Remove "Helpful Tips" (all points covered in detail elsewhere) - Remove "Before Making Changes" as standalone section (folded into Making Changes) - Collapse "Adding a New Drink Category Filter" to a one-line note - Fix raw flutter test --update-goldens → ./bin/mise exec flutter -- flutter test - Consolidate Testing sections (Best Practices + Guidelines + Coverage) - Merge Definition of Done, Error Handling, Abstraction, Documentation into Engineering Standards - 927 lines → 496 lines https://claude.ai/code/session_015rZFtTwYwLn5Z8zQrk4sgM

- check: pre-commit gate running generate → analyze + test in one command - goldens:update: wraps --update-goldens with optional file argument - test: 180s timeout to prevent hanging test suites - AGENTS.md: reference check as canonical pre-commit command, goldens:update replaces raw flutter test --update-goldens invocation https://claude.ai/code/session_015rZFtTwYwLn5Z8zQrk4sgM

- test: output saved to $TEST_LOG (mktemp default, caller-injectable) - analyze: output saved to $ANALYZE_LOG (same pattern) - Path printed before the run so agents have it even if the run crashes - Grep hint printed after the run for convenience - Remove timeout=180 from test task - AGENTS.md: drop manual redirect instructions, note TEST_LOG session pinning https://claude.ai/code/session_015rZFtTwYwLn5Z8zQrk4sgM

https://claude.ai/code/session_015rZFtTwYwLn5Z8zQrk4sgM

Copilot

Pull request overview

This PR aims to correct and streamline agent/developer documentation (AGENTS.md / Copilot instructions / Claude guidance) and update local task-running guidance around mise.

Changes:

Reworks AGENTS.md into a more structured, architecture-first guide and updates task references (including new check / goldens:update tasks).
Updates mise.toml tasks to capture test/analyze output to log files and adds new convenience tasks (check, goldens:update).
Simplifies CLAUDE.md and trims/updates .github/copilot-instructions.md to reduce duplication and point to AGENTS.md.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 9 comments.

File	Description
mise.toml	Updates task behavior (log capture) and adds new tasks (`check`, `goldens:update`).
AGENTS.md	Major rewrite: architecture overview, updated mise command guidance, testing/accessibility sections.
CLAUDE.md	Replaced full content with a single `@AGENTS.md` reference.
.github/copilot-instructions.md	Condensed Copilot guidance; updated project structure and references.

+echo "TEST_LOG=$TEST_LOG"
+flutter test 2>&1 | tee "$TEST_LOG"
+echo "---"
+echo "Grep with: grep -n 'FAILED\|ERROR' $TEST_LOG"


+echo "ANALYZE_LOG=$ANALYZE_LOG"
+flutter analyze --no-fatal-infos 2>&1 | tee "$ANALYZE_LOG"
+echo "---"
+echo "Grep with: grep -n 'error\|warning' $ANALYZE_LOG"


+| **Pre-commit gate** | `./bin/mise run check` | **Run before every commit** |
+| Generate code (mocks) | `./bin/mise run generate` | After model changes |
+| Analyze code | `./bin/mise run analyze` | generate → analyze |
+| Run tests | `./bin/mise run test` | generate → test |
+| Run tests with coverage | `./bin/mise run coverage` | Includes code generation |
+| Run dev server | `MISE_ENV=dev ./bin/mise run dev` | |


 ```bash
-# Run all tests (can be slow)
+# Pin a path for the whole session so output accumulates in one known place
+export TEST_LOG=/tmp/my-session-test.log
 ./bin/mise run test

-# Run specific test file
-./bin/mise run test test/style_screen_test.dart
-
-# Run tests with output to file for analysis
-./bin/mise run test > /tmp/test_output.txt 2>&1
-cat /tmp/test_output.txt | grep -E "(passed|failed)" | tail -10
-
-# Run with timeout to prevent hanging
-timeout 180 ./bin/mise run test
+# Run a specific test file
+./bin/mise exec flutter -- flutter test test/my_test.dart


+**Infrastructure** (`lib/services/`):
+- `BeerApiService` — HTTP API calls
+- `FestivalService` — festival metadata
+- `StorageService` — SharedPreferences; contains `FavoritesService`, `RatingsService`, `FestivalStorageService`


richardthe3rd · 2026-05-11T22:14:10Z

- Cloudflare Worker (`cloudflare-worker/`)
- Package versions in `pubspec.yaml`
- Analysis rules in `analysis_options.yaml`
+@AGENTS.md


This is intentional — @AGENTS.md is Claude Code's memory file import syntax (documented at https://code.claude.com/docs/en/memory). When Claude reads CLAUDE.md, it automatically loads the referenced file into context. It's not standard Markdown, but CLAUDE.md is a Claude Code config file, not a documentation file for human readers. The effect is that agents get the full AGENTS.md content without duplication.

Generated by Claude Code

- Store error messages in provider state
- Display user-friendly error messages in UI
- Provide retry functionality for failed operations
+Every interactive element needs a `Semantics` wrapper with a `label`. See [`docs/code/accessibility.md`](../docs/code/accessibility.md) and `CLAUDE.md` for full requirements and examples.


 [tasks.test]
-description = "Run all Flutter tests"
+description = "Run all Flutter tests (output saved to $TEST_LOG, or set TEST_LOG to reuse a path)"
 depends = ['generate']
-run = 'flutter test'
+run = '''
+TEST_LOG="${TEST_LOG:-$(mktemp /tmp/test-XXXXXX.log)}"
+echo "TEST_LOG=$TEST_LOG"
+flutter test 2>&1 | tee "$TEST_LOG"
+echo "---"
+echo "Grep with: grep -n 'FAILED\|ERROR' $TEST_LOG"
+'''
+
+[tasks.check]
+description = "Pre-commit gate: generate → analyze + test (run before every commit)"
+depends = ['analyze', 'test']
+run = 'echo "All checks passed"'
+
+[tasks."goldens:update"]
+description = "Regenerate golden screenshot files (omit file arg to update all)"
+depends = ['generate']
+usage = 'arg "[file]" help="Specific test file to update"'
+run = 'flutter test --update-goldens ${usage_file:-}'


- Search and filter by category, name, brewery, or style
- Save favorites and rate drinks
- View brewery details
+**Linter rules enforced**: `prefer_const_constructors`, `prefer_final_locals`, `prefer_final_fields`, `avoid_print`, `prefer_single_quotes`, `sort_child_properties_last`, `use_key_in_widget_constructors`.


- Add goldens:update to Common Tasks table - Move 'run check' note to top of Git Commit section (not after PR title examples) - Replace hardcoded /tmp/ example path with $TMPDIR/cbf-test.log https://claude.ai/code/session_015rZFtTwYwLn5Z8zQrk4sgM

github-actions · 2026-05-11T22:07:01Z

LCOV of commit `a93e703` during CI #160

Summary coverage rate:
  lines......: 77.1% (2439 of 3163 lines)
  functions..: no data found
  branches...: no data found

Files changed coverage rate: n/a

https://claude.ai/code/session_015rZFtTwYwLn5Z8zQrk4sgM

codecov · 2026-05-11T22:12:55Z

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

- Add set -o pipefail + exit code capture to test and analyze tasks so pipe through tee doesn't mask flutter test/analyze exit codes - Fix StorageService docs: there is no StorageService class; the actual classes are FavoritesService, RatingsService, FestivalStorageService - Add prefer_const_declarations to linter rules list (was missing) - Reword list as "among others" to avoid implying exhaustiveness - Fix copilot-instructions.md accessibility reference: CLAUDE.md → AGENTS.md (CLAUDE.md is now just an @AGENTS.md import) https://claude.ai/code/session_015rZFtTwYwLn5Z8zQrk4sgM

github-actions · 2026-05-11T22:23:29Z

🚀 Cloudflare Pages Preview

Your preview deployment is ready!

Preview URL: https://claude-review-agents-claude.staging-cambeerfestival.pages.dev

This preview will be automatically updated when you push new commits to this PR.

Copilot AI review requested due to automatic review settings May 11, 2026 22:01

Copilot started reviewing on behalf of richardthe3rd May 11, 2026 22:01 View session

claude added 8 commits May 11, 2026 22:02

fix: remove stale 180s timeout note from task table

fd7d2ea

https://claude.ai/code/session_015rZFtTwYwLn5Z8zQrk4sgM

richardthe3rd force-pushed the claude/review-agents-claude-docs-qWYn7 branch from 810c955 to fd7d2ea Compare May 11, 2026 22:03

Copilot AI reviewed May 11, 2026

View reviewed changes

docs: fix three issues in AGENTS.md

b236e96

- Add goldens:update to Common Tasks table - Move 'run check' note to top of Git Commit section (not after PR title examples) - Replace hardcoded /tmp/ example path with $TMPDIR/cbf-test.log https://claude.ai/code/session_015rZFtTwYwLn5Z8zQrk4sgM

docs: demote TEST_LOG to a footnote, not the primary example

8fa967c

https://claude.ai/code/session_015rZFtTwYwLn5Z8zQrk4sgM

richardthe3rd changed the title ~~docs: fix factual errors and outdated references in AGENTS.md and CLAUDE.md~~ docs(agents): fix factual errors, add mise tasks, improve agent efficiency May 11, 2026

richardthe3rd merged commit 4781ffe into main May 11, 2026
11 of 12 checks passed

richardthe3rd deleted the claude/review-agents-claude-docs-qWYn7 branch May 11, 2026 22:27

This was referenced May 13, 2026

Release 2026.5.5 #262

Merged

Release 2026.5.5 #285

Merged

Navigation Menu

docs(agents): fix factual errors, add mise tasks, improve agent efficiency - #259

docs(agents): fix factual errors, add mise tasks, improve agent efficiency#259
richardthe3rd merged 11 commits into
mainfrom
claude/review-agents-claude-docs-qWYn7

richardthe3rd commented May 11, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

richardthe3rd May 11, 2026

Uh oh!

github-actions Bot commented May 11, 2026 •

edited

Loading

Uh oh!

codecov Bot commented May 11, 2026

Uh oh!

github-actions Bot commented May 11, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

richardthe3rd commented May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

mise.toml changes (behaviour)

Factual fixes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

richardthe3rd May 11, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

LCOV of commit a93e703 during CI #160

Uh oh!

codecov Bot commented May 11, 2026

Codecov Report

Uh oh!

github-actions Bot commented May 11, 2026

🚀 Cloudflare Pages Preview

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

richardthe3rd commented May 11, 2026 •

edited

Loading

github-actions Bot commented May 11, 2026 •

edited

Loading

LCOV of commit `a93e703` during CI #160