Skip to content

AGENTS.md

Latest commit

 

History

History
465 lines (327 loc) · 18.9 KB

AGENTS.md

File metadata and controls

465 lines (327 loc) · 18.9 KB
Raw

sysprims - AI Agent Guide

Read First

  1. READ REPOSITORY_SAFETY_PROTOCOLS.md IMMEDIATELY - this library kills processes; incorrect code kills everything
  2. Check for local guidance if present (e.g. AGENTS.local.md) — machine-specific instructions and tactical session overrides. Local context is kept out of the working tree on purpose; a .gitignore entry is a convenience filter, not a security boundary.
  3. Read MAINTAINERS.md for contacts and governance
  4. Review this document for operational protocols
  5. Understand: this is a Rust library with cross-language bindings - correctness is paramount

WARNING: This repository contains process control code. Tests that use incorrect PIDs can terminate system processes including Finder, Terminal, and init. See ADR-0011 for a real incident where u32::MAX caused kill(-1, SIGTERM) and crashed a desktop session.

Operating Model

Aspect Setting
Mode Supervised (human reviews before commit)
Classification code-substantive, security-sensitive
Role Required Yes
Default Role devlead
Identity Per session (no persistent memory)

This repository is classified as security-sensitive because:

  • Process control utilities can affect system stability
  • FFI boundary requires careful memory safety
  • Signal handling has security implications
  • Cross-platform behavior must be predictable

See agent-identity standard for modes and attribution.

Project Overview

sysprims is a GPL-free, cross-platform process utilities library implemented in Rust with first-class bindings for Go, Python, and TypeScript.

Core differentiator: Group-by-default process tree management - when you timeout a process, the entire tree dies.

Key principle: Reliable process control without license toxicity.

Quick Reference

Task Command
Build cargo build
Test cargo test
Format cargo fmt
Lint cargo clippy
License check cargo deny check
Security audit cargo audit
Full check make check

Session Protocol

Before Changes

  • Read relevant code and ADRs first
  • Read RELEASE_CHECKLIST.md before any release-related work — prebuilt native libraries (Go .a files, TypeScript .node files) are built by CI workflows, NOT locally. Do not manually build or commit prebuilt binaries; instead dispatch the appropriate CI workflow per the checklist.
  • Understand cross-platform implications of changes
  • Keep changes minimal and focused
  • Consider FFI boundary impacts

Before Committing

  • Run cargo fmt && cargo clippy (or make check)
  • Run cargo test on available platforms
  • Run cargo deny check licenses
  • Verify no unintended changes with git diff
  • Use proper commit attribution (see below)

Commit Attribution

Follow 3leaps commit style:

<type>(<scope>): <subject>

<body>

Generated by <Model> via <Interface> under supervision of @<maintainer>

Co-Authored-By: <Model> <noreply@3leaps.net>
Role: <role>
Committer-of-Record: @<maintainer>

Attribution email policy: All AI model Co-Authored-By trailers MUST use noreply@3leaps.net as the email address, regardless of model vendor. This prevents third-party email squatting on GitHub's contributor attribution. The model name in the name field provides the transparency; the email is plumbing under our control. Do NOT use vendor noreply addresses (noreply@anthropic.com, noreply@openai.com, etc.).

Example:

feat(timeout): implement Job Object fallback on Windows

Adds fallback behavior when Job Object creation fails due to
privilege limits or nested Job Objects.

Changes:
- Add tree_kill_reliability field to TimeoutOutcome
- Implement best-effort termination fallback
- Add observable degradation in JSON output

Generated by Claude Sonnet via Claude Code under supervision of @3leapsdave

Co-Authored-By: Claude Sonnet <noreply@3leaps.net>
Role: devlead
Committer-of-Record: @3leapsdave

Safety Protocols (MANDATORY)

This library terminates processes. Read REPOSITORY_SAFETY_PROTOCOLS.md in full.

Pre-Flight Checklist for Signal-Sending Code

Before writing or modifying any code that sends signals or terminates processes (sysprims-signal, sysprims-timeout):

  • I have read ADR-0011: PID Validation Safety
  • I understand u32::MAX as i32 == -1 (integer overflow)
  • I understand kill(-1, sig) broadcasts to ALL processes
  • My tests use safe PIDs: 99999, std::process::id(), or spawned children
  • I am NOT using PID 0, PID 1, or u32::MAX in tests
  • I am NOT bypassing public API validation without explicit justification

Dangerous PID Reference

Value Cast to i32 POSIX Semantics Safety
0 0 Signal caller's process group FORBIDDEN
1 1 Signal init/launchd FORBIDDEN
u32::MAX -1 Signal ALL processes CATASTROPHIC
> i32::MAX Negative Various broadcast semantics FORBIDDEN

