project-starter

A Claude Code project scaffold that gives the agent complete, non-conflicting context from the first session — and keeps it from drifting across sessions. Works for full-stack web projects and CLI / no-UI projects alike.

It is built on three layers:

Layer	File(s)	When it loads	Cost
Always-on brain	CLAUDE.md	Every message	Small (keep it < 200 lines)
On-demand specs	context/*.md	Read at session start	Loaded deliberately
Path-scoped rules	.claude/rules/*.md	Only when a matching file is open	Zero unless relevant

Plus hooks for hard enforcement (typecheck on every TS edit, block credential leaks in shell commands) and the JSM Agent Skills (/architect, /remember, /review, /recover, /imprint) for the session workflow.

---

Start a new project

git clone https://github.com/FriedDev/project-starter.git my-new-project
cd my-new-project
bash setup.sh

setup.sh does four things:

1. Installs the skills — npx skills@latest add JavaScript-Mastery-Pro/skills (this is why the repo itself ships no skill files — see "How skills work" below).
2. Wires the symlinks — Claude Code discovers skills in .claude/skills/, but the installer writes them to .agents/skills/. The script symlinks one to the other.
3. Makes the hooks executable — chmod +x .claude/hooks/*.sh.
4. Resets git — deletes the starter's history and runs git init so your project starts clean. Pass bash setup.sh --keep-git to skip this.

Requires Node.js (for npx) and network access on first run. If npx is missing, the script tells you exactly what to run later — everything else still completes.

After setup, fill in the context/ files and edit CLAUDE.md, then open Claude Code.

---

How skills work (read this if /architect is missing)

The skills are not committed to this repo. They are installed at setup time so you always get the latest version. This means:

• A fresh git clone has empty .agents/skills/ and .claude/skills/. That is expected.
• The skills only exist after you run bash setup.sh.
• .agents/ and .claude/skills/ are gitignored, so they never get committed back.

If /architect, /remember, /review, /recover, or /imprint aren't available in Claude Code, you haven't run setup.sh yet — or the npx step failed. Re-run:

npx skills@latest add JavaScript-Mastery-Pro/skills
bash setup.sh   # re-wires symlinks idempotently

---

What's in the box

CLAUDE.md                 always-loaded brain — session bootstrap + non-negotiable rules
setup.sh                  one-time setup (run after clone)
README.md                 this file
.gitignore                excludes memory, secrets, node_modules, and the installed skills

context/
  project-overview.md     what the project is and does            (fill in)
  architecture.md         stack, folders, system boundaries, schema (fill in)
  code-standards.md       TypeScript + patterns (web section is deletable for CLI projects)
  library-docs.md         how each third-party library is used here (fill in)
  build-plan.md           phased feature list                      (fill in)
  progress-tracker.md     living status — read LAST every session  (fill in as you go)

.claude/
  settings.json           permissions allowlist + hook wiring (portable, no hardcoded paths)
  hooks/
    typecheck-on-edit.sh  runs `npm run typecheck` after any .ts/.tsx edit
    block-credential-leak.sh  blocks shell commands with inline secrets
  rules/
    core-code.md          UNIVERSAL — fires for src/ cli/ commands/ lib/ agent/   (keep always)
    agent-code.md         agent/AI logic rules
    components.md         web only — React components
    api-routes.md         web only — app/api route handlers
    server-actions.md     web only — actions/

memory/
  MEMORY.md               auto-memory index (gitignored beyond this seed)

---

Web project vs CLI / no-UI project

The scaffold is the same; you delete what doesn't apply.

• Web (Next.js) project — keep everything as-is.
• CLI / no-UI project:
  • Delete .claude/rules/components.md, api-routes.md, server-actions.md.
  • Delete the # Web (Next.js) section of context/code-standards.md (it's fenced with clear start/end markers).
  • Keep core-code.md — it covers src/, cli/, commands/, lib/ with stack-neutral rules.

The template note at the top of CLAUDE.md says the same thing, so the agent sees it too.

---

Session workflow

When	Run
Start of session (continuing work)	/remember restore
Before any complex feature	/architect
After any feature	/review
Broken after one fix attempt	/recover
End of session	/remember save

New session with no prior save: read CLAUDE.md, then all context/ files in order, ending with progress-tracker.md.

---

Updating the starter itself

This repo is the source of truth for the pattern. To improve it: clone with --keep-git (bash setup.sh --keep-git), make changes, and push back to project-starter. Don't commit installed skills, memory.md, or secrets — .gitignore already blocks them.