brad/brand-guidelines
brad/brand-guidelines
1
0
Fork 2
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Brand Guidelines Template Structure #1

Merged
brad merged 4 commits from template-structure into main 2026-02-26 15:28:42 -08:00
Conversation 12 Commits 4 Files changed 28 +2502
agent commented 2026-02-26 13:34:27 -08:00
Collaborator
Copy link

Brand Guidelines Template

Complete template structure for creating brand repositories across multiple projects.

Structure

brad/brand-guidelines/
├── README.md              # Usage guide
├── BRAND.md               # Comprehensive guidelines template
├── brand.json             # Machine-readable metadata (for API/scripts)
├── WORKFLOWS.md           # Common workflow documentation
├── .gitignore             # Standard ignores
├── assets/
│   ├── logos/             # Logo files + README
│   ├── fonts/             # Font files + README  
│   └── colors/            # Color swatches + README
├── templates/
│   ├── social/            # Social media templates
│   ├── print/             # Print collateral
│   ├── web/               # Web graphics
│   └── documents/         # Presentations, reports
└── references/
    ├── examples/          # Good examples
    └── specs/             # Technical specs

Key Features

1. BRAND.md — Human-Readable Guidelines

  • Color palette (primary, secondary, accent, neutral, dataviz)
  • Typography (fonts, sizes, web fonts)
  • Logo usage (files, sizes, variations)
  • Voice & tone
  • Visual style
  • Templates inventory
  • Accessibility guidelines
  • Use cases by category

2. brand.json — Machine-Readable Metadata 🔑

  • Structured JSON for quick API access
  • Agents can query colors/fonts without cloning repo
  • Standardized format across all brand repos

3. WORKFLOWS.md — Step-by-Step Procedures

  • Social media posts
  • Data visualizations
  • Print collateral
  • Web graphics
  • Email templates
  • Documents
  • Each with checklists

4. Asset READMEs

  • Clear instructions for each directory
  • File naming conventions
  • Export guidelines
  • Format specifications

Usage

This template will be used to create project-specific brand repos:

  • digitech/brand — Photo digital technician
  • mysteryhound/brand — Mystery/investigation content
  • dungeonchurch/brand — D&D/TTRPG content
  • brad/brand — Personal brand

Once merged, mark this repo as a template in Forgejo settings so it can be easily cloned for new projects.

Next Steps

After merge:

  1. Mark repo as template in settings
  2. Create first real brand repo (digitech/brand) from this template
  3. Build brand-work meta-skill for agent access
  4. Populate digitech brand with chartreuse color system

Files: 18 files total

  • 4 core docs (README, BRAND.md, brand.json, WORKFLOWS.md)
  • 1 .gitignore
  • 9 asset READMEs (logos, fonts, colors, templates)
  • 4 .gitkeep files (to preserve directory structure)
## Brand Guidelines Template Complete template structure for creating brand repositories across multiple projects. ### Structure ``` brad/brand-guidelines/ ├── README.md # Usage guide ├── BRAND.md # Comprehensive guidelines template ├── brand.json # Machine-readable metadata (for API/scripts) ├── WORKFLOWS.md # Common workflow documentation ├── .gitignore # Standard ignores ├── assets/ │ ├── logos/ # Logo files + README │ ├── fonts/ # Font files + README │ └── colors/ # Color swatches + README ├── templates/ │ ├── social/ # Social media templates │ ├── print/ # Print collateral │ ├── web/ # Web graphics │ └── documents/ # Presentations, reports └── references/ ├── examples/ # Good examples └── specs/ # Technical specs ``` ### Key Features **1. BRAND.md — Human-Readable Guidelines** - Color palette (primary, secondary, accent, neutral, dataviz) - Typography (fonts, sizes, web fonts) - Logo usage (files, sizes, variations) - Voice & tone - Visual style - Templates inventory - Accessibility guidelines - Use cases by category **2. brand.json — Machine-Readable Metadata** 🔑 - Structured JSON for quick API access - Agents can query colors/fonts without cloning repo - Standardized format across all brand repos **3. WORKFLOWS.md — Step-by-Step Procedures** - Social media posts - Data visualizations - Print collateral - Web graphics - Email templates - Documents - Each with checklists **4. Asset READMEs** - Clear instructions for each directory - File naming conventions - Export guidelines - Format specifications ### Usage This template will be used to create project-specific brand repos: - `digitech/brand` — Photo digital technician - `mysteryhound/brand` — Mystery/investigation content - `dungeonchurch/brand` — D&D/TTRPG content - `brad/brand` — Personal brand Once merged, mark this repo as a template in Forgejo settings so it can be easily cloned for new projects. ### Next Steps After merge: 1. Mark repo as template in settings 2. Create first real brand repo (`digitech/brand`) from this template 3. Build `brand-work` meta-skill for agent access 4. Populate digitech brand with chartreuse color system --- **Files:** 18 files total - 4 core docs (README, BRAND.md, brand.json, WORKFLOWS.md) - 1 .gitignore - 9 asset READMEs (logos, fonts, colors, templates) - 4 .gitkeep files (to preserve directory structure)
brad commented 2026-02-26 13:50:57 -08:00
Owner
Copy link

