From fa44b734c964f92cd8d814b773d672888f02ba46 Mon Sep 17 00:00:00 2001 From: Chad El Kurdi <162061136+Chad-Mufasax@users.noreply.github.com> Date: Tue, 26 May 2026 19:35:26 +0200 Subject: [PATCH] Align company-skeleton with vault-skeleton (Team/Agents/Decisions/Skills) + onboarding update MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit company-skeleton was missing Team/Agents/Skills as first-class folders, and had 'People/' instead of 'Team/' (schema mismatch with the personal vault). Aligned: - rename People/ → Team/ (with proper README + _template, same as vault) - add Agents/, Skills/ (new dirs, mirror vault-skeleton schema) - replace Decisions/.gitkeep with proper README + _template - keep Process/ (HR/ops, distinct from Skills/) - update company-skeleton/CLAUDE.md routing table Onboarding flow extended to cover the new folders (Team/Agents/Decisions/Skills) plus a Block 9 mentioning the optional --with-gstack flag. setup-company.sh print message lists the new folders as STEP 3 (seed entries). --- company-skeleton/Agents/README.md | 14 ++++++++++ company-skeleton/Agents/_template.md | 31 ++++++++++++++++++++++ company-skeleton/CLAUDE.md | 8 +++--- company-skeleton/Decisions/.gitkeep | 0 company-skeleton/Decisions/README.md | 17 ++++++++++++ company-skeleton/Decisions/_template.md | 31 ++++++++++++++++++++++ company-skeleton/People/.gitkeep | 0 company-skeleton/Skills/README.md | 18 +++++++++++++ company-skeleton/Skills/_template.md | 35 +++++++++++++++++++++++++ company-skeleton/Team/README.md | 15 +++++++++++ company-skeleton/Team/_template.md | 33 +++++++++++++++++++++++ onboarding/ONBOARDING.md | 17 +++++++++--- setup-company.sh | 9 ++++++- 13 files changed, 221 insertions(+), 7 deletions(-) create mode 100644 company-skeleton/Agents/README.md create mode 100644 company-skeleton/Agents/_template.md delete mode 100644 company-skeleton/Decisions/.gitkeep create mode 100644 company-skeleton/Decisions/README.md create mode 100644 company-skeleton/Decisions/_template.md delete mode 100644 company-skeleton/People/.gitkeep create mode 100644 company-skeleton/Skills/README.md create mode 100644 company-skeleton/Skills/_template.md create mode 100644 company-skeleton/Team/README.md create mode 100644 company-skeleton/Team/_template.md diff --git a/company-skeleton/Agents/README.md b/company-skeleton/Agents/README.md new file mode 100644 index 0000000..8ca6693 --- /dev/null +++ b/company-skeleton/Agents/README.md @@ -0,0 +1,14 @@ +# Agents — the AI agents the company uses + +> Same schema as `../Team/`, but for AI agents. Each agent is a first-class member of the team, not a hidden tool — name, runtime, skills, scope, track record. A new teammate (human or AI) discovers the team by browsing `Team/` + `Agents/`. + +Pattern: `Agents/{{agent-name}}.md` per agent. Start from `_template.md`. + +What goes in each file: +- Runtime (claude-code, gstack, hermes, openclaw, custom) +- Skills (cf `../Skills/`) +- Scope / owner-of +- Trigger phrases or slash commands to invoke +- Recent successes/failures + +If the company adopts **gstack**, its 23 specialists (CEO, eng manager, designer, reviewer, QA, CSO…) each get a small entry here pointing to the gstack skill file — they become known members of the team. diff --git a/company-skeleton/Agents/_template.md b/company-skeleton/Agents/_template.md new file mode 100644 index 0000000..aeb37a8 --- /dev/null +++ b/company-skeleton/Agents/_template.md @@ -0,0 +1,31 @@ +--- +type: agent +runtime: "{{RUNTIME}}" # claude-code | hermes | openclaw | custom +skills: + - "{{SKILL_NAME_1}}" + - "{{SKILL_NAME_2}}" +owner-of: + - "{{SCOPE_1}}" + - "{{SCOPE_2}}" +status: active # active | paused | retired +--- + +# {{AGENT_NAME}} + +## Runtime +{{RUNTIME}} — {{RUNTIME_DETAILS}} + +## Skills +- {{SKILL_1}} — `Skills/{{slug}}.md` +- {{SKILL_2}} — `Skills/{{slug}}.md` + +## Scope +- {{OWNED_THING_1}} +- {{OWNED_THING_2}} + +## How to invoke +- Trigger phrases: {{TRIGGER_PHRASES}} +- Slash command (if any): `/{{SLASH}}` + +## Recent +- {{YYYY-MM-DD}} — {{OUTCOME}} diff --git a/company-skeleton/CLAUDE.md b/company-skeleton/CLAUDE.md index 07afde0..575fa7a 100644 --- a/company-skeleton/CLAUDE.md +++ b/company-skeleton/CLAUDE.md @@ -6,11 +6,13 @@ Shared vault indexed as the `company` source in each member's GBrain. | Folder | Content | |---|---| | `company.md` | Identity, stack, team, conventions | -| `Decisions/` | Locked decisions (one file per decision, dated) | -| `Process/` | Recurring procedures (onboarding, deploy, incident, reconcile…) | +| `Team/` | Humans on the team — one file per person (replaces older `People/`) | +| `Agents/` | AI agents the company uses — same schema as `Team/`, both first-class | +| `Decisions/` | Locked decisions, one file per decision (`YYYY-MM-DD-.md`) | +| `Skills/` | Procedures in [gstack SKILL.md format](https://github.com/garrytan/gstack) — invokable by any agent | +| `Process/` | HR / ops / business processes (onboarding, vacation, expense) — distinct from `Skills/` | | `Projects/` | Active projects (status, roadmap, decisions) | | `Clients/` | Client/partner sheets | -| `People/` | Who does what, internal contacts | ## Contributing (open contribution) Everyone can enrich: diff --git a/company-skeleton/Decisions/.gitkeep b/company-skeleton/Decisions/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/company-skeleton/Decisions/README.md b/company-skeleton/Decisions/README.md new file mode 100644 index 0000000..f960b5e --- /dev/null +++ b/company-skeleton/Decisions/README.md @@ -0,0 +1,17 @@ +# Decisions — company-wide decisions, one file each + +> Architectural, product, business, process. Anything you'll want to answer "why did we choose X?" for, six months from now, in one query. Both humans and agents read this folder before proposing changes that overlap an existing decision. + +Pattern: `Decisions/YYYY-MM-DD-{{slug}}.md`. Start from `_template.md`. + +**Company decisions** go here. **Personal decisions** stay in each member's `~/Documents/Brain/Decisions/`. The federated query surfaces both. + +What makes a decision worth a file: +- It locks in a trade-off (cost vs perf, build vs buy, simple vs flexible) +- Reversing it would cost real time or money +- You'd want anyone joining the company to find it + +Status fields: +- `active` — current truth +- `superseded` — replaced by a newer decision (link in the file) +- `reversed` — explicitly walked back diff --git a/company-skeleton/Decisions/_template.md b/company-skeleton/Decisions/_template.md new file mode 100644 index 0000000..52cd3c2 --- /dev/null +++ b/company-skeleton/Decisions/_template.md @@ -0,0 +1,31 @@ +--- +type: decision +date: "{{YYYY-MM-DD}}" +owner: "{{OWNER}}" # person or agent +status: active # active | superseded | reversed +revisit: "{{WHEN_OR_NULL}}" # e.g. "after 1st enterprise client" or null +supersedes: "{{LINK_OR_NULL}}" +--- + +# {{DECISION_TITLE}} + +## Context +{{WHAT_TRIGGERED_THIS}} + +## Options considered +1. **{{OPTION_A}}** — {{TRADE_OFFS}} +2. **{{OPTION_B}}** — {{TRADE_OFFS}} +3. **{{OPTION_C}}** — {{TRADE_OFFS}} + +## Decision +{{WHAT_WE_CHOSE}} — because {{PRIMARY_REASON}}. + +## Trade-offs accepted +- {{COST_OR_RISK_1}} +- {{COST_OR_RISK_2}} + +## How we'll know if this was right +{{VERIFIABLE_SIGNAL_OR_DATE}} + +## Superseded by +{{LINK_IF_REVERSED}} diff --git a/company-skeleton/People/.gitkeep b/company-skeleton/People/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/company-skeleton/Skills/README.md b/company-skeleton/Skills/README.md new file mode 100644 index 0000000..98c499c --- /dev/null +++ b/company-skeleton/Skills/README.md @@ -0,0 +1,18 @@ +# Skills — invocable procedures for any agent in the company + +> One file per skill. YAML frontmatter is the [gstack](https://github.com/garrytan/gstack) **SKILL.md** format — directly usable by gstack, Claude Code, and any agent stack that respects the convention. + +**Skills are distinct from `../Process/`**: +- `Skills/` — invocable procedures with YAML triggers (an agent detects a phrase and executes the workflow). For human + AI consumption. +- `Process/` — HR / ops / business processes (onboarding flow, vacation policy, expense reimbursement). Mostly human consumption, descriptive not invocable. + +Pattern: `Skills/{{slug}}.md`. Start from `_template.md`. + +Frontmatter fields: +- `name` — slug (matches filename) +- `version` — semver, bump on behavior change +- `description` — paragraph; agent reads it to decide whether to invoke +- `allowed-tools` — security gate (which Claude Code tools the skill may use) +- `triggers` — phrases that auto-route to this skill ("when in doubt, invoke") + +A skill here is invokable by any team member's Claude Code via the trigger phrases or as a slash command. Federated with each member's personal `Skills/`. diff --git a/company-skeleton/Skills/_template.md b/company-skeleton/Skills/_template.md new file mode 100644 index 0000000..cd3511a --- /dev/null +++ b/company-skeleton/Skills/_template.md @@ -0,0 +1,35 @@ +--- +name: "{{SLUG}}" +version: "1.0.0" +description: | + {{ONE_PARAGRAPH_DESCRIBING_WHAT_THE_SKILL_DOES_AND_WHEN_TO_USE_IT}} +allowed-tools: + - Bash + - Read + - Edit +triggers: + - "{{TRIGGER_PHRASE_1}}" + - "{{TRIGGER_PHRASE_2}}" +--- + +# {{SKILL_NAME}} + +## When to invoke +- {{CONDITION_1}} +- {{CONDITION_2}} + +## Workflow +1. {{STEP_1}} +2. {{STEP_2}} +3. {{STEP_3}} + +## Examples +- **Input:** {{EXAMPLE_INPUT}} + **Output:** {{EXAMPLE_OUTPUT}} + +## Quality gates +- {{GATE_1}} +- {{GATE_2}} + +## Failure modes +- {{FAILURE_MODE_AND_WORKAROUND}} diff --git a/company-skeleton/Team/README.md b/company-skeleton/Team/README.md new file mode 100644 index 0000000..682df67 --- /dev/null +++ b/company-skeleton/Team/README.md @@ -0,0 +1,15 @@ +# Team — the humans in the company + +> One file per person on the team. Anyone (human or agent) can query this folder to answer "who knows X" or "who owns Y" across the whole team. Federated with each member's personal `Team/` → personal contacts + this shared roster surface in the same query. + +Pattern: `Team/{{firstname-lastname}}.md` per person. Start from `_template.md`. + +What lives in each file: +- Role + one-liner +- Focus areas +- What they own (projects, components, processes) +- Who they work with on what +- Contact +- Recent activity (accretes over time) + +This is the **company roster** — every member sees it, every agent sees it. AI agents live next door in `../Agents/` with the same schema. diff --git a/company-skeleton/Team/_template.md b/company-skeleton/Team/_template.md new file mode 100644 index 0000000..5fef97d --- /dev/null +++ b/company-skeleton/Team/_template.md @@ -0,0 +1,33 @@ +--- +type: team-member +role: "{{ROLE}}" +focus: + - "{{FOCUS_AREA_1}}" + - "{{FOCUS_AREA_2}}" +owner-of: + - "{{OWNED_THING_1}}" + - "{{OWNED_THING_2}}" +location: "{{LOCATION}}" +--- + +# {{FIRST_NAME}} {{LAST_NAME}} + +## Role +{{ROLE_ONE_LINER}} + +## Focus areas +- {{AREA_1}} +- {{AREA_2}} + +## Owner of +- {{OWNED_THING_1}} — {{WHAT_THAT_MEANS}} + +## Working with +- {{COLLEAGUE_1}} — {{ON_WHAT}} + +## Contact +- Email: {{EMAIL}} +- {{OTHER_CHANNEL}} + +## Recent +- {{YYYY-MM-DD}} — {{WHAT_HAPPENED}} diff --git a/onboarding/ONBOARDING.md b/onboarding/ONBOARDING.md index 83aae58..a485ad9 100644 --- a/onboarding/ONBOARDING.md +++ b/onboarding/ONBOARDING.md @@ -10,14 +10,25 @@ Replace every `{{PLACEHOLDER}}` in: - `~/Documents/Brain/Profile/stack.md` (personal tools) - `~/.claude/CLAUDE.md` (the brain-in-a-box block: {{NAME}}, {{LANGUAGE}}) +Then **seed** the team-first folders with the user's real entities (no need to fill all at once — start with what's immediately relevant): +- `~/Documents/Brain/Team/.md` (themselves, and any humans they collaborate with regularly) +- `~/Documents/Brain/Agents/.md` (any AI agent in their orbit — Hermes? gstack specialists? custom hook? — even if just stubs, declare them) +- `~/Documents/Brain/Decisions/YYYY-MM-DD-.md` (1-2 recent meaningful decisions, to amorce le pattern) +- `~/Documents/Brain/Skills/.md` (any pattern they already repeat 3+ times — easy candidates to capture) + +Each of these folders ships a `README.md` (purpose) + `_template.md` (schema). Copy `_template.md` to a real filename and fill in. + ## Flow (interview) **Block 1 — Identity**: name, city/country, education/background, GitHub, emails (work/personal), machine. **Block 2 — Work**: main role, stack/skills, domains. Company or activity (name, description, sector, stage idea/MVP/launched/scaling). **Block 3 — Projects**: main project (1 line) + other active projects. -**Block 4 — Team** (if relevant): who does what, who decides what (who to contact for X). -**Block 5 — Style**: default language, desired tone (direct/detailed), communication preferences, work preferences (plans before action? max autonomy? visible logs?). -**Block 6 — Tools/access** (no secrets): installed CLIs, cloud, DB, where secrets live (Keychain, .env) — locations, never values. +**Block 4 — Team & agents**: humans they collaborate with regularly (1 file per person in `Team/`), AI agents they use (Hermes, gstack specialists if installed, custom hooks — 1 file per agent in `Agents/`). Same schema for both. +**Block 5 — Decisions to seed** (1-3 of them): meaningful decisions they've already made and would want anyone joining to find. Capture in `Decisions/YYYY-MM-DD-.md` with context, options, trade-offs. +**Block 6 — Patterns to skillify** (optional): any procedure they repeat that could be captured as a `Skills/.md` (gstack-compatible format). +**Block 7 — Style**: default language, desired tone (direct/detailed), communication preferences, work preferences (plans before action? max autonomy? visible logs?). +**Block 8 — Tools/access** (no secrets): installed CLIs, cloud, DB, where secrets live (Keychain, .env) — locations, never values. +**Block 9 — Optional: gstack**: if the user wants 23 AI specialists (CEO/eng/QA/CSO/reviewer/release-engineer/…) alongside, suggest `./install.sh --with-gstack` and add an `Agents/.md` for each gstack skill they'll actually use. ## After the interview diff --git a/setup-company.sh b/setup-company.sh index c887c8a..f9c8d18 100755 --- a/setup-company.sh +++ b/setup-company.sh @@ -43,7 +43,14 @@ STEP 2 — fill in the company profile (you, or via Claude Code): cd $CO && claude # "Fill company.md with the company context (stack, team, conventions)." -STEP 3 — give each member the join command: +STEP 3 — seed the team-first folders (1-2 entries each is enough to start): + $CO/Team/ humans on the team (1 file per person, copy _template.md) + $CO/Agents/ AI agents the company uses (gstack specialists, Hermes, custom) + $CO/Decisions/ company-wide decisions (one file per decision, YYYY-MM-DD-.md) + $CO/Skills/ invocable procedures (gstack SKILL.md format) + $CO/Process/ HR/ops processes (onboarding, vacation, expense) — distinct from Skills/ + +STEP 4 — give each member the join command: cd brain-in-a-box && ./install.sh --company https://github.com//brain-company Members get their personal brain + the 'company' source (queryable, git-pulled nightly).