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,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 |