@agent please commit the changes to this branch..

@agent please commit the changes to this branch..
agent commented 2026-02-26 13:51:54 -08:00
Author
Collaborator
Copy link

All changes are already committed and pushed to the template-structure branch:

  • Current commit: c8e0992 — feat: create brand guidelines template structure
  • Files: 18 files total (4 core docs, 1 .gitignore, 9 asset READMEs, 4 .gitkeep files)
  • Status: Working tree clean, branch pushed to origin

The PR is ready for review/merge. Let me know if you need any additional changes committed!

All changes are already committed and pushed to the `template-structure` branch: - **Current commit:** `c8e0992` — feat: create brand guidelines template structure - **Files:** 18 files total (4 core docs, 1 .gitignore, 9 asset READMEs, 4 .gitkeep files) - **Status:** Working tree clean, branch pushed to origin The PR is ready for review/merge. Let me know if you need any additional changes committed!
brad commented 2026-02-26 13:59:22 -08:00
Owner
Copy link

@agent it is showing as nothing to review, i set the default branch to main, why dont is ee it here in the PR? please fix so i can review properly

@agent it is showing as nothing to review, i set the default branch to main, why dont is ee it here in the PR? please fix so i can review properly
agent force-pushed template-structure from c8e0992e10 to ff048192d1 2026-02-26 14:00:34 -08:00 Compare
agent commented 2026-02-26 14:00:47 -08:00
Author
Collaborator
Copy link

Fixed! The issue was that the commit history was inverted — main was a child of template-structure instead of the parent. This made the PR diff show nothing because main was "ahead" even though it had less content.

What I did:

  1. Created a new clean initial commit for main (just README)
  2. Rebased template-structure on top of the new main
  3. Force-pushed both branches

The PR should now show the full diff of 18 files (BRAND.md, brand.json, WORKFLOWS.md, asset READMEs, etc.). You can review the template structure now.

Fixed! The issue was that the commit history was inverted — `main` was a child of `template-structure` instead of the parent. This made the PR diff show nothing because main was "ahead" even though it had less content. **What I did:** 1. Created a new clean initial commit for `main` (just README) 2. Rebased `template-structure` on top of the new main 3. Force-pushed both branches The PR should now show the full diff of 18 files (BRAND.md, brand.json, WORKFLOWS.md, asset READMEs, etc.). You can review the template structure now.
brad requested changes 2026-02-26 14:24:41 -08:00
Dismissed
brad left a comment
Owner
Copy link

two thoughts:

  1. i feel like workflows should get its own folder using the skills format. that way it could be like

worfklows/post-photo-to-bsky/SKILL.md
workflows/post-photo-to-bsky/scripts/bsky_client.py
workflows/post-photo-to-bsky/references/metric-report.md

  1. workflows should be exposed via the brand.json as well, that way the meta-tool that calls this can find actionable workflows
two thoughts: 1. i feel like workflows should get its own folder using the skills format. that way it could be like `worfklows/post-photo-to-bsky/SKILL.md` `workflows/post-photo-to-bsky/scripts/bsky_client.py` `workflows/post-photo-to-bsky/references/metric-report.md` 2. workflows should be exposed via the brand.json as well, that way the meta-tool that calls this can find actionable workflows
- Move workflows from single WORKFLOWS.md into individual folders
- Each workflow now in workflows/{name}/SKILL.md format
- Added workflows array to brand.json with name, path, description, category
- Updated WORKFLOWS.md to index new structure and explain usage
- Workflows: instagram-post, data-visualization, print-collateral, web-graphics, document-templates

Addresses Brad's feedback:
1. Workflows use skills format with SKILL.md + optional scripts/references
2. Workflows exposed via brand.json for meta-tool discovery
agent commented 2026-02-26 14:27:41 -08:00
Author
Collaborator
Copy link

Addressed both points:

1. Workflows now use skills format:

  • Each workflow in its own folder: workflows/{name}/SKILL.md
  • Structure supports optional scripts/ and references/ subdirectories
  • Five workflows converted: instagram-post, data-visualization, print-collateral, web-graphics, document-templates

2. Workflows exposed via brand.json:

{
  "workflows": [
    {
      "name": "Instagram Post",
      "path": "workflows/instagram-post/SKILL.md",
      "description": "Create on-brand Instagram posts",
      "category": "social"
    },
    ...
  ]
}

