Project Setup

Project Setup — Tool Folder Scaffolding

> This skill handles tools — utilities and dev projects built for own use, team use, or open-source release. No buyer being designed for. For client engagements, use $TEMPLATE_ROOT/templates/client-project/.claude/skills/project-setup/SKILL.md. For internal products with a buyer/audience, use $TEMPLATE_ROOT/templates/internal-product/.claude/skills/project-setup/SKILL.md.

This skill handles three situations:

• Greenfield: The user wants a new tool folder. You copy the template and fill placeholders.
• Retrofit: An existing tool folder needs the template structure added. You merge intelligently — add what's missing, leave existing content alone.
• Reconcile: An existing folder's memory has drifted from reality (long technical session, thread loss, in-flight state never made it to disk). You rebuild state.md and re-sync the other memory files from git history, the activity log, and on-disk evidence.

Before doing anything, read $TEMPLATE_ROOT/config.local.md first — if it exists, use those values. Otherwise fall back to $TEMPLATE_ROOT/config.md. The .local.md variant is gitignored and holds the user's real paths and identity; config.md is the generic public version. Every path below is expressed relative to those two variables. Do not hardcode anyone's home directory. If the file that was actually read (either .local.md or .md) still contains /REPLACE/WITH/... placeholders, stop and tell the user to fill it first — the repo won't work until they do.

The template lives at $TEMPLATE_ROOT/templates/tool/. Instantiated projects live at $TOOLS_ROOT/{project-slug}/.

When to Use

Greenfield triggers:

• "Set up a new tool"
• "Scaffold a folder for [tool name]"
• "Start a new utility project"
• "Create the folder structure for [a script/integration/CLI]"

Retrofit triggers:

• "Retrofit this folder" (and the folder is a tool/utility, not a client engagement or internal product)
• "Bring this tool up to the template"
• "Add the template structure to this existing tool folder"
• The user selects an existing folder in Cowork and asks you to set it up

Reconcile triggers:

• "Reconcile this folder's memory"
• "The state file is out of date"
• "Rebuild memory from git history"
• "I had a long session and the folder doesn't reflect reality anymore"
• Auto-prompt: during retrofit, if 01-context/state.md exists but is older than 7 days AND there's been git activity since, offer reconcile mode.

Detecting Which Mode

Before doing anything, determine mode. Ask yourself:

1. Is there a target folder path already referenced?
2. Does that folder already exist?
3. Does it already have content (files, subfolders) beyond what the template would generate?
4. Does it already conform to the template (i.e., has 01-context/state.md and the iterative-memory rule)?

Decision tree:

• No folder exists → greenfield.
• Folder exists, missing template files → retrofit.
• Folder exists, conforms to template, but state.md is stale or the user asks to rebuild memory → reconcile.
• Ambiguous → ask the user explicitly.

Prerequisites (greenfield + retrofit)

Use AskUserQuestion if anything important is missing. At minimum, gather:

1. Project slug — short, lowercase, hyphenated (e.g. gtm-form-tracker, linear-todos-sync)
2. Tool display name — the name used in running text and the README header
3. One-liner — what the tool does in one sentence
4. Stage — idea / prototype / working / used in production / sunset
5. Why this tool exists — what friction it removes, what it automates
6. Users — yourself / your team / contractors / external users / public open source
7. Project start date — ISO format
8. Current status — one line. "Initial prototype," "Working but rough," "In daily use," etc.

Additional helpful context (ask if relevant):

• Platform / ecosystem the tool plugs into (Shopify, GTM, Linear, etc.)
• In/out scope boundaries (tools accrete features fast — write these down)
• Success criteria — what "this is working" looks like
• Tech stack picks
• Project-specific guardrails the user wants the agent to respect

In retrofit mode, some of these may already be answered in files like CLAUDE.md, README.md, or any spec/design docs in the folder. Read first, ask only for the gaps.

The Placeholder Map

Every {{TOKEN}} is documented in $TEMPLATE_ROOT/placeholder-map.md. Read that file before filling anything. It's the source of truth — if a token exists in a template file but not in the map, flag to the user rather than guessing.

---

Greenfield Procedure

Step 1: Confirm slug and target path

Confirm with the user:

• Slug: {project-slug}
• Target: $TOOLS_ROOT/{project-slug}/

If the target folder already exists, stop and ask the user. This may actually be a retrofit situation.

Step 2: Copy the template

cp -R "$TEMPLATE_ROOT/templates/tool" "$TOOLS_ROOT/{project-slug}"
find "$TOOLS_ROOT/{project-slug}" -name ".DS_Store" -delete

Step 3: Read the placeholder map

Read $TEMPLATE_ROOT/placeholder-map.md in full. Note the section on tool-specific tokens (TOOL_*, ECOSYSTEM_*).

Step 4: Gather the data

