g1-shared 📚

Cross-project playbook, conventions, rules, and templates for the Generate One platform.

---

✨ Overview

g1-shared is the coordination layer for Generate One's multi-repository infrastructure. It contains shared documentation referenced by all per-project repositories: startup sequences, role detection rules, operational rules, skill files, and dispatch templates. This repo has no services or infrastructure — it is purely documentation and templates that define how AI agents operate across the platform.

The canonical source of truth for skills, decisions, and dispatches lives in Directus (g1-brain namespace). This repo holds archive copies and cross-project operational guides.

🏗️ Repository Structure

g1-shared/
├── docs/
│   ├── playbook.md              # Startup sequence, role detection, memory patterns
│   ├── cross-project-guide.md  # Dispatch, stack isolation, unified systems
│   ├── rules/                  # Tiered operational rules (Tier 1/2/3)
│   ├── skills/                 # Role skill files (archive copies)
│   ├── playbooks/              # Specialized playbooks
│   ├── states/                 # State snapshots
│   └── lead-states/            # Lead session state
└── templates/
    ├── CLAUDE-md-template.md   # Per-project CLAUDE.md template
    └── dispatch-template.md    # Agent team dispatch format

📋 Playbook

docs/playbook.md defines how every AI agent must start a session:

1. TIME       → g1-time:current_time()       — anchor to reality
2. ROLE SKILL → Read skill for your role
3. SKILLS     → g1-brain:find_helpful_skills  — load relevant tool docs
4. MEMORY     → g1-brain:search_memory_facts  — check prior context
5. PLAN       → Read work item from Worklenz
6. ANNOUNCE   → State what you're doing
7. EXECUTE    → Do the work

📖 Roles

Role	Where	Responsibilities
Architect	Claude Desktop (CD)	Architecture decisions, phase approval, destructive actions, skill authoring
DevOps	Claude Code (CC)	Phase execution, agent team dispatch, infrastructure, labs
PM	Claude Code (CC)	Phase planning, completion verification, Worklenz/Forgejo/memory hygiene

📏 Rules

docs/rules/ contains tiered operational rules:

Tier	Scope	Examples
Tier 1	Breaking (never violate)	Deploy vs restart, network requirements, FQDN prefix
Tier 2	Important patterns	Env var updates, container naming, Coolify API behavior
Tier 3	Best practices	Local-build images, mcp-proxy flags, compose source of truth

🔧 Templates

Template	Purpose
templates/CLAUDE-md-template.md	Per-project CLAUDE.md template for new repos
templates/dispatch-template.md	Agent team dispatch format for multi-CC operations

📊 Source of Truth Matrix

Content Type	Canonical Location
Skills	Directus (g1-brain namespace)
Project instructions	generate-one repo
Decisions, dispatches, reports	Directus (g1-brain namespace)
Compose files, scripts	Per-project repos in Forgejo
Archive copies	docs/skills/, docs/states/ in this repo

🔗 Related Repos

All g1-* project repos reference g1-shared conventions:

Repo	Purpose
generate-one	Platform root — project-level docs
g1-core	Core infrastructure (PostgreSQL, Valkey)
g1-llm	LLM routing and GPU inference
g1-brain	Memory, knowledge, reasoning
svc-tools	MCP protocol layer (MetaMCP)
g1-web	Web intelligence (SearXNG + Crawl4AI)
g1-api	Fusio API gateway
g1-git	Source code management (Forgejo)
g1-auth	Single Sign-On (Authentik)

---

🛡️ Part of Generate One

Generate One — AI infrastructure that answers to you.

Self-hosted, sovereign AI platform. generate.one