Use when starting a new dissertation project or adopting an existing repo for dissertation work
meta/ directory exists in the current projectDetermine which mode applies. If the current directory has substantial existing content (markdown files, code, data), offer init adopt. If it is empty or has only a README, proceed with init new.
Ask the user to confirm the mode if unclear.
init new)Interactive setup — ask these questions one at a time before creating any files:
Once answers are collected, scaffold the full project structure:
<project>/
CLAUDE.md
AGENTS.md
GEMINI.md
meta/
memory.md # Initialize with project creation entry
progress.md # All chapters marked as [NOT STARTED]
milestones.md # Empty template
plan.md # Empty template
style/
tasks/
writings/
ch01-<name>/
outline.md
resources.md
draft.md
status.md
assets/
reviews/
ch02-<name>/
...
references/
literature/
results/
docs/
.gitignore
File generation steps:
Create all directories. Use ch01-<slug>, ch02-<slug>, ... based on chapter names provided.
Generate meta/memory.md:
# Memory
## Current Focus
Project just initialized: <title>
## Recent Decisions
- <date>: Project created with <citation style> citation style, language: <language>
## Open Questions
## Key Insights
## Next Session
- Run `checkin` to begin your first session
- Consider running `brainstorm` to explore research directions
meta/progress.md:# Progress
| Chapter | Status | Notes |
|---------|--------|-------|
| ch01 — <name> | [NOT STARTED] | |
| ch02 — <name> | [NOT STARTED] | |
...
meta/milestones.md:# Milestones
| Milestone | Target Date | Status |
|-----------|-------------|--------|
| Topic finalized | | [ ] |
| Literature review complete | | [ ] |
| Outline approved | | [ ] |
| First draft complete | | [ ] |
| Revisions complete | | [ ] |
| Submission | | [ ] |
Generate meta/plan.md as an empty template with headers: # Plan, ## Timeline, ## Weekly Routine.
Generate writings/ch0N-<name>/status.md for each chapter:
# <Chapter Name> Status
## Sections
(to be filled during outline)
## Blockers
## Last Updated
<date> by init
6b. Generate writings/ch0N-<name>/outline.md for each chapter as an empty placeholder:
# Chapter N: <Chapter Name>
## Outline
*To be drafted. Run `superpaper-outline` to plan this chapter.*
6c. Generate writings/ch0N-<name>/draft.md for each chapter as an empty placeholder:
# Chapter N: <Chapter Name>
## Draft
*Not yet started. Complete the outline first, then run `superpaper-draft`.*
6d. Generate writings/ch0N-<name>/resources.md for each chapter as an empty placeholder:
# Chapter N: <Chapter Name> — Resources
## Literature
*No references yet. Run `superpaper-ingest` to add literature.*
## Results
*No analysis results yet.*
Generate CLAUDE.md with full project settings (see template below).
Generate AGENTS.md referencing the same project settings and skill mapping as CLAUDE.md.
Generate GEMINI.md with tool mapping reference (activate_skill maps to Skill tool in Claude Code).
Generate .gitignore (see template below).
Run:
# If git not already initialized, run git init first
git init # safe to run even if already initialized (no-op)
git add .
git commit -m "init: <title>"
Note: Check if .git/ already exists. If so, skip git init to avoid confusing output — run git add . && git commit -m "init: <title>" directly.
Project scaffolded. Run
checkinto start your first session, orbrainstormto explore research directions.
init adopt)Key principle: adopt mode never moves or deletes existing files without explicit confirmation from the user. This is non-negotiable — NEVER alter or remove existing content without asking.
For repos with existing content:
Paper language? (zh / en)
Paper title?
Citation style? (GB/T 7714 / APA / Chicago / IEEE / custom)
Scan the repo for content patterns:
.bib files) → literature referencesPresent proposed mapping to the user. Example:
Found content:
chapters/intro.md → writings/ch01-introduction/draft.md (symlink/record in CLAUDE.md)
chapters/lit.md → writings/ch02-literature/draft.md
data/ → references/results/
refs.bib → references/literature/ (after ingest)
No files will be moved. Mapping recorded in CLAUDE.md.
Confirm? (yes / adjust)
After user confirmation, create the meta/ layer on top:
meta/memory.md — initial entry describing the adoption and what was foundmeta/progress.md — chapters with existing drafts marked as [IN PROGRESS], others as [NOT STARTED]status.md for each identified chapterIf the existing structure uses different directory names (e.g., chapters/ instead of writings/), record the mapping in CLAUDE.md under a ## Directory Mapping section. Do not rename directories.
Generate CLAUDE.md / AGENTS.md / GEMINI.md.
Commit: "init: adopt existing repo — <title>"
Generate this in the user's project root:
# <Paper Title>
## Project Settings
- Language: <language>
- Citation style: <citation style>
- University: <from question 5, or blank if user skipped>
## Skills
This project uses superpaper.
Before any task, check for a matching skill.
### Project Manager
- Session start → superpaper-checkin
- New materials → superpaper-ingest
- End of session → superpaper-memory-update
### Research Facilitator
- Topic exploration → superpaper-brainstorm
- Literature gaps → superpaper-research
- Data questions → superpaper-data-explore / superpaper-analysis
### Writing Assistant
- Chapter planning → superpaper-outline
- Writing → superpaper-draft
- Reviewing → superpaper-review
### Quality Assurance
- Audit → superpaper-lint
- Submission prep → superpaper-export
## Context Loading
1. Read meta/memory.md — recent history and decisions
2. Read meta/progress.md — overall state
3. Read relevant writings/<ch>/status.md — chapter details
4. Read relevant references/<key>/summary.md — don't re-read originals
## Writing Principles
- Mark uncertainty: [TODO], [CITE], [DATA]. Never fabricate.
- Always structurally complete. Missing sections have placeholders.
- Respect human edits. Never overwrite without asking.
- Follow meta/style/style-guide.md — extracted from sample paragraphs/chapters you provide.
- Shorter is better.
- Task files in `meta/tasks/` should have a status header: `status: pending | in-progress | done`. Stale done tasks can be archived to `meta/tasks/archive/`.
## Boundaries
- Do not fabricate data, results, or citations
- Do not mark chapters as finalized (human only)
- Do not make major structural changes without asking
- Do not delete human content without permission
- For deep research: generate prompts, don't pretend to search
- For coding/analysis: generate specs, don't write code
# PDFs (markdown-first — PDFs are local reference copies)
*.pdf
# Data files
*.csv
*.xlsx
*.dta
*.sav
*.rds
# Large binary files
*.zip
*.tar.gz
# Assets (figures regenerated from code)
writings/*/assets/*
!writings/*/assets/.gitkeep
# OS
.DS_Store
Thumbs.db
# Editor
.idea/
.vscode/
*.swp
# Exported drafts (regenerate with export skill)
export/
meta/memory.md, meta/progress.md, meta/milestones.md, meta/plan.mdwritings/ch0N-<name>/ directories with placeholder filesreferences/literature/, references/results/, references/docs/CLAUDE.md, AGENTS.md, GEMINI.md with project settings and skill mapping.gitignorech01-<slug>, ch02-<slug>, etc. Slugify names (lowercase, hyphens).zh projects).CLAUDE.md is what any agent reads when entering the dissertation project.checkin as the very next skill to run after init completes.