feat: add github authentication for agent work orders pr creation

.env.example

@@ -32,6 +32,12 @@ LOG_LEVEL=INFO
 # Required for the agent work orders service to execute Claude CLI commands
 ANTHROPIC_API_KEY=
 
+# GitHub Personal Access Token (Required for Agent Work Orders PR creation)
+# Get your token from: https://github.com/settings/tokens
+# Required scopes: repo, workflow
+# The agent work orders service uses this for gh CLI authentication to create PRs
+GITHUB_PAT_TOKEN=
+
 # Service Ports Configuration
 # These ports are used for external access to the services
 HOST=localhost

docker-compose.yml

@@ -175,6 +175,7 @@ services:
       - AGENT_WORK_ORDERS_PORT=${AGENT_WORK_ORDERS_PORT:-8053}
       - CLAUDE_CLI_PATH=${CLAUDE_CLI_PATH:-claude}
       - GH_CLI_PATH=${GH_CLI_PATH:-gh}
+      - GH_TOKEN=${GITHUB_PAT_TOKEN}
     networks:
       - app-network
     volumes:

python/src/agent_work_orders/README.md

@@ -95,6 +95,7 @@ docker compose up -d
 | `ARCHON_MCP_URL` | Auto | MCP server URL (auto-configured by discovery mode) |
 | `CLAUDE_CLI_PATH` | `claude` | Path to Claude CLI executable |
 | `GH_CLI_PATH` | `gh` | Path to GitHub CLI executable |
+| `GH_TOKEN` | - | GitHub Personal Access Token for gh CLI authentication (required for PR creation) |
 | `LOG_LEVEL` | `INFO` | Logging level |
 | `STATE_STORAGE_TYPE` | `memory` | State storage (`memory` or `file`) - Use `file` for persistence |
 | `FILE_STATE_DIRECTORY` | `agent-work-orders-state` | Directory for file-based state (when `STATE_STORAGE_TYPE=file`) |
@@ -167,6 +168,32 @@ docker compose logs -f archon-agent-work-orders
 
 ## Troubleshooting
 
+### GitHub Authentication (PR Creation Fails)
+
+The `gh` CLI requires authentication for PR creation. There are two options:
+
+**Option 1: PAT Token (Recommended for Docker)**
+
+Set `GH_TOKEN` or `GITHUB_TOKEN` environment variable with your Personal Access Token:
+
+```bash
+# In .env file
+GITHUB_PAT_TOKEN=ghp_your_token_here
+
+# Docker compose automatically maps GITHUB_PAT_TOKEN to GH_TOKEN
+```
+
+The token needs these scopes:
+- `repo` (full control of private repositories)
+- `workflow` (if creating PRs with workflow files)
+
+**Option 2: gh auth login (Local development only)**
+
+```bash
+gh auth login
+# Follow interactive prompts
+```
+
 ### Claude CLI Not Found
 
 ```bash

python/src/agent_work_orders/main.py

@@ -15,7 +15,7 @@ configure_structured_logging(config.LOG_LEVEL)
 
 app = FastAPI(
     title="Agent Work Orders API",
-    description="PRD-compliant agent work order system for workflow-based agent execution",
+    description="Agent work order system for workflow-based agent execution",
     version="0.1.0",
 )
 

python/src/agent_work_orders/server.py

@@ -143,6 +143,27 @@ async def health_check() -> dict[str, Any]:
         "available": shutil.which("git") is not None,
     }
 
+    # Check GitHub CLI authentication
+    try:
+        result = subprocess.run(
+            [config.GH_CLI_PATH, "auth", "status"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        # gh auth status returns 0 if authenticated
+        health_status["dependencies"]["github_cli"] = {
+            "available": shutil.which(config.GH_CLI_PATH) is not None,
+            "authenticated": result.returncode == 0,
+            "token_configured": os.getenv("GH_TOKEN") is not None or os.getenv("GITHUB_TOKEN") is not None,
+        }
+    except Exception as e:
+        health_status["dependencies"]["github_cli"] = {
+            "available": False,
+            "authenticated": False,
+            "error": str(e),
+        }
+
     # Check Archon server connectivity (if configured)
     archon_server_url = os.getenv("ARCHON_SERVER_URL")
     if archon_server_url: