Agent Workflow Configuration

Harness-agnostic coding-agent workflow config with shared instructions, rules, skills, and adapter-specific settings for Claude Code, Pi, and Codex.

Install

./install.sh claude   # install Claude Code adapter
./install.sh pi       # install Pi adapter
./install.sh codex    # install Codex adapter
./install.sh all      # install all adapters

Environment overrides:

• CLAUDE_CONFIG_DIR — default ~/.claude
• PI_CONFIG_DIR — default ~/.pi/agent
• CODEX_CONFIG_DIR — default ~/.codex
• CODEX_AGENTS_DIR — default ~/.agents
• BLUEPRINT_DIR — default ~/workspace/blueprints

Prerequisites

• git
• Graphite CLI (gt) for stacked branch / PR workflow
• GitHub CLI (gh) for PR and issue metadata
• Python 3 for Claude statusline only
• macOS Keychain only for Claude quota statusline enrichment
• Codex CLI (codex) for the Codex adapter
• Rust/Cargo for the Pi Context Guard core

Layout

AGENTS.md                  # shared global instructions
CLAUDE.md                  # Claude compatibility entrypoint
install.sh                 # harness-aware installer
bin/blueprint              # portable blueprint state CLI
Cargo.toml                  # Rust workspace for vendored helper binaries
crates/context-guard/       # Pi Context Guard Rust core
rules/                     # shared coding/workflow rules
skills/                    # Agent Skills packages
harnesses/
  claude/
    settings.json          # Claude Code settings
    statusline.py          # Claude Code statusline
    hooks/                 # Claude Code hooks
  pi/
    settings.json          # Pi settings
    keybindings.json       # Pi TUI keybindings
    tui.json               # Pi TUI footer/icon colors
    effort.json            # Pi per-model thinking defaults
    extensions/            # Pi extensions
  codex/
    config.toml            # Codex CLI baseline settings
    hooks.json             # Codex hook registration
    hooks/                 # Codex hook scripts

Shared config

Portable across harnesses:

• AGENTS.md — global instructions
• rules/*.md — style, tests, comments, PR workflow, context budget
• skills/*/SKILL.md — Agent Skills-compatible workflow packages
• bin/blueprint — opt-in proposals, reviews, and reports

Blueprints are durable artifacts created only by explicitly invoked artifact skills. Ordinary coding and PR workflows do not create them:

blueprint create proposal "topic"
blueprint create review "topic"
blueprint create report "topic"
blueprint find --type proposal,review,report
blueprint archive <slug>

New spec and plan creation is rejected. Existing files remain findable and archivable for compatibility.

Claude Code adapter

Installed by ./install.sh claude into ~/.claude:

• links CLAUDE.md, AGENTS.md, rules/, skills/
• links harnesses/claude/settings.json as settings.json
• links Claude statusline and hooks

Claude-specific features retained outside shared skills:

• Claude Code hooks and statusline protocol
• Claude plugin settings

Shared skills avoid native task/team dependencies. Blueprints remain optional unless an artifact skill is explicitly invoked.

Pi adapter

Installed by ./install.sh pi into ~/.pi/agent:

• links AGENTS.md, rules/, skills/
• links harnesses/pi/settings.json as settings.json
• links Pi keybindings.json, tui.json, and effort.json when present
• links harnesses/pi/extensions/* into ~/.pi/agent/extensions/
• installs blueprint to ~/.local/bin
• builds crates/context-guard and links context-guard to ~/.local/bin

Pi uses /skill:<name> commands, for example:

/skill:commit
/skill:submit
/skill:research
/skill:review

Direct aliases like /commit can be added later with a Pi extension.

Codex adapter

Installed by ./install.sh codex into ~/.codex and ~/.agents:

• copies harnesses/codex/config.toml as a baseline to ~/.codex/config.toml
• links harnesses/codex/hooks.json and harnesses/codex/hooks/*
• links AGENTS.md and rules/ into ~/.codex as reference files
• links shared skills/ as $HOME/.agents/skills
• links shared rules/ as $HOME/.agents/rules
• installs blueprint to ~/.local/bin

If ~/.codex/config.toml already exists as a real file, the Codex installer backs it up before copying the baseline config. Codex may append local runtime state such as project trust, hook trust hashes, and UI notices to the installed copy; those tables are intentionally not checked into this repo.

Codex reads repository AGENTS.md files automatically. Shared skills are installed through Codex's user skill path and can be invoked with $commit, $submit, $research, $review, and other skill names.

Portability status

Manual artifact skills: context, research, review, diagnose, acceptance, simplify, report, and archive.

Direct workflows may consume artifacts but do not require or create trackers: implement, fix, debug, pr-plan, respond, split-commit, vibe, and resume-work.

Rules

• rules/style.md — simple readable code
• rules/comment-quality.md — comments explain what code cannot
• rules/test-quality.md — tests must catch realistic bugs
• rules/pr-workflow.md — Graphite-first PR workflow
• rules/context-budget.md — conserve context window
• rules/skill-editing.md — keep skills cohesive
• rules/blueprints.md — portable blueprint convention
• rules/harness-compat.md — portability rules for shared content