Agentic organization starter kit

Run your organization as code: your website, your apps, your decks, your facts and your voice — and, if you want, your projects and your team — in one repo you own, operated by AI. You talk; it reads your guides, does the work, publishes, and learns.

This is the workflow I use to run everything from a nonprofit's full marketing site to an artist's gallery and shop to my own one-page projects. Enough people have asked "how do you do that?" that I packaged it. Clone this, spend an hour on setup with a technical friend (or with me), and from then on you update your site by talking.

The bet behind it: AI should pay off on both horizons at once. It saves you time today (a post, a deck, a site update in minutes), and because every use leaves a rule, a fact, or a guide in the repo, the thousandth request is served better than the first. Disposable AI is fast today and worthless tomorrow; a grand IT scheme is the opposite. An agentic organization gets both, because the same gesture serves both.

Paul Duan · @pyduan · paulduan.com

Why this exists

Start with what's newly possible, because it's enormous. One person with an AI operator can now do what used to take a team: run a real website, produce decks and campaigns, follow every project, keep a research watch, even get management-grade help with their team. People half-joke about one-person unicorns; the honest version for the rest of us is that a two-person nonprofit can now operate like a twenty-person one. That's the prize, if it's done well.

Done naively, it isn't. Just handing everyone an AI chat window produces the same three failure modes, in organizations and solo projects alike:

• Middlemen that don't help. Non-technical people end up fighting a SaaS site builder (a subscription, an editor that fights back, content locked inside, someone else's banner on your own page) or depending on a developer for every comma.
• Shadow AI. Everyone prompts in their own corner. The same work gets redone everywhere, nothing is reviewable, and the AI never learns at the scale of the project or the team: every session starts from scratch.
• Version chaos. v3_FINAL_def(reviewed).xlsx scattered across the Drive, desktops, inboxes, and people's heads. Nobody knows which one is true.

The answer isn't a better prompt or one more tool: it's governance embedded in the structure of a repo. Write what the AI must know into plain files that inherit from one another — your identity and facts, your voice, your per-format rules, your personal voice on top — and the AI reads them fresh every session. Change a fact at the source and every future page, deck, and post is right by construction. That's the whole trick: you don't prompt-engineer, you maintain guides, and only once.

That's the best of both worlds: the acceleration of everyone using AI on everything, with none of the shadow. And it's cumulative: every correction becomes a rule, every project leaves a playbook, every 1:1 leaves a trace, so the system is measurably smarter after each use instead of starting over.

The idea

• One repo is the source of truth. Your content, your voice guide, your design system, and your format playbooks all live here as plain files. The website and every deck are derivatives, rebuilt from those sources. You don't integrate a mockup, you keep a design system; you don't email talking points around in Word files, you keep a facts library that's always current for everyone.
• AI is the operator. You open the folder in Claude Code and talk in plain language. It reads your guides on its own (the repo tells it where everything is), makes the change, shows you the result, and publishes.
• Git remembers everything. Every version of every page is kept forever, so nothing you do can break the site permanently.
• Publishing is free and automatic. Cloudflare Workers watches the repo and puts every change live on your domain in about a minute.

What a session feels like

"I dropped two new paintings in the inbox folder. Add them to the gallery, the big one is 1200 euros."

"Make a ten-slide deck for Tuesday's pitch from the notes I gave you, in French."

"Our tone reads too corporate. Warmer, fewer buzzwords."

"We won the Marseille grant. Log it, file the award letter, and tell me what's next across all projects."

"Here are my 1:1 notes from this week. What should I not drop as a manager?"

That third one updates your voice guide, so every future page and deck inherits it. At the end of each session the AI saves, publishes, and folds anything new it learned about your taste into your guides. You never touch git, code, or a deploy button.

What's in the box

