1. Read references/language-change.md + references/language-adaptation.md
2. Execute the Language Change Protocol
3. Report and stop

E. "continue" / "接着上次" / "上次做到哪了":

1. Read references/continue.md
2. Execute the Continue process (recover last session context)
3. Report and stop

F. "continue full context" / "全面回顾" / "项目全景" / "full context":

1. Read references/continue-full-context.md
2. Execute the Continue Full Context process (full project trajectory recovery)
3. Report and stop

End Session Flow

When triggered by "end session" / "结束会话" / "收工", execute in order:

1. Write session log → log/session-YYYY-MM-DD-{slug}.md
   • Same-day multiple sessions: use slug to distinguish (e.g., session-2026-04-21-prd-draft.md)
   • Format: see Session Log Format below
2. Log Compaction → if unarchived raw logs ≥ threshold (default 10, configured in CLAUDE.md): read references/log-compaction.md and execute
3. Update session-handoff.md → refresh "current progress" and "next steps"
4. Update PROJECT.md → if structure/module status changed
5. Update TODO.md → mark completed tasks
6. Collect constitution candidates → append to .claude/candidates.md (see rules below)
7. File reorganization (incremental) → read references/file-reorganization.md, execute Mode B
   • If STRUCTURE.md missing: execute Mode A first to establish baseline
   • Update .claude/.file-snapshot.json
8. Evaluate & write update log → read references/update-log.md
   • Evaluate session significance; if significant, prepend entry to UPDATE_LOG.md
   • Optionally offer GitHub Release creation
   • If not significant, skip silently
9. Output summary → brief summary in the configured language (check CLAUDE.md Language setting)

Session Log Format

Session log headers adapt to the configured language (read references/language-adaptation.md for glossary).

# Session YYYY-MM-DD — {topic}

## Session Goal
## Key Actions (Chronological)
## Decisions & Rationale
## Output Files
## Unfinished Items / Next Session Pickup
## CLAUDE.md Candidates (if any)

Constitution Candidate Rules

AI automatically appends to .claude/candidates.md when:

• User explicitly says "always do this" / "this is a rule" / "don't ever..."
• Same decision appears across multiple sessions
• Decision involves naming conventions, file structure, collaboration flow
• Decision involves tech stack or architecture constraints

Never modify CLAUDE.md directly. All candidates require user review via "review claude".

TODO Format

Each task in TODO.md must include:

- [ ] {task description}
  Owner: {name} | Deadline: {date} | Dependencies: {prerequisite}

If user provides a task missing required fields, ask them to fill in. Completed tasks are checked and kept (not deleted).

Init Flow

Step 1: Detect Mode

Scan project root for: CLAUDE.md, PROJECT.md, session-handoff.md, TODO.md, log/, STRUCTURE.md, UPDATE_LOG.md, .claude/.file-snapshot.json, .claude/candidates.md

• Fresh: None exist → create all
• Upgrade: Some exist → read references/upgrade-mode.md, create only missing files, never overwrite existing content

Step 2: Ask Questions

Use AskUserQuestion to ask:

1. 项目名称 — e.g., "达人营销AI", "Data Pipeline"
2. 一句话定义 — e.g., "AI-powered influencer marketing platform for US/EU markets"
3. 当前阶段 — e.g., "v1 MVP", "规划中", "已上线"
4. GitHub 仓库 — optional, e.g., "org/repo-name"
5. 是否创建 Cursor 规则文件 — yes/no (default yes)
6. 语言 / Language — en / zh / bilingual (default bilingual)

Step 3: Create Files

Read references/file-templates.md + references/language-adaptation.md.

Create each file using templates, replacing {{VARIABLES}} with user answers. Apply language adaptation rules and glossary from the reference.

Create log/.gitkeep (empty file) alongside log/ directory so git tracks it when empty.

Step 4: Output Report

项目管理系统已初始化 ✓

文件状态：
  ✅ CLAUDE.md           — 项目宪法（已创建）
  ✅ PROJECT.md          — 项目 Wiki（已创建）
  ✅ session-handoff.md  — 接手指引（已创建）
  ✅ TODO.md             — 执行清单（已创建）
  ✅ log/                — 会话日志目录（已创建）
  ✅ .claude/candidates.md — 宪法候选池（已创建）
  ✅ STRUCTURE.md        — 文件管理规则（已创建）
  ✅ UPDATE_LOG.md       — 更新日志（已创建）
  ✅ .cursor/rules/      — Cursor 规则（已创建 / 已跳过）
  🌐 Language: {{LANGUAGE}}

下一步：
1. 根据项目需要，在 TODO.md 添加第一批任务
2. 正常开始工作
3. 结束时说 "end session" 即可自动记录
4. 切换语言随时说 "change language" / "切换语言"

触发词速查：
  end session / 结束会话 / 收工 → 写 log + 全量同步
  review claude / 更新宪法     → 展示候选池逐条确认
  sync wiki / 同步项目         → 强制更新 PROJECT.md
  status / 项目现状            → 朗读 Wiki + handoff 摘要
  整理文件 / organize files → 扫描并整理文件结构

Reference Loading

| Trigger | Read these files | |---------|-----------------| | Init (fresh) | references/file-templates.md + references/language-adaptation.md | | Init (upgrade) | above + references/upgrade-mode.md | | End session | references/file-reorganization.md + references/update-log.md + references/log-compaction.md (if logs ≥ threshold) | | 整理文件 / organize files | references/file-reorganization.md | | 切换语言 / change language | references/language-change.md + references/language-adaptation.md | | continue / 接着上次 | references/continue.md | | continue full context / 全面回顾 | references/continue-full-context.md |