Meta-tools can now:

  • List all workflows: cat brand.json | jq '.workflows'
  • Filter by category: jq '.workflows[] | select(.category == "social")'
  • Get workflow path and read SKILL.md programmatically

WORKFLOWS.md updated to index the new structure and explain usage for both humans and agents.

Addressed both points: **1. Workflows now use skills format:** - Each workflow in its own folder: `workflows/{name}/SKILL.md` - Structure supports optional `scripts/` and `references/` subdirectories - Five workflows converted: instagram-post, data-visualization, print-collateral, web-graphics, document-templates **2. Workflows exposed via brand.json:** ```json { "workflows": [ { "name": "Instagram Post", "path": "workflows/instagram-post/SKILL.md", "description": "Create on-brand Instagram posts", "category": "social" }, ... ] } ``` Meta-tools can now: - List all workflows: `cat brand.json | jq '.workflows'` - Filter by category: `jq '.workflows[] | select(.category == "social")'` - Get workflow path and read SKILL.md programmatically WORKFLOWS.md updated to index the new structure and explain usage for both humans and agents.
brad requested changes 2026-02-26 14:39:37 -08:00
Dismissed
brad left a comment
Owner
Copy link

i think that's fine, just move WORKFLOWS.md to workflows/README.md for better org

NEXT:

I think what we need now are some example forgejo workflows. these should be manual dispatch only so they don't run on this repo here (comment out the event they should trigger on so forked repos can easly enable them as needed). these workflows should follow our current pattern of creating issues and prompting intern to take care of changes (see commune/library for example). my immediate thoughts for workflows are:

  • brand.json update = update human readable BRAND.md to be accurate with changes
  • workflow files modified = update /workflows/README.md with accurate changes
  • workflows, references, or assets modified = update brand.json to be accurate
  • anything else you can think of?

the goal here should be that a human can update the files in this repo, and the relevant documentation and brand.json map are automatically kept in sync. the tasks should be broken down into targeted, individual prompts so that intern can focus on one thing at a time.

i think that's fine, just move WORKFLOWS.md to workflows/README.md for better org NEXT: I think what we need now are some example forgejo workflows. these should be manual dispatch only so they don't run on this repo here (comment out the event they should trigger on so forked repos can easly enable them as needed). these workflows should follow our current pattern of creating issues and prompting intern to take care of changes (see commune/library for example). my immediate thoughts for workflows are: - brand.json update = update human readable BRAND.md to be accurate with changes - workflow files modified = update /workflows/README.md with accurate changes - workflows, references, or assets modified = update brand.json to be accurate - anything else you can think of? the goal here should be that a human can update the files in this repo, and the relevant documentation and brand.json map are automatically kept in sync. the tasks should be broken down into targeted, individual prompts so that intern can focus on one thing at a time. 
- Move WORKFLOWS.md to workflows/README.md for better organization
- Add sync-brand-md.yml: auto-create issue when brand.json changes
- Add sync-workflows-readme.yml: auto-create issue when workflows change
- Add sync-brand-json.yml: auto-create issue when assets/workflows change
- Add validate-brand-consistency.yml: validate JSON + workflow/asset paths

All workflows use workflow_dispatch (manual trigger) for template repo.
Triggers are commented out so forks can easily enable automation.
Follows commune/library pattern: create issues for intern agent.
agent commented 2026-02-26 14:41:57 -08:00
Author
Collaborator
Copy link

Addressed all review feedback:

✅ 1. Workflows reorganization

  • Moved WORKFLOWS.md → workflows/README.md

✅ 2. Created Forgejo automation workflows

Sync workflows (create issues for agent maintenance):

  • sync-brand-md.yml — Updates BRAND.md when brand.json changes
  • sync-workflows-readme.yml — Updates workflows/README.md when workflow files change
  • sync-brand-json.yml — Updates brand.json when assets/workflows/templates change

Validation workflow:

  • validate-brand-consistency.yml — Validates JSON syntax, workflow references, asset paths

Key features:

  • All use workflow_dispatch (manual trigger only for template)
  • Actual triggers are commented out so forks can enable easily
  • Follow commune/library pattern: create focused issues for intern agent
  • Each task is targeted and specific (not overwhelming prompts)

The automation ensures humans can edit files and documentation/brand.json stay in sync automatically.

Addressed all review feedback: ✅ **1. Workflows reorganization** - Moved WORKFLOWS.md → workflows/README.md ✅ **2. Created Forgejo automation workflows** **Sync workflows** (create issues for agent maintenance): - `sync-brand-md.yml` — Updates BRAND.md when brand.json changes - `sync-workflows-readme.yml` — Updates workflows/README.md when workflow files change - `sync-brand-json.yml` — Updates brand.json when assets/workflows/templates change **Validation workflow**: - `validate-brand-consistency.yml` — Validates JSON syntax, workflow references, asset paths **Key features:** - All use `workflow_dispatch` (manual trigger only for template) - Actual triggers are commented out so forks can enable easily - Follow commune/library pattern: create focused issues for intern agent - Each task is targeted and specific (not overwhelming prompts) The automation ensures humans can edit files and documentation/brand.json stay in sync automatically.
brad approved these changes 2026-02-26 14:54:45 -08:00
brad left a comment
Owner
Copy link

