From 1878f807a6118486341994b64fe3adda5f9abe60 Mon Sep 17 00:00:00 2001 From: Ben Zwick Date: Fri, 30 Jan 2026 10:29:42 +0000 Subject: [PATCH] Add Claude Code skills and CLAUDE.md Add configuration for Claude Code AI assistant: - CLAUDE.md with repository overview, contribution workflow, and commit conventions - Skills for creating and updating Project Week project pages - Agent for exploring past projects --- .claude/agents/project-week-explorer.md | 35 +++++++ .claude/skills/create-project/SKILL.md | 98 ++++++++++++++++++++ .claude/skills/update-claude-md/SKILL.md | 66 ++++++++++++++ .claude/skills/update-project/SKILL.md | 94 +++++++++++++++++++ CLAUDE.md | 111 +++++++++++++++++++++++ 5 files changed, 404 insertions(+) create mode 100644 .claude/agents/project-week-explorer.md create mode 100644 .claude/skills/create-project/SKILL.md create mode 100644 .claude/skills/update-claude-md/SKILL.md create mode 100644 .claude/skills/update-project/SKILL.md create mode 100644 CLAUDE.md diff --git a/.claude/agents/project-week-explorer.md b/.claude/agents/project-week-explorer.md new file mode 100644 index 000000000..088ef835f --- /dev/null +++ b/.claude/agents/project-week-explorer.md @@ -0,0 +1,35 @@ +# Project Week Explorer Agent + +This agent searches and analyzes past NA-MIC Project Week projects. + +## Capabilities + +- Search for projects by keyword, extension name, or topic +- Analyze trends across multiple project weeks +- Extract key investigators, objectives, and outcomes +- Compare project evolution over time + +## Usage + +Use this agent when you need to: +1. Find all past projects related to a specific topic (e.g., SlicerCBM, segmentation, registration) +2. Understand how a project has evolved over multiple project weeks +3. Gather context for creating a new project page +4. Identify potential collaborators who have worked on similar projects + +## Search Locations + +Projects are organized in directories like: +- `PW##_YEAR_Location/Projects/ProjectName/README.md` + +Key metadata in project pages: +- `project_title:` - Full project title +- `category:` - Project category +- `key_investigators:` - List of investigators with affiliations +- Sections: Project Description, Objective, Approach and Plan, Progress, Illustrations, Background and References + +## Example Queries + +- "Find all projects related to biomechanics" +- "List SlicerCBM projects across all years" +- "Who has worked on image registration projects?" diff --git a/.claude/skills/create-project/SKILL.md b/.claude/skills/create-project/SKILL.md new file mode 100644 index 000000000..f81ee33d9 --- /dev/null +++ b/.claude/skills/create-project/SKILL.md @@ -0,0 +1,98 @@ +--- +name: create-project +description: Create a new NA-MIC Project Week project page from template, searching past projects for context +argument-hint: "[project-name]" +allowed-tools: + - Read + - Write + - Grep + - Glob + - Bash +--- + +# Create Project Week Project + +This skill creates a new project page for NA-MIC Project Week. + +## Usage + +Invoke with: `/create-project ` + +Example: `/create-project SlicerCBM` + +## Instructions + +When this skill is invoked: + +1. **Search for past projects** with the same or similar name: + - Use grep/glob to find existing projects across all PW directories + - Read the most recent versions to understand project history and context + - Note key investigators, objectives achieved, and ongoing work + +2. **Identify the current Project Week**: + - Find the highest numbered PW directory (e.g., PW44_2026_GranCanaria) + - This is where the new project will be created + +3. **Read the current template**: + - Located at `PW##_YEAR_Location/Projects/Template/README.md` + - Use this exact structure for the new project + +4. **Create a feature branch** (IMPORTANT - never commit to master): + ```bash + git checkout master + git checkout -b PW##_YEAR_Location/ProjectName + ``` + +5. **Create the project page**: + - Folder name: Convert project name to PascalCase with no spaces/special characters + - Path: `PW##_YEAR_Location/Projects//README.md` + - Populate with content from past projects, updated for current objectives + +6. **Required fields in frontmatter**: + - `layout: pw##-project` (match current PW number) + - `permalink: /:path/` + - `project_title:` Full descriptive title + - `category:` One of: IGT and Training, DICOM, VR/AR and Rendering, Segmentation / Classification / Landmarking, Quantification and Computation, Registration, Cloud / Web, Infrastructure, Other + - `presenter_location:` "In-person" or "Online" + - `key_investigators:` List with name, affiliation, country + +7. **Content sections**: + - Project Description: Brief overview paragraph + - Objective: Numbered list of specific goals + - Approach and Plan: How objectives will be achieved + - Progress and Next Steps: Initially placeholder, updated during event + - Illustrations: Images/videos demonstrating the work + - Background and References: Links to code, data, publications + +8. **Commit and push the branch**: + ```bash + git add PW##_YEAR_Location/Projects/ProjectName/ + git commit -m "PW##_YEAR_Location: Add project ProjectName" + git push -u origin PW##_YEAR_Location/ProjectName + ``` + +9. **Create PR to upstream** (IMPORTANT: must use --head flag for fork-based PRs): + ```bash + # Get fork owner from origin remote + FORK_OWNER=$(git remote get-url origin | sed 's/.*[:/]\([^/]*\)\/ProjectWeek.*/\1/') + BRANCH=$(git branch --show-current) + + gh pr create \ + --repo NA-MIC/ProjectWeek \ + --base master \ + --head "$FORK_OWNER:$BRANCH" \ + --title "PW##: Add ProjectName project" \ + --body "## Summary + - Add ProjectName project for PW## + + ## Key Investigators + - Name (Affiliation)" + ``` + +## Tips + +- Keep the folder name concise but descriptive +- Reference past achievements in the Background section +- Link to relevant GitHub repos, documentation, and publications +- Use presenter_location "In-person" if attending in person +- NEVER commit directly to master - always use feature branches diff --git a/.claude/skills/update-claude-md/SKILL.md b/.claude/skills/update-claude-md/SKILL.md new file mode 100644 index 000000000..5696a8f43 --- /dev/null +++ b/.claude/skills/update-claude-md/SKILL.md @@ -0,0 +1,66 @@ +--- +name: update-claude-md +description: Update CLAUDE.md based on latest repo documentation for project creation +allowed-tools: + - Read + - Write + - Glob + - Grep + - Bash +--- + +# Update CLAUDE.md + +This skill updates CLAUDE.md to reflect the latest documentation in the repository. + +## Instructions + +1. **Find the current Project Week:** + ```bash + ls -d PW*_*/ | sort -V | tail -1 + ``` + +2. **Read ALL relevant documentation:** + - `PW##_YEAR_Location/README.md` - project categories in frontmatter, event details + - `PW##_YEAR_Location/Projects/Template/README.md` - current template structure + - `PW##_YEAR_Location/ContributingProjectPages.md` - contribution guidelines, PR workflow + - `.github/ISSUE_TEMPLATE/project.yml` - GitHub issue-based project creation + - `.github/workflows/project-page-pull-request.yml` - automated PR creation, **branch naming convention** + - `MAINTAINERS.md` - maintainer workflow info + - `README.md` - upstream repo URL, general info + +3. **Check git configuration:** + ```bash + git remote -v # Get upstream URL + git branch -a # Understand branch structure + ``` + +4. **List available skills:** + ```bash + ls .claude/skills/ + ``` + +5. **Update CLAUDE.md with these sections:** + - Repository Overview (brief) + - Key Documentation (references to actual files, not duplicated content) + - Contribution Workflow (fork-based, PR to master, branch naming) + - Commit Message Convention (from git log examples) + - Available Skills (from .claude/skills/) + - Commands (bundle exec jekyll serve, update-from-upstream.sh) + +## Key things to capture: + +- **CRITICAL: Never commit to master** - always use feature branches +- **Branch naming:** `PW##_YEAR_Location/ProjectName` (from workflow yml) +- **Full workflow:** branch → commit → push → PR to upstream +- **Upstream URL:** from git remote or README +- **PR target:** upstream `master` branch +- **Two project creation options:** GitHub issue OR manual PR (both use branches) +- **Commit format:** `PW##_YEAR_Location: Add project ProjectName` + +## Do NOT: + +- Copy/paste full templates or documentation into CLAUDE.md +- Remove existing useful information without reason +- Miss the contribution workflow details (this was missed before!) +- Forget to check GitHub Actions workflows for automation details diff --git a/.claude/skills/update-project/SKILL.md b/.claude/skills/update-project/SKILL.md new file mode 100644 index 000000000..1b7d85046 --- /dev/null +++ b/.claude/skills/update-project/SKILL.md @@ -0,0 +1,94 @@ +--- +name: update-project +description: Update an existing project page - creates branch, helps with edits, creates PR when ready +argument-hint: "[project-name] [action]" +allowed-tools: + - Read + - Write + - Edit + - Grep + - Glob + - Bash +--- + +# Update Project + +This skill helps update an existing NA-MIC Project Week project page. + +## Usage + +``` +/update-project ProjectName start # Start editing (creates branch) +/update-project ProjectName # Continue editing (shows current state) +/update-project ProjectName finish # Commit, push, and create PR +``` + +## Actions + +### `start` - Begin editing session + +1. Find the project in the current Project Week directory +2. Create a feature branch: + ```bash + git checkout master + git pull upstream master # sync first + git checkout -b PW##_YEAR_Location/ProjectName-updates + ``` +3. Show current project README for reference +4. Ready for user to request changes + +### (no action) - Continue editing + +1. Check we're on the correct branch +2. Show current state of project README +3. Show uncommitted changes if any +4. Ready for user to request more changes + +### `finish` - Complete and create PR + +1. Show diff of all changes made +2. Ask user to confirm +3. Commit changes: + ```bash + git add PW##_YEAR_Location/Projects/ProjectName/ + git commit -m "PW## ProjectName: Update " + ``` +4. Push branch: + ```bash + git push -u origin PW##_YEAR_Location/ProjectName-updates + ``` +5. Check if PR already exists for this branch: + ```bash + FORK_OWNER=$(git remote get-url origin | sed 's/.*[:/]\([^/]*\)\/ProjectWeek.*/\1/') + BRANCH=$(git branch --show-current) + gh pr list --repo NA-MIC/ProjectWeek --head "$FORK_OWNER:$BRANCH" --json url + ``` +6. Create PR if none exists (IMPORTANT: must use --head flag for fork-based PRs): + ```bash + gh pr create \ + --repo NA-MIC/ProjectWeek \ + --base master \ + --head "$FORK_OWNER:$BRANCH" \ + --title "PW## ProjectName: " \ + --body "## Summary + - " + ``` + + **IMPORTANT:** This is updating an EXISTING project, not adding a new one. The PR title should describe + what was updated (e.g., "PW44 SlicerCBM: Update progress and add screenshots"), NOT "Add project". + +7. Return PR URL to user + +## Finding the project + +Search in order: +1. Current PW directory: `PW##_YEAR_Location/Projects/ProjectName/` +2. Case-insensitive glob if exact match not found +3. Show options if multiple matches + +## Tips + +- User can make multiple rounds of changes before `finish` +- If user wants to abandon changes: `git checkout master` discards uncommitted work +- Branch naming includes `-updates` suffix to distinguish from new project branches +- Commit message should summarize what was actually changed (objectives, progress, etc.) diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 000000000..cdb42627a --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,111 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Repository Overview + +NA-MIC Project Week website - Jekyll static site at https://projectweek.na-mic.org. Biannual hackathon for medical image computing (3D Slicer, VTK, ITK, OHIF). + +## Key Documentation + +- **Current event:** Find highest numbered `PW##_YEAR_Location/` directory +- **Project template:** `PW##_YEAR_Location/Projects/Template/README.md` +- **Contributing guide:** `PW##_YEAR_Location/ContributingProjectPages.md` +- **Categories:** Listed in `PW##_YEAR_Location/README.md` frontmatter (`project_categories`) + +## Contribution Workflow + +**IMPORTANT: Never commit directly to master. Always use branches and PRs.** + +### Git Remote Setup + +This repo uses a fork-based workflow with two remotes: +- `origin` - Your fork (e.g., `benzwick/ProjectWeek`) +- `upstream` - Main repo (`NA-MIC/ProjectWeek`) + +Check remotes with: `git remote -v` + +### Workflow Steps + +1. Create feature branch: `PW##_YEAR_Location/ProjectName` +2. Commit changes to branch +3. Push branch to origin (your fork) +4. Create PR to upstream `master` + +**For new projects:** +```bash +git checkout -b PW44_2026_GranCanaria/ProjectName +# create project files +git add PW44_2026_GranCanaria/Projects/ProjectName/ +git commit -m "PW44_2026_GranCanaria: Add project ProjectName" +git push -u origin PW44_2026_GranCanaria/ProjectName +``` + +**For project updates:** +```bash +git checkout -b PW44_2026_GranCanaria/ProjectName-updates +# make changes +git commit -m "PW44 ProjectName: Update Objectives" +git push -u origin PW44_2026_GranCanaria/ProjectName-updates +``` + +### Creating Pull Requests + +**IMPORTANT:** When creating PRs from a fork, you MUST use the `--head` flag to specify the fork owner and branch. + +First, get the fork owner from the origin remote: +```bash +git remote get-url origin | sed 's/.*[:/]\([^/]*\)\/ProjectWeek.*/\1/' +``` + +Then create the PR with the correct flags: +```bash +gh pr create \ + --repo NA-MIC/ProjectWeek \ + --base master \ + --head FORK_OWNER:BRANCH_NAME \ + --title "PW44: Add ProjectName project" \ + --body "## Summary +- Brief description of changes + +## Key Investigators +- Name (Affiliation)" +``` + +**Example** (for benzwick fork): +```bash +gh pr create \ + --repo NA-MIC/ProjectWeek \ + --base master \ + --head benzwick:PW44_2026_GranCanaria/SlicerCBM \ + --title "PW44: Add SlicerCBM project" \ + --body "## Summary +- Add SlicerCBM project for PW44 + +## Key Investigators +- Ben Zwick (UWA, Talk2View)" +``` + +**Upstream:** https://github.com/NA-MIC/ProjectWeek + +## Commit Message Convention + +``` +PW44_2026_GranCanaria: Add project ProjectName +PW44 ProjectName: Update Objectives +``` + +## Available Skills + +Skills in `.claude/skills/`: + +- `/create-project [name]` - Create a new project page on a feature branch +- `/update-project [name] [start|finish]` - Update existing project with branch/PR workflow +- `/update-claude-md` - Update CLAUDE.md based on latest repo documentation + +## Commands + +```bash +bundle exec jekyll serve # Local development +./update-from-upstream.sh # Sync master with upstream and push +```