🗺️ PAM - Project Architectural Maps

PAM is an anagram of MAP. That is intentional. The acronyms are load-bearing. So is your architecture — PAM finds out which parts are 🍑.

PAM scans your monorepo (or multi-repo system), reads every README and project structure, and tells you which parts are 🍑 ASS and which are just PASS.

The Naming Convention

These are not jokes. They are the literal filenames.

Term	Stands for	What it means
PAM	Project Architectural Maps	The tool itself
MAP	(anagram of PAM)	The visual file-tree artifact PAM generates
🍑 ASS	Architectural System Significance	This project is load-bearing — remove it and other systems break
PASS	Project-Architectural Semi-Significance	Matters internally, but the rest of the system doesn't care if it disappears
🍑 ReadMyAss	(literal filename)	Human-readable map with a “You Are Here” marker. Like a README, but for your architecture

Your monorepo gets rated. Every project is either 🔴🍑 ASS (system-critical) or 🟡 PASS (self-contained). The ones that are both? That’s where you pay attention.

The Problem

Nobody documents architecture. README files rot. New developers guess at relationships. AI agents hallucinate dependencies. One project gets renamed and three downstream systems break because nobody mapped the dependency graph.

PAM fixes this by generating a multi-layer map that actually stays current:

• ASS_MASTER.md 🍑 — The most important file. Which projects are architecturally significant, what depends on what, and what breaks if something disappears
• ReadMyAss.md - Human-readable narrative with Mermaid diagrams and a "You Are Here" breadcrumb
• PAM_Master.md - Quick visual tree with ⭐ markers on the load-bearing projects
• PASS.md - Per-project: what matters inside this project even if nobody else cares

Third-Party Repo Evaluation

Drop in a link to any public repo, npm package, or tool and ask:

"Would this benefit my system?"

PAM reads the repo, compares it against ASS_MASTER.md 🍑, and gives you a verdict:

Verdict	Translation
✅ ADDS VALUE	Real gap-fill. PAM names exactly where it slots in
🟡 MAYBE	Some overlap. PAM names the conditional
🔴 REDUNDANT	You already have something that does this
⚠️ COULD CONFLICT	Port collision, hook overlap, or it'll step on something running
⛔ NOT USEFUL	Wrong domain, wrong runtime, abandoned, doesn't fit

Every verdict comes with rationale, touched systems, and a recommended action - not just a label.

📦 Install

npm install -g pam-maps

Use with AI Coding Agents

PAM works with any CLI agent - Pi, Claude Code, Codex, Cursor, Aider, or standalone. Copy the skill files into your agent config:

# Pi
cp -r skills/ ~/.pi/agent/skills/
cp agents/PAM.md ~/.pi/agent/agents/

# Claude Code / Codex / others
cp -r skills/ ~/.claude/skills/    # or ~/.codex/skills/

Then use /pam status, /pam sync, /pam evaluate <url>, etc. inside any session.

Or just talk to PAM in natural language — no slash commands required.

🚀 Usage

CLI (standalone)

# Scan your monorepo → structured JSON of every project
pam-scan /path/to/your/monorepo

# Evaluate a third-party repo without cloning it
pam-fetch https://github.com/expressjs/express

# Log a change for the next sync
pam-log --project my-api --type contract-change \
        --summary "Changed default port from 3000 to 8080" \
        --ripple "frontend, reverse-proxy"

Agent Commands

Command	What it does
/pam status	Which projects have maps, what's stale, pending changes
/pam sync	Regenerate all maps (cached — only re-syncs what changed)
/pam sync <project>	Refresh just one project's ASS/PASS/ReadMyAss files
/pam evaluate <url>	Verdict on a third-party repo against your 🍑 ASS_MASTER

PAM also responds to natural language — no slash commands needed:

• "Hey PAM, can you analyze this repo?"
• "Hey PAM, can you sync this new repo that I'm working on?"
• "PAM, would this npm package benefit my system?"
• "Hey PAM, what breaks if I delete this project?"

🔍 What PAM Generates

Master Layer (whole system)

<monorepo>/.pi/MAPS/
├── ASS_MASTER.md  🍑   ← THE important file. Global significance breakdown.
│                         "What contributes to the system, what depends on what,
│                          what breaks if this disappears."
├── ReadMyAss.md        ← Human-readable narrative. Mermaid diagrams.
│                         "You Are Here" breadcrumb navigation.
└── PAM_Master.md       ← Quick visual tree. ⭐ = ASS, 🟡 = PASS, ⚪ = neither.

Slave Layer (per-project)

<project>/.pi/MAPS/
├── ASS_SLAVE.md   🍑   ← Only the parts that affect OTHER systems.
│                         Hand-off points, shared contracts, ports, daemons.
├── PASS.md             ← What matters INSIDE this project.
│                         Hot paths, fragile glue, critical configs.
├── ReadMyAss.md        ← This project's narrative + its place in the graph.
└── PAM_Slave.md        ← Visual tree. ⭐ = files the program actually uses.

Significance Ratings

Rating	Meaning	Example
🔴🍑 ASS	Remove it and other systems break	Shared API gateway, auth service, message bus
🟡 PASS	Self-contained - the system doesn't notice if it's gone	Internal CLI tool, standalone utility
🔴🍑🟡 Both	Load-bearing and internally complex — pay attention here	Core service with fragile internal architecture

📁 Repo Structure

pam-maps/
├── agents/PAM.md              ← PAM's identity, vocabulary, and rules
├── skills/pam/SKILL.md        ← The /pam workflow (for AI agent sessions)
├── scripts/
│   ├── scan-readmes.mjs       ← Walk a monorepo, emit structured JSON
│   ├── fetch-repo-readme.mjs  ← Fetch a GitHub repo's README via API (no clone)
│   └── log-pending.mjs        ← Append/read/drain the pending change log
├── templates/
│   ├── ASS_MASTER.template.md 🍑 ← Template for the global significance file
│   ├── ASS_SLAVE.template.md  🍑 ← Template for per-project significance
│   ├── PASS.template.md       ← Template for internal significance
│   ├── ReadMyAss_*.template.md 🍑 ← Templates for human-readable narratives
│   ├── PAM_*.template.md      ← Templates for visual maps
│   └── pre-commit-pam-check.sh ← Git hook: warns on ASS-significant changes
├── prompts/pam.md             ← Slash command entry point
└── package.json

⚙️ Configuration

# Set your monorepo root (or PAM defaults to cwd)
export PAM_ROOT=/path/to/your/monorepo
pam-scan

# Or pass it directly
pam-scan /path/to/monorepo

PAM reads READMEs to understand project roles. No Nx, Turborepo, or Lerna config required - any directory with a README is a project.

🤝 Contributing

PRs welcome. If your monorepo has a structure PAM doesn't handle well, open an issue.

📄 License

MIT - built by @CymatiStatic

---

_{🍑 Yes, you will have files named ASS_MASTER.md and ReadMyAss.md in your repo. Your coworkers will ask questions. That's a feature. 🍑}