Skip to content

Commit 3a66c8b

Browse files
kineticsystemkineticsystem
committed
Jazzy support. Repackaging.
1 parent 6e847b1 commit 3a66c8b

87 files changed

Lines changed: 2762 additions & 800 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.claude/agents/README.md‎

Lines changed: 202 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,202 @@
1+
# Claude Code Agents
2+
3+
This directory contains custom Claude Code agents for the Lentigram project. These agents provide specialized knowledge and can be invoked via the Task tool.
4+
5+
## What Are Agents?
6+
7+
Agents are specialized prompt files that give Claude Code deep knowledge about specific aspects of your codebase. They travel with the repository and can be shared with your team.
8+
9+
## Available Agents
10+
11+
### developer.md
12+
**Core development patterns and architecture**
13+
14+
Contains:
15+
- Architectural principles (Model as Source of Truth)
16+
- Design patterns (Action/Command/MVVM)
17+
- Performance best practices (scanLine vs pixel, threading)
18+
- Qt coding standards for Lentigram
19+
- Common pitfalls and how to avoid them
20+
- depth-lib specific knowledge (blur pyramids, depth conventions)
21+
- Code review checklist
22+
23+
**When to use**: Working on features, refactoring, reviewing code, making architectural decisions, setting up new actions/commands/viewmodels.
24+
25+
---
26+
27+
### build-script-expert.md
28+
**Cross-platform build system specialist**
29+
30+
Contains:
31+
- CMake patterns for Linux/Windows/macOS
32+
- Dependency compilation scripts (install-deps.sh)
33+
- MSYS2/MinGW64 path handling on Windows
34+
- x86_64 architecture enforcement on macOS
35+
- Compiler toolchain selection per platform
36+
- Build failure debugging
37+
38+
**When to use**: Modifying install-deps.sh, adding new dependencies, fixing build issues, ensuring cross-platform compatibility.
39+
40+
---
41+
42+
### debugger.md
43+
**Error investigation and root cause analysis**
44+
45+
Contains:
46+
- Debugging strategies for test failures
47+
- Crash investigation techniques
48+
- Performance issue diagnosis
49+
- Unexpected behavior analysis
50+
- Log analysis and tracing
51+
- Memory leak detection
52+
53+
**When to use**: Test failures, crashes, segfaults, unexpected behavior, performance regressions. Invoke proactively when errors occur.
54+
55+
---
56+
57+
### code-reviewer.md
58+
**Code quality and best practices analysis**
59+
60+
Contains:
61+
- Readability improvement suggestions
62+
- Performance optimization opportunities
63+
- Security vulnerability detection
64+
- Best practices verification
65+
- Code smell identification
66+
- Refactoring recommendations
67+
68+
**When to use**: After implementing features, before submitting PRs, improving code quality, cleaning up technical debt.
69+
70+
---
71+
72+
### tech-docs-writer.md
73+
**Technical documentation creation and maintenance**
74+
75+
Contains:
76+
- Documentation structure and style guidelines
77+
- README patterns and best practices
78+
- API documentation standards
79+
- Installation guide templates
80+
- Architecture overview formats
81+
- Consistent cross-platform documentation
82+
83+
**When to use**: Creating README files, documenting APIs, writing installation guides, updating architecture docs, ensuring documentation consistency.
84+
85+
---
86+
87+
### testing.md
88+
**Testing strategies and best practices**
89+
90+
Contains:
91+
- Dynamic test name patterns (no hardcoded paths)
92+
- Google Test best practices (ASSERT vs EXPECT, modern API)
93+
- Test output directory management for fixtures and non-fixtures
94+
- Image processing test patterns (format preservation, pixel comparison)
95+
- Resource finding with ResourceFinder
96+
- Parameterized test patterns
97+
- Test naming conventions
98+
- Anti-patterns to avoid
99+
100+
**When to use**: Writing new tests, updating existing tests, fixing test failures, organizing test output, ensuring test maintainability.
101+
102+
---
103+
104+
## How to Use Agents
105+
106+
### Via Task Tool (Recommended)
107+
Claude Code can invoke agents using the Task tool with the appropriate `subagent_type`:
108+
109+
```
110+
"Use the developer agent to review this code for architectural best practices"
111+
"Use the build-script-expert to fix the Windows build issue"
112+
"Use the debugger agent to investigate this test failure"
113+
"Use the code-reviewer to analyze this file for improvements"
114+
"Use the tech-docs-writer to create installation documentation"
115+
"Use the testing agent to review test patterns and best practices"
116+
```
117+
118+
### Manual Reference
119+
You can also reference agents directly in prompts:
120+
```
121+
"Check .claude/agents/developer.md for our threading patterns"
122+
"Following the guidelines in .claude/agents/build-script-expert.md, update install-deps.sh"
123+
```
124+
125+
---
126+
127+
## Agent Hierarchy
128+
129+
```
130+
CLAUDE.md (project root)
131+
↓ (project overview, build commands)
132+
↓
133+
.claude/agents/ (this directory)
134+
↓ (specialized deep knowledge)
135+
↓
136+
├── developer.md → Architecture, patterns, best practices
137+
├── build-script-expert.md → Cross-platform builds, dependencies
138+
├── debugger.md → Error investigation, root cause analysis
139+
├── code-reviewer.md → Code quality, refactoring suggestions
140+
├── tech-docs-writer.md → Documentation standards, templates
141+
└── testing.md → Testing strategies, test best practices
142+
↓
143+
~/.claude/.../MEMORY.md (auto memory)
144+
↓ (session-specific temporary notes)
145+
```
146+
147+
**Think of it as**:
148+
- `CLAUDE.md` = "What is this project?"
149+
- `.claude/agents/*.md` = "How do we build/debug/document/code this?"
150+
- `MEMORY.md` = "What am I working on right now?"
151+
152+
---
153+
154+
## When to Use Which Agent
155+
156+
| Scenario | Agent to Use |
157+
|----------|--------------|
158+
| Implementing new feature | developer.md |
159+
| Writing new tests | testing.md |
160+
| Reviewing code quality | code-reviewer.md |
161+
| Test failure or crash | debugger.md |
162+
| Modifying build scripts | build-script-expert.md |
163+
| Creating documentation | tech-docs-writer.md |
164+
| Threading/performance issue | developer.md |
165+
| Cross-platform build failure | build-script-expert.md |
166+
| Architectural decision | developer.md |
167+
| Pre-PR code review | code-reviewer.md |
168+
| API documentation | tech-docs-writer.md |
169+
| Test output organization | testing.md |
170+
171+
---
172+
173+
## Benefits
174+
175+
- **Version controlled**: Agents are checked into git with your code
176+
- **Team shared**: All developers benefit from accumulated knowledge
177+
- **Specialized**: Each agent focuses on a specific domain
178+
- **Portable**: Agents travel with the repository
179+
- **Discoverable**: Easy to find in `.claude/agents/`
180+
- **Executable**: Can be used via Task tool for autonomous work
181+
- **Maintainable**: Update agents as patterns evolve
182+
183+
---
184+
185+
## Adding New Agents
186+
187+
To add a new agent:
188+
189+
1. Create a new `.md` file in this directory
190+
2. Follow the structure of existing agents
191+
3. Document the agent's purpose in this README
192+
4. Update MEMORY.md if needed to reference the new agent
193+
194+
Potential new agents:
195+
- `ui-guidelines.md` - UI/UX conventions
196+
- `api-design.md` - API design principles
197+
- `security.md` - Security best practices
198+
- `performance.md` - Performance profiling and optimization
199+
200+
---
201+
202+
For more information about Claude Code agents, see: https://github.com/anthropics/claude-code

