Skip to content
This repository was archived by the owner on Mar 18, 2026. It is now read-only.

AGENTS.md

Latest commit

 

History

History
100 lines (76 loc) · 4.26 KB

AGENTS.md

File metadata and controls

100 lines (76 loc) · 4.26 KB

Knowledge Work Plugins

Declarative plugin collection that specializes Claude for professional roles and workflows. Built for Claude Cowork, compatible with Claude Code.

Issue Tracking

This project uses br (beads_rust) for issue tracking.

Note: br is non-invasive and never executes git commands. After br sync --flush-only, describe the change with jj describe.

Quick reference:

  • br ready - Find unblocked work
  • br create "Title" --type task --priority 2 - Create issue
  • br close <id> - Complete work
  • br sync --flush-only - Sync beads (run at session end)
  • jj describe -m "sync beads" - Describe the change after sync

Project overview

  • 10 independent, role-focused plugins (productivity, sales, customer-support, product-management, marketing, legal, finance, data, enterprise-search, cowork-plugin-management)
  • Licensed under Apache 2.0

Repository structure

plugin-name/
├── .claude-plugin/plugin.json   # Plugin manifest (name, version, description)
├── .mcp.json                    # MCP server configurations (tool connections)
├── README.md                    # Plugin overview and setup
├── CONNECTORS.md                # Tool integrations and placeholders
├── commands/                    # Slash commands (explicit user-invoked workflows)
│   └── command-name.md
└── skills/                      # Domain knowledge (auto-activated by Claude)
    └── skill-name/
        ├── SKILL.md             # Skill definition and instructions
        ├── references/          # Supporting materials
        └── assets/              # Templates, examples

Top-level files:

  • .claude-plugin/marketplace.json — central registry of all plugins
  • README.md — main documentation and plugin table

Conventions

  • File/directory naming: lowercase with hyphens (call-prep.md, contract-review/)
  • Skill files: named SKILL.md inside a named directory under skills/
  • Command files: one .md file per command inside commands/
  • Placeholder prefix: ~~ marks tool-agnostic placeholders that orgs customize (e.g., ~~project tracker, ~~chat)
  • Frontmatter: commands and skills use YAML frontmatter with description and optionally name
  • Content style: plain language, numbered step-by-step workflows, tables for structured data
  • Connectors: documented in each plugin's CONNECTORS.md, configured in .mcp.json as HTTP MCP endpoints

Making changes

All content is markdown and JSON — edit directly, no build step required. When adding or modifying plugins:

  1. Follow the directory structure above
  2. Keep plugin manifests in .claude-plugin/plugin.json up to date
  3. Update .mcp.json when adding or changing tool connections
  4. Use ~~ placeholders for tool names that vary by organization
  5. Update the top-level README.md plugin table if adding a new plugin
  6. Update .claude-plugin/marketplace.json if adding a new plugin

Landing the Plane (Session Completion)

When ending a work session, you MUST complete ALL steps below. Work is NOT complete until git push succeeds.

MANDATORY WORKFLOW:

  1. File issues for remaining work - Create issues for anything that needs follow-up
  2. Run quality gates (if code changed) - Tests, linters, builds
  3. Update issue status - Close finished work, update in-progress items
  4. PUSH TO REMOTE - This is MANDATORY: 
    git pull --rebase
br sync --flush-only
jj describe -m "sync beads"
git push
git status  # MUST show "up to date with origin"
  5. Clean up - Clear stashes, prune remote branches
  6. Verify - All changes committed AND pushed
  7. Hand off - Provide context for next session

CRITICAL RULES:

  • Work is NOT complete until git push succeeds
  • NEVER stop before pushing - that leaves work stranded locally
  • NEVER say "ready to push when you are" - YOU must push
  • If push fails, resolve and retry until it succeeds

Code Quality

nix develop --command prek run --all-files  # Run all pre-commit checks

Commit Messages and PR Titles

No prefixes (feat:, fix:, [codex], etc.). Start with capital letter, imperative mood, include GitHub issue number. Example: Add job count for locales #123. PR titles follow the same rules.