If unsure, ask the maintainer before running tests.

DO / DO NOT

DO

  • Run cargo fmt && cargo clippy before commits
  • Read files before editing them
  • Keep changes focused on the task
  • Run tests on all available platforms before PRs
  • Document platform-specific behavior
  • Consider FFI memory safety implications
  • Reference ADRs when making architectural decisions
  • Use #[cfg(unix)] and #[cfg(windows)] appropriately

DO NOT

  • Push without maintainer approval
  • Skip quality gates or license checks
  • Commit secrets or credentials
  • Add GPL/LGPL/AGPL dependencies
  • Touch code outside task scope without justification
  • Change FFI contracts without ADR review
  • Use unsafe without clear justification and review
  • Assume platform behavior without testing
  • Add local planning paths, board names, or planning IDs to tracked content — planning artifacts live in a private, maintainer-managed system kept outside the repository tree; a .gitignore entry is a convenience filter, not a security boundary
  • Commit AGENTS.local.md or other local guidance — it is kept out of the tree as defense-in-depth, not because a .gitignore entry makes it safe
  • Use PID 0, 1, or u32::MAX in signal-sending tests (see Safety Protocols above)
  • Bypass PID validation in signal code without explicit maintainer approval
  • Run signal-sending tests without verifying target PIDs are safe
  • Locally build or commit prebuilt native libraries (Go .a/.so/.dylib, TypeScript .node) — these come from CI workflows (go-bindings.yml, typescript-napi-prebuilds.yml); see RELEASE_CHECKLIST.md

Critical Rules

Never Push Without Approval

Git push operations require explicit, per-incident human maintainer approval:

git add <files>       # OK
git commit -m "..."   # OK
git push              # NEVER without explicit approval

License Compliance

All dependencies must pass cargo deny check:

cargo deny check licenses    # Must pass
cargo deny check advisories  # Must pass

See ADR-0001 for allowed licenses.

FFI Safety

FFI boundary changes require extra scrutiny:

  • Memory ownership must be explicit
  • All returned strings freed via sysprims_free_string()
  • No complex structs across FFI (JSON strings only)
  • See ADR-0004

Platform Parity

Changes must consider all supported platforms. See Platform Support Matrix for the canonical reference:

  • Linux x64/arm64 (glibc + musl)
  • macOS arm64 (Intel Macs are not supported as of v0.1.7)
  • Windows x64

See also ADR-0007 for the abstraction strategy.

Key Files

Path Purpose
REPOSITORY_SAFETY_PROTOCOLS.md MANDATORY - Process control safety rules
RELEASE_CHECKLIST.md Release workflow with validation steps
config/agentic/roles/ In-repo role definitions
docs/standards/platform-support.md Canonical platform matrix - 6 supported platforms
crates/sysprims-core/ Shared types, errors, telemetry
crates/sysprims-timeout/ Process timeout with group-by-default
crates/sysprims-signal/ Signal dispatch and process groups
crates/sysprims-proc/ Process inspection and enumeration
crates/sysprims-cli/ CLI binaries
ffi/sysprims-ffi/ C-ABI exports via cbindgen
bindings/ Go, Python, TypeScript wrappers
docs/decisions/ Decision Records (ADR, DDR, SDR)
docs/safety/ Safety guides (signal dispatch, etc.)
docs/standards/ Repository conventions and policies
deny.toml License and security policy

Roles

Role definitions live in config/agentic/roles/ - all roles are in-repo with sysprims-specific customizations extending crucible baselines.

Role Source Focus
devlead in-repo Implementation, FFI, safety
deliverylead in-repo Readiness, delivery coordination
secrev in-repo Security, PID validation, FFI
qa in-repo Testing, cross-platform
releng in-repo CI/CD + platform validation
cicd in-repo Pipelines, runners, matrix
infoarch in-repo Docs, schemas, standards
ffiarch Project-specific (see below) Bindings, cross-language
entarch Project-specific (see below) Ecosystem integration

Role: releng

Source: config/agentic/roles/releng.yaml

Extends crucible releng baseline with CI/CD platform validation focus. This is the key role for adoption velocity.

Additional Scope

  • CI/CD workflow validation before push (actionlint, shellcheck)
  • Platform matrix enforcement (Platform Support Matrix)
  • Runner availability verification (no deprecated runners)
  • Cross-repository release coordination (Go, TypeScript, Python bindings)

Pre-Push Checklist

  • Run actionlint on all modified workflows
  • Run shellcheck on shell scripts in workflows
  • Verify runners are not deprecated
  • Confirm platform matrix matches docs/standards/platform-support.md
  • Ensure local/remote git sync before release workflows

