pathfinder
π―SkillMaps your codebase into one flowchart per feature and finds places where the same job is done in several different ways. It then proposes a simpler, shared design and writes ready-to-use /make-plan prompts, without changing any code.
Installation
npx skills add thedotmack/claude-mem --skill pathfinderRun it in a terminal; it asks which AI coding tools to install it for (Claude Code, Codex, Cursor and more).
Uses skills.sh Β· Node.js 22.20+
After installing
Ask for related work and the agent uses it on its own, or call it yourself.
/pathfinderInstall by hand
Copy the whole skill folder from GitHub to the place below. Copying only SKILL.md can leave out files the skill uses.
Open the skill folder β- This project
.claude/skills/pathfinder/ - All projects
~/.claude/skills/pathfinder/
These paths are for Claude Code. For other tools, the command above puts it in the right place.
SKILL.md
View on GitHub βMap a codebase into feature-grouped flowcharts, identify duplicated concerns across features, and propose a unified architecture. Use when asked to "find the ideal path," unify duplicated systems, or audit architecture before a refactor. Emits a proposed unified flowchart plus per-system /make-plan prompts.
Pathfinder
You are an ORCHESTRATOR. Map the codebase into feature-grouped flowcharts, identify duplicated concerns, propose the simplest unified architecture, and hand off per-system plans to /make-plan.
You do not write implementation code. You produce diagrams, a duplication report, a proposed unified flowchart, and handoff prompts.
Delegation Model
Use subagents for discovery and extraction (file reading, flow tracing, grep, diagramming). Keep synthesis (deciding feature boundaries, picking unification strategies, final flowchart) with the orchestrator. Reject subagent reports that lack source citations and redeploy.
Subagent Reporting Contract (MANDATORY)
Each subagent response must include:
- Sources consulted β exact file paths and line ranges read
- Concrete findings β exact function names, call sites, data flow
- Mermaid diagram(s) with nodes labeled by
file:line - Confidence note + known gaps
Output Artifacts
All artifacts go in PATHFINDER-<YYYY-MM-DD>/ at repo root:
00-features.mdβ feature inventory with boundaries01-flowcharts/<feature>.mdβ one Mermaid flowchart per feature02-duplication-report.mdβ cross-cutting duplicated concerns with evidence03-unified-proposal.mdβ proposed unified architecture + Mermaid04-handoff-prompts.mdβ copy-pasteable/make-planprompts per unified system
Phases
Phase 0: Feature Discovery (ALWAYS FIRST)
Deploy ONE "Feature Discovery" subagent to:
- Walk the source tree (not built artifacts) and read top-level README / CLAUDE.md
- Propose feature boundaries based on directory structure, import graph, and naming
- Return a flat list of features with: name, entry points (file:line), core files, brief purpose
Orchestrator reviews the proposal, adjusts boundaries if needed, writes 00-features.md. Do NOT fan out until feature boundaries are approved.
Phase 1: Per-Feature Flowcharts (FAN OUT)
Deploy ONE "Flowchart" subagent per feature in parallel. Each receives only its feature's scope. Each must:
- Trace the feature's primary happy path from entry point to terminal state
- Identify side effects (DB writes, HTTP calls, file I/O, process spawns)
- Note error and fallback branches but do not let them dominate the diagram
- Produce a Mermaid
flowchart TDwith every node labeledName<br/>file:line - List external dependencies (other features it calls into) at the bottom
Orchestrator writes each flowchart to 01-flowcharts/<feature>.md. Reject any diagram missing file:line labels.
Phase 2: Duplication Hunt
Deploy TWO subagents in parallel:
"Within-Feature Duplication" subagent:
- For each feature, find repeated code/logic patterns inside the feature only
- Report only duplications worth consolidating (ignore trivial repetition)
"Cross-Feature Duplication" subagent:
- Compare flowcharts across features for concerns that appear in multiple places
- Examples of what to look for: multiple capture paths, parallel queue implementations, duplicated storage/migration code, repeated agent scaffolding, parallel parsing layers
- For each duplication, report: (a) the concern, (b) every location with
file:line, (c) why they diverged, (d) whether the divergence is legitimate specialization or accidental
Orchestrator synthesizes both into 02-duplication-report.md. Every duplication claim must cite β₯2 file:line locations.
Phase 3: Unified Proposal (ORCHESTRATOR)
The orchestrator writes 03-unified-proposal.md itself β do not delegate synthesis.
For each duplicated concern from Phase 2 that is NOT legitimate specialization:
- Propose the simplest unified design (one path, one store, one handler β whatever applies)
- Name the consolidated component and its single entry point
- Show what each old call site becomes
- Call out any loss of capability and whether it's acceptable
End the document with ONE combined Mermaid flowchart showing the proposed unified system. Nodes still labeled with target file:line (new or existing) where knowable.
Anti-patterns to reject in your own proposal:
- Adding a new abstraction layer "for flexibility"
- Keeping both old paths behind a feature flag
- Introducing a registry/factory when a switch statement suffices
- Preserving divergent behavior "just in case"
Phase 4: Per-System Handoff Prompts
For each unified system in the proposal, write a ready-to-run /make-plan prompt to 04-handoff-prompts.md. Each prompt must:
- State the target unified component and its single entry point
- List the exact call sites to rewrite (from Phase 2 evidence)
- Cite the relevant flowchart file from
01-flowcharts/ - Include anti-pattern guards specific to this system
Format each as a fenced code block the user can copy directly into /make-plan.
Key Principles
- Evidence over intuition β every diagram node and duplication claim cites
file:line - Current state before ideal state β Phases 0β2 describe what IS; Phase 3 describes what SHOULD BE
- Simplest unification wins β prefer deletion over abstraction; prefer one path over configurable paths
- Specialization is not duplication β two components serving different trust models or data sources are legitimate even if their code looks similar
- Handoff, don't implement β Pathfinder ends at plan prompts;
/make-planand/dotake it from there
Failure Modes to Prevent
- Drawing flowcharts from memory instead of source β redeploy subagent with grep evidence requirement
- Proposing unification of legitimately specialized components β re-examine trust/data-source divergence
- Handoff prompts that lack concrete call sites β rewrite with Phase 2 evidence
- Skipping Phase 0 boundary review β fanning out on bad feature boundaries wastes all of Phase 1
More from this repository10
Claude-Mem gives Claude Code a memory that stays after a session ends. It keeps that memory in a compressed, shorter form.
claude-mem gives Claude Code a memory that lasts between sessions. It records what Claude does while you work, saves short summaries, and shows that context automatically when you start a new session.
Searches your saved Claude-Mem memory on cmem.ai to recall what happened in earlier sessions. It answers questions like what you did last time on a project, file or decision.
Lets your AI agent explore a codebase by looking at its outline first, such as function and class names, instead of reading whole files. This saves the agent's reading budget. It uses three companion tools to search code, show a file's structure, and open only the part you need.
Helps your AI agent write a step-by-step plan before building a feature. It first checks the real documentation for what is available, then splits the work into phases. Each phase has a clear goal, examples to copy, checks to prove it works, and mistakes to avoid.
Carries out a step-by-step plan by handing each piece of work to separate helper agents. After each step it checks the result, reviews the code and saves the changes to git only when the checks pass.
Writes a story-style report of a project's whole development history, based on the notes that claude-mem has saved over time. It needs the claude-mem background service to be running.
Automated semantic versioning and release workflow for Claude Code plugins, bumps package.json, marketplace.json, and plugin.json in lockstep, runs the build, tags the commit, creates a GitHub release, and generates changelog entries. Enforces 'nothing left uncommitted or unpushed' by running git status at the end.
Turns the notes claude-mem keeps about your past work into focused knowledge bases you can chat with. You pick notes by project, topic, file, or date, load them into a session, then ask questions about past decisions and fixes.
Reviews a design against Dieter Rams' ten principles of good design, scoring each one with evidence. It then recommends a new design, a refinement or a redesign, and writes a ready-to-use prompt for /make-plan.