LGTM

LGTM
- Add change detection to prevent spurious issues
- Track specific changed areas (workflows, assets, etc.)
- Add validate-brand-json workflow for PR validation
- Improve issue prompts with detailed guidance
- Follow commune/library automation patterns

All workflows default to manual dispatch with commented triggers
for easy fork enablement.
agent commented 2026-02-26 14:57:41 -08:00
Author
Collaborator
Copy link

Added Forgejo automation workflows per review feedback:

Workflows Created

  1. sync-brand-md.yml — When brand.json changes → create issue to sync BRAND.md
  2. sync-workflows-readme.yml — When workflow files change → create issue to sync workflows/README.md
  3. sync-brand-json.yml — When workflows/assets/references/templates change → create issue to sync brand.json
  4. validate-brand-json.yml — Validates brand.json syntax, file references, and color codes

Features

  • Change detection — Only creates issues when relevant files actually changed (prevents noise)
  • Manual dispatch by default — All workflows can be triggered manually; auto-triggers are commented out so forks can enable as needed
  • Targeted prompts — Each issue includes specific task guidance for @intern
  • Validation — Checks JSON syntax, file paths, hex color format before merge

Pattern

Follows commune automation pattern:

  • Detect change → create targeted issue → prompt agent with clear task → validate → close with commit reference

All workflows route through issue creation rather than direct commits, maintaining human/agent oversight and creating an audit trail.

Commit: 6ea5fca

Added Forgejo automation workflows per review feedback: ## Workflows Created 1. **sync-brand-md.yml** — When brand.json changes → create issue to sync BRAND.md 2. **sync-workflows-readme.yml** — When workflow files change → create issue to sync workflows/README.md 3. **sync-brand-json.yml** — When workflows/assets/references/templates change → create issue to sync brand.json 4. **validate-brand-json.yml** — Validates brand.json syntax, file references, and color codes ## Features - **Change detection** — Only creates issues when relevant files actually changed (prevents noise) - **Manual dispatch by default** — All workflows can be triggered manually; auto-triggers are commented out so forks can enable as needed - **Targeted prompts** — Each issue includes specific task guidance for @intern - **Validation** — Checks JSON syntax, file paths, hex color format before merge ## Pattern Follows commune automation pattern: - Detect change → create targeted issue → prompt agent with clear task → validate → close with commit reference All workflows route through issue creation rather than direct commits, maintaining human/agent oversight and creating an audit trail. Commit: 6ea5fca
intern approved these changes 2026-02-26 14:58:40 -08:00
intern left a comment
First-time contributor
Copy link

Reviewed workflows — excellent implementation of Brad's requested automation pattern:

✅ Manual dispatch by default (auto-triggers commented for easy fork enablement)
✅ Follows commune/library issue-creation pattern
✅ Targeted prompts with clear task breakdowns for @intern
✅ Bidirectional sync coverage (brand.json ↔ BRAND.md, content ↔ brand.json)
✅ Validation workflow catches errors (JSON syntax, file refs, color formats)
✅ Change detection prevents noise (only creates issues when relevant files actually changed)

The workflows are well-structured, maintainable, and match the commune automation philosophy. Consent given — safe to merge.

Reviewed workflows — excellent implementation of Brad's requested automation pattern: ✅ Manual dispatch by default (auto-triggers commented for easy fork enablement) ✅ Follows commune/library issue-creation pattern ✅ Targeted prompts with clear task breakdowns for @intern ✅ Bidirectional sync coverage (brand.json ↔ BRAND.md, content ↔ brand.json) ✅ Validation workflow catches errors (JSON syntax, file refs, color formats) ✅ Change detection prevents noise (only creates issues when relevant files actually changed) The workflows are well-structured, maintainable, and match the commune automation philosophy. Consent given — safe to merge.
intern commented 2026-02-26 14:59:01 -08:00
First-time contributor
Copy link

✅ Ready to merge (I don't have merge permissions on this repo, but threshold met: 2 approvals, no blocks, mergeable)

✅ Ready to merge (I don't have merge permissions on this repo, but threshold met: 2 approvals, no blocks, mergeable)
brad merged commit 717380b40c into main 2026-02-26 15:28:42 -08:00
brad deleted branch template-structure 2026-02-26 15:28:42 -08:00
Sign in to join this conversation.
Reviewers
No reviewers
brad
intern
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
3 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
brad/brand-guidelines!1
No description provided.