Use AskUserQuestion where needed. Collect answers for every required placeholder. For long-form fields, draft from what the user tells you, then let them refine. Do not invent facts — leave TODO: markers with questions if you don't know something.

Step 5: Fill the placeholders

Use Edit with replace_all: true for each token, one file at a time:

• CLAUDE.md
• README.md
• 01-context/tool-charter.md
• 01-context/project-scope.md
• 01-context/decisions-log.md
• 01-context/activity-log.md
• 01-context/insights.md — usually just the {{PROJECT_DISPLAY_NAME}} and {{LAST_UPDATED}} tokens; {{INITIAL_INSIGHTS}} can be left empty or lightly seeded
• 01-context/state.md — sections empty, headers in place. Fill {{PROJECT_DISPLAY_NAME}}, {{LAST_UPDATED}}, {{LAST_UPDATED_SURFACE}}, and {{ACTIVE_SUBPROJECT_SLUG}}. If there's no active sub-project yet, leave that as none-yet or similar. {{INITIAL_STATE_NOTE}} can be a one-line "Project just kicked off — no in-flight work." {{EXTERNAL_SYSTEMS_INVENTORY_HINTS}} can be left empty or seeded with any platforms the tool is expected to touch (e.g., "Will likely touch: AWS Lambda, GTM container API.")
• 02-deliverables/kickoff-notes.md

Ecosystem-context-worthy tools only: If the tool plugs into a platform with non-obvious conventions, integrates with vendor APIs that have gotchas, or is meant for public release, also fill 01-context/domain-context.md with the ECOSYSTEM_* tokens. For self-contained tools with no meaningful external context, delete the domain-context.md file rather than leaving it with unfilled placeholders. Ask the user if you're unsure.

Subfolder READMEs (03-assets/, 04-research/, 05-build/) are generic — skim but usually no edits needed.

Step 6: Seed the decisions log

Pre-fill realistic rows based on what the user has shared:

• Any decisions already made (tech stack, hosting, architecture)
• Any open decisions you can identify
• Any outstanding external dependencies you know about (vendor accounts, API access, credentials)

Don't overfill. The user will add rows as the project moves.

Step 7: Seed the activity log

Append one entry to 01-context/activity-log.md noting the scaffold.

Step 8: Confirm the iterative-memory rules and /checkpoint command are in place

The template includes:

• .claude/rules/iterative-memory.md — always-on rule for Claude Code / Cowork
• .cursor/rules/iterative-memory.mdc — always-on rule for Cursor
• .claude/commands/checkpoint.md — the /checkpoint slash command

Verify these copied over. They are essential to the iterative model — without them, agents will fall back to session-end discipline.

Step 9: Report back

Show the user:

• Folder path that was created
• Tree of what got generated
• Any TODO: markers
• Summary of placeholder values used

Wait for the user's review before declaring complete.

---

Retrofit Procedure

Core principle: merge intelligently, never overwrite silently. The user has already put effort into this folder. Your job is to add missing template pieces, not to second-guess what they've built.

Step 1: Inventory the existing folder

Compare the existing folder to the template structure. Produce an inventory of:

• Files that exist in the template but not in this folder → candidates to create
• Files that exist in both → candidates for surgical addition (e.g., adding the new "Iterative Memory — Update As You Go" section to an existing CLAUDE.md) but never overwrite
• Subfolders missing → 03-assets/{copy,photos,brand}/, 04-research/competitors/, 05-build/wireframes/, .claude/commands/, .claude/rules/, .claude/skills/project-setup/, .cursor/rules/
• Files that exist here but not in the template → leave alone, note them

Memory-drift detection. If 01-context/state.md already exists, check:

• When was it last updated? (Last updated: … line in the file, or git log)
• Has there been git activity since that timestamp?
• If the gap is > 7 days OR there are uncommitted changes since the last state.md write, flag this as memory drift and ask the user whether to switch into the reconcile mode below before continuing the retrofit.

Step 2: Mine existing artifacts before asking the user anything

Retrofit is different from greenfield because the answers to most prerequisite questions are already somewhere — the folder, the user's other tools, or public sources. Your job is to find them, not ask. Work this hierarchy top-down, only dropping to the next tier when the current one is exhausted:

Tier 1 — Inside the folder itself (always check first):

• CLAUDE.md or README.md at folder root — often has tool one-liner, current status
• 01-context/tool-charter.md — what the tool is, who uses it, scope boundaries
• 01-context/project-scope.md — what's being built, timeline, tech stack
• 01-context/decisions-log.md — what's been settled, what's open
• 01-context/activity-log.md — chronology of recent work
• 01-context/state.md (if it exists) — current in-flight state
• 02-deliverables/ — specs, design docs, ADRs often contain the richest source material; sub-project subfolders are where active technical work lives
• The actual code — module structure, README, CI config — these tell you a lot about scope and conventions
• 04-research/ — vendor/platform docs, related-tool analysis
• Any loose .md, .pdf at the root — users often drop context here first

