Skip to main content

Module 7: Onboard Your Project

Modules 0–6 taught you to use ADW on projects that already have it wired up. This module is about wiring it up yourself, on a repo that doesn't have any of this yet. There are three separate pieces, and it's worth keeping them separate in your head because they get set up differently and fail differently:

  1. Ground the repo — give it a lat.md/ knowledge graph.
  2. Gate the repo — add the lat check CI gate so the graph can't silently rot.
  3. Register the repo — add it as a manifest so it feeds the company-wide knowledge atlas.
  4. Wire an ADW entry point — pick pipeline 9 (targetRepo) or the GitHub adw-issue-trigger.yml, depending on where the repo lives.

1. Ground the repo: lat.md​

Module 2 covered what lat.md/ is and how to write it. For onboarding, the mechanical steps are:

  • Create a lat.md/ directory with at least an architecture.md (or equivalent entry section) describing what the project does and why.
  • Every section needs a leading paragraph — this isn't optional style, lat check enforces it.
  • Use [[wiki links]] and // @lat: [[architecture#CI Gates]] code refs to tie documentation to the actual code, the same conventions from Module 2.

Your CLI likely has a scaffolding helper for this — check whether ops onboard project exists in your environment and run it against the new repo; it exists specifically to lay down the initial lat.md/ skeleton (and, depending on your CLI version, some of the other pieces below) so you aren't starting from a blank directory.

2. Gate the repo: the required lat check CI status​

Grounding only stays true if something enforces it. That's the hard gate in the reinforcement loop from Module 2: lat check running as a required CI status check. Concretely, that means:

  • A pipeline/workflow step that runs lat check on every PR.
  • That check configured as a required status in branch protection / build validation — not merely advisory.
  • The effect: a PR that renames or deletes a documented symbol, or breaks a [[link]] / @lat: reference, fails CI and cannot merge until fixed.

This check is deliberately offline and deterministic — it validates links and refs against files that exist in the repo, with no LAT_LLM_KEY and no network call required. That's what makes it safe to make required: it can't flake because a semantic-search API key expired.

Look for CI template scaffolding for this (for example under something like templates/ci/ in the orchestration repo) rather than hand-rolling the step — reusing the template keeps the gate consistent with every other repo's, which matters once the atlas starts aggregating across repos.

The third gate: shift-left

Module 2 mentioned a third gate — a pre-commit lat-check hook that runs against the committed-to-be state, catching a broken ref before it's even pushed. Wiring the CI gate is required for onboarding; wiring the pre-commit hook too is strongly recommended, since it gives contributors the same feedback minutes earlier.

3. Register the repo: feeding the atlas​

A repo's lat.md/ graph is only useful company-wide once it's part of the company knowledge atlas — the wg-lat-atlas repo, which aggregates every repo's graph via CONTAINS and CROSS_REPO edges and validates the combined, portfolio-wide graph with ops ontology check --scope=atlas.

A repo "feeds the atlas" once both are true:

  • (a) it has a valid lat.md/ committed (from step 1, enforced by step 2), and
  • (b) it is registered as a manifest in wg-orchestration.

The manifest registration is what tells the atlas aggregator this repo exists and should be pulled in — without it, a perfectly valid lat.md/ just sits in its own repo, invisible to portfolio-wide search and cross-repo links.

4. Wire your own ADW entry point​

This is where Module 6's two models become a decision you actually make, once, per repo:

  • Repo lives in Azure DevOps → Model 1. Before you can dispatch to it via pipeline 9's targetRepo parameter, the ADW-Agents container identity needs a one-time grant of Contribute + Create-PR on this specific repo. Ask whoever administers ADO permissions for your org to add this grant — it will not work without it, and the failure mode (a clone or PR step failing partway through) is confusing if you don't know to check this first.
  • Repo lives on GitHub → Model 2. Add .github/workflows/adw-issue-trigger.yml (copy it from a repo that already has it, e.g. the Mars work-order system, rather than writing it from scratch), then configure two things in the repo settings:
    • A repository secret named ANTHROPIC_API_KEY.
    • An adw label, so there's something to attach to an issue to trigger the workflow.

Wastey says

If you only remember one thing from this module: grounding (lat.md) and gating (CI check) are the same for every repo regardless of host. The ADW entry point is the one step that forks based on where the repo actually lives.

Hands-on lab: produce an onboarding bill of materials​

Pick a sample repo — a real one you want to onboard, or a throwaway sandbox repo if you'd rather practice first. Without necessarily executing every step live, produce a written bill of materials covering:

  1. Grounding: Does the repo have a lat.md/? If not, what would the initial skeleton contain (list the sections you'd start with)? Note whether ops onboard project is available to scaffold it.
  2. Gating: Is there a CI/pipeline definition in the repo already? Where would the lat check step go, and is there a CI template you can reuse instead of writing it by hand?
  3. Registration: Is this repo currently registered as a manifest in wg-orchestration? If not, what information would the registration need (repo name, host, owner)?
  4. Entry point: Is this repo on ADO or GitHub? Based on that, list the exact one-time setup items from section 4 above that apply to it (e.g. "GitHub → needs ANTHROPIC_API_KEY secret + adw label + the workflow file" or "ADO → needs Contribute + Create-PR grant on this repo for the ADW-Agents identity").

Write this up as a short checklist document — this is exactly the kind of artifact you'd hand to a teammate (or your future self) before actually running the onboarding.

Practice: order the onboarding steps​

Put these onboarding steps in the right order:Put in order
1Gate the repo with lat check as a required CI status
2Ground the repo with a lat.md/ knowledge graph
3Register the repo as a manifest so it feeds the atlas
4Wire an ADW entry point (pipeline 9 targetRepo, or GitHub adw-issue-trigger.yml)

Decide: which entry point does your repo need?​

Choose your pathADO vs GitHub entry point

Where does the repo live?

Knowledge check​

What two things must be true for a repo's lat.md to "feed the atlas"?
Why is it safe to make `lat check` a REQUIRED CI status check?
A repo lives on GitHub and you're wiring its ADW entry point. What do you need to configure?