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: