ry-agent-native

Reusable workflow plugin for the Agent-Native AI Development Workflow — Roy's Unified Stack.

Each script, prompt, config template, and slash command lives in its own file. This repo is the single source of truth: edit one file here, propagate the change to all projects that bootstrap from it.

Source documents preserved under docs/:

• Roy_Agent_Native_Workflow_v2.1.md — full spec
• Agent-Native-Workflow-Field-Guide.md — scenario playbook

---

What this repo gives you

• templates/project-workspace/ — Drop-in skeleton for a new project's project-workspace repo. Contains .claude/{hooks,scripts,prompts,personas,poller-state}, design-tokens/, CLAUDE.md, repos.json, .env.example, .gitignore.
• templates/ralph/ — wrapper.sh, .ralphrc, and fix_plan.example.md for each repo worktree.
• templates/launchd/ — com.roy.agent-coordinator.plist and com.roy.daily-digest.plist (15-min poll + 7am digest).
• templates/github-actions/ci.yml — Per-repo CI workflow (the only thing left on GitHub Actions).
• templates/repo-claude/CLAUDE.md — Per-repo agent instructions template.
• claude/commands/ — Slash commands for Roy's daily use in Claude Code.
• bootstrap/ — Setup scripts: system deps, plugins, new project bootstrap.

---

Prerequisites

Per docs/Roy_Agent_Native_Workflow_v2.1.md Section 19:

• Mac Mini M4 (or any 24/7 macOS host)
• Homebrew, Node 20+, Bun 1.0+, Go 1.22+, Python 3, gh, jq, tmux, coreutils
• Claude Code CLI v2.1.89+ (npm i -g @anthropic-ai/claude-code)
• Plugins: GSTACK, Superpowers v5.1.0+, Graphify, Ralph (install via bootstrap/install-plugins.sh)
• Linear workspace + MCP access (https://mcp.linear.app/mcp)
• GitHub bot account with Write access to all code repos (PAT in .env)
• Slack incoming webhooks (one per #agent-<repo> channel + #agent-ops)
• v0 by Vercel, html.to.design Figma plugin, tweakcn (UI work only)

---

Bootstrap a new project

# 1. One-time on the Mac Mini
./bootstrap/install-system-deps.sh
./bootstrap/install-plugins.sh

# 2. Per project
./bootstrap/bootstrap-project-workspace.sh <PROJECT_NAME> <TARGET_PARENT_DIR>

The bootstrap creates <TARGET_PARENT_DIR>/<PROJECT_NAME>/project-workspace/ with every template copied in and hooks made executable.

Then, in the new project-workspace:

1. Edit repos.json — replace GITHUB_ORG and *_REPO_NAME placeholders.
2. cp .env.example .env — fill in GITHUB_TOKEN, all SLACK_WEBHOOK_*, CLAUDE_PROJECT_DIR.
3. Edit the two templates/launchd/*.plist files — replace PROJECT_WORKSPACE_PATH with the absolute path. Copy to ~/Library/LaunchAgents/, then launchctl load each.
4. Replace persona templates: run GSTACK /plan-ceo-review, /plan-eng-review, /plan-design-review and overwrite .claude/personas/{ceo,engineer,designer}.md.
5. Install Graphify per code repo (Section 19.3 step 7):

   for repo in backend frontend admin mobile; do
     ( cd ../$repo && graphify install --project && graphify hook install && mkdir -p .claude/specs )
   done

6. Drop templates/github-actions/ci.yml into each code repo at .github/workflows/ci.yml and fill in the language-specific steps.
7. In Claude Code, run /setup-linear (one-time workspace setup), then /migrate-wbs (one-time WBS migration).

Full setup steps: docs/Roy_Agent_Native_Workflow_v2.1.md Section 19.3.

---

Placeholder convention

Every project-specific value in a template uses SCREAMING_SNAKE_CASE. Search-and-replace targets:

Placeholder	Where	What to put
GITHUB_ORG	repos.json	Your GitHub organization name
BACKEND_REPO_NAME / FRONTEND_REPO_NAME / ADMIN_REPO_NAME / MOBILE_REPO_NAME	repos.json	Your repo names
PROJECT_NAME	.ralphrc	Set automatically by bootstrap-project-workspace.sh
PROJECT_WORKSPACE_PATH	launchd .plist files, agent-coordinator.sh, .env.example	Absolute path to project-workspace on Mac Mini
GITHUB_BOT_TOKEN	.env.example, launchd plist	Bot PAT (Write access; rotate monthly)
SLACK_WEBHOOK_*_URL	.env.example, launchd plist	Incoming webhook URLs
LINEAR_ISSUE_ID	templates/ralph/fix_plan.example.md	Issue ID like AUTH-010
SUBTASK_DESCRIPTION	templates/ralph/fix_plan.example.md	Sub-issue text

---

Slash commands (claude/commands/)

These are copied into each project's .claude/commands/ by bootstrap-project-workspace.sh. Roy invokes them from Claude Code daily:

Command	Stage	Purpose
/setup-linear	0	One-time Linear workspace setup (teams, statuses, labels)
/migrate-wbs	0	One-time Excel WBS → Linear migration
/plan-issue <ID>	1	Office-hours + autoplan + spec + sub-issues for a Linear issue
/mockup <ID>	1	UI mockup sub-workflow (v0 + Figma, Gate B)
/bug-report	—	QA bug report template
/simple-fix <ID>	—	Trigger the simple-fix shortcut path
/review-pr <PR> <REPO> <ID>	2	Manually re-run the PR review agent
/halt-triage <ID> <REPO>	2	Diagnose a Ralph halt, recommend action
/morning-digest	—	On-demand version of the 7am digest

---

Editing the workflow

When Roy wants to change behavior:

1. Edit the file in this repo (e.g. templates/project-workspace/.claude/hooks/pr-reviewer.sh).
2. Commit + tag (git tag v2.1.X).
3. In each project, pull updates:

   cd <ry-agent-native-checkout> && git pull
   # then for each project:
   rsync -a --exclude='specs' --exclude='mockups' --exclude='learnings' --exclude='.env' --exclude='.claude/logs' \
     templates/project-workspace/ <project>/project-workspace/

Project-local data (specs/, mockups/, learnings/, .env, .claude/logs/, .claude/poller-state/) is preserved by the exclude list.

---

Directory map

ry-agent-native/
├── README.md
├── docs/
│   ├── Roy_Agent_Native_Workflow_v2.1.md      # Full spec (source of truth)
│   └── Agent-Native-Workflow-Field-Guide.md   # Scenario playbook
├── bootstrap/
│   ├── install-system-deps.sh
│   ├── install-plugins.sh
│   └── bootstrap-project-workspace.sh
├── claude/commands/                            # Slash commands
│   ├── setup-linear.md
│   ├── migrate-wbs.md
│   ├── plan-issue.md
│   ├── mockup.md
│   ├── bug-report.md
│   ├── simple-fix.md
│   ├── review-pr.md
│   ├── halt-triage.md
│   └── morning-digest.md
├── templates/
│   ├── project-workspace/                      # Drop-in skeleton
│   │   ├── CLAUDE.md
│   │   ├── repos.json
│   │   ├── .env.example
│   │   ├── .gitignore
│   │   ├── .claude/
│   │   │   ├── settings.json
│   │   │   ├── hooks/         # 13 scripts (4 fully extracted, 9 stubbed)
│   │   │   ├── scripts/       # post-pr-review.py
│   │   │   ├── prompts/       # pr-reviewer-system.md
│   │   │   ├── personas/      # ceo/engineer/designer
│   │   │   └── poller-state/  # empty JSON files
│   │   └── design-tokens/
│   │       ├── sync-tokens.sh
│   │       ├── web/
│   │       └── mobile/
│   ├── ralph/
│   │   ├── wrapper.sh
│   │   ├── .ralphrc
│   │   └── fix_plan.example.md
│   ├── launchd/
│   │   ├── com.roy.agent-coordinator.plist
│   │   └── com.roy.daily-digest.plist
│   ├── github-actions/
│   │   └── ci.yml
│   └── repo-claude/
│       └── CLAUDE.md