Skip to content

Latest commit

 

History

History
107 lines (89 loc) · 4.98 KB

AGENTS.md

File metadata and controls

107 lines (89 loc) · 4.98 KB

AGENTS.md

Mission and North Star

  • PID Pal explains running processes in plain, calm, educational language.
  • System truth is non-negotiable: never invent process facts or behaviors.
  • LLMs are interpreters, not authorities; prefer "likely" and say when unsure.
  • The tool is read-only; do not add features that modify or terminate processes.

Architecture Guardrails

  • Keep the three layers cleanly separated:
    • Observation (src/pidpal/core/observer.py, src/pidpal/platform/): deterministic data collection only.
    • Interpretation (src/pidpal/core/interpreter.py, src/pidpal/knowledge/): heuristics and curated facts.
    • Explanation (src/pidpal/core/explainer.py, src/pidpal/llm/): human language, LLM optional.
  • Avoid coupling layers (no heuristics in observers, no system calls in explainers).
  • Degrade gracefully without LLM access; fallback output should remain useful.
  • Prefer cross-platform patterns even when only Linux is implemented today.

Repo Map

  • Core pipeline: src/pidpal/core/observer.py, src/pidpal/core/interpreter.py, src/pidpal/core/explainer.py
  • Shared actions: src/pidpal/core/actions.py (reusable functions for both CLI modes)
  • Platform adapters: src/pidpal/platform/
  • Knowledge base: src/pidpal/knowledge/binaries.json, src/pidpal/knowledge/heuristics.py
  • LLM providers: src/pidpal/llm/
  • CLI: src/pidpal/ui/cli.py (entry point, classic mode)
  • Interactive: src/pidpal/ui/interactive.py (guided mode wizard)
  • Formatting: src/pidpal/ui/formatter.py
  • Config and cache: src/pidpal/utils/config.py, src/pidpal/utils/cache.py
  • Docs: docs/architecture.md, docs/ROADMAP.md, docs/usage.md, docs/quickstart.md
  • Tests: tests/unit/, tests/integration/ (includes test_guided_mode.py)
  • Scripts: scripts/test.sh, scripts/build.sh, scripts/setup-github-project.sh

Current Status (Post-MVP)

Completed:

  • MVP v0.1.0 features (issues #7-#15)
  • Epic #19: Guided Mode (issues #20-#24)
    • Shared actions module (core/actions.py)
    • Guided mode wizard (ui/interactive.py)
    • CLI routing with --interactive and --no-interactive flags
    • Integration tests for guided mode
    • Documentation updates

Next Up:

  • Epic #26: Token & Cost Observability (issues #27-#32)
  • Issue #17: GitHub Actions CI/CD pipeline

CLI Modes

PID Pal supports two modes:

  1. Classic mode: pidpal <PID> - Single command, immediate output
  2. Guided mode: pidpal (no args) or --interactive - Menu-driven wizard

Use --no-interactive to force classic mode in scripts.

Implementation Standards

  • Python 3.10+, type hints where practical, dataclasses for data models.
  • Keep line length at 100 (Black) and run ruff for linting.
  • Add or update tests with behavior changes; keep fixtures small and readable.
  • Favor clear error messages at the CLI boundary; avoid tracebacks in normal mode.
  • When adding knowledge entries, keep descriptions factual and non-alarmist.

LLM and Safety Guidelines

  • Do not send secrets to LLMs; sanitize or omit sensitive env/config data.
  • Prompts must cite observable facts and avoid overconfident claims.
  • Never claim security guarantees or threat assessments without evidence.
  • If an explanation is uncertain, say so plainly.

Working Agreements for Agents

  • Start from the vision doc: PID Pal — Vision, Purpose, and Instruction Set.md.
  • Keep changes focused; avoid refactors unless they unblock work.
  • Update docs and examples when user-facing behavior changes.
  • If a task requires system access or privileged actions, ask explicitly first.

Definition of Done

  • Behavior change covered by unit or integration tests where feasible.
  • CLI output changes are reflected in docs/usage.md or examples/sample_outputs.md.
  • LLM prompt changes reviewed for tone, evidence-based language, and uncertainty.
  • No new hardcoded paths or OS-specific assumptions without platform guards.
  • Error messages are user-friendly and surfaced at the CLI boundary.

Working Procedure (Recommended)

  • Prefer issues/epics as the source of truth for scope and acceptance criteria.
  • Create a focused branch (feature/, fix/, docs/, test/, refactor/).
  • Implement smallest viable change, then iterate with tests/docs.
  • Run relevant checks locally before sharing changes.
  • Note limitations or follow-ups when leaving TODOs.

Testing Expectations

  • Unit tests for core logic changes: tests/unit/.
  • Integration tests for CLI behavior: tests/integration/.
  • Mock external dependencies (psutil, LLM APIs) in unit tests.
  • Avoid network calls in tests; use fixtures and stubs.

PR Checklist (Quick)

  • Scope is aligned to an issue or clearly justified.
  • Tests added or updated; skipped tests explained.
  • Docs/examples updated if user-facing behavior changed.
  • Lint/format pass locally (black, ruff).
  • No secrets or private data in logs, prompts, or fixtures.

Suggested Local Commands

  • Tests: pytest tests/
  • Format: black src/ tests/
  • Lint: ruff check src/ tests/
  • Type check: mypy src/pidpal
  • Build: scripts/build.sh