Execute developer-docs and skills agents via runtime-agent-full-run

[chubes4]

Closes #101

Problem

developer-docs-agent.yml and skills-agent.yml called Automattic/docs-agent/.github/workflows/maintain-docs.yml@main, whose run-agent job chains to Automattic/wp-codebox/.github/workflows/run-agent-task.yml@main. That wp-codebox workflow is deliberately plan-only — it builds a task-request artifact and never executes. So both Build with WordPress docs workflows only planned: the documentation agent never ran and no documentation PR was ever opened.

docs-agent is intentionally runner-neutral — its tests/validate-docs-agent-bundle.php enforces that maintain-docs.yml stays on the plan-only runner and forbids wiring execution/credentials into docs-agent, and forbids hardcoding downstream context (Studio, agent-skills) there. Execution is therefore consumer-owned: the consumer must call an executing runner directly. This PR does exactly that, mirroring the working executing consumer Automattic/intelligence/.github/workflows/docs-agent.yml. No changes to docs-agent, wp-codebox, or homeboy-extensions.

Before / after uses:

	Before	After
developer-docs-agent.yml	Automattic/docs-agent/.github/workflows/maintain-docs.yml@main (plan-only)	Extra-Chill/homeboy-extensions/.github/workflows/runtime-agent-full-run.yml@main (executes)
skills-agent.yml	Automattic/docs-agent/.github/workflows/maintain-docs.yml@main (plan-only)	Extra-Chill/homeboy-extensions/.github/workflows/runtime-agent-full-run.yml@main (executes)

Input mapping (docs use case preserved)

The docs use case is unchanged; only the execution path moved. Mapping from the old maintain-docs.yml inputs to the executing runner:

docs use case	old maintain-docs input	new runtime-agent-full-run input
Workload / flow	audience: technical + run_kind	workload_id / runtime_execution.input.flow_slug = technical-docs-bootstrap-flow (dispatch) or technical-docs-maintenance-flow (push to trunk); skills = skills-maintenance-flow
Docs bundle	(implicit via maintain-docs)	runtime_execution.source: .ci/docs-agent/bundles/technical-docs-agent (skills: bundles/skills-agent), bundle_repo: Automattic/docs-agent, bundle_ref: docs_agent_ref
Base branch	base_ref: trunk	runner_workspace.from: origin/trunk (normalized to base trunk)
Docs branch	docs_branch: docs-agent/build-with-wordpress-developer-docs	runner_workspace.branch = same (skills: docs-agent/build-with-wordpress-skills)
Writable paths	writable_paths	writable_paths (README.md,docs/**,plugins/**/README.md; skills skills/**,plugins/**/skills/**,plugins/**/README.md)
Bootstrap contract	bootstrap_contract (required_paths/required_globs)	workspace_contract_checks (paths_exist/glob_min_count/entry_points/forbidden_phrases) — gated to dispatch/bootstrap
Context aliases	context_repositories (studio, wordpress-agent-skills)	context_repositories (same)
Verification	verification_commands (pnpm install/build/verify)	verification_commands (same)
Drift	drift_checks (git diff --exit-code)	drift_checks (same)
Prompt	prompt	prompt (same docs prompt, publication-neutral)

Bundle/recipe content stays sourced from Automattic/docs-agent. Runtime dependencies Automattic/agents-api@main,Extra-Chill/data-machine@main,Extra-Chill/data-machine-code@main are mounted because the docs-agent bundle uses DMC-registered workspace/git tools. runtime_profile: datamachine-agent-ci and its inline runtime_profiles JSON match the intelligence consumer exactly.

Provider-secret wiring (the gotcha)

runtime-agent-full-run.yml only declares/forwards PROVIDER_SECRET_1..5 into the run step; it never forwards a raw OPENAI_API_KEY env. The runner forwards a provider secret only if the credential's mapped env name is a known forwarded slot. So:

provider_plugin:
  credentials:
    connectors_ai_openai_api_key: "PROVIDER_SECRET_1"   # mapped env name = forwarded slot
secrets:
  PROVIDER_SECRET_1: ${{ secrets.OPENAI_API_KEY }}        # repo OPENAI_API_KEY -> slot 1

This is the working form. The latent-bug form maps connectors_ai_openai_api_key to a raw OPENAI_API_KEY env that the run step never sets, so the key silently never reaches the provider. We use the slot form, fed from the repo's existing OPENAI_API_KEY secret.

Why it now executes and publishes

• The job runs runtime-agent-full-run.yml, which sets up the WP Codebox runtime, materializes runtime/validation dependencies, and actually invokes the docs-agent bundle through run-headless-loop.cjs (not a plan artifact).
• The runner owns publication via runner_workspace: after the agent writes files, workspace-publication-lifecycle.cjs resets the publication branch from origin/trunk, commits, pushes docs-agent/build-with-wordpress-developer-docs (skills: docs-agent/build-with-wordpress-skills), and opens/updates a PR with the artifact_export_config title/body templates. success_requires_pr is true for bootstrap (dispatch) and false for maintenance (push / scheduled), so a no-op maintenance run passes without a PR.

Verification

• YAML parses; 0 unknown with: keys, 0 unknown secrets:, 0 missing required inputs (runtime_profiles, target_repo, workload_id all present), checked against runtime-agent-full-run.yml's declared contract (81 inputs, 7 secrets).
• All embedded JSON payloads validate; runner_workspace.branch/from, provider_plugin.credentials, and the gated bootstrap workspace_contract_checks JSON parse cleanly.
• Structural parity with Automattic/intelligence/.github/workflows/docs-agent.yml: same runner, same datamachine-agent-ci profile mechanism, same publication shape.

AI assistance

• AI assistance: Yes
• Tool(s): Claude Opus 4.8 via Claude Code
• Used for: Root-cause confirmation, workflow rewrite, and contract verification.