New Workspace Setup Checklist

Use this checklist when setting up a new Claude Code workspace from scratch. Each item includes a brief explanation of what it means and why it matters. Work through the phases in order -- each builds on the previous.

Phase 1: Before you start

Confirm these before creating any files:

• Decide the workspace purpose. Is this a personal workspace, a client workspace, or a team workspace? The type determines which CLAUDE.md template to use and what access boundaries to set.
• Name the workspace. Choose a short, descriptive identifier (e.g. acme-construction, agency-os). This becomes the folder name, the git repository name, and the identity Claude uses in session banners.
• Have a git remote ready. Create the GitHub (or equivalent) repository before starting. Commit early -- if something goes wrong, you want a clean restore point.

Phase 2: Setting up structure

[ ] Create .claude/ directory
    -- The hidden folder where all Claude configuration lives.
    -- Claude Code looks here automatically on every session start.

[ ] Create .claude/CLAUDE.md with workspace identity
    -- The primary instruction file. Defines who Claude is in this
    -- workspace, what folders it can access, and what conventions to follow.

[ ] Create .claude/state/state.json (workspace + empty projects)
    -- Tracks project status, milestones, and priorities across sessions.
    -- Acts as a persistent project dashboard Claude reads on startup.

[ ] Create .claude/rules/ and add communication, autonomy, blocked-commands
    -- Granular instruction files, one concern per file. Claude loads
    -- all files in this directory automatically. Start with the three
    -- named above -- they cover the most common behaviour settings.

[ ] Create .claude/skills/ directory
    -- Where reusable instruction sets (skills) live. Empty at first;
    -- you add skills as you identify recurring tasks worth automating.

[ ] Create .claude/hooks/ directory
    -- Where automation scripts live that run at session lifecycle points
    -- (e.g. on session start, before a tool runs, on session end).

[ ] Create Claude Projects/, Documentation/, Scripts/
    -- Standard top-level folders. Claude Projects/ holds all project
    -- subfolders. Documentation/ holds reference material and templates.
    -- Scripts/ holds operational scripts Claude can run.

Phase 3: Configuration

[ ] Register workspace in ~/.claude.json or .mcp.json
    -- Tells Claude Code which MCP servers are available in this workspace.
    -- ~/.claude.json is personal (not committed); .mcp.json is shared.

[ ] Set up Git remote (SSH preferred)
    -- SSH is more reliable than HTTPS for automated pushes.
    -- Run: git remote set-url origin git@github.com:you/repo.git

[ ] Add .gitignore entries for .prima-memory/, *.db, .env
    -- These files contain credentials or large local data that must
    -- never be committed. The .gitignore file tells version control
    -- to ignore them permanently.

[ ] Register MCP servers needed for this workspace
    -- MCP servers connect Claude to external tools (calendar, email,
    -- databases). Register only what this workspace actually needs.

[ ] Test Claude loads CLAUDE.md on startup
    -- Open a new session and ask Claude to confirm its workspace identity.
    -- If it cannot, the file path or registration is incorrect.

Phase 4: First session

[ ] Run /day to verify state reads correctly
    -- The /day command reads state.json and presents a session briefing.
    -- If it errors, the state file structure is incorrect.

[ ] Create first project with /newproject
    -- Registers the first body of work in state.json. Confirms the
    -- project creation workflow is operational end-to-end.

[ ] Test a skill with a sample invocation
    -- Type /help to see which skills are loaded, then invoke one.
    -- Confirms skills in .claude/skills/ are being discovered.

[ ] Verify git push goes to the correct remote
    -- Run a /sync and confirm the push lands on the right repository.
    -- Critical for client workspaces -- a push to the wrong remote
    -- could expose client data in the wrong repository.

Verification

After completing all four phases, confirm the workspace is operating correctly:

• Session banner shows the correct workspace name and type
• Claude can read and write files within the workspace root
• Claude cannot access folders outside the scope defined in CLAUDE.md
• /status returns a project overview (even if empty)
• A test git commit and push completes without errors