Add agentic-first workflow infrastructure for Claude Code

[Darktex]

Summary

OpenEnv is designed for Claude Code contributions. This PR adds the infrastructure to support an agentic-first development workflow where:

1. Design/Alignment (human-owned): RFCs, principles, trade-off decisions
2. Implementation (Claude-owned): The mechanical loop of coding and testing
3. Review (collaborative): Claude catches bugs, flags alignment questions for humans

What's Included

Alignment Documents (.claude/docs/)

Document	Purpose
PRINCIPLES.md	Design principles and trade-offs
INVARIANTS.md	System invariants that must never be violated
PATTERNS.md	Code patterns and conventions
CONTRIBUTING.md	Agentic contribution workflow
REPO_WALKTHROUGH.md	Annotated directory structure

Skills (.claude/skills/)

Skill	Purpose
alignment-review	Two-tier code review (bugs + alignment flags)
pre-submit-pr	Comprehensive PR readiness validation
rfc-check	Determine if RFC is required

Agents (.claude/agents/)

Agent	Purpose
alignment-reviewer	Review PRs for bugs + alignment
env-validator	Validate environments end-to-end
openenv-architect	Design new features/environments
build-validator	Validate builds before merge

Automation & Templates

• .claude/hooks/ - lint.sh, test.sh, check-debug.sh
• .github/PULL_REQUEST_TEMPLATE.md - PR checklist
• .github/ISSUE_TEMPLATE/rfc-proposal.md - RFC template

Updated Docs

• CLAUDE.md - Complete rewrite with agentic workflow focus
• README.md - Updated HTTPEnvClient→EnvClient, HTTP→WebSocket
• CONTRIBUTING.md - Links to detailed workflow docs

Key Concepts

• Two-tier review: Tier 1 (bugs, fix immediately) + Tier 2 (alignment flags for humans)
• Skills vs Agents: Skills run inline, Agents run in isolation
• Auto-discovery: Skills and agents found automatically when cloning repo
• Dual API boundary: WebSocket for infrastructure, MCP for agents

Test Plan

• Verified hook scripts work (bash .claude/hooks/lint.sh)
• Skills are auto-discovered in Claude Code
• All docs are reachable from CLAUDE.md
• No duplicate information across docs
• Consistent terminology (WebSocket, EnvClient, correct paths)

[Darktex]

Note: This is an automated review by Claude Code (alignment-reviewer agent), not a human review. The account posting this is shared with the human maintainer.

---

Excellent! Now let me compile my comprehensive review:

Alignment Review Report

Automated Checks

Lint Check: ⚠️ BLOCKED - uv not available in review environment
Debug Code Check: ✅ CLEAN - No debugger statements found. Print statements found are appropriate:

• CLI commands use console.print() for user output (legitimate CLI communication)
• Test file test_local_docker_provider.py uses print() for test output (legitimate test logging)
• Docstring examples use print() for documentation (legitimate)
• All print statements are appropriate for their context

Open RFCs Context

All current RFCs are in "In Review" status:

• RFC 000: Project Phases
• RFC 001: Abstractions (dual API boundary)
• RFC 002: Environment Specification
• RFC 003: MCP Support

This PR implements workflow infrastructure that supports these RFCs rather than conflicting with them.

---

Tier 1: Fixes Required

✅ None identified - All automated checks that could run passed. The lint check requires uv which isn't available in this environment, but the PR adds the lint hook for future validation.

---

Tier 2: Alignment Discussion

Principle Conflicts

✅ None identified - This PR strongly aligns with OpenEnv principles:

1. "Be hands-on" (Principle Add boiler plate code for CodingEnv #3): Provides working implementations (hooks, skills, agents) rather than just documentation
2. "Design for LLMs" (Principle Add BaseHTTPClient to talk to Envs via JSON over RPC. #4): The entire PR is about making the codebase more accessible to Claude Code
3. Two-phase model: Explicitly documents design/alignment (human) vs implementation (Claude) separation

RFC Conflicts

✅ None identified - No conflicts with open RFCs. The PR:

• Documents the dual API boundary (RFC 001) in INVARIANTS.md
• References the WebSocket preference (RFC 002) in updated docs
• Prepares infrastructure for MCP integration (RFC 003) via alignment review

Positive Alignment Observations

This PR demonstrates exemplary alignment with OpenEnv's principles:

1. Dogfooding: The PR itself was created using the workflow it establishes (agentic-first)
2. Minimal delta: Adds workflow infrastructure without changing core code
3. Invariant documentation: Codifies existing architectural decisions (dual API, client-server separation, rewards in environment)
4. .gitignore fix: Critically important - the old .gitignore was blocking all Claude-related files with wildcards. The new version allows committed workflow files while excluding personal/temporary Claude Code files.

---

Documentation Quality Review

CLAUDE.md

• ✅ Clear entry point with progressive depth (start simple, links to details)
• ✅ Accurate file path references (verified all links exist)
• ✅ Build commands match actual project structure
• ✅ Skills and agents tables match actual files

.claude/docs/

• ✅ PRINCIPLES.md: Well-structured, traces decisions to RFCs
• ✅ INVARIANTS.md: Critical rules clearly stated with violation examples
• ✅ PATTERNS.md: Concrete code patterns with examples
• ✅ CONTRIBUTING.md: Clear two-phase model explanation
• ✅ REPO_WALKTHROUGH.md: Comprehensive directory guide with annotations

Skills & Agents

• ✅ All include frontmatter with name, description, tools, model
• ✅ Clear instructions with output format templates
• ✅ Two-tier review model consistently applied
• ✅ RFC-awareness built into review workflows

---

Infrastructure Quality Review

Hooks (.claude/hooks/)

• ✅ lint.sh: Checks for uv, runs ruff format --check
• ✅ test.sh: Sets PYTHONPATH, excludes special-setup envs correctly
• ✅ check-debug.sh: Falls back to grep if rg unavailable (good defensive coding)
• ✅ All scripts have proper error handling (set -e where appropriate)
• ✅ All scripts are executable (verified with ls -la)

GitHub Templates

• ✅ PULL_REQUEST_TEMPLATE.md: Includes alignment checklist, RFC status
• ✅ ISSUE_TEMPLATE/rfc-proposal.md: Guides RFC creation with principles alignment

---

Changes to Existing Files

README.md

• ✅ Updated architecture diagram to reflect WebSocket (not HTTP)
• ✅ Removed outdated "Quick Start" section (appropriate - details moved to docs)
• ✅ Updated client class names (HTTPEnvClient → EnvClient)

CONTRIBUTING.md

• ✅ Simplified to focus on agentic workflow
• ✅ Points to .claude/docs/CONTRIBUTING.md for details
• ✅ Keeps CLA requirement visible

.gitignore

• ✅ Critical fix: Removes overly broad *claude* wildcards
• ✅ Explicitly allows committed workflow files
• ✅ Excludes personal/temporary Claude Code files
• ✅ Documents what's kept vs excluded with comments

---

Security & Safety Review

✅ No security concerns identified:

• No credentials exposed
• No execution of untrusted code
• Bash scripts use defensive patterns (check for tools before using)
• No changes to core runtime code

---

Summary

• 0 mechanical issues to fix (pending lint verification with uv)
• 0 alignment points for human review
• 0 RFC conflicts to discuss

Verdict: ✅ READY FOR MERGE

Rationale

This PR is a textbook example of agentic-first infrastructure:

1. Self-documenting: The PR adds the very workflow infrastructure used to create it
2. No core changes: Purely additive - adds documentation, tooling, and workflow without touching core logic
3. Alignment-focused: Every file reinforces the two-tier review model and principle-based development
4. Immediately useful: Contributors can use /alignment-review and other skills right after merge
5. Critical .gitignore fix: Unblocks Claude Code usage by allowing committed workflow files

Recommendations

1. After merge: Run uv run ruff format src/ tests/ --check to verify lint passes
2. Consider: Adding a "bootstrap" script that helps new contributors install recommended Claude Code plugins
3. Future: The hooks could be enhanced with git pre-commit integration (optional)

---

No blocking issues identified. This PR significantly improves the contributor experience for Claude Code users while maintaining all OpenEnv invariants and principles.

---

Automated review by Claude Code | Learn more about OpenEnv's agentic workflow