project-with-reflect

project-with-reflect

English | 中文

A self-distilling meta-skill for Codex, Claude Code, and other AI coding agents. — Neil Z. Shao

Best used with Obsidian + plugins:

• Neat File Tree — a cleaner, calmer file tree.
• Folder Notes — the <folder>/<folder>.md folder-note convention this skill optionally leans on (experiment records, evals, the per-workstream goal log).

Juggling several projects at once? Need to remember how to connect to a handful of machines and services? Tired of rewriting the same long prompts and re-explaining the same project to your agent?

It manages each project for you — worktrees, logs, reflect, a growing long-term knowledge base — and everything you operate (a connection), each becoming a callable /<name> skill:

• Servers — ssh in to deploy / tail logs / run commands.
• Training boxes — GPU machines: run training / nvidia-smi, with their quirks remembered (e.g. nvidia-smi -pl 300 after a reboot).
• Devices — USB/serial flash targets (dev boards…): flash / monitor / REPL.
• APIs — HTTP/WebSocket services (only the key's env-var name on disk, never the key).
• MCP servers — used directly via their mcp__<name>__* tools.

All of it Obsidian-friendly (lessons / knowledge / dashboard are clean, readable Markdown).

Your personal knowledge base — readable in your editor and your notes app:

Show your knowledge base in VS Code	Show your knowledge base in Obsidian

At a glance

• Everything is a skill — a project, and each connection above, gets its own /<name> once registered.
• Auto-logs as you work — commits, decisions, key findings, an experiment's result, an error + its fix, jotted to the active stream.
• Native hooks nudge memory hygiene — checkin before substantial work, re-read disk memory before risky commands, record edits/findings, flush before compaction.
• reflect distills itself — captures the session, then folds the log into lean, readable lessons it loads next time (and appends run results to a permanent experiment record).
• Checkin reboots from disk — before work, the agent reloads the goal/plan, progress, findings, and failed attempts from persistent files.
• Loads before acting — the agent reads existing lessons / decisions / knowledge first, so it stops re-explaining and repeating mistakes.
• Runs across agents — Claude Code has the plugin flow; Codex and other agents use the skill surfaces in this repo.

Core loop: work (auto-log) → /<project> reflect (capture + distill) → lean readable lessons → better next session

Install

Elegant published install:

Claude Code has the nicest first-class marketplace flow:

/plugin marketplace add initialneil/project-with-reflect
/plugin install project-with-reflect@project-with-reflect

For Codex and other agents that support the Agent Skills installer, use the open skills CLI:

npx skills add initialneil/project-with-reflect

Codex local/dev install:

Use this when working from a checkout, or if your agent does not yet wire the skills CLI into Codex's user skill directory:

mkdir -p ~/.codex/skills
ln -sfn /path/to/project-with-reflect/.codex/skills/project-with-reflect ~/.codex/skills/project-with-reflect

Quick start

The daily loop is: register → check status / check in → work → log and reflect.

1. Register once

# register a project → generates the /myapp skill
/register-project myapp ~/code/myapp

# optional: register a reusable workstream — just say what it's based on
/register-workstream my-feature based on main   # → generates /myapp-my-feature

2. Check status and check in

# from anywhere, even ~
/project-with-reflect status        # lists projects/connections and flags what needs attention
/myapp checkin                      # loads context, asks about cwd, then recaps with status
/myapp checkin train-v2             # or check straight into a specific workstream

3. Work, record, reflect

/myapp-my-feature ...                        # (or just /myapp for the main workstream)
/record-a-lesson the v2 baseline: 0.83 F1   # persist a result/conclusion NOW (≡ /myapp record "…")
/log-and-reflect          # from anywhere in the repo — resolves the project from your cwd
# (≡ /myapp reflect — "reflect" already captures the session first)