Making PCP a bit friendlier to AI agents

.github/ISSUE_TEMPLATE/pcp_bug_report.yml

@@ -0,0 +1,61 @@
+name: Performance Co-Pilot Issue Report
+description: Create a report for a PCP related bug
+title: "[Bug] "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: Thank you for taking the time to fill out this bug report!
+  - type: textarea
+    id: issue-description
+    attributes:
+      label: Issue Description
+      description: What is the issue that you are encountering?
+    validations:
+      required: True
+  - type: input
+    id: operating-system
+    attributes:
+      label: Operating System
+      description: What is your machines operating system? Include name and version number.<br>(`cat /etc/os-release | grep -E "^(NAME=|VERSION=)"`)
+      placeholder: e.g. Rocky Linux Version 9.5
+    validations:
+      required: True
+  - type: input
+    id: architecture
+    attributes:
+      label: Architecture
+      description: What is your machines architecture?<br>(`uname -m`)
+      placeholder: e.g. x86_64
+    validations:
+      required: True
+  - type: input
+    id: pcp-version
+    attributes:
+      label: PCP Version
+      description: What version of PCP are you using (optional)?<br>(`(cd path_to_your_pcp_install/bin && ./pcp)`)
+      placeholder: e.g. main or PCP 7.1.2
+    validations:
+      required: False
+  - type: input
+    id: component
+    attributes:
+      label: Component
+      description: What PCP component does this issue pertain to (optional)?
+      placeholder: e.g. pmlogger
+    validations:
+      required: False
+  - type: textarea
+    id: steps-to-reproduce
+    attributes:
+      label: Steps to Reproduce
+      description: Provide steps to reproduce this issue (optional).
+    validations:
+      required: False
+  - type: textarea
+    id: additional-information
+    attributes:
+      label: Additional Information
+      description: Is there any additional information that is relevant to your issue? Are there known machine configurations or versions of PCP where this issue does not occur?
+    validations:
+      required: False

.github/ISSUE_TEMPLATE/pcp_feature_request.yml

@@ -0,0 +1,23 @@
+name: Performance Co-Pilot Feature Request
+description: Request additional functionality or suggest a new approach to existing functionality
+title: "[RFE] "
+labels: ["feature"]
+body:
+  - type: markdown
+    attributes:
+      value: Thank you for taking the time to make a feature request!
+  - type: textarea
+    id: feature-request
+    attributes:
+      label: Description of Request for Enhancement
+      description: Describe the feature that you would like to see in PCP.
+    validations:
+      required: True
+  - type: input
+    id: component
+    attributes:
+      label: Component
+      description: If this is for a specific PCP component, please mention it here (optional).
+      placeholder: e.g. pmlogger
+    validations:
+      required: False

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,14 @@
+## Pull Request Description
+
+## Related Issues
+Fixes #
+
+## Checklist
+- [ ] ** Description **
+_Why_ this PR exists. Reference all relevant information, including _background_, _issues_, _test failures_, etc
+- [ ] ** Commmits **
+_Commits_ are self contained and only do one thing
+_Commits_ have a header of the form: `module: short description`
+_Commits_ have a body (whenever relevant) containing a detailed description of the addressed problem and its solution
+- [ ] Documentation updated
+- [ ] Tests added/updated

AGENTS.md

