pal-e-docs

Architecture: claude-custom docs/

arch-docs-claude-custom Architecture

architecture active
Project

Architecture: claude-custom docs/

Purpose

Operational reference documentation for the claude-custom configuration system. The docs/ directory provides self-contained reference material describing the structure, behavior, and conventions of every component in the claude-custom harness.

Diagram

Components

Component Purpose Notes
<code>CLAUDE.md</code> Entry point read at session start Symlink to README.md
<code>README.md</code> Table of contents linking to all 9 docs Also contains setup instructions and symlink inventory
<code>docs/filetree.md</code> Map of every directory and key file Mermaid architecture diagram; "I want to change X, which file?"
<code>docs/hooks.md</code> Hook inventory by lifecycle event Matchers, purposes, enforcement details
<code>docs/agents.md</code> Agent types, frontmatter, spawn requirements Enforcement layers documented
<code>docs/skills.md</code> Skill definitions and frontmatter Skills vs commands distinction
<code>docs/settings.md</code> settings.json and settings.local.json layering What each section controls
<code>docs/mcp-servers.md</code> MCP server inventory What each does, where code lives, key tools
<code>docs/enforcement.md</code> Three enforcement mechanisms disallowedTools, frontmatter hooks, settings hooks
<code>docs/operations.md</code> Operational procedures Worktree isolation, post-merge sync, platform detection, pal-e-docs queries
<code>docs/platform-lifecycle.md</code> Platform onboarding and CI/CD Rails onboarding, CI/CD loop, base images, iOS pipeline, port convention

Key Decisions

  • docs/ over pal-e-docs for repo reference -- docs/ is co-located with the code it describes, version-controlled in the same repo, and available offline at session start. Pal-e-docs stores cross-project SOPs and conventions; docs/ stores repo-specific operational reference.
  • CLAUDE.md as symlink, not standalone -- README.md is the single source of truth. The symlink ensures Claude Code reads it at session start without duplicating content.
  • Each doc is self-contained -- no doc depends on reading another first. This allows agents to read only the doc relevant to their task.
  • First PR pattern -- new repos always start with CLAUDE.md symlink + README.md TOC + docs/ directory. This ensures documentation infrastructure exists before feature work begins.
  • /update-docs post-merge chain -- docs are maintained via the update-docs skill after merges, or directly during feature work in the same PR. This keeps docs synchronized with code changes.
  • project-claude-custom -- project page
  • board-claude-custom -- project board
  • enforcement-architecture -- defense-in-depth enforcement note
  • agent-workflow -- main session owns docs, agents own repos
  • feedback_first-pr-pattern -- memory file documenting the first PR convention
  • arch-mac-bootstrap, arch-asc-provider, arch-tofu-consumers -- sibling arch notes in other projects