The Problem
I had two planning systems fighting each other. The global commands in ~/.claude/commands/ used .plans/ paths, while the project-level skills in .claude/skills/create-plan/ used .planning/ paths. They could not interoperate. Worse, the global /create-plan command coupled PRD writing with task generation in a single shot, meaning there was no window for human review between "here is the design" and "here are the tasks."
The project-level system was over-engineered -- TDD workflows, specialist agents, Socratic dialogue, plan-mode integration -- none of which delivered proportional value. The simpler global PRD approach was the one I actually wanted to use.
What I Built
This was a three-phase refactor that restructured the entire planning workflow across both the motivka project and the global Claude commands.
Phase 1: Directory migration. I migrated motivka from .planning/ to .plans/, breaking all Obsidian symlinks and copying content into plain markdown files. The 15 existing plan files and roughly 50 archived plans became plain .md files under .plans/prds/. I updated path references across 9 files including CLAUDE.md, settings, agents, and dockerignore patterns.
Phase 2: Legacy cleanup. I deleted 5 project-level commands, 3 skill directories, a migration hook, and 2 broken global symlinks. Everything that duplicated the global system was removed. Only build.md survived because it has no global equivalent.
Phase 3: Global command improvements. I split /create-plan to stop after PRD writing, created a new /generate-tasks command for task file generation, and added context-aware next-step suggestions throughout the pipeline. I fixed the ACTIVE_TASK.md dead symlink (written by 2 commands, read by 0), removed the /review double-invocation risk, and retargeted the sync hook from Obsidian to iA Writer.
Key Decisions
- Simplify deliberately -- the project-level planning skill was over-engineered. Complexity was not delivering proportional value.
- Per-feature PRDs in
.plans/prds/{date}-{slug}.mdrather than a single overwritablePRD.md. - Keep PROJECT.md and ROADMAP.md separate -- strategic context (stable) versus execution tracker (volatile).
- No retroactive project-wide PRD for Motivka -- it is already built. New features each get their own.
- Retarget sync hook to iA Writer rather than dropping it entirely -- the hook logic was reusable, only paths changed.
What is Next
The workflow pipeline now has clear handoff points: /create-plan produces a PRD, the developer annotates it, /refine-plan processes annotations, /generate-tasks creates task files, and /execute-plan runs the build-verify loop. Each arrow is a human decision point. No stage auto-advances. This foundation supports all future feature work on motivka and every other project in the ecosystem.