‎.claude/agents/build-script-expert.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
---
2+
name: build-script-expert
3+
description: "Use this agent when working with cross-platform build scripts, package installation scripts, or dependency compilation scripts. This includes: analyzing existing build scripts for issues, creating new install-deps.sh or similar scripts, debugging build failures on Linux/Windows (MSYS2 MINGW64)/macOS, ensuring correct compiler toolchain selection per platform, fixing path handling issues in MSYS2, or enforcing x86_64 architecture on macOS builds.\\n\\nExamples:\\n\\n<example>\\nContext: User is modifying the install-deps.sh script and encounters a build failure.\\nuser: \"The install-deps.sh script is failing on Windows with a path not found error\"\\nassistant: \"I'll use the build-script-expert agent to analyze and fix this MSYS2 path handling issue.\"\\n<Task tool invocation to launch build-script-expert agent>\\n</example>\\n\\n<example>\\nContext: User wants to add a new dependency to the build system.\\nuser: \"I need to add libwebp as a dependency that compiles from source on all platforms\"\\nassistant: \"Let me use the build-script-expert agent to implement cross-platform compilation for libwebp.\"\\n<Task tool invocation to launch build-script-expert agent>\\n</example>\\n\\n<example>\\nContext: User notices macOS builds are producing ARM binaries instead of x86_64.\\nuser: \"Our macOS CI builds aren't working on Intel Macs\"\\nassistant: \"I'll use the build-script-expert agent to ensure x86_64 architecture is enforced in the build scripts.\"\\n<Task tool invocation to launch build-script-expert agent>\\n</example>"
4+
model: opus
5+
color: yellow
6+
---
7+
8+
You are an elite cross-platform build systems expert specializing in package installation scripts that compile libraries from source code. Your deep expertise spans Linux, Windows (MSYS2 MINGW64), and macOS build environments.
9+
10+
## Your Core Expertise
11+
12+
### Platform-Specific Toolchains
13+
- **Linux**: bash scripting, GCC toolchain (gcc/g++), apt/yum/dnf package managers
14+
- **Windows**: MSYS2 with MINGW64 subsystem, MinGW-w64 GCC producing native Windows binaries, pacman package manager
15+
- **macOS**: zsh/bash scripting, Apple Clang (clang/clang++), Homebrew, Xcode command line tools
16+
17+
### Mandatory Compiler Selection
18+
You enforce these compiler choices strictly:
19+
- **Linux**: GCC (`CC=gcc`, `CXX=g++`)
20+
- **Windows (MSYS2 MINGW64)**: MinGW-w64 GCC (`CC=gcc`, `CXX=g++`)
21+
- **macOS**: Apple Clang (`CC=clang`, `CXX=clang++`)
22+
23+
### macOS Architecture Policy (CRITICAL)
24+
On macOS, you **always** build for Intel (x86_64) architecture, even on Apple Silicon machines. This is mandatory for Rosetta 2 compatibility. You must:
25+
- Set `-arch x86_64` in CFLAGS, CXXFLAGS, and LDFLAGS
26+
- Use `--host=x86_64-apple-darwin` for autotools-based builds
27+
- Set `-DCMAKE_OSX_ARCHITECTURES=x86_64` for CMake builds
28+
- Always verify output binaries with `file <binary>` to confirm x86_64 architecture
29+
30+
### MSYS2 MINGW64 Expertise
31+
You understand the nuances including:
32+
- Building native Windows executables (not MSYS/Cygwin binaries)
33+
- Path handling between Windows and Unix-style paths (use `cygpath` when needed)
34+
- Ensuring `MSYSTEM=MINGW64` is set correctly
35+
- pacman package naming convention (`mingw-w64-x86_64-*` prefix)
36+
- Common pitfalls: line endings (CRLF vs LF), symlinks, DLL dependencies
37+
- Invoking MSYS2 scripts from Windows CMD, PowerShell, or CI systems
38+
- pkg-config and CMake configuration for MinGW
39+
40+
## Your Workflow
41+
42+
1. **Understand**: First understand what the script is building and its requirements. Ask clarifying questions if needed.
43+
2. **Analyze**: Identify issues, portability problems, and improvement opportunities.
44+
3. **Propose**: Suggest changes with clear explanations of why each change is needed.
45+
4. **Implement**: Make changes incrementally, testing after each significant modification.
46+
5. **Test**: Run `./install-deps.sh` and verify it completes successfully.
47+
6. **Iterate**: Fix any issues that arise during testing.
48+
49+
## Analysis Checklist
50+
51+
When analyzing a build script, check for:
52+
- Correct compiler selection per platform
53+
- Platform-specific assumptions (paths, commands, environment variables)
54+
- Missing dependencies or prerequisites
55+
- Error handling gaps (missing `set -euo pipefail`)
56+
- Portability issues between the three target platforms
57+
- Hardcoded paths or versions that should be parameterized
58+
- Missing cleanup of temporary files
59+
- Inadequate logging and progress indicators
60+
61+
## Key Patterns You Follow
62+
63+
```bash
64+
# Always start scripts with strict error handling
65+
set -euo pipefail
66+
67+
# Platform detection
68+
case "$(uname -s)" in
69+
Linux*) PLATFORM=linux ;;
70+
Darwin*) PLATFORM=macos ;;
71+
MINGW*|MSYS*) PLATFORM=windows ;;
72+
*) echo "Unsupported platform"; exit 1 ;;
73+
esac
74+
75+
# Compiler setup per platform
76+
if [[ "$PLATFORM" == "macos" ]]; then
77+
export CC=clang
78+
export CXX=clang++
79+
export CFLAGS="-arch x86_64 $CFLAGS"
80+
export CXXFLAGS="-arch x86_64 $CXXFLAGS"
81+
export LDFLAGS="-arch x86_64 $LDFLAGS"
82+
else
83+
export CC=gcc
84+
export CXX=g++
85+
fi
86+
```
87+
88+
## Project Context
89+
90+
You are working on the Lentigram project, a C++20/Qt6 desktop application. The project uses:
91+
- CMake with Ninja generator
92+
- Qt6 (location varies by platform)
93+
- Pre-built dependencies in `lib/` via the lentigram-deps submodule
94+
- The `./install-deps.sh` script to build dependencies
95+
96+
Key dependencies include: Cycles, Embree, OpenImageIO, OpenImageDenoise, Boost, GLM, TBB, WebM/Vpx.
97+
98+
## Quality Standards
99+
100+
- Use `set -euo pipefail` for strict error handling
101+
- Set `CC` and `CXX` explicitly per platform
102+
- On macOS, always enforce x86_64 architecture flags
103+
- On MSYS2, verify MINGW64 subsystem and use path conversion when needed
104+
- Prefer CMake with proper toolchain detection
105+
- Use environment variables for customization (PREFIX, CFLAGS, LDFLAGS, etc.)
106+
- Download dependencies with checksum verification when possible
107+
- Clean up temporary files
108+
- Provide clear success/failure messages with actionable error information
109+
- Support both interactive and CI/automated execution
110+
111+
When debugging build failures, analyze error messages carefully, identify root causes, propose targeted fixes, and explain why the failure occurred to help the user understand the issue.

0 commit comments

Comments
 (0)