Plan: Repo Consolidation and Documentation Hub

plan-2026-02-24-repo-consolidation Plan

plan completed

Project

Vision

pal-e is the foundation for an AI agency. "I tell an agent what to do, and it already knows my platform, my SOPs, my active projects, and where I left off." pal-e-docs is the single coordination hub — both for AI agents (who query via MCP) and humans (who browse rendered docs with diagrams). All repos consolidated on Forgejo. All documentation accessible from a single landing page.

Projects & Repos Touched

Project/Repo	Platform	Role in this plan
<strong>forgejo-sdk</strong>	GitHub → Forgejo	Migrate to Forgejo
<strong>forgejo-mcp</strong>	GitHub → Forgejo	Migrate to Forgejo
<strong>pal-e-docs-mcp</strong>	GitHub → Forgejo	Migrate to Forgejo
<strong>pal-e-docs</strong> (app)	Forgejo	Landing page + repos browse frontend
<strong>pal-e-docs</strong> (database)	MCP	Update project pages with new URLs
<strong>claude-config</strong>	Forgejo	Fix plan-skill enforcement gap

Context

The previous plan (mermaid diagrams + living documentation) is complete — all 5 phases executed, 3 PRs merged. But 3 repos (forgejo-sdk, forgejo-mcp, pal-e-docs-mcp) are still on GitHub for no good reason. The only repos that should be on GitHub are pal-e-platform and pal-e-services (chicken-and-egg: they create the Forgejo infra). Meanwhile, the browse frontend at /browse/ is a bare project list — not the documentation hub it should be.

Previous Plan

plan-2026-02-24-enforcement-unification (completed) → mermaid/living-docs (completed, not stored as note) → this plan

Decisions Made

Decision	Rationale
<strong>Keep pal-e-platform + pal-e-services on GitHub</strong>	They bootstrap Forgejo. If Forgejo dies, you need these to rebuild.
<strong>Move forgejo-sdk, forgejo-mcp, pal-e-docs-mcp to Forgejo</strong>	No technical reason for GitHub. MCP tools run locally, remote doesn't affect runtime.
<strong>Archive GitHub repos, don't delete</strong>	Read-only backup. No data loss.
<strong>No Woodpecker CI initially</strong>	Local dev tools, not deployed services. CI can be added later.
<strong>Landing page pulls from DB</strong>	Projects, repos, SOPs all queryable via SQLAlchemy. Stays current automatically.

Phases

Phase 1: Move 3 Repos to Forgejo

Goal: forgejo-sdk, forgejo-mcp, pal-e-docs-mcp live on Forgejo. GitHub copies archived.

For each repo: create empty Forgejo repo, push all branches + tags, rename remotes, close GitHub issues, archive GitHub repo, update Repo entity via MCP.

Phase 2: Enhance Browse Landing Page

Goal: /browse/ becomes the documentation hub with projects, repos, SOPs, and architecture.

Repo: pal-e-docs app (Forgejo) — issue + branch + PR

frontend.py — Add Repo import, rich landing route, /repos route
landing.html (new) — Platform overview + mermaid, projects, repos with badges, documentation links
repos.html (new) — Dedicated /browse/repos page
base.html — Nav update (Home, Repos, Tags) + badge CSS

Phase 3: Update Project Pages + Repo Entities

Goal: Project pages reflect new Forgejo URLs.

Update project-claude-config and project-pal-e-docs via MCP.

Phase 4: Fix Plan-Skill Enforcement Gap

Goal: Prevent agents from skipping /plan skill steps 6-10 when in plan mode.

Repo: claude-custom (Forgejo) — issue + branch + PR

Reference: plan-skill-enforcement-gap note (details root cause and fix options)

PostToolUse hook on EnterPlanMode — remind MCP calls required
PreToolUse hook on ExitPlanMode — warn if no plan note created
Update /plan skill instructions — clarify MCP allowed in plan mode

Verification

[ ] All 3 repos on Forgejo, GitHub archived
[ ] list_repos(project="claude-config") returns forgejo platform repos
[ ] pal-e-docs.tail5b443a.ts.net/browse/ shows rich landing page
[ ] pal-e-docs.tail5b443a.ts.net/browse/repos shows all repos
[ ] Plan-mode hooks fire correctly

Next Plan Seeds

Woodpecker CI for MCP tools
PyPI publishing from Woodpecker
Browse search bar
Deprecate Project.repo_url
pal-e-auth
Litestream backup
Move pal-e-services to Forgejo