# openspec/changes/wf-hire-an-agent/proposal.md

## Why

New agents start on a shared service key with wide access. Nobody knows what they will do, and when one leaves, its keys stay behind in every tool. You can let an agent do real work in week one without betting the production database on it, and prove to a reviewer what it was allowed to do.

## What Changes

- Add the `hire-an-agent` workflow to the PromptReports workflow library, run by the workflow runner as an agent acting for a person.
- PromptCompute: Register the agent (agt_) and its version (agv_) from a signed manifest (today: Built).
- PromptCompute: Put its environment in listen mode (today: Built).
- ContextFile: Give it a starter context packet (today: Planned).
- RepoOps: Load the lessons it must read before it acts (today: Built).
- PromptCompute: Review earned autonomy per action after the trial (today: Built).
- PromptCompute: Offboard: revoke its keys and tokens in every product (today: Planned).
- Gate `grant.create`, `access.grant`, `access.revoke` through PromptCompute approvals; each gated step runs only after `verifyResume` passes, with `final_args`.
- Write a signed record at the end of each run and count one workflow request.

## Impact

- Products: PromptCompute, ContextFile, RepoOps.
- Outside the family: GitHub, The agent's runtime (any MCP client).
- State: Planned. Deferred: the plan keeps the agent registry (LDG-2265) and builds the guided hire flow only when a customer asks for it. Registration, versions, listen mode and earned autonomy exist in PromptCompute.
- Plan row: LDG-2271.

# openspec/changes/wf-hire-an-agent/tasks.md

## 1. Connect and authorize

- [ ] 1.1 Confirm the org has a connection for each of: PromptCompute, ContextFile, RepoOps. Stop and tell the user which is missing.
- [ ] 1.2 Get a PromptReports ID agent token for each product the run calls (RFC 8693 exchange). Where a product does not accept ID tokens yet, use its connect key.
- [ ] 1.3 Register policy for `grant.create`, `access.grant`, `access.revoke` with `require_approval` as the default.

## 2. Build the steps

- [ ] 2.1 PromptCompute: Register the agent (agt_) and its version (agv_) from a signed manifest.
- [ ] 2.2 PromptCompute: Put its environment in listen mode.
- [ ] 2.3 ContextFile: Give it a starter context packet. Blocked: this part is Planned; until it ships, record the step's evidence as `missing` and continue.
- [ ] 2.4 RepoOps: Load the lessons it must read before it acts.
- [ ] 2.5 PromptCompute: Review earned autonomy per action after the trial.
- [ ] 2.6 PromptCompute: Offboard: revoke its keys and tokens in every product. Blocked: this part is Planned; until it ships, record the step's evidence as `missing` and continue.

## 3. Verify and record

- [ ] 3.1 Run a dry run with the user's inputs: Agent name = billing-fixer; Manifest = git commit, model, prompt hash; Starting scope = repoops.open_pr, fix.apply.
- [ ] 3.2 Run it once for real; approve each gate as the user.
- [ ] 3.3 Measure the outcomes: Agents on their own identity: target 100%; Days in listen mode before enforce; Minutes to offboard an agent from every product.
- [ ] 3.4 Confirm the run left a signed record with a task id and one workflow request counted.

# openspec/changes/wf-hire-an-agent/specs/workflow-hire-an-agent/spec.md

## ADDED Requirements

### Requirement: Every hired agent has its own identity

The workflow SHALL register an agt_ agent with an Ed25519 key and an agv_ version before granting any scope.

#### Scenario: Every hired agent has its own identity

- **WHEN** the manifest detail does not hash to its declared digest
- **THEN** registration is refused with manifest_detail_mismatch and the run stops

### Requirement: Offboarding reaches every product

The offboard step SHALL revoke the agent's tokens in each connected product and SHALL report each product that did not confirm.

#### Scenario: Offboarding reaches every product

- **WHEN** one product does not confirm revocation within ten minutes
- **THEN** the run marks that product missing and opens an approval for a manual revoke

### Requirement: Evidence stays honest

Each step SHALL report what it saw as measured, inferred or missing, and SHALL never report missing as measured.

#### Scenario: A product part is not built

- **WHEN** a step depends on a part that is Planned or Proposed
- **THEN** the step records `missing`, names the part, and the approval card shows the gap

### Requirement: One run is one workflow request

The runner SHALL count one workflow request when the first step starts, and SHALL NOT count retries, resumes or dry runs.

#### Scenario: A gated step resumes after two days

- **WHEN** a person approves a step and the run resumes
- **THEN** the org's usage does not change