set-up-project

Set up project

Scaffold and audit the per-repo configuration the skills assume:

• Rules file: AGENTS.md, which every harness reads. CLAUDE.md is either the single line @AGENTS.md or a symlink to AGENTS.md. Claude Code skips a project's AGENTS.md when a CLAUDE.md exists, and both of those forms give it the same text.
• Issue tracker: where issues live. GitHub is the default, and local markdown also works out of the box.
• Triage labels: the strings used for the five canonical triage roles
• Domain docs: where GLOSSARY.md and ADRs live, and the consumer rules for reading them
• Release lifecycle: docs/agents/releasing.md explains how the project releases a version, so everyone who releases it follows the same steps. It starts from the user's shared release rules when their workstation repo has them.
• Folder standard: the .gitignore lines of orchestrating/folder-standard.md
• Allow-only project permissions: the global rules are the machine's safety rails, and a project's own harness files only add convenience. The audit flags every project file that weakens a global rule.

You explore, present what you found, confirm with the user, then write. Running it again is the audit.

Steps

1. Check the machine

Run set-up-machine's verifier, python3 <set-up-machine skill>/scripts/verify.py, from the set-up-machine skill installed beside this one. A pass is exit code 0. When the exit code is not 0, run the set-up-machine skill first, then come back. Done when the verifier exits 0.

2. Explore

Look at the current repo to understand its starting state. Read whatever exists; don't assume:

