docs(agents): add AGENTS.md and integrate bonedigger into factory model

[castrojo]

Summary

• add AGENTS.md with bonedigger's factory contract, issue lifecycle, labels, local validation, and CI/CD integration points
• replace the template sync PAT flow with the mergeraptor GitHub App token pattern
• update bonedigger skill docs to point at the projectbluefin/* downstream repos and the app-token auth model

Test plan

• actionlint .github/workflows/*.yml

Closes #13
Closes projectbluefin/common#418

[hanthor]

LGTM — AGENTS.md and factory model integration are well-structured. Note: has a merge conflict that needs resolving before merge.

[hanthor]

Switching from BONEDIGGER_SYNC_TOKEN PAT to the mergeraptor GitHub App token is a clear security improvement — scoped to specific repos, auditable, and rotatable. Action pinned by digest. Note: the repositories: list in create-github-app-token is hardcoded; if a new downstream repo is added it must be updated in sync with the matrix. AGENTS.md is well-structured and follows the factory contract format. LGTM.

[hanthor]

Switching from BONEDIGGER_SYNC_TOKEN PAT to the mergeraptor GitHub App token is a clear security improvement — scoped per-repo, auditable, rotatable. Action pinned by digest. One note: the repositories: list in create-github-app-token is hardcoded; adding a new downstream repo requires updating both the token scope and the matrix in sync. AGENTS.md is well-structured and follows the factory contract format. LGTM.

[castrojo]

Review

Verdict: Needs Changes

Critical (blocks merge)

• AGENTS.md — Missing ublue-os prohibition. Every factory AGENTS.md must include an explicit, prominent section prohibiting all writes to ublue-os/* (issues, PRs, comments, forks, workflow dispatch, automated reports). The common AGENTS.md carries a full ## 🚫 ABSOLUTE PROHIBITION — ublue-os org section with itemized examples. Omitting it here means any agent working in bonedigger (which syncs templates to factory repos) has no hard stop against accidentally writing to the old org.
• AGENTS.md — Missing Human Decision Gates. The four gates (Design / Security / Breakage / Merge) are factory-mandatory per common/AGENTS.md. Bonedigger changes propagate to all factory repos so this gate is especially important here.

Important (should fix)

• AGENTS.md — No commit attribution format specified. Needs Assisted-by: <Model> via pi trailer requirement and explicit zero-Co-authored-by: rule.
• .github/workflows/sync-templates.yml — actions/checkout@v4 is a floating tag (pre-existing). Not introduced by this PR, but SHA-pinning enforcement via pre-commit would catch it. Worth noting for a follow-up.

Strengths

• PAT → GitHub App token migration is the right security move; MERGERAPTOR_APP_ID / MERGERAPTOR_PRIVATE_KEY pattern matches common factory auth model.
• actions/create-github-app-token is SHA-pinned (@bcd2ba49) ✅
• Downstream refs updated from ublue-os/* → projectbluefin/* across both skill docs — correct and overdue.
• docs/skills/bonedigger-templates.md auth section updated to match new pattern.

Notes

No CI checks reported for the branch — expected for a docs + workflow-only PR if the workflow trigger is push to main rather than PR.

Recommendation: Add the ublue-os prohibition and human gates sections to AGENTS.md before merging — these are factory-standard, not optional.

[hanthor]

Review: Changes requested

The AGENTS.md addition itself is excellent content. However, there are blockers:

1. Merge conflicts — branch is 11 commits behind main, mergeable_state is dirty.

2. Regressive changes — if merged as-is, the PR would revert improvements already on main:

   • .github/workflows/sync-templates.yml: uses floating @v4 tag (main has SHA-pinned @v6), missing concurrency group, uses secrets.MERGERAPTOR_APP_ID instead of vars.MERGERAPTOR_APP_ID
   • docs/skills/bonedigger-overview.md and docs/skills/bonedigger-templates.md: ublue-os→projectbluefin and knuckle additions are already on main

Recommendation: Rebase on latest main, then drop changes to these 3 files (.github/workflows/sync-templates.yml, both skill docs). Keep only the AGENTS.md addition. Then run:

pre-commit run --all-files
actionlint .github/workflows/*.yml

[hanthor]

This PR currently has merge conflicts with the base branch and can't be merged as-is. Could you rebase / resolve the conflicts? Happy to re-review once it's mergeable — the change itself looks reasonable.