# Extending Shared Skills to a New Project

This directory contains shared workflow templates that can be reused across projects.
Each project provides its own config; the templates provide the logic.

## How It Works

```
~/.claude/skills/_templates/          ← shared workflow logic (this directory)
  pr-pipeline-workflow.md             ← review→fix→merge steps
  release-workflow.md                 ← CalVer tag→push steps
  release-core.sh                     ← parameterized release script
  EXTENDING.md                        ← this file

<project>/.claude/skills/             ← per-project config
  pr-pipeline/SKILL.md               ← agent names, repo mapping, → template pointer
  release/SKILL.md                   ← service mapping, deploy commands, → template pointer
  release/release.sh                 ← thin wrapper calling release-core.sh
  release/release-config.env         ← bash-sourceable service/image map
```

## Adding pr-pipeline to a New Project

1. Create `<project>/.claude/skills/pr-pipeline/SKILL.md`:

```markdown
---
name: pr-pipeline
description: Review-fix-merge pipeline for <Project Name> PRs.
---

# PR Pipeline — <Project Name>

## Config

| Key | Value |
|---|---|
| REVIEWER_AGENT | `pr-reviewer` |
| REVIEWER_MODEL | `sonnet` |
| FIXER_AGENT | `engineer` |
| FIXER_MODEL | `sonnet` |
| MERGER_AGENT | `<project-ops-agent>` |
| MERGER_MODEL | `sonnet` |

### Repo Mapping

| Short name | Gitea repo | Owner |
|---|---|---|
| `database` | `<project>-database` | `cal` |
| `discord` | `<project>-v2` | `cal` |

## Workflow

Follow the workflow defined in `~/.claude/skills/_templates/pr-pipeline-workflow.md`,
substituting the config values above.
```

**Key decisions:**
- `MERGER_AGENT` must match an agent defined in the project's `.claude/agents/` directory
- `REVIEWER_AGENT` and `FIXER_AGENT` are typically global agents (`pr-reviewer`, `engineer`)
- Repo mapping short names are arbitrary — pick whatever feels natural for the project

## Adding release to a New Project

1. Create `<project>/.claude/skills/release/release-config.env`:

```bash
BASEDIR="/mnt/NV2/Development/<project>"

declare -A SERVICE_DIRS=(
  [database]="database"
  [discord]="discord-app-v2"
)

declare -A SERVICE_IMAGES=(
  [database]="manticorum67/<project>-database"
  [discord]="manticorum67/<project>-discordapp"
)
```

2. Create `<project>/.claude/skills/release/release.sh`:

```bash
#!/usr/bin/env bash
exec bash ~/.claude/skills/_templates/release-core.sh \
  --config "$(dirname "$0")/release-config.env" "$@"
```

3. Create `<project>/.claude/skills/release/SKILL.md` with:
   - Config section (BASEDIR, service mapping table, deploy commands)
   - Usage/examples section with the correct paths
   - Workflow section pointing to `~/.claude/skills/_templates/release-workflow.md`

**Key decisions:**
- Only list services that need **manual** CalVer release in the config. If a repo auto-tags on merge (like some CI setups), omit it from SERVICE_DIRS.
- Deploy commands are project-specific — list them in the SKILL.md so Claude knows how to deploy after tagging.
- `SERVICE_IMAGES` can omit services that don't produce Docker images (e.g., CLI-only tools).

## Modifying Shared Workflow Logic

Edit the template files in `~/.claude/skills/_templates/`. Changes propagate to all projects automatically.

**Rules:**
- Templates must not contain project-specific strings (no repo names, paths, or agent names)
- Use `{PLACEHOLDER}` notation for values that come from project config
- Test changes against at least the Paper Dynasty skills before considering them stable