Francesco + Claude — System Overview

Updated April 2026 · Served from CT200

What's Outdated in the Previous Guide

7 things that changed since the last guide was written
  • Knowledge base was _Meta/knowledge/ → now _Meta-Knowledge/ (separate git repo)
  • Daily journal was _Meta/Journal/ → now _Meta-Journal/ (separate git repo)
  • Binary files: "natural filesystem locations" → now strict Documents/ folder with mirrored paths per machine
  • Git push: "always manual, never automatic" → now auto-push at every session close (pre-authorised)
  • External repos: flat folder → now live under _External/{github-owner}/{repo}/
  • Session-start trace (Rule A): not mentioned at all — Claude writes a trace line to reminders.md at every session start
  • Session-close sequence: missing the 3-step order: clean Rule A → commit _Meta → commit projects

Workspace Structure

Everything lives in one root at /root/_AiWorkspace/ (CT200) or /Users/francescorinaldi/_AiWorkspace/ (laptop). The layout is flat — personal projects sit directly at the root.

_AiWorkspace/
├── _Meta/ ← hub: registries, CLAUDE.md, reminders.md
├── _Meta-Knowledge/ ← separate repo: one .md per tag
├── _Meta-Guides/ ← separate repo: human-readable reference files
├── _Meta-Journal/ ← separate repo: daily journal entries
├── ProjectName/ ← personal projects, PascalCase, flat
├── AnotherProject/
├── _External/
│ └── github-owner/
│ ├── repo-name/ ← external clone (contribute via PRs)
│ └── repo-name-Twin/ ← your notes: rules.md + session-log.md
└── OLD/ ← read-only archive
Three Registries (inside _Meta/)
projects.csv — id, name, status, github_remote, description
project-tags.csv — project_id, tag (one row per pair)
tags.csv — tag, description (Con, Hom, Her, Pro, Cat, Cf…)
Before Creating Any Project
Claude reads projects.csv first and checks whether something related already exists. If yes, you get a prompt to confirm it's genuinely a new project.
Binary Files (PDFs, images)
Never in git. Stored at Documents/[tag]/[mirrored path]/[file]. All registered in _Meta/documents-registry.csv. Always check the registry before Finder.
Entity Tags
Con Concord   Hom Homelab
Her Hermione   Pro Prometeo
Tags live in tags.csv, not in folder names.

Session Start — What Happens Every Time

The very first action is unconditional: git pull in _Meta. Then Claude reads your first message and follows this path.

1. git pull _Meta unconditional first action 2. Read first user prompt extract topic + tags Detect Location Case B workspace root Case C outside workspace Case A — inside project Ask: new project? 2 confirmations needed to work at root level Warn user outside _AiWorkspace not the agreed setup rules.md exists? YES Read rules.md apply as project rules NO Check git remote External repo? → find Twin, read its rules.md No remote? → inform user 5. Pull _Meta-Knowledge clone if not present locally · git pull if exists 6. Read {tag}.md files one per matched tag · auto-loaded · cross-project context 7. Write session-start trace append one line to _Meta/reminders.md [date machine] Session open — project — "first prompt" ★ WORK ★ — session ends (see Session Close) — SESSION START — STEP SUMMARY 1. git pull _Meta (unconditional) 2. Read first user prompt, extract topic and tags 3. Detect location: Case A (inside project) / Case B (workspace root) / Case C (outside workspace) 4. Read rules.md — or find the Twin folder for external repos 5. Pull _Meta-Knowledge (clone if new machine) 6. Read {tag}.md for each matched tag 7. Write session-start trace to _Meta/reminders.md (crash-safe marker)

Session Close — Pre-Authorised, Automatic

When Francesco says "close session", all steps below run without asking for permission. Claude prints a summary at the end.

Francesco: "close session" all steps below run without confirmation Step 1 — Remove session-start trace delete the Rule A line from _Meta/reminders.md this marks the session as cleanly closed Step 2 — Write session-log.md date · 4–6 bullets · decisions + next steps · WHY not WHAT keep last 10 entries · remove oldest when exceeded Step 3 — Update knowledge files if new knowledge gained: update _Meta-Knowledge/{tag}.md commit + push _Meta-Knowledge Step 4 — Commit + push _Meta captures reminders.md cleanup + any other _Meta changes Step 5 — Commit + push project repo(s) all repos worked on during the session Session closed Claude prints a summary of what was done END OF DAY (separate from session close) Triggered by: "close day" or "end of day" or "write journal" Pull _Meta-Journal → read all today's session-logs → write _Meta-Journal/YYYY-MM-DD.md → commit + push

Knowledge System

The knowledge base lives in its own git repo: _Meta-Knowledge/. One Markdown file per tag, named exactly after the tag (e.g. concord.md, homelab.md). At session start, Claude loads only the files that match the current project's tags.

How Knowledge is Loaded
1. Read first prompt → extract topic
2. Look up tags.csv + project-tags.csv
3. Pull _Meta-Knowledge
4. Read {tag}.md for each match
Result: full context, no manual recap
Growth Rule
Files start flat. When any section exceeds ~50 lines: extract to {tag}-{subtopic}.md and replace with a one-line summary + link. The parent file becomes an index.
Voice Files (special type)
concord-voice.md, personal-voice.md etc.
Top: style principles, tone, audience, themes.
Bottom: chronological archive of past writing. Enables consistent style across months.
Cross-Project by Design
Knowledge is indexed by tag, not by project. Something learned in Concord-Pitch is automatically available in any future project tagged Con — no copy-pasting needed.

The Three Separate Repos

Three repos sit alongside the workspace and are pulled only when needed:

_Meta-Knowledge/
Pulled at every session start (if relevant tags exist). Updated at session close if new knowledge was gained. Never auto-pulled in full — only relevant tag files are read.
_Meta-Guides/
Human-readable reference files, how-tos, translated documents. Never auto-pulled — pull manually only when needed. This file lives here.
_Meta-Journal/
Daily journal entries at YYYY-MM-DD.md. Pulled and written only when Francesco says "end of day" or "write journal". Not a session log — a human-readable personal recap.

Git and GitHub Rules

Every Project is a Repo from Day One
git init + .gitignore + initial commit on creation.
Standard ignore: .DS_Store, _archive/, *.pdf.
Private GitHub repo created and connected as part of setup.
Push is Automatic at Session Close
Unlike in the old guide, push to GitHub is automatic at every session close — pre-authorised. Francesco works across multiple machines and needs repos always in sync.
Commit Messages
Short and descriptive. Focus on the why, not the what. Format: [what changed and why]. Git diff already shows what changed — the message explains the decision.
External Repos
Repos owned by others: contribute via branches and PRs only. Never commit to main directly. Personal notes go in the Twin folder, not in the upstream repo.

Safety Rules — When Claude Stops and Asks

Always stops first
• Change would touch more than 5 files
• Authentication, payments, or personal data
• Installing new dependencies
• Deleting files
• Tests fail
Always proceeds without asking
• Reading files
• Writing session-log.md at session close
• Committing and pushing at session close
• Pulling knowledge files at session start
• Writing session-start trace to reminders.md
Language rules
No flattery, no filler phrases. Direct answers. Jargon always explained — Francesco does not have a technical background. Admit uncertainty rather than guessing.
Cost equation
Cost of asking = zero.
Cost of a wrong action = high.
When in doubt, ask. The system is designed to remove friction, not to act recklessly.

System overview · Updated April 2026 · Served from CT200 · Source: _Meta-Guides/system-overview.html