@@ -0,0 +1,194 @@
+# AGENTS.md
+
+This file provides guidance to AI Agents (for example claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Performance Co-Pilot (PCP) is a mature, extensible, cross-platform toolkit for system-level performance monitoring and management. It provides a unifying abstraction for all performance data in a system and many tools for interrogating, retrieving and processing that data.
+
+## Development Commands
+
+### Building and Packaging
+```bash
+# Configure and build from source (requires autotools)
+./configure --prefix=/usr --libexecdir=/usr/lib --sysconfdir=/etc --localstatedir=/var
+make
+
+# Build packages for the current platform
+./Makepkgs --verbose
+
+# Cross-compile for Windows (requires MinGW)
+./Makepkgs --verbose --target mingw64
+
+# Install manually after building
+sudo make install
+```
+
+### Quality Assurance Testing
+```bash
+# Run QA setup validation
+qa/admin/check-vm
+
+# Install dependencies for your platform
+qa/admin/list-packages -m
+
+# Run all QA tests
+cd qa && ./check
+
+# Run specific tests
+cd qa && ./check 000        # Run test 000
+cd qa && ./check 100-200    # Run tests 100-200
+cd qa && ./check -g pmcd    # Run pmcd group tests
+
+# Create new test
+cd qa && ./new
+
+# Remake expected output for a test
+cd qa && ./remake 123
+```
+
+### PMCD Service Management
+```bash
+# Start the PCP daemon
+sudo systemctl start pmcd
+# or
+sudo service pmcd start
+
+# Check PCP metrics
+pminfo -dfmt
+pmprobe -v
+```
+
+## High-Level Architecture
+
+### Core Components
+
+- **libpcp**: Main PCP library providing core functionality
+- **pmcd**: Performance Metrics Collection Daemon - central coordinator
+- **pmlogger**: Performance data logging daemon
+- **pmie**: Performance Metrics Inference Engine - rule-based monitoring
+- **pmproxy**: Web API proxy and time series interface
+
+### Tool Categories
+
+1. **Data Collection Tools**: pmcd, pmlogger, various pmdas
+2. **Data Export Tools**: pcp2arrow, pcp2elasticsearch, pcp2json, etc.
+3. **Analysis Tools**: pminfo, pmval, pmstat, pmchart, pmrep and pcp subtools
+4. **Archive Tools**: pmlogdump, pmlogextract, pmlogrewrite, pmlogsummary
+5. **Administrative Tools**: pmconfig, pmlc, pmafm, pmcheck
+
+### PMDAs (Performance Metrics Domain Agents)
+
+PMDAs collect metrics from specific subsystems. Key directories in `src/pmdas/`:
+
+- **Platform PMDAs**: linux, darwin, aix, windows - core system metrics
+- **Application PMDAs**: apache, mysql, postgres, mongodb, elasticsearch
+- **System PMDAs**: bpf, bpftrace, nvidia, amdgpu
+- **Network PMDAs**: cisco, bind2, apache, nginx
+- **Storage PMDAs**: dm, nfsclient, gluster, xfs
+- **Development PMDAs**: sample, simple, trivial - for testing and examples
+
+### Library Structure
+
+- **libpcp**: Core library with platform abstractions
+- **libpcp_pmda**: PMDA development framework
+- **libpcp_pmcd**: PMCD-specific functionality
+- **libpcp_gui**: GUI toolkit integration
+- **libpcp_web**: Web API and time series support
+- **libpcp_trace**: Event trace instrumentation
+- **libpcp_import**: Data import for PCP archives
+
+## Available Agents
+
+- `pcp-code-reviewer` - Reviews code against PCP project standards (whitespace, naming, structure, PCP patterns)
+
+## Development Guidelines
+
+### QA Testing Philosophy
+- All changes should include appropriate QA tests
+- Tests should be deterministic and portable across platforms
+- Use existing archives and filtering functions where possible
+- Tests run as non-root user with sudo for privileged operations
+
+### PMDA Development
+- Use `src/pmdas/simple` or `src/pmdas/sample` as starting templates
+- Follow the Install/Remove script patterns in existing PMDAs
+- PMDAs can be written in C, Python, or Perl
+
+### Code Conventions
+- Follow existing code style in surrounding files
+- Add permanent diagnostics using pmDebugOptions framework
+- Use GPL-compatible licensing for all contributions
+- Never introduce code that logs or exposes secrets
+
+## Testing Requirements
+
+### Prerequisites
+- PCP must be installed (not run from source tree)
+- User "pcp" must exist for services
+- User "pcpqa" used for testing via pcp-testsuite package
+- Sudo access required for privileged operations
+
+### Essential QA Commands
+```bash
+# First-time setup validation
+cd qa && ./check 000
+
+# Check specific functionality
+cd qa && ./check -g pmcd    # PMCD tests
+cd qa && ./check -g pmda    # PMDA tests
+cd qa && ./check -g archive # Archive tests
+```
+
+### Platform Support
+PCP supports Linux, macOS, Windows (MinGW), AIX, and Solaris. Tests should be written to be portable or use `_notrun()` for platform-specific limitations.
+
+## macOS Development (Darwin Platform Only)
+
+When developing on macOS (`Platform: darwin` in environment):
+
+### Critical Constraints
+
+1. **Stage changes before VM tests**
+   - The Tart VM accesses the filesystem directly — `git add` is the minimum required
+   - Unstaged changes in `src/pmdas/darwin*` AND `build/mac/` are INVISIBLE to the VM
+   - A full commit also works; either way, run `/macos-qa-test` after staging
+
+2. **Test environments**
+   - Unit tests: Run locally (no PCP needed)
+   - Integration tests: Tart VM only (`/macos-qa-test`)
+
+### macOS-Specific Agent
+
+- `macos-darwin-pmda-qa` - Runs integration tests in isolated Tart VM
+
+### Quick Start
+```bash
+./Makepkgs --verbose              # One-time: full build (5-30 min)
+cd build/mac/test && ./run-all-tests.sh  # Daily: build + test (20-30s)
+```
+
+### Key Directories
+
+| Directory | Purpose |
+|-----------|---------|
+| `build/mac/` | Test orchestration, PKG packaging, Tart VMs |
+| `dev/darwin/` | Quick-compile tools (~10s vs 30min) |
+| `src/pmdas/darwin/` | Darwin PMDA source code |
+| `src/pmdas/darwin_proc/` | Darwin process PMDA source |
+
+### Documentation
+
+- `build/mac/CLAUDE.md` - Development workflow, test commands
+- `build/mac/MACOS_DEVELOPMENT.md` - Tart VM clean-room builds
+
+## Nix Development
+
+Nix packaging is provided via `flake.nix` and the `build/nix/` directory.
+See `docs/HowTos/nix/index.rst` for full documentation.
+
+```bash
+nix build              # Build PCP package
+nix develop            # Development shell
+nix flake show         # List all packages and apps
+```