Skip to content

Commit 86680b0

Browse files
committed
Add section 16: the build plan
Signed-off-by: Nate W <natew@cncf.io> Assisted-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent 96f2fec commit 86680b0

1 file changed

Lines changed: 55 additions & 0 deletions

File tree

specs/ai-assisted-techdocs-assessment-spec.md

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -592,6 +592,61 @@ verification behind it was real (section 10).
592592
The block is defined by this spec and layered above the template body, so the
593593
methodology corpus and its templates are not modified (P-2, NG-4).
594594

595+
## 16. Build plan
596+
597+
The system is built the way it runs. Each component in section 13 starts as a
598+
tracking issue in cncf/techdocs, is drafted by the cloud agent where a file is
599+
the deliverable, and lands through a human-reviewed PR: the same
600+
issue-to-draft-to-review loop the assessments will use (section 5). Building the
601+
system with its own loop is the point: by the time the first project is
602+
assessed, every role has rehearsed and the platform's behavior has been observed
603+
rather than assumed. The earliest steps run before the instructions and
604+
environment components exist; the loop holds anyway, just with less scaffolding.
605+
606+
Preflight, before any build step: the administrator/platform owner works through
607+
the preconditions in section 11: cloud agent and MCP policies enabled for
608+
cncf/techdocs, MCP left at its read-only default, writer access confirmed, and
609+
the credit cap reviewed. These are organization and repository settings, not
610+
files, so this step is recorded in its tracking issue rather than a PR.
611+
612+
The build steps, in dependency order, each sized to one issue:
613+
614+
1. Labels (`.github/settings.yml`). Deliberately trivial first delegation: its
615+
real product is observed platform behavior: the agent's branch naming, what
616+
access review-comment revisions require, whether Actions runs on agent PRs
617+
wait for approval, and the token's effective scopes. Done when the labels
618+
exist and the observations are recorded against the section 17 checks.
619+
2. Repository instructions (`.github/copilot-instructions.md`). Ground rules for
620+
any agent work in this repository, carrying the section 8 discipline. Done
621+
when merged after review against sections 8 and 14.
622+
3. Intake template (`.github/ISSUE_TEMPLATE/assessment-request.yml`). Done when
623+
a dry-run request files cleanly, collecting the section 7 fields, the
624+
project's documentation domains for the firewall allowlist (section 11), and
625+
the up-front AI disclosure (HC-6).
626+
4. Environment setup (`.github/workflows/copilot-setup-steps.yml`). Done when an
627+
agent session's logs show the prepared environment.
628+
5. Data-collection scripts (`scripts/assessment/`). Done when running the
629+
committed command against a sample project twice yields the same committed
630+
outputs (HC-5).
631+
6. Provenance check (workflow plus `scripts/assessment/`). Done when a fixture
632+
PR with a malformed or unfilled block fails, a well-formed one passes, and
633+
the draft-versus-ready leniency behaves as section 15 specifies.
634+
7. Agent profiles (`.github/agents/`, one PR per profile). The three drafters,
635+
then the verifier (section 14). Done when each profile, run against a
636+
fixture, writes only its declared outputs with the provenance block present,
637+
and the verifier's report correctly flags a planted unsupported claim.
638+
8. Phase-advance workflow (`.github/workflows/assessment-phase.yml`). Done when
639+
a merged fixture PR opens the next phase's tracking issue, linked and
640+
unassigned (section 12).
641+
9. Approver-independence check (advisory; a build-plan candidate from section
642+
12). Comments when a phase's approver also drafted or reviewed it; never
643+
blocks. Done when it flags a staged violation, or explicitly deferred.
644+
645+
The build is complete when steps 1 through 8 are merged, the section 17
646+
build-time checks have recorded answers, and one end-to-end walkthrough of the
647+
section 5 lifecycle on a fixture project has run clean. Then the pilot is
648+
chosen, deliberately, per the caveat in section 10.
649+
595650
## 17. Open questions and future work
596651

597652
- Filing issues into project repos. A separate, opt-in tool to create the

0 commit comments

Comments
 (0)