• git remote -v and .git/config: is this a GitHub repo? Which one?
• AGENTS.md and CLAUDE.md at the repo root: does either exist? Is there already an ## Agent skills or ## Environment defaults section in either?
• GLOSSARY.md and GLOSSARY-MAP.md at the repo root, and any CONTEXT.md or CONTEXT-MAP.md in the repo: the domain docs' old names, which the skills no longer read
• docs/adr/ and any src/*/docs/adr/ directories
• docs/agents/: does this skill's prior output already exist?
• .efforts/: a sign that a local-markdown issue tracker is already in use
• docs/assets/: the folder standard's old image folder
• Is the triage skill installed? It is when a triage skill folder sits beside this one, or triage is in your available skills. This decides whether Section B runs at all.
• Monorepo signals: a pnpm-workspace.yaml, a workspaces field in package.json, or a populated packages/* with its own src/. These are present only in a genuinely large multi-package repo; their absence means single-context, which is almost every repo.
• How the project releases today: look for a CHANGELOG.md, the files that hold a version, the tags and the GitHub releases that gh release list shows, anything that publishes to a registry, and release steps already written in AGENTS.md or another doc. A package.json without "private": true, a Homebrew cask and a release workflow each publish to a registry. These signals decide whether Section E runs.
• The user's shared release rules: when the pointer ~/.config/agents/source.md names a workstation repo, read <path-to-workstation-repo>/setup/releasing.md if it exists. Without the pointer or the file, the seed template alone is the starting point.
• A tool the project's own docs require for a role skills name, such as a worktree tool in a docs/worktrees.md or a session host its scripts assume. This decides whether Section D runs.

3. Present findings and ask

Summarise what's present and what's missing. Then take the sections in order. One section, one answer, then the next.

Lead each section with the recommended answer so the user can accept it in a word. Give a one-line explainer only when the choice genuinely branches; skip the section entirely when exploration already settled it. Skip Section B when triage isn't installed, Section C when there's no monorepo and no old CONTEXT.md or CONTEXT-MAP.md, Section D when the project names no tool for a role, and Section E when the project has never released and has no release signals.

Section A: issue tracker

Explainer: The "issue tracker" is where issues live for this repo. Skills like to-tickets, triage, and to-spec read from and write to it. They need to know whether to call gh issue create, write a markdown file under .efforts/, or follow some other workflow you describe. Pick the place you actually track work for this repo.

Default posture: these skills were designed for GitHub. If a git remote points at GitHub, propose that. If a git remote points at GitLab, on gitlab.com or a self-hosted host, propose GitLab. Otherwise, or when the user prefers another tracker, offer:

• GitHub: issues live in the repo's GitHub Issues, through the gh CLI.
• GitLab: issues live in the repo's GitLab Issues, through the glab CLI.
• Local markdown: issues live as files under .efforts/<effort>/ in this repo, which suits solo projects and repos without a remote.
• Other, such as Jira or Linear: ask the user to describe the workflow in one paragraph, and record it as freeform prose.

Record the choice in docs/agents/issue-tracker.md. The GitHub and GitLab templates carry a "PRs as a request surface" flag, defaulted off. Leave it off and don't raise it: a user who wants external PRs in the triage queue can flip the flag in the file later.

Section B: triage label vocabulary

Skip this section entirely when exploration found that the triage skill isn't installed, since an uninstalled skill needs no labels.

If it is installed, ask exactly one question:

Do you want to keep the default triage labels? The recommended answer is yes.

The defaults are the five canonical roles, each label string equal to its name: needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix. On yes, write them as-is. Only if the user says no, usually because their tracker already uses other names such as bug:triage for needs-triage, collect the overrides so triage applies existing labels instead of creating duplicates.

Section C: domain docs

Default to single-context, which is one GLOSSARY.md and one docs/adr/ at the repo root. This fits almost every repo, so write it without asking.

Offer multi-context, a root GLOSSARY-MAP.md that points to one GLOSSARY.md per context, only when exploration found monorepo signals. Then confirm which layout they want.

When exploration found an old CONTEXT.md or CONTEXT-MAP.md, propose renaming each with git mv, so its history follows it: git mv CONTEXT.md GLOSSARY.md, git mv CONTEXT-MAP.md GLOSSARY-MAP.md, and the same for each per-context CONTEXT.md. Where the new name already exists, git mv refuses: propose merging the old file into the new one instead, and ask which wins where they disagree. Also propose updating the map's links and any other file that names the old files; the drafts of AGENTS.md and docs/agents/domain.md already use the new names.

When exploration found a docs/assets/ folder, propose moving each topic with git mv, as ../orchestrating/folder-standard.md > 'Migration from older layouts' says: images the project ships or shows to assets/images/<topic>/, screenshots to assets/screenshots/<topic>/, and each relative link to them updated.

Section D: project environment defaults

Recommend none. Ask only when exploration found a tool the project requires for a role: then propose an ## Environment defaults row for it, which overrides the user's global row for this project. agents-md.md > 'Environment defaults' says what may go there.

Section E: release lifecycle

Recommend writing docs/agents/releasing.md from releasing.md, with the user's shared release rules applied over it, and filled with what exploration found: what a release ships, the release order and who runs each step. Keep the page short, with each step in a line or two. Leave out what the shared rules already say, such as the version rule, the changelog format and the tag and notes formatting, and leave out commands, install instructions and plans for a registry the project doesn't use yet. Where the project does something the shared rules don't say, keep the project's way and name it. Where the two disagree, show both and ask which one this project follows. When the release steps already live in another doc, propose moving them into docs/agents/releasing.md and leaving a pointer behind.

4. Confirm and write

Show the user a draft of:

• AGENTS.md: new from agents-md.md, or the existing one with the ## Agent skills block and any ## Environment defaults rows added, and each line of an existing CLAUDE.md moved into it
• CLAUDE.md: the single line @AGENTS.md, or an existing symlink to AGENTS.md left as it is. Claude Code skips a project's AGENTS.md when a CLAUDE.md exists, and both forms give it the same text.
• .gitignore: .scratch/ and .claude/worktrees/, each only where it's missing
• The contents of docs/agents/issue-tracker.md and docs/agents/domain.md, of docs/agents/triage-labels.md when triage is installed, and of docs/agents/releasing.md when Section E ran
• Each rename or merge of an old CONTEXT.md or CONTEXT-MAP.md, and the edits to the files that name them, when Section C proposed them
• Each move out of docs/assets/, and the links it updates, when proposed

Let them edit, then take one approval for all of it. Then write:

1. Edit AGENTS.md, never CLAUDE.md. If an ## Agent skills block already exists, update its contents in place rather than appending a duplicate, and keep the user's edits around it. Include the ### Triage labels sub-block only when triage is installed and Section B ran, and the ### Releases sub-block only when Section E ran.

2. Leave a CLAUDE.md that holds @AGENTS.md or is a symlink to AGENTS.md as it is, and add the missing .gitignore lines.

3. Write the docs files using the seed templates in this skill folder as a starting point:

   • issue-tracker-github.md: GitHub issue tracker
   • issue-tracker-gitlab.md: GitLab issue tracker
   • issue-tracker-local.md: local-markdown issue tracker
   • triage-labels.md: label mapping, written only when triage is installed
   • domain.md: domain doc consumer rules + layout
   • releasing.md: the release lifecycle, written only when Section E ran

   For "other" issue trackers, write docs/agents/issue-tracker.md from scratch using the user's description.

   Give every docs/agents/issue-tracker.md the templates' ## Title prefixes section, so each skill that creates an issue titles it the same way. Seed its semantic list from the areas the project's open issue titles already name, one line each with what the area covers.

4. Run each approved rename or merge of an old CONTEXT.md or CONTEXT-MAP.md, then update the files that named it.

5. Run each approved move out of docs/assets/, then update the links to it.

Done when every approved change is made.

5. Audit

Read every harness file the project holds, from the root down, against set-up-machine's rules.json, whether or not that harness is set up on this machine: .claude/settings.json and settings.local.json, .cursor/cli.json, opencode.json or opencode.jsonc and .opencode/, .codex/config.toml. references/project-files.md says what each harness lets a project file do to a global rule, and how to judge an entry. Report each finding as:

• weakens: a global rule no longer holds as the machine sets it, in some harness. Explain which and why, and propose the fix: remove the entry, or narrow it to the project's own commands. The file is the project's, so change it only on the user's approval.
• overlaps: an allow that covers a rule's command while the rule still holds. Propose narrowing it.
• extra, a project deny or ask, and gap, what you can't judge: name each.

Also report each old CONTEXT.md or CONTEXT-MAP.md still in the repo, with the rename Section C proposes for it. Report a docs/agents/issue-tracker.md that has no ## Title prefixes section, and propose the section step 3 writes. Report a project with release signals and no docs/agents/releasing.md, and a docs/agents/releasing.md that disagrees with the user's shared release rules, and propose the update Section E writes.

The audit passes with no weakens. Done when it passes, or the user has chosen to keep a weakens entry: then it stays failed, and the report names that entry.

6. Done

Tell the user the setup is complete, what the audit found, and which skills will now read from these files. Mention they can edit AGENTS.md and docs/agents/*.md directly later; re-running this skill audits the project again, updates the release page when the shared release rules change, and switches issue trackers when they want to. Leave the commit to the user or the skill that called this one.