Merge pull request #7 from cartsnitch/docs/add-organization-documentation

Add documentation to .github organization repository
2026-04-15 10:27:59 +00:00
parent f22d0aaf19 478df0b75d
commit a653f30a21
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
@@ -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
+│   │   ├── <agent-name>/
+│   │   │   ├── 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 |