Synced from Hive. This page is pulled from hivecommons/hive@v5 during the docs build. Edit the canonical source in the Hive repository.

CNCF TechDocs AI-assisted assessment — curated workflow model

cncf-techdocs-assessment@curated-2026.11.2 is the current version of the first curated model in the hub marketplace (https://hive.hivecommons.dev → Settings → Workflows → Marketplace on any hive); curated-2026.11.1 stays in the catalogue unchanged. It encodes the CNCF TechDocs team’s AI-assisted documentation assessment process so a hive bound to cncf/techdocs runs intake, drafting, verification, stakeholder review and approval as a visible lifecycle, with every agent action followed by a human gate.

Source of truth (the model cites both by SHA in its workflow.hivecommons.dev/source* annotations and in each element’s citations):

The model’s scope is github.com cncf/techdocs — the upstream repository where the process runs; the fork above is where the spec was written. Model files: pkg/hub/marketplace/curated/cncf-techdocs-assessment-2026.11.2.yaml (current) and pkg/hub/marketplace/curated/cncf-techdocs-assessment.yaml (curated-2026.11.1) (apiVersion: workflow.hivecommons.dev/v1alpha1, derivation.mode: rules, meta.provenance: curated). Curated files are never edited in place: a change is a new file with a new meta.version, and the catalogue keeps every version. The same repository is also in the ingest corpus (pkg/workflowmodel/ingest/corpus/extra.json), so an ingested-unreviewed version built from the pipeline files alone sits next to this one in the catalogue.

How the spec maps onto the model

The spec (§5 Lifecycle, §6 Phases, §12 Lifecycle bindings) describes one six-step loop — request → accept → draft → review → stakeholder review → merge — run once per phase (A analysis, B implementation plan, C issue backlog). The model encodes the loop once and carries the phase as a label (phase/assessment, phase/implementation, phase/backlog; skip-implementation makes the A merge open C). Each phase’s tracking issue and the intake issue itself travel the issue states; each AI-drafted deliverable is a pull request that travels the PR states.

Columns

ColumnStatesSpec
Requestedrequested§5 step 1, §12 Request
Acceptedaccepted, escalated§5 step 2, §12 Accept; §5 failure path
Draftingdraft-open (issue), drafting (PR)§5 step 3, §12 Draft
Reviewin-review, checks-failing§5 step 4, §12 Review
Stakeholdersstakeholder-review§5 step 5, §12 Stakeholder review
Approvalawaiting-merge§5 step 6, §12 Merge
Done (terminal)merged, closed, declined, discarded§12 Merge / Failure and abort

States and rules (first match wins)

Issues (intake and per-phase tracking issues):

StateStageRuleOwner
declinedterminalclosed and triage/declined—
closedterminalclosed—
escalated45 needs-decisiona hold label is presentadministrator
draft-open40 covered-by-PRtriage/accepted and a covering PR existsregistered agent
accepted20 claimedtriage/acceptedreviewer (technical writer)
requested10 actionableneeds-triagereviewer

The accepted state reuses the built-in stage number 20, so an accepted issue wears stage/020-claimed, but no agent holds a claim on it: the state means “waiting on the reviewer to start the drafter”. The in-progress sweep leaves that label alone on a model-bound repository and does not withhold the issue for it (hivecommons/hive#18434; before the fix the label was removed and re-added every enumeration cycle).

Pull requests (deliverables carry the Docs analysis label; anything else abstains):

StateStageRule
mergedterminalmerged
discardedterminalclosed unmerged
in-review50 review-pendingdraft and verified
drafting70 fixingdraft
checks-failing71 needs-authorchecks red
awaiting-merge90 ready-for-human-mergeconfirmed
stakeholder-review60 reviewedready and verified
in-review50 review-pendingready but not yet verified

Transitions

FromToEventGate (who)Spec
requestedacceptedaccepted/accept (reviewer)§12 Accept
requesteddeclineddeclined/decline (reviewer)§12 Accept
requestedclosedclosed—withdrawn
accepteddraft-opendraft-opened— (drafter opens the PR)§12 Draft
acceptedescalatedheld—§5 failure path
acceptedclosedclosed——
draft-openaccepteddraft-withdrawn—restart / hand-write / stop
draft-openescalatedheld—§5 failure path
draft-openclosedclosed—phase merged or aborted
escalatedacceptedreleased— (administrator)—
escalatedclosedclosed/abort (administrator)§12 Failure and abort
draftingin-reviewverified/verify (reviewer; needs verified)§12 Review
in-reviewstakeholder-reviewready/ready (reviewer; needs verified + green checks)§12 Stakeholder review
stakeholder-reviewawaiting-mergeconfirmed/confirm (stakeholder)§12 Stakeholder review
stakeholder-review / awaiting-mergechecks-failingchecks-red——
checks-failingstakeholder-reviewchecks-green——
awaiting-mergemergedmerged/approve (approver; needs confirmed + green)§5 step 6, §12 Merge
drafting / in-review / checks-failing / stakeholder-review / awaiting-mergediscardedclosed/discard (reviewer)—

Every gate is released by a human role; the two agent profiles (techdocs-drafter in accepted/drafting, techdocs-verifier in drafting) can only move work up to a gate, never through one — the compiler’s agent-no-human-gate refusal enforces this.

Roles

RoleSelectorSpec
requesterissue author (human)§4
reviewerrepository write permission (technical writer who /accepted)§4
approverrepository write permission§4
stakeholderset frozen at /accept from the intake’s validated contacts§4, §12
administratorrepository admin§4, §12 Failure and abort
drafter, verifierthe hive bot (non-human)§4, §6

Labels

From settings.yml: Docs analysis. Proposed for the assessment: needs-triage, triage/accepted, triage/declined, phase/assessment, phase/implementation, phase/backlog, verified, confirmed, skip-implementation.

Checks

Required CI: format-check, link-check, spell-check (the three cncf/techdocs workflows, ingested as pipelines with their source hashes). Required manual: provenance block present and the strict check passes (spec §15).

Intake

assessment-request.yml fields map to facts as recorded in the workflow.hivecommons.dev/intake-fields annotation: project name, maturity and moving-levels → assessment metadata; website/docs/repo/other-scope/out-of-scope → scope; domains → the agent’s egress allowlist; contacts → the frozen stakeholder set (validated at /accept); tooling/context → drafter input; the HC-6 disclosure acknowledgement is required.

Reference repos from the request

curated-2026.11.2 adds a spec.intake block (hivecommons/hive#18139):

intake:
  referenceRepoFields:
    - "Website or documentation repository"
    - "Other repositories or sites in scope"
  outOfScopeFields:
    - "Out of scope"

The entries are the rendered ### <label> headings of assessment-request.yml as they appear in a request issue’s body, not the form’s field ids. A hive bound to this version derives one write-tier (issues+prs) project.reference_repos entry per repository named under a referenceRepoFields heading and not under an outOfScopeFields heading, once a maintainer with write access to cncf/techdocs applies triage/accepted to the request. The derived entries carry the request as provenance (cncf/techdocs#395 style), are rebuilt on every config load and never written to the overlay or runtime config, and disappear when the issue closes or the label is removed. curated-2026.11.1 is unchanged and declares no intake fields, so a hive that stays bound to it derives nothing.

Operator walkthrough: the Hive Commons pilot

The first request through this path is cncf/techdocs#395, the Hive Commons assessment. What the operator of the TechDocs hive (authorized repo cncf/techdocs) does and sees:

  1. Rebind to 11.2. Settings → Workflows → Marketplace, bind cncf/techdocs to cncf-techdocs-assessment@curated-2026.11.2. This step is required: a hive still bound to curated-2026.11.1 derives nothing, however many requests are accepted. No reference_repos entry is written by hand.
  2. A maintainer accepts the request. Someone with write access to cncf/techdocs applies triage/accepted to #395. A label applied by a bot grants nothing.
  3. Three derived entries appear on the next pass (boot, config reload or every HIVE_REFERENCE_REPOS_DERIVE_INTERVAL, default 10m): hivecommons/docs, hivecommons/hivecommons.github.io and hivecommons/hive, each at the issues+prs tier with derived_from: cncf/techdocs#395. The kick’s 📚 REFERENCE REPOS block lists them with (from cncf/techdocs#395). Settings → Reference repos shows them read-only with the source link. The credential_state depends on where this hive’s GitHub App is installed:
    • App installed on the reference repos (the Hive Commons hive itself, whose App is on every hivecommons repo): credential_state: write-tier, and the hive may do what step 4 lists.
    • App installed only on cncf/techdocs (a contributor’s or the TechDocs team’s own hive): the entries read read-only with a reason, #395 carries one hive:reference-repos-read-only comment, and the hive keeps running. The App cannot be installed in an organization the hive does not own, so nothing in the hive turns this into write access on its own. The drafter can still clone and read the repos (public repos need no credential) and the deliverable still lands in cncf/techdocs, which is all Phase A needs. Step 4’s issue, PR and branch actions are not available there until the reference repos’ owner grants write access.
  4. What the hive may do there (write tier only). Clone and read the three repos, read their issues and PRs, open an issue, open a PR or push a topic branch, and comment on an issue or PR it opened itself. The assessment deliverable still lives in cncf/techdocs.
  5. What it may not do. Merge, push to a default branch, label or assign other people’s items, review, or close other people’s issues. The proxy refuses each of these and logs reference_repo in the violations log. hivecommons repos get no queue, no ACMM evaluation and no work items.
  6. Closing #395 removes them. When the request issue closes, or triage/accepted is removed, the three entries, their proxy policies and their kick lines are gone on the next pass. Nothing was ever written to the overlay or runtime config, so there is nothing to clean up. A hand-written entry for one of the repos, if the operator adds one, takes precedence and stays.

Starting the drafter (Accepted → Draft)

The hive hands the phase to its agents itself. The model grants techdocs-drafter the accepted and drafting states and techdocs-verifier the drafting state; the compiler resolves where each takes over (Agent dispatch):

StateProfileStarts when
Accepted (issue)techdocs-draftertriage/accepted is on the issue and no PR covers it
Drafting (draft PR)techdocs-verifiera person with write access comments /verify on the draft PR

On each pass the hive:

  1. withholds every item in those states from the generic lanes, so the scanner or a feature agent never picks up an accepted request before the drafter does;
  2. resolves the hive agent that fills the profile, in the order listed under Which agent fills a profile;
  3. for the issue, takes the agent claim on the hive’s claim ledger first; a claim someone else holds (a person working the phase by hand) stops the hand-off;
  4. kicks that agent once with the issue, the state’s guidance and the deliverable the model requires: a draft PR in cncf/techdocs labeled Docs analysis plus the issue’s phase label, named in the PR request (hive-open-pr --issues N) and referenced with Refs #N, not marked ready and without the verified / confirmed gate labels;
  5. records the hand-off in workflow-dispatch.json under the workflow store root when the kick lands, so neither a later pass nor a restart repeats it. A kick that could not be delivered (busy, paused, failed) is retried on a later pass.

The verifier runs once per /verify comment: each new /verify from the reviewer is a new pass, posting its report as a PR comment. A /hive verify command is the model-reply path instead: it applies verified directly, which is how a reviewer records a deliberate skip.

Which agent fills a profile

The first of these that names an enabled agent is the one kicked (a replica is never chosen: its base agent is):

  1. the pin, workflow.dispatch.profiles.<profile>.agent. A pin that names no enabled agent stops the hand-off; it never falls through to another agent;
  2. an agent named after the profile (techdocs-drafter);
  3. the first enabled writer, docs or feature agent, in that role order, by name;
  4. the hive’s standard agent for the work, so a default fleet needs no setup: for a profile that opens a pull request (techdocs-drafter) the issue worker, the scanner role that every issue without a lane of its own goes to; for a profile that reviews (techdocs-verifier) the reviewer. It must be allowed to work on the bound repository (its repos: scope, when it has one, includes cncf/techdocs).

No other agent is picked on its own: a supervisor, guide or brainstorm agent opens no pull requests. On a hive with the standard roster (scanner, reviewer, ci-maintainer, quality, guide, brainstorm, supervisor) the drafter is therefore the scanner and the verifier the reviewer.

When nothing fills a profile the hand-off cannot happen, and the item stays withheld from the generic lanes, so the hive says so in three places:

  • Settings → Repos: the repository’s workflow row lists each profile of the bound model with the agent it is handed to. A profile nothing fills shows a warning naming it, and the picker next to it saves the pin (owner only, PUT /api/workflows/dispatch/profiles, audited workflow_dispatch_agent). Automatic clears the pin. The next pass uses the pick; no restart is needed.
  • Activity Monitor: the item’s row wears a no agent for <profile> badge whose hover gives the reason.
  • Send to profile: the manual send answers with the same reason and where to fix it.

The hive log repeats it on each pass (workflow dispatch: item not handed off, with the profile and the reason).

To use the workflow, the hive needs workflow.enabled: true and cncf/techdocs bound to cncf-techdocs-assessment; dispatch is on by default (workflow.dispatch.enabled). Pin the agents, here or with the picker, if the default pick is wrong:

workflow:
  enabled: true
  dispatch:
    profiles:
      techdocs-drafter: {agent: writer}
      techdocs-verifier: {agent: reviewer}

workflow.dispatch.profiles.<profile>.disabled: true stops one profile’s automatic hand-off, and workflow.dispatch.enabled: false stops them all (owned items stay withheld from the generic lanes either way). prompt_template replaces the built-in prompt; see the design doc for its ${VAR} placeholders.

Send to drafter (owner)

On the Activity Monitor, the ⋯ menu of a cncf/techdocs row in a dispatched state offers Send to techdocs-drafter (an Accepted issue) or Send to techdocs-verifier (a draft PR in Drafting). It is owner-only and runs the same hand-off on demand: it reads the item fresh, resolves the agent (a profile set disabled for automatic dispatch still resolves), takes the claim, kicks the agent and records the hand-off (POST /api/workflows/dispatch, audited workflow_dispatch). Use it to restart after a discarded draft (a hand-off happens once per issue and state on its own: retries are a person’s choice, spec §5) or to run the verifier without a /verify comment.

Starting the drafter by hand (fallback)

When no agent fills the profile (pick one first: see Which agent fills a profile) or the hive predates automatic dispatch, a hive owner starts the draft by hand:

  1. Check the request is accepted: triage/accepted is on the issue, applied by a maintainer with write access to cncf/techdocs, and the hive’s workflow column shows Accepted.

  2. On the hive dashboard, signed in with the owner role (kicks with a prompt are owner-only), open the agent card of an agent that may work on cncf/techdocs and type the drafting instruction into its Send a message to … box, then Send. Name the issue, the phase and the deliverable, for example:

    Draft the Phase A (assessment) deliverable for cncf/techdocs#395 following the CNCF
    TechDocs assessment spec (§6 Phase A, §14 Assessment drafter, §15 provenance block).
    Read the request issue for the project, scope and contacts. Work on a topic branch in
    cncf/techdocs, open a DRAFT pull request labeled `Docs analysis` and `phase/assessment`,
    name the issue in the PR request (`hive-open-pr --issues 395`) and reference it in
    the body with `Refs #395` (not a closing keyword: the intake closes at the final
    phase). Do not mark it ready and do not apply `verified`.
  3. Once the draft PR is open and the PR request named the issue (a Refs line alone in the body does not cover it; a declared issue does), the next pass moves the issue to draft-open (stage 40) and the PR to drafting. From there every step is a human gate: the reviewer runs or skips the verifier (/verify, the verified label), marks the PR ready (/ready), stakeholders /confirm, and an independent approver merges.

Not representable today

These parts of the spec are documented in the model’s annotations but not enforced by the engine:

  • Close reason (completed vs. not planned) — no fact distinguishes them.
  • Approver independence from the drafter and reviewer — no fact records who drafted or reviewed.
  • Phase as a state dimension and the A→C skip — carried by labels; the open-next-phase-tracking-issue, notify-contacts and mention-stakeholders bookkeeping actions are declarative only.
  • Membership of the frozen stakeholder set — the gate exists, the check does not yet.
  • Data-collection scripts and the strict provenance check — a manual check.