Tier 2 — The user's connected surfaces (check if Tier 1 has gaps):

• Second Brain / Obsidian notes on the tool
• Linear projects tagged to the tool
• Any prior Claude chat exports in the folder

Tier 3 — Public sources (fill in the picture):

• Vendor / platform docs the tool integrates with
• Adjacent tools or alternatives in the same ecosystem
• Open-source repos doing similar things

Tier 4 — Ask the user (last resort, and only with structure): Only ask the user about something after Tiers 1–3 have been checked and came up empty. When you do ask, batch the gaps into one AskUserQuestion call rather than pinging them repeatedly. Frame each question as "I couldn't find X in [places checked] — is it Y, Z, or something else?" so the user sees you did the work.

Track provenance as you go. For every significant fact you gather, note where it came from — that becomes {{CHARTER_SOURCES}} in tool-charter.md and helps future agents (and the user) trace back why something is asserted. Example: "Built to wrap GTM Container API — see /04-research/gtm-api-notes.md".

Step 3: Propose a draft understanding for the user to confirm

Before writing anything authoritative into CLAUDE.md or the 01-context/ files, produce a short "here's what I think I know" summary for the user. Include:

• The one-paragraph project description you'd put in CLAUDE.md
• Current status bullets as you understand them
• Any project-specific guardrails you inferred
• A list of gaps where you're still guessing, and what you'd put in each

The user confirms, corrects, or fills gaps. Only then do you commit content to files. This prevents the agent from hard-coding a wrong understanding across multiple files that the user then has to untangle.

Step 4: Show the user the plan

Before making any changes to files, tell the user:

• What you'll create (new files, empty subfolders with .gitkeep)
• What you'll modify (surgical additions to existing files)
• What you'll leave untouched

Wait for the user's confirmation before proceeding.

Step 5: Create missing files and folders

For each missing file, copy from the template and then fill placeholders using the understanding the user confirmed in Step 3. Leave TODO: markers only for things that remained genuinely unknown after Tiers 1–4 and the draft-understanding review.

About the new and contextual files:

• 01-context/state.md — always create if missing. This is the central piece of the iterative-memory upgrade. If you can build a real state from existing artifacts (recent commits, last few activity-log entries, contents of an active 02-deliverables/{slug}/ subfolder), do — that's effectively a reconcile pass folded into the retrofit. If nothing's in flight, leave the sections empty with headers in place.
• 01-context/insights.md — always create if missing. Fill the {{PROJECT_DISPLAY_NAME}} and {{LAST_UPDATED}} tokens. Seed {{INITIAL_INSIGHTS}} with any observations you gathered from Tier 1 mining. If nothing surfaced, leave it empty.
• 01-context/domain-context.md — only create if the tool plugs into a non-trivial ecosystem (vendor APIs with gotchas, platform conventions, open-source release context). If the tool is self-contained, do not create this file in retrofit. Ask the user if it's ambiguous.

For missing subfolders, create them with a .gitkeep.

For the missing .claude/ setup, copy over .claude/commands/ (including checkpoint.md), .claude/rules/ (including iterative-memory.md), and .claude/skills/project-setup/ from the template. Also copy .cursor/rules/iterative-memory.mdc. These don't contain placeholders, so no filling needed.

Step 6: Surgical additions to existing files

For an existing CLAUDE.md:

• If it has the old "Cross-Surface Continuity — Read This" section (session-end-discipline language), replace it with the new "Iterative Memory — Update As You Go" section from the template. Leave everything else in CLAUDE.md alone.
• If it has neither section, insert the new "Iterative Memory — Update As You Go" section after the "How to Get Oriented on Specific Topics" table and before "Voice and Tone for Any Content You Draft."
• Check whether the orientation table has rows for state.md, activity-log.md, and insights.md. Add any that are missing.
• Do not modify any other content.

For an existing README.md:

• Leave alone unless the user explicitly asks for a refresh.

For existing 01-context/*.md files:

• Leave alone. If any of them appear outdated but present, note that in the report — don't modify.

For existing subfolder READMEs:

• Leave alone.

Step 7: Seed the activity log with a retrofit entry

Append an entry to 01-context/activity-log.md that lists exactly what was added. Format per the template already in that file. Be specific: "Added state.md, added iterative-memory rule files, replaced Cross-Surface Continuity section in CLAUDE.md with Iterative Memory section, created /checkpoint command" — not "retrofitted to template."

Step 8: Refresh state.md

If you created or updated state.md, do one final pass to make sure it actually reflects the most recent commit, the active sub-pro

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: 16wells
• Source: 16wells/claude-project-setup
• License: MIT

Install and usage instructions live in the source repository linked above.