Docs: add git workflow guidelines to AGENTS.md and all SKILL files

.cognition/skills/debug-exiftool/SKILL.md

@@ -11,6 +11,17 @@ triggers:
 
 You are debugging failures in the Image::ExifTool test suite running under PerlOnJava (a Perl-to-JVM compiler/interpreter). Failures typically stem from missing Perl features or subtle behavior differences in PerlOnJava, not bugs in ExifTool itself.
 
+## Git Workflow
+
+**IMPORTANT: Never push directly to master. Always use feature branches and PRs.**
+
+```bash
+git checkout -b fix/exiftool-issue-name
+# ... make changes ...
+git push origin fix/exiftool-issue-name
+gh pr create --title "Fix: description" --body "Details"
+```
+
 ## Project Layout
 
 - **PerlOnJava source**: `src/main/java/org/perlonjava/` (compiler, bytecode interpreter, runtime)

.cognition/skills/debug-perlonjava/SKILL.md

@@ -11,6 +11,17 @@ triggers:
 
 You are debugging failures in PerlOnJava, a Perl-to-JVM compiler with a bytecode interpreter fallback. This skill covers debugging workflows for test failures, regressions, and parity issues between backends.
 
+## Git Workflow
+
+**IMPORTANT: Never push directly to master. Always use feature branches and PRs.**
+
+```bash
+git checkout -b fix/descriptive-name
+# ... make changes ...
+git push origin fix/descriptive-name
+gh pr create --title "Fix: description" --body "Details"
+```
+
 ## Project Layout
 
 - **PerlOnJava source**: `src/main/java/org/perlonjava/` (compiler, bytecode interpreter, runtime)

.cognition/skills/debugger/SKILL.md

@@ -4,6 +4,17 @@
 
 Continue implementing the Perl debugger (`-d` flag) for PerlOnJava. The debugger uses DEBUG opcodes injected at statement boundaries in the bytecode interpreter.
 
+## Git Workflow
+
+**IMPORTANT: Never push directly to master. Always use feature branches and PRs.**
+
+```bash
+git checkout -b feature/debugger-improvement
+# ... make changes ...
+git push origin feature/debugger-improvement
+gh pr create --title "Debugger: description" --body "Details"
+```
+
 ## Key Documentation
 
 ### Design Document
@@ -36,14 +47,18 @@ Continue implementing the Perl debugger (`-d` flag) for PerlOnJava. The debugger
 | Command | Description |
 |---------|-------------|
 | `n` | Next (step over) |
-| `s` | Step into |
+| `s` | Step into (shows subroutine name, e.g., `main::foo(file:line)`) |
+| `r` | Return (step out of current subroutine) |
 | `c [line]` | Continue (optionally to line) |
 | `q` | Quit |
 | `l [range]` | List source (`l 10-20` or `l 15`) |
 | `.` | Show current line |
 | `b [line]` | Set breakpoint |
 | `B [line]` | Delete breakpoint (`B *` = all) |
 | `L` | List breakpoints |
+| `T` | Stack trace |
+| `p expr` | Print expression (supports lexical variables) |
+| `x expr` | Dump expression with Data::Dumper (supports lexical variables) |
 | `h` | Help |
 
 ## Comparison with System Perl Debugger
@@ -65,8 +80,8 @@ Tested side-by-side with `perl -d`:
 | Loading message | None | Shows perl5db.pl version | OK (intentional) |
 
 ### Known Differences to Address
-1. **Package prefix**: Add `main::` (or current package) to location display
-2. **Prompt counter**: Change to 1-indexed (`DB<1>`) to match Perl
+1. ~~**Package prefix**: Add `main::` (or current package) to location display~~ **DONE**
+2. ~~**Prompt counter**: Change to 1-indexed (`DB<1>`) to match Perl~~ **DONE**
 3. **`l` command**: Perl shows current line, subsequent `l` shows next 10 lines
 
 ## Source Files
@@ -85,23 +100,26 @@ Tested side-by-side with `perl -d`:
 
 ## Next Steps (from design doc)
 
