Alien-Libgit2

 view release on metacpan or  search on metacpan

.claude/rules/alien-libgit2-rules.md  view on Meta::CPAN

speed on non-trivial work; judgment on trivial ones. Loaded automatically at launch (same
priority as `CLAUDE.md`). Subagents get their conventions from the skills force-loaded via
`briefing.skills` — this file is for the orchestrating agent.

## Engineering discipline

1. **Think before coding** — State assumptions. When uncertain, ask rather than guess.
   Push back when a simpler approach exists. Stop when confused; name what's unclear.
2. **Simplicity first** — Minimum change that solves the problem. Nothing speculative.
3. **Surgical changes** — Touch only what you must. Don't "improve" adjacent code,
   comments or formatting. Match existing style.
4. **Read before you write** — `alienfile` is the whole distribution; read it *and* the
   CI workflows before changing either. They encode the same CMake flags twice on purpose.
5. **Surface conflicts, don't average them** — Contradicting patterns: pick one (more
   recent / more tested), say why, flag the other. Don't blend.
6. **Checkpoint after every significant step** — done / verified / left.
7. **Fail loud** — "Done" is wrong if anything was skipped silently; "tests pass" is wrong
   if only one install path ran.

## Delegation

.claude/rules/alien-libgit2-rules.md  view on Meta::CPAN

## Public issues (GitHub) — never act without instruction

**karr** is the internal agent board, churned freely. **GitHub issues**
(`github.com/Getty/p5-alien-libgit2`) are the public tracker: real humans, published under
the maintainer's account. Never act on one on your own initiative — not even to read it —
unless the user points at a specific item.

## Perl and Alien specifics — reference, don't restate

House Perl style: skill `getty-perl-core`. Alien::Build mechanics: skill `perl-alien`.
This distribution's own facts: skill `alien-libgit2-core`. Do not duplicate them here.

.claude/skills/getty-perl-core/SKILL.md  view on Meta::CPAN

## Control flow

- **Postfix `if`/`unless`** for guards and short conditions: `croak(...) if $self->readonly;`
- **`unless $x`** instead of `if !$x`.
- **Guard clauses return bare:** `return unless $res->is_success;` — not `return undef;`.
- **Nested ternaries** for a return that picks between expressions, instead of an if/elsif chain.

## Data

- **`{ %hash }` and `\%hash` are different operations, not two styles.** `{ %h }` builds a new anonymous copy; `\%h` references the existing hash. Return a copy when the caller must not mutate your state; return the reference when sharing is the poin...
- **`Path::Tiny`** for every file operation — not `File::Spec`, not bare `open`. `path(...)->child(...)->slurp_utf8`.
- **`JSON::MaybeXS`** always — never `JSON::PP`, `JSON::XS`, `Cpanel::JSON::XS` directly. Encoders get `canonical => 1, convert_blessed => 1`.
- **Every serialiser is deterministic.** MessagePack `->canonical`, DBIC `serializer_options => { canonical => 1 }`. Same rule, every format.
- **Booleans: `JSON->true` / `JSON->false`.** `use JSON::MaybeXS;` covers codec and booleans.
- `$YAML::XS::Boolean = 'JSON::PP'` is one of YAML::XS's fixed mode names, not a module choice — leave it alone.
- **Align `=>` in multi-line hash literals** when keys are of similar length.
- **Optional pairs inline:** `$cond ? ( experimental => 1 ) : (),`

## Configuration

.claude/skills/getty-perl-core/SKILL.md  view on Meta::CPAN

# → GETTY/Module-Name-1.234.tar.gz  ← pin to 1.234
```

Getty-authored (non-exhaustive): `Langertha`, `IO::K8s`, `Kubernetes::REST`, `WWW::Crawl4AI`, `Net::Async::Crawl4AI`, `Net::Async::WebSearch`, `Catalyst::Plugin::ChainedURI`, `Locale::Simple`, `DBIO::*`, `WWW::Zitadel`, `WWW::PayPal`, `WWW::Chain`.

## Changelog (the Changes file)

Every distribution ships a `Changes` file with a `{{$NEXT}}` token at the top (Dist::Zilla's `[NextRelease]` fills it at release time).

- **Add a bullet under `{{$NEXT}}` in the SAME commit as any user-facing change** — new bindings, behaviour changes, bug fixes, deprecations. If a CPAN consumer would notice, it belongs there.
- **Match the existing style:** two-space indent, `  - ` bullets, wrap near 78 columns, present-tense imperative ("New binding X", "Fix Y on macOS").
- **One topic, one bullet, one to three lines** — touching an area again rewrites the bullet that is already there instead of adding a second. Wording and length: `getty-git-commit-style`.
- **Skip pure dev-tooling noise** — skill hardlinks, editor config, internal CI refactors. A CI fix that unbreaks the build for everyone IS worth a line.
- **Never hand-edit the version line or timestamp** — `[NextRelease]` owns those.

## Forbidden

❌ `require Foo` inside a method to "speed up startup" · ❌ a Getty repo's `$VERSION` as a cpanfile requirement · ❌ `'0'` or `'>= x'` as a version argument · ❌ `default => sub {...}` for a non-trivial attribute default · ❌ 4-space indent ...

## When in doubt

Grep hand-written Getty code for how the pattern is used there — the reference is an older repo with no AI commits in its history. Newer repos may show an agent's guess rather than the house rule.

.claude/skills/getty-perl-release-author-getty/SKILL.md  view on Meta::CPAN

effect.

## Release Workflow

```bash
dzil release        # Builds, tests, uploads to CPAN, bumps version, commits, tags
```

Read the `{{$NEXT}}` section of `Changes` once as a whole first. It was written bullet
by bullet over weeks, so this is where entries circling one topic get merged into one
and over-detailed ones get cut back (skill `getty-git-commit-style`). It is not only a
changelog: `GitHub::CreateRelease` runs with `notes_from = ChangeLog` and publishes the
section verbatim as the release notes.

Fix it in its own commit *before* `dzil release`. `Changes` sits in the release commit's
`allow_dirty` list, so an uncommitted edit stops nothing — it is folded into the release
snapshot silently, under a message naming only the version.

## Conventions

1. `copyright_year` IS used in dist.ini — GETTY has it in ALL distributions, do NOT remove it

.claude/skills/perl-alien/references/alienfile.md  view on Meta::CPAN

A helper can be defined in the alienfile and then used in any command string:

```perl
meta->interpolator->add_helper(foo_config => sub { 'foo-config' });
```

## Command lists

`build` takes an arrayref of commands. A plain string is interpolated and run
through the shell; a nested arrayref is `system()`-style, argument by argument, and
is what to use as soon as any argument can contain a space:

```perl
build [
  [ '%{cmake}', '-DCMAKE_INSTALL_PREFIX=%{.install.prefix}', '%{.install.extract}' ],
  '%{make}',
  '%{make} install',
];
```