OpenAgentsControl/.github/PROJECT_CLI_GUIDE.md

GitHub Project CLI Guide

Quick reference for managing your OpenAgents Control project board from the terminal.

🚀 Quick Start

# View all available commands
make help

# Create a new idea
make idea TITLE="Add eval harness for OSS models" LABELS="idea,evals"

# List all ideas
make ideas

# Open project board in browser
make board

---

📋 Common Workflows

Creating Ideas

Simple idea:

make idea TITLE="Improve documentation"

Idea with description:

make idea TITLE="Add support for Cursor" BODY="Extend the framework to work with Cursor IDE" LABELS="idea,feature"

Using gh directly:

gh issue create \
  --repo darrenhinde/OpenAgentsControl \
  --title "Add eval harness for small OSS models" \
  --body "Problem: Need to test agents with smaller models\n\nProposed solution: Create eval harness" \
  --label "idea,agents,evals"

Viewing & Managing Ideas

List all open ideas:

make ideas
# or
gh issue list --repo darrenhinde/OpenAgentsControl --label idea

View specific issue:

make issue-view NUM=123
# or
gh issue view 123 --repo darrenhinde/OpenAgentsControl

Comment on an idea:

make issue-comment NUM=123 COMMENT="Leaning towards X approach"
# or
gh issue comment 123 --repo darrenhinde/OpenAgentsControl --body "Great idea!"

Close when done:

make issue-close NUM=123
# or
gh issue close 123 --repo darrenhinde/OpenAgentsControl

Project Board Management

Open board in browser:

make board

View project info:

make project-info

List all project items:

make project-items

Add issue to project:

make add-to-project ISSUE_URL=https://github.com/darrenhinde/OpenAgentsControl/issues/123
# or
gh project item-add 2 --owner darrenhinde --url https://github.com/darrenhinde/OpenAgentsControl/issues/123

---

🏷️ Labels

Available labels for categorizing issues:

• idea - High-level proposals
• feature - New features
• bug - Bug fixes
• docs - Documentation
• agents - Agent system
• evals - Evaluation framework
• framework - Core framework

List all labels:

make labels

Create new label:

gh label create "priority-high" --repo darrenhinde/OpenAgentsControl --color "d73a4a" --description "High priority"

---

🔧 Advanced Usage

Edit Project Fields (Status, Priority)

Note: This requires knowing the item ID from the project.

# Get item list with IDs
gh project item-list 2 --owner darrenhinde --format json

# Edit item status
gh project item-edit 2 \
  --owner darrenhinde \
  --id ITEM_ID \
  --field "Status" \
  --value "In Progress"

Milestones

Create milestone:

gh milestone create "v0.2 - DX & Examples" \
  --repo darrenhinde/OpenAgentsControl \
  --description "Short-term focus on developer experience"

Attach milestone to issue:

gh issue edit 123 --repo darrenhinde/OpenAgentsControl --milestone "v0.2 - DX & Examples"

Bulk Operations

Close multiple issues:

for i in 123 124 125; do
  gh issue close $i --repo darrenhinde/OpenAgentsControl
done

Add label to multiple issues:

for i in 123 124 125; do
  gh issue edit $i --repo darrenhinde/OpenAgentsControl --add-label "priority-high"
done

---

📝 Daily Workflow Example

# Morning: Check what's on the board
make ideas

# Create a new idea
make idea TITLE="Add local eval runner" BODY="Run evals locally without cloud" LABELS="idea,evals"

# Start working on issue #42
make issue-comment NUM=42 COMMENT="Starting work on this today"

# Open board to see progress
make board

# Evening: Close completed issue
make issue-close NUM=42

---

🔗 Resources

• Project Board: https://github.com/users/darrenhinde/projects/2
• Repository: https://github.com/darrenhinde/OpenAgentsControl
• GitHub CLI Docs: https://cli.github.com/manual/

---

💡 Tips

1. Use aliases in your shell:

   # Add to ~/.bashrc or ~/.zshrc
   alias oa-idea='make -C ~/Documents/GitHub/opencode-agents idea'
   alias oa-list='make -C ~/Documents/GitHub/opencode-agents ideas'
   alias oa-board='make -C ~/Documents/GitHub/opencode-agents board'
   

2. Create issue templates:

   • Already available in .github/ISSUE_TEMPLATE/
   • Use gh issue create to pick a template interactively

3. Use saved searches:

   # Save common queries as shell functions
   function oa-my-issues() {
    gh issue list --repo darrenhinde/OpenAgentsControl --assignee @me
   }
   

4. Combine with git workflow:

   # Create issue and branch in one go
   ISSUE=$(gh issue create --repo darrenhinde/OpenAgentsControl --title "Fix bug" --label bug --format json | jq -r .number)
   git checkout -b "fix/issue-$ISSUE"
   

---

Last Updated: December 4, 2025