https://github.com/iammrcupp/claude-project-kit
Scaffolding for starting Claude-assisted projects — working-folder templates, auto-memory starters, and cross-project conventions.
https://github.com/iammrcupp/claude-project-kit
anthropic claude claude-code developer-experience project-management scaffolding templates
Last synced: 18 days ago
JSON representation
Scaffolding for starting Claude-assisted projects — working-folder templates, auto-memory starters, and cross-project conventions.
- Host: GitHub
- URL: https://github.com/iammrcupp/claude-project-kit
- Owner: IamMrCupp
- License: mit
- Created: 2026-04-22T05:46:16.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-30T06:51:33.000Z (about 2 months ago)
- Last Synced: 2026-04-30T07:20:44.652Z (about 2 months ago)
- Topics: anthropic, claude, claude-code, developer-experience, project-management, scaffolding, templates
- Language: Markdown
- Size: 326 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# Claude Project Framework
[](https://github.com/IamMrCupp/claude-project-kit/releases)
[](LICENSE)
[](#requirements)
A reusable scaffold for starting new projects with Claude. Battle-tested on real projects and generalized so it works for personal code, open-source, or work projects.
**Setup runs once, in ~30 seconds:**
**Every session after starts grounded — one line and Claude knows the project:**
> **Heads up — Claude state for a bootstrapped project lives in three places, none of them your repo:**
>
> ```
> ┌────────────────────┐ templates copied ┌──────────────────────┐
> │ Kit checkout │ ───────────────────▶ │ Working folder │
> │ (this repo) │ │ (per-project state) │
> │ templates/ │ │ CONTEXT.md │
> │ bootstrap.sh │ │ SESSION-LOG.md │
> │ docs │ │ plan.md, … │
> └────────────────────┘ └──────────────────────┘
> │ ▲
> │ memory seeded │ Claude reads
> ▼ │ each session
> ┌────────────────────────────────────────────────────────────┐
> │ Auto-memory │
> │ ~/.claude/projects//memory/ │
> │ (per-project preferences, persistent across sessions) │
> └────────────────────────────────────────────────────────────┘
> ```
>
> The kit never modifies your repo. All three locations are private and local.
## Contents
- [Quickstart](#quickstart)
- [Features](#features)
- [What this is / isn't](#what-this-is--isnt)
- [Why this works](#why-this-works)
- [The idea, in one paragraph](#the-idea-in-one-paragraph)
- [How to use](#how-to-use-new-or-existing-project)
- [The lifecycle](#the-lifecycle)
- [What's in here](#whats-in-here)
- [Requirements](#requirements)
- [Related docs](#related-docs)
- [Support](#support)
- [License](#license)
## Quickstart
```bash
git clone https://github.com/IamMrCupp/claude-project-kit ~/Code/claude-project-kit
cd # the project you want to bootstrap
~/Code/claude-project-kit/bootstrap.sh # interactive — asks you everything
```
That kicks off interactive mode: it asks for the working-folder path, project name, issue tracker, and CI tool, then seeds everything in one pass. Full walkthrough in [SETUP.md](SETUP.md). Full flag list: `bootstrap.sh -h`.
## Features
- **Idempotent bootstrap** — write-once by default, with `--dry-run` (preview), `--force` (override the empty-folder check), `--skip-memory` (working folder only), and `--no-gitignore` (skip the `.gitignore` step).
- **Workspace mode** — `--workspace ` sets up a multi-repo initiative folder (workspace-CONTEXT.md + per-repo subfolders + shared `tickets/`). Detects Terraform / Terragrunt repos and prompts about sibling envs/modules repos.
- **Issue tracker awareness** — `--tracker {github,jira,linear,gitlab,shortcut,other,none}` seeds tracker-specific memory AND fills `{{TRACKER_TYPE}}` / `{{TRACKER_KEY}}` in `CONTEXT.md`. JIRA and Linear take a project / team key.
- **Per-ticket scratchpads** — `/pull-ticket ` slash command + `pull-ticket.sh` helper script fetch ticket data via tracker MCPs / CLIs and seed `tickets/-.md`. **Read-only** against the tracker — never creates, edits, transitions, or comments.
- **CI awareness** — `--ci {github-actions,gitlab-ci,jenkins,circleci,atlantis,ansible-cli,other,none}` seeds CI-specific memory.
- **Auto-memory seeding** — starter memory files for role, conventions, project context, and external references, with placeholder substitution from your repo (`{{PROJECT_NAME}}`, `{{REPO_SLUG}}`, etc.).
- **Phase-based planning docs** — `plan.md` + per-phase checklist + `implementation.md` give Claude scoped, numbered tasks instead of a wall of intent.
- **SEED-PROMPT auto-fill** — point Claude at one file and it deep-reads your repo, fills `CONTEXT.md`, drafts `research.md`, flags inferences, and stops for your review.
- **Starter agents** — `code-reviewer` (universal), `session-summarizer` (kit-aware), and `research-question` (universal, built for parallel fan-out), staged in the working folder; copy into your repo to activate.
- **Starter slash commands** — `/session-start`, `/session-verify`, `/refresh-context`, `/close-phase`, `/session-end`, `/session-handoff`, `/pull-ticket`, `/archive-ticket`, `/run-acceptance`, `/research`, `/plan`. Install once globally with `scripts/install-commands.sh --global` (recommended) or per-repo with `--project `.
- **Managed `.gitignore` block** — bootstrap appends a marker-bracketed block to `/.gitignore` covering `.claude/` (local-only Claude Code state), macOS junk (`.DS_Store` etc.), and editor / IDE files (`.vscode/`, `.idea/`, `*.swp`, ...). Idempotent on re-runs; opt out with `--no-gitignore`. Kit's stance: `.claude/` stays local to the user, never committed.
- **Upgrade helpers** — `scripts/sync-memory.sh`, `scripts/sync-templates.sh`, and `scripts/rename-workspace.sh` keep auto-memory, working-folder templates, and workspace paths in sync with the latest kit release without overwriting your filled-in content. See [SETUP.md §Upgrading](SETUP.md#upgrading-an-existing-project).
- **Worked examples** — `examples/widget-tracker/` (fictional Go CLI, single-repo, mid-Phase 1) and `examples/acme-platform/` (fictional Terraform multi-repo workspace, JIRA-driven, **long-running with multiple initiatives** — one completed, one active — plus `workspace-plan.md`, `workspace-phase-N-checklist.md`, and active + archived ticket scratchpads).
- **Conventions baseline** — Conventional Commits, merge-only PRs, ticket-driven branch / PR / commit shape, test-plan format, test-first where the code shape fits (apps / APIs / libraries — not IaC / scripts), etc. Read once, drop or keep per project.
- **No surprises** — MIT licensed, no telemetry. By default no network calls, and the only file bootstrap writes to your target repo is `.gitignore` (managed block, opt-out via `--no-gitignore`); everything else lands in the out-of-tree working folder. The sole opt-in exception is `--with-labels`, which calls `gh` to create a triage label scheme on a repo you own — off unless you pass it.
See [FEATURES.md](FEATURES.md) for one-paragraph-per-feature detail with example invocations.
## What this is / isn't
- **Is:** a workflow scaffold layered on top of Claude Code — templates, memory starters, conventions, three starter agents, eleven starter slash commands.
- **Isn't:** a Claude Code plugin, a replacement for `CLAUDE.md`, or a project tracker. It complements all three.
## Why this works
The templates aren't the point — what they do *to* Claude is:
- **External docs survive sessions.** `CONTEXT.md` and `SESSION-LOG.md` act as durable memory that persists across every new session. You stop re-explaining scope, decisions, and current status every time Claude starts fresh.
- **Auto-memory encodes preferences.** Commit style, PR conventions, merge strategy, test-plan expectations — all land in memory once and apply automatically. No "and remember to use merge commits" tacked onto every prompt.
- **Phase-based planning docs anchor the work.** `plan.md` + `phase-N-checklist.md` + `implementation.md` turn ambiguous goals into numbered, scoped tasks Claude can execute against, one branch at a time.
Net effect: prompts get more responsive and code output tightens up, because Claude spends fewer tokens figuring out what you want and more tokens doing it. The setup front-loads the context work so every subsequent prompt can be short.
## The idea, in one paragraph
Every project gets **two parallel sets of files**:
1. **A private AI working folder** (outside the repo) — the canonical source of truth across sessions. Holds `CONTEXT.md`, `SESSION-LOG.md`, plan docs, phase checklists.
2. **Auto-memory** at `~/.claude/projects//memory/` — durable facts about *you* and *how you want to work*: feedback, preferences, references, project context. One file per fact, indexed by `MEMORY.md`.
The working folder is project-specific knowledge ("what are we building, how far are we, what landed last week"). Auto-memory is cross-session behavior ("always use merge commits", "I prefer terse responses"). Neither is committed to the repo.
## How to use (new or existing project)
Works the same for greenfield repos and ones you're adopting it on mid-stream — the kit never modifies the target repo, it just creates an external working folder and seeds per-project auto-memory.
1. Read [SETUP.md](SETUP.md) — it walks you through the full bootstrap in ~10 minutes.
2. Pick a private working folder location (e.g. `~/Documents/Claude/Projects//`).
3. From your target repo root, run `bootstrap.sh` — either of:
- **Interactive (hand-held):** `bootstrap.sh` with no arguments prompts for working-folder path, project name, whether to seed auto-memory, your issue tracker (GitHub Issues / JIRA / Linear / GitLab / Shortcut / other / none), and your primary CI/automation tool (GitHub Actions / GitLab CI / Jenkins / CircleCI / Atlantis / Ansible CLI / other / none). For JIRA and Linear, it also prompts for the project or team key.
- **Non-interactive (scripted):** `bootstrap.sh [--tracker TYPE] [--jira-project KEY | --linear-team KEY] [--ci TYPE]` — see `bootstrap.sh -h` for the full flag list.
4. Open Claude Code in the target repo and say *"Follow the instructions in `/SEED-PROMPT.md`."* Claude deep-reads your repo, fills the templates, flags anything it inferred or can't derive, and stops for your review.
5. Answer Claude's questions, confirm the inferences, and start working. From the next session onward (once `reference_ai_working_folder.md` is in auto-memory, which bootstrap seeds for you), the daily-use prompt is just *"Load context and give me a 3-bullet summary of where we are."* — full prompt library, including the verbose first-session form and mid-PR resume, in [PROMPTS.md](PROMPTS.md).
## The lifecycle
```
bootstrap → seed prompt → first session → iterate → session-end → upgrade
(once) (once) (once) (loop) (each end) (per kit release)
```
- **Bootstrap** — once per project. Creates the working folder, seeds memory, drops `SEED-PROMPT.md`.
- **Seed prompt** — once, immediately after. Claude fills the templates, flags inferences, stops for review.
- **First session** — confirm inferences, start phase 0.
- **Iterate** — branch → commit → PR → merge → tick the checklist.
- **Session-end** — `SESSION-LOG.md` entry + `CONTEXT.md` status bump + checklist tick + memory pass. `/session-end` automates this.
- **Upgrade** — when the kit ships new templates / memory / commands, see [SETUP.md §Upgrading](SETUP.md#upgrading-an-existing-project).
## What's in here
File tree
```
.
├── README.md ← you are here
├── SETUP.md ← step-by-step: starting a new project
├── FEATURES.md ← feature-by-feature reference
├── CONVENTIONS.md ← generic working rules (commits, PRs, etc.)
├── STABILITY.md ← what 1.x promises not to break
├── PROMPTS.md ← ready-to-paste session-opening prompts
├── CHANGELOG.md ← what's landed; upgrade notes for existing adopters
├── CONTRIBUTING.md ← contributor onboarding
├── SECURITY.md ← reporting vulnerabilities
├── LICENSE
├── bootstrap.sh ← one-command setup (see SETUP.md step 2)
├── pull-ticket.sh ← terminal-driven /pull-ticket equivalent (read-only)
├── scripts/ ← post-bootstrap helpers (idempotent, write-once by default)
│ ├── install-commands.sh ← install slash commands + agents (--global | --project)
│ ├── sync-memory.sh ← copy any newly-shipped memory templates into existing auto-memory
│ ├── sync-templates.sh ← refresh working-folder / workspace templates without clobbering edits
│ └── rename-workspace.sh ← rename a workspace folder + rewrite path refs across auto-memory
├── docs/adr/ ← Architecture Decision Records (see README inside)
├── templates/ ← copied into a new working folder
│ ├── SEED-PROMPT.md ← instructions for Claude to auto-fill the rest
│ ├── CONTEXT.md
│ ├── SESSION-LOG.md
│ ├── plan.md
│ ├── implementation.md
│ ├── phase-N-checklist.md
│ ├── acceptance-test-results.md
│ ├── research.md
│ ├── workspace/ ← workspace-mode-only templates
│ │ ├── workspace-CONTEXT.md ← cross-repo overview (--workspace)
│ │ └── ticket.md ← per-ticket scratchpad shape
│ └── .claude/ ← starter agents + slash commands (staged in WF)
│ ├── agents/ ← code-reviewer, session-summarizer
│ ├── commands/ ← /session-start, /session-verify, /refresh-context, /close-phase, /session-end, /session-handoff, /pull-ticket, /run-acceptance, /research, /plan
│ └── README.md ← how to copy into your target repo
├── examples/ ← filled-in reference — read, don't copy
│ ├── widget-tracker/ ← fictional Go CLI, single-repo, mid-Phase-1 snapshot
│ └── acme-platform/ ← fictional Terraform multi-repo workspace + JIRA tickets
└── memory-templates/ ← starter auto-memory for a new project
├── MEMORY.md ← index of memory files
├── user_role.md ← who you are, how to calibrate
├── feedback_*.md ← rules & preferences (commits, PRs, CI, etc.)
├── project_*.md ← project context
├── reference_*.md ← external pointers (working folder, etc.)
├── trackers/ ← per-tracker reference memory (github / jira / linear / gitlab / shortcut / other)
└── ci/ ← per-CI reference memory (github-actions / gitlab-ci / jenkins / circleci / atlantis / ansible-cli / other)
```
## Requirements
- **Bash 3.2+** — the macOS default works.
- **git** — `git remote get-url origin` is used to derive `{{REPO_SLUG}}`. Bootstrap still runs without it; you'll fill that placeholder by hand.
- **Claude Code CLI** — [install instructions](https://docs.claude.com/en/docs/claude-code).
- **Tested on:** macOS and Linux. Should work on WSL2; not currently tested on native Windows.
## Related docs
| Doc | What it covers |
|---|---|
| [SETUP.md](SETUP.md) | Full bootstrap walkthrough (interactive + scripted), upgrade flow, manual alternative, troubleshooting |
| [FEATURES.md](FEATURES.md) | Feature-by-feature reference with example invocations |
| [PROMPTS.md](PROMPTS.md) | Session-opening / session-end prompt library |
| [CONVENTIONS.md](CONVENTIONS.md) | Commit / PR / CI rules the kit assumes |
| [STABILITY.md](STABILITY.md) | What `1.x` promises not to break, and what can change in any release |
| [CHANGELOG.md](CHANGELOG.md) | What's shipped, with **For existing adopters** notes per release |
| [CONTRIBUTING.md](CONTRIBUTING.md) | Adding tracker / CI variants, running the Bats suite, PR shape |
| [SECURITY.md](SECURITY.md) | Vulnerability reporting |
| [docs/adr/](docs/adr/) | Architecture Decision Records — why the kit's structural decisions look the way they do |
## When to update this framework
Treat this kit as a living template. If a pattern or rule proves useful on a real project, fold it back in here so future projects start ahead. Conversely, if something in here turns out to be dead weight, prune it.
## Scope & assumptions
The conventions and tooling notes are written assuming **Git + GitHub + GitHub Actions**. They translate cleanly to GitLab (MRs, `glab ci`, pipelines), Jenkins, Azure DevOps, etc. — adapt the specifics, keep the principles.
## Support
If this kit saved you time and you'd like to throw a coffee my way:
- [ko-fi.com/iammrcupp](https://ko-fi.com/iammrcupp)
- [buymeacoffee.com/iammrcupp](https://buymeacoffee.com/iammrcupp)
No pressure — the kit's MIT-licensed and will stay that way regardless.
## License
MIT — see [LICENSE](LICENSE). Use it, fork it, strip out what doesn't fit your context.