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
2026-04-14 14:22:40 +00:00
parent af7de2a618
commit 478df0b75d
2 changed files with 239 additions and 0 deletions
@@ -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/<agent-name>/`
+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/<source>/` 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-name> 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-name> 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