Skip to content

Commit 05bbdd8

Browse files
chubes4chubes4
authored
Execute developer-docs and skills agents via runtime-agent-full-run (#102)
* Execute developer-docs and skills agents via runtime-agent-full-run Repoint developer-docs-agent.yml and skills-agent.yml off the plan-only Automattic/docs-agent maintain-docs.yml path onto the executing runner Extra-Chill/homeboy-extensions runtime-agent-full-run.yml, mirroring the working Automattic/intelligence docs-agent consumer. maintain-docs.yml chains to wp-codebox run-agent-task.yml, which is deliberately plan-only, so the docs/skills runs never executed or opened a PR. docs-agent is intentionally runner-neutral (its bundle test forbids wiring execution into maintain-docs.yml), so execution is consumer-owned. The technical-docs-agent and skills-agent docs-agent bundles remain the workload; mounts agents-api + data-machine + data-machine-code runtime dependencies (the bundle uses DMC-registered workspace/git tools). The runner owns publication, opening docs PRs on docs-agent/build-with-wordpress-developer-docs and docs-agent/build-with-wordpress-skills. OpenAI credentials are wired through the PROVIDER_SECRET_1 slot (credentials map connectors_ai_openai_api_key -> PROVIDER_SECRET_1, with PROVIDER_SECRET_1 fed from the OPENAI_API_KEY repo secret) because the runner only forwards PROVIDER_SECRET_1..5 into the run step. Closes #101 * Use default GITHUB_TOKEN instead of requiring a Homeboy app token build-with-wordpress documents its OWN repo and all checked-out dependency repos (docs-agent bundle, agents-api, data-machine, data-machine-code) are public, so the default Actions GITHUB_TOKEN — granted contents/pull-requests: write — can read the deps and open the docs PR in this same repo. Set require_homeboy_app_token=false so the runner uses the GITHUB_TOKEN fallback, and drop the unused HOMEBOY_APP_ID/HOMEBOY_APP_PRIVATE_KEY secret passthroughs. (The Homeboy GitHub App token is only needed for cross-repo/private-repo publication, like the intelligence consumer that documents other repos.) --------- Co-authored-by: Chris Huber <chris.huber@a8c.com>
1 parent d73a502 commit 05bbdd8

2 files changed

Lines changed: 237 additions & 58 deletions

File tree

‎.github/workflows/developer-docs-agent.yml‎

Lines changed: 119 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,15 @@ name: Build With WordPress Developer Docs Agent
22

33
on:
44
workflow_dispatch:
5+
inputs:
6+
docs_agent_ref:
7+
description: Ref of Automattic/docs-agent containing the portable bundle.
8+
required: false
9+
default: main
10+
openai_model:
11+
description: OpenAI model to use.
12+
required: false
13+
default: gpt-5.5
514
push:
615
branches:
716
- trunk
@@ -18,51 +27,68 @@ concurrency:
1827
jobs:
1928
developer-docs-agent:
2029
name: Maintain Developer Docs
21-
uses: Automattic/docs-agent/.github/workflows/maintain-docs.yml@main
30+
# Execute the technical-docs-agent docs bundle through the runtime-agent-full-run
31+
# runner so the agent actually runs and the runner opens a documentation PR.
32+
# docs-agent is intentionally runner-neutral (its maintain-docs.yml only builds a
33+
# plan), so execution is consumer-owned and we call the executing runner directly.
34+
uses: Extra-Chill/homeboy-extensions/.github/workflows/runtime-agent-full-run.yml@main
2235
with:
23-
audience: technical
24-
run_kind: ${{ github.event_name == 'workflow_dispatch' && 'bootstrap' || 'maintenance' }}
25-
base_ref: trunk
26-
docs_branch: docs-agent/build-with-wordpress-developer-docs
27-
docs_agent_ref: main
28-
writable_paths: README.md,docs/**,plugins/**/README.md
29-
bootstrap_contract: |
36+
runtime_provider: wp-codebox
37+
runtime_ref: main
38+
runtime_wordpress_version: '7.0'
39+
runtime_profile: datamachine-agent-ci
40+
runtime_profiles: |
41+
{
42+
"datamachine-agent-ci": {
43+
"id": "datamachine-agent-ci",
44+
"runtime_task_ability": "datamachine/run-agent-bundle",
45+
"runtime_bundle_ability": "datamachine/run-agent-bundle",
46+
"runtime_workflow_ability": "datamachine/execute-workflow",
47+
"ability_requirements": ["datamachine/run-agent-bundle"]
48+
}
49+
}
50+
workload_id: ${{ github.event_name == 'workflow_dispatch' && 'technical-docs-bootstrap-flow' || 'technical-docs-maintenance-flow' }}
51+
workload_label: Run technical-docs-agent Data Machine agent
52+
target_repo: Automattic/build-with-wordpress
53+
provider: openai
54+
provider_plugin: |
55+
{
56+
"repo": "WordPress/ai-provider-for-openai",
57+
"ref": "trunk",
58+
"register_function": "WordPress\\OpenAiAiProvider\\register_provider",
59+
"credentials": {
60+
"connectors_ai_openai_api_key": "PROVIDER_SECRET_1"
61+
}
62+
}
63+
runtime_execution: |
3064
{
31-
"required_paths": [
32-
"README.md",
33-
"docs/README.md",
34-
"docs/architecture.md",
35-
"docs/generated-outputs.md",
36-
"docs/skills-and-integrations.md",
37-
"docs/contributor-workflows.md"
38-
],
39-
"required_globs": [
40-
{
41-
"pattern": "docs/**/*.md",
42-
"min": 5
43-
}
44-
],
45-
"entry_points": [
46-
{
47-
"path": "README.md",
48-
"must_link_to": ["docs/README.md"]
49-
},
50-
{
51-
"path": "docs/README.md",
52-
"must_link_to": [
53-
"docs/architecture.md",
54-
"docs/generated-outputs.md",
55-
"docs/skills-and-integrations.md",
56-
"docs/contributor-workflows.md"
57-
]
58-
}
59-
],
60-
"forbidden_phrases": [
61-
"future coverage",
62-
"deferred",
63-
"saved for later"
64-
]
65+
"kind": "bundle",
66+
"source": ".ci/docs-agent/bundles/technical-docs-agent",
67+
"input": {
68+
"flow_slug": "${{ github.event_name == 'workflow_dispatch' && 'technical-docs-bootstrap-flow' || 'technical-docs-maintenance-flow' }}"
69+
},
70+
"metadata": {
71+
"bundle_repo": "https://github.com/Automattic/docs-agent.git",
72+
"bundle_ref": "${{ github.event_name == 'workflow_dispatch' && inputs.docs_agent_ref || 'main' }}",
73+
"bundle_path_in_repo": "bundles/technical-docs-agent"
74+
}
6575
}
76+
prompt: |
77+
Maintain developer-facing documentation for Build with WordPress.
78+
79+
Manual dispatch runs the bootstrap flow and should create or improve the initial developer documentation structure if the repository does not already have one. Push-triggered merge checks run the maintenance flow and should make the smallest source-grounded documentation update needed for newly merged code or finish with no changes when documentation is current.
80+
81+
Write the developer documentation as repository docs: `docs/README.md` as the index, focused topic pages under `docs/**`, and `plugins/**/README.md` only when a plugin package needs local developer-facing contract notes. For the bootstrap surface, prefer `docs/architecture.md`, `docs/generated-outputs.md`, `docs/skills-and-integrations.md`, and `docs/contributor-workflows.md` as the main topic pages.
82+
83+
Cover the repository purpose, package layout, generated plugin artifacts, build and verification commands, skill packaging, Studio integration points, and contributor workflows. Document agent/plugin configuration files and generated plugin artifacts from those repository docs and plugin README files. Use the read-only context aliases `studio` and `wordpress-agent-skills` only as source evidence for integration behavior.
84+
85+
Write the documentation files into the runner-provided workspace and leave publication to the runner; it commits the workspace changes and opens the documentation pull request.
86+
model: ${{ github.event_name == 'workflow_dispatch' && inputs.openai_model || 'gpt-5.5' }}
87+
max_turns: ${{ github.event_name == 'workflow_dispatch' && 40 || 12 }}
88+
step_budget: ${{ github.event_name == 'workflow_dispatch' && 80 || 16 }}
89+
time_budget_ms: ${{ github.event_name == 'workflow_dispatch' && 1800000 || 600000 }}
90+
runtime_dependencies: Automattic/agents-api@main,Extra-Chill/data-machine@main,Extra-Chill/data-machine-code@main
91+
validation_dependencies: Automattic/docs-agent@${{ github.event_name == 'workflow_dispatch' && inputs.docs_agent_ref || 'main' }}
6692
context_repositories: |
6793
[
6894
{
@@ -100,12 +126,54 @@ jobs:
100126
"description": "Generated package outputs are committed after build"
101127
}
102128
]
103-
prompt: |
104-
Maintain developer-facing documentation for Build with WordPress.
105-
106-
Manual dispatch runs the bootstrap flow and should create or improve the initial developer documentation structure if the repository does not already have one. Push-triggered merge checks run the maintenance flow and should make the smallest source-grounded documentation update needed for newly merged code or finish with no changes when documentation is current.
107-
108-
Write the developer documentation as repository docs: `docs/README.md` as the index, focused topic pages under `docs/**`, and `plugins/**/README.md` only when a plugin package needs local developer-facing contract notes. For the bootstrap surface, prefer `docs/architecture.md`, `docs/generated-outputs.md`, `docs/skills-and-integrations.md`, and `docs/contributor-workflows.md` as the main topic pages.
109-
110-
Cover the repository purpose, package layout, generated plugin artifacts, build and verification commands, skill packaging, Studio integration points, and contributor workflows. Document agent/plugin configuration files and generated plugin artifacts from those repository docs and plugin README files. Use the read-only context aliases `studio` and `wordpress-agent-skills` only as source evidence for integration behavior.
111-
secrets: inherit
129+
writable_paths: README.md,docs/**,plugins/**/README.md
130+
workspace_contract_checks: >-
131+
${{ github.event_name == 'workflow_dispatch' && '{"paths_exist":[{"path":"README.md"},{"path":"docs/README.md"},{"path":"docs/architecture.md"},{"path":"docs/generated-outputs.md"},{"path":"docs/skills-and-integrations.md"},{"path":"docs/contributor-workflows.md"}],"glob_min_count":[{"glob":"docs/**/*.md","min":5}],"entry_points":[{"path":"README.md","must_link_to":["docs/README.md"]},{"path":"docs/README.md","must_link_to":["docs/architecture.md","docs/generated-outputs.md","docs/skills-and-integrations.md","docs/contributor-workflows.md"]}],"forbidden_phrases":["future coverage","deferred","saved for later"]}' || '{}' }}
132+
runner_workspace: |
133+
{
134+
"enabled": true,
135+
"repo": "Automattic/build-with-wordpress",
136+
"clone_url": "https://github.com/Automattic/build-with-wordpress.git",
137+
"branch": "docs-agent/build-with-wordpress-developer-docs",
138+
"branch_prefix": "docs-agent/build-with-wordpress-developer-docs",
139+
"from": "origin/trunk",
140+
"bootstrap": false
141+
}
142+
artifact_export_config: |
143+
{
144+
"pr_title_template": "docs: maintain Build with WordPress developer documentation",
145+
"pr_body_template": "## Build with WordPress developer docs\n\nThe technical-docs-agent Data Machine agent (Automattic/docs-agent `bundles/technical-docs-agent`) updated developer-facing documentation in this repository.\n\n- Flow: {task_id}\n- Publication opened by the runtime-agent-full-run runner.\n",
146+
"commit_message_template": "docs: maintain developer documentation"
147+
}
148+
success_requires_pr: ${{ github.event_name == 'workflow_dispatch' }}
149+
# All checked-out repos (docs-agent bundle, agents-api, data-machine,
150+
# data-machine-code) are public and the target is this same repo, so the
151+
# default GITHUB_TOKEN (granted contents/pull-requests: write above) can
152+
# read deps and open the docs PR. No Homeboy GitHub App token is required;
153+
# the runner falls back to GITHUB_TOKEN when app creds are unavailable.
154+
require_homeboy_app_token: false
155+
required_abilities: |
156+
[
157+
"datamachine/import-agent",
158+
"datamachine/run-flow",
159+
"datamachine/drain-job",
160+
"datamachine-code/workspace-worktree-add"
161+
]
162+
app_token_repos: Automattic/build-with-wordpress,Automattic/docs-agent
163+
allowed_repos: |
164+
[
165+
"Automattic/build-with-wordpress"
166+
]
167+
runtime_output_projections: '{"docs_pr_url":"metadata.engine_data.docs_agent.pr_url"}'
168+
callback_data: |
169+
{
170+
"agent_slug": "technical-docs-agent",
171+
"pipeline_slug": "technical-docs-pipeline",
172+
"flow_slug": "${{ github.event_name == 'workflow_dispatch' && 'technical-docs-bootstrap-flow' || 'technical-docs-maintenance-flow' }}",
173+
"bundle_path": "bundles/technical-docs-agent",
174+
"target_repo": "Automattic/build-with-wordpress"
175+
}
176+
transcript_artifact_name: developer-docs-agent-transcript-${{ github.run_id }}
177+
replay_bundle_artifact_name: developer-docs-agent-replay-${{ github.run_id }}
178+
secrets:
179+
PROVIDER_SECRET_1: ${{ secrets.OPENAI_API_KEY }}

‎.github/workflows/skills-agent.yml‎

Lines changed: 118 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,15 @@ name: Build With WordPress Skills Agent
22

33
on:
44
workflow_dispatch:
5+
inputs:
6+
docs_agent_ref:
7+
description: Ref of Automattic/docs-agent containing the portable bundle.
8+
required: false
9+
default: main
10+
openai_model:
11+
description: OpenAI model to use.
12+
required: false
13+
default: gpt-5.5
514
schedule:
615
- cron: '0 9 * * 1'
716

@@ -10,16 +19,73 @@ permissions:
1019
pull-requests: write
1120
issues: write
1221

22+
concurrency:
23+
group: skills-agent-${{ github.ref }}
24+
cancel-in-progress: false
25+
1326
jobs:
1427
skills-agent:
1528
name: Maintain Live Skills
16-
uses: Automattic/docs-agent/.github/workflows/maintain-docs.yml@main
29+
# Execute the skills-agent docs bundle through the runtime-agent-full-run runner so
30+
# the agent actually runs and the runner opens a skills documentation PR. docs-agent
31+
# is intentionally runner-neutral (its maintain-docs.yml only builds a plan), so
32+
# execution is consumer-owned and we call the executing runner directly.
33+
uses: Extra-Chill/homeboy-extensions/.github/workflows/runtime-agent-full-run.yml@main
1734
with:
18-
audience: skills
19-
base_ref: trunk
20-
docs_branch: docs-agent/build-with-wordpress-skills
21-
docs_agent_ref: main
22-
writable_paths: skills/**,plugins/**/skills/**,plugins/**/README.md
35+
runtime_provider: wp-codebox
36+
runtime_ref: main
37+
runtime_wordpress_version: '7.0'
38+
runtime_profile: datamachine-agent-ci
39+
runtime_profiles: |
40+
{
41+
"datamachine-agent-ci": {
42+
"id": "datamachine-agent-ci",
43+
"runtime_task_ability": "datamachine/run-agent-bundle",
44+
"runtime_bundle_ability": "datamachine/run-agent-bundle",
45+
"runtime_workflow_ability": "datamachine/execute-workflow",
46+
"ability_requirements": ["datamachine/run-agent-bundle"]
47+
}
48+
}
49+
workload_id: skills-maintenance-flow
50+
workload_label: Run skills-agent Data Machine agent
51+
target_repo: Automattic/build-with-wordpress
52+
provider: openai
53+
provider_plugin: |
54+
{
55+
"repo": "WordPress/ai-provider-for-openai",
56+
"ref": "trunk",
57+
"register_function": "WordPress\\OpenAiAiProvider\\register_provider",
58+
"credentials": {
59+
"connectors_ai_openai_api_key": "PROVIDER_SECRET_1"
60+
}
61+
}
62+
runtime_execution: |
63+
{
64+
"kind": "bundle",
65+
"source": ".ci/docs-agent/bundles/skills-agent",
66+
"input": {
67+
"flow_slug": "skills-maintenance-flow"
68+
},
69+
"metadata": {
70+
"bundle_repo": "https://github.com/Automattic/docs-agent.git",
71+
"bundle_ref": "${{ github.event_name == 'workflow_dispatch' && inputs.docs_agent_ref || 'main' }}",
72+
"bundle_path_in_repo": "bundles/skills-agent"
73+
}
74+
}
75+
prompt: |
76+
Maintain live agent skill instructions and generated packaged skill outputs for Build with WordPress.
77+
78+
Run the skills maintenance flow and make the smallest source-grounded skill update needed for newly merged code, or finish with no changes when the skills are current. Edit live skill instructions under `skills/**`, packaged skill outputs under `plugins/**/skills/**`, and `plugins/**/README.md` only when a plugin package needs local developer-facing contract notes.
79+
80+
Use the read-only context aliases `studio` and `wordpress-agent-skills` only as source evidence for integration and packaging behavior.
81+
82+
Write the skill changes into the runner-provided workspace and leave publication to the runner; it commits the workspace changes and opens the skills pull request.
83+
model: ${{ github.event_name == 'workflow_dispatch' && inputs.openai_model || 'gpt-5.5' }}
84+
max_turns: 12
85+
step_budget: 16
86+
time_budget_ms: 600000
87+
runtime_dependencies: Automattic/agents-api@main,Extra-Chill/data-machine@main,Extra-Chill/data-machine-code@main
88+
validation_dependencies: Automattic/docs-agent@${{ github.event_name == 'workflow_dispatch' && inputs.docs_agent_ref || 'main' }}
2389
context_repositories: |
2490
[
2591
{
@@ -57,4 +123,49 @@ jobs:
57123
"description": "Generated skill package outputs are committed after build"
58124
}
59125
]
60-
secrets: inherit
126+
writable_paths: skills/**,plugins/**/skills/**,plugins/**/README.md
127+
runner_workspace: |
128+
{
129+
"enabled": true,
130+
"repo": "Automattic/build-with-wordpress",
131+
"clone_url": "https://github.com/Automattic/build-with-wordpress.git",
132+
"branch": "docs-agent/build-with-wordpress-skills",
133+
"branch_prefix": "docs-agent/build-with-wordpress-skills",
134+
"from": "origin/trunk",
135+
"bootstrap": false
136+
}
137+
artifact_export_config: |
138+
{
139+
"pr_title_template": "docs: maintain Build with WordPress live skills",
140+
"pr_body_template": "## Build with WordPress live skills\n\nThe skills-agent Data Machine agent (Automattic/docs-agent `bundles/skills-agent`) updated live skill instructions and generated packaged skill outputs in this repository.\n\n- Flow: {task_id}\n- Publication opened by the runtime-agent-full-run runner.\n",
141+
"commit_message_template": "docs: maintain live skills"
142+
}
143+
success_requires_pr: false
144+
# Public deps + same-repo target → default GITHUB_TOKEN suffices; no
145+
# Homeboy GitHub App token required (runner falls back to GITHUB_TOKEN).
146+
require_homeboy_app_token: false
147+
required_abilities: |
148+
[
149+
"datamachine/import-agent",
150+
"datamachine/run-flow",
151+
"datamachine/drain-job",
152+
"datamachine-code/workspace-worktree-add"
153+
]
154+
app_token_repos: Automattic/build-with-wordpress,Automattic/docs-agent
155+
allowed_repos: |
156+
[
157+
"Automattic/build-with-wordpress"
158+
]
159+
runtime_output_projections: '{"docs_pr_url":"metadata.engine_data.docs_agent.pr_url"}'
160+
callback_data: |
161+
{
162+
"agent_slug": "skills-agent",
163+
"pipeline_slug": "skills-pipeline",
164+
"flow_slug": "skills-maintenance-flow",
165+
"bundle_path": "bundles/skills-agent",
166+
"target_repo": "Automattic/build-with-wordpress"
167+
}
168+
transcript_artifact_name: skills-agent-transcript-${{ github.run_id }}
169+
replay_bundle_artifact_name: skills-agent-replay-${{ github.run_id }}
170+
secrets:
171+
PROVIDER_SECRET_1: ${{ secrets.OPENAI_API_KEY }}

0 commit comments

Comments
 (0)