Design the `orfe` custom tool and CLI contract

[z0r4n-bot]

Context

The current GitHub workflow uses a mix of:

• gh CLI with minted GitHub App installation tokens
• proxy-backed GitHub MCP reads
• direct GraphQL mutations for operations not exposed by GitHub MCP

We want to replace that ad hoc mix with a deterministic, reusable interface named orfe.

The long-term direction is:

• an installable CLI named orfe
• an OpenCode custom tool named orfe
• caller resolution through context.agent at the OpenCode wrapper boundary
• caller-name to GitHub-role mapping through repo-local configuration
• internal GitHub App token minting inside orfe
• direct GitHub REST/GraphQL calls instead of GitHub MCP as the primary execution path
• a committed repo-local config model plus separate machine-local auth configuration
• Octokit as the GitHub API client layer

A local PoC already validated that the wrapper can infer the current caller from context.agent without requiring manual role selection in the tool API.

For stand-alone orfe V1, the owned command surface should stay limited to generic issue operations, generic PR operations, and GitHub Project Status field read/write operations. Repo-specific [WORKFLOW] comment semantics belong in a higher layer built on top of generic operations.

Desired outcome

Produce and approve the canonical V1 orfe specification as a committed repository artifact.

Deliverable

Add a committed spec document for V1 orfe, for example at docs/orfe/spec.md.

Scope

The spec should define:

• the overall architecture of the orfe package, CLI/core, and OpenCode custom tool wrapper
• the wrapper/core boundary, where the wrapper reads context.agent and passes a plain callerName into the orfe core
• caller resolution rules using context.agent at the wrapper layer only
• the repo-local configuration model, including caller-name to GitHub-role mapping
• the machine-local auth configuration model for GitHub App credentials and key material
• the internal auth/provider model, where orfe mints GitHub App installation tokens itself rather than shelling out to an external token command
• the CLI subcommand structure
• the V1 command surface for generic issue, generic pr, and GitHub Project Status field operations
• naming conventions such as pr_number and get-or-create
• required success output, help, and invalid-usage behavior
• explicit scope boundaries and non-goals
• the GitHub API client approach, using Octokit rather than gh or GitHub MCP as the implementation layer

For each V1 command, the spec should define:

• description / purpose
• command name
• arguments/options
• success return shape
• side effects
• failure behavior
• idempotency expectations where relevant

Dependencies

This issue is the design/spec prerequisite for the rest of the orfe V1 backlog.

Acceptance criteria

• a committed V1 orfe spec document exists in the repository
• the spec defines the architecture of the package, CLI/core, and custom tool wrapper
• the spec defines the wrapper/core boundary and explicitly states that context.agent is consumed only at the wrapper boundary
• the spec defines repo-local caller-name to GitHub-role mapping
• the spec defines the repo-local config model
• the spec defines the separate machine-local auth configuration model
• the spec explicitly states that GitHub Apps are the default and only auth mode in v1
• the spec explicitly states that token minting is internal to orfe
• the spec does not require or expose an external token_command contract for v1
• the spec defines the CLI subcommand hierarchy
• the spec defines the V1 command surface and keeps it limited to generic issue operations, generic PR operations, and GitHub Project Status field read/write operations
• the spec defines the GitHub API client layer and explicitly states that orfe should use Octokit as the official JS/TS GitHub client
• each V1 command has a documented description, arguments, return shape, side effects, failure behavior, and idempotency expectation where relevant
• the spec defines help and invalid-usage behavior
• the spec defines naming conventions needed by follow-up issues
• the spec is specific enough that issues Build orfe foundation and runtime scaffolding #14 and Add contract tests and command scaffolding for the orfe CLI and custom tool #15 can proceed without reopening design questions

Non-goals

• implementing the orfe package
• building command scaffolding
• writing contract tests
• changing agent permissions
• replacing gh immediately
• adding install-time config scaffolding
• defining repo-specific [WORKFLOW] comment formatting or event vocabularies
• defining rollout, adoption, or permission policy for a specific repository