AGENTS.md            the AI's operating manual: rules + a map of every guide (CLAUDE.md is a one-line pointer to it)
FEATURES.md          what the repo does, feature by feature, and the design decision behind each
STACK.md             what runs on what and the way out of each service, each row approved by you, dated
CONNECTORS.md        which of your mail, files and chat the agent may read, for what and how far, approved the same way
ORGANIGRAM.md        your org's repos + who may use/change/approve what (solo by default)
QUICKSTART.md        the one-pager to hand someone before the setup hour
SETUP.md             the one-hour setup checklist, three ways to install
source/              your source of truth
  brief.md           who you are, what the site is for, current priorities
  objectives.md      your north star: the few priorities projects & goals align to (yours alone)
  decisions.md       how hypotheses & positioning evolved, and why (per discussion)
  inbox/             drop zone: put anything here and tell the AI about it
  content/           your canonical texts, facts, and data (prices, catalogs...)
  facts/             sourced third-party facts and key figures (stats, benchmarks)
  brand/             voice guide, design guide, design tokens, original assets
  formats/           one playbook per output: website pages, decks, apps, messages, the intranet
  quality/           the register of the AI's own mistakes on your project (see below)
site/                the website itself (Astro, deployed by Cloudflare Workers)
decks/               your presentations: each composed in deck.mdx, built into one shareable HTML file
apps/                your web apps (a calculator, a form flow, a tool), one folder each
apps/dashboard/      your intranet: a quickstart, where every project stands, your tools, behind a login
projects/            (optional module) your real work, tracked: charter, log, files, next steps
team/                (optional module) your team files — gitignored, local-only, never shared
scripts/             install scripts (mac + windows), the deploy/build helpers, the checks
docs/                how it works, the deploy guide, the troubleshooting FAQ, how this goes wrong
.claude/             skills (setup, new-project, publish, new-deck, research, projects, team, reflect, feedback, update-kit, check-setup) + hooks

