Set up a work site

A work site is where you think your project through, before and while you build it. You write what you're working on and why, shape ideas before building them, and keep track of the work, research and decisions along the way. Your agents read it before they build, and keep it up to date as they work.

It's a small PathMX site in its own repository, beside your code. When you're done, you'll have it running on your computer with your first idea written up in your own words. Allow about 45 minutes, most of it writing.

The parts marked "You" are where your own thinking goes. Claude won't write them for you; it asks questions that help you write them. Writing it yourself is how you find out what you think, and your agents get better direction from it than from anything they'd guess.

Open Claude's Code tab in your projects folder, the one that holds your project's repositories, and paste:

I'm in the PathMX Builders Club. Read https://pathmx.club/learn/work.guide.md
and follow its "For Claude" steps with me in this folder. Go one step at a
time, and stop to ask me before anything that needs my sign-in.

Next time, open Claude in the work site's folder, or in one of your code repositories once it points to the work site.

• Start the week with Now. Two or three sentences on the home page: what you're working on and why it matters.
• Shape before you build. When an idea will take more than an afternoon, start a shape and write the problem and how much time it deserves. Mark it ready when you know what you're building.
• Break a ready shape into issues with Claude. Each issue names the repository it changes. Work on it there; Claude keeps its "Where it stands" current.
• Log decisions when you make them, in a sentence or two.
• Bring it to check-ins. Walk Mark through Now, the shape you're on and what's in progress.

You're helping a student builder set up a work site for their project from the PathMX work starter. First read For agents working with a builder and follow it throughout. Log every PathMX problem in the work site's pathmx-feedback.md once it exists (step B).

Ask the builder what the project is called and which repositories hold its code. Confirm the folder you have open is the one that holds those repositories; the work site goes beside them. Run git --version and bun --version; Bun must be 1.4.0 or newer.

Name the work site after the project, ending in -work, such as axiocite-work. In the projects folder:

git clone https://github.com/pathmx/pathmx-work-starter <name>
cd <name>
git remote remove origin
bun install --frozen-lockfile

Set name in package.json to the same name. Read the work site's AGENTS.md now and follow it, especially "This work site": it says which parts are the builder's to write.

Start the development server and keep it running in the background:

bun run dev

Have the builder open http://localhost:3000 and confirm they see "Project work". If port 3000 is taken, use bun run dev --port 3001.

1. Replace "Project work" with the project's name, such as "Axiocite work", in paths/work.layout.md (the sidebar) and the title of paths/index.md.
2. Ask the builder to read the home page's introduction and change anything that isn't how they'd say it.
3. In the issue template at the bottom of paths/issues.md, replace my-app with one of their repositories.
4. In paths/work.log.md, replace YYYY-MM-DD with today's date.

Leave the bracketed prompts for the builder. Run bun run check, which should report No issues found.

Ask the builder which idea they're working toward next. If their club project page names a first milestone, start there. Create paths/shaping/<name>.shape.md from the template at the bottom of paths/shaping.md, with the idea's name as its title, and leave every bracketed prompt in place. It appears on the home page.

Then help them write it, starting with The problem and How much it's worth. Ask one question at a time, such as "Who ran into this last, and what happened?" or "What would you want to show after two weeks?" They write the answers into the page: in an editor, or in chat for you to place exactly as they wrote them. Point out anything vague or contradictory; don't rewrite it. The other sections can wait for later sessions.

Finish with two short pieces of their own: the Now on the home page, and the first entry in the log. Run bun run check.

git add -A
git commit -m "Start my work site"

Putting it on GitHub is optional. A work site often holds plans for a business or a client, so suggest a private repository; the builder chooses. If they want one, they create an empty repository on github.com and give you its URL. Run git remote add origin <url> and git push -u origin main.

Mark reads work sites before check-ins. Suggest the builder add him as a collaborator: on github.com, the repository's Settings → Collaborators → Add people, then wmdmark. They do this themselves.

Ask the builder whether their code repositories should point to the work site. If they agree, add this to each one's AGENTS.md, with the work site's folder name:

## Work site

Plans, shapes and issues for this project live in its work site, `../<name>`.
Before starting, read the issue you're working on there. Before ending a
session, update its "Where it stands" and status.

Commit it the way that repository usually takes changes, such as on a branch with a pull request.

Tell the builder where the work site is and how to open it (bun run dev in its folder), what they wrote, which prompts are still waiting for them, and any PathMX feedback you logged. Remind them to start next week with Now.

For agents working with a builder covers working with a builder and logging PathMX feedback. All guides · Back to the Builders Club