Set up your project workspace

What you get

The template is a coordination layer — not product code. It gives every agent and human a single known place to find context, conventions, and active work. Everything project-specific is a <…> placeholder or a stub with a header comment, so you fill in, you don't reverse-engineer.

The mental model

One file is the front door. The three agent entrypoints are symlinks to it, so every runtime reads the exact same context — edit once, all agents see it.

Quick start

Five steps from clone to a working workspace. Steps 1–3 are mechanical; step 4 is where you make it your project.

1. Create your workspace from the template

   On GitHub, click “Use this template”, or clone and reset git history:

   git clone https://github.com/<you>/ai-workspace-template.git <project>-workspace
   cd <project>-workspace
   rm -rf .git && git init

2. Bootstrap the local files

   Run the setup script — it runs a dependency preflight, then creates .env, the agent symlinks, repos/README.md, and the per-user config copies (idempotent). Add --clone-repos for a multi-repo workspace. Missing tools? Follow runbooks/dependencies.md.

   ./scripts/setup.sh                 # creates .env, symlinks, repos/README.md
   ./scripts/check-workspace-structure.sh   # verify symlinks resolve, dirs present

3. Wire up agents & MCP

   Copy the per-user config templates (all gitignored), then authenticate. Run the check, then follow runbooks/authentication.md for anything missing; per-runtime MCP detail is in docs/mcp-setup.md. The YouTube transcript MCP server is workspace-local and credential-free; install yt-dlp if you use it.

   cp -n .env.example .env
   cp -n .mcp.json.example .mcp.json
   cp -n .claude/settings.json.example .claude/settings.local.json
   ./scripts/check-service-access.sh                  # reports gaps + fix commands
   gh auth login                                      # if not already authenticated

4. Make it your project

   Replace every <…> placeholder and resolve the TODO / “Fill in” comments — start with CONTEXT.md (it loads into every agent session). Find what's left:

   grep -rIn --exclude-dir=.git -e '<[a-z-]\+>' -e 'TODO' -e 'Fill in:' .

   • CONTEXT.md — name, purpose, single- vs multi-repo model
   • docs/repos-registry.md — one entry per product repo
   • docs/service-access.md — your GitHub username; add a section per service
   • SPEC.md — product intent (or delete for a pure coordination layer)
   • work/ — prune the maintainer's shipped work history (git rm -r work/*/); it's a worked example, not machinery — see template-usage.md §5

5. Start building

   Decide on the optional bits: graphify is the core MCP server (wired by default; it also adds .gemini/settings.json / .opencode/plugins/graphify.js). YouTube transcript MCP is an opt-in fragment under mcp-fragments/, loaded per session — see docs/mcp-setup.md; GitHub goes through the required gh CLI (no MCP server). Delete what you don't use.

   Add reusable workflows under skills/ and list them in CONTEXT.md. The template ships four: checkpoint (session wrap-up), onboard-repo (bring a repo in), rlm (query huge contexts), and decision-log — capture the why behind a decision (/decision) as an ephemeral note in work/<proj>/decisions.md, promoted to a committed ADR under docs/adr/ for lasting-weight calls. See the Decision Records section of CONTEXT.md.

   Checks: scripts/run-checks.sh runs every workspace check; on GitHub, .github/workflows/checks.yml runs it on each push (delete the file to opt out), and git config core.hooksPath scripts/git-hooks opts you in to a pre-commit run of the fast set.

Deeper reference:

• docs/template-usage.md — adapting the template to a project
• docs/workspace-setup.md — recreating the workspace on a new machine
• docs/workspace-structure.md — what every directory is for

Global vs. workspace-local setup

Setup splits into two layers. Do the GLOBAL layer once per machine; the LOCAL layer once per clone. The local layer depends on the global one (the MCP token and the gh login).

What's tracked vs. gitignored

Nothing secret ever enters git. Credentials stay in the keychain; the repo holds only templates and non-secret identifiers. Full table in docs/workspace-structure.md → “Gitignored vs. Checked In”.

Recommended toolchain

Optional external tools this workflow assumes. They're global / per-user — installed once per machine, never committed to the repo — except for two that also need a per-repo step. Full setup in docs/recommended-tooling.md.

Quick reference:

# status line
npm install -g ccstatusline           # install once; wire statusLine in ~/.claude/settings.json

# plugins (official marketplace is built in)
claude plugin install superpowers@claude-plugins-official

# graphify
uv tool install "graphifyy[mcp]"
/graphify                             # build the graph for THIS repo → graphify-out/
graphify update .                     # refresh after code changes

# YouTube transcript MCP
yt-dlp --version                      # install via brew / apt / winget if missing
scripts/mcp/youtube-transcript.sh     # workspace-local stdio server

# skill repos — managed via agent-context (clone, then link with agent-context-sync)
git clone https://github.com/mattpocock/skills.git ~/Developer/references/mattpocock-skills
git clone https://github.com/ForrestChang/andrej-karpathy-skills.git ~/Developer/references/karpathy-claude-md
agent-context-sync                    # links new skills into ~/.config/agent-context/skills

# Matt Pocock per-repo config (before to-tickets / triage / to-spec)
# run the setup-matt-pocock-skills skill in the repo

For AI agents

If you are an AI agent setting this up

• Read CONTEXT.md first — it's the front door and loads the project's conventions and the “Agent Coding Principles” / “Agent Context Discipline” rules.
• Treat docs/workspace-structure.md as the spec. Its “Agent Bootstrap Instructions” section is a step-by-step procedure for scaffolding or extending a workspace — files to create, stub-header format, and post-scaffold verification checks.
• Confirm preconditions before creating files — workspace name, repo list, editors/runtimes, and external services. Don't invent repo names or clone URLs.
• Persist intermediate state to work/<project>/ so it survives context compaction — not to conversation memory.
• Disk is the source of truth. Re-read files before asserting facts; verify symlinks resolve and scripts are executable after scaffolding.

Verify before you call it done

gh auth status                                    # global: GitHub auth
claude mcp list                                   # local:  core MCP (graphify) visible
scripts/mcp/youtube-transcript.sh                 # local:  starts YouTube MCP (opt-in fragment)
./scripts/check-workspace-structure.sh            # local:  symlinks + dirs OK