btrace (Agent Skills)

# Claude Code Guide

Follow the repository-wide rules in [AGENTS.md](AGENTS.md). This file intentionally contains only Claude-specific orientation; `AGENTS.md` is the canonical operational contract.

## Common commands

Use a workspace-local Gradle cache when appropriate, and redirect Gradle output to a log before filtering and reading it (see [AGENTS.md](AGENTS.md#build-and-verification)).

```bash
# Distribution and all unit tests
GRADLE_USER_HOME=$(pwd)/.gradle-user ./gradlew :btrace-dist:build

# Module, test class, or formatting check
GRADLE_USER_HOME=$(pwd)/.gradle-user ./gradlew :btrace-agent:test
GRADLE_USER_HOME=$(pwd)/.gradle-user ./gradlew :btrace-agent:test --tests '*InstrStackTest'
GRADLE_USER_HOME=$(pwd)/.gradle-user ./gradlew spotlessCheck

# Integration tests: build the distribution first
GRADLE_USER_HOME=$(pwd)/.gradle-user ./gradlew -Pintegration :integration-tests:test

# Intentional instrumentation-bytecode changes only
GRADLE_USER_HOME=$(pwd)/.gradle-user ./gradlew test -PupdateTestData
```

## Where to look

- Script compiler and verifier: `btrace-compiler`
- Agent lifecycle and bytecode weaving: `btrace-agent` (instrumentation engine lives in its `io.btrace.instr` package)
- Script API, runtime, and protocol: `btrace-core`, `btrace-runtime`
- CLI: `btrace-client`; packaging: `btrace-dist`
- Golden instrumentation data: `btrace-agent/src/test/resources/instrumentorTestData/`

## Detailed references

- [Documentation index](docs/README.md)
- [Masked JAR architecture](docs/architecture/MaskedJarArchitecture.md) — required reading for distribution/class-loading changes
- [Instrumentation backends](docs/architecture/InstrumentationBackends.md)
- [Protocol architecture](docs/architecture/Version2ProtocolArchitecture.md)
- [Extension development](docs/BTraceExtensionDevelopmentGuide.md)
- [Troubleshooting](docs/Troubleshooting.md)

# Repository Guide for Coding Agents

## Start here

BTrace is a Java tracing tool: the client compiles and sends a script, the agent instruments the target JVM, and the runtime emits results. The root project is a multi-module Gradle build.

- `btrace-agent` — attachable agent, script lifecycle, and bytecode instrumentation/weaving
- `btrace-compiler` — script verification and compilation
- `btrace-runtime` / `btrace-core` — script APIs, runtime support, and protocol
- `btrace-client` — CLI and attachment client
- `btrace-dist` — distribution assembly; `integration-tests` — end-to-end tests
- `btrace-extensions/*` — extension API and implementations

For the developer command reference and code-navigation pointers, see [CLAUDE.md](CLAUDE.md). For user and contributor documentation, start at [docs/README.md](docs/README.md).

## Non-negotiable rules

- Do not commit unless the changes are fully tested or the user explicitly requests a commit.
- Preserve unrelated working-tree changes.
- In Java code, import types and use simple names; do not introduce fully qualified type names in source.
- Main code targets Java 8 and uses the Java 11 toolchain. Follow Spotless/Google Java Format.
- Unit tests live in `src/test/java` and use `*Test`; integration tests live in `integration-tests/src/test/java`.
- Changes to user-visible behavior that crosses modules or process boundaries must include end-to-end functional coverage in `integration-tests`; unit and component tests are required where useful but are not a substitute for exercising the real client, agent, target JVM, and protocol interaction.
- Confirm that a new test or build gate **fails when it should**, not only that it passes. Run it against the unfixed code, or against input it must reject, and check the failure is the expected one. A check that cannot fail reports success regardless of what the code does, and reads as coverage while providing none. Where a revert is used to produce the failure, revert only the code under test: reverting too much fails for an unrelated reason and proves nothing about the behavior being asserted.

## Build and verification

Run Gradle with a workspace-local cache in restricted environments:

```bash
GRADLE_USER_HOME=$(pwd)/.gradle-user ./gradlew :module:test
```

Do not consume Gradle output directly. Redirect it to a file, filter it to relevant lines, then read that file. Use `spotlessCheck` for validation and `spotlessApply` only when formatting changes are intended. Build `:btrace-dist:build` before integration tests.

If a restricted network environment causes address-selection failures, add:

```bash
JAVA_TOOL_OPTIONS="-Djava.net.preferIPv4Stack=true -Djava.net.preferIPv6Addresses=false"
```

## Distribution changes

`btrace.jar` is a masked single-JAR distribution. Classes must be assigned to bootstrap, agent, client, or shared sections deliberately. Any masked-JAR structure change requires:

```bash
./gradlew clean :btrace-dist:btraceJar
```

Read [Masked JAR Architecture](docs/architecture/MaskedJarArchitecture.md) before modifying its class layout or loader behavior.

## Documentation placement

- User-facing and contributor documentation belongs in `docs/`; keep [docs/README.md](docs/README.md) current when adding a guide.
- Plans and session notes belong in `internal/plans/` (or `internal/superpowers/plans/`).
- Design/requirement specs belong in `internal/specs/` (or `internal/superpowers/specs/`); libretto/muse files belong in `internal/libretti/`.
- Never create or write to a singular `doc/` directory, or add plans, agent notes, or internal material below `docs/`.

## Reference map

- [Contribution workflow](CONTRIBUTING.md)
- [Instrumentation backend selection](docs/architecture/InstrumentationBackends.md)
- [v2 wire protocol](docs/architecture/Version2ProtocolArchitecture.md)
- [Extension development](docs/BTraceExtensionDevelopmentGuide.md) and [interface rules](docs/ExtensionInterfaceRules.md)
- [Troubleshooting](docs/Troubleshooting.md)

# GitHub Copilot Instructions for BTrace

## About BTrace
BTrace is a safe, dynamic tracing tool for the Java platform. It dynamically instruments running Java applications to inject tracing code at runtime using bytecode instrumentation.

## Project Structure
- **Gradle multi-module project** with modules named `btrace-*`
- **Core modules**: `btrace-core`, `btrace-agent`, `btrace-runtime`, `btrace-client`, `btrace-instr`
- **Build artifacts**: `btrace-dist` for distributions
- **Tests**: `integration-tests/` for integration tests, `src/test/java` in modules for unit tests
- **Documentation**: `docs/` directory

## Architecture Overview
- **btrace-agent**: Attachable Java agent with class transformer, manages script lifecycle
- **btrace-compiler**: Verifies and compiles BTrace scripts to bytecode
- **btrace-instr**: ASM-based instrumentation and weaving utilities
- **btrace-runtime**: APIs for scripts (printing, timers, data collection)
- **btrace-client**: CLI/attach tooling for sending scripts to target JVM
- **services**: SPI for pluggable exporters (e.g., statsd)

## Development Guidelines

### Language & Versions
- **Language**: Java
- **Source/Target**: Java 8
- **Build toolchain**: JDK 11
- **Test framework**: JUnit Jupiter (JUnit 5)

### Code Style
- **Format**: Google Java Format enforced via Spotless
- **Packages**: All under `io.btrace.*`
- **Naming**: Module names follow `btrace-<component>` pattern
- **Imports**: Order enforced; remove unused imports
- **Comments**: Only add if they match existing style or explain complex logic

### Building & Testing
```bash
# Full build with unit tests
./gradlew build

# Build distribution only
./gradlew :btrace-dist:build

# Run unit tests
./gradlew test

# Run integration tests (requires dist build first)
./gradlew -Pintegration test

# Format code
./gradlew spotlessApply

# Check formatting
./gradlew spotlessCheck
```

### Important Environment Variables
- `JAVA_HOME`: Required for builds
- `TEST_JAVA_HOME`: Required for integration tests (typically JDK 11)
- `BTRACE_TEST_DEBUG=true`: Enable verbose integration test output
- `BTRACE_HOME`: Optional, points to exploded dist

### Testing Best Practices
- Unit tests: `src/test/java` with `*Test` suffix
- Integration tests: `integration-tests/src/test/java`
- BTrace scripts: `integration-tests/src/test/btrace`
- Always run relevant tests after making changes
- Update golden files when changing instrumentor: `./gradlew test -PupdateTestData`

### Commit & PR Guidelines
- **Commit style**: Conventional Commits (e.g., `feat(core): add probe`, `fix(instr): handle null arg`)
- **Clear descriptions**: Link related issues
- **Tests required**: Update/add tests; ensure CI passes
- **Formatting**: Must pass `spotlessCheck`
- **No unrelated changes**: Keep changes focused and minimal

## Troubleshooting

### Build Issues
- **Attach disabled**: Remove `-XX:+DisableAttachMechanism` from target JVM
- **Permission errors**: Attach requires same OS user as target JVM
- **Toolchain issues**: Verify `JAVA_HOME` and `TEST_JAVA_HOME` point to valid JDKs

### Restricted Environments
```bash
# Use workspace-local Gradle cache
GRADLE_USER_HOME=$(pwd)/.gradle-user

# Force IPv4 to avoid network interface issues
JAVA_TOOL_OPTIONS="-Djava.net.preferIPv4Stack=true -Djava.net.preferIPv6Addresses=false"
```

## Code Generation Tips
- **Prefer simplicity**: Simple, performant solutions over complex designs
- **Use existing patterns**: Follow patterns from similar code in the repository
- **Minimal changes**: Make the smallest possible changes to achieve the goal
- **Reuse libraries**: Use ASM for bytecode, JCTools for concurrency, existing BTrace APIs
- **No temporary files in repo**: Use `/tmp` for scratch work
- **Security**: Never commit secrets; avoid introducing vulnerabilities

## Example BTrace Script Pattern
```java
package example;
import static io.btrace.core.BTraceUtils.*;
import io.btrace.core.annotations.*;

@BTrace
public class ExampleTrace {
  @OnMethod(clazz="com.example.Target", method="methodName")
  public static void onMethod(@ProbeMethodName String method) {
    println("Called: " + method);
  }
}
```

## Key Dependencies
- **ASM**: Bytecode manipulation
- **JCTools**: High-performance concurrent data structures
- **hppcrt**: Optimized collections
- **JUnit Jupiter**: Testing framework

## Additional Resources
- Full guidelines: See `AGENTS.md` in repository root
- Tutorial: `docs/BTraceTutorial.md`
- Binary releases: https://github.com/btraceio/btrace/releases