feat(harper-best-practices): add delegating-to-the-built-in-agent rule

[kriszyp]

What

Adds a new ops rule to the harper-best-practices skill: delegating-to-the-built-in-agent.

It teaches a client agent the lifecycle for handing work to Harper's built-in agent (the agent_prompt operations API + harper agent CLI landing in 5.2 via the harper#626 stack):

• When to delegate — server-side work best done in-process (schema/component changes, restart, worker debug/profile via the inspector, larger multi-step handoffs).
• Prerequisites — agent: enabled + a generative backend; all agent ops are super_user.
• Two drive paths — the harper agent CLI (reuses harper login creds, zero connector setup) and the raw operations API (agent_prompt → poll get_agent_session → approve_agent_action on awaiting_approval → continue via session_id).
• MCP alternative — curated agent tools at the ops API /mcp endpoint for MCP-native clients.

Cross-links deploying-to-harper-fabric so the deploy → connect → delegate flow reads as one lifecycle.

Why

Closes the UX gap where the skills path taught building + deploying an app but had no knowledge of the built-in agent it could delegate to. This makes the skills route a first-class, low-friction way to reach the agent (piggybacks on the deploy credential chain) alongside MCP.

Mechanics

• mode: synthesized (hand-authored — no upstream doc source exists for #626 yet).
• Manifest entry added (ops, priority 4, order 7); SKILL.md index and AGENTS.md regenerated deterministically from the manifest/bodies. Purely additive (0 deletions).
• npm run build, format:check, validate-skills, and validate-generated all pass.

⚠️ Merge / release timing

Draft — the ops this rule documents ship with the harper#626 stack in 5.2. Do not merge/release before that stack lands, or the skill will reference operations that don't exist yet. Target: release just ahead of the 5.2 cut.

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request adds comprehensive documentation and best practices for delegating tasks to Harper's built-in agent (introduced in Harper 5.2+), updating AGENTS.md, SKILL.md, rules.manifest.yaml, and creating a new rule file delegating-to-the-built-in-agent.md. The review feedback suggests formatting improvements to ensure proper YAML spacing (e.g., autoApprove: false instead of autoApprove:false) in the inline examples, and recommends enhancing the programmatic polling loop example to capture and print the final session status rather than exiting silently.

[gemini-code-assist]

In YAML, keys and values should be separated by a space after the colon (e.g., autoApprove: false instead of autoApprove:false). This ensures standard YAML formatting and prevents potential parsing issues if users copy-paste this configuration.

Suggested change

	3. **Approve or deny a paused action.** When the agent enabled configuration has `autoApprove:false`,
	3. **Approve or deny a paused action.** When the agent enabled configuration has `autoApprove: false`,

[gemini-code-assist]

In YAML, keys and values should be separated by a space after the colon (e.g., autoApprove: false instead of autoApprove:false). This ensures standard YAML formatting and prevents potential parsing issues if users copy-paste this configuration.

Suggested change

	- **Approvals are your safety gate.** With `autoApprove:false`, the agent pauses before destructive
	- **Approvals are your safety gate.** With `autoApprove: false`, the agent pauses before destructive

[gemini-code-assist]

The current programmatic polling loop exits as soon as the status is no longer "running". However, if the session transitions to awaiting_approval, the loop terminates silently without indicating the final status or prompting the user. Capturing the final status in a variable and printing it after the loop exits provides better visibility and debugging information.

Suggested change

	while [ "$(curl -s -u <user>:<pass> <ops-endpoint> -H 'Content-Type: application/json' \
	-d "{\"operation\":\"get_agent_session\",\"session_id\":\"$SID\"}" | jq -r .status)" = "running" ]; do
	sleep 3
	done
	while true; do
	STATUS=$(curl -s -u <user>:<pass> <ops-endpoint> -H 'Content-Type: application/json' \
	-d "{\"operation\":\"get_agent_session\",\"session_id\":\"$SID\"}" | jq -r .status)
	if [ "$STATUS" != "running" ]; then
	break
	fi
	sleep 3
	done
	echo "Session ended with status: $STATUS"

[gemini-code-assist]

In YAML, keys and values should be separated by a space after the colon (e.g., autoApprove: false instead of autoApprove:false). This ensures standard YAML formatting and prevents potential parsing issues if users copy-paste this configuration.

Suggested change

	3. **Approve or deny a paused action.** When the agent enabled configuration has `autoApprove:false`,
	3. **Approve or deny a paused action.** When the agent enabled configuration has `autoApprove: false`,

[gemini-code-assist]

In YAML, keys and values should be separated by a space after the colon (e.g., autoApprove: false instead of autoApprove:false). This ensures standard YAML formatting and prevents potential parsing issues if users copy-paste this configuration.

Suggested change

	- **Approvals are your safety gate.** With `autoApprove:false`, the agent pauses before destructive
	- **Approvals are your safety gate.** With `autoApprove: false`, the agent pauses before destructive

[gemini-code-assist]

The current programmatic polling loop exits as soon as the status is no longer "running". However, if the session transitions to awaiting_approval, the loop terminates silently without indicating the final status or prompting the user. Capturing the final status in a variable and printing it after the loop exits provides better visibility and debugging information.

Suggested change

	while [ "$(curl -s -u <user>:<pass> <ops-endpoint> -H 'Content-Type: application/json' \
	-d "{\"operation\":\"get_agent_session\",\"session_id\":\"$SID\"}" | jq -r .status)" = "running" ]; do
	sleep 3
	done
	while true; do
	STATUS=$(curl -s -u <user>:<pass> <ops-endpoint> -H 'Content-Type: application/json' \
	-d "{\"operation\":\"get_agent_session\",\"session_id\":\"$SID\"}" | jq -r .status)
	if [ "$STATUS" != "running" ]; then
	break
	fi
	sleep 3
	done
	echo "Session ended with status: $STATUS"