• "I had to re-explain the architecture again." Each new session starts with missing context.
• "What did we decide about naming conventions last week?" Decisions disappear into chat history.
• "The README and TODOs keep drifting from reality." Project state stops matching the files.
• "The AI keeps violating rules I already explained." Rules live in your head instead of in project memory.
• "I switch between Claude Code, Cursor, and Codex." Different tools need one shared source of truth.

project-butler turns a project folder into that source of truth.

What It Creates

Run /project-butler once. It creates a file-based project memory stack:

project-root/
├── CLAUDE.md                   <- Project rules / constitution
├── PROJECT.md                  <- Current project wiki
├── STRUCTURE.md                <- File organization rules
├── UPDATE_LOG.md               <- Milestone-level changelog
├── session-handoff.md          <- Cross-session handoff
├── TODO.md                     <- Execution checklist
├── log/                        <- Session logs
└── .claude/
    ├── candidates.md           <- Candidate rules for review
    └── .file-snapshot.json     <- File organization snapshot

The core files are plain Markdown, so other tools can read them even when they do not run the skill natively.

Common Commands

All triggers are natural language. Use slash commands only for first-time setup.

| You say | What happens | |---|---| | /project-butler | Initialize or upgrade the project memory stack. | | end session / we're done | Write a session log, update handoff, sync wiki, update TODOs, organize new files, and record significant changes. | | continue / continue from last time | Recover the previous session and resume without re-explaining context. | | continue full context | Rebuild the full project trajectory from the latest session plus historical summaries. | | review claude / check the rules | Review candidate project rules before they are promoted into the constitution. | | sync wiki / update overview | Force-refresh PROJECT.md. | | status / where are we | Read the current wiki and handoff summary. | | organize files | Run file organization based on STRUCTURE.md. | | change language | Switch project management files between English, Chinese, and bilingual mode. |

Session recovery (continue / continue full context) is routed through project-butler internally. There is no separate /continue command to install.

Tool Support

| Tool | Status | How it works | |---|---|---| | Claude Code | Native skill | Install this repo under ~/.claude/skills/project-butler and run /project-butler. | | Cursor | Project rules | project-butler can generate .cursor/rules/project-system.mdc, which points Cursor at the same project memory files. | | Codex | Shared memory files | Codex can read the generated Markdown files (PROJECT.md, TODO.md, session-handoff.md, rules) as project context. | | Other AI assistants | File-based | Any assistant that can read project files can use the memory stack as shared context. |

See docs/compatibility.md for details and caveats.

How It Works

The Memory Stack

project-butler organizes project memory by stability:

Stable rules
┌─────────────────────────────────────┐
│  CLAUDE.md / project rules          │  <- Human-reviewed principles
│  ↑ candidates collected by AI       │
└─────────────────────────────────────┘
            ↑ distilled from work
Current state
┌─────────────────────────────────────┐
│  PROJECT.md                         │  <- What the project is now
│  STRUCTURE.md                       │  <- Where files belong
│  UPDATE_LOG.md                      │  <- Milestone-level changes
└─────────────────────────────────────┘
            ↑ summarized from facts
Raw facts
┌──────────────────────┐ ┌───────────────────────┐
│  log/                │ │  TODO.md              │
│  What happened       │ │  What needs doing     │
└──────────────────────┘ └───────────────────────┘
            ↓
session-handoff.md       <- Where the next session should resume

Bottom feeds top. Top constrains bottom.

• Session logs capture what happened.
• Handoff tells the next assistant where to resume.
• Project wiki summarizes the current state.
• TODOs keep execution visible.
• Rules / constitution preserve decisions that should keep guiding the project.
• Update log records significant changes at milestone level.
• Structure rules keep files from drifting into chaos.

Language Support

project-butler supports three language modes:

| Mode | Content language | User file naming | |---|---|---| | en | English | English naming (kebab-case) | | zh | Chinese | Chinese naming allowed | | bilingual | Chinese with English annotations | English preferred, Chinese acceptable |

You choose the mode during setup, and can later say change language.

Upgrade Mode

If a project already has some management files, project-butler creates only the missing ones. It does not overwrite existing content. It also detects legacy .claude/memory/ layouts and suggests migration.

Examples

See docs/examples.md for a complete session flow:

1. initialize a project,
2. work normally,
3. end the session,
4. resume the next day,
5. review accumulated rules.

Requirements

• Claude Code CLI for native skill execution
• jq for continue / continue full context session recovery
• Optional: Cursor for generated project rules
• Optional: Codex or other AI coding assistants that can read project Markdown files

Update Log

v1.2.1 (2026-05-09) - Skill Loader Compatibility

• Move continue reference workflows under references/ instead of nested SKILL.md files.
• Shorten skill metadata to satisfy loader limits.
• Keep session recovery routed through the main project-butler skill.

v1.2.0 (2026-05-05) - Update Log Auto-Tracking

• Auto-detect significant updates at end session.
• Add UPDATE_LOG.md for milestone-level change history.
• Offer optional GitHub Release creation for significant updates.
• Support both code and non-code projects.

v1.1.0 (2026-05-04) - SKILL.md Refactor + Continue Rename

• Refactor SKILL.md from 1175 to 196 lines with on-demand reference loading.
• Rename /resume to continue and /resume-full to continue full context.
• Route all triggers through natural language.

v1.0.0 (2026-05-01) - Session Recovery + Log Compaction

• Add session recovery (continue / continue full context).
• Add log compaction when raw logs exceed the threshold.
• Rename from project-init to project-butler.

Full update log: UPDATE_LOG.md | Releases: GitHub Releases

Star History

License

MIT