diff --git a/.agents/skills/grilly/SKILL.md b/.agents/skills/grilly/SKILL.md new file mode 100644 index 0000000..0489160 --- /dev/null +++ b/.agents/skills/grilly/SKILL.md @@ -0,0 +1,141 @@ +```markdown +# grilly Development Patterns + +> Auto-generated skill from repository analysis + +## Overview +This skill teaches the core development patterns, coding conventions, and common workflows used in the `grilly` codebase. `grilly` is a Python-centric project (with C++ and shader components) focused on autograd operations, GPU acceleration, and integration between Python and C++. The repository emphasizes modularity, clear commit practices, and a workflow-driven approach to adding features and documenting progress. + +## Coding Conventions + +- **File Naming:** + Use `snake_case` for all Python and script files. + *Example:* + ``` + test_backward_rmsnorm.py + train_linear_ce.py + ``` + +- **Import Style:** + Prefer **relative imports** within Python modules. + *Example:* + ```python + from .core import Tensor + from .autograd import backward_rmsnorm + ``` + +- **Export Style:** + Use **named exports** for functions and classes. + *Example:* + ```python + def backward_rmsnorm(...): + ... + ``` + +- **Commit Messages:** + - Freeform, but often start with prefixes like `autograd`, `docs`, `integration`, `todo`. + - Average commit message length: ~69 characters. + +## Workflows + +### Add New Autograd Operation +**Trigger:** When adding support for a new operation to the autograd engine (e.g., `backward_rmsnorm`, `forward_linear`). +**Command:** `/new-autograd-op` + +1. Implement or add new GLSL shader(s) for the operation if needed. + *Example:* `shaders/rms-norm-backward.glsl` +2. Compile GLSL to SPIR-V if required. + *Example:* `shaders/spv/rms-norm-backward.spv` +3. Update C++ autograd headers and source to add the handler. + - `cpp/include/grilly/autograd/autograd.h` + - `cpp/src/autograd.cpp` +4. Wire the operation into Python bindings. + - `cpp/python/bindings_autograd.cpp` +5. Add or update a test for the new op. + *Example:* `test_backward_rmsnorm.py` + +--- + +### Document Autograd State or Milestone +**Trigger:** When completing a significant feature, bugfix, or integration step and wanting to record the project state. +**Command:** `/update-state-doc` + +1. Edit `AUTOGRAD_STATE.md` to describe new features, bugfixes, or integration steps. +2. Optionally update `TODO.md` or related docs. +3. Commit the documentation. + +--- + +### Integration Test or Training Script Addition +**Trigger:** When verifying that a new feature or workflow works in a real training or integration scenario. +**Command:** `/add-integration-test` + +1. Add or update a script in `experimental/resident_train/`. + *Example:* `train_linear_ce.py` +2. Run the script to verify integration. +3. Optionally update documentation with results. + +--- + +### Add or Update Python-C++ Binding +**Trigger:** When adding a new C++ feature that needs to be exposed to Python. +**Command:** `/add-python-binding` + +1. Implement or update binding in `cpp/python/`. + *Example:* `bindings_autograd.cpp`, `bindings_core.cpp` +2. Update `CMakeLists.txt` if new binding files are added. +3. Optionally add a Python test or usage example. + +--- + +### Add or Update Shader and SPIR-V +**Trigger:** When implementing a new GPU operation or updating an existing one. +**Command:** `/add-shader` + +1. Write or modify a GLSL shader in `shaders/*.glsl`. +2. Compile to SPIR-V and add/update `shaders/spv/*.spv`. +3. Wire up usage in C++ and/or Python if needed. + +--- + +### Add or Update TODO or Workboard +**Trigger:** When recording new tasks, marking tasks as done, or updating project planning. +**Command:** `/update-todo` + +1. Edit `TODO.md` to add, update, or mark tasks as done. +2. Commit `TODO.md`. + +--- + +## Testing Patterns + +- **Framework:** Unknown (no standard Python test framework detected). +- **File Pattern:** Python test files use the pattern `test_*.py`. +- **Integration Tests:** Often placed in `experimental/resident_train/`. +- **Other Patterns:** Some references to `*.test.ts` (TypeScript), but main tests appear to be Python scripts. + +*Example test file:* +```python +# test_backward_rmsnorm.py +from .autograd import backward_rmsnorm + +def test_backward_rmsnorm_basic(): + # Setup input tensors + ... + # Call the function + result = backward_rmsnorm(...) + # Assert correctness + assert ... +``` + +## Commands + +| Command | Purpose | +|----------------------|----------------------------------------------------------------| +| /new-autograd-op | Add a new autograd operation (forward/backward) | +| /update-state-doc | Update project state documentation (AUTOGRAD_STATE.md, TODO.md)| +| /add-integration-test| Add or update an integration test or training script | +| /add-python-binding | Add or update Python-C++ bindings | +| /add-shader | Add or update a GLSL shader and its SPIR-V binary | +| /update-todo | Update TODO.md or project workboard | +``` diff --git a/.agents/skills/grilly/agents/openai.yaml b/.agents/skills/grilly/agents/openai.yaml new file mode 100644 index 0000000..13767bc --- /dev/null +++ b/.agents/skills/grilly/agents/openai.yaml @@ -0,0 +1,6 @@ +interface: + display_name: "Grilly" + short_description: "Repo-specific patterns and workflows for grilly" + default_prompt: "Use the grilly repo skill to follow existing architecture, testing, and workflow conventions." +policy: + allow_implicit_invocation: true \ No newline at end of file diff --git a/.claude/commands/add-new-autograd-op.md b/.claude/commands/add-new-autograd-op.md new file mode 100644 index 0000000..991f4cb --- /dev/null +++ b/.claude/commands/add-new-autograd-op.md @@ -0,0 +1,41 @@ +--- +name: add-new-autograd-op +description: Workflow command scaffold for add-new-autograd-op in grilly. +allowed_tools: ["Bash", "Read", "Write", "Grep", "Glob"] +--- + +# /add-new-autograd-op + +Use this workflow when working on **add-new-autograd-op** in `grilly`. + +## Goal + +Implements a new autograd operation (forward/backward) or wires an existing shader into the autograd engine, including Python bindings and tests. + +## Common Files + +- `cpp/include/grilly/autograd/autograd.h` +- `cpp/src/autograd.cpp` +- `cpp/python/bindings_autograd.cpp` +- `shaders/*.glsl` +- `shaders/spv/*.spv` +- `test_*.py` + +## Suggested Sequence + +1. Understand the current state and failure mode before editing. +2. Make the smallest coherent change that satisfies the workflow goal. +3. Run the most relevant verification for touched files. +4. Summarize what changed and what still needs review. + +## Typical Commit Signals + +- Implement or add new GLSL shader(s) for the operation if needed (e.g., shaders/rms-norm-backward.glsl, shaders/spv/rms-norm-backward.spv) +- Update C++ autograd headers and source to add the handler (cpp/include/grilly/autograd/autograd.h, cpp/src/autograd.cpp) +- Wire the operation into Python bindings (cpp/python/bindings_autograd.cpp) +- Add or update a test for the new op (e.g., test_backward_rmsnorm.py, test_backward_swiglu.py, etc.) + +## Notes + +- Treat this as a scaffold, not a hard-coded script. +- Update the command if the workflow evolves materially. \ No newline at end of file diff --git a/.claude/commands/feature-development.md b/.claude/commands/feature-development.md new file mode 100644 index 0000000..75c0c9a --- /dev/null +++ b/.claude/commands/feature-development.md @@ -0,0 +1,35 @@ +--- +name: feature-development +description: Workflow command scaffold for feature-development in grilly. +allowed_tools: ["Bash", "Read", "Write", "Grep", "Glob"] +--- + +# /feature-development + +Use this workflow when working on **feature-development** in `grilly`. + +## Goal + +Standard feature implementation workflow + +## Common Files + +- `**/*.test.*` + +## Suggested Sequence + +1. Understand the current state and failure mode before editing. +2. Make the smallest coherent change that satisfies the workflow goal. +3. Run the most relevant verification for touched files. +4. Summarize what changed and what still needs review. + +## Typical Commit Signals + +- Add feature implementation +- Add tests for feature +- Update documentation + +## Notes + +- Treat this as a scaffold, not a hard-coded script. +- Update the command if the workflow evolves materially. \ No newline at end of file diff --git a/.claude/commands/test-driven-development.md b/.claude/commands/test-driven-development.md new file mode 100644 index 0000000..fdeacc3 --- /dev/null +++ b/.claude/commands/test-driven-development.md @@ -0,0 +1,37 @@ +--- +name: test-driven-development +description: Workflow command scaffold for test-driven-development in grilly. +allowed_tools: ["Bash", "Read", "Write", "Grep", "Glob"] +--- + +# /test-driven-development + +Use this workflow when working on **test-driven-development** in `grilly`. + +## Goal + +Test-first development workflow (TDD) + +## Common Files + +- `**/*.test.*` +- `**/*.spec.*` +- `src/**/*` + +## Suggested Sequence + +1. Understand the current state and failure mode before editing. +2. Make the smallest coherent change that satisfies the workflow goal. +3. Run the most relevant verification for touched files. +4. Summarize what changed and what still needs review. + +## Typical Commit Signals + +- Write failing test +- Implement code to pass test +- Refactor if needed + +## Notes + +- Treat this as a scaffold, not a hard-coded script. +- Update the command if the workflow evolves materially. \ No newline at end of file diff --git a/.claude/ecc-tools.json b/.claude/ecc-tools.json new file mode 100644 index 0000000..468f8d5 --- /dev/null +++ b/.claude/ecc-tools.json @@ -0,0 +1,296 @@ +{ + "version": "1.3", + "schemaVersion": "1.0", + "generatedBy": "ecc-tools", + "generatedAt": "2026-06-17T22:01:32.554Z", + "repo": "https://github.com/Grillcheese-AI/grilly", + "referenceSetReadiness": { + "score": 0, + "present": 0, + "total": 7, + "items": [ + { + "id": "deep-analyzer-corpus", + "label": "Deep analyzer corpus", + "status": "missing", + "evidence": [], + "recommendation": "Add analyzer fixture, golden, benchmark, or reference-set files that can catch analyzer regressions." + }, + { + "id": "rag-evaluator", + "label": "RAG/evaluator comparison", + "status": "missing", + "evidence": [], + "recommendation": "Add retrieval or evaluator reference-set comparison fixtures with expected ranking behavior." + }, + { + "id": "pr-salvage", + "label": "PR salvage/review corpus", + "status": "missing", + "evidence": [], + "recommendation": "Add stale-PR, review-thread, reopen-flow, or salvage reference cases for queue cleanup automation." + }, + { + "id": "discussion-triage", + "label": "Discussion triage corpus", + "status": "missing", + "evidence": [], + "recommendation": "Add public discussion triage fixtures, golden cases, or reference sets for informational, answered, and no-response classifications." + }, + { + "id": "harness-compatibility", + "label": "Harness compatibility", + "status": "missing", + "evidence": [], + "recommendation": "Add cross-harness, adapter-compliance, or harness-audit evidence for Claude, Codex, OpenCode, Zed, dmux, and agent surfaces." + }, + { + "id": "security-evidence", + "label": "Security evidence", + "status": "missing", + "evidence": [], + "recommendation": "Attach security evidence such as SBOMs, SARIF, audit reports, or AgentShield evidence packs." + }, + { + "id": "ci-failure-mode", + "label": "CI failure-mode evidence", + "status": "missing", + "evidence": [], + "recommendation": "Add captured CI failure logs, dry-run fixtures, or troubleshooting docs for common workflow failure modes." + } + ] + }, + "profiles": { + "requested": "research", + "recommended": "research", + "effective": "developer", + "requestedAlias": "research", + "recommendedAlias": "research", + "effectiveAlias": "developer" + }, + "requestedProfile": "research", + "profile": "developer", + "recommendedProfile": "research", + "effectiveProfile": "developer", + "tier": "free", + "requestedComponents": [ + "repo-baseline", + "workflow-automation", + "research-tooling" + ], + "selectedComponents": [ + "repo-baseline", + "workflow-automation" + ], + "requestedAddComponents": [], + "requestedRemoveComponents": [], + "blockedRemovalComponents": [], + "tierFilteredComponents": [ + "research-tooling" + ], + "requestedRootPackages": [ + "runtime-core", + "workflow-pack", + "research-pack" + ], + "selectedRootPackages": [ + "runtime-core", + "workflow-pack" + ], + "requestedPackages": [ + "runtime-core", + "workflow-pack", + "research-pack" + ], + "requestedAddPackages": [], + "requestedRemovePackages": [], + "selectedPackages": [ + "runtime-core", + "workflow-pack" + ], + "packages": [ + "runtime-core", + "workflow-pack" + ], + "blockedRemovalPackages": [], + "tierFilteredRootPackages": [ + "research-pack" + ], + "tierFilteredPackages": [ + "research-pack" + ], + "conflictingPackages": [], + "dependencyGraph": { + "runtime-core": [], + "workflow-pack": [ + "runtime-core" + ] + }, + "resolutionOrder": [ + "runtime-core", + "workflow-pack" + ], + "requestedModules": [ + "runtime-core", + "workflow-pack", + "research-pack" + ], + "selectedModules": [ + "runtime-core", + "workflow-pack" + ], + "modules": [ + "runtime-core", + "workflow-pack" + ], + "managedFiles": [ + ".claude/skills/grilly/SKILL.md", + ".agents/skills/grilly/SKILL.md", + ".agents/skills/grilly/agents/openai.yaml", + ".claude/identity.json", + ".codex/config.toml", + ".codex/AGENTS.md", + ".codex/agents/explorer.toml", + ".codex/agents/reviewer.toml", + ".codex/agents/docs-researcher.toml", + ".claude/homunculus/instincts/inherited/grilly-instincts.yaml", + ".claude/commands/feature-development.md", + ".claude/commands/test-driven-development.md", + ".claude/commands/add-new-autograd-op.md" + ], + "packageFiles": { + "runtime-core": [ + ".claude/skills/grilly/SKILL.md", + ".agents/skills/grilly/SKILL.md", + ".agents/skills/grilly/agents/openai.yaml", + ".claude/identity.json", + ".codex/config.toml", + ".codex/AGENTS.md", + ".codex/agents/explorer.toml", + ".codex/agents/reviewer.toml", + ".codex/agents/docs-researcher.toml", + ".claude/homunculus/instincts/inherited/grilly-instincts.yaml" + ], + "workflow-pack": [ + ".claude/commands/feature-development.md", + ".claude/commands/test-driven-development.md", + ".claude/commands/add-new-autograd-op.md" + ] + }, + "moduleFiles": { + "runtime-core": [ + ".claude/skills/grilly/SKILL.md", + ".agents/skills/grilly/SKILL.md", + ".agents/skills/grilly/agents/openai.yaml", + ".claude/identity.json", + ".codex/config.toml", + ".codex/AGENTS.md", + ".codex/agents/explorer.toml", + ".codex/agents/reviewer.toml", + ".codex/agents/docs-researcher.toml", + ".claude/homunculus/instincts/inherited/grilly-instincts.yaml" + ], + "workflow-pack": [ + ".claude/commands/feature-development.md", + ".claude/commands/test-driven-development.md", + ".claude/commands/add-new-autograd-op.md" + ] + }, + "files": [ + { + "moduleId": "runtime-core", + "path": ".claude/skills/grilly/SKILL.md", + "description": "Repository-specific Claude Code skill generated from git history." + }, + { + "moduleId": "runtime-core", + "path": ".agents/skills/grilly/SKILL.md", + "description": "Codex-facing copy of the generated repository skill." + }, + { + "moduleId": "runtime-core", + "path": ".agents/skills/grilly/agents/openai.yaml", + "description": "Codex skill metadata so the repo skill appears cleanly in the skill interface." + }, + { + "moduleId": "runtime-core", + "path": ".claude/identity.json", + "description": "Suggested identity.json baseline derived from repository conventions." + }, + { + "moduleId": "runtime-core", + "path": ".codex/config.toml", + "description": "Repo-local Codex MCP and multi-agent baseline aligned with ECC defaults." + }, + { + "moduleId": "runtime-core", + "path": ".codex/AGENTS.md", + "description": "Codex usage guide that points at the generated repo skill and workflow bundle." + }, + { + "moduleId": "runtime-core", + "path": ".codex/agents/explorer.toml", + "description": "Read-only explorer role config for Codex multi-agent work." + }, + { + "moduleId": "runtime-core", + "path": ".codex/agents/reviewer.toml", + "description": "Read-only reviewer role config focused on correctness and security." + }, + { + "moduleId": "runtime-core", + "path": ".codex/agents/docs-researcher.toml", + "description": "Read-only docs researcher role config for API verification." + }, + { + "moduleId": "runtime-core", + "path": ".claude/homunculus/instincts/inherited/grilly-instincts.yaml", + "description": "Continuous-learning instincts derived from repository patterns." + }, + { + "moduleId": "workflow-pack", + "path": ".claude/commands/feature-development.md", + "description": "Workflow command scaffold for feature-development." + }, + { + "moduleId": "workflow-pack", + "path": ".claude/commands/test-driven-development.md", + "description": "Workflow command scaffold for test-driven-development." + }, + { + "moduleId": "workflow-pack", + "path": ".claude/commands/add-new-autograd-op.md", + "description": "Workflow command scaffold for add-new-autograd-op." + } + ], + "workflows": [ + { + "command": "feature-development", + "path": ".claude/commands/feature-development.md" + }, + { + "command": "test-driven-development", + "path": ".claude/commands/test-driven-development.md" + }, + { + "command": "add-new-autograd-op", + "path": ".claude/commands/add-new-autograd-op.md" + } + ], + "adapters": { + "claudeCode": { + "skillPath": ".claude/skills/grilly/SKILL.md", + "identityPath": ".claude/identity.json", + "commandPaths": [ + ".claude/commands/feature-development.md", + ".claude/commands/test-driven-development.md", + ".claude/commands/add-new-autograd-op.md" + ] + }, + "codex": { + "configPath": ".codex/config.toml", + "agentsGuidePath": ".codex/AGENTS.md", + "skillPath": ".agents/skills/grilly/SKILL.md" + } + } +} \ No newline at end of file diff --git a/.claude/homunculus/instincts/inherited/grilly-instincts.yaml b/.claude/homunculus/instincts/inherited/grilly-instincts.yaml new file mode 100644 index 0000000..216f191 --- /dev/null +++ b/.claude/homunculus/instincts/inherited/grilly-instincts.yaml @@ -0,0 +1,648 @@ +# Instincts generated from https://github.com/Grillcheese-AI/grilly +# Generated: 2026-06-17T22:02:17.009Z +# Version: 2.0 +# NOTE: This file supplements (does not replace) any existing curated instincts. +# High-confidence manually curated instincts should be preserved alongside these. + +--- +id: grilly-commit-length +trigger: "when writing a commit message" +confidence: 0.6 +domain: git +source: repo-analysis +source_repo: https://github.com/Grillcheese-AI/grilly +--- + +# Grilly Commit Length + +## Action + +Write moderate-length commit messages (~69 characters) + +## Evidence + +- Average commit message length: 69 chars +- Based on 56 commits + +--- +id: grilly-naming-files +trigger: "when creating a new file" +confidence: 0.8 +domain: code-style +source: repo-analysis +source_repo: https://github.com/Grillcheese-AI/grilly +--- + +# Grilly Naming Files + +## Action + +Use snake_case naming convention + +## Evidence + +- Analyzed file naming patterns in repository +- Dominant pattern: snake_case + +--- +id: grilly-import-relative +trigger: "when importing modules" +confidence: 0.75 +domain: code-style +source: repo-analysis +source_repo: https://github.com/Grillcheese-AI/grilly +--- + +# Grilly Import Relative + +## Action + +Use relative imports for project files + +## Evidence + +- Import analysis shows relative import pattern +- Example: import { x } from '../lib/x' + +--- +id: grilly-export-style +trigger: "when exporting from a module" +confidence: 0.7 +domain: code-style +source: repo-analysis +source_repo: https://github.com/Grillcheese-AI/grilly +--- + +# Grilly Export Style + +## Action + +Prefer named exports + +## Evidence + +- Export pattern analysis +- Dominant style: named + +--- +id: grilly-test-separate +trigger: "when writing tests" +confidence: 0.8 +domain: testing +source: repo-analysis +source_repo: https://github.com/Grillcheese-AI/grilly +--- + +# Grilly Test Separate + +## Action + +Place tests in the tests/ or __tests__/ directory, mirroring src structure + +## Evidence + +- Separate test directory pattern detected +- Tests live in dedicated test folders + +--- +id: grilly-test-naming +trigger: "when creating a test file" +confidence: 0.85 +domain: testing +source: repo-analysis +source_repo: https://github.com/Grillcheese-AI/grilly +--- + +# Grilly Test Naming + +## Action + +Name test files using the pattern: *.test.ts + +## Evidence + +- File pattern: *.test.ts +- Consistent across test files + +--- +id: grilly-workflow-feature-development +trigger: "when implementing a new feature" +confidence: 0.9 +domain: workflow +source: repo-analysis +source_repo: https://github.com/Grillcheese-AI/grilly +--- + +# Grilly Workflow Feature Development + +## Action + +Follow the feature-development workflow: +1. Add feature implementation +2. Add tests for feature +3. Update documentation + +## Evidence + +- Workflow detected from commit patterns +- Frequency: ~10x per month +- Files: **/*.test.* + +--- +id: grilly-workflow-test-driven-development +trigger: "when adding new functionality" +confidence: 0.75 +domain: workflow +source: repo-analysis +source_repo: https://github.com/Grillcheese-AI/grilly +--- + +# Grilly Workflow Test Driven Development + +## Action + +Follow the test-driven-development workflow: +1. Write failing test +2. Implement code to pass test +3. Refactor if needed + +## Evidence + +- Workflow detected from commit patterns +- Frequency: ~5x per month +- Files: **/*.test.*, **/*.spec.*, src/**/* + +--- +id: grilly-workflow-add-new-autograd-op +trigger: "when doing add new autograd op" +confidence: 0.75 +domain: workflow +source: repo-analysis +source_repo: https://github.com/Grillcheese-AI/grilly +--- + +# Grilly Workflow Add New Autograd Op + +## Action + +Follow the add-new-autograd-op workflow: +1. Implement or add new GLSL shader(s) for the operation if needed (e.g., shaders/rms-norm-backward.glsl, shaders/spv/rms-norm-backward.spv) +2. Update C++ autograd headers and source to add the handler (cpp/include/grilly/autograd/autograd.h, cpp/src/autograd.cpp) +3. Wire the operation into Python bindings (cpp/python/bindings_autograd.cpp) +4. Add or update a test for the new op (e.g., test_backward_rmsnorm.py, test_backward_swiglu.py, etc.) + +## Evidence + +- Workflow detected from commit patterns +- Frequency: ~5x per month +- Files: cpp/include/grilly/autograd/autograd.h, cpp/src/autograd.cpp, cpp/python/bindings_autograd.cpp + +--- +id: grilly-workflow-document-autograd-state-or-milestone +trigger: "when doing document autograd state or milestone" +confidence: 0.9 +domain: workflow +source: repo-analysis +source_repo: https://github.com/Grillcheese-AI/grilly +--- + +# Grilly Workflow Document Autograd State Or Milestone + +## Action + +Follow the document-autograd-state-or-milestone workflow: +1. Edit AUTOGRAD_STATE.md to describe new features, bugfixes, or integration steps. +2. Commit AUTOGRAD_STATE.md (sometimes with TODO.md or related docs). + +## Evidence + +- Workflow detected from commit patterns +- Frequency: ~8x per month +- Files: AUTOGRAD_STATE.md, TODO.md + +--- +id: grilly-workflow-integration-test-or-training-script-addition +trigger: "when doing integration test or training script addition" +confidence: 0.75 +domain: workflow +source: repo-analysis +source_repo: https://github.com/Grillcheese-AI/grilly +--- + +# Grilly Workflow Integration Test Or Training Script Addition + +## Action + +Follow the integration-test-or-training-script-addition workflow: +1. Add or update a script in experimental/resident_train/ (e.g., train_linear_ce.py, train_mingru_ce.py, train_full.py, train_trunk_lm.py, bisect_block.py, etc.) +2. Run the script to verify integration. +3. Optionally update documentation with results. + +## Evidence + +- Workflow detected from commit patterns +- Frequency: ~5x per month +- Files: experimental/resident_train/*.py + +--- +id: grilly-workflow-add-or-update-python-cpp-binding +trigger: "when doing add or update python cpp binding" +confidence: 0.65 +domain: workflow +source: repo-analysis +source_repo: https://github.com/Grillcheese-AI/grilly +--- + +# Grilly Workflow Add Or Update Python Cpp Binding + +## Action + +Follow the add-or-update-python-cpp-binding workflow: +1. Implement or update binding in cpp/python/ (e.g., bindings_autograd.cpp, bindings_core.cpp, bindings_core.h) +2. Update CMakeLists.txt if new binding files are added. +3. Optionally add a Python test or usage example. + +## Evidence + +- Workflow detected from commit patterns +- Frequency: ~3x per month +- Files: cpp/python/*.cpp, cpp/python/*.h, CMakeLists.txt + +--- +id: grilly-workflow-add-or-update-shader-and-spirv +trigger: "when doing add or update shader and spirv" +confidence: 0.65 +domain: workflow +source: repo-analysis +source_repo: https://github.com/Grillcheese-AI/grilly +--- + +# Grilly Workflow Add Or Update Shader And Spirv + +## Action + +Follow the add-or-update-shader-and-spirv workflow: +1. Write or modify a GLSL shader in shaders/*.glsl. +2. Compile to SPIR-V and add/update shaders/spv/*.spv. +3. Wire up usage in C++ and/or Python if needed. + +## Evidence + +- Workflow detected from commit patterns +- Frequency: ~3x per month +- Files: shaders/*.glsl, shaders/spv/*.spv + +--- +id: grilly-workflow-add-or-update-todo-or-workboard +trigger: "when doing add or update todo or workboard" +confidence: 0.7 +domain: workflow +source: repo-analysis +source_repo: https://github.com/Grillcheese-AI/grilly +--- + +# Grilly Workflow Add Or Update Todo Or Workboard + +## Action + +Follow the add-or-update-todo-or-workboard workflow: +1. Edit TODO.md to add, update, or mark tasks as done. +2. Commit TODO.md. + +## Evidence + +- Workflow detected from commit patterns +- Frequency: ~4x per month +- Files: TODO.md + +--- +id: grilly-coding-file-naming-snake-case +trigger: "When creating a new file" +confidence: 0.9 +domain: code-style +source: repo-analysis +source_repo: Grillcheese-AI/grilly +--- + +# Grilly Coding File Naming Snake Case + +## Action + +Name the file using snake_case + +## Evidence + +- Pattern: files use snake_case naming convention + +--- +id: grilly-coding-function-naming-camelCase +trigger: "When defining a new function" +confidence: 0.9 +domain: code-style +source: repo-analysis +source_repo: Grillcheese-AI/grilly +--- + +# Grilly Coding Function Naming CamelCase + +## Action + +Name the function using camelCase + +## Evidence + +- Pattern: functions use camelCase naming convention + +--- +id: grilly-coding-class-naming-pascal-case +trigger: "When defining a new class" +confidence: 0.9 +domain: code-style +source: repo-analysis +source_repo: Grillcheese-AI/grilly +--- + +# Grilly Coding Class Naming Pascal Case + +## Action + +Name the class using PascalCase + +## Evidence + +- Pattern: classes use PascalCase naming convention + +--- +id: grilly-coding-constant-naming-screaming-snake-case +trigger: "When defining a constant" +confidence: 0.9 +domain: code-style +source: repo-analysis +source_repo: Grillcheese-AI/grilly +--- + +# Grilly Coding Constant Naming Screaming Snake Case + +## Action + +Name the constant using SCREAMING_SNAKE_CASE + +## Evidence + +- Pattern: constants use SCREAMING_SNAKE_CASE naming convention + +--- +id: grilly-coding-import-relative +trigger: "When importing modules in Python" +confidence: 0.8 +domain: code-style +source: repo-analysis +source_repo: Grillcheese-AI/grilly +--- + +# Grilly Coding Import Relative + +## Action + +Use relative imports + +## Evidence + +- Pattern: importStyle is relative + +--- +id: grilly-coding-export-named +trigger: "When exporting modules or functions" +confidence: 0.8 +domain: code-style +source: repo-analysis +source_repo: Grillcheese-AI/grilly +--- + +# Grilly Coding Export Named + +## Action + +Use named exports + +## Evidence + +- Pattern: exportStyle is named + +--- +id: grilly-testing-file-pattern +trigger: "When creating a new test file" +confidence: 0.8 +domain: testing +source: repo-analysis +source_repo: Grillcheese-AI/grilly +--- + +# Grilly Testing File Pattern + +## Action + +Name the test file with the pattern *.test.ts + +## Evidence + +- Pattern: test files named *.test.ts + +--- +id: grilly-testing-unit-tests +trigger: "When adding tests" +confidence: 0.8 +domain: testing +source: repo-analysis +source_repo: Grillcheese-AI/grilly +--- + +# Grilly Testing Unit Tests + +## Action + +Write unit tests for new features + +## Evidence + +- Pattern: testTypes includes unit + +--- +id: grilly-testing-tdd-workflow +trigger: "When developing a new feature using TDD" +confidence: 0.8 +domain: testing +source: repo-analysis +source_repo: Grillcheese-AI/grilly +--- + +# Grilly Testing Tdd Workflow + +## Action + +First write a failing test, then implement code to pass the test, then refactor if needed + +## Evidence + +- Workflow: test-driven-development +- Example commits: 'test: add tests for user validation', 'feat: implement user validation' + +--- +id: grilly-git-commit-prefixes +trigger: "When writing a commit message" +confidence: 0.9 +domain: git +source: repo-analysis +source_repo: Grillcheese-AI/grilly +--- + +# Grilly Git Commit Prefixes + +## Action + +Prefix the commit with a category such as autograd, docs, integration, or todo + +## Evidence + +- Pattern: commit prefixes +- Examples: 'autograd: ...', 'docs: ...', 'integration: ...', 'TODO: ...' + +--- +id: grilly-git-commit-length +trigger: "When writing a commit message" +confidence: 0.7 +domain: git +source: repo-analysis +source_repo: Grillcheese-AI/grilly +--- + +# Grilly Git Commit Length + +## Action + +Keep the commit message concise, around 69 characters on average + +## Evidence + +- Pattern: average commit length is 69 + +--- +id: grilly-workflow-add-new-autograd-op +trigger: "When adding support for a new operation to the autograd engine" +confidence: 0.9 +domain: workflow +source: repo-analysis +source_repo: Grillcheese-AI/grilly +--- + +# Grilly Workflow Add New Autograd Op + +## Action + +Implement GLSL shader(s) if needed, update C++ autograd headers and source, wire into Python bindings, and add/update a test for the new op + +## Evidence + +- Workflow: add-new-autograd-op +- Example files: shaders/*.glsl, cpp/include/grilly/autograd/autograd.h, cpp/python/bindings_autograd.cpp, test_*.py + +--- +id: grilly-workflow-document-autograd-state-or-milestone +trigger: "When completing a significant feature, bugfix, or integration step" +confidence: 0.9 +domain: workflow +source: repo-analysis +source_repo: Grillcheese-AI/grilly +--- + +# Grilly Workflow Document Autograd State Or Milestone + +## Action + +Edit AUTOGRAD_STATE.md to describe the change and commit it (optionally with TODO.md) + +## Evidence + +- Workflow: document-autograd-state-or-milestone +- Example files: AUTOGRAD_STATE.md, TODO.md + +--- +id: grilly-workflow-integration-test-or-training-script-addition +trigger: "When verifying a new feature or workflow in a real training or integration scenario" +confidence: 0.9 +domain: workflow +source: repo-analysis +source_repo: Grillcheese-AI/grilly +--- + +# Grilly Workflow Integration Test Or Training Script Addition + +## Action + +Add or update a script in experimental/resident_train/, run it to verify integration, and optionally update documentation with results + +## Evidence + +- Workflow: integration-test-or-training-script-addition +- Example files: experimental/resident_train/*.py + +--- +id: grilly-workflow-add-or-update-python-cpp-binding +trigger: "When adding a new C++ feature that needs to be exposed to Python" +confidence: 0.85 +domain: workflow +source: repo-analysis +source_repo: Grillcheese-AI/grilly +--- + +# Grilly Workflow Add Or Update Python Cpp Binding + +## Action + +Implement or update binding in cpp/python/, update CMakeLists.txt if new files are added, and optionally add a Python test or usage example + +## Evidence + +- Workflow: add-or-update-python-cpp-binding +- Example files: cpp/python/*.cpp, cpp/python/*.h, CMakeLists.txt + +--- +id: grilly-workflow-add-or-update-shader-and-spirv +trigger: "When implementing or updating a GPU operation" +confidence: 0.9 +domain: workflow +source: repo-analysis +source_repo: Grillcheese-AI/grilly +--- + +# Grilly Workflow Add Or Update Shader And Spirv + +## Action + +Write or modify a GLSL shader in shaders/*.glsl, compile to SPIR-V and add/update shaders/spv/*.spv, and wire up usage in C++/Python if needed + +## Evidence + +- Workflow: add-or-update-shader-and-spirv +- Example files: shaders/*.glsl, shaders/spv/*.spv + +--- +id: grilly-workflow-add-or-update-todo-or-workboard +trigger: "When recording new tasks, marking tasks as done, or updating project planning" +confidence: 0.85 +domain: workflow +source: repo-analysis +source_repo: Grillcheese-AI/grilly +--- + +# Grilly Workflow Add Or Update Todo Or Workboard + +## Action + +Edit TODO.md to add, update, or mark tasks as done, then commit TODO.md + +## Evidence + +- Workflow: add-or-update-todo-or-workboard +- Example files: TODO.md + diff --git a/.claude/identity.json b/.claude/identity.json new file mode 100644 index 0000000..5ed5b33 --- /dev/null +++ b/.claude/identity.json @@ -0,0 +1,14 @@ +{ + "version": "2.0", + "technicalLevel": "technical", + "preferredStyle": { + "verbosity": "minimal", + "codeComments": true, + "explanations": true + }, + "domains": [ + "python" + ], + "suggestedBy": "ecc-tools-repo-analysis", + "createdAt": "2026-06-17T22:02:17.009Z" +} \ No newline at end of file diff --git a/.claude/skills/grilly/SKILL.md b/.claude/skills/grilly/SKILL.md new file mode 100644 index 0000000..0489160 --- /dev/null +++ b/.claude/skills/grilly/SKILL.md @@ -0,0 +1,141 @@ +```markdown +# grilly Development Patterns + +> Auto-generated skill from repository analysis + +## Overview +This skill teaches the core development patterns, coding conventions, and common workflows used in the `grilly` codebase. `grilly` is a Python-centric project (with C++ and shader components) focused on autograd operations, GPU acceleration, and integration between Python and C++. The repository emphasizes modularity, clear commit practices, and a workflow-driven approach to adding features and documenting progress. + +## Coding Conventions + +- **File Naming:** + Use `snake_case` for all Python and script files. + *Example:* + ``` + test_backward_rmsnorm.py + train_linear_ce.py + ``` + +- **Import Style:** + Prefer **relative imports** within Python modules. + *Example:* + ```python + from .core import Tensor + from .autograd import backward_rmsnorm + ``` + +- **Export Style:** + Use **named exports** for functions and classes. + *Example:* + ```python + def backward_rmsnorm(...): + ... + ``` + +- **Commit Messages:** + - Freeform, but often start with prefixes like `autograd`, `docs`, `integration`, `todo`. + - Average commit message length: ~69 characters. + +## Workflows + +### Add New Autograd Operation +**Trigger:** When adding support for a new operation to the autograd engine (e.g., `backward_rmsnorm`, `forward_linear`). +**Command:** `/new-autograd-op` + +1. Implement or add new GLSL shader(s) for the operation if needed. + *Example:* `shaders/rms-norm-backward.glsl` +2. Compile GLSL to SPIR-V if required. + *Example:* `shaders/spv/rms-norm-backward.spv` +3. Update C++ autograd headers and source to add the handler. + - `cpp/include/grilly/autograd/autograd.h` + - `cpp/src/autograd.cpp` +4. Wire the operation into Python bindings. + - `cpp/python/bindings_autograd.cpp` +5. Add or update a test for the new op. + *Example:* `test_backward_rmsnorm.py` + +--- + +### Document Autograd State or Milestone +**Trigger:** When completing a significant feature, bugfix, or integration step and wanting to record the project state. +**Command:** `/update-state-doc` + +1. Edit `AUTOGRAD_STATE.md` to describe new features, bugfixes, or integration steps. +2. Optionally update `TODO.md` or related docs. +3. Commit the documentation. + +--- + +### Integration Test or Training Script Addition +**Trigger:** When verifying that a new feature or workflow works in a real training or integration scenario. +**Command:** `/add-integration-test` + +1. Add or update a script in `experimental/resident_train/`. + *Example:* `train_linear_ce.py` +2. Run the script to verify integration. +3. Optionally update documentation with results. + +--- + +### Add or Update Python-C++ Binding +**Trigger:** When adding a new C++ feature that needs to be exposed to Python. +**Command:** `/add-python-binding` + +1. Implement or update binding in `cpp/python/`. + *Example:* `bindings_autograd.cpp`, `bindings_core.cpp` +2. Update `CMakeLists.txt` if new binding files are added. +3. Optionally add a Python test or usage example. + +--- + +### Add or Update Shader and SPIR-V +**Trigger:** When implementing a new GPU operation or updating an existing one. +**Command:** `/add-shader` + +1. Write or modify a GLSL shader in `shaders/*.glsl`. +2. Compile to SPIR-V and add/update `shaders/spv/*.spv`. +3. Wire up usage in C++ and/or Python if needed. + +--- + +### Add or Update TODO or Workboard +**Trigger:** When recording new tasks, marking tasks as done, or updating project planning. +**Command:** `/update-todo` + +1. Edit `TODO.md` to add, update, or mark tasks as done. +2. Commit `TODO.md`. + +--- + +## Testing Patterns + +- **Framework:** Unknown (no standard Python test framework detected). +- **File Pattern:** Python test files use the pattern `test_*.py`. +- **Integration Tests:** Often placed in `experimental/resident_train/`. +- **Other Patterns:** Some references to `*.test.ts` (TypeScript), but main tests appear to be Python scripts. + +*Example test file:* +```python +# test_backward_rmsnorm.py +from .autograd import backward_rmsnorm + +def test_backward_rmsnorm_basic(): + # Setup input tensors + ... + # Call the function + result = backward_rmsnorm(...) + # Assert correctness + assert ... +``` + +## Commands + +| Command | Purpose | +|----------------------|----------------------------------------------------------------| +| /new-autograd-op | Add a new autograd operation (forward/backward) | +| /update-state-doc | Update project state documentation (AUTOGRAD_STATE.md, TODO.md)| +| /add-integration-test| Add or update an integration test or training script | +| /add-python-binding | Add or update Python-C++ bindings | +| /add-shader | Add or update a GLSL shader and its SPIR-V binary | +| /update-todo | Update TODO.md or project workboard | +``` diff --git a/.codex/AGENTS.md b/.codex/AGENTS.md new file mode 100644 index 0000000..0925852 --- /dev/null +++ b/.codex/AGENTS.md @@ -0,0 +1,28 @@ +# ECC for Codex CLI + +This supplements the root `AGENTS.md` with a repo-local ECC baseline. + +## Repo Skill + +- Repo-generated Codex skill: `.agents/skills/grilly/SKILL.md` +- Claude-facing companion skill: `.claude/skills/grilly/SKILL.md` +- Keep user-specific credentials and private MCPs in `~/.codex/config.toml`, not in this repo. + +## MCP Baseline + +Treat `.codex/config.toml` as the default ECC-safe baseline for work in this repository. +The generated baseline enables GitHub, Context7, Exa, Memory, Playwright, and Sequential Thinking. + +## Multi-Agent Support + +- Explorer: read-only evidence gathering +- Reviewer: correctness, security, and regression review +- Docs researcher: API and release-note verification + +## Workflow Files + +- `.claude/commands/feature-development.md` +- `.claude/commands/test-driven-development.md` +- `.claude/commands/add-new-autograd-op.md` + +Use these workflow files as reusable task scaffolds when the detected repository workflows recur. \ No newline at end of file diff --git a/.codex/agents/docs-researcher.toml b/.codex/agents/docs-researcher.toml new file mode 100644 index 0000000..0daae57 --- /dev/null +++ b/.codex/agents/docs-researcher.toml @@ -0,0 +1,9 @@ +model = "gpt-5.4" +model_reasoning_effort = "medium" +sandbox_mode = "read-only" + +developer_instructions = """ +Verify APIs, framework behavior, and release-note claims against primary documentation before changes land. +Cite the exact docs or file paths that support each claim. +Do not invent undocumented behavior. +""" \ No newline at end of file diff --git a/.codex/agents/explorer.toml b/.codex/agents/explorer.toml new file mode 100644 index 0000000..732df7a --- /dev/null +++ b/.codex/agents/explorer.toml @@ -0,0 +1,9 @@ +model = "gpt-5.4" +model_reasoning_effort = "medium" +sandbox_mode = "read-only" + +developer_instructions = """ +Stay in exploration mode. +Trace the real execution path, cite files and symbols, and avoid proposing fixes unless the parent agent asks for them. +Prefer targeted search and file reads over broad scans. +""" \ No newline at end of file diff --git a/.codex/agents/reviewer.toml b/.codex/agents/reviewer.toml new file mode 100644 index 0000000..b13ed9c --- /dev/null +++ b/.codex/agents/reviewer.toml @@ -0,0 +1,9 @@ +model = "gpt-5.4" +model_reasoning_effort = "high" +sandbox_mode = "read-only" + +developer_instructions = """ +Review like an owner. +Prioritize correctness, security, behavioral regressions, and missing tests. +Lead with concrete findings and avoid style-only feedback unless it hides a real bug. +""" \ No newline at end of file diff --git a/.codex/config.toml b/.codex/config.toml new file mode 100644 index 0000000..bc1ee67 --- /dev/null +++ b/.codex/config.toml @@ -0,0 +1,48 @@ +#:schema https://developers.openai.com/codex/config-schema.json + +# ECC Tools generated Codex baseline +approval_policy = "on-request" +sandbox_mode = "workspace-write" +web_search = "live" + +[mcp_servers.github] +command = "npx" +args = ["-y", "@modelcontextprotocol/server-github"] + +[mcp_servers.context7] +command = "npx" +args = ["-y", "@upstash/context7-mcp@latest"] + +[mcp_servers.exa] +url = "https://mcp.exa.ai/mcp" + +[mcp_servers.memory] +command = "npx" +args = ["-y", "@modelcontextprotocol/server-memory"] + +[mcp_servers.playwright] +command = "npx" +args = ["-y", "@playwright/mcp@latest", "--extension"] + +[mcp_servers.sequential-thinking] +command = "npx" +args = ["-y", "@modelcontextprotocol/server-sequential-thinking"] + +[features] +multi_agent = true + +[agents] +max_threads = 6 +max_depth = 1 + +[agents.explorer] +description = "Read-only codebase explorer for gathering evidence before changes are proposed." +config_file = "agents/explorer.toml" + +[agents.reviewer] +description = "PR reviewer focused on correctness, security, and missing tests." +config_file = "agents/reviewer.toml" + +[agents.docs_researcher] +description = "Documentation specialist that verifies APIs, framework behavior, and release notes." +config_file = "agents/docs-researcher.toml" \ No newline at end of file