diff --git a/docs/working/plans/2026-06-21-documentation-restructure.md b/docs/working/plans/2026-06-21-documentation-restructure.md index 9104e77..08172c3 100644 --- a/docs/working/plans/2026-06-21-documentation-restructure.md +++ b/docs/working/plans/2026-06-21-documentation-restructure.md @@ -1,6 +1,6 @@ # Documentation Restructure Implementation Plan -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [x]`) syntax for tracking. **Goal:** Restructure `docs/` from an organic flat layout into a type-first hierarchy (`guides/`, `reference/`, `working/`, `research/`) serving two personas: Mischa and Claude. @@ -25,7 +25,7 @@ - Create directories: `docs/guides/`, `docs/reference/`, `docs/working/specs/`, `docs/working/plans/`, `docs/working/qa/`, `docs/working/milestones/`, `docs/research/` - Move: all 49 existing files under `docs/` to their new locations -- [ ] **Step 1: Create the new directory tree** +- [x] **Step 1: Create the new directory tree** ```bash mkdir -p /home/mischa/Nextcloud/Projects/travel-blog-intotheeast/docs/guides @@ -37,7 +37,7 @@ mkdir -p /home/mischa/Nextcloud/Projects/travel-blog-intotheeast/docs/working/mi mkdir -p /home/mischa/Nextcloud/Projects/travel-blog-intotheeast/docs/research ``` -- [ ] **Step 2: Move specs/ and plans/ (bulk)** +- [x] **Step 2: Move specs/ and plans/ (bulk)** ```bash cd /home/mischa/Nextcloud/Projects/travel-blog-intotheeast @@ -53,7 +53,7 @@ for f in docs/working/plans/*.md; do done ``` -- [ ] **Step 3: Move milestone specs** +- [x] **Step 3: Move milestone specs** ```bash cd /home/mischa/Nextcloud/Projects/travel-blog-intotheeast @@ -63,7 +63,7 @@ git mv docs/working/milestones/milestone-3.md docs/working/milestones/milestone- git mv docs/working/milestones/milestone-4.md docs/working/milestones/milestone-4.md ``` -- [ ] **Step 4: Move QA docs** +- [x] **Step 4: Move QA docs** ```bash cd /home/mischa/Nextcloud/Projects/travel-blog-intotheeast @@ -71,7 +71,7 @@ git mv docs/qa-test-plan.md docs/working/qa/test-plan.md git mv docs/qa-results.md docs/working/qa/results.md ``` -- [ ] **Step 5: Move remaining working/ docs** +- [x] **Step 5: Move remaining working/ docs** ```bash cd /home/mischa/Nextcloud/Projects/travel-blog-intotheeast @@ -82,7 +82,7 @@ git mv docs/production-todo.md docs/working/production-todo.md git mv docs/summary.md docs/working/summary.md ``` -- [ ] **Step 6: Move research docs** +- [x] **Step 6: Move research docs** ```bash cd /home/mischa/Nextcloud/Projects/travel-blog-intotheeast @@ -91,7 +91,7 @@ git mv docs/research-findpenguins.md docs/research/findpenguins.md git mv docs/research-story-editing.md docs/research/story-editing.md ``` -- [ ] **Step 7: Move design system to reference/** +- [x] **Step 7: Move design system to reference/** ```bash cd /home/mischa/Nextcloud/Projects/travel-blog-intotheeast @@ -99,14 +99,14 @@ git mv docs/design/design-spec.md docs/reference/design-system.md rmdir docs/design # now empty ``` -- [ ] **Step 8: Move posting pipeline to guides/ (base for Task 4)** +- [x] **Step 8: Move posting pipeline to guides/ (base for Task 4)** ```bash cd /home/mischa/Nextcloud/Projects/travel-blog-intotheeast git mv docs/guides/posting.md docs/guides/posting.md ``` -- [ ] **Step 9: Verify — no files remain at docs/ root, no docs/working/ exists** +- [x] **Step 9: Verify — no files remain at docs/ root, no docs/working/ exists** ```bash find /home/mischa/Nextcloud/Projects/travel-blog-intotheeast/docs -maxdepth 1 -type f @@ -122,7 +122,7 @@ ls /home/mischa/Nextcloud/Projects/travel-blog-intotheeast/docs/working/plans/ | # Expected: 19 (18 original + this plan) ``` -- [ ] **Step 10: Commit** +- [x] **Step 10: Commit** ```bash cd /home/mischa/Nextcloud/Projects/travel-blog-intotheeast @@ -139,28 +139,28 @@ git commit -m "docs: restructure docs/ into guides/ reference/ working/ research After the moves, links inside plan and spec files still point to old paths like `docs/working/plans/...` and `docs/working/milestones/milestone-1.md`. This task fixes them all. -- [ ] **Step 1: Replace docs/working/specs/ references** +- [x] **Step 1: Replace docs/working/specs/ references** ```bash cd /home/mischa/Nextcloud/Projects/travel-blog-intotheeast grep -rl "docs/working/specs/" docs/ | xargs sed -i 's|docs/working/specs/|docs/working/specs/|g' ``` -- [ ] **Step 2: Replace docs/working/plans/ references** +- [x] **Step 2: Replace docs/working/plans/ references** ```bash cd /home/mischa/Nextcloud/Projects/travel-blog-intotheeast grep -rl "docs/working/plans/" docs/ | xargs sed -i 's|docs/working/plans/|docs/working/plans/|g' ``` -- [ ] **Step 3: Replace docs/working/ catch-all (any remaining bare references)** +- [x] **Step 3: Replace docs/working/ catch-all (any remaining bare references)** ```bash cd /home/mischa/Nextcloud/Projects/travel-blog-intotheeast grep -rl "docs/working/" docs/ | xargs sed -i 's|docs/working/|docs/working/|g' ``` -- [ ] **Step 4: Replace milestone spec references** +- [x] **Step 4: Replace milestone spec references** ```bash cd /home/mischa/Nextcloud/Projects/travel-blog-intotheeast @@ -170,14 +170,14 @@ grep -rl "docs/milestone-3-spec" docs/ | xargs sed -i 's|docs/milestone-3-spec\. grep -rl "docs/milestone-4-spec" docs/ | xargs sed -i 's|docs/milestone-4-spec\.md|docs/working/milestones/milestone-4.md|g' ``` -- [ ] **Step 5: Replace posting-pipeline reference** +- [x] **Step 5: Replace posting-pipeline reference** ```bash cd /home/mischa/Nextcloud/Projects/travel-blog-intotheeast grep -rl "docs/posting-pipeline" docs/ | xargs sed -i 's|docs/posting-pipeline\.md|docs/guides/posting.md|g' ``` -- [ ] **Step 6: Fix references inside CLAUDE.md** +- [x] **Step 6: Fix references inside CLAUDE.md** ```bash cd /home/mischa/Nextcloud/Projects/travel-blog-intotheeast @@ -186,7 +186,7 @@ sed -i 's|docs/working/plans/|docs/working/plans/|g' CLAUDE.md sed -i 's|docs/working/|docs/working/|g' CLAUDE.md ``` -- [ ] **Step 7: Verify no old paths remain** +- [x] **Step 7: Verify no old paths remain** ```bash cd /home/mischa/Nextcloud/Projects/travel-blog-intotheeast @@ -198,7 +198,7 @@ grep -r "docs/posting-pipeline" docs/ CLAUDE.md # Expected: no output ``` -- [ ] **Step 8: Commit** +- [x] **Step 8: Commit** ```bash cd /home/mischa/Nextcloud/Projects/travel-blog-intotheeast @@ -213,7 +213,7 @@ git commit -m "docs: fix all internal cross-references after restructure" **Files:** - Create: `docs/README.md` -- [ ] **Step 1: Write docs/README.md** +- [x] **Step 1: Write docs/README.md** Create `/home/mischa/Nextcloud/Projects/travel-blog-intotheeast/docs/README.md` with this content: @@ -250,14 +250,14 @@ Create `/home/mischa/Nextcloud/Projects/travel-blog-intotheeast/docs/README.md` **Raw research input** → [`research/`](research/) ``` -- [ ] **Step 2: Verify** +- [x] **Step 2: Verify** ```bash cat /home/mischa/Nextcloud/Projects/travel-blog-intotheeast/docs/README.md # Expected: the full content above, no truncation ``` -- [ ] **Step 3: Commit** +- [x] **Step 3: Commit** ```bash cd /home/mischa/Nextcloud/Projects/travel-blog-intotheeast @@ -274,7 +274,7 @@ git commit -m "docs: add README.md navigation index" The moved `posting-pipeline.md` is a technical reference. Reformat it as a step-by-step guide for Mischa, preserving all factual content, adding a quick-start at the top and a troubleshooting section at the bottom. -- [ ] **Step 1: Rewrite docs/guides/posting.md** +- [x] **Step 1: Rewrite docs/guides/posting.md** Replace the full content of `docs/guides/posting.md` with: @@ -396,7 +396,7 @@ Every entry supports these frontmatter fields: → Run `make fix-perms` to restore container file ownership. ``` -- [ ] **Step 2: Verify** +- [x] **Step 2: Verify** ```bash grep -c "Quick start" /home/mischa/Nextcloud/Projects/travel-blog-intotheeast/docs/guides/posting.md @@ -406,7 +406,7 @@ grep -c "Troubleshooting" /home/mischa/Nextcloud/Projects/travel-blog-intotheeas # Expected: 1 ``` -- [ ] **Step 3: Commit** +- [x] **Step 3: Commit** ```bash cd /home/mischa/Nextcloud/Projects/travel-blog-intotheeast @@ -421,7 +421,7 @@ git commit -m "docs: rewrite posting guide as user-facing step-by-step" **Files:** - Create: `docs/guides/gpx-manager.md` -- [ ] **Step 1: Write docs/guides/gpx-manager.md** +- [x] **Step 1: Write docs/guides/gpx-manager.md** Create `/home/mischa/Nextcloud/Projects/travel-blog-intotheeast/docs/guides/gpx-manager.md` with this content: @@ -513,7 +513,7 @@ GPX files are registered as a valid media type in `user/config/media.yaml`, so G No manual linking is needed — upload and it appears. ``` -- [ ] **Step 2: Verify** +- [x] **Step 2: Verify** ```bash grep -c "slugif" /home/mischa/Nextcloud/Projects/travel-blog-intotheeast/docs/guides/gpx-manager.md @@ -523,7 +523,7 @@ grep -c "Komoot" /home/mischa/Nextcloud/Projects/travel-blog-intotheeast/docs/gu # Expected: >= 3 ``` -- [ ] **Step 3: Commit** +- [x] **Step 3: Commit** ```bash cd /home/mischa/Nextcloud/Projects/travel-blog-intotheeast @@ -538,7 +538,7 @@ git commit -m "docs: add GPX manager guide" **Files:** - Create: `docs/guides/trip-switching.md` -- [ ] **Step 1: Write docs/guides/trip-switching.md** +- [x] **Step 1: Write docs/guides/trip-switching.md** Create `/home/mischa/Nextcloud/Projects/travel-blog-intotheeast/docs/guides/trip-switching.md` with this content: @@ -551,10 +551,10 @@ When you start a new trip, **two files must be updated together** — if only on ## Checklist -- [ ] Update `user/config/site.yaml` → `active_trip` -- [ ] Update `user/pages/02.post/post-form.md` → `pageconfig.parent` -- [ ] Create the new trip page tree (see below) -- [ ] Run `make content-push` to push the changes to production +- [x] Update `user/config/site.yaml` → `active_trip` +- [x] Update `user/pages/02.post/post-form.md` → `pageconfig.parent` +- [x] Create the new trip page tree (see below) +- [x] Run `make content-push` to push the changes to production --- @@ -634,7 +634,7 @@ After pushing, check: 3. Map at `/trips//map` shows the correct (empty or GPX-only) state ``` -- [ ] **Step 2: Verify** +- [x] **Step 2: Verify** ```bash grep -c "checklist\|Checklist" /home/mischa/Nextcloud/Projects/travel-blog-intotheeast/docs/guides/trip-switching.md @@ -644,7 +644,7 @@ grep -c "pageconfig.parent" /home/mischa/Nextcloud/Projects/travel-blog-intothee # Expected: >= 2 ``` -- [ ] **Step 3: Commit** +- [x] **Step 3: Commit** ```bash cd /home/mischa/Nextcloud/Projects/travel-blog-intotheeast @@ -660,7 +660,7 @@ git commit -m "docs: add trip switching guide" - Create: `docs/guides/local-setup.md` - Modify: `CLAUDE.md` — replace §2 with pointer; add superpowers skill path overrides -- [ ] **Step 1: Write docs/guides/local-setup.md** +- [x] **Step 1: Write docs/guides/local-setup.md** Create `/home/mischa/Nextcloud/Projects/travel-blog-intotheeast/docs/guides/local-setup.md` with this content: @@ -780,7 +780,7 @@ languages: Without `include_default_lang: false`, Grav adds a language prefix to all URLs even for single-language sites. ``` -- [ ] **Step 2: Replace CLAUDE.md §2 with pointer and add skill path overrides** +- [x] **Step 2: Replace CLAUDE.md §2 with pointer and add skill path overrides** In `CLAUDE.md`, replace the entire `## 2. Local development setup` section (from `## 2.` through the end of the Language URL prefix block) with: @@ -797,7 +797,7 @@ Plans: `docs/working/plans/YYYY-MM-DD-.md` The brainstorming and writing-plans skills default to `docs/working/`; these lines override that default. ``` -- [ ] **Step 3: Verify CLAUDE.md** +- [x] **Step 3: Verify CLAUDE.md** ```bash grep -c "Local development setup" /home/mischa/Nextcloud/Projects/travel-blog-intotheeast/CLAUDE.md @@ -814,7 +814,7 @@ grep -c "First-time setup after cloning" /home/mischa/Nextcloud/Projects/travel- # Expected: 0 ``` -- [ ] **Step 4: Verify local-setup.md** +- [x] **Step 4: Verify local-setup.md** ```bash grep -c "make setup" /home/mischa/Nextcloud/Projects/travel-blog-intotheeast/docs/guides/local-setup.md @@ -824,7 +824,7 @@ grep -c "include_default_lang" /home/mischa/Nextcloud/Projects/travel-blog-intot # Expected: 1 ``` -- [ ] **Step 5: Commit** +- [x] **Step 5: Commit** ```bash cd /home/mischa/Nextcloud/Projects/travel-blog-intotheeast @@ -839,7 +839,7 @@ git commit -m "docs: extract local setup guide from CLAUDE.md; add skill path ov **Files:** - Create: `docs/reference/architecture.md` -- [ ] **Step 1: Write docs/reference/architecture.md** +- [x] **Step 1: Write docs/reference/architecture.md** Create `/home/mischa/Nextcloud/Projects/travel-blog-intotheeast/docs/reference/architecture.md` with this content: @@ -993,7 +993,7 @@ Rendered as route polyline on map | `CLAUDE.md` | Project rules and always-loaded context for Claude | ``` -- [ ] **Step 2: Verify** +- [x] **Step 2: Verify** ```bash grep -c "Plugin roles\|Template hierarchy\|GPX data flow\|Data flow for a post" \ @@ -1001,7 +1001,7 @@ grep -c "Plugin roles\|Template hierarchy\|GPX data flow\|Data flow for a post" # Expected: 4 ``` -- [ ] **Step 3: Commit** +- [x] **Step 3: Commit** ```bash cd /home/mischa/Nextcloud/Projects/travel-blog-intotheeast @@ -1018,7 +1018,7 @@ git commit -m "docs: add architecture overview reference" Four memory files still reference `docs/working/` paths. Update them to `docs/working/`. -- [ ] **Step 1: Identify affected lines** +- [x] **Step 1: Identify affected lines** ```bash MEMORY_DIR="/home/mischa/.claude/projects/-home-mischa-Nextcloud-Projects-travel-blog-intotheeast/memory" @@ -1026,7 +1026,7 @@ grep -n "docs/superpowers" "$MEMORY_DIR/MEMORY.md" "$MEMORY_DIR/feedback-plan-ex "$MEMORY_DIR/project-story-mode-and-maplibre.md" "$MEMORY_DIR/project-homepage-redesign.md" ``` -- [ ] **Step 2: Apply sed replacements** +- [x] **Step 2: Apply sed replacements** ```bash MEMORY_DIR="/home/mischa/.claude/projects/-home-mischa-Nextcloud-Projects-travel-blog-intotheeast/memory" @@ -1038,7 +1038,7 @@ for f in "$MEMORY_DIR/MEMORY.md" "$MEMORY_DIR/feedback-plan-execution-gap.md" \ done ``` -- [ ] **Step 3: Verify no old paths remain in memory** +- [x] **Step 3: Verify no old paths remain in memory** ```bash MEMORY_DIR="/home/mischa/.claude/projects/-home-mischa-Nextcloud-Projects-travel-blog-intotheeast/memory" @@ -1046,7 +1046,7 @@ grep -r "docs/superpowers" "$MEMORY_DIR/" # Expected: no output ``` -- [ ] **Step 4: Commit memory project memory update to docs repo** +- [x] **Step 4: Commit memory project memory update to docs repo** Memory files are not in the git repo, so no commit needed. But update the memory pointer in MEMORY.md to reference the plans stored at their new location. @@ -1058,7 +1058,7 @@ grep "plans\|specs\|superpowers\|working" \ # Expected: all plan/spec references point to docs/working/, none to docs/working/ ``` -- [ ] **Step 5: Final verification — complete restructure** +- [x] **Step 5: Final verification — complete restructure** ```bash cd /home/mischa/Nextcloud/Projects/travel-blog-intotheeast @@ -1088,7 +1088,7 @@ grep "docs/working/specs\|docs/working/plans" CLAUDE.md # Expected: 2 lines ``` -- [ ] **Step 6: Commit final state** +- [x] **Step 6: Commit final state** ```bash cd /home/mischa/Nextcloud/Projects/travel-blog-intotheeast