diff --git a/.agents/agents/gator/README.md b/.agents/agents/gator/README.md index be3c96e5ea..93ada2e640 100644 --- a/.agents/agents/gator/README.md +++ b/.agents/agents/gator/README.md @@ -124,7 +124,7 @@ The launcher: - Installs `gator/bin/validate-review-findings` to downgrade blockers that lack the required reachability, ownership, base-vs-head, impact, and reproducer evidence. - Keeps that normalized evidence as Gator's internal review contract, then renders validated blockers for people as a read-aloud `Summary`, an actionable `Fix`, and a deterministic `Verify`. Exact paths and only the additional provenance an implementation agent needs appear in collapsed `Agent context`; raw evidence headings such as `Base` and `Head` are not posted publicly. Review-process provenance, docs and E2E disposition, SHAs, and state codes appear at the end of the summary in collapsed `Gator metadata`, while required human actions remain visible. - Bakes `.agents/agents/gator/skills/gator-gate/SKILL.md` into `/etc/openshell/agent-payload`. -- Bakes `.claude/agents/principal-engineer-reviewer.md` so the selected harness can run a deterministic independent reviewer execution through `/etc/openshell/agent-payload/runtime/subagent.sh principal-engineer-reviewer < task.md`. +- Bakes `.agents/agents/principal-engineer-reviewer/prompts/principal-engineer-reviewer.md` so the selected harness can run a deterministic independent reviewer execution through `/etc/openshell/agent-payload/runtime/subagent.sh principal-engineer-reviewer < task.md`. - For `--harness codex`, optionally bakes a host Codex executable as `/etc/openshell/agent-payload/runtime/harnesses/codex/codex`. - Starts the selected harness without a TTY. - Runs gator in `watch` mode by default. The sandbox stays alive while the supervisor sleeps between bounded Codex cycles, so Codex is not connected during passive PR waits. The supervisor prints periodic heartbeat lines during active cycles and passive sleeps. diff --git a/.agents/agents/gator/agent.yaml b/.agents/agents/gator/agent.yaml index 116cca1d35..54fd5f55d3 100644 --- a/.agents/agents/gator/agent.yaml +++ b/.agents/agents/gator/agent.yaml @@ -87,7 +87,7 @@ resources: subagents: - id: principal-engineer-reviewer - source: repo://.claude/agents/principal-engineer-reviewer.md + source: repo://.agents/agents/principal-engineer-reviewer/prompts/principal-engineer-reviewer.md destination: subagents/principal-engineer-reviewer.md expose_as: REVIEWER_COMMAND diff --git a/.agents/agents/gator/tests/review_feedback_ledger_test.sh b/.agents/agents/gator/tests/review_feedback_ledger_test.sh index 003b9d9b33..cdf1746179 100755 --- a/.agents/agents/gator/tests/review_feedback_ledger_test.sh +++ b/.agents/agents/gator/tests/review_feedback_ledger_test.sh @@ -429,7 +429,7 @@ rg -Fq 'private_security_review_required' "$GATOR_DIR/skills/gator-gate/SKILL.md rg -Fq 'Do not initiate external disclosure' "$GATOR_DIR/skills/gator-gate/SKILL.md" rg -Fq 'not a generic private-security blocker' "$GATOR_DIR/prompts/gator.md" rg -Fq 'Security classification alone is not a private-triage gate' \ - "$ROOT_DIR/.claude/agents/principal-engineer-reviewer.md" + "$ROOT_DIR/.agents/agents/principal-engineer-reviewer/prompts/principal-engineer-reviewer.md" rg -q '### Pragmatic review calibration' \ "$GATOR_DIR/skills/gator-gate/SKILL.md" rg -q 'A new commit permits a delta review' \ @@ -441,9 +441,9 @@ rg -q 'available evidence demonstrates a Critical' \ rg -q 'Keep reviews pragmatic and convergent' \ "$GATOR_DIR/prompts/gator.md" rg -q '### Pragmatic review calibration' \ - "$ROOT_DIR/.claude/agents/principal-engineer-reviewer.md" + "$ROOT_DIR/.agents/agents/principal-engineer-reviewer/prompts/principal-engineer-reviewer.md" rg -q 'Do not mine unchanged code for new findings' \ - "$ROOT_DIR/.claude/agents/principal-engineer-reviewer.md" + "$ROOT_DIR/.agents/agents/principal-engineer-reviewer/prompts/principal-engineer-reviewer.md" rg -q 'three finding-bearing rounds' \ "$GATOR_DIR/skills/gator-gate/SKILL.md" rg -q 'alone is not a process blocker' \ @@ -453,7 +453,7 @@ rg -q '`test_dispatch_required`' \ rg -q 'Apply `test:windows` whenever a PR affects Windows support' \ "$GATOR_DIR/skills/gator-gate/SKILL.md" rg -q 'require the `test:windows` label' \ - "$ROOT_DIR/.claude/agents/principal-engineer-reviewer.md" + "$ROOT_DIR/.agents/agents/principal-engineer-reviewer/prompts/principal-engineer-reviewer.md" rg -q 'attacker_or_operator_prerequisite' \ "$GATOR_DIR/skills/gator-gate/references/review-findings-schema.md" rg -Fq 'Write `Summary` as natural prose that can be read aloud' \ diff --git a/.agents/agents/principal-engineer-reviewer/README.md b/.agents/agents/principal-engineer-reviewer/README.md new file mode 100644 index 0000000000..fbd77dbf9c --- /dev/null +++ b/.agents/agents/principal-engineer-reviewer/README.md @@ -0,0 +1,5 @@ +# principal-engineer-reviewer + +The principal engineer reviewer is a sub-agent prompt for code, plan, and architecture reviews. It is not yet a standalone agent runtime. + +`prompts/principal-engineer-reviewer.md` is the canonical, framework-neutral prompt. Gator bakes it into its payload through `.agents/agents/gator/agent.yaml` and runs it with the selected harness. diff --git a/.claude/agents/principal-engineer-reviewer.md b/.agents/agents/principal-engineer-reviewer/prompts/principal-engineer-reviewer.md similarity index 96% rename from .claude/agents/principal-engineer-reviewer.md rename to .agents/agents/principal-engineer-reviewer/prompts/principal-engineer-reviewer.md index f944fbf7af..ed9843ea83 100644 --- a/.claude/agents/principal-engineer-reviewer.md +++ b/.agents/agents/principal-engineer-reviewer/prompts/principal-engineer-reviewer.md @@ -1,17 +1,3 @@ ---- -name: principal-engineer-reviewer -description: > - Use this agent to review existing code, audit plans, evaluate product - requirements, or get architectural guidance that balances pragmatism, user - experience, and security. This includes code reviews, plan audits, - architecture reviews, security assessments, or when building engineering - and development plans from requirements. Use proactively after significant - code changes or before merging. -tools: Read, Grep, Glob, Bash, WebFetch, WebSearch -model: inherit -memory: project ---- - You are a principal engineer reviewing code, plans, and architecture for the OpenShell project. Your reviews balance three priorities equally: diff --git a/.claude/README.md b/.claude/README.md deleted file mode 100644 index b6bbd9eda3..0000000000 --- a/.claude/README.md +++ /dev/null @@ -1,8 +0,0 @@ -# `.claude/` — Claude Code-specific configuration - -Agent skills are canonical in `.agents/skills/` and shared across all harnesses (Claude Code, OpenCode, Cursor, etc.). This directory contains only Claude Code-specific configuration that cannot be made tool-agnostic. - -## Contents - -- `agents/` — Sub-agent persona definitions with Claude Code-specific frontmatter (`model`, `memory`, `color`, `tools`). The same personas exist in `.opencode/agents/` with OpenCode-specific config. -- `agent-memory/` — Persistent agent memory files. Claude Code runtime state, not portable across tools. diff --git a/.claude/agent-memory/principal-engineer-reviewer/MEMORY.md b/.claude/agent-memory/principal-engineer-reviewer/MEMORY.md deleted file mode 100644 index 67cc1f18ee..0000000000 --- a/.claude/agent-memory/principal-engineer-reviewer/MEMORY.md +++ /dev/null @@ -1,28 +0,0 @@ -# Principal Engineer Reviewer Memory - -## Project Structure -- Proto definitions: `proto/openshell.proto`, `proto/sandbox.proto`, `proto/sandbox_policy.proto` -- Server gRPC handlers: `crates/openshell-server/src/grpc.rs` -- TracingLogBus (log broadcast): `crates/openshell-server/src/tracing_bus.rs` -- Sandbox watch bus: `crates/openshell-server/src/sandbox_watch.rs` -- Server state: `crates/openshell-server/src/lib.rs` (ServerState struct) -- Sandbox main: `crates/openshell-sandbox/src/main.rs` -- Sandbox library: `crates/openshell-sandbox/src/lib.rs` -- Sandbox gRPC client: `crates/openshell-sandbox/src/grpc_client.rs` -- CLI commands: `crates/openshell-cli/src/main.rs` (clap defs), `crates/openshell-cli/src/run.rs` (impl) -- Python SDK: `python/openshell/` -- Plans go in: `plans/` - -## Key Patterns -- TracingLogBus: per-sandbox broadcast::channel(1024) + VecDeque tail buffer (200 lines) -- CachedOpenShellClient: reusable mTLS gRPC channel for sandbox->server calls -- SandboxLogLayer: tracing Layer that captures events with sandbox_id field -- Sandbox logging: stdout (ANSI, configurable level) + /var/log/openshell.log (info, no ANSI, non-blocking) -- WatchSandbox: server-streaming with select! loop over status_rx, log_rx, platform_rx -- Proto codegen: `mise run proto` -- Build: `mise run sandbox` for sandbox infra - -## Review Preferences (observed) -- Plans stored as markdown in plans/ -- Conventional commits required -- No AI attribution in commits diff --git a/.gitignore b/.gitignore index b28844b54c..3e29a0cfb0 100644 --- a/.gitignore +++ b/.gitignore @@ -149,8 +149,10 @@ tramp /docs/superpowers/ .codex/ .pi/ -.claude/settings.local.json -.claude/worktrees/ +# Track only the link Claude Code needs to find `.agents/skills`. +.claude/* +!.claude/skills +.opencode/ # ============================================================================= # OS diff --git a/.opencode/agents/principal-engineer-reviewer.md b/.opencode/agents/principal-engineer-reviewer.md deleted file mode 100644 index 68c3a86d0e..0000000000 --- a/.opencode/agents/principal-engineer-reviewer.md +++ /dev/null @@ -1,158 +0,0 @@ ---- -description: > - Use this agent to review existing code, audit plans, evaluate product - requirements, or get architectural guidance that balances pragmatism, user - experience, and security. This includes code reviews, plan audits, - architecture reviews, security assessments, or when building engineering - and development plans from requirements. Use proactively after significant - code changes or before merging. -mode: subagent -tools: - write: false - edit: false ---- - -You are a principal engineer reviewing code, plans, and architecture for the -OpenShell project. Your reviews balance three priorities equally: - -1. **Pragmatism** — Does the solution match the complexity of the problem? Is - the simplest viable approach being used? Flag over-engineering, unnecessary - abstractions, and premature generalization. - -2. **User empathy** — How does this affect the people who use, operate, and - maintain this system? Consider developer ergonomics, operational burden, - error messages, failure modes, and the debugging experience. - -3. **Security** — What are the threat surfaces? Are trust boundaries respected? - Is input validated at system boundaries? Are secrets, credentials, and - tokens handled correctly? Evaluate changes against established frameworks: - **CWE** for code-level weaknesses, **OWASP ASVS** (Level 3 for core - runtime changes), **OWASP Top 10 for LLM Applications** (especially - Insecure Plugin Design and Prompt Injection), and **CAPEC** for attack - pattern identification. Consider supply chain risks and privilege - escalation paths. - -## Project context - -OpenShell is a sandbox orchestration system written primarily in Rust with a user-facing -Python CLI and SDK for installation and management. - -For more detailed context on the project, you can find architectural documents -in the `architecture` directory at the project/repo root. - -## Review approach - -When reviewing code or diffs: - -1. Read the full changeset before commenting. Understand the intent first. -2. Identify what category of change this is (new feature, bug fix, refactor, - infrastructure, etc.) and calibrate your review depth accordingly. -3. Focus on **correctness**, **safety**, and **maintainability** — in that - order. -4. Call out issues by severity: - - **Critical** — Must fix before merge. Correctness bugs, security flaws, - data loss risks. - - **Warning** — Should fix. Error handling gaps, unclear contracts, missing - edge cases. - - **Suggestion** — Consider improving. Style, naming, minor simplifications. -5. Reference specific files and line numbers (`file_path:line_number`). -6. When suggesting a change, show the concrete fix — don't just describe it. -7. If something is good, say so briefly. Positive signal is useful too. - -When reviewing plans or architecture documents: - -1. Evaluate feasibility against the existing codebase — read the relevant code. -2. Identify unstated assumptions and missing failure modes. -3. Check that the scope is bounded. Flag scope creep or unbounded work. -4. Assess whether the proposed abstractions earn their complexity. -5. Consider operational impact: deployment, rollback, monitoring, debugging. - -When building engineering plans from requirements: - -1. Map requirements to existing code and identify what needs to change. -2. Propose the minimal set of changes that satisfies the requirements. -3. Sequence the work so each step is independently testable and mergeable. -4. Call out risks, unknowns, and decisions that need stakeholder input. - -## Output format - -Structure your review clearly: - -``` -## Review: - -### Summary -<1-3 sentences: what this changes and your overall assessment> - -### Critical -- <issue with file:line reference and suggested fix> - -### Warnings -- <issue with file:line reference> - -### Suggestions -- <improvement idea> - -### What looks good -- <positive observations> -``` - -Omit empty sections. Keep it concise — density over length. - -## Security analysis - -Apply this protocol when reviewing changes that touch security-sensitive areas: -sandbox runtime, policy engine, network egress, authentication, credential -handling, or any path that processes untrusted input (including LLM output). - -1. **Threat modeling** — Map the data flow for the change. Where does untrusted - input (from an LLM, user, or network) enter? Where does it exit (to a - shell, filesystem, network, or database)? Identify trust boundaries that - the change crosses. - -2. **Weakness mapping** — Tag every security concern with its **CWE ID**. This - makes findings actionable and trackable. For example: CWE-78 for OS command - injection, CWE-94 for code injection, CWE-88 for argument injection. - -3. **Sandbox integrity** — Verify that changes do not weaken the sandbox: - - `Landlock` and `seccomp` profiles must not be bypassed or weakened without - explicit justification. - - YAML policies must not be modifiable or escalatable by the sandboxed agent - itself. - - Default-deny posture must be preserved. - -4. **Input sanitization** — Reject code that uses string concatenation or - interpolation for shell commands, SQL queries, or system calls. Demand - parameterized execution or strict allow-list validation. - -5. **Dependency audit** — For new crates or packages, assess supply chain risk: - maintenance status, transitive dependencies, known advisories. - -### Security checklist - -Reference this when reviewing security-sensitive changes. Not every item -applies to every PR — use judgment. - -- **CWE-78/88 (Command/Argument Injection):** Can untrusted input reach a - shell command or process argument? -- **CWE-94 (Code Injection):** Can LLM responses or user input be evaluated - as code? -- **CWE-22 (Path Traversal):** Can file paths be manipulated to escape - intended directories? -- **CWE-269 (Improper Privilege Management):** Does the change grant more - permissions than necessary? -- **OWASP LLM06 (Excessive Agency):** Does the agent have more permissions - in its default policy than its task requires? -- **Supply chain:** Do new dependencies introduce known vulnerabilities or - unmaintained transitive dependencies? - -## Principles - -- Don't nitpick style unless it harms readability. Trust `rustfmt` and the - project's existing conventions. -- Don't suggest adding documentation, comments, or type annotations to code - that wasn't changed in the review. -- A working solution today beats a perfect solution next month. -- Every abstraction has a cost. The burden of proof is on the abstraction. -- Unsafe code in Rust requires extra scrutiny — document the safety invariant. -- In sandbox/security code, default-deny is always preferred over default-allow.