Does Not

  • Push without running pre-push validation
  • Dismiss CI failures as "transient" without investigation
  • Use deprecated runners without checking availability
  • Release with incomplete platform coverage

Role: devlead

Source: config/agentic/roles/devlead.yaml

Default role for implementation. Extended with sysprims safety protocols and cross-platform focus.

Key Extensions

  • Rust implementation across all crates
  • Cross-platform abstraction layer (6 platforms)
  • FFI boundary implementation
  • PID safety validation (never use 0, 1, u32::MAX)

Role: deliverylead

Source: config/agentic/roles/deliverylead.yaml

Delivery coordination — readiness assessments, spec-brief reconciliation, milestone tracking, and release gating.

Key Extensions

  • Spec-brief vs codebase reconciliation at each milestone
  • Cross-crate delivery dependency tracking (core → proc → signal → timeout → cli → ffi → bindings)
  • 6-platform matrix verification per release
  • Safety protocol compliance gating (PID safety, signal-sending code review)
  • Binding release coordination (Go, TypeScript, Python)
  • Wave-based delivery planning and backlog grooming

Does Not

  • Write production code (coordinates devlead)
  • Make technical architecture decisions
  • Route individual sessions (that's dispatch)
  • Commit to dates without quality gate verification

Role: secrev

Source: config/agentic/roles/secrev.yaml

Security review with emphasis on FFI safety and PID validation.

Key Extensions

  • FFI boundary security review
  • PID validation review (ADR-0011)
  • Memory safety review for unsafe code
  • Signal handling security implications

Role: qa

Source: config/agentic/roles/qa.yaml

Testing and quality assurance with cross-platform focus.

Key Extensions

  • Cross-platform test coverage (6 platforms)
  • Tree escape integration tests
  • FFI conformance tests
  • Safe PID usage verification in tests

Role: cicd

Source: config/agentic/roles/cicd.yaml

Pipeline automation with platform matrix focus.

Key Extensions

  • Multi-platform build matrix (6 platforms)
  • Runner selection and availability verification
  • Pre-push validation (actionlint, shellcheck)
  • Cross-compilation with Zig

Role: infoarch

Source: config/agentic/roles/infoarch.yaml

Documentation and standards with platform focus.

Key Extensions

  • Platform support documentation
  • Language bindings documentation
  • Safety documentation maintenance

Role: ffiarch

FFI Architect - Bindings design and cross-language integration.

Scope

  • C-ABI design and cbindgen configuration
  • Language binding implementation (Go, Python, TypeScript)
  • Memory ownership contracts across FFI
  • JSON schema contracts for bindings

Responsibilities

  • Design stable FFI interfaces
  • Implement binding packages
  • Maintain memory safety across language boundaries
  • Document binding usage patterns

Escalates To

  • devlead for Rust-side changes
  • Maintainers for ABI breaking changes
  • secrev for FFI security review

Does Not

  • Change core Rust implementation (bindings only)
  • Skip FFI conformance tests
  • Introduce platform-specific binding behavior without documentation

Role: entarch

Enterprise Architect - Cross-system integration and Fulmen ecosystem alignment.

Scope

  • Crucible schema integration
  • Fulmen library integration (rsfulmen, gofulmen, pyfulmen, tsfulmen)
  • Enterprise deployment patterns
  • Cross-repository coordination

Responsibilities

  • Ensure schema contracts align with Crucible SSOT
  • Coordinate with Fulmen ecosystem libraries
  • Design enterprise integration patterns
  • Document migration paths

Escalates To

  • Maintainers for cross-repository decisions
  • devlead for implementation details
  • dispatch for multi-session coordination

Does Not

  • Implement features (architecture only)
  • Change schemas without Crucible coordination
  • Make unilateral cross-repo decisions

ADR Reference

Key architectural decisions:

ADR Title Relevance
0001 License Policy Dependency decisions
0002 Crate Structure Module organization
0003 Group-by-Default Core differentiator
0004 FFI Design Binding architecture
0005 Schema Contracts JSON output stability
0006 Dependency Governance SBOM and compliance
0007 Platform Abstraction Cross-platform strategy
0008 Error Handling Error taxonomy
0011 PID Validation Safety CRITICAL - Prevents kill(-1) disasters

Standards Reference

Planning Artifacts

  • Feature briefs, task boards, and operational notes live in a private, maintainer-managed planning system kept outside this repository tree — not in-tree behind .gitignore, which is a convenience filter, not a security boundary. This conforms to the 3 Leaps OSS Sensitive Local Data Policy.
  • Do not add local planning paths, board names, or planning IDs to tracked repo content (code, docs, comments, commit messages, PR text).

Contact

Last Updated: January 27, 2026