Skip to content
Back to search

project-butler

SkillWorks with Claude CodeGitHub

"Project memory workflow for init/upgrade, profile-aware setup, end session, normal/full close, file organization, document archiving, language switching, versioned update logs, rule review, status, wiki sync, and context recovery. Use for /project-butler, setup/初始化, foundation setup, profile setup, end session/收工, normal close, full close, foundation repair, organize files/整理文件, change language/切换语言, continue/接着上次, continue full context/全面回顾, review claude, sync wiki, status. Maintains project memory files. Runs version freshness check before trigger routing."

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jamesshi96--project-butler/badge.svg)](/listings/jamesshi96--project-butler)

HTML

<a href="/listings/jamesshi96--project-butler"><img src="/api/listings/jamesshi96--project-butler/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Install as a Claude Code skill:

git clone https://github.com/JamesShi96/project-butler.git ~/.claude/skills/project-butler

Open any project and set up project memory:

/project-butler

Work normally. At the end of a work session:

end session

Next time, resume without re-explaining the project:

continue

That is enough for daily use. For Cursor, Codex, and other assistants, see [Tool Compatibility](docs/compatibility.md).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 341 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: project-butler
  3. description: "Project memory workflow for init/upgrade, profile-aware setup, end session, normal/full close, file organization, document archiving, language switching, versioned update logs, rule review, status, wiki sync, and context recovery. Use for /project-butler, setup/初始化, foundation setup, profile setup, end session/收工, normal close, full close, foundation repair, organize files/整理文件, change language/切换语言, continue/接着上次, continue full context/全面回顾, review claude, sync wiki, status. Maintains project memory files. Runs version freshness check before trigger routing."
  4. ---
  5. # Project Butler — Project Memory Stack
  6. Initialize standardized project memory:
  7. ```
  8. 上层(稳定原则)
  9. ┌─────────────────────────────────────┐
  10. │ CLAUDE.md(项目宪法)← 人工确认 │
  11. │ ↑ candidates(AI 自动收集候选) │
  12. └─────────────────────────────────────┘
  13. ↑ 抽象沉淀
  14. 中层(当前快照)
  15. ┌─────────────────────────────────────┐
  16. │ PROJECT.md(项目 Wiki)← AI 自动同步 │
  17. │ 概览 / 结构 / 模块状态 / 文件索引 │
  18. │ STRUCTURE.md(文件管理规则)← AI 自动│
  19. │ 目录规则 / 匹配条件 / 整理历史 │
  20. │ UPDATE_LOG.md(里程碑变化)← AI 自动 │
  21. │ DOCS.md(文档索引 + 元数据)← AI 自动 │
  22. │ .claude/project-profile.json(画像配置)│
  23. │ .claude/profile-pending.json(画像待处理)│
  24. └─────────────────────────────────────┘
  25. ↑ 状态汇总
  26. 下层(事实流水)
  27. ┌────────────────────┐ ┌────────────────────┐
  28. │ log/(会话日志) │ │ TODO.md(执行清单)│
  29. │ raw + summaries │ │ owner/deadline/ │
  30. │ + archive(分级) │ │ deps │
  31. └────────────────────┘ └────────────────────┘
  32. ↓
  33. session-handoff.md(下次接手点)
  34. ```
  35. Core idea: bottom feeds top, top constrains bottom. Logs and TODOs are raw facts. Handoff marks the next resume point. Wiki is the current snapshot. Structure manages file organization. Docs index manages document output. Update Log records versioned milestone changes. Constitution is stable principles.
  36. Supports 3 language modes: English (`en`), Chinese (`zh`), or bilingual. All content adapts to the selected language.
  37. ---
  38. ## Step -1: Version Freshness Check (always run first)
  39. <EXTREMELY_IMPORTANT>
  40. Before any other step, read `references/update-check.md` and execute
  41. the version freshness check described there.
  42. - If the check prints nothing → continue to Step 0 silently.
  43. - If the check prints a `VERSION_NOTICE:` block → do NOT print it
  44. verbatim. Instead present ONE interactive update prompt with
  45. AskUserQuestion, worded in the project's CLAUDE.md language:
  46. - Question: "project-butler is N commits behind upstream. Update now?"
  47. (read N from the `VERSION_NOTICE:` line).
  48. - Option "Update now" → run
  49. `bash "<SKILL_DIR>/scripts/check-update.sh" --pull "<SKILL_DIR>"`
  50. as a single Bash call, then report its `UPDATE_OK` / `UPDATE_FAILED`
  51. output to the user.
  52. - Option "Remind me later" → do nothing; the script throttles the
  53. prompt to at most once per 24h, so it will not ask again today.
  54. - Option "Stop reminding" → tell the user to set
  55. `PROJECT_BUTLER_NO_UPDATE_CHECK=1` to silence permanently.
  56. Present this prompt once, before the triggered work. The script already
  57. limits it to once per 24h, so do not add your own suppression.
  58. - Never run `git pull` on the skill directory yourself EXCEPT as the
  59. "Update now" action the user explicitly selected (which runs the
  60. `--pull` subcommand above).
  61. - If you cannot find the "Base directory for this skill: <path>" line
  62. in the current skill loading prompt, skip the check silently and
  63. continue to Step 0.
  64. </EXTREMELY_IMPORTANT>
  65. ---
  66. ## Step 0: Trigger Routing
  67. Determine how this skill was triggered:
  68. **A. "整理文件" / "organize files":**
  69. 1. Read `references/file-reorganization.md`
  70. 2. Execute **Mode A: Four-Phase Organize** (Discover → Ask or Plan → Plan → Execute)
  71. 3. Report and stop
  72. **B. "收工" / "end session" / "结束会话" / "we're done" / "wrap up" / "done for today" / "normal close" / "full close":**
  73. 1. Execute the **End Session Flow** below (inline)
  74. 2. Report and stop
  75. **C. Initialization (/project-butler, 初始化项目, setup project, etc.):**
  76. → Continue to **Init Flow** below
  77. **D. "切换语言" / "change language":**
  78. 1. Read `references/language-change.md` + `references/language-adaptation.md`
  79. 2. Execute the Language Change Protocol
  80. 3. Report and stop
  81. **E. "continue" / "接着上次" / "上次做到哪了":**
  82. 1. Read `references/continue.md`
  83. 2. Execute the Continue process (recover last session context)
  84. 3. Report and stop
  85. **F. "continue full context" / "全面回顾" / "项目全景" / "full context":**
  86. 1. Read `references/continue-full-context.md`
  87. 2. Execute the Continue Full Context process (full project trajectory recovery)
  88. 3. Report and stop
  89. **G. "review claude" / "审查规则" / "更新宪法" / "check the rules":**
  90. 1. Read `.claude/candidates.md`
  91. 2. Present pending candidates one by one for accept / reject / rewrite
  92. 3. For accepted or rewritten candidates, append to CLAUDE.md only after explicit user confirmation
  93. 4. Move processed candidates to adopted or rejected sections in `.claude/candidates.md`
  94. 5. Report and stop
  95. **H. "sync wiki" / "同步项目" / "update overview" / "refresh overview":**
  96. 1. Read PROJECT.md, STRUCTURE.md, UPDATE_LOG.md, DOCS.md, TODO.md, and session-handoff.md if present
  97. 2. Rescan current project files and update PROJECT.md current snapshot, module map, file structure, key file index, links, and progress sections
  98. 3. Preserve user-authored content where possible
  99. 4. Report and stop
  100. **I. "status" / "项目现状" / "where are we":**
  101. 1. Read PROJECT.md and session-handoff.md
  102. 2. Also read TODO.md and latest UPDATE_LOG.md entry if present
  103. 3. If `.claude/project-profile.json` or `.claude/profile-pending.json` exists, read `references/project-profile-system.md` and include profile debt / review queue in the dashboard
  104. 4. Present a compact project dashboard in the configured language: Project, Active Work, Recent Change, Profile, Next Best Step
  105. 5. Report and stop
  106. **J. "foundation setup" / "profile setup" / "foundation repair" / "profile repair" / "profile sync":**
  107. 1. Read `references/project-profile-system.md`
  108. 2. Execute the matching Profile System flow
  109. 3. Report and stop
  110. ---
  111. ## End Session Flow
  112. When triggered by "end session" / "结束会话" / "收工" / "we're done" / "wrap up" / "done for today" / "normal close" / "full close", execute in order:
  113. 1. **Write session log** → `log/session-YYYY-MM-DD-{slug}.md`
  114. - Same-day multiple sessions: use slug to distinguish (e.g., `session-2026-04-21-prd-draft.md`)
  115. - Format: see Session Log Format below
  116. 2. **Log Compaction** → if unarchived raw logs ≥ threshold (default 10, configured in CLAUDE.md):
  117. read `references/log-compaction.md` and execute
  118. 3. **Update session-handoff.md** → refresh "current progress" and "next steps"
  119. 4. **Update PROJECT.md** → if structure/module status changed
  120. 5. **Update TODO.md** → mark completed tasks
  121. 6. **Collect constitution candidates** → append to `.claude/candidates.md` (see rules below)
  122. 7. **Profile impact scan** → if `.claude/project-profile.json` exists, `.claude/profile-pending.json` exists, or the user explicitly requested Normal Close / Full Close / profile sync:
  123. - Read `references/project-profile-system.md`
  124. - Run the Profile-Aware End Session flow
  125. - For Normal Close: record profile-impacting changes in `.claude/profile-pending.json`
  126. - For Full Close: produce a Scope Plan before changing profile docs
  127. - Do not rewrite protected sections, document policies, or stable baselines without explicit confirmation
  128. 8. **File reorganization (incremental)** → read `references/file-reorganization.md`, execute Mode B
  129. - If STRUCTURE.md missing: execute Mode A first to establish baseline
  130. - Update `.claude/.file-snapshot.json`
  131. 9. **Document archiving** → read `references/document-archiving.md`, scan and archive document output
  132. - Identify documents created/modified this session
  133. - Classify by type, archive to `docs/` subdirectories
  134. - Update `DOCS.md` index and metadata
  135. - If DOCS.md missing: create it (upgrade compatibility)
  136. 10. **Evaluate & write update log** → read `references/update-log.md`
  137. - Evaluate session significance
  138. - If significant: determine bump level (major/minor/patch), calculate new version from UPDATE_LOG.md metadata, prepend versioned entry
  139. - Optionally offer GitHub Release creation
  140. - If not significant, skip silently
  141. 11. **Output summary** → result-focused summary in the configured language (check CLAUDE.md Language setting)
  142. ### User-Facing Output Style
  143. After `end session`, summarize outcomes instead of listing internal protocol steps:
  144. ```text
  145. Session saved.
  146. Updated:
  147. - Handoff refreshed
  148. - TODO updated: {done count} done, {active count} active
  149. - Project wiki synced
  150. - Profile: {normal close / full close / no profile impact / profile pending count}
  151. - Documents archived: {count}
  152. - Update log: {version added or skipped}
  153. Next:
  154. - {next action}
  155. - {next action}
  156. ```
  157. Omit lines that do not apply. For `status`, answer as a compact dashboard:
  158. ```text
  159. Current Status
  160. Project:
  161. - Stage: {stage}
  162. - Focus: {current focus}
  163. Active Work:
  164. - {active item}
  165. Recent Change:
  166. - {latest update log entry or "No milestone update yet"}
  167. Profile:
  168. - {profile shape / pending debt / review needed, only when profile files exist}
  169. Next Best Step:
  170. - {single recommended next step}
  171. ```
  172. ### Session Log Format
  173. Session log headers adapt to the configured language (read `references/language-adaptation.md` for glossary).
  174. ```markdown
  175. # Session YYYY-MM-DD — {topic}
  176. ## Session Goal
  177. ## Key Actions (Chronological)
  178. ## Decisions & Rationale
  179. ## Output Files
  180. ## Unfinished Items / Next Session Pickup
  181. ## CLAUDE.md Candidates (if any)
  182. ```
  183. ### Constitution Candidate Rules
  184. AI automatically appends to `.claude/candidates.md` when:
  185. - User explicitly says "always do this" / "this is a rule" / "don't ever..."
  186. - Same decision appears across multiple sessions
  187. - Decision involves naming conventions, file structure, collaboration flow
  188. - Decision involves tech stack or architecture constraints
  189. **Never promote candidates into CLAUDE.md automatically.** All candidates require explicit user review via "review claude" before CLAUDE.md is changed.
  190. ### TODO Format
  191. Each task in TODO.md must include:
  192. ```
  193. - [ ] {task description}
  194. Owner: {name} | Deadline: {date} | Dependencies: {prerequisite}
  195. ```
  196. If user provides a task missing required fields, ask them to fill in. Completed tasks are checked and kept (not deleted).
  197. ---
  198. ## Init Flow
  199. ### Step 1: Detect Mode
  200. Scan project root for: CLAUDE.md, PROJECT.md, session-handoff.md, TODO.md, log/, STRUCTURE.md, UPDATE_LOG.md, DOCS.md, docs/, .claude/.file-snapshot.json, .claude/candidates.md, .claude/project-profile.json, .claude/profile-pending.json
  201. - **Fresh**: None exist → read `references/project-profile-system.md` and run Foundation Setup as the default setup path. Create the base 7-component memory stack, `.claude/project-profile.json`, `.claude/profile-pending.json`, and only the user-confirmed baseline docs. For lightweight projects, use `maintenance.preference = "lightweight"` and keep Required docs minimal instead of skipping profile state.
  202. - **Upgrade**: Some exist → read `references/upgrade-mode.md`; if profile files are missing, also read `references/project-profile-system.md` and offer profile-aware upgrade using the latest Foundation Setup model
  203. - **Profile files present**: profile files exist → preserve existing profile state and patch only schema-compatible missing fields
  204. ### Step 2: Ask Questions
  205. For Fresh initialization, follow Foundation Setup in `references/project-profile-system.md`: ask for the required setup basics, ask for a natural project description, infer the project shape, generate project-specific foundation areas, ask only targeted follow-up questions, and propose Required / Recommended / Optional documents before file creation.
  206. AskUserQuestion should still keep setup lightweight. Make clear that the user can press Enter for recommended defaults.
  207. Required:
  208. 1. **项目名称** — e.g., "达人营销AI", "Data Pipeline"
  209. 2. **一句话定义** — e.g., "AI-powered influencer marketing platform for US/EU markets"
  210. 3. **当前阶段** — e.g., "v1 MVP", "规划中", "已上线"
  211. Recommended defaults:
  212. 4. **GitHub 仓库** — optional, e.g., "org/repo-name" (default empty)
  213. 5. **是否创建 Cursor 规则文件** — yes/no (default yes)
  214. 6. **是否创建 Codex AGENTS.md** — yes/no (default no)
  215. 7. **语言 / Language** — `en` / `zh` / `bilingual` (default bilingual)
  216. 8. **版本命名方式** — choose one (default AI recommendation, fallback Semantic)
  217. 预设选项:Semantic (v0.1.0) / Codename ({project name} 0.1) / Patch (Patch 1) / Date (2026.06.1)
  218. AI 根据项目类型推荐:产品/品牌类→Codename / 游戏/内容类→Patch / 日志/研究类→Date / 默认→Semantic
  219. ### Step 3: Create Files
  220. Read `references/file-templates.md` + `references/language-adaptation.md` + `references/document-archiving.md` + `references/project-profile-system.md`.
  221. Create each file using templates, replacing `{{VARIABLES}}` with user answers. For UPDATE_LOG.md, calculate the initial version based on the version style selection and current date (e.g., semantic → `v0.1.0`, date → `2026.06.1`). Apply language adaptation rules and glossary from the reference.
  222. Create `log/.gitkeep` (empty file) alongside `log/` directory so git tracks it when empty.
  223. Create `.claude/.file-snapshot.json` with empty content: `{"lastScan":"","files":{}}`.
  224. Create `.claude/project-profile.json`, `.claude/profile-pending.json`, and confirmed Required profile baseline docs from the approved Foundation Setup proposal.
  225. If the user enabled Cursor support, create `.cursor/rules/project-system.mdc` from Template 6.
  226. If the user enabled Codex support, create `AGENTS.md` from Template 6b. If `AGENTS.md` already exists, do not overwrite it; offer to append the project-butler section after confirmation.
  227. ### Step 4: Output Report
  228. Adapt this report to the configured language:
  229. ```
  230. Project memory is ready.
  231. Daily commands:
  232. - end session — save progress and next steps
  233. - continue — resume next time
  234. - status — check current state
  235. Advanced:
  236. - review claude — approve long-term rules when needed
  237. Created:
  238. - Project memory and handoff notes
  239. - TODO tracking
  240. - Document index
  241. - Update log
  242. - Profile config and pending queue: created
  243. - File organization rules
  244. - Cursor rules: created / skipped
  245. - Codex AGENTS.md: created / skipped
  246. Settings:
  247. - Language: {{LANGUAGE}}
  248. - Version style: {{VERSION_STYLE}} (starting: {{VERSION_INITIAL}})
  249. ```
  250. ---
  251. ## Reference Loading
  252. | Trigger | Read these files |
  253. |---------|-----------------|
  254. | Init (fresh) | `references/file-templates.md` + `references/language-adaptation.md` + `references/document-archiving.md` + `references/project-profile-system.md` |
  255. | Init (upgrade) | above + `references/upgrade-mode.md`; include `references/project-profile-system.md` when creating, repairing, or preserving profile files |
  256. | End session | `references/file-reorganization.md` + `references/document-archiving.md` + `references/update-log.md` + `references/log-compaction.md` (if logs ≥ threshold); include `references/project-profile-system.md` when profile files exist or Normal/Full Close is requested |
  257. | 整理文件 / organize files | `references/file-reorganization.md` |
  258. | 切换语言 / change language | `references/language-change.md` + `references/language-adaptation.md` |
  259. | continue / 接着上次 | `references/continue.md` |
  260. | continue full context / 全面回顾 | `references/continue-full-context.md` |
  261. | review claude / 审查规则 | Inline workflow in Step 0 |
  262. | sync wiki / 同步项目 | Inline workflow in Step 0 |
  263. | status / 项目现状 | Inline workflow in Step 0; include `references/project-profile-system.md` when profile files exist |
  264. | profile setup / full close / foundation repair | `references/project-profile-system.md` |
README.md · README · 349 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # project-butler
  2. **[English](README.md)** | [中文](README_zh.md)
  3. [![GitHub stars](https://img.shields.io/github/stars/JamesShi96/project-butler?style=social)](https://github.com/JamesShi96/project-butler/stargazers)
  4. [![GitHub release](https://img.shields.io/github/v/release/JamesShi96/project-butler?display_name=tag)](https://github.com/JamesShi96/project-butler/releases)
  5. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
  6. [![AI Coding Assistants](https://img.shields.io/badge/AI%20Coding%20Assistants-Claude%20Code%20%7C%20Cursor%20%7C%20Codex-6B46C1)](docs/compatibility.md)
  7. > Make AI coding agents remember your project between sessions.
  8. project-butler helps Claude Code, Cursor, Codex, and similar AI coding assistants behave like long-term project teammates instead of starting from scratch every session.
  9. For normal use, you only need four actions:
  10. ```text
  11. /project-butler Set up project memory
  12. end session Save progress and next steps
  13. continue Resume next time
  14. status Check where the project stands
  15. ```
  16. For projects that need stronger product, architecture, roadmap, research, or eval alignment, project-butler can also create a Project Profile during setup and offer profile-aware Normal Close / Full Close behavior.
  17. ## Quick Start
  18. Install as a Claude Code skill:
  19. ```bash
  20. git clone https://github.com/JamesShi96/project-butler.git ~/.claude/skills/project-butler
  21. ```
  22. Open any project and set up project memory:
  23. ```text
  24. /project-butler
  25. ```
  26. Work normally. At the end of a work session:
  27. ```text
  28. end session
  29. ```
  30. Next time, resume without re-explaining the project:
  31. ```text
  32. continue
  33. ```
  34. That is enough for daily use. For Cursor, Codex, and other assistants, see [Tool Compatibility](docs/compatibility.md).
  35. ## Updating project-butler
  36. The skill auto-checks for updates on every invocation. Once per day per
  37. machine, it runs `git fetch` against its own repo and compares local
  38. `HEAD` to `origin/main`. If behind, Claude Code asks you once — and at
  39. most once every 24 hours:
  40. ```
  41. project-butler is 3 commits behind upstream. Update now?
  42. › Update now — pull the latest version right here
  43. › Remind me later — ask again tomorrow
  44. › Stop reminding — turn the check off
  45. ```
  46. Picking **Update now** runs a fast-forward-only `git pull` for you and
  47. reports the result. If it fails (local changes, offline, SSH blocked),
  48. you get the manual command plus an HTTPS fallback. Nothing is ever
  49. pulled without you choosing it.
  50. The prompt is worded in your project's CLAUDE.md `Language:` setting
  51. (English / Chinese / bilingual), and stops appearing once you are up to
  52. date — the cache is keyed on commit SHA, not just time.
  53. **Side effect on `git status`**: after the auto-fetch, `git status`
  54. inside the skill directory may show "behind origin/main by N commits".
  55. This is expected and harmless — the skill never modifies the working
  56. tree unless you pick "Update now".
  57. **Silencing**: `export PROJECT_BUTLER_NO_UPDATE_CHECK=1`. Only the
  58. literal value `"1"` silences — `=0`, `=false`, or empty does **not**
  59. silence (counter-intuitive but intentional).
  60. **Note**: the check runs as a skill instruction, so it is best-effort —
  61. it may occasionally not fire. Run the script manually any time you want
  62. a definitive answer.
  63. **Debugging a missing prompt**: from an external shell only, run the
  64. shared update-check script with
  65. `PROJECT_BUTLER_UPDATE_CHECK_DEBUG=1`. Never enable debug inside
  66. Claude Code — CC captures stderr into the LLM context and debug output
  67. will leak into responses.
  68. **Cursor / Codex**: these tools do not have Claude Code's skill
  69. lifecycle, so update checks are manual/on-demand:
  70. ```bash
  71. bash "${PROJECT_BUTLER_SKILL_DIR:-$HOME/.claude/skills/project-butler}/scripts/check-update.sh"
  72. ```
  73. Outside Claude Code there is no prompt — the script just prints a
  74. `VERSION_NOTICE:` block with the update command when you are behind, and
  75. nothing when you are current.
  76. **Reach limitation**: if you installed project-butler before v1.7.0,
  77. you do not have this auto-check feature yet. Pull once manually:
  78. ```bash
  79. cd ~/.claude/skills/project-butler && git pull
  80. ```
  81. After that, future updates are announced automatically.
  82. ## Why It Exists
  83. AI coding assistants are powerful in one session and forgetful across sessions. If any of these sound familiar, project-butler is for you:
  84. - **"I had to re-explain the architecture again."** Each new session starts with missing context.
  85. - **"What did we decide about naming conventions last week?"** Decisions disappear into chat history.
  86. - **"The README and TODOs keep drifting from reality."** Project state stops matching the files.
  87. - **"The AI keeps violating rules I already explained."** Rules live in your head instead of in project memory.
  88. - **"I switch between Claude Code, Cursor, and Codex."** Different tools need one shared source of truth.
  89. project-butler turns a project folder into that source of truth, so the next AI session can pick up where the last one stopped.
  90. ## Main Commands
  91. All triggers are natural language. Use slash commands only for first-time setup.
  92. | Command | Use it when |
  93. |---|---|
  94. | `/project-butler` | Set up or upgrade project memory. |
  95. | `end session` / `we're done` | Save progress, refresh next steps, and record important changes. |
  96. | `continue` / `continue from last time` | Resume the previous session without re-explaining context. |
  97. | `status` / `where are we` | Get the current project state and the next best step. |
  98. ## Advanced Commands
  99. | Command | Use it when |
  100. |---|---|
  101. | `continue full context` | Rebuild the full project trajectory after a long break or assistant switch. |
  102. | `review claude` / `check the rules` | Review candidate project rules before they become long-term rules. |
  103. | `sync wiki` / `update overview` | Force-refresh `PROJECT.md`. |
  104. | `organize files` | Clean up new files according to `STRUCTURE.md`. |
  105. | `change language` | Switch project management files between English, Chinese, and bilingual mode. |
  106. | `normal close` | Save the session and defer profile-impacting updates into the pending queue. |
  107. | `full close` | Align affected profile docs now with a bounded Scope Plan. |
  108. | `profile setup` / `foundation repair` | Create or repair the project profile and baseline reference docs after confirmation. |
  109. Session recovery (`continue` / `continue full context`) is routed through project-butler internally. There is no separate `/continue` command to install.
  110. ## What It Maintains
  111. Run `/project-butler` once. It maintains these plain Markdown files in your project:
  112. ```text
  113. project-root/
  114. ├── CLAUDE.md <- Project rules / constitution
  115. ├── PROJECT.md <- Current project wiki
  116. ├── STRUCTURE.md <- File organization rules
  117. ├── UPDATE_LOG.md <- Milestone-level changelog
  118. ├── DOCS.md <- Document index and metadata
  119. ├── session-handoff.md <- Cross-session handoff
  120. ├── TODO.md <- Execution checklist
  121. ├── docs/ <- Archived project documents
  122. ├── log/ <- Session logs
  123. └── .claude/
  124. ├── candidates.md <- Candidate rules for review
  125. ├── project-profile.json <- Project profile config
  126. ├── profile-pending.json <- Profile pending/debt queue
  127. └── .file-snapshot.json <- File organization snapshot
  128. ```
  129. The core files are plain Markdown, so other tools can read them even when they do not run the skill natively.
  130. What that means in practice:
  131. - Keeps the current project state readable.
  132. - Keeps next steps clear between sessions.
  133. - Keeps project documents indexed and findable.
  134. - Records milestone changes so the project has a clear history.
  135. - Keeps new files from drifting into random folders.
  136. - Preserves long-term rules only after user review.
  137. Project Butler also keeps a small machine-readable profile so the assistant can understand which long-lived docs matter, which sections are protected, and which profile updates have been deferred.
  138. ## Tool Support
  139. | Tool | Status | How it works |
  140. |---|---|---|
  141. | Claude Code | Native skill | Install this repo under `~/.claude/skills/project-butler` and run `/project-butler`. |
  142. | Cursor | Project rules, best-effort | project-butler can generate `.cursor/rules/project-system.mdc`, which points Cursor at the same project memory files and mirrors the main triggers. |
  143. | Codex | `AGENTS.md`, best-effort | project-butler can generate `AGENTS.md`, which points Codex at the same project memory files and mirrors the main triggers. |
  144. | Other AI assistants | File-based | Any assistant that can read project files can use the project memory as shared context. |
  145. See [docs/compatibility.md](docs/compatibility.md) for details and caveats.
  146. ## How It Works
  147. ### Internals: The Memory Stack
  148. project-butler uses a 7-component memory stack internally, organized by stability:
  149. ```text
  150. Stable rules
  151. ┌─────────────────────────────────────┐
  152. │ CLAUDE.md / project rules │ <- Human-reviewed principles
  153. │ ↑ candidates collected by AI │
  154. └─────────────────────────────────────┘
  155. ↑ distilled from work
  156. Current state
  157. ┌─────────────────────────────────────┐
  158. │ PROJECT.md │ <- What the project is now
  159. │ STRUCTURE.md │ <- Where files belong
  160. │ UPDATE_LOG.md │ <- Milestone-level changes
  161. │ DOCS.md │ <- Document index
  162. │ .claude/project-profile.json │ <- Profile config
  163. │ .claude/profile-pending.json │ <- Profile debt queue
  164. └─────────────────────────────────────┘
  165. ↑ summarized from facts
  166. Raw facts
  167. ┌──────────────────────┐ ┌───────────────────────┐
  168. │ log/ │ │ TODO.md │
  169. │ What happened │ │ What needs doing │
  170. └──────────────────────┘ └───────────────────────┘
  171. ↓
  172. session-handoff.md <- Where the next session should resume
  173. ```
  174. Bottom feeds top. Top constrains bottom.
  175. - **Session logs** capture what happened.
  176. - **Handoff** tells the next assistant where to resume.
  177. - **Project wiki** summarizes the current state.
  178. - **TODOs** keep execution visible.
  179. - **Rules / constitution** preserve decisions that should keep guiding the project.
  180. - **Update log** records significant changes at milestone level.
  181. - **Structure rules** keep files from drifting into chaos.
  182. - **Document index** keeps project documents organized under `docs/`.
  183. - **Project profile** tracks project shape, document tiers, document policies, pending profile updates, and review queue items.
  184. ### Project Profiles
  185. Project Profile System is internal profile-aware behavior for setup and close. Fresh setup stays conversational and can remain lightweight by creating only minimal confirmed docs.
  186. During setup, project-butler asks what you are trying to do in natural language, infers the project shape, asks a few targeted follow-up questions, and proposes Required / Recommended / Optional reference docs. It does not force you to pick a fixed project type or expose Profile System as a setup switch.
  187. During close, profile-aware projects can use:
  188. | Mode | Behavior |
  189. |---|---|
  190. | Normal Close | Save the session and record profile-impacting changes in `.claude/profile-pending.json`. |
  191. | Full Close | Read only affected profile docs, present a Scope Plan, and apply safe updates inside that boundary. |
  192. Full Close confirms boundaries, not every small edit. It still requires explicit confirmation before changing protected sections, document policies, stable baselines, or whole-document rewrites.
  193. ### Language Support
  194. project-butler supports three language modes:
  195. | Mode | Content language | User file naming |
  196. |---|---|---|
  197. | `en` | English | English naming (`kebab-case`) |
  198. | `zh` | Chinese | Chinese naming allowed |
  199. | `bilingual` | Chinese with English annotations | English preferred, Chinese acceptable |
  200. You choose the mode during setup, and can later say `change language`.
  201. ### Version Naming
  202. During setup, project-butler asks which version style the project should use:
  203. | Style | Example | Best for |
  204. |---|---|---|
  205. | Semantic | `v0.1.0` | Engineering projects and libraries |
  206. | Codename | `Project Name 0.1` | Products, brands, and creative projects |
  207. | Patch | `Patch 1` | Games and iterative content releases |
  208. | Date | `2026.06.1` | Research logs, operations, and document-heavy work |
  209. `end session` uses this style when a significant update deserves an `UPDATE_LOG.md` entry.
  210. ### Upgrade Mode
  211. If a project already has some management files, project-butler creates only the missing ones. It does not replace existing files; when a system section needs an update, it asks before making a small targeted patch. It also detects legacy `.claude/memory/` layouts and suggests migration.
  212. During upgrade, project-butler preserves existing files and offers to bring the project into the current profile-aware setup model. It infers profile state from existing project docs and asks for confirmation before writing profile files or changing existing document policies.
  213. ## Examples
  214. See [docs/examples.md](docs/examples.md) for a complete session flow:
  215. 1. initialize a project,
  216. 2. work normally,
  217. 3. end the session,
  218. 4. resume the next day,
  219. 5. review accumulated rules.
  220. ## Requirements
  221. - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI for native skill execution
  222. - [jq](https://jqlang.github.io/jq/) for `continue` / `continue full context` session recovery
  223. - Optional: [Cursor](https://cursor.sh) for generated project rules
  224. - Optional: Codex or other AI coding assistants that can read project Markdown files and `AGENTS.md`
  225. ## Update Log
  226. ### v1.7.1 (2026-06-21) - Multi-Tool Compatibility Foundation
  227. - Extract version freshness detection into `scripts/check-update.sh` so Claude Code can keep automatic Step -1 checks while Cursor/Codex can run manual checks on demand.
  228. - Add Codex `AGENTS.md` project-instruction template and update Cursor rules with manual update-check coverage.
  229. - Document best-effort Cursor/Codex support and add an adapter coverage matrix.
  230. ### v1.6.0 (2026-06-10) - Project Profile System Runtime Wiring
  231. - Add `references/project-profile-system.md` and route profile setup, Normal Close, Full Close, Foundation Repair, and profile-aware status through the main skill.
  232. - Teach generated project rules, continue, full context recovery, and upgrade mode to read and preserve profile files.
  233. - Document Project Profile System as internal profile-aware runtime behavior on top of the base 7-component memory stack.
  234. ### v1.5.1 (2026-06-03) - Product Noise Reduction
  235. - Reframe the README around four primary actions: `/project-butler`, `end session`, `continue`, and `status`.
  236. - Move internals behind "How it works" and make examples result-focused.
  237. - Update generated CLAUDE/Cursor rules to separate daily workflow from advanced commands.
  238. ### v1.5.0 (2026-06-03) - Versioned Update Log System
  239. - Add version style selection during setup: Semantic, Codename, Patch, and Date.
  240. - Teach end-session update logging to calculate the next version from the selected style.
  241. - Sync README, examples, compatibility docs, generated rules, continue recovery, document archiving, upgrade mode, and trigger routing with the current memory stack.
  242. ### v1.4.1 (2026-06-02) - Cross-Reference + Flow Consistency
  243. - Fix DOCS.md, file snapshot, language switching, continue recovery, and template consistency gaps found through six review rounds.
  244. - Align document archiving, file reorganization, and Cursor rule templates.
  245. ### v1.3.0 (2026-06-01) - Four-Phase File Reorganization
  246. - Replace template-based file organization with Discover, Ask or Plan, Plan, and Execute phases.
  247. - Add confidence routing, safe move planning, and a never-delete cleanup policy.
  248. ### v1.2.1 (2026-05-09) - Skill Loader Compatibility
  249. - Move `continue` reference workflows under `references/` instead of nested `SKILL.md` files.
  250. - Shorten skill metadata to satisfy loader limits.
  251. - Keep session recovery routed through the main project-butler skill.
  252. Full update log: [UPDATE_LOG.md](UPDATE_LOG.md) | Releases: [GitHub Releases](https://github.com/JamesShi96/project-butler/releases)
  253. ## Star History
  254. [![Star History Chart](https://api.star-history.com/svg?repos=JamesShi96/project-butler&type=Date)](https://www.star-history.com/#JamesShi96/project-butler&Date)
  255. ## License
  256. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.