The guides ship as genericized templates distilled from real projects. The first session personalizes them: the AI interviews you, then builds from whatever you start with — documents dropped in the inbox, an existing live site it scrapes, or an existing repo it clones and mines for content (rebasing onto this kit's own structure, never reusing the old code) — or from nothing at all, if you're starting fresh.

What the first hour actually does

Not "build a website". The first session starts by walking STACK.md and CONNECTORS.md with you, one row at a time, so every service and every connector has your yes and a date on it. Then it publishes your intranet behind a sign-in. Then it decides where this organization's material will live, decides which facts matter, and goes and finds them, through the connectors you approved: the facts with their sources, the decisions with their reasons, the history in order. It runs your first real task as a recipe the repository keeps, so the second run costs less than the first. The site is built from those files, in the last part of the hour, and every later session reads them rather than re-asking you.

That order is the whole design. Build the site first and the corpus never gets opened, because a finished-looking site removes the reason to go back — and then every conversation reasons from memory instead of from a file. The recipe is .claude/skills/fact-finding/SKILL.md, and it runs again, smaller, every time a new client, area or pile of documents arrives.

Two things worth knowing before you start

An intranet, before anything else. Once the stack is approved, the first thing the setup builds is your intranet: a private home page, only you (and whoever you name) can open. At the top, a banner with the quickstart and how the system works, in words you edit in source/content/intranet-home.md; below it, where every project stands, who waits on what, and a card per tool. It publishes as its own Cloudflare Worker behind a login, never as a public URL nobody has guessed yet. source/formats/dashboard.md is the playbook.

It keeps a record of its own mistakes. Every project running this kit logs what the AI got wrong — what it had in front of it, what it did, who caught it, and whether anything now prevents it — into source/quality/incidents.json. You can read that as a report at any time, and send an anonymized version (the transferable lesson only, nothing about you or your work) to whoever maintains the framework:

node scripts/error-report.mjs --anonymized --email

That is how the seven failure families in docs/failure-modes.md got written: a real project logged its errors, and the defaults changed.

Getting started

About an hour, three ways to do it — pick whichever fits, they all end the same place. The single page to hand someone who is about to sit down for it is QUICKSTART.md (the accounts, the paste, the connectors, the first use case); full detail in SETUP.md:

• Let Claude install itself. Open Claude Code (the desktop app is the easiest on-ramp if you're not a terminal person) and paste the prompt below; it checks your machine, installs whatever's missing, and creates your own copy of this repo.
• Run a script. One command, Mac or Windows, does the same thing deterministically — good for a technical helper setting this up for someone else.
• Do it by hand. Click Use this template on GitHub, install the few tools yourself, clone it.

The prompt to paste, if you go the first route, is QUICKSTART.md ▸ Install, in one paste: one prompt for everyone, in the order the setup runs. Paste it in the Code tab of Claude Code, never in the chat: only a Code session reads the repository.

Either way you end up with your own copy, cloned locally, and a first session that opens on the stack walk, then your intranet, then the interview. After that it's yours: open the folder, run claude (or the desktop app), talk.

If a step fails, docs/troubleshooting.md has the fixes for the problems everyone actually hits: git vs GitHub vs gh, the Mac command-line-tools popup, "command not found" right after an install, Cloudflare's empty branch dropdown, and running Claude Code in the cloud instead of installing anything locally.

Try saying

A few things to say once you're in, to get a feel for it:

• "Set up my organization." The first session: the stack and the connectors, row by row, then your intranet, then the interview. ("Set up my site" works too.)
• "Set up my site from my existing site at [URL]." — skips straight to scraping it.
• "Here's my old site's repo: [URL]. Set up from that." — mines the raw files instead of the rendered pages (often richer).
• "Build me a [calculator / simulator / intake form] for this project." — a web app in apps/, same brand, same repo, published under the site or on its own URL.
• "I want to start a new project for [someone/something else]." — a different client or brand gets its own repo, never mixed into this one. (Same project's tool or sub-site stays here; the AI makes that call before creating anything.)
• "Find me real numbers on [X]." — a sourced research pass, banked for later.
• "Make a deck for [occasion], here are my notes." — a new presentation from a brief.
• "Start tracking the [client / grant / launch] project." — a charter, a decisions log, and living next steps in projects/; every later deck or status question draws on it.
• "Here are this week's 1:1 notes." — distilled into a per-person file and a prioritized management TODO, all in a local-only folder that never leaves your machine.
• "This doesn't sound like me — [what's off]." — corrects the voice guide, permanently, for every future page and deck.
• "Update the framework." — pulls the latest kit improvements (new skills, better guides) into your project, keeping all your own content.

Staying up to date

This kit keeps improving. Your project is your own copy, so it doesn't change on its own — when you want the latest, open your project in Claude Code and say "update the framework" (the update-kit skill). It pulls the newest guides, skills, and scripts from the template, leaves all your content untouched (your pages, your facts, your voice), and tells you if any improvement needs a small follow-up. Then it commits and publishes as usual. Nothing you've built is at risk.

If you set up before the update-kit skill existed (early adopter — you won't see it in .claude/skills/), or your copy of it is old, send your agent the block in update-kit ▸ The block to send an install that predates kit-sync once. It fetches the sync tool from the template before anything else, keeps every file you changed for you to decide on, and ends by saying which rows of your STACK.md and CONNECTORS.md still wait for your yes, for your next session to walk with you.

When you grow

The kit is tuned for one owner working solo on main. When a second regular contributor joins, the switch is one conversation: contributors move to branches and pull requests, one person merges, and everything else stays the same — the same guides, the same cascade, now with a review before publishing. And when you end up running several projects, there's a spectrum for laying them out (folders in one repo, repos in one GitHub org, or separate orgs) that the AI will walk with you before it builds. The mental model — growth, multiple projects, and the escalation paths for content and features — is in docs/how-it-works.md.

Where this comes from

Every rule in these guides was learned by shipping: a multi-contributor organization site with a full design system and deck engine, an artist's gallery and shop that gets updated weekly through an inbox folder, a brand built from scratch where the source documents came before any website, and a couple of deliberately tiny personal sites. The kit keeps what survived contact with real, mostly non-technical users and drops the rest.

Contributing

An error report, a pack your project already runs, or a pull request on the kit: the three ways, and how each is triaged, are in CONTRIBUTING.md.

Status

Beta, and open to more than friends now. If you're using it and something in the flow confused you or your AI, that's a bug in the kit: tell me.

MIT license. If you build something with it, I'd love to see it — and if this saved you the trouble of building it yourself, a star helps the next person find it.