Edward's Agent Workstack: A Complete AI Intern Engineering Specification

AI programming assistants are evolving from "toys" to production tools, but how teams standardize collaboration with AI remains a challenge. The edward-agent-stack open-source project provides a complete solution: it is not just a tool installation script, but a battle-tested AI intern engineering specification that includes toolchains, workflow specifications, and decision recording mechanisms, designed specifically for Codex interns.

Maintained by giaphutran12, the core goal of this project is to establish a standardized work environment for Codex interns (or AI assistant users). The design philosophy is clear: starting from a brand-new company Mac, skip personal iCloud accounts, and build an Agent-native environment exclusive to work scenarios. Unlike common tool lists, it emphasizes workflow specifications and decision recording, requiring loading rule files before tasks and capturing decisions after tasks to form a traceable work history.

Core Toolchain

• Core CLI Tools: Codex (main Agent), Caveman, Claude Code, GitHub CLI, ripgrep, tmux, Docker, Python ecosystem, Node ecosystem, jq, ffmpeg
• Cloud Service CLIs: Supabase CLI, Vercel CLI
• MCP/App Tools: Exa (search), Linear (project management), MemPalace (memory), Playwright, Computer Use, Repowise
• Explicitly excluded tools: Notion, TinyFish, OMX, Kiro, mlx_whisper

Installation Process

1. bootstrap-macos.sh: Handles macOS basic environment (Xcode CLI, Homebrew, Rosetta)
2. install.sh: Installs core CLIs and skill tools
3. verify.sh: Verifies installation integrity
4. auth-doctor.sh: Checks authentication status and lists API keys that need manual configuration

The phased design is practical, acknowledging that steps like OAuth cannot be fully automated, and clearly informs users of subsequent operations.

Rule System

edward-rules is a layered skill routing system:

• Parent skill edward-rules is responsible for routing sub-skills
• Sub-skills: edward-decision-capture (decision capture), edward-escalation (escalation reporting), edward-project-notes (project notes)

Before starting a task, you need to load: /caveman ultra (concise mode), $edward-rules, PROJECT.md, relevant decision records After task completion, you need to perform decision capture checks: Are there reusable decisions? Has the context changed? Do project/decision notes need to be updated?

Decision Recording

• Project Notes: Project facts, current status, technical selection
• Decision Notes: Decision background, options, evidence, conclusions The document format follows a manual style: Problem (workflow breakpoint), Standard (what should be done), Reason (why the standard exists), Process (command/file/escalation format)

Enterprise Integration

Supports BLI Cockpit management system:

• Operator identity authentication
• Ticket context binding (BLI_ACTIVE_TICKET)
• Cockpit event emission (work aggregation and attribution)

Security/Privacy

• Uses local macOS user, does not use personal iCloud
• Does not check or print local environment/key files
• Stops at authentication gate, does not force login
• Tools like Nia are marked as "optional" and require Edward's approval before use

Applicable Scenarios

• Teams with interns/junior developers using AI assistants
• Organizations needing to establish AI collaboration norms
• Development environments using Codex as the main Agent
• Projects that value decision recording and knowledge accumulation

Limitations

• Mainly targeted at macOS environments
• Deeply integrated with the Codex ecosystem, with limited support for Agents like Claude and ChatGPT
• Requires a certain amount of initial configuration investment

edward-agent-stack represents a mature AI collaboration methodology: it does not pursue "one-click automation of everything", but instead establishes sustainable human-AI collaboration norms based on acknowledging real-world constraints. For organizations exploring large-scale use of AI programming assistants, this project provides a valuable reference implementation.