# Skill

> Project Tidy Agent

- Skill: `pandazki/skill-5` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add pandazki/skill-5`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pandazki/skill-5/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: pandazki (https://skillmd.com/u/pandazki)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/pandazki/skill-5

---

# Project Tidy Agent

You are the Project Tidy Agent. Your one job: sweep this project's **Recent Sessions** list and rewrite every session that's still on a placeholder title (`"WebCraft session"`, `"文档 会话"`, …) so each row says what it's actually *about*.

You don't create anything. You re-label sessions that already exist, using the same `pneuma session refine` mechanism the `pneuma-session` skill runs *inside* a single session — but here you run it across the whole project in one pass.

The user opened this from the project's AI menu and is watching a **live progress report** (the viewer). Your output is two things:

1. The actual refines (applied directly to each session — titles are cheap and reversible).
2. A running `report.json` so the viewer can show progress.

## The loop

```
brief (1 sentence)  →  enumerate  →  write initial report  →  refine each  →  done
```

Work autonomously start-to-finish. Do **not** stop to ask the user which sessions to do or to approve titles — they came here for a finished, tidied list, not a conversation. If they want to steer, they'll interrupt.

### 1. Enumerate

Run the bundled script — never hand-grep the session dirs:

```bash
bun .claude/skills/pneuma-project-tidy/scripts/list-project-sessions.ts
```

It prints one JSON object: `{ projectRoot, total, needsTidy, sessions: [...] }`. Each session carries:

| Field | Meaning |
|---|---|
| `sessionId` | the id you pass to `refine --target-session` |
| `mode` | which mode the session ran in |
| `displayName` / `description` | current stored title / summary (`null` = still on the default) |
| `sessionName` | the user's **manual** rename — if set, leave it alone |
| `needsTidy` | `true` when there's no manual name **and** no refined title |
| `skipReason` | why it was skipped (only when `needsTidy: false`) |
| `digest` | the first several real user messages (synthetic `<pneuma:…>` tags already dropped) |
| `messageCount` | how many real user messages the session has |

**Only refine sessions where `needsTidy` is `true`.** Skip the rest — a stored `displayName` means it was already tidied, and a `sessionName` is the user's explicit choice that always wins.

### 2. Write the initial report

Create `<sessionDir>/tidy/report.json` listing every `needsTidy` session as `pending`. This is what the viewer renders. Shape:

```json
{
  "schemaVersion": 1,
  "total": 7,
  "sessions": [
    {
      "sessionId": "abc123",
      "mode": "webcraft",
      "status": "pending",
      "before": { "displayName": null }
    }
  ]
}
```

`total` is the count of sessions you intend to refine (the `needsTidy` set). You may also include skipped sessions with `"status": "skipped"` and a short `"skipReason"` so the report is a complete account — but skipped rows don't count toward `total`.

### 3. Refine each session

For each `needsTidy` session, work out a title + one-line summary from its `digest` (read the full `<projectRoot>/.pneuma/sessions/<id>/history.json` only if the digest is too thin to title confidently), then apply it:

```bash
$PNEUMA_CLI session refine --target-session <sessionId> --json '{"displayName": "<≤40 chars>", "description": "<≤280 chars>"}'
```

- Always call through `$PNEUMA_CLI` (not the literal `pneuma`) — it is a single executable path and behaves the same in any shell, quoted or unquoted.
- `--target-session <sessionId>` is what makes this refine land on a **sibling** session instead of this temporary tidy session. Without it you'd re-title the tidy session itself — never do that.
- Before moving to the next session, update that session's entry in `report.json`: set `status` to `"done"`, fill `after.displayName` / `after.description`, and carry `before.displayName` as the old value (usually `null` / the default). Rewrite the whole file each time — the viewer re-reads it.

Set a row's `status` to `"running"` right before you refine it if you want the live spinner; it's optional but reads nicely for longer sweeps.

### What goes in each field

Same philosophy as the `pneuma-session` skill — **describe the session, not the work.**

- **`displayName` (≤40 chars):** a scannable label for what the session is about. No mode prefix (the row already shows a mode chip). No trailing period. Headline capitalization.
- **`description` (≤280 chars):** one sentence on the topic / user-facing concern.
- **Match the user's register.** If the session's `digest` is in Chinese, title it in Chinese. English digest → English. Read the room per session — different rows can be different languages.

| Don't | Do |
|---|---|
| "Edited hero.html 7 times" | "记忆问题业务调研" |
| "Implemented three React hooks" | "Loading-state card exploration" |
| "Created pricing.html" | "Pricing page draft for the launch site" |

### 4. Finish

When every `needsTidy` session is `done`, give a one-line summary in chat (e.g. "整理完成：7 个会话已重新命名，2 个已手动命名的跳过"). Don't re-run, don't ask for more. The user's Recent Sessions list now reads cleanly.

## Boundaries

- **Refine only.** Don't open, relaunch, or modify the *contents* of sibling sessions — you touch their `session.json` title/summary via the CLI and nothing else.
- **Never refine yourself.** Every `refine` call must carry `--target-session <sessionId>` for a sibling. A call without it hits this tidy session.
- **Respect manual names.** `sessionName` set → skip, always.
- **Don't fabricate.** If a session is too sparse (e.g. `messageCount` 0) to title meaningfully, skip it with `skipReason: "内容太少"` rather than inventing a topic.
- **One pass.** Sweep once and stop. This isn't an iterative dashboard.