How to Run a Team on GitHub

A practical playbook for business teams working alongside AI agents

About this guide

This guide explains how a small team can use GitHub as its shared "operating system": the one place where work is planned, assigned, done, reviewed and remembered. It is written for business teams (sales, marketing, operations, training, leadership), not for software engineers. You do not need to write code to use anything described here.

Before you start. This guide assumes the basics of working on GitHub with Claude Code: branches, changes, review and merge. Our AI Builder course teaches those basics, so we don't explain them here. We can also customise the course so your team learns the pro setup this guide describes.

Everything in this guide comes from how our own team works every day. We are three AI-native founders, two non-technical and one technical, and we work with AI agents that draft documents, update plans, write code and make changes for us. Where we recommend something that we do not yet do consistently ourselves, we say so clearly with this marker:

Suggested improvement: a recommendation that goes beyond our current practice.

Anything without that marker is something our team already does.

1. Why GitHub, even for non-engineers

Most teams already have tasks spread across chat threads, email, a spreadsheet and someone's head. That works until it doesn't: a task gets forgotten, two people do the same thing, or nobody remembers why a decision was made.

We use GitHub for business work for four reasons.

1. Everything has an owner and a history. Every issue shows who owns it, when it was opened, what was discussed and when it was closed. Every document change shows who changed what and why.
2. Review is built in. Nothing becomes "official" until someone looks at it. This is the same safety net engineers use for code, applied to plans, proposals, playbooks and content.
3. AI agents work natively here. Agents such as Claude Code can read a repo, follow written instructions, draft changes and open a pull request for a human to approve. GitHub gives agents a safe place to work: they propose, people decide.
4. It scales from three people to thirty. The same habits (issues, owners, reviews, a weekly summary) work for a small team and keep working as you grow.

One idea runs through the whole guide: the source of truth, the single place you agree to trust when two places disagree. For us, GitHub (the project map plus the issues) is the source of truth. Spreadsheets, chat messages and dashboards are views of it, never the other way round. We run the company on GitHub Enterprise and use no separate tracking tool: the project dashboards we check are live pages generated from the repositories and published with GitHub Pages (Section 5).

You do not have to move everything at once. Section 13 gives a 30-day plan for getting started.

2. How to lay out your repositories

What we do

We keep one planning repository for the whole team and separate repositories for each product or body of work.

• The planning repo (we call it the PM repo). This is the team's control room. It holds the mental model, our project map (Section 4), the cross-team issues, the weekly reports (Section 12) and a short lessons-learned file. It contains no product files, only the plan and its history.
• Work repos. One per product, service line, website or content collection. For example: a repo for your sales and client work, one for your training content, one for your website, one for shared brand assets. The real work (documents, decks, code) lives in its "home" repo.

