Merge pull request #33 from NeoLabHQ/feature/vg/git/add-worktrees-and-notes

feat(git): add git worktrees and notes skills

Author: LeoVS09

.claude-plugin/marketplace.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
   "name": "context-engineering-kit",
-  "version": "1.7.3",
+  "version": "1.8.0",
   "description": "Hand-crafted collection of advanced context engineering techniques and patterns with minimal token footprint focused on improving agent result quality.",
   "owner": {
     "name": "NeoLabHQ",
@@ -32,8 +32,8 @@
     },
     {
       "name": "git",
-      "description": "Introduces commands for commit and PRs creation.",
-      "version": "1.0.3",
+      "description": "Introduces commands for commit and PRs creation, plus skills for git worktrees and notes.",
+      "version": "1.1.0",
       "author": {
         "name": "Vlad Goncharov",
         "email": "vlad.goncharov@neolab.finance"
@@ -55,7 +55,7 @@
     {
       "name": "sadd",
       "description": "Introduces skills for subagent-driven development, dispatches fresh subagent for each task with code review between tasks, enabling fast iteration with quality gates.",
-      "version": "1.1.0",
+      "version": "1.1.1",
       "author": {
         "name": "Vlad Goncharov",
         "email": "vlad.goncharov@neolab.finance"
@@ -99,7 +99,7 @@
     {
       "name": "customaize-agent",
       "description": "Commands and skills for writing and refining commands, hooks, skills for Claude Code, includes Anthropic Best Practices and Agent Persuasion Principles that can be useful for sub-agent workflows.",
-      "version": "1.3.0",
+      "version": "1.3.1",
       "author": {
         "name": "Vlad Goncharov",
         "email": "vlad.goncharov@neolab.finance"

README.md

@@ -300,7 +300,7 @@ jobs:
 
 ### Git
 
-Commands for streamlined Git operations including commits and pull request creation.
+Commands and skills for streamlined Git operations including commits, pull request creation, and advanced workflow patterns.
 
 **How to install**
 
@@ -315,6 +315,11 @@ Commands for streamlined Git operations including commits and pull request creat
 - `/git:analyze-issue` - Analyze a GitHub issue and create a detailed technical specification
 - `/git:load-issues` - Load all open issues from GitHub and save them as markdown files
 
+**Skills**
+
+- **worktrees** - Git worktree commands and workflow patterns for parallel branch development
+- **notes** - Git notes commands for attaching non-invasive metadata to commits
+
 ### Test-Driven Development
 
 Commands and skills for test-driven development with anti-pattern detection.

docs/plugins/README.md

@@ -157,15 +157,17 @@ Code quality and architecture patterns including Clean Architecture and SOLID pr
 
 #### Git
 
-Streamlined Git operations with conventional commits and pull request management.
+Streamlined Git operations with conventional commits, pull request management, and advanced workflow patterns.
 
 **Key Features:**
 
 * Conventional commits with emoji
 * Pull request creation
 * Issue analysis and loading
+* Git worktrees for parallel branch development
+* Git notes for commit metadata annotations
 
-**When to use:** For all Git operations to maintain commit and PR quality.
+**When to use:** For all Git operations to maintain commit and PR quality, or when working on multiple branches simultaneously.
 
 [Full Documentation](git/)
 

docs/plugins/git/README.md

@@ -258,6 +258,73 @@ PR number or URL (optional - can work with current branch).
 > /git:attach-review-to-pr 456
 ```
 
+## Skills Overview
+
+### worktrees - Parallel Branch Development
+
+Use when working on multiple branches simultaneously, context switching without stashing, reviewing PRs while developing, testing in isolation, or comparing implementations across branches.
+
+- Purpose - Provide git worktree commands and workflow patterns for parallel development
+- Core Principle - One worktree per active branch; switch contexts by changing directories
+
+**Key Concepts**
+
+| Concept | Description |
+|---------|-------------|
+| Main worktree | Original working directory from `git clone` or `git init` |
+| Linked worktree | Additional directories created with `git worktree add` |
+| Shared `.git` | All worktrees share same Git object database (no duplication) |
+| Branch lock | Each branch can only be checked out in ONE worktree at a time |
+
+**Quick Reference**
+
+| Task | Command |
+|------|---------|
+| Create worktree (existing branch) | `git worktree add <path> <branch>` |
+| Create worktree (new branch) | `git worktree add -b <branch> <path>` |
+| List all worktrees | `git worktree list` |
+| Remove worktree | `git worktree remove <path>` |
+
+**Common Workflows**
+
+- **Feature + Hotfix in Parallel** - Create worktree for hotfix while feature work continues
+- **PR Review While Working** - Create temporary worktree to review PRs without stashing
+- **Compare Implementations** - Create worktrees for different versions to diff side-by-side
+- **Long-Running Tasks** - Run tests in isolated worktree while continuing development
+
+### notes - Commit Metadata Annotations
+
+Use when adding metadata to commits without changing history, tracking review status, test results, code quality annotations, or supplementing commit messages post-hoc.
+
+- Purpose - Attach non-invasive metadata to Git objects without modifying commit history
+- Core Principle - Add information to commits after creation without rewriting history
+
+**Key Concepts**
+
+| Concept | Description |
+|---------|-------------|
+| Notes ref | Storage location, default `refs/notes/commits` |
+| Non-invasive | Notes never modify SHA of original object |
+| Namespaces | Use `--ref` for different note categories (reviews, testing, audit) |
+| Display | Notes appear in `git log` and `git show` output |
+
+**Quick Reference**
+
+| Task | Command |
+|------|---------|
+| Add note | `git notes add -m "message" <sha>` |
+| View note | `git notes show <sha>` |
+| Append to note | `git notes append -m "message" <sha>` |
+| Use namespace | `git notes --ref=<name> <command>` |
+| Push notes | `git push origin refs/notes/<name>` |
+
+**Common Use Cases**
+
+- **Code Review Tracking** - Mark commits as reviewed with reviewer attribution
+- **Test Results Annotation** - Record test pass/fail status and coverage
+- **Audit Trail** - Attach security review or compliance information
+- **Sharing Notes** - Push/fetch notes to share metadata with team
+
 ## Conventional Commit Format
 
 The plugin follows the [conventional commits specification](https://www.conventionalcommits.org/):

docs/reference/skills.md

@@ -29,6 +29,13 @@ Continuous improvement methodology with multiple analysis techniques. [More info
 
 - `kaizen` - Japanese continuous improvement philosophy with root cause analysis, Five Whys, PDCA cycles, and lean practices.
 
+### Git
+
+Streamlined Git operations with advanced workflow patterns. [More info](../plugins/git/README.md).
+
+- `worktrees` - Use when working on multiple branches simultaneously, context switching without stashing, reviewing PRs while developing, testing in isolation, or comparing implementations across branches.
+- `notes` - Use when adding metadata to commits without changing history, tracking review status, test results, code quality annotations, or supplementing commit messages post-hoc.
+
 ### Customaize Agent
 
 Prompt engineering techniques and patterns for creating effective extensions. [More info](../plugins/customaize-agent/README.md).

plugins/customaize-agent/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "customaize-agent",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "Commands and skills for writing and refining commands, hooks, skills for Claude Code, includes Anthropic Best Practices and Agent Persuasion Principles that can be useful for sub-agent workflows.",
   "author": {
     "name": "Vlad Goncharov",

plugins/customaize-agent/commands/create-skill.md

@@ -448,26 +448,6 @@ When: Reference material too large for inline
 
 ## The Iron Law (Same as TDD)
 
-```
-NO SKILL WITHOUT A FAILING TEST FIRST
-```
-
-This applies to NEW skills AND EDITS to existing skills.
-
-Write skill before testing? Delete it. Start over.
-Edit skill without testing? Same violation.
-
-**No exceptions:**
-
-- Not for "simple additions"
-- Not for "just adding a section"
-- Not for "documentation updates"
-- Don't keep untested changes as "reference"
-- Don't "adapt" while running tests
-- Delete means delete
-
-**REQUIRED BACKGROUND:** The superpowers:test-driven-development skill explains why this matters. Same principles apply to documentation.
-
 ## Testing All Skill Types
 
 Different skill types need different test approaches:
@@ -521,21 +501,6 @@ Different skill types need different test approaches:
 
 **Success criteria:** Agent finds and correctly applies reference information
 
-## Common Rationalizations for Skipping Testing
-
-| Excuse | Reality |
-|--------|---------|
-| "Skill is obviously clear" | Clear to you ≠ clear to other agents. Test it. |
-| "It's just a reference" | References can have gaps, unclear sections. Test retrieval. |
-| "Testing is overkill" | Untested skills have issues. Always. 15 min testing saves hours. |
-| "I'll test if problems emerge" | Problems = agents can't use skill. Test BEFORE deploying. |
-| "Too tedious to test" | Testing is less tedious than debugging bad skill in production. |
-| "I'm confident it's good" | Overconfidence guarantees issues. Test anyway. |
-| "Academic review is enough" | Reading ≠ using. Test application scenarios. |
-| "No time to test" | Deploying untested skill wastes more time fixing it later. |
-
-**All of these mean: Test before deploying. No exceptions.**
-
 ## Bulletproofing Skills Against Rationalization
 
 Skills that enforce discipline (like TDD) need to resist rationalization. Agents are smart and will find loopholes when under pressure.

plugins/git/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "git",
-  "version": "1.0.3",
-  "description": "Introduces commands for commit and PRs creation.",
+  "version": "1.1.0",
+  "description": "Introduces commands for commit and PRs creation, plus skills for git worktrees and notes.",
   "author": {
     "name": "Vlad Goncharov",
     "email": "vlad.goncharov@neolab.finance"

plugins/git/README.md

@@ -258,6 +258,73 @@ PR number or URL (optional - can work with current branch).
 > /git:attach-review-to-pr 456
 ```
 
+## Skills Overview
+
+### worktrees - Parallel Branch Development
+
+Use when working on multiple branches simultaneously, context switching without stashing, reviewing PRs while developing, testing in isolation, or comparing implementations across branches.
+
+- Purpose - Provide git worktree commands and workflow patterns for parallel development
+- Core Principle - One worktree per active branch; switch contexts by changing directories
+
+**Key Concepts**
+
+| Concept | Description |
+|---------|-------------|
+| Main worktree | Original working directory from `git clone` or `git init` |
+| Linked worktree | Additional directories created with `git worktree add` |
+| Shared `.git` | All worktrees share same Git object database (no duplication) |
+| Branch lock | Each branch can only be checked out in ONE worktree at a time |
+
+**Quick Reference**
+
+| Task | Command |
+|------|---------|
+| Create worktree (existing branch) | `git worktree add <path> <branch>` |
+| Create worktree (new branch) | `git worktree add -b <branch> <path>` |
+| List all worktrees | `git worktree list` |
+| Remove worktree | `git worktree remove <path>` |
+
+**Common Workflows**
+
+- **Feature + Hotfix in Parallel** - Create worktree for hotfix while feature work continues
+- **PR Review While Working** - Create temporary worktree to review PRs without stashing
+- **Compare Implementations** - Create worktrees for different versions to diff side-by-side
+- **Long-Running Tasks** - Run tests in isolated worktree while continuing development
+
+### notes - Commit Metadata Annotations
+
+Use when adding metadata to commits without changing history, tracking review status, test results, code quality annotations, or supplementing commit messages post-hoc.
+
+- Purpose - Attach non-invasive metadata to Git objects without modifying commit history
+- Core Principle - Add information to commits after creation without rewriting history
+
+**Key Concepts**
+
+| Concept | Description |
+|---------|-------------|
+| Notes ref | Storage location, default `refs/notes/commits` |
+| Non-invasive | Notes never modify SHA of original object |
+| Namespaces | Use `--ref` for different note categories (reviews, testing, audit) |
+| Display | Notes appear in `git log` and `git show` output |
+
+**Quick Reference**
+
+| Task | Command |
+|------|---------|
+| Add note | `git notes add -m "message" <sha>` |
+| View note | `git notes show <sha>` |
+| Append to note | `git notes append -m "message" <sha>` |
+| Use namespace | `git notes --ref=<name> <command>` |
+| Push notes | `git push origin refs/notes/<name>` |
+
+**Common Use Cases**
+
+- **Code Review Tracking** - Mark commits as reviewed with reviewer attribution
+- **Test Results Annotation** - Record test pass/fail status and coverage
+- **Audit Trail** - Attach security review or compliance information
+- **Sharing Notes** - Push/fetch notes to share metadata with team
+
 ## Conventional Commit Format
 
 The plugin follows the [conventional commits specification](https://www.conventionalcommits.org/):