---
title: Set up a work site
description: Give your project a place to think it through, beside its code. You write the ideas and decisions; your agents read them before they build and keep the work current.
---

# 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.

---

<!-- id: whats-in-it -->

## What's in it

| Page | What it's for | Who writes it |
| --- | --- | --- |
| Now | What you're working on this week, and why | You |
| Shape | An idea you're thinking through: the problem, who feels it, how much time it deserves, a rough direction | You, with Claude asking questions |
| Design | How a settled idea will work | You and Claude together |
| Issue | One piece of work: what will be true when it's done, and where it stands | Either of you; Claude keeps it current |
| Research | A question looked into, and what it means for your project | Either; you write what it means |
| Log | What happened and what you decided | You |

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.

---

<!-- id: hand-off -->

## Hand it to Claude

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

```text
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.

---

<!-- id: week-to-week -->

## Week to week

- **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.

---

<!-- id: for-claude -->

## For Claude

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

---

<!-- id: find-project -->

### A. Find the project

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.

---

<!-- id: starter -->

### B. Copy the starter

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

```sh
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:

```sh
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`.

---

<!-- id: make-it-theirs -->

### C. Make it theirs

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`.

---

<!-- id: first-shape -->

### D. Write the first shape

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`.

---

<!-- id: save -->

### E. Save it with Git

```sh
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.

---

<!-- id: point-code -->

### F. Point the code at it

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:

```md
## 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.

---

<!-- id: wrap-up -->

### G. Wrap up

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.

---

## More

[For agents working with a builder](./agents.guide.md) covers working with a
builder and logging PathMX feedback. [All guides](./index.md) ·
[Back to the Builders Club](../index.md)