The rule that holds this together: work is filed where it will be done, and the planning repo only points to it. If a website change will happen in the website repo, the issue lives there, and the project map links to it (for example website#35). This avoids duplicate tickets in two places.

Folder conventions that work for business teams

Inside a work repo, a predictable folder structure matters more than a perfect one. Section 11 shows the folder we keep for every prospect and client.

A few habits make this reliable:

• Keep a _template folder so every new company, project or cohort starts with the same files.
• Separate stages physically. We keep prospects in pipeline/ and signed customers in clients/. A small automated check (a GitHub Action) comments on any PR that adds a customer folder without the company being on the signed list. This stops mistakes before they are merged.
• One fact, one home. Each important fact (pricing, the list of active customers, the stage of each deal) lives in exactly one file. Other documents refer to it rather than copying it. When copies exist, they drift, and a stale copy is worse than none.
• Keep an _archive/ folder rather than deleting old material.

3. Issues: the unit of work

What we do

Every piece of work that takes more than a few minutes becomes an issue. We follow the rule "issue first": before anyone (human or AI) starts work, or before the plan is updated, the issue exists. This way the plan always points to something real.

A good issue in our team has five parts:

1. A clear title that starts with the area and says the outcome: "Website: publish the case-study page", not "website stuff".
2. Goal and context: why this matters, who asked for it and when. We write down who named the task and the date ("Named by Maria, 2026-09-23"), so the reason for the work is never lost.
3. Done when: a short numbered list of checks that make the work unambiguously finished. This is the most important part. "Done when the page is live and its public link is recorded on this issue" is testable. "Improve the page" is not.
4. Owner and priority: exactly one named owner and a priority from P0 to P3 (see Section 6).
5. Related links: parent or sibling issues ("Related: #174, #175"), the documents involved, and the part of the project map that claims this work.

For bigger pieces of work, we create a parent issue that describes the whole outcome, and child issues for each concrete step. For example, a parent issue "Create visual case studies" with children "Embed visuals in client decks" and "Embed visuals on the website".

For repeating work, such as weekly outreach quotas, we keep one parent issue that describes the standing process and open a small "this week" issue for each week's execution. That keeps both the routine and the actual results visible.

Every task has a named owner. An issue with no owner is treated as a gap to fix, not as a normal state. Our project dashboard deliberately shows unowned work in its own loud column so it cannot hide.

When a question needs a decision rather than work, we open it as a discussion topic issue (label type:topic), tag the person it needs to be discussed with, and close it with a comment that starts with "Decision:". That comment becomes the permanent record of what was decided and why.

Suggested improvement: Our planning repo does not yet have a built-in issue template, so the structure above is applied by habit and by our AI agents' instructions. Add an issue template (see Appendix A) so GitHub pre-fills the structure for everyone. One of our product repos already does this, including a short "Definition of Ready" checklist (not a duplicate, one reviewable unit, priority assigned), and it clearly reduces duplicate and half-finished tickets.

4. The mental model

The mental model is something Giuseppe came up with. The idea is simple. You write your own short list of priorities for a project, in plain language, in one file. Each priority is a key item: what matters, how urgent it is (P0 to P3), who owns it and what done means. Then GitHub and the agents do the mapping. They find every open issue that belongs to each key item, and they flag the work that is untracked: open issues not linked to any priority, priorities with no issue behind them, unassigned tasks and stale items.

People set the priorities from the top down. Agents keep the bottom-up reality, the issues and pull requests, reconciled against them.

Why it works for non-technical founders

• You think in priorities, not tickets. Nobody has to read 150 issues to know where the company stands. You write a handful of key items in your own words, and the file stays short enough to read in two minutes.
• The map stays honest because agents check it. A plan written once and never checked is out of date within a week. Here an agent compares the file with GitHub every night and reports what is missing, unowned or stuck (Section 5). The founder decides what to do about it.
• Changing your mind is cheap. Moving a key item from P1 to P0, or giving it a new owner, is a one-line edit in a small PR. The agents pick it up on their next run.

What we do

We keep the mental model in one markdown file, mental-model.md, at the top of the planning repo, and our product repo has one of its own. In this guide we also call it the map.

The map has two levels:

• Main topics (level-2 headings) are the key items: for example "P0 · Launch the new program" or "P1 · Website refresh". Each has a priority, a default owner and a one- or two-sentence Done definition describing the observable end state.
• Subtopics (level-3 headings) are the concrete units of work under each main topic. Each subtopic has a Done definition and a list of the issues that cover it.

A subtopic looks like this:

### Publish the customer case-study page
<!-- refs: #125 website#35 -->
**Owner:** Maria
**Priority:** P1
**Status:** Ready
**Due:** 2026-10-15
**Done:** the case-study page is live on the website, its URL is recorded
on #125, and the customer has approved what is shown.

The rules that make the map trustworthy:

• The map holds the priorities, not the tasks. It shows how the work fits together. The issues hold the detail.
• When the map and GitHub disagree, fix the issue first, then update the map. Never the other way round, and never from memory: every issue number in the map must come from a real lookup.
• Issues attach only to subtopics. If you want to hang an issue directly on a main topic, it means a subtopic is missing.
• The first linked issue is the next action. Order matters.
• "none" is an honest answer. A subtopic with refs: none has no issue behind it yet, and that gap should be visible, not hidden.
• Closed issues stay, marked as closed (for example #139(closed)), so the map keeps its evidence. A closed issue only counts as done if the Done bar was really met.
• Status values are simple: Backlog (agreed, not started), Ready (next up), Ongoing (actively worked), Blocked (waiting on a decision or someone else), Review (waiting for eyes), Done.
• Separate what was said from what was inferred. When an agent or a teammate fills in a priority or an owner that nobody actually stated, the map says so explicitly, so it is not mistaken for a decision.
• The map only changes through a pull request. No one edits it directly on main, and dashboards only read it.

The everyday flow is: a new piece of work comes up, an issue is opened, then a small PR adds or updates the matching subtopic in the map. Most of our map PRs are titled simply "Map #193: set up outreach campaign" and change nothing but that one entry. Many of them are drafted by an AI agent.

The mental model only says what should be true. Section 5 describes the tracker: how agents check it against GitHub every night.

5. The automatic project tracker

What we do

The tracker is the agents' half of the mental model (Section 4). We decide what matters, and agents do the checking. The key items are defined in the map: each main topic has a priority from P0 to P3, one owner and a definition of done. Nobody updates a status list by hand. Agents read the map, fetch the live state of every repository it points to, and report where each key item stands.

For each key item, the tracker answers five questions:

1. What is still open? The open issues linked to it, with the first one shown as the next action.
2. Is every task owned? An unassigned issue under a key item is flagged. In our product repo, a nightly job assigns it to the key item's owner. It never overrides an assignment a person made.
3. What work has no key item? Open issues that no subtopic links to. Either the map is missing something, or the work is not worth doing.
4. What is stale? Items with no movement for a while, milestones past their date with open issues, and subtopics whose issues are all closed while the definition of done is still unmet.
5. Is a key item finished? When every linked issue is closed, an agent audits the result against the definition of done before the item comes off the map.

Three pieces do this for us:

• The /check skill, run on demand in the planning repo. It parses the map with the same parser the dashboard uses, fetches the issues from every repository the map mentions, and reports in four blocks: PARSE (problems reading the map), CONFIRMED, DRIFT (map and issues disagree) and GAPS (work with no issue, or issues with no place in the map). It proposes the issues to file and the map entries to add, and creates nothing without a person's go-ahead.
• A live dashboard page. This is the tracker we look at, and it lives on GitHub, not in a separate tool. A GitHub Action rebuilds the page from the map and the live issues every night and whenever the map changes, and publishes it with GitHub Pages, visible only inside our GitHub Enterprise organisation. The product we run for a lighting distributor has a go-live dashboard built the same way from its own repository. It shows each key item with its progress, its next open issue, its open PRs and what changed since yesterday: completed, advanced, stalled or shipped. Unlinked issues get their own table. It refuses to publish if it could not read all the data, because a page with quiet holes in it looks authoritative while being wrong.
• A nightly triage agent that proposes, through a PR, which unlinked issues belong under which key item. It links only the clear cases and lists the rest with a reason. In one run on our product repo, 16 of 19 open issues were linked to no key item. The agent linked two and pointed out that most of the others formed one initiative the map did not have yet. Adding a key item is a founder's decision, so it stopped there.

This is the format we use, shown with invented names and numbers.

Example format: a key item in the map

## P1 · Launch the partner program
**Owner:** Maria
**Done:** ten partners signed, and each has run one joint webinar.

### Partner onboarding kit
<!-- refs: #212 website#41 #198(closed) -->
**Status:** Ongoing
**Due:** 2026-10-31
**Done:** the kit is published and three partners have used it.

Example format: the nightly tracker output

TRACKER  2026-09-23 (nightly run)

P0 · Close the Q4 pilots             owner: Sam     2 of 3 subtopics done
   Pilot kickoff calls                next: #207    assigned: Sam
   Starter guide for users            refs: none    GAP: no issue yet
P1 · Launch the partner program      owner: Maria   0 of 2 subtopics done
   Partner onboarding kit             next: #212    assigned tonight: Maria
   Partner webinar series             STALE: #219, no activity for 16 days

NOT LINKED TO ANY KEY ITEM: 5 of 14 open issues
   #230 Update the pricing page       suggested: P2 · Website refresh
   #233 Try a new CRM field           no clear fit, needs a decision

DRIFT
   Website refresh > Case studies: all refs closed, Done not met.
   Proposed issue: "Publish the second case study" (website repo)

Suggested improvement: You do not need a custom dashboard on day one. Start with the map, the /check skill run once a week, and GitHub's built-in filters (for example, open issues with no assignee). Add the nightly run and the dashboard once the map has settled.

6. Labels and priorities

What we do

We keep labels few and meaningful. Our working set has four families:

Our priority scale:

• P0: blocking. Nothing else matters until this moves.
• P1: important. Improve as soon as possible, but not blocking.
• P2: later. Tracked so it isn't lost.
• P3: meta and trackers. Housekeeping, claimed so the "unowned" list stays meaningful.

A subtopic inherits its main topic's priority and can override it, for example when one piece of a P2 area is genuinely urgent.

Suggested improvement: Create all four priority labels (priority:P0 to priority:P3) in every repo, not only P0 and P1, and add a status:blocked label. Use the same label names across all repos so filters and digests work everywhere. Remove GitHub's default labels you never use; fewer labels get used more consistently.

7. Pull requests and review rules

What we do

• Nobody works directly on main. Every change, whether made by a person or an AI agent, happens on a branch and arrives as a pull request. This rule is written into the instruction file of every one of our repos.
• One PR, one reviewable change. If the description needs to cover two unrelated things, split it. Small PRs get reviewed quickly and properly.
• Link the PR to its issue. Our product repos end every PR with an "Issues closed" section that says Closes #133. When the PR is merged, GitHub closes the issue automatically. Across our organization, several hundred merged PRs use this pattern.
• The PR description explains the change for a reviewer. Our PRs use a consistent structure: What this does (one or two sentences), Changes, Verification / Test plan (what was checked, with ticked boxes), and Risk (low, medium or high, and why). Map PRs also state what did not change ("No issues were created or edited. Only the map changed.").
• Anything customer-facing goes through staging first. For our learning platform, changes go into a staging branch, are checked on a preview site, and only move to the live site on the product owner's explicit approval. Merging to the live version is a human decision every time, not a formality.
• Name branches so you know where they came from, for example maria/website-case-study or mac/fix-timezone.
• Notifications on important changes. A small GitHub Action posts to the team chat whenever the main branch of our commercial repo changes, so nothing lands silently.

Who merges

Today, for low-risk planning changes (such as adding one entry to the project map), the person who asked for the change usually reviews the agent's PR and merges it themselves, often within a minute. For product and customer-facing work, a named owner approves.

Suggested improvement: Adopt a simple written merge rule, and turn on GitHub's "branch protection" for main so it is enforced rather than remembered:

• Planning and notes PRs: the requester may self-merge after reading the full change.
• Anything customer-facing, anything touching money, contracts or customer data, and any change to agent instructions: a second person must approve.
• Duplicates: close duplicate PRs immediately with a one-line comment pointing to the one you kept. (We occasionally see an agent open the same PR twice; an open duplicate confuses everyone later.)

8. Working with AI agents in the repo

This is where GitHub pays for itself. An AI agent is only as good as the instructions and guard rails around it, and a repo is the natural place to keep both.

The instructions file

What we do

Every repo has an instructions file at its top level, which agents read automatically at the start of every session. Claude Code reads CLAUDE.md; many other tools read AGENTS.md. (You can keep one and have the other point to it.) Folders can have their own instructions file for more specific rules, for example a separate one for the sales folder.

Our instruction files contain:

• What this repo is and who it is for, in a few sentences.
• Where things live: the folder structure and which file is the single source of truth for each important fact.
• Vocabulary: words that are easy to confuse, defined once. (In our training platform, "course", "session" and "lesson" mean specific things; the file includes a small table.)
• Hard rules, stated as "never" and "always": never commit to main; never delete data rows without explicit approval; never deploy without showing the change first and getting a "yes"; when a fact can't be verified, write "Unknown, verify directly" instead of guessing.
• The standard processes, step by step (for example, onboarding a new customer onto the platform).
• The reason behind each rule, often with the date of the incident that caused it. Agents follow rules better when they understand why, and so do new teammates.

We keep the file short and put detailed how-to steps in separate "skills" (reusable, named instruction sets such as /check, /new-cohort, /meeting-prep, /weekly-digest) that the agent loads only when needed. But any rule that says "never", or that could trigger a real send, payment or deletion, stays in the main instructions file, because a prohibition that lives in an optional file might not be loaded the one time it matters.

How agents work day to day

• Agents open PRs; humans review and merge. An agent, usually Claude Code (on a laptop or running in the background; Cursor's cloud agents are an alternative), takes an issue, works on a branch and opens a PR with a clear description. A person reads it and decides.
• Agents draft outward-facing actions; humans send them. Emails, social posts, proposals and anything a customer will see are drafted by the agent and approved by a person before they go out.
• Agents update the plan, too. When a teammate names a new task in a meeting or a chat, an agent opens the issue, then opens a small PR adding it to the project map. The teammate reviews and merges.
• One agent session, one working copy. When several agent sessions work on the same repo at the same time, each gets its own worktree so they do not trip over each other's branches.
• Automations must check where they are running. Our weekly-digest script refuses to commit, push or send anything unless it is running from the main branch. We added this after an automation accidentally pushed unreviewed work to main.
• A failure must look like a failure. If an automated summary cannot be generated, the job stops and says why. It never fills the gap with placeholder text that looks like real content.

Keep a lessons file

What we do

The planning repo has a tasks/lessons.md file. Each time something goes wrong, we write a short entry: what happened, why it matters, and how we changed the process or the automation so it cannot happen the same way again. Agents read it, and so do people. The most useful lesson we have recorded is simple: when the same incident happens twice, the first fix was wrong; change the design, not the discipline.

9. Running software for a customer with agents

Some of our work is software that a customer's staff use every day. One example is a product we run for a lighting distributor. It reads incoming requests for quotes, matches them to the catalogue and prepares the quote in the customer's ERP. Agents write almost all of its code, and our technical founder is responsible for it. The habits in the earlier sections still apply. This section covers what we add when real users depend on the result.

What we do

• Customer feedback becomes GitHub issues automatically. Every screen has a "Report an issue" button. The report stores the page, the user and an optional screenshot. Once a day a triage agent reviews the new reports against the live system with read-only access. For each one it decides: file a GitHub issue, not a bug, or not enough evidence. It files at most five issues per run and writes down what it checked. When a report is unclear, it goes back to a person with a specific question, usually a request for a screenshot. From there the report follows the normal GitHub path:
  1. The nightly triage (Section 5) labels the new issue and links it to a key item in the mental model.
  2. The fix is a PR. It merges only when the automated tests pass and it adds a "what's new" entry, or a written reason for skipping one (see the bullets below).
  3. Merging to main deploys the fix.
  4. When the issue closes, the customer's report is marked resolved.
• Every issue meets a Definition of Ready. The issue template asks whether it is a duplicate, whether it is one reviewable piece of work, what priority it has (P0 blocks core use, P3 means a workaround exists), what and why, and the acceptance criteria. Our non-technical founders write issues the same way.
• Every PR meets a Definition of Done. The PR template has checkboxes for tests, evidence that matching quality did not drop, user-facing changes, data and integrations, and deploy steps. It ends with Closes #N.
• Agent autonomy has tiers. For small, reversible changes, the agent builds and the change merges once the checks pass. For changes users will see, the agent first shows a preview with written acceptance criteria. For logins, database migrations, writes to the customer's ERP and changes to AI prompts, there is a written design and an explicit approval before any code is written.
• Merging means deploying, so the checks come first. Automated tests run on every PR, and the deploy job waits for them. After each deploy, a script logs in to the live product and checks the main pages. If that fails, the deploy fails. A daily job checks the security certificate and opens a top-priority issue well before it expires. We added it after a certificate expired.
• Release notes live in the product. A "what's new" page lists new features in the four languages the users speak. An automated check fails any PR that changes a screen users see, unless it adds an entry or gives a written reason why not. Entries for features that are not live yet stay on hold, and the check flags any hold older than 90 days.
• Rules come from incidents. The test configuration and the agent instructions record the incident behind each rule, with its issue number. When the same problem happens twice, it becomes an automated check instead of a reminder.

Suggested improvement: Things we are changing in our own setup, and would set up with you from the start:

• A second look only where the risk is. When one technical person opens and merges almost every PR, nobody else sees the risky changes before they go live. List the risky paths (migrations, ERP writes, prompts, login, deploy scripts and workflows) in a CODEOWNERS file and require one approval from someone other than the author on those paths only. With one technical founder, that approval can come from a non-technical founder who reads the plain-language summary and checks the preview, backed by an independent agent review of the code. Everything else merges on green checks.
• A preview before live. A staging copy of the product, refreshed on every PR or at least every day, where non-technical founders can click through a change before it merges.
• Bots under their own name. An automation that opens PRs with a founder's personal token makes the history say that founder did the work. Give each automation its own GitHub App or machine account.
• Alerts for errors between deploys. The login check only runs at deploy time. Route new production errors to the team chat so they are seen the same day.
• Archive the side repos. Early prototype and research repos collect issues nobody reads. Move anything still relevant into the main repo, then archive the rest.

10. An optional spreadsheet mirror for non-technical teammates

What we do

The live dashboard (Section 5) is where we check projects. Some teammates still prefer a spreadsheet, so we keep an optional Google Sheet mirror of the plan ("PM Tasks"): one row per task, with columns for topic, task, owner, priority, status, due date and a link to the issue.

The rules are strict and simple:

1. GitHub is the source of truth. The Sheet is a convenient view of the project map and issues, never an independent plan.
2. After any change on GitHub, the Sheet is refreshed from the map and issues. In practice our AI agent does this at the end of the same working session: issue first, then the map PR, then the Sheet refresh.
3. Teammates may edit the Sheet directly: add a row, change an owner or priority, mark something done.
4. "Sync" is the trigger word. When someone edits the Sheet and says "sync" (in chat, to the agent), the agent reads the Sheet, opens or updates the matching GitHub issues, updates the project map through a PR, and then refreshes the Sheet so everyone sees the reconciled version. New issues created this way say so in their notes ("Added from PM Tasks Sheet, 2026-09-07").
5. If the Sheet and GitHub disagree and nobody said "sync", GitHub wins.

This gives non-technical teammates a familiar tool without splitting the truth into two places.

Suggested improvement: Add a "Last synced" timestamp cell at the top of the Sheet, and protect the columns that should only come from GitHub (issue number, link). Then nobody wonders whether they are looking at stale data, and nobody accidentally breaks a link.

11. Business information lives in GitHub, not only code

What we do

Most of what we keep in GitHub is not code. It is the commercial memory of the company: who we talk to, what they said, what we proposed and what we decided. An agent can only draft a good proposal or follow-up if it can read that history, so the history lives next to the work.

This is the shape of our sales repository, with invented company names:

sales/
├── docs/
│   ├── icp.md                    ideal customer profile, product line A
│   ├── icp-training.md           ideal customer profile, product line B
│   └── pricing.md                the only file that states prices
├── pipeline/
│   ├── pipeline.json             the stage of every company, in one place
│   ├── _template/                copy this to start a new company
│   ├── acme-distribution/
│   │   ├── status.md             stage, last contact, next action
│   │   ├── call-notes.md         dated notes, newest first
│   │   ├── discovery-questions.md
│   │   ├── 2026-09-11_call.txt   raw call transcript
│   │   └── proposals/            drafts and sent versions
│   └── northwind-tools/
├── clients/
│   └── globex-industrial/        same files, signed customers only
└── tasks/todo.md

• Right after a call, the record goes in. The transcript is saved into the company's folder. An agent updates call-notes.md with the date, the people, what was said and the next steps, and updates status.md with the stage and next action. The change arrives as a PR with a dated title, for example "Add discovery call notes and transcript (2026-09-11)".
• The CRM gets the same notes the same day. Our rule is repo first, CRM as well. The repo keeps the full history next to the proposals; the CRM keeps the relationship view that sales uses day to day.
• The ideal customer profile is a document. We keep two ICP files, one per product line, because the buyer and the pain are different. A lead can fail one and be a strong fit for the other. Agents use these files to score new leads, so the scoring follows what we wrote down rather than what someone remembers.
• One fact, one home. Prices live in one file, the stage of every company in another, and each client's current status in its own call-notes.md. Other documents point to these files instead of copying them. When one of them changes, the agent lists the documents that may now be out of date.
• Decisions are recorded on issues. A question that needs a decision becomes an issue with the label type:topic and a person: label for whoever it needs. We close it with a comment that starts with "Decision:", so the answer and the reason are on record and linked from the work they affect. Chat is for talking; the repo is for remembering.
• Internal and external material are kept visibly apart. Files meant only for the team are marked as internal, and an automated check blocks publishing any file that contains internal markers under an external-looking name.

Suggested improvement: Two things we are still fixing ourselves. First, we paste transcripts from our meeting recorder by hand; connect the recorder so the transcript lands in the right folder without anyone doing it. Second, use a fixed file-name pattern for every meeting record, YYYY-MM-DD-<topic>.md, with a five-line header: date, attendees, decisions, action items (each with an owner and an issue number) and a link to the transcript. Action items without an issue number tend to be forgotten.

12. The weekly report, built automatically

What we do

Nobody on our team writes the weekly report. A scheduled job builds it every Monday morning from what actually happened on GitHub that week. A shorter daily version runs every morning.

How it is built:

1. Collect. The script lists every repository in our GitHub organisation and pulls the week's commits and merged PRs from each one, with the author and the PR number.
2. Group. Each repository carries a GitHub topic such as area-commercial or area-technology, which maps it to a business area. A repository without a topic is placed by inference and marked "untagged", so the guess is visible.
3. Summarise. A language model writes one TL;DR line per area (about 20 words at most) and a Details section per area. It follows a written rules file.
4. Count. Contributions per person, and which repositories were active or quiet that week.
5. Publish and archive. The report is posted to our team chat and committed to the planning repo as digests/weekly/YYYY-MM-DD.md, with the daily ones in digests/daily/. The archive doubles as proof that the job ran.

The rules file is short, and each rule names the report that once got it wrong:

• Keep every PR citation. A PR number that appears in a source commit stays in the bullet, exactly as written. Never dropped, never invented.
• Say what is internal and what shipped. Investigation work and back-office tools are labelled as such, never described like a customer-facing feature.
• Verify every link against the file that records it. Never guess a URL from a naming pattern.
• Keep internal metrics out. Say what kind of work was done instead.
• Label people accurately, with their own organisation, not the company being discussed.
• Make failures visible. If scheduled runs were missed, the next report opens with a "schedule gap" line, worked out from the archive dates. If the language model is unavailable, the report says so and falls back to plain commit titles. It never ships placeholder text. The job also refuses to run from any branch except main.

Issue movement is covered by the tracker (Section 5): its daily view lists, per key item, what was completed, what advanced, what stalled and what shipped. A second scheduled job extracts the week's learnings after the weekly report, and the ones worth keeping go into the lessons file, tasks/lessons.md.

Here is a short excerpt from a real weekly report, with repository and people names replaced and long lines shortened. This one also shows the gap warning at work.

Weekly Digest: 2026-09-07 to 2026-09-13

Schedule gap: last archived weekly was 2026-08-10. Rebuilt ad hoc by
an agent; extractive TL;DR.

TL;DR
- Tech Platform: kill switches for email polling and request analysis (42 commits)
- Commercial: new /bootcamp-recommend skill; LinkedIn asset set (81 commits)
- Corporate Bootcamps: student projects showcase added to the map (42 commits)

Details: Tech Platform
client-product, 41 commits (topic: area-technology)
- feat(admin): kill switches for email polling and request analysis,
  with a banner users can read (#2141) @founder3
- feat(tutorial): revisitable in-app walkthrough of the five
  pipeline stages (#1816) (#2130) @founder3
- audit(onboarding-tutorial): PROBLEMS, 5 findings (#2136) @founder1
- ... +26 more

Contributions this week
@founder1: 77    @founder3: 55    @founder2: 33
Active: 11 repositories    Quiet: 15 repositories

Suggested improvement: Turn the report into a 20-minute Monday meeting. Each owner reads their area's TL;DR line, flags anything blocked and confirms their P0 items. Close the meeting by running the tracker (Section 5) so the plan is accurate for the week ahead.

13. A 30-day adoption plan

This plan assumes a team of 3 to 15 people, one person acting as "plan owner", and access to an AI coding agent. Everything here is suggested; adapt it to your pace.

Week 1: Set up the foundation

• Create a GitHub organization for the team and invite everyone.
• Create the planning repo. Add a short README, an instructions file (Appendix D), the labels in Appendix C, and the issue and PR templates (Appendices A and B).
• Turn on branch protection for main (require a pull request before merging).
• Make sure everyone has the basics of working on GitHub with Claude Code (branches, changes, review, merge). Our AI Builder course teaches them.

Week 2: Put the work in

• The plan owner writes the first version of the project map: three to six main topics, each with a priority, owner and Done definition.
• Turn every current task into an issue with an owner, a priority and a "Done when" list. Link each one from a subtopic in the map.
• Optional: create the Sheet mirror and agree the "sync" rule with the team.

Week 3: Bring in the agents and the work repos

• Create one or two work repos (for example, sales and content) with the folder template from Section 11.
• Have an AI agent take three small issues, open PRs and link them with "Closes #N". Humans review and merge.
• Start saving call notes and transcripts in each company's folder right after the call, and mirror them to the CRM.
• Start the lessons file with the first thing that went wrong (something always does).

Week 4: Make it a habit

• Switch on the weekly report (even a manual one written by an agent from the week's merged PRs and closed issues) and archive it in the planning repo.
• Hold the first Monday report meeting.
• Run /check and fix every drift and gap it finds, then schedule it nightly.
• Review: what is working, what is noise, which labels nobody uses. Trim.

Signs it is working after 30 days: every open task has an owner; nobody asks "where is the latest version?"; the Monday meeting takes under 20 minutes; and agents' PRs are being reviewed within a day.

14. Checklists

Before you start any piece of work

• Is there an issue? If not, open one first.
• Does it have exactly one owner and a priority?
• Does it have a "Done when" list someone else could check?
• Is it linked from a subtopic in the project map?

Before you open a pull request

• I am on a branch, not on main.
• The PR covers one change only.
• The description says what, why, what I checked, and the risk.
• It says Closes #N for the issue it finishes.

Before you merge a pull request

• I read the whole change, not just the description.
• Customer-facing or sensitive? A second person has approved.
• Nothing outward-facing (email, post, deploy) happens automatically on merge that nobody approved.
• Any duplicate PR is closed with a comment.

Every week

• The weekly report was produced and archived, with no schedule gap.
• Every P0 has moved or has a stated blocker.
• The tracker shows no unresolved drift, unowned tasks or unlinked issues.
• If you keep the Sheet mirror, it has been synced.

Appendix A: Issue template

Save as .github/ISSUE_TEMPLATE/task.md in each repo.

---
name: Task
about: One unit of work with an owner and a clear finish line
title: "<Area>: <outcome>"
labels: type:work
---

## Goal
<!-- One or two sentences: what changes, and why it matters. -->

## Context
<!-- Who asked for this and when ("Named by <name>, YYYY-MM-DD").
     Links to call notes, documents, or the conversation it came from. -->

## Done when
1.
2.
3.

**Owner:** <one name>
**Priority:** P0 | P1 | P2 | P3
**Due:** YYYY-MM-DD (optional)

## Related
- Parent / sibling issues: #
- Project map subtopic: <main topic> > <subtopic>

## Before starting (Definition of Ready)
- [ ] Searched open and closed issues: this is not a duplicate
- [ ] This is one reviewable piece of work (otherwise split it)
- [ ] Owner and priority are set

Appendix B: Pull request template

Save as .github/pull_request_template.md.

## What this does
<!-- One or two sentences: the change and why. One PR = one reviewable change. -->

## Changes
-

## What I checked
- [ ]
- [ ]

## What did NOT change
<!-- e.g. "No issues created or edited. Only the project map changed." -->

## Risk
Low | Medium | High, because ...

## Issues closed
Closes #

Appendix C: Starter labels

Appendix D: Instructions file starter (CLAUDE.md / AGENTS.md)

# <Repo name>: instructions for people and AI agents

## What this repo is
<Two or three sentences: purpose, who uses it.>

## Where things live
- Project map: `mental-model.md` (planning repo), changed only by pull request
- <Fact> lives only in `<file>`. Refer to it; never copy it.
- New company/project folders: copy `_template/`.

## Hard rules
- Never commit to main. Work on a branch and open a pull request.
- Issue first: every change is linked to an issue ("Closes #N").
- Never send, post, publish or deploy anything outward-facing without
  showing the exact content to a person and getting an explicit "yes".
- Never delete files or data rows without explicit approval.
- If a fact can't be verified, write "Unknown, verify directly". Don't guess.
- If an automated step fails, stop and say why. Never fill the gap
  with placeholder text.

## Standard processes
- New task: open the issue, then a PR adding it to the project map,
  then refresh the PM Tasks sheet if you keep one.
- "Sync" (only with a sheet): read the PM Tasks sheet, update issues and the map (by PR),
  then refresh the sheet.
- Meeting notes: save to `<folder>/<company>/call-notes.md` and the CRM.

## Vocabulary
| Term | Meaning here |
|---|---|
| | |

## Why these rules exist
- <YYYY-MM-DD>: <what went wrong, one line> -> <rule it created>

Appendix E: Project map starter

# Project map

This file is the team's picture of what we are trying to finish and who
owns each piece. It is not the tracker: issues hold the detail. When this
file and GitHub disagree, fix the issue first, then this file. Edits
arrive only by pull request.

Priorities: P0 blocking · P1 important, not blocking · P2 later · P3 meta.
Status: Backlog · Ready · Ongoing · Blocked · Review · Done.

<!-- map:start -->

## P0 · <Main topic>
**Owner:** <name>
**Done:** <the observable end state, one or two sentences>

### <Subtopic>
<!-- refs: #12 other-repo#34 -->
**Owner:** <name>        (optional, defaults to the main topic's owner)
**Priority:** P1         (optional, defaults to the main topic's)
**Status:** Ready
**Due:** YYYY-MM-DD      (optional)
**Done:** <the bar this piece has to clear>

This playbook reflects our team's working practices as of September 2026. Recommendations marked "Suggested improvement" go beyond what we do today; everything else is current practice.