From 9313931537767e0caa881d3e6bfa3258b99f4d72 Mon Sep 17 00:00:00 2001 From: Nicholas Romero Date: Fri, 3 Apr 2026 10:03:37 -0500 Subject: [PATCH] fix(platform_engineer): ask release policy before automation --- library/jobs/platform_engineer/AGENTS.md | 4 +- library/jobs/platform_engineer/job.yml | 57 +++++++++++++++---- .../platform_engineer/steps/audit_release.md | 24 ++++++++ .../steps/setup_release_pipeline.md | 47 ++++++++++++++- 4 files changed, 119 insertions(+), 13 deletions(-) diff --git a/library/jobs/platform_engineer/AGENTS.md b/library/jobs/platform_engineer/AGENTS.md index 9fe7db60..b520752e 100644 --- a/library/jobs/platform_engineer/AGENTS.md +++ b/library/jobs/platform_engineer/AGENTS.md @@ -32,4 +32,6 @@ platform_engineer/ ## Learnings -(To be populated after workflow executions) +- `release_builder` should follow the repository's standard docs convention for the canonical release doc when one exists; otherwise use `docs/releases.md` or `docs/platform/releases.md`. Keep the root `AGENTS.md` concise by linking to that doc instead of duplicating release details. +- CI-provider-specific release behavior belongs in `.github/AGENTS.md` and/or `.forgejo/AGENTS.md`. Those files should explain workflow entrypoints, required secrets, and release-specific CI expectations, while the root `AGENTS.md` only points to them. +- `release_builder` must ask the user to define the release policy before wiring automation when cadence, version semantics, stabilization, backports, hotfixes, merge-back, publish targets, or stable-versus-unstable consumption are not already explicit in the repo. The job should implement the chosen policy, not infer one from tooling defaults. diff --git a/library/jobs/platform_engineer/job.yml b/library/jobs/platform_engineer/job.yml index 6cf4215c..99325a81 100644 --- a/library/jobs/platform_engineer/job.yml +++ b/library/jobs/platform_engineer/job.yml @@ -147,10 +147,26 @@ step_arguments: - name: release_configs description: "CI workflow files, release scripts, and branch protection configs" type: file_path + review: + strategy: matches_together + instructions: | + Read release_audit.md and release_docs.md to verify that: + - The release configuration files implement the documented decisions for versioning, changelog generation, release notes, and publish targets. + - The CI release pipeline includes build, test, tag, and publish stages per convention 27. + - Publishing uses CI secret references only and does not hardcode credentials. + - Root and provider-specific AGENTS guidance referenced in release_docs.md matches the created documentation files. - name: release_docs.md description: "Documentation of release process decisions and setup" type: file_path + review: + strategy: matches_together + instructions: | + Verify that: + - The canonical release process is documented at the repository's standard docs location for operational/release docs, or at `docs/releases.md` / `docs/platform/releases.md` when no stronger convention exists. + - Root `AGENTS.md` references the canonical release doc and points to `.github/AGENTS.md` and/or `.forgejo/AGENTS.md` when those directories are relevant. + - The documented branch strategy, publish targets, required CI secrets, and post-setup steps are complete and consistent with the created release configs. + - The document is sufficient for a human or non-DeepWork agent to understand how releases work in this repository. - name: infrastructure_audit.md description: "Infrastructure audit documenting setup, gaps, and convention compliance" @@ -202,6 +218,14 @@ step_arguments: - name: observability_configs description: "Monitoring configuration files (Helm values, nix modules, cloud configs, alert rules)" type: file_path + review: + strategy: matches_together + instructions: | + Read observability_plan.md to verify that: + - The created monitoring configs match the selected stack and implementation approach from the plan. + - Alert rules include runbook references per convention 9. + - Dashboard or monitoring coverage addresses golden signals per convention 7. + - The configs include evidence of validation readiness such as syntax-checkable structure, dry-run compatibility, or tool-specific validation expectations. - name: migration_description description: "What is being migrated (e.g., 'migrate from Zalando Postgres operator to CNPG')" @@ -223,6 +247,13 @@ step_arguments: - name: github_issue_url.md description: "URL of the created GitHub issue" type: file_path + review: + strategy: matches_together + instructions: | + Verify that: + - The file contains a valid issue URL or equivalent shared-surface issue reference. + - The created issue matches the workflow intent and links to or summarizes the migration, incident, or platform work clearly enough for collaborators to act on it. + - Any required checklist, deliverables, or validation-gate expectations referenced by the producing workflow are reflected in the issue body. - name: migration_report.md description: "Migration execution report with completed steps, validation results, and final state" @@ -837,8 +868,10 @@ workflows: 1. Read context.md for CI provider, package managers, build tools, repo structure. 2. Check for existing release infrastructure — CI release workflows, version files, changelog files, release branch patterns, tag conventions, GitHub Releases, release scripts, release tooling configuration (release-please, semantic-release, git-cliff, changesets, goreleaser). - 3. Assess against conventions 24-29 — SemVer compliance, release notes generation, release branch strategy, CI pipeline stages (build/test/tag/publish), automated artifact publishing, changelog from commits/PRs. - 4. Document findings with specific file paths, tool names, and configuration details. + 3. Identify which release-policy decisions are already explicit in the repository and which still require user judgment before automation can be configured. At minimum, assess cadence, version semantics, stabilization model, backport policy, hotfix policy, merge-back policy, publish targets, and stable-vs-unstable consumption guidance. + 4. Treat unresolved release-policy questions as audit gaps. The setup step must not invent those answers without asking the user. + 5. Assess against conventions 24-29 — SemVer compliance, release notes generation, release branch strategy, CI pipeline stages (build/test/tag/publish), automated artifact publishing, changelog from commits/PRs. + 6. Document findings with specific file paths, tool names, configuration details, and unresolved policy questions. inputs: context.md: {} outputs: @@ -850,7 +883,7 @@ workflows: ## Objective - Configure a complete release pipeline based on gaps identified in release_audit.md. All decisions requiring user judgment MUST be surfaced via AskUserQuestion. + Configure a complete release pipeline based on gaps identified in release_audit.md. All decisions requiring user judgment MUST be surfaced via AskUserQuestion. Release automation implements project policy, so this workflow MUST ask the user to define the release policy before it writes automation when that policy is not already explicit. ## Task @@ -859,13 +892,15 @@ workflows: ### Process 1. Read release_audit.md (gap analysis) and context.md (platform context). - 2. Set up versioning (convention 24) — choose version bumping tool based on stack, configure it. - 3. Set up changelog generation (convention 29) — choose tool based on stack and CI provider. - 4. Document release branch strategy (convention 26) — ask user for preferred model (trunk-based, release branches, GitFlow). - 5. Create CI release workflow (convention 27) — MUST include build, test, tag, publish stages. Ask user for publish targets. - 6. Configure automated artifact publishing (convention 28) — add publish steps with CI secret references (NEVER hardcode tokens). - 7. Configure release notes (convention 25) — release-please, git-cliff, or GitHub auto-generated notes. - 8. Document all decisions in release_docs.md. + 2. Confirm the release policy with the user before configuring automation whenever it is not already explicit in the repository. Ask about cadence, version semantics, stabilization model, backport policy, hotfix policy, merge-back policy, publish targets, and stable-vs-unstable consumption guidance. Ask only for unresolved items, but do not proceed while those items remain ambiguous. + 3. Set up versioning (convention 24) — choose version bumping tool based on stack, configure it. + 4. Set up changelog generation (convention 29) — choose tool based on stack and CI provider. + 5. Document release branch strategy (convention 26) — ask user for preferred model (trunk-based, release branches, GitFlow) when the confirmed release policy does not already answer it. + 6. Create CI release workflow (convention 27) — MUST include build, test, tag, publish stages. Ask user for publish targets when they are not already part of the confirmed release policy. + 7. Configure automated artifact publishing (convention 28) — add publish steps with CI secret references (NEVER hardcode tokens). + 8. Configure release notes (convention 25) — release-please, git-cliff, or GitHub auto-generated notes. + 9. Surface the release process for both humans and agents — canonical release doc following the repository's standard docs convention when one exists, concise root AGENTS.md reference, provider-specific `.github/AGENTS.md` or `.forgejo/AGENTS.md`. + 10. Document all decisions in release_docs.md, including the release policy that was confirmed before implementation. inputs: release_audit.md: {} context.md: {} @@ -873,10 +908,12 @@ workflows: release_configs: {} release_docs.md: {} process_requirements: + policy_confirmed_first: "The workflow MUST confirm the release policy with the user before configuring automation when cadence, version semantics, stabilization, backports, hotfixes, merge-back, publish targets, or stable-vs-unstable guidance are not already explicit." pipeline_complete: "CI release pipeline MUST include build, test, tag, and publish stages per convention 27." versioning_configured: "Semantic versioning MUST be set up with automated version bumping." release_notes: "Changelog/release notes generation MUST be configured per convention 29." branch_strategy_documented: "Release branch strategy MUST be documented in the repository." + agent_guidance_wired: "The repository MUST expose the release process through a canonical docs path that follows the repo's documentation convention when available, plus AGENTS.md references for root and relevant CI-provider directories." decisions_documented: "All setup decisions MUST be documented in release_docs.md." infrastructure_audit: diff --git a/library/jobs/platform_engineer/steps/audit_release.md b/library/jobs/platform_engineer/steps/audit_release.md index 2dde8158..9da798c8 100644 --- a/library/jobs/platform_engineer/steps/audit_release.md +++ b/library/jobs/platform_engineer/steps/audit_release.md @@ -94,6 +94,19 @@ Examine each category of release infrastructure. For each item, record whether i - `cargo-release` config in `Cargo.toml` or `.cargo/config.toml` - `.goreleaser.yml`, `.goreleaser.yaml` (goreleaser) +**Release policy clarity:** +- Check whether the repository already makes the release policy explicit in docs or automation. +- At minimum, look for explicit decisions about: + - release cadence + - version semantics + - stabilization model + - backport policy + - hotfix policy + - merge-back policy + - publish targets + - stable-vs-unstable consumption guidance +- If any of those remain unclear after auditing the repo, record them as policy gaps that the setup step MUST ask the user to resolve. + #### 3. Assess Against Release Management Conventions Evaluate each convention with a clear pass/fail/partial/not-applicable status: @@ -186,6 +199,16 @@ Write the audit to `.deepwork/artifacts/platform_engineer/release_builder/releas - **Branch protection**: - **Strategy documented**: yes / no — +### Release policy +- **Cadence documented**: yes / no — +- **Version semantics documented**: yes / no — +- **Stabilization model documented**: yes / no — +- **Backport policy documented**: yes / no — +- **Hotfix policy documented**: yes / no — +- **Merge-back policy documented**: yes / no — +- **Stable vs unstable guidance documented**: yes / no — +- **Open policy questions for user**: + ### Release Scripts - **Scripts found**: - **Makefile/Justfile targets**: @@ -232,6 +255,7 @@ strategy to adopt in setup_release_pipeline.> - **Current State Documented**: The existing release process (or lack thereof) is fully documented with specific file paths, tool names, and configuration details. No area is left as "did not check." - **Gaps Identified**: Missing components are identified by systematically checking against each of the six release management conventions (24-29). Each gap includes a concrete recommendation, not just "add this." - **Versioning Assessed**: The current versioning scheme is documented with the actual version value, tag history, and a clear assessment of SemVer compliance. The assessment includes a recommendation for the version bumping approach. +- **Policy Gaps Identified**: Missing release-policy decisions that require explicit user judgment are called out before automation work begins. - **Actionable for Next Step**: The audit contains enough detail that `setup_release_pipeline` can act on every gap without re-scanning the repository. File paths, tool names, and specific missing pieces are all documented. - **No Changes Made**: This step is read-only. No files in the repository are created or modified. Only the output artifact is written. diff --git a/library/jobs/platform_engineer/steps/setup_release_pipeline.md b/library/jobs/platform_engineer/steps/setup_release_pipeline.md index 97649828..59ce992e 100644 --- a/library/jobs/platform_engineer/steps/setup_release_pipeline.md +++ b/library/jobs/platform_engineer/steps/setup_release_pipeline.md @@ -2,7 +2,7 @@ ## Objective -Configure a complete release pipeline based on the gaps identified in `release_audit.md`. For each missing or incomplete piece of release infrastructure, create the appropriate configuration files, CI workflows, and documentation. All decisions that require user judgment (e.g., which registry to publish to, which branching model to follow) MUST be surfaced via `AskUserQuestion` before proceeding. +Configure a complete release pipeline based on the gaps identified in `release_audit.md`. For each missing or incomplete piece of release infrastructure, create the appropriate configuration files, CI workflows, and documentation. All decisions that require user judgment MUST be surfaced via `AskUserQuestion` before proceeding. Release automation implements project policy, so this workflow MUST ask the user to define the release policy before it writes automation when that policy is not already explicit. ## Task @@ -18,6 +18,24 @@ Read both input files: Identify the project's primary stack from context.md (e.g., Node/npm, Python/uv, Rust/cargo, Go, Nix) because this determines which versioning tools, changelog generators, and publishing targets are appropriate. +#### 1a. Confirm the release policy with the user + +Release automation encodes product policy. Do not silently invent that policy. + +Use `AskUserQuestion` to gather the missing decisions, grouping related questions when possible. At minimum, confirm: +- Release cadence: scheduled, milestone-driven, ad hoc, or another model +- Version semantics: what constitutes major, minor, and patch changes for this project +- Stabilization policy: whether releases stabilize on `main`, `release/*`, or another branch model, and how long stabilization stays open +- Backport policy: what kinds of changes may land on a release branch after the cut +- Hotfix policy: whether `hotfix/*` exists now or is deferred +- Merge-back policy: whether release or hotfix branches must merge back to the main development line +- Publish targets: GitHub Releases, Forgejo releases, registries, container images, Nix flake consumption, or other artifacts +- Consumer guidance: what users should treat as unstable versus stable (for example, `main` versus tags) + +If the user has already answered some of these in the conversation or the repo docs make them explicit, do not ask again. Ask only for the unresolved items. + +Do not proceed to workflow or branch-rule implementation until the unresolved policy questions are answered. If the environment does not provide `AskUserQuestion`, stop and tell the user which policy decisions are still required. + #### 2. Set Up Versioning (Convention 24) If the audit shows versioning is missing or not SemVer-compliant: @@ -103,8 +121,13 @@ For **GitFlow**: **In all cases:** - Write the branching strategy documentation to a discoverable location (e.g., `docs/releasing.md` or a section in `CONTRIBUTING.md`) +- Follow the repository's standard documentation convention for canonical operational docs when one exists +- If the repository does not already define a standard location for release/process docs, prefer a canonical release document at `docs/releases.md` or `docs/platform/releases.md` +- Update the root `AGENTS.md` to reference the canonical release document and point agents to provider-specific guidance in `.github/AGENTS.md` and/or `.forgejo/AGENTS.md` when those directories exist or are created - Document the strategy in `release_docs.md` +The documented branch strategy MUST match the release policy confirmed with the user in step 1a. If the user chose a milestone-driven or human-gated cadence, the workflow and branch docs must reflect that instead of implying continuous delivery defaults. + #### 5. Create CI Release Workflow (Convention 27) If the audit shows no CI release pipeline or the pipeline is missing stages: @@ -168,6 +191,7 @@ Use `AskUserQuestion` to determine publish targets: - Include all four stages (build, test, tag, publish) - Use CI provider secret management for registry credentials — NEVER hardcode tokens - Add comments in the workflow explaining each stage +- Create or update `.github/AGENTS.md` and/or `.forgejo/AGENTS.md` with CI-provider-specific release behavior, workflow entrypoints, required secrets, and links back to the canonical release doc - Document which secrets need to be configured in CI settings (e.g., `NPM_TOKEN`, `PYPI_TOKEN`) #### 6. Configure Automated Artifact Publishing (Convention 28) @@ -225,9 +249,11 @@ Create `release_docs.md` as a comprehensive record of all setup decisions. This The specific files created depend on the stack and CI provider. Common examples: - `.github/workflows/release.yml` — CI release workflow +- `.github/AGENTS.md` or `.forgejo/AGENTS.md` — CI-provider-specific agent guidance for release automation - `cliff.toml` or `.changeset/config.json` — Changelog tool config - `release-please-config.json` — Release automation config -- `docs/releasing.md` — Release branch strategy documentation +- `` or `docs/releases.md` / `docs/platform/releases.md` — Canonical release process and branch strategy documentation +- `AGENTS.md` — Root agent guidance linking to the canonical release doc and CI-provider AGENTS files ### release_docs.md @@ -241,6 +267,16 @@ Write to `.deepwork/artifacts/platform_engineer/release_builder/release_docs.md` ## Decisions Made +### Release policy +- **Cadence**: +- **Version semantics**: +- **Stabilization model**:
+- **Backport policy**: +- **Hotfix policy**: +- **Merge-back policy**: +- **Publish targets**: +- **Stable vs unstable guidance**: + ### Versioning - **Tool**: - **Rationale**: @@ -258,6 +294,11 @@ Write to `.deepwork/artifacts/platform_engineer/release_builder/release_docs.md` - **Branch naming**: - **Documentation**: +### Documentation Surfacing +- **Canonical release doc**: +- **Root agent entrypoint**: +- **CI provider agent docs**: + ### CI Release Pipeline - **Workflow file**: - **Trigger**: @@ -307,6 +348,8 @@ Write to `.deepwork/artifacts/platform_engineer/release_builder/release_docs.md` - **Versioning Configured**: Semantic versioning is set up with a concrete version bumping mechanism appropriate to the project's stack. The user knows exactly how to bump a version. - **Release Notes Configured**: Changelog or release notes generation is configured and integrated into the release workflow per convention 29. The tool parses commits or PRs automatically. - **Branch Strategy Documented**: The release branching strategy is documented in a discoverable location within the repository, not just in the artifact. +- **Policy Before Automation**: The release policy was confirmed with the user before automation was configured, and the resulting pipeline matches that policy rather than implicit defaults. +- **Agent Guidance Wired**: The root `AGENTS.md` references the canonical release doc, and CI-provider-specific release behavior is documented in `.github/AGENTS.md` and/or `.forgejo/AGENTS.md` when those directories are relevant. - **Decisions Documented**: All setup decisions (tool choices, publish targets, branching model) are recorded in `release_docs.md` with rationale. A new team member could understand the release process by reading this document. - **Secrets Not Exposed**: No secret values, tokens, or credentials appear in any created files. CI secrets are referenced by name only, with instructions for how to set them up. - **User Consulted**: Decisions requiring user judgment (registry targets, branching model, changelog approach) were surfaced via `AskUserQuestion` rather than assumed.