pal-e-docs

Plan: Docs Foundation

plan-2026-02-24-docs-foundation Plan

plan completed
Project

Plan: Docs Foundation

Vision

pal-e-docs is the development operating system. Documentation is king. Every hook event is a documentation check-in opportunity. Plans live as notes, link to each other, and agents find them automatically. Templates are enforced, not suggested. The note system is solid before we build on top of it. And the data is backed up — because 35+ notes of hard-won knowledge deserve durability.

Projects & Repos Touched

Project/Repo Platform Role in this plan
pal-e-docs app Forgejo Landing page, browse frontend enhancements
pal-e-docs-mcp Forgejo MCP tool improvements
claude-custom Forgejo SessionStart plan injection, PreToolUse hooks (Task, create_note), skills
pal-e-platform GitHub MinIO deployment (see <code>plan-2026-02-24-minio-object-storage</code>)

Context

What's done:
  • 35+ notes, 5 projects, 8 repos, tag-based type system operational
  • Plan template with recursive structure documented
  • Hook events reference note created (see hook-events-reference)
  • Enforcement architecture documented (see enforcement-architecture)
  • Plan mode removed — plans are just notes, no special mode needed
  • Repo consolidation complete — all repos on Forgejo except bootstrap repos
  • Landing page shipped with architecture diagram
  • Phase 1 complete: note-conventions, agent-paradigm, html-style-guide created, note_links backfilled across 10 notes
  • Phase 2 complete: check-agent-spawn.sh hook deployed (PR #23 merged). "No plan, no agent" axiom enforced.
  • Phase 3 complete: SessionStart injects all active plans cross-project + convention refs always injected (PR #25 merged).
  • Phase 4 redefined: Markdown conversion killed. Template enforcement promoted to its own plan: plan-2026-02-25-template-enforcement.
  • Phase 5 complete: Doc check-in hooks deployed (PR #33 merged). PostToolUse on merge reminds to update project page. Stop hook reminds to update docs before session end.
The gaps:
  • Templates exist but are advisory — no enforcement at hook level. See plan-2026-02-25-template-enforcement.
  • No backup strategy for SQLite database — data loss risk

Previous Plan

plan-2026-02-24-repo-consolidation (completed)

Depends On

Phase 6 depends on plan-2026-02-24-minio-object-storage (MinIO must be deployed before Litestream can replicate to it).

Decisions Made

Decision Rationale
Kill plan mode entirely Plans are notes in pal-e-docs. No special permission mode needed.
Descriptive slugs over zettelkasten IDs Slugs are human-readable AND machine-guessable.
Tags are the type system No NoteType column. Type determined by tags: <code>plan,active</code> vs <code>sop,active</code> vs <code>issue,open</code>.
Templates enforced at hook level via PreToolUse Hooks gate tool calls at point of action. Templates fetched from pal-e-docs dynamically.
Dense linking over sparse Every note should link to related notes via <code>note_links</code>.
Phases can become plans with user approval Recursive plan structure. Prevents scope creep.
Events → Hooks → MCP → Skills → Agents Corrected 5-layer paradigm with directional flow.
SessionStart queries ALL active plans cross-project Plans span repos/projects.
No plan, no agent (the axiom) PreToolUse hook on Task tool. Simple <code>plan-</code> pattern check.
Main session owns docs, agents own repos Clean separation of concerns.
Hook applies to ALL Task spawns including reviews PR reviews should happen in context of a plan too.
Convention references always injected <code>agent-spawn-conventions</code> and <code>agent-workflow</code> injected even when pal-e-docs is unreachable.
Issues tracked as notes, not Forgejo issues All knowledge in one system. Issues are notes tagged <code>issue,open</code>. Project pages have issues tables. User stories belong on issues, not project pages.
One-way relationships (parent → child) Projects link to repos/plans/issues. Children don't need to point back. Keeps things flexible — repos/plans can serve multiple projects.
Roadmaps are plan tables on project pages Not separate entities. Project page IS the roadmap. Links to plan notes with status.
Kill markdown conversion for pal-e-docs Only PRs/issues need markdown, and those live on Forgejo already. No need to add markdown_content to notes. Templates are HTML in pal-e-docs, agents naturally write markdown for Forgejo.
Stop hook is remind-only, not blocking Blocking a Stop feels aggressive. Reminder context is sufficient for main session to act on.
Stop hook fires for main session only Stop event is inherently main-session-only. SubagentStop is a separate event. Subagents don't touch docs per agent-workflow SOP.

Phases

Phase 1: Conventions & Paradigm Documentation — COMPLETE

Completed 2026-02-24:
  • note-conventions, agent-paradigm, html-style-guide created
  • note_links backfilled on 10 notes

Phase 2: Agent Spawn Quality Enforcement — COMPLETE

Completed 2026-02-25:
  • check-agent-spawn.sh PreToolUse hook deployed — PR #23 merged on claude-custom

Phase 3: SessionStart Plan Injection — COMPLETE

Completed 2026-02-25:
  • SessionStart injects all active plans + convention refs — PR #25 merged on claude-custom

Phase 4: Template Enforcement — PROMOTED TO PLAN

Promoted 2026-02-25: Markdown conversion killed. Template enforcement promoted to plan-2026-02-25-template-enforcement.
PreToolUse hooks on submit_pr and create_issue that validate bodies against templates fetched from pal-e-docs.

Phase 5: Documentation Check-in Hooks — COMPLETE

Completed 2026-02-26:
  • remind-update-docs.sh PostToolUse hook on mcp__forgejo__merge_approved_pr — PR #33 merged on claude-custom
  • stop-doc-checkin.sh Stop hook — remind-only, main session only
  • Issue: issue-doc-checkin-hooks (resolved)

Phase 6: DB Backup via Litestream → MinIO

Goal: Continuous SQLite replication to MinIO.
Depends on: plan-2026-02-24-minio-object-storage
Repo: pal-e-docs (Forgejo)
  • Add Litestream sidecar to k8s deployment
  • Configure replication to s3://litestream-backups/pal-e-docs/
  • Test restore
  • Document restore procedure as SOP

Key Files

Phase File Repo Change
1 (MCP operations only) pal-e-docs DB DONE
2 ~/.claude/hooks/check-agent-spawn.sh claude-custom DONE
3 ~/.claude/hooks/session-start-context.sh claude-custom DONE
4 {"html" => "Promoted to <code>plan-2026-02-25-template-enforcement</code>", "colspan" => 3}
5 ~/.claude/hooks/remind-update-docs.sh, stop-doc-checkin.sh claude-custom DONE
6 k8s/deployment.yaml pal-e-docs Litestream sidecar

Verification

  • [x] note-conventions note exists
  • [x] agent-paradigm note exists
  • [x] html-style-guide note exists
  • [x] note_links backfilled
  • [x] agent-spawn-conventions note exists
  • [x] agent-workflow updated with 5 rules + separation of concerns
  • [x] PreToolUse hook on Task blocks prompts without plan slug
  • [x] PreToolUse hook on Task passes prompts with plan slug
  • [x] SessionStart injects all active plans cross-project
  • [x] Templates updated: project-page, plan, issue (new), pr-body
  • [x] First issue note created (issue-mermaid-newline-bug)
  • [x] Doc check-in hooks deployed — post-merge reminder + Stop session reminder (PR #33)
  • [ ] Template enforcement hooks deployed (see plan-2026-02-25-template-enforcement)
  • [ ] Litestream replicating to MinIO

Next Plan Seeds

  • Public-facing CSS + Tailscale Funnel (see plan-2026-02-24-public-docs-and-templates)
  • Mermaid overflow/scroll fix for browse frontend
  • /new-issue and /new-project skills
  • Browse search bar
  • Asset upload API using MinIO
  • Update /review-pr skill to include plan context in review agent spawns
  • plan-2026-02-25-template-enforcement — promoted from Phase 4
  • plan-2026-02-24-minio-object-storage — Phase 6 depends on this
  • plan-2026-02-24-repo-consolidation — previous plan (completed)
  • plan-2026-02-24-public-docs-and-templates — next plan (deferred)
  • agent-spawn-conventions — the axiom
  • agent-workflow — the operating model