AI Workflow Rules

Reusable AI workflow rules, agent templates, and skills for software development projects. Consumed by projects as a git submodule.

What This Is

A shared repository of framework-agnostic workflow rules and agent role definitions. Projects add this as a submodule and symlink the skills they need, keeping their AI agents lean and their workflow knowledge centralized and version-controlled.

No project-specific content lives here. Everything is generic and reusable.

Architecture

Three-layer model:

workflow-core/          Layer 1: Universal workflow rules (board management, PR process,
                        routing, triage) — no tech assumptions

role-*/                 Layer 2: Role-specific skills (coordinator, reviewer, builder,
                        tester, etc.) — framework-agnostic

tech-*/                 Layer 3: Technology skills (tech-flutter, tech-firebase, etc.)
                        — framework-specific, opt-in

Projects compose from all three layers by symlinking what they need into .claude/skills/.

Quick Start

1. Add as submodule

git submodule add <repo-url> .claude/workflow-base
git submodule update --init

2. Install skills

# Install all skills (symlinks into .claude/skills/)
.claude/workflow-base/scripts/install.sh .

# Or install manually
mkdir -p .claude/skills
ln -s ../workflow-base/skills/workflow-core .claude/skills/workflow-core
ln -s ../workflow-base/skills/role-coordinator .claude/skills/role-coordinator

3. Create thin agent files

Agent files in .claude/agents/ reference shared skills via frontmatter:

---
name: coordinator
skills:
  - workflow-core
  - role-coordinator
---

# Coordinator

<!-- Project-specific context only -->
Board: https://github.com/org/repo/projects/1
Labels: needs:build, needs:review, needs:test

The skill content stays in the submodule. The agent file stays thin.

Directory Structure

.
├── CLAUDE.md                    # Safety rules for editing this repo
├── README.md                    # This file
├── agents/                      # Generic agent templates (copy + customize)
│   ├── coordinator.md
│   ├── docs-optimizer.md
│   └── ...
├── skills/                      # Installable skills (symlink into projects)
│   ├── workflow-core/           # Universal workflow rules
│   │   ├── SKILL.md
│   │   ├── board-management.md
│   │   ├── pr-process.md
│   │   └── triage.md
│   ├── role-coordinator/        # Coordinator role rules
│   │   └── SKILL.md
│   ├── role-reviewer/           # Code reviewer rules
│   │   └── SKILL.md
│   ├── role-builder/            # Feature builder rules
│   │   └── SKILL.md
│   ├── role-tester/             # Test writer rules
│   │   └── SKILL.md
│   └── tech-*/                  # Technology-specific skills (opt-in)
└── scripts/
    ├── check-project-leak.sh    # Pre-commit guard against project-specific content
    └── install.sh               # Install skills into a target project

How Projects Consume This

Projects do not edit files in .claude/workflow-base/. They:

1. Symlink skills they want into .claude/skills/
2. Create thin agent files in .claude/agents/ that reference those skills
3. Add project-specific context only in the agent files

When this repo is updated (bug fixes, improved rules), projects pull the latest via:

git submodule update --remote .claude/workflow-base

Contributing

Before committing any change:

1. Run ./scripts/check-project-leak.sh — must exit 0
2. Keep skills under 500 lines total (SKILL.md + supporting files)
3. Use generic language: "the project", "the app", "the team"
4. No framework-specific content outside tech-* skills
5. Test that the skill makes sense without project context

See CLAUDE.md for the full rules.

Community Skills

Before writing a new skill, check these community sources:

Source	Description
Anthropic Official	Reference implementations (includes skill-creator)
SkillsMP	200K+ marketplace, filter by 2+ stars
Antigravity	800+ curated (Flutter, Firebase, code-review, etc.)
VoltAgent	300+ from official dev teams + community

All follow the Agent Skills standard — works across Claude Code, Cursor, Copilot, Codex.

Tip: Install Anthropic's skill-creator skill for guidance when writing new skills:

# Copy to user-level skills (available across all projects)
cp -r <path>/skills/skill-creator ~/.claude/skills/

License

[Add license here]