From 478df0b75d238bac38f4098850911809f59b4ce5 Mon Sep 17 00:00:00 2001 From: Barcode Betty Date: Tue, 14 Apr 2026 14:22:40 +0000 Subject: [PATCH] Add documentation to .github organization repository - Add README.md explaining repo purpose and folder structure - Add CONTRIBUTING.md with contribution guidelines for org-level changes - Document Paperclip, agents, and skills configuration - Add instructions for maintaining org settings --- CONTRIBUTING.md | 123 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 116 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 239 insertions(+) create mode 100644 CONTRIBUTING.md create mode 100644 README.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..76524db --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,123 @@ +# Contributing to CartSnitch Organization + +This document outlines the process for making changes to the `.github` organization repository. + +## When to Modify This Repository + +Changes to this repository are appropriate for: + +- Adding or updating organization profile content (`profile/README.md`) +- Adding new agents or modifying existing agent configurations +- Adding, removing, or updating shared skills +- Modifying Renovate configuration +- Updating company metadata +- Adding documentation about organization-wide practices + +## When NOT to Modify This Repository + +Do NOT use this repository for: + +- Application code changes (use the appropriate application repository) +- Infrastructure changes (use `cartsnitch/infra`) +- Documentation for specific applications (add to the application's repo) + +## Change Process + +### 1. Create a Branch + +Create a feature branch from `main`: + +```bash +git checkout main +git pull origin main +git checkout -b feature/your-change-name +``` + +### 2. Make Your Changes + +Make the necessary changes following the guidelines below. + +#### Adding a New Agent + +1. Create a new folder in `company/agents//` +2. Add the agent configuration to `company/.paperclip.yaml` +3. Create at minimum: + - `AGENTS.md` - Agent instructions and role definition + - `MEMORY.md` - Initial memory/knowledge base (can start empty) + +#### Adding a New Skill + +1. Create or identify the appropriate `company/skills//` folder +2. Add the skill definition to `company/.paperclip.yaml` +3. Ensure skill files exist in the appropriate subdirectory + +#### Updating Organization Profile + +1. Edit `profile/README.md` +2. Ensure any new links are valid +3. Maintain consistent formatting + +### 3. Commit Your Changes + +Commit with a clear, descriptive message: + +```bash +git add . +git commit -m "Add agent configuration" +``` + +### 4. Submit a Pull Request + +Open a PR against `main`: + +```bash +git push origin feature/your-change-name +gh pr create --base main --title "Add agent" --body "Description of changes" +``` + +### 5. Review and Merge + +- PRs require approval from the CTO (Savannah Savings) or CEO (Coupon Carl) +- After approval, the PR can be merged +- Merges to `main` are automatically deployed to the organization + +## Guidelines + +### Agent Naming + +- Use kebab-case for agent names (e.g., `barcode-betty`, `checkout-charlie`) +- Agent names should be descriptive of the role + +### Agent Configuration + +When adding or updating agents in `.paperclip.yaml`: + +- Include a clear `capabilities` description +- Set appropriate `icon` for the UI +- Configure heartbeat settings appropriately for the role: + - Engineers/QA: 14400 seconds (4 hours) + - CEO: 28800 seconds (8 hours) + - UAT (Deal Dottie): 300 seconds (5 minutes) for rapid response + +### Paperclip Configuration Schema + +The `.paperclip.yaml` uses schema version `paperclip/v1`. When editing: + +- Ensure valid YAML syntax +- Follow the existing structure and conventions +- Include all required fields for agent definitions + +### Skill Documentation + +When adding new skills: + +- Ensure the skill folder contains a `SKILL.md` file +- Include a brief description of the skill's purpose +- Reference the external source if applicable + +## Contacts + +For questions about this repository or the change process: + +- **CTO (Savannah Savings)**: Technical decisions, agent configuration +- **CEO (Coupon Carl)**: Organizational decisions, high-level direction diff --git a/README.md b/README.md new file mode 100644 index 0000000..ef91970 --- /dev/null +++ b/README.md @@ -0,0 +1,116 @@ +# CartSnitch Organization Repository + +This is the [CartSnitch](https://github.com/cartsnitch) organization health repository. It contains organization-wide configuration, company metadata, agent definitions, and shared skills. + +## Repository Purpose + +- **Organization Profile**: Public-facing profile at `profile/README.md` +- **Company Metadata**: Internal company information at `company/` +- **Agent Definitions**: Paperclip agent configurations at `company/agents/` +- **Shared Skills**: Reusable skills at `company/skills/` +- **Dependency Management**: Renovate configuration at `renovate-config.json` + +## Folder Structure + +``` +.github/ +├── profile/ +│ ├── README.md # Organization public profile (shown on github.com/cartsnitch) +│ └── cartsnitch-logo.png # Organization logo +├── company/ +│ ├── README.md # Company overview and agent/skill inventory +│ ├── .paperclip.yaml # Paperclip configuration (agents, skills, company settings) +│ ├── agents/ # Per-agent configuration and instructions +│ │ ├── / +│ │ │ ├── AGENTS.md # Agent-specific instructions +│ │ │ ├── MEMORY.md # Agent memory/knowledge base +│ │ │ └── ... # Agent-specific files (life/, memory/, etc.) +│ └── skills/ # Shared skill definitions +│ ├── farhoodliquor/ # Third-party skills (playwright-ephemeral, shannon, github-app-token) +│ ├── fluxcd/ # Flux CD skills (gitops-knowledge, gitops-repo-audit) +│ ├── minimax-ai/ # MiniMax AI skills +│ └── paperclipai/ # Paperclip platform skills (paperclip, para-memory-files, etc.) +├── renovate-config.json # Renovate dependency update configuration +└── cartsnitch-logo.png # Organization logo (also in profile/) +``` + +## Key Components + +### Organization Profile (`profile/`) + +The `profile/README.md` is displayed on the CartSnitch GitHub organization page at https://github.com/cartsnitch. It includes: +- Organization branding and logo +- Links to key repositories +- Tech stack overview +- Getting started information for developers + +### Paperclip Configuration (`company/.paperclip.yaml`) + +This file defines: +- All agents in the CartSnitch organization (role, capabilities, adapter config, runtime settings) +- Company branding settings (brand color, logo) +- Agent sidebar ordering + +### Agent Definitions (`company/agents/`) + +Each agent has its own folder containing: +- `AGENTS.md` - Agent-specific instructions and role definition +- `MEMORY.md` - Agent's persistent knowledge base +- Additional agent-specific files (heartbeat configs, github settings, etc.) + +### Skills (`company/skills/`) + +Shared skills are organized by source: +- `farhoodliquor/` - Third-party skills from Farhood Liquor +- `fluxcd/` - Flux CD operational skills +- `minimax-ai/` - MiniMax AI capabilities +- `paperclipai/` - Paperclip platform skills + +## Maintenance + +### Updating Agent Configurations + +Agent configurations are defined in `company/.paperclip.yaml`. To update an agent: + +1. Edit the agent section in `.paperclip.yaml` +2. Update the agent's `AGENTS.md` file if role/capabilities changed +3. Submit changes via PR following the contribution guidelines + +### Adding New Agents + +New agents should be added to `company/.paperclip.yaml` with: +- Unique agent name +- Role (engineer, qa, ceo, cto, cmo) +- Icon selection +- Capabilities description +- Adapter configuration +- Runtime settings (heartbeat interval, max concurrent runs) +- Required environment inputs + +### Managing Skills + +Skills are imported from external sources: +- `paperclipai/*` skills are sourced from the Paperclip repository +- `fluxcd/*` skills are sourced from the Flux CD agent-skills repository +- `farhoodliquor/*` skills are sourced from Farhood Liquor skills repository +- `minimax-ai/*` skills are sourced from MiniMax AI skills repository + +To add or update a skill, edit `company/.paperclip.yaml` and ensure the skill files exist in the appropriate `company/skills/` subdirectory. + +### Renovate Configuration + +The `renovate-config.json` defines dependency update behavior for all CartSnitch repositories. Updates are automated via Mend Renovate with: +- Weekly schedule (Monday before 7am) +- Auto-merge enabled for minor/patch updates +- Manual review required for major updates +- Grouped updates for related packages (ESLint, TypeScript, testing, Docker, Kubernetes) + +## Related Repositories + +| Repository | Purpose | +|------------|---------| +| [cartsnitch](https://github.com/cartsnitch/cartsnitch) | Main application and consumer interface | +| [api](https://github.com/cartsnitch/api) | Backend API and services | +| [common](https://github.com/cartsnitch/common) | Shared libraries and utilities | +| [infra](https://github.com/cartsnitch/infra) | Infrastructure and deployment | +| [receiptwitness](https://github.com/cartsnitch/receiptwitness) | Receipt parsing and processing |