From 54a55b42717e17477f30f19a74c7bab1e01b7ff5 Mon Sep 17 00:00:00 2001 From: "Andrei G." Date: Sun, 7 Jun 2026 00:36:16 +0200 Subject: [PATCH 1/2] docs(agents): track all AGENTS.md guides and refresh review instructions Force-add every AGENTS.md in the repository (root, directory-level, and all 31 crate guides) so coding/review agents pick up path-specific instructions from version control instead of local-only files. These were previously untracked because AGENTS.md is globally ignored. Add the seven previously missing crate guides: zeph-agent-context, zeph-agent-feedback, zeph-agent-persistence, zeph-agent-tools, zeph-durable, zeph-plugins, and zeph-worktree, matching the existing per-crate format with crate-local checks, invariants, gates, and spec references. Refresh .github/copilot-instructions.md: correct the crate count, fix the feature-gated crate list, and document the agent-pipeline and zeph-durable dependency invariants. --- .github/AGENTS.md | 8 +++ .github/copilot-instructions.md | 6 +- AGENTS.md | 91 +++++++++++++++++++++++++ book/AGENTS.md | 8 +++ config/AGENTS.md | 8 +++ crates/AGENTS.md | 8 +++ crates/zeph-a2a/AGENTS.md | 8 +++ crates/zeph-acp/AGENTS.md | 8 +++ crates/zeph-agent-context/AGENTS.md | 11 +++ crates/zeph-agent-feedback/AGENTS.md | 10 +++ crates/zeph-agent-persistence/AGENTS.md | 11 +++ crates/zeph-agent-tools/AGENTS.md | 11 +++ crates/zeph-bench/AGENTS.md | 8 +++ crates/zeph-channels/AGENTS.md | 9 +++ crates/zeph-commands/AGENTS.md | 8 +++ crates/zeph-common/AGENTS.md | 8 +++ crates/zeph-config/AGENTS.md | 9 +++ crates/zeph-context/AGENTS.md | 9 +++ crates/zeph-core/AGENTS.md | 11 +++ crates/zeph-db/AGENTS.md | 9 +++ crates/zeph-durable/AGENTS.md | 11 +++ crates/zeph-experiments/AGENTS.md | 8 +++ crates/zeph-gateway/AGENTS.md | 9 +++ crates/zeph-index/AGENTS.md | 8 +++ crates/zeph-llm/AGENTS.md | 10 +++ crates/zeph-mcp/AGENTS.md | 8 +++ crates/zeph-memory/AGENTS.md | 10 +++ crates/zeph-orchestration/AGENTS.md | 9 +++ crates/zeph-plugins/AGENTS.md | 13 ++++ crates/zeph-sanitizer/AGENTS.md | 9 +++ crates/zeph-scheduler/AGENTS.md | 8 +++ crates/zeph-skills/AGENTS.md | 9 +++ crates/zeph-subagent/AGENTS.md | 9 +++ crates/zeph-tools/AGENTS.md | 8 +++ crates/zeph-tui/AGENTS.md | 8 +++ crates/zeph-vault/AGENTS.md | 9 +++ crates/zeph-worktree/AGENTS.md | 10 +++ docker/AGENTS.md | 8 +++ src/AGENTS.md | 9 +++ tests/AGENTS.md | 8 +++ 40 files changed, 438 insertions(+), 2 deletions(-) create mode 100644 .github/AGENTS.md create mode 100644 AGENTS.md create mode 100644 book/AGENTS.md create mode 100644 config/AGENTS.md create mode 100644 crates/AGENTS.md create mode 100644 crates/zeph-a2a/AGENTS.md create mode 100644 crates/zeph-acp/AGENTS.md create mode 100644 crates/zeph-agent-context/AGENTS.md create mode 100644 crates/zeph-agent-feedback/AGENTS.md create mode 100644 crates/zeph-agent-persistence/AGENTS.md create mode 100644 crates/zeph-agent-tools/AGENTS.md create mode 100644 crates/zeph-bench/AGENTS.md create mode 100644 crates/zeph-channels/AGENTS.md create mode 100644 crates/zeph-commands/AGENTS.md create mode 100644 crates/zeph-common/AGENTS.md create mode 100644 crates/zeph-config/AGENTS.md create mode 100644 crates/zeph-context/AGENTS.md create mode 100644 crates/zeph-core/AGENTS.md create mode 100644 crates/zeph-db/AGENTS.md create mode 100644 crates/zeph-durable/AGENTS.md create mode 100644 crates/zeph-experiments/AGENTS.md create mode 100644 crates/zeph-gateway/AGENTS.md create mode 100644 crates/zeph-index/AGENTS.md create mode 100644 crates/zeph-llm/AGENTS.md create mode 100644 crates/zeph-mcp/AGENTS.md create mode 100644 crates/zeph-memory/AGENTS.md create mode 100644 crates/zeph-orchestration/AGENTS.md create mode 100644 crates/zeph-plugins/AGENTS.md create mode 100644 crates/zeph-sanitizer/AGENTS.md create mode 100644 crates/zeph-scheduler/AGENTS.md create mode 100644 crates/zeph-skills/AGENTS.md create mode 100644 crates/zeph-subagent/AGENTS.md create mode 100644 crates/zeph-tools/AGENTS.md create mode 100644 crates/zeph-tui/AGENTS.md create mode 100644 crates/zeph-vault/AGENTS.md create mode 100644 crates/zeph-worktree/AGENTS.md create mode 100644 docker/AGENTS.md create mode 100644 src/AGENTS.md create mode 100644 tests/AGENTS.md diff --git a/.github/AGENTS.md b/.github/AGENTS.md new file mode 100644 index 000000000..01a44b7fa --- /dev/null +++ b/.github/AGENTS.md @@ -0,0 +1,8 @@ +# GitHub Automation Guide + +This directory contains CI, release, and repository automation files. + +- Keep workflow commands aligned with the actual supported local commands in the repository. +- Prefer explicit, reproducible CI steps over clever shell tricks. +- If you change checks, matrix entries, release flow, or badges, update the relevant docs and README references. +- Treat permission scopes, tokens, and supply-chain settings as security-sensitive. diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 01bcf2ccb..2494e958f 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -6,12 +6,14 @@ applyTo: "**" ## Project Context -Zeph is a Rust AI agent workspace (Edition 2024, resolver 3) with 10 crates. Review all changes against these standards. +Zeph is a Rust AI agent workspace (Edition 2024, resolver 3) with 31 library crates under `crates/` plus the `zeph` CLI binary. Review all changes against these standards. ## Architecture Rules - `zeph-core` orchestrates all leaf crates; no reverse dependencies allowed -- `zeph-a2a`, `zeph-mcp`, `zeph-tui` are feature-gated and optional +- `zeph-agent-context`, `zeph-agent-persistence`, and `zeph-agent-tools` MUST NOT depend on `zeph-core` — the dependency runs `zeph-core` → these crates, never the reverse; flag any new `zeph-core` import added to them +- `zeph-durable` is a Layer-0 infra crate (alongside `zeph-db`, `zeph-common`); it MUST NOT depend on `zeph-llm`, `zeph-memory`, `zeph-core`, `zeph-sanitizer`, or any business-layer crate +- `zeph-tui`, `zeph-a2a`, `zeph-acp`, `zeph-gateway`, `zeph-scheduler`, and `zeph-bench` are feature-gated and optional - All dependencies defined in root `[workspace.dependencies]` with no features at workspace level - Crates inherit via `workspace = true` and specify features locally - TLS: `rustls` only — reject any `openssl-sys` introduction diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..d17a6c7fe --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,91 @@ +# Repository Guidelines + +## Project Structure & Module Organization +Zeph is a Rust workspace (`Cargo.toml`) with the CLI entrypoint in `src/` and domain crates in `crates/` (for example: `zeph-core`, `zeph-llm`, `zeph-memory`, `zeph-tools`, `zeph-tui`). +Top-level integration tests live in `tests/`, while crate-specific tests and benches live under each crate’s `tests/` and `benches/` directories. Documentation sources are in `docs/src/` (mdBook), runtime defaults are in `config/default.toml`, and container assets are in `docker/`. +Do not create git worktrees inside this repository. Create separate worktrees only under the sibling directory `../worktrees/`. + +## Specifications (MANDATORY) + +All feature and system specifications live in `specs/`. **Compliance is non-negotiable.** + +- **Before implementing any feature**: read the relevant spec in `specs/` and the system + invariants in `specs/001-system-invariants/spec.md`. +- **Before modifying any subsystem**: read the corresponding spec document. The `## Key Invariants` + and `NEVER` sections define hard constraints — violating them requires an explicit architectural + decision, not just a code review. +- **Index**: `specs/README.md` — maps every subsystem to its spec file. +- **Constitution**: `specs/constitution.md` — project-wide non-negotiable rules that apply to every change. +- If a spec is missing or outdated for the area you are changing, create or update it before writing code. + +## Agent Operating Notes + +`AGENTS.md` is the primary instruction file for all coding agents (Codex, Copilot, etc.). `.claude/CLAUDE.md` and `.claude/rules/*` are Claude-specific or supplemental context — not the primary source of operating rules. +Path-specific instructions for GitHub Copilot live in `.github/instructions/*.instructions.md` with `applyTo` frontmatter. + +- Use `cargo nextest run` as the default test runner. +- Keep Rust changes compatible with Edition 2024 and MSRV `1.88`. +- Prefer zero-warning `clippy`; avoid `unwrap`/`expect` in production code when proper error propagation is possible. +- Any user-facing change must update relevant docs, config defaults, and `CHANGELOG.md` (`[Unreleased]` section). +- For new functionality, provide all integration points: config section, CLI subcommand/argument, TUI command palette entry, `--init` wizard, `--migrate-config` migration step, live testing playbook in `.local/testing/playbooks/`, and coverage row in `.local/testing/coverage-status.md`. +- In the TUI, every background operation (LLM inference, memory search, tool execution, MCP connection, etc.) must have a visible spinner with a short, descriptive status message. + +## Multi-Model Design + +All new functionality must be designed for multi-model operation. Match models to task complexity: + +- **Simple tasks** (entity extraction, embeddings, classification, routing): fast, cheap models (e.g. `gpt-4o-mini`, `qwen3:8b`). +- **Medium tasks** (summarization, compaction, skill matching): mid-tier models. +- **Complex tasks** (planning, code generation, multi-step reasoning): most capable models (e.g. `claude-opus-4`). + +All providers declared once in `[[llm.providers]]` with a `name` field. Subsystems reference a provider by name via a single `*_provider` field — no inline provider config duplication. When the field is empty, fall back to the default provider. Never hardcode a model name. + +## Secrets & Vault + +All secrets and API keys are stored exclusively in the Zeph age vault. Never use environment variables, `.env` files, or shell profiles for secrets. All `ZEPH_*` keys are resolved automatically from the age vault at startup. To read a key for external scripts: `cargo run --features full -- vault get `. + +## Continuous Improvement Protocol +- Continuous-improvement sessions are read-only: use them for live manual testing, anomaly detection, research, dependency review, and issue triage; do not make code changes in those sessions. +- Do not treat unit/integration tests as sufficient validation for user-facing or agent-loop changes. Run real end-to-end agent sessions with real LLM/tool execution via `cargo run --features full -- --config .local/config/testing.toml` and use `--tui` or `RUST_LOG=debug` when needed. +- For continuous-improvement and ACP/IDE test runs, override runtime artifact paths in the active config to absolute temporary locations so logs, SQLite state, debug dumps, audit files, and other ephemeral outputs land under a dedicated temp directory instead of polluting the default user data directories. Prefer a per-session root such as `/tmp/zeph-ci//`. +- At minimum, override `logging.file`, `memory.sqlite_path`, `debug.output_dir`, and any other runtime-writing paths used by the scenario under test to absolute temp paths before launching the agent. +- After each live test session, review the resolved debug dump and log directories from the active config, plus metrics and agent responses, for correctness, regressions, retries, timeouts, hallucinations, and tool-use quality. +- Treat the configured runtime artifact directory as the primary evidence location for live runs: request/response payloads in the configured debug dump directory and runtime traces in the configured log directory should be checked before drawing conclusions from terminal output alone. +- For GonkaGate continuous-improvement runs, use `.local/config/testing-gonkagate.toml`. It must resolve `ZEPH_COMPATIBLE_GONKAGATE_API_KEY` from the age vault only, target `https://api.gonkagate.com/v1`, use `Qwen/Qwen3-235B-A22B-Instruct-2507-FP8`, and keep logs/debug/SQLite/audit artifacts under `/tmp/zeph-ci/gonkagate`. +- Record every session in `.local/testing/journal.md`, including positive confirmations, failures, scope, config used, and component status. When behavior changes, reset the affected component to untested until re-verified. +- When you find an anomaly, reproduce it, classify severity, and file a GitHub issue with clear repro steps and expected vs actual behavior. Fixes must happen later in a dedicated implementation session, not during the continuous-improvement pass. +- Testing is a hard gate: when many components are untested or a batch of core changes landed, prioritize live validation before research, dependency updates, or new feature work. +- Keep the test environment clean when relevant: clear the temporary runtime artifact directory, test DB state, audit logs, session logs, and overflow files before comprehensive runs; do not delete `.local/testing/`. +- Maintain the testing knowledge base in `.local/testing/`: `journal.md`, `process-notes.md`, `playbooks/`, and `regressions.md`. Add regressions for newly found bugs and capture process improvements after each session. +- Research new agent/testing techniques and monitor dependency health (`cargo outdated --workspace`, `cargo deny check advisories`) as part of the cycle, but only after current critical functionality has been live-tested. + +## Build, Test, and Development Commands +- `cargo build --workspace --features full`: Build the full workspace feature set used in CI. +- `cargo run -- --help`: Run the CLI locally and list commands. +- `cargo nextest run --workspace --lib --bins`: Fast unit/binary test pass. +- `cargo nextest run --config-file .github/nextest.toml --workspace --profile ci --features full`: Full suite with the CI config and full feature set (Docker required). +- `cargo +nightly fmt --check`: Verify formatting. +- `cargo clippy --profile ci --workspace --features full -- -D warnings`: Run CI-equivalent lint checks with the full feature set. +- `cargo llvm-cov --all-features --workspace`: Generate coverage locally. + +## Coding Style & Naming Conventions +Use Rust 2024 edition and MSRV `1.88`. Follow `rustfmt` defaults (4-space indentation) and keep Clippy warnings at zero where practical. +Use `snake_case` for functions/modules/files, `PascalCase` for types/traits, and `SCREAMING_SNAKE_CASE` for constants. Prefer small modules with explicit responsibilities; keep public APIs in `lib.rs` minimal and re-export intentionally. + +## Testing Guidelines +Use `cargo-nextest` as the default runner. Name integration tests with `*_integration.rs` and keep deterministic unit tests close to implementation. +For features touching external systems (for example Qdrant), use container-backed tests and document required services. Add regression tests for every bug fix. + +## Commit & Pull Request Guidelines +Git history follows Conventional Commits with scopes, e.g. `feat(zeph-tools): ...`, `fix: ...`, `ci: ...`. +Keep subject lines imperative and concise, and reference issues/PRs when relevant (`(#736)`). +Before every commit, run the full validation suite against the CI feature set (`--features full` where supported) and do not commit if any step fails: +- `cargo +nightly fmt --check` +- `cargo clippy --profile ci --workspace --features full -- -D warnings` +- `cargo nextest run --config-file .github/nextest.toml --workspace --profile ci --features full` +- `cargo check --workspace --features full` +- `cargo build --workspace --features full` +PRs should include: a clear problem statement, implementation summary, test evidence (commands + results), and docs/config updates when behavior changes. + +## Security & Configuration Tips +Do not commit secrets. All secrets must go through the Zeph age vault (`zeph vault` commands) — never environment variables or `.env` files. Review `SECURITY.md` before changing tool execution, sandboxing, or permission flows. diff --git a/book/AGENTS.md b/book/AGENTS.md new file mode 100644 index 000000000..daed73853 --- /dev/null +++ b/book/AGENTS.md @@ -0,0 +1,8 @@ +# Docs Guide + +This directory holds the mdBook source for Zeph documentation. + +- Keep docs aligned with the current code, config defaults, and CLI behavior. +- When adding or moving pages under `docs/src/`, update `docs/src/SUMMARY.md`. +- Prefer concise, technical documentation over marketing copy in reference and guide pages. +- If a code change affects user-facing behavior, configuration, architecture, or workflows, update the relevant docs in the same change. diff --git a/config/AGENTS.md b/config/AGENTS.md new file mode 100644 index 000000000..f5ce45215 --- /dev/null +++ b/config/AGENTS.md @@ -0,0 +1,8 @@ +# Config Guide + +This directory holds runtime defaults and configuration templates. + +- Treat `config/default.toml` as the source of truth for documented defaults unless a feature explicitly overrides them at runtime. +- Keep config keys, comments, and docs in sync. Config supports `ZEPH_*` env var overrides for non-secret values only — secrets must go through the age vault, never env vars. +- When adding or changing config keys, update the relevant docs and any setup/instruction materials that reference them. +- Preserve readability: keep sections coherent and comments directly attached to the settings they describe. diff --git a/crates/AGENTS.md b/crates/AGENTS.md new file mode 100644 index 000000000..4fd95bc3c --- /dev/null +++ b/crates/AGENTS.md @@ -0,0 +1,8 @@ +# Crates Guide + +This directory contains the workspace crates. The root [`AGENTS.md`](../AGENTS.md) remains the primary instruction file; use local `AGENTS.md` files in individual crates for crate-specific workflow notes. + +- Keep changes local to the crate you are editing unless shared APIs require coordinated updates. +- Default verification is crate-first: `cargo build -p `, `cargo nextest run -p `, then workspace checks only if the change crosses crate boundaries. +- Use `cargo clippy -p --all-targets -- -D warnings` before considering crate-local work done. +- If a crate's public behavior or configuration changes, update the crate `README.md`, root docs in `docs/src/`, and any relevant config or CLI surfaces. diff --git a/crates/zeph-a2a/AGENTS.md b/crates/zeph-a2a/AGENTS.md new file mode 100644 index 000000000..36671bc0a --- /dev/null +++ b/crates/zeph-a2a/AGENTS.md @@ -0,0 +1,8 @@ +# zeph-a2a Guide + +Protocol client/server work for A2A lives here. + +- Start with crate-local checks: `cargo build -p zeph-a2a`, `cargo nextest run -p zeph-a2a`, `cargo clippy -p zeph-a2a --all-targets -- -D warnings`. +- Keep changes isolated to A2A transport, discovery, JSON-RPC, and server behavior unless a shared API truly requires cross-crate edits. +- Preserve protocol-facing behavior unless the task explicitly calls for a spec-aligned change. +- If external behavior changes, update `crates/zeph-a2a/README.md` and the relevant docs in `docs/src/advanced/a2a.md`. diff --git a/crates/zeph-acp/AGENTS.md b/crates/zeph-acp/AGENTS.md new file mode 100644 index 000000000..746ad294e --- /dev/null +++ b/crates/zeph-acp/AGENTS.md @@ -0,0 +1,8 @@ +# zeph-acp Guide + +IDE embedding, ACP transport, permissions, and session handling live here. + +- Start with crate-local checks: `cargo build -p zeph-acp`, `cargo nextest run -p zeph-acp`, `cargo clippy -p zeph-acp --all-targets -- -D warnings`. +- Be careful with session lifecycle, permission gates, HTTP/WebSocket transport, and filesystem/terminal bridging. +- Changes in ACP behavior should stay aligned with the CLI flags in the root binary and with ACP-related docs. +- If user-visible behavior changes, update `crates/zeph-acp/README.md` and the relevant docs in `docs/src/advanced/acp.md` or `docs/src/guides/ide-integration.md`. diff --git a/crates/zeph-agent-context/AGENTS.md b/crates/zeph-agent-context/AGENTS.md new file mode 100644 index 000000000..f68d38918 --- /dev/null +++ b/crates/zeph-agent-context/AGENTS.md @@ -0,0 +1,11 @@ +# zeph-agent-context Guide + +Context-assembly service (`ContextService`): system prompt rebuild, memory injection, semantic recall, summarization, and compaction. A stateless façade extracted from `Agent` so context-assembly edits do not recompile the tool dispatcher or persistence layer. + +- Start with crate-local checks: `cargo build -p zeph-agent-context`, `cargo nextest run -p zeph-agent-context`, `cargo clippy -p zeph-agent-context --all-targets -- -D warnings`. +- Read `specs/021-zeph-context/spec.md` before changing assembly, budget, or compaction behavior; honor its `## Key Invariants` and `NEVER` sections. +- Core invariant: this crate MUST NOT depend on `zeph-core`. The decoupling is the whole point — never add a `zeph-core` dependency to satisfy a borrow. +- Keep the borrow-lens views (`MessageWindowView`, `ContextAssemblyView`, `ContextSummarizationView`) narrow; `zeph-core` constructs them from `Agent` field projections. +- Features: `sqlite` (default) / `postgres` forwarded to `zeph-memory`, plus `index` for `IndexAccess` integration. Run `cargo nextest run -p zeph-agent-context --features index` when touching index-backed assembly views. +- LLM serialization gate: summarization and compaction build LLM request payloads — changes to `summarization/` or `compaction.rs` require a live API session test (no 400/422, well-formed `messages` array in the debug dump) before merge. +- Multi-model: summarization and compaction call an LLM — resolve the provider via a `*_provider` field referencing a named `[[llm.providers]]` entry; never hardcode a model. diff --git a/crates/zeph-agent-feedback/AGENTS.md b/crates/zeph-agent-feedback/AGENTS.md new file mode 100644 index 000000000..fc0ca5b09 --- /dev/null +++ b/crates/zeph-agent-feedback/AGENTS.md @@ -0,0 +1,10 @@ +# zeph-agent-feedback Guide + +Implicit correction detection from user messages: the regex-only `FeedbackDetector` (zero LLM calls) and the LLM-backed `JudgeDetector` for borderline or missed cases. + +- Start with crate-local checks: `cargo build -p zeph-agent-feedback`, `cargo nextest run -p zeph-agent-feedback`, `cargo clippy -p zeph-agent-feedback --all-targets -- -D warnings`. +- Read `specs/016-agent-feedback/spec.md` before changing detection strategy, thresholds, or rate limits. +- Multi-language patterns span 7 languages (en, ru, es, de, fr, zh, ja). Any new or altered pattern needs regression tests for both tiers — anchored (`^`, base confidence) and unanchored (mid-sentence, base − 0.10). Preserve that tier semantics. +- Mind the CJK limitations documented in `lib.rs`: `token_overlap()` uses whitespace tokenisation and does not segment Chinese/Japanese; keep the 2+ character minimum for unanchored CJK patterns to limit false positives. +- Keep regexes compiled once into the flat `Vec<(Regex, f32)>` per correction kind — this is a hot path; never recompile per message. +- Multi-model: `JudgeDetector` calls an LLM — resolve the provider via a `*_provider` field referencing a named `[[llm.providers]]` entry; never hardcode a model. Do not bypass the `judge_rate_limit` / `judge_rate_window_secs` rate limiting from `LearningConfig`. diff --git a/crates/zeph-agent-persistence/AGENTS.md b/crates/zeph-agent-persistence/AGENTS.md new file mode 100644 index 000000000..606809242 --- /dev/null +++ b/crates/zeph-agent-persistence/AGENTS.md @@ -0,0 +1,11 @@ +# zeph-agent-persistence Guide + +Persistence service (`PersistenceService`): loads conversation history from and writes messages to `SemanticMemory` (SQLite + Qdrant), plus tool-pair sanitization, embedding decisions, and graph-extraction configuration. + +- Start with crate-local checks: `cargo build -p zeph-agent-persistence`, `cargo nextest run -p zeph-agent-persistence`, `cargo clippy -p zeph-agent-persistence --all-targets -- -D warnings`. +- Read `specs/057-agent-persistence/spec.md` before changing history loading, persistence, or extraction enqueueing. +- Core invariant: this crate MUST NOT depend on `zeph-core`. Keep the borrow-lens views (`MemoryPersistenceView`, `SecurityView`, `MetricsView`) narrow; `zeph-core` builds them from `Agent` fields. +- Features: `sqlite` (default) / `postgres` forwarded to `zeph-memory` — verify behavior is identical across both backends; silent divergence is a first-class bug. +- LLM serialization gate: tool-pair sanitization (`sanitize.rs`, `request.rs`) controls whether `tool_use`/`tool_result` blocks are well-formed. A malformed pairing causes hard LLM 400/422 errors that unit tests do not catch — changes here require a live multi-turn + tool-call session test before merge. +- Embedding dimension mismatches are a recurring source of bugs: whenever the embedding model or vector collection config changes, verify stored and query vector dimensions match before running tests. +- Multi-model: graph extraction and embedding each call an LLM/embedder — resolve via `*_provider` fields referencing named `[[llm.providers]]` entries; never hardcode a model. diff --git a/crates/zeph-agent-tools/AGENTS.md b/crates/zeph-agent-tools/AGENTS.md new file mode 100644 index 000000000..3f5cc9240 --- /dev/null +++ b/crates/zeph-agent-tools/AGENTS.md @@ -0,0 +1,11 @@ +# zeph-agent-tools Guide + +Tool-dispatch primitives consumed by the tool loop in `zeph-core`: the sealed `AgentChannel` trait, borrowed event carriers (`ToolEventStart`, `ToolEventOutput`), and doom-loop detection (`doom_loop_hash`). + +- Start with crate-local checks: `cargo build -p zeph-agent-tools`, `cargo nextest run -p zeph-agent-tools`, `cargo clippy -p zeph-agent-tools --all-targets -- -D warnings`. +- Read `specs/006-tools/spec.md` before changing the dispatch contract or tool-result handling. +- Architecture invariant: this crate MUST NOT depend on `zeph-core` or `zeph-channels`. `AgentChannel` is a minimal, sealed trait specifically to avoid the circular dependency that `zeph-core::channel::Channel` would create — never break this by adding those deps. +- `AgentChannel` is sealed via the `Sealed` trait: external implementations are forbidden by design. `zeph-core` implements it through its local `AgentChannelView<'a, C>` adapter. +- Crate status: Phase-2 scaffolding (issue #3516). Full `ToolDispatcher` extraction from `zeph-core` is a follow-up — keep changes minimal and aligned with that direction rather than adding speculative surface. +- Doom-loop detection is agent-safety critical: any change to `doom_loop_hash` or its hashing inputs needs regression coverage so repeated tool calls are still detected. +- LLM serialization gate: once tool dispatch / batch tool-result processing is extracted here, changes to those paths require a live session test with a real tool call before merge. diff --git a/crates/zeph-bench/AGENTS.md b/crates/zeph-bench/AGENTS.md new file mode 100644 index 000000000..4ccc79185 --- /dev/null +++ b/crates/zeph-bench/AGENTS.md @@ -0,0 +1,8 @@ +# zeph-bench Guide + +Benchmark harness and `zeph bench` CLI subcommand for evaluating agent performance on standardized datasets (LOCOMO, FRAMES, GAIA, etc.) live here. + +- Start with crate-local checks: `cargo build -p zeph-bench`, `cargo nextest run -p zeph-bench`, `cargo clippy -p zeph-bench --all-targets -- -D warnings`. +- Keep evaluation logic reproducible and deterministic; non-deterministic results make regressions invisible. +- Multi-model: LLM-as-judge evaluation exposes a `*_provider` config field referencing `[[llm.providers]]` by name — never hardcode a model. +- If user-facing behavior or dataset support changes, update `crates/zeph-bench/README.md` and the relevant benchmark docs. diff --git a/crates/zeph-channels/AGENTS.md b/crates/zeph-channels/AGENTS.md new file mode 100644 index 000000000..fcd53c9dd --- /dev/null +++ b/crates/zeph-channels/AGENTS.md @@ -0,0 +1,9 @@ +# zeph-channels Guide + +CLI and chat-channel adapters live here. + +- Start with crate-local checks: `cargo build -p zeph-channels`, `cargo nextest run -p zeph-channels`, `cargo clippy -p zeph-channels --all-targets -- -D warnings`. +- Keep changes isolated to channel adapters, rendering, and streaming behavior unless shared channel traits require coordinated edits. +- Secrets (Telegram bot token, webhook secrets) are resolved exclusively from the age vault at startup — never from env vars, config files, or hardcoded values. +- Validate formatting and rendering changes against existing markdown and channel tests. +- If external behavior changes, update `crates/zeph-channels/README.md` and the relevant channel docs. diff --git a/crates/zeph-commands/AGENTS.md b/crates/zeph-commands/AGENTS.md new file mode 100644 index 000000000..974b2f386 --- /dev/null +++ b/crates/zeph-commands/AGENTS.md @@ -0,0 +1,8 @@ +# zeph-commands Guide + +Slash command registry, `CommandHandler` trait, `ChannelSink` abstraction, and `CommandOutput` type live here. + +- Start with crate-local checks: `cargo build -p zeph-commands`, `cargo nextest run -p zeph-commands`, `cargo clippy -p zeph-commands --all-targets -- -D warnings`. +- Keep command dispatch logic thin; push reusable business logic into the appropriate domain crate. +- When adding a new slash command, wire it in the root binary (`src/`), update the `--help` output, and add a TUI command palette entry where applicable. +- If the command surface changes, update `crates/zeph-commands/README.md` and the relevant docs. diff --git a/crates/zeph-common/AGENTS.md b/crates/zeph-common/AGENTS.md new file mode 100644 index 000000000..9d7e1a7e1 --- /dev/null +++ b/crates/zeph-common/AGENTS.md @@ -0,0 +1,8 @@ +# zeph-common Guide + +Shared utility functions, security primitives (`Secret`, `VaultError`), and strongly-typed identifiers (`ToolName`, `SessionId`) used across the workspace live here. + +- Start with crate-local checks: `cargo build -p zeph-common`, `cargo nextest run -p zeph-common`, `cargo clippy -p zeph-common --all-targets -- -D warnings`. +- This crate must have zero dependencies on other `zeph-*` crates to remain a safe shared foundation. +- Security primitives (`Secret`) must never expose inner values through `Debug`, `Display`, or serialization — verify before adding new impls. +- If the public API changes, downstream crates will be affected workspace-wide; run `cargo build --workspace` after changes here. diff --git a/crates/zeph-config/AGENTS.md b/crates/zeph-config/AGENTS.md new file mode 100644 index 000000000..aa0c14d7e --- /dev/null +++ b/crates/zeph-config/AGENTS.md @@ -0,0 +1,9 @@ +# zeph-config Guide + +Configuration structs, TOML loader, `ZEPH_*` env var overrides, validation, and migration helpers live here. Vault secret resolution is handled upstream in `zeph-core`. + +- Start with crate-local checks: `cargo build -p zeph-config`, `cargo nextest run -p zeph-config`, `cargo clippy -p zeph-config --all-targets -- -D warnings`. +- `ZEPH_*` env var overrides are for non-secret values only — secrets are resolved from the age vault, never from env vars or config files. +- When adding or renaming config keys, add a `--migrate-config` migration step so existing configs upgrade automatically. +- Keep config structs, `config/default.toml`, docs, and the `--init` wizard in sync for every new field. +- If the config surface changes, update `crates/zeph-config/README.md` and `docs/src/` reference pages. diff --git a/crates/zeph-context/AGENTS.md b/crates/zeph-context/AGENTS.md new file mode 100644 index 000000000..c03ba7647 --- /dev/null +++ b/crates/zeph-context/AGENTS.md @@ -0,0 +1,9 @@ +# zeph-context Guide + +Context budget, lifecycle management, compaction strategy, and context assembler live here. This crate is stateless and data-only — it has no dependency on `zeph-core`. + +- Start with crate-local checks: `cargo build -p zeph-context`, `cargo nextest run -p zeph-context`, `cargo clippy -p zeph-context --all-targets -- -D warnings`. +- LLM serialization gate: changes to context assembly structs (`MessagePart`, `Message`, assembled `messages` array) require a live API session test before merge — verify no 400/422 errors and a well-formed payload in the debug dump. +- Multi-model: compaction uses an LLM — expose a `compaction_provider` config field referencing `[[llm.providers]]` by name; never hardcode a model. +- Keep `IndexAccess` trait contract stable; callers in `zeph-core` implement it and breakage is silent at the trait boundary. +- If external behavior changes, update `crates/zeph-context/README.md` and the relevant context docs. diff --git a/crates/zeph-core/AGENTS.md b/crates/zeph-core/AGENTS.md new file mode 100644 index 000000000..5c2ca4031 --- /dev/null +++ b/crates/zeph-core/AGENTS.md @@ -0,0 +1,11 @@ +# zeph-core Guide + +Core agent orchestration, config, context building, sanitization, and subagent plumbing live here. + +- Start with crate-local checks: `cargo build -p zeph-core`, `cargo nextest run -p zeph-core`, `cargo clippy -p zeph-core --all-targets -- -D warnings`. +- Prefer minimal, well-contained changes; `zeph-core` is the highest-coupling crate in the workspace. +- Any change here may require follow-up updates in config, CLI wiring, docs, and integration tests. +- Be especially careful with context assembly, sanitization, config loading, and feature-gated surfaces. +- LLM serialization gate: changes to context assembly (`src/agent/context/`), `MessagePart`, `Message`, or any struct in LLM request/response paths require a live API session test before merge — verify no 400/422 errors and a well-formed `messages` array in the debug dump. +- Multi-model: every subsystem calling an LLM must expose a `*_provider` config field referencing a named entry in `[[llm.providers]]`; never hardcode a model name. +- TUI: every background operation triggered from core must surface a visible spinner/status message in the TUI layer. diff --git a/crates/zeph-db/AGENTS.md b/crates/zeph-db/AGENTS.md new file mode 100644 index 000000000..0a179c91e --- /dev/null +++ b/crates/zeph-db/AGENTS.md @@ -0,0 +1,9 @@ +# zeph-db Guide + +Database abstraction layer (`DbPool`, `DbRow`, `DbTransaction`, `DbQueryResult`) with compile-time SQLite/PostgreSQL backend selection lives here. + +- Start with crate-local checks: `cargo build -p zeph-db`, `cargo nextest run -p zeph-db`, `cargo clippy -p zeph-db --all-targets -- -D warnings`. +- All queries must use parameterized statements — reject any string-interpolated SQL to prevent injection. +- Schema changes require a migration; never alter existing migration files after they have been applied. +- Test with both backends (`--features sqlite` and `--features postgres`) before merging; silent divergence between backends is a first-class bug. +- If the public API changes, run `cargo build --workspace` — downstream crates depend on these type aliases. diff --git a/crates/zeph-durable/AGENTS.md b/crates/zeph-durable/AGENTS.md new file mode 100644 index 000000000..b76132fae --- /dev/null +++ b/crates/zeph-durable/AGENTS.md @@ -0,0 +1,11 @@ +# zeph-durable Guide + +Layer-0 durable execution: journals control flow (steps, inputs/outputs, promises, timers) so a crashed or interrupted execution resumes at the point of failure instead of restarting. Analogous in placement to `zeph-db` and `zeph-common`. + +- Start with crate-local checks: `cargo build -p zeph-durable`, `cargo nextest run -p zeph-durable`, `cargo clippy -p zeph-durable --all-targets -- -D warnings`. +- Test both backends — they are mutually exclusive: `cargo nextest run -p zeph-durable --no-default-features --features sqlite` and `... --features postgres`. +- Read `specs/064-durable-execution/spec.md` before any change; honor its `## Key Invariants` and `NEVER` sections. INV references below are from that spec. +- INV-1 (purity): this is a pure Layer-0 infra primitive — it sees opaque serialized payloads, never domain types. It MUST NOT depend on `zeph-llm`, `zeph-memory`, `zeph-core`, `zeph-sanitizer`, or any business-layer crate. Domain meaning lives in thin adapter modules inside each consuming crate. +- INV-14 (schema ownership): this crate owns no `.sql` files and no `sqlx::migrate!`. All `durable_*` schema lives as numbered migrations in `zeph-db/migrations/{sqlite,postgres}/`, applied via `zeph_db::run_migrations` against a dedicated `durable.db` pool. Any schema change goes through `zeph-db` with both-backend migration parity. +- Crypto is fail-closed and security-sensitive: `PayloadCipher` is AEAD, `PayloadAad` binds entries, and the read-side `max_payload` guard rejects oversized payloads. Never weaken the cipher contract, AAD binding, or the guard without an explicit security review. +- Preserve the `JournalWriter` actor invariants: group-commit for buffered appends, flush-before-commit ACK for exactly-once entries, and `MAX(seq)` restart resume. The `ExecutionBackend` trait is sealed — keep dispatch through `DurableBackendEnum`. diff --git a/crates/zeph-experiments/AGENTS.md b/crates/zeph-experiments/AGENTS.md new file mode 100644 index 000000000..11965cff7 --- /dev/null +++ b/crates/zeph-experiments/AGENTS.md @@ -0,0 +1,8 @@ +# zeph-experiments Guide + +Experiment engine for A/B testing adaptive agent behavior and hyperparameter tuning (temperature, top-p, retrieval depth, etc.) via an LLM-as-judge evaluation loop lives here. + +- Start with crate-local checks: `cargo build -p zeph-experiments`, `cargo nextest run -p zeph-experiments`, `cargo clippy -p zeph-experiments --all-targets -- -D warnings`. +- Multi-model: LLM-as-judge and hypothesis scoring expose `*_provider` config fields referencing `[[llm.providers]]` by name — never hardcode a model. +- Keep experiment runs reproducible: seed random state, fix dataset splits, and record all config parameters in experiment artifacts. +- If user-facing behavior changes, update `crates/zeph-experiments/README.md` and the relevant docs. diff --git a/crates/zeph-gateway/AGENTS.md b/crates/zeph-gateway/AGENTS.md new file mode 100644 index 000000000..13f6eda53 --- /dev/null +++ b/crates/zeph-gateway/AGENTS.md @@ -0,0 +1,9 @@ +# zeph-gateway Guide + +HTTP gateway and webhook ingestion code lives here. + +- Start with crate-local checks: `cargo build -p zeph-gateway`, `cargo nextest run -p zeph-gateway`, `cargo clippy -p zeph-gateway --all-targets -- -D warnings`. +- Treat auth, request validation, limits, and tracing as security-sensitive behavior. +- Bearer tokens and webhook secrets are resolved exclusively from the age vault — never hardcoded or passed via env vars. +- Keep gateway behavior aligned with root CLI/config surfaces. +- If external behavior changes, update `crates/zeph-gateway/README.md` and `docs/src/advanced/gateway.md`. diff --git a/crates/zeph-index/AGENTS.md b/crates/zeph-index/AGENTS.md new file mode 100644 index 000000000..41aea4318 --- /dev/null +++ b/crates/zeph-index/AGENTS.md @@ -0,0 +1,8 @@ +# zeph-index Guide + +Code indexing, repo map generation, and code retrieval live here. + +- Start with crate-local checks: `cargo build -p zeph-index`, `cargo nextest run -p zeph-index`, `cargo clippy -p zeph-index --all-targets -- -D warnings`. +- Preserve deterministic indexing behavior where possible; retrieval regressions should get tests. +- Be careful with filesystem walking, tree-sitter parsing, and persistence interactions with memory/index stores. +- If user-facing behavior changes, update `crates/zeph-index/README.md` and the relevant indexing docs. diff --git a/crates/zeph-llm/AGENTS.md b/crates/zeph-llm/AGENTS.md new file mode 100644 index 000000000..9a602b67d --- /dev/null +++ b/crates/zeph-llm/AGENTS.md @@ -0,0 +1,10 @@ +# zeph-llm Guide + +Provider implementations, orchestration, routing, and inference behavior live here. + +- Start with crate-local checks: `cargo build -p zeph-llm`, `cargo nextest run -p zeph-llm`, `cargo clippy -p zeph-llm --all-targets -- -D warnings`. +- Changes here are high impact: preserve provider contracts, streaming behavior, retries, and schema extraction semantics unless explicitly changing them. +- LLM serialization gate: any change to `claude.rs`, `openai.rs`, `ollama.rs`, `compatible.rs`, or any `#[derive(Serialize, Deserialize)]` struct on the request/response path requires a live multi-turn + tool-call session test before merge. +- Multi-model: all provider backends resolve through the `[[llm.providers]]` registry by name; subsystems reference providers via `*_provider` fields — never inline model strings. +- Keep model/provider docs and config examples in sync with behavior. +- If external behavior changes, update `crates/zeph-llm/README.md` and the relevant provider docs. diff --git a/crates/zeph-mcp/AGENTS.md b/crates/zeph-mcp/AGENTS.md new file mode 100644 index 000000000..819ea2097 --- /dev/null +++ b/crates/zeph-mcp/AGENTS.md @@ -0,0 +1,8 @@ +# zeph-mcp Guide + +MCP client lifecycle, registry, policies, and tool execution bridging live here. + +- Start with crate-local checks: `cargo build -p zeph-mcp`, `cargo nextest run -p zeph-mcp`, `cargo clippy -p zeph-mcp --all-targets -- -D warnings`. +- Treat policy enforcement, rate limits, transport setup, and tool exposure as security-sensitive behavior. +- Keep changes isolated to MCP behavior unless shared tool abstractions require coordinated edits. +- If external behavior changes, update `crates/zeph-mcp/README.md` and the relevant MCP docs. diff --git a/crates/zeph-memory/AGENTS.md b/crates/zeph-memory/AGENTS.md new file mode 100644 index 000000000..7c27b36d1 --- /dev/null +++ b/crates/zeph-memory/AGENTS.md @@ -0,0 +1,10 @@ +# zeph-memory Guide + +Conversation persistence, embeddings, semantic recall, document ingestion, and graph memory live here. + +- Start with crate-local checks: `cargo build -p zeph-memory`, `cargo nextest run -p zeph-memory`, `cargo clippy -p zeph-memory --all-targets -- -D warnings`. +- Be careful with persistence schema changes, token counting, vector-store behavior, and retention/eviction logic. +- Embedding dimension mismatches are a recurring source of bugs: whenever the embedding model or vector collection config changes, verify that stored and query vector dimensions match before running tests. +- Multi-model: summarization, compaction, and graph extraction each use an LLM — expose `*_provider` fields referencing `[[llm.providers]]` names; never hardcode a model. +- Memory-related bug fixes should get regression coverage near the changed code or in crate tests. +- If external behavior changes, update `crates/zeph-memory/README.md` and the relevant memory docs. diff --git a/crates/zeph-orchestration/AGENTS.md b/crates/zeph-orchestration/AGENTS.md new file mode 100644 index 000000000..5709a2edf --- /dev/null +++ b/crates/zeph-orchestration/AGENTS.md @@ -0,0 +1,9 @@ +# zeph-orchestration Guide + +Multi-model task orchestration: DAG decomposition, concurrent sub-agent execution, failure propagation, and result synthesis live here. + +- Start with crate-local checks: `cargo build -p zeph-orchestration`, `cargo nextest run -p zeph-orchestration`, `cargo clippy -p zeph-orchestration --all-targets -- -D warnings`. +- Multi-model: planner and synthesizer use LLMs — expose `planner_provider` and `synthesizer_provider` config fields referencing `[[llm.providers]]` by name; use the most capable model for planning and reasoning tasks. +- DAG execution must handle partial failure gracefully; do not silently drop sub-task errors. +- LLM serialization gate: changes to task decomposition or result synthesis structs require a live multi-turn session test before merge. +- If external behavior changes, update `crates/zeph-orchestration/README.md` and the relevant orchestration docs. diff --git a/crates/zeph-plugins/AGENTS.md b/crates/zeph-plugins/AGENTS.md new file mode 100644 index 000000000..d4cb8c0c6 --- /dev/null +++ b/crates/zeph-plugins/AGENTS.md @@ -0,0 +1,13 @@ +# zeph-plugins Guide + +Plugin packaging, installation, and management: a plugin is a directory (local or remote git) with a `plugin.toml` manifest, skill directories, optional MCP server declarations, and a config overlay. Plugins install to `~/.local/share/zeph/plugins//` and load at agent startup. + +- Start with crate-local checks: `cargo build -p zeph-plugins`, `cargo nextest run -p zeph-plugins`, `cargo clippy -p zeph-plugins --all-targets -- -D warnings`. +- Read `specs/058-plugins/spec.md` before changing the manifest format, install flow, or overlay resolution. +- The security model is non-negotiable — every guarantee below needs regression coverage when its code path changes: + - Config overlays are **tighten-only**: they may add to `blocked_commands`, narrow `allowed_commands`, or raise `disambiguation_threshold` — never loosen a constraint (`overlay.rs`). + - Plugin MCP entries are validated against `mcp.allowed_commands` at install time. + - `.bundled` markers are stripped recursively from all plugin skill trees. + - Skill-name conflicts with managed, bundled, or other plugin skills are hard errors at install. +- `integrity.rs` and `manager/security.rs` are security-sensitive; do not relax integrity checks or install-time validation without an explicit security review. +- If install, overlay, or manifest behavior changes, update `crates/zeph-plugins/README.md` and the relevant plugin docs. diff --git a/crates/zeph-sanitizer/AGENTS.md b/crates/zeph-sanitizer/AGENTS.md new file mode 100644 index 000000000..bb394c47c --- /dev/null +++ b/crates/zeph-sanitizer/AGENTS.md @@ -0,0 +1,9 @@ +# zeph-sanitizer Guide + +Untrusted content isolation: sanitization pipeline, injection detection, truncation, and spotlighting for all external content entering the agent context live here. + +- Start with crate-local checks: `cargo build -p zeph-sanitizer`, `cargo nextest run -p zeph-sanitizer`, `cargo clippy -p zeph-sanitizer --all-targets -- -D warnings`. +- Treat every change here as security-sensitive: sanitization is the primary defense against prompt injection. +- Every new injection pattern or bypass discovered in live testing must get a regression test before the fix is merged. +- Do not weaken truncation limits or bypass conditions without an explicit security review. +- If sanitization behavior changes, verify cross-channel consistency (CLI, TUI, Telegram) — a bypass in one channel is a bypass everywhere. diff --git a/crates/zeph-scheduler/AGENTS.md b/crates/zeph-scheduler/AGENTS.md new file mode 100644 index 000000000..574988188 --- /dev/null +++ b/crates/zeph-scheduler/AGENTS.md @@ -0,0 +1,8 @@ +# zeph-scheduler Guide + +Scheduled task persistence, cron handling, and update-check jobs live here. + +- Start with crate-local checks: `cargo build -p zeph-scheduler`, `cargo nextest run -p zeph-scheduler`, `cargo clippy -p zeph-scheduler --all-targets -- -D warnings`. +- Preserve deterministic scheduling and storage behavior; time parsing and job-state transitions should get explicit test coverage. +- Keep scheduler behavior aligned with root CLI/config and any built-in scheduling skills. +- If external behavior changes, update `crates/zeph-scheduler/README.md` and the relevant scheduler docs. diff --git a/crates/zeph-skills/AGENTS.md b/crates/zeph-skills/AGENTS.md new file mode 100644 index 000000000..e1e00c014 --- /dev/null +++ b/crates/zeph-skills/AGENTS.md @@ -0,0 +1,9 @@ +# zeph-skills Guide + +Skill loading, matching, trust, and evolution logic live here. + +- Start with crate-local checks: `cargo build -p zeph-skills`, `cargo nextest run -p zeph-skills`, `cargo clippy -p zeph-skills --all-targets -- -D warnings`. +- Preserve matcher quality and trust semantics unless the task explicitly changes retrieval or scoring behavior. +- Multi-model: skill matching, embedding, and self-learning evolution call LLMs — expose `*_provider` fields referencing `[[llm.providers]]` names; never hardcode a model. +- Changes to skill loading or trust should be checked against instruction-file and skill-related docs. +- If external behavior changes, update `crates/zeph-skills/README.md` and the relevant skills docs. diff --git a/crates/zeph-subagent/AGENTS.md b/crates/zeph-subagent/AGENTS.md new file mode 100644 index 000000000..04a6188b4 --- /dev/null +++ b/crates/zeph-subagent/AGENTS.md @@ -0,0 +1,9 @@ +# zeph-subagent Guide + +Sub-agent spawning, capability grants, transcript management, and lifecycle hooks live here. + +- Start with crate-local checks: `cargo build -p zeph-subagent`, `cargo nextest run -p zeph-subagent`, `cargo clippy -p zeph-subagent --all-targets -- -D warnings`. +- Treat grant scoping and capability propagation as security-sensitive: a sub-agent must never inherit more permissions than explicitly granted. +- LLM serialization gate: changes to sub-agent message passing or transcript structs require a live session test with actual sub-agent spawning before merge. +- TUI: sub-agent spawning and active tasks must surface visible spinner/status feedback. +- If external behavior changes, update `crates/zeph-subagent/README.md` and the relevant sub-agent docs. diff --git a/crates/zeph-tools/AGENTS.md b/crates/zeph-tools/AGENTS.md new file mode 100644 index 000000000..f6b7fb0f6 --- /dev/null +++ b/crates/zeph-tools/AGENTS.md @@ -0,0 +1,8 @@ +# zeph-tools Guide + +Tool execution, shell permissions, filtering, scraping, and audit behavior live here. + +- Start with crate-local checks: `cargo build -p zeph-tools`, `cargo nextest run -p zeph-tools`, `cargo clippy -p zeph-tools --all-targets -- -D warnings`. +- Treat shell execution, permissions, trust gating, network access, and audit logging as security-sensitive behavior. +- Prefer explicit safeguards over implicit defaults; regressions here can affect the whole agent. +- If external behavior changes, update `crates/zeph-tools/README.md` and the relevant tools/security docs. diff --git a/crates/zeph-tui/AGENTS.md b/crates/zeph-tui/AGENTS.md new file mode 100644 index 000000000..07fd1e091 --- /dev/null +++ b/crates/zeph-tui/AGENTS.md @@ -0,0 +1,8 @@ +# zeph-tui Guide + +The ratatui dashboard, UI state, event loop, and visual feedback live here. + +- Start with crate-local checks: `cargo build -p zeph-tui`, `cargo nextest run -p zeph-tui`, `cargo clippy -p zeph-tui --all-targets -- -D warnings`. +- Any background or implicit operation must surface visible status/spinner feedback in the UI. +- Preserve keyboard flow, redraw behavior, and test coverage for regressions in event handling. +- If external behavior changes, update `crates/zeph-tui/README.md` and the relevant TUI docs. diff --git a/crates/zeph-vault/AGENTS.md b/crates/zeph-vault/AGENTS.md new file mode 100644 index 000000000..6ab1fb56c --- /dev/null +++ b/crates/zeph-vault/AGENTS.md @@ -0,0 +1,9 @@ +# zeph-vault Guide + +Secret storage with pluggable backends and age encryption (`VaultProvider` trait, age backend, env backend for tests) lives here. + +- Start with crate-local checks: `cargo build -p zeph-vault`, `cargo nextest run -p zeph-vault`, `cargo clippy -p zeph-vault --all-targets -- -D warnings`. +- Treat every change here as highest-sensitivity: this crate is the only authorized path for secret access in the workspace. +- `Secret` values must never appear in logs, `Debug` output, error messages, or serialized payloads — audit any new `impl` that touches the inner value. +- The `env` backend is for testing only and must never be enabled in production configs (`ZEPH_VAULT_BACKEND=env` is forbidden outside test contexts). +- Do not add new secret resolution paths outside this crate; callers must go through `VaultProvider`. diff --git a/crates/zeph-worktree/AGENTS.md b/crates/zeph-worktree/AGENTS.md new file mode 100644 index 000000000..3caf897e5 --- /dev/null +++ b/crates/zeph-worktree/AGENTS.md @@ -0,0 +1,10 @@ +# zeph-worktree Guide + +Per-subagent git worktree lifecycle: `WorktreeManager` creates, removes, lists, and reconciles git worktrees; `WorktreeHandle` records one managed worktree; git invocation is abstracted behind `GitRunner` / `DefaultGitRunner`. + +- Start with crate-local checks: `cargo build -p zeph-worktree`, `cargo nextest run -p zeph-worktree`, `cargo clippy -p zeph-worktree --all-targets -- -D warnings`. +- Read `specs/063-worktree-subsystem/spec.md` before any change; honor its `## Key Invariants` and `NEVER` sections. +- Dependency direction: `zeph-subagent → zeph-worktree → (zeph-config, tokio, thiserror, tracing)`. This crate MUST NOT depend on `zeph-core`, `zeph-subagent`, or `zeph-channels`. +- All git invocations go through the `GitRunner` abstraction so tests can mock them — never shell out to `git` directly elsewhere in the crate. +- `sanitize.rs` feeds agent ids and branch names into git CLI arguments; treat it as security-sensitive (argument/shell injection). Every new input shape needs a sanitization regression test before merge. +- Worktrees are never created inside this repository — managed worktrees live under the sibling `../worktrees/` directory. Path-construction and reconciliation logic must respect that convention. diff --git a/docker/AGENTS.md b/docker/AGENTS.md new file mode 100644 index 000000000..faa240373 --- /dev/null +++ b/docker/AGENTS.md @@ -0,0 +1,8 @@ +# Docker Guide + +This directory contains container and image assets for Zeph. + +- Keep images reproducible, minimal, and aligned with the documented install/run flows. +- Treat network exposure, credentials, user permissions, and base-image choices as security-sensitive. +- If Docker behavior changes, update the corresponding docs and examples. +- Avoid introducing container-specific behavior that diverges silently from the local CLI unless explicitly intended and documented. diff --git a/src/AGENTS.md b/src/AGENTS.md new file mode 100644 index 000000000..5a387e997 --- /dev/null +++ b/src/AGENTS.md @@ -0,0 +1,9 @@ +# Root Binary Guide + +This directory contains the top-level binary wiring for CLI commands, runtime startup, daemon entrypoints, and feature-gated integration points. + +- Changes here usually coordinate existing crate APIs rather than introducing core logic from scratch. +- When adding or changing a feature, provide all integration points: config section, CLI subcommand/argument, TUI command palette entry, `--init` wizard update, `--migrate-config` migration step, live testing playbook in `.local/testing/playbooks/`, and coverage row in `.local/testing/coverage-status.md`. +- Secrets are never passed via environment variables or flags; all `ZEPH_*` keys are resolved from the age vault at startup. +- Keep command handling thin; prefer pushing reusable logic into the appropriate crate. +- Validate that CLI flags and subcommands stay aligned with docs and `config/default.toml`. diff --git a/tests/AGENTS.md b/tests/AGENTS.md new file mode 100644 index 000000000..9dfb2a543 --- /dev/null +++ b/tests/AGENTS.md @@ -0,0 +1,8 @@ +# Integration Tests Guide + +This directory contains top-level integration scenarios for the workspace binary and cross-crate behavior. + +- Prefer `cargo nextest run --test ` or targeted workspace `nextest` filters over `cargo test`. +- Keep tests deterministic and focused on externally visible behavior. +- Add regression coverage here when a bug spans multiple crates or depends on root-binary wiring. +- Document external service requirements clearly when a test needs Docker, Qdrant, or network-like fixtures. From 2071a8a418fdaf5955301c4aaebca41271a63465 Mon Sep 17 00:00:00 2001 From: "Andrei G." Date: Sun, 7 Jun 2026 00:37:43 +0200 Subject: [PATCH 2/2] build: stop ignoring AGENTS.md in this repo Add a !AGENTS.md negation so per-directory agent guides are tracked despite the contributor's global AGENTS.md ignore, preventing new guides from being silently skipped. --- .gitignore | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.gitignore b/.gitignore index e4190fc2a..59c353060 100644 --- a/.gitignore +++ b/.gitignore @@ -14,3 +14,6 @@ book/book/ *.log zeph.log *.session + +# Track per-directory agent guides despite the global AGENTS.md ignore +!AGENTS.md