-### Phase 2: Source Line Support (partially done)
+### Phase 2: Source Line Support (mostly done)
 - [x] Store source lines during parsing
 - [x] Skip compile-time statements (use/no)
+- [x] Display subroutine names when stepping (e.g., `main::foo(file:line)`)
 - [ ] Track breakable lines (statements vs comments)
 - [ ] Implement `@{"_<$filename"}` magical array
 - [ ] Implement `%{"_<$filename"}` for breakpoint storage
 
-### Phase 3: Debug Variables
-- [ ] `$DB::single`, `$DB::trace`, `$DB::signal` as tied variables
-- [ ] `$DB::filename`, `$DB::line` (currently Java-only)
-- [ ] `@DB::args` support in `caller()`
-- [ ] `%DB::sub` for subroutine location tracking
-
-### Phase 4: Perl Expression Evaluation
-- [ ] `p expr` - print expression value
-- [ ] `x expr` - dump expression (Data::Dumper style)
-- [ ] General expression evaluation in debugger context
+### Phase 3: Debug Variables (partially done)
+- [x] `$DB::single`, `$DB::trace`, `$DB::signal` synced from Java
+- [x] `$DB::filename`, `$DB::line` set by DEBUG opcode
+- [x] `@DB::args` support in `caller()`
+- [x] `%DB::sub` for subroutine location tracking
+- [ ] Make debug variables fully tied (Perl can modify them)
+
+### Phase 4: Perl Expression Evaluation (DONE)
+- [x] `p expr` - print expression value
+- [x] `x expr` - dump expression (Data::Dumper style)
+- [x] Lexical variable access in debugger expressions
+- [x] Registry deduplication to minimize memory usage
 
 ### Phase 5: perl5db.pl Compatibility
 - [ ] Inject `BEGIN { require 'perl5db.pl' }` when `-d` used

.cognition/skills/interpreter-parity/SKILL.md

@@ -11,6 +11,17 @@ triggers:
 
 You are fixing cases where PerlOnJava's bytecode interpreter produces different results than the JVM compiler backend. The interpreter should be a drop-in replacement — same parsing, same runtime APIs, different execution engine.
 
+## Git Workflow
+
+**IMPORTANT: Never push directly to master. Always use feature branches and PRs.**
+
+```bash
+git checkout -b fix/interpreter-issue-name
+# ... make changes ...
+git push origin fix/interpreter-issue-name
+gh pr create --title "Fix interpreter: description" --body "Details"
+```
+
 ## Project Layout
 
 - **PerlOnJava source**: `src/main/java/org/perlonjava/` (compiler, bytecode interpreter, runtime)

.cognition/skills/profile-perlonjava/SKILL.md

@@ -2,6 +2,17 @@
 
 Profile and optimize PerlOnJava runtime performance using Java Flight Recorder.
 
+## Git Workflow
+
+**IMPORTANT: Never push directly to master. Always use feature branches and PRs.**
+
+```bash
+git checkout -b perf/optimization-name
+# ... make changes ...
+git push origin perf/optimization-name
+gh pr create --title "Perf: description" --body "Details"
+```
+
 ## When to Use
 
 - Investigating performance bottlenecks in Perl scripts running on PerlOnJava

AGENTS.md

@@ -49,6 +49,25 @@ Example format at the end of a design doc:
   java -jar target/perlonjava.jar --int -e 'code'     # Interpreter
   ```
 
+### Git Workflow
+
+**IMPORTANT: Never push directly to master. Always use feature branches and PRs.**
+
+1. **Create a feature branch** before making changes:
+   ```bash
+   git checkout -b feature/descriptive-name
+   ```
+
+2. **Make commits** on the feature branch with clear messages
+
+3. **Push the feature branch** and create a PR:
+   ```bash
+   git push origin feature/descriptive-name
+   gh pr create --title "Title" --body "Description"
+   ```
+
+4. **Wait for review** before merging
+
 ### Commits
 
 - Reference the design doc or issue in commit messages when relevant