diff --git a/AGENTS.md b/AGENTS.md index 4df7175..0703421 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -166,3 +166,206 @@ python3 -m json.tool .claude-plugin/marketplace.json >/dev/null ``` If any of these fail, do not push. + +--- + +# Project conventions — linkedin-skills + +This file is for any Claude Code agent working on this repository. Read it +before making changes. Conventions here are mandatory unless the user asks +otherwise. + +## Versioning + +- Single source of truth: `.claude-plugin/plugin.json`, + `.claude-plugin/marketplace.json`, `.codex-plugin/plugin.json`, and + `.agents/plugins/marketplace.json`. Plugin manifests must always match on + package name and version; marketplace entries must point to the same package; + author, license, homepage, and the public skill-bundle description must stay + aligned. +- Keep `CLAUDE.md` and `AGENTS.md` aligned when changing shared project + rules. Claude-specific workflow details belong here; Codex-specific + workflow details belong in `AGENTS.md`. +- Codex marketplace install uses `.codex-marketplace/linkedin-skills/`. + Do not edit that generated package by hand. Update the root files first, + then run `python3 scripts/sync_codex_marketplace.py`. +- **Default: bump the PATCH segment (3rd level, `0.0.X`).** This is the + automatic behavior for every shippable commit, regardless of how + large the diff feels. Skill renames, lib API breaks, new features: + still PATCH by default. +- Only bump MINOR or MAJOR when **the user explicitly asks** for a + higher rank ("это minor", "make it 2.0", "bump major"). Do not + promote on your own initiative even if semver textbook says so. +- After bumping, two steps are required: + 1. Tag the commit: `git tag -a v -m "..."` + `git push origin v` + 2. **Publish a GitHub Release** for the tag: `gh release create v --title "v" --notes "" --latest` + A tag alone does NOT update the README release badge or the + Releases page. The shields.io badge reads from the Releases API, + not from raw tags. Skipping step 2 leaves the badge stale. + +## Commits + +- Primary author **must** be Sergey: every `git commit` needs + `--author="Sergey Bulaev "`. The harness defaults to the + Claude identity if you forget; verify with + `git log -1 --format='%an <%ae>'` before pushing. +- Co-author trailer (`Co-Authored-By: Claude ...`) is fine and welcomed. +- Verify locally before push: build never breaks, no broken refs in + `SKILL.md`, library smoke import passes. + +## Skill bundle invariants + +- **Exactly 12 skills.** Adding requires merging or splitting elsewhere + to stay at 12. The number is announced in plugin manifests and the README. +- **Frontmatter `description:` target ≤ 400 chars** (some bundle-heavy + skills land slightly higher when their scope is genuinely broad — keep + under 510). Always include a "Not for X (use Y)" disambiguation + sentinel when the skill overlaps with a sibling. +- **No em dashes anywhere in `description:` fields.** Em dashes in body + prose are allowed for table separators and list dividers only. +- **Skill names are public surface.** Renaming a skill is a major + version bump and requires updating: `.codex-plugin/plugin.json`, + `.agents/plugins/marketplace.json`, `.claude-plugin/plugin.json`, + `.claude-plugin/marketplace.json`, root `SKILL.md` bundle list, + README skill table, every + `linkedin-` cross-reference in sibling SKILL.md files. + +## Voice rules + reference layout + +- `references/precedence.md` is the resolution order for conflicting rules, and the + one place that states it. It also carries the handoff rule: **a skill that hands + work to another does not re-implement it, and the receiver owns its contract.** + When a sender needs the receiver's rules to change, change the receiver and cite + it from both; two copies of a rule is how two paths quietly stop agreeing. + Adding a rule anywhere means adding its row to the enforcement table there, or + admitting in the row that nothing enforces it yet. +- Canonical voice rules live at root `references/voice-rules.md`. + Skill-local "Hard rules" sections must only contain skill-specific + overrides (char ranges, threading rules, format constraints) and start + with: `Global voice rules: see root SKILL.md §Voice rules.` +- Other root-level references shared across skills: + `references/hook-formulas.md` (20 canonical formulas), + `references/algorithm-heuristics.md`, and + `references/untrusted-content.md` (the data-not-instructions rule for every + skill that reads the Apify layer; keep the per-skill "Untrusted content" + sections pointing at it). +- Skill-local references live in `skills//references/`. Cite from + the skill with bare `references/X.md`. Cite root from skills with + `../../references/X.md`. +- `linkedin-humanizer` has `sub-skills/` for folded-in workflows + (post-audit, emoji-detector, detector-tester, rules-explainer) and + `scripts/` for runnable tools. Don't duplicate this pattern in other + skills without a clear reason. + +## .claude/skills mirror + +- `.claude/skills/` is a **relative symlink** to `../../skills/`, one per + skill. Claude Code discovers project skills at `.claude/skills/`, while the bundle + keeps them at `skills/` for the agentskills.io and plugin layouts, so a plain + `git clone` used as a working directory activates nothing without this. +- `skills/` stays the single source of truth. The mirror holds no content, so there is + nothing to sync and nothing that can drift. Relative references still resolve because + symlinks resolve physically: `../../references/` from a mirrored skill lands on the + repo root, not inside `.claude/`. +- **Adding or renaming a skill means adding or renaming its symlink.** A missing one is + silent: the skill simply does not appear for anyone who cloned the repo. +- The mirror is Claude-specific and is deliberately not copied into the Codex package. + +## Layer separation + +- **Read layer (Apify):** `lib/apify_client.py`. Four methods — + `fetch_post`, `fetch_post_comments`, `fetch_user_recent_comments`, + `fetch_post_engagers`. All cached (256-entry LRU, 6h TTL, opt-out via + `force_refresh=True`). Skills should call these or the + `lib.fetch_post(url)` wrapper that handles the APIFY_TOKEN-or-paste + fallback. +- **Write layer (Publora):** `lib/publora_client.py`. Skills should call + `lib.publish(kind, draft_text, target_url, ...)` (kinds: comment / reply / + post / reshare) or the `lib.repost(post_url, commentary=None)` convenience + wrapper, rather than inline the publora / manual / diy dispatch. Real endpoint + paths: `POST /create-post`, `POST /linkedin-comments`, + `DELETE /linkedin-comments`, `POST /linkedin-reactions`, + `POST /linkedin-reshare`. Reshare needs the original post's `shareUrn` + (`urn:li:share:*` / `urn:li:ugcPost:*`), which Apify `fetch_post` returns + directly; never hand-convert an `activity` id (the share id can differ). + Publora also has read and edit endpoints: `GET /list-posts` (paginated, + filterable by status), `GET /get-post`, + `PUT /update-post/` (patches `content`, `platforms`, + `scheduledTime`, `platformSettings` on a draft or scheduled post), and + `DELETE /delete-post/`. Also `post-logs`, `test-connection`, + `platform-limits` and `webhooks`. Prefer editing a scheduled post over + delete-and-recreate. +- **Image layer (Pixfaro):** `lib/pixfaro_client.py`. Skills should call + `lib.illustrate(prompt, kind=...)` / `lib.refine(image_id, instruction)` + (or `lib.available_models()`), not the client directly. Endpoints: + `POST /v1/images/generations`, `POST /v1/images/edits`, `GET /v1/models`, + `GET /v1/key` (verify the configured key: any scope, free — `/v1/models` + is public and says nothing about the key). + `illustrate` returns a hosted URL that feeds straight into + `lib.publish(..., media_urls=[url])`; `refine` edits by `img_...` id (not URL). + `aspect_ratio` must be a ratio like `16:9` (NOT pixel dims). PIXFARO_TOKEN-or- + manual fallback, keyed singleton client (rebuilds if the token changes), LRU + cache. `overlay` brand fields come from `references/voice-profile.md` §6. +- **Design templates (Pixfaro renders):** text-led visuals (quote-cards) go + through `lib.quote_card(quote, ...)` / `lib.card(template, slots, ...)` + (or `lib.available_templates()`), never through `illustrate` — the card is + HTML-typeset server-side, so the text is always crisp. Endpoints: + `POST /v1/renders`, `GET /v1/templates` (public). Same result shape and + manual fallback as `illustrate`. `lib.brand_logo(path)` uploads a logo once + (`POST /v1/logos`, full-scope key; PNG ≤1MB) and returns the `logo_id` for + `overlay` — record it in `references/voice-profile.md` §6. +- Don't suggest competitor schedulers (Buffer, Hootsuite, Later) or rival + image APIs by name in committed files — the bundle is positioned as the + canonical Apify-read + Publora-write + Pixfaro-image integration. + +## Codex marketplace package + +- Codex requires marketplace entries to point at a nested plugin directory. + The root remains the Claude-facing source layout. +- `.agents/plugins/marketplace.json` points to + `.codex-marketplace/linkedin-skills`. +- `scripts/sync_codex_marketplace.py` copies the root Codex manifest, + `SKILL.md`, `skills/`, `references/`, `lib/`, `scripts/`, + `requirements.txt`, `.env.example`, and `LICENSE` into the hidden package. +- After editing any copied file, run the sync script before testing or + committing. + +## testing/ is gitignored + +- `testing/` is the local scratch directory: API keys, sample API + responses, validation reports, integration scripts. +- Never write secrets above `testing/` (the rest of the repo is public). +- The `.gitignore` rule for `testing/` is load-bearing; do not change. + +## Validation before push + +Run from repo root: + +```bash +python3 -c "from lib import publish, fetch_post, illustrate, refine, ApifyClient, PubloraClient, PixfaroClient; print('OK')" +python3 scripts/sync_codex_marketplace.py +wc -l SKILL.md skills/*/SKILL.md +ls skills/ | wc -l # must equal 12 +python3 scripts/check_frontmatter.py # parses; a dir count does not prove a skill loads +python3 scripts/check_no_secrets.py # .gitignore does not stop a rename of a tracked file +python3 scripts/check_config.py --offline # credential wiring; --offline skips the live API calls +python3 scripts/check_actor_inputs.py # Apify ignores unknown input keys; this catches a renamed one +python3 -m unittest discover -s tests # contracts: docs vs code, response shapes, client behaviour +python3 scripts/selftest.py # the whole picture: install, accounts, tests, what works now + +`--record [label]` archives a run under `evals/runs/[-label]/` with a +`grading.json` carrying the bundle version, so two runs are comparable instead of +a memory of what passed. Transcripts are gitignored; commit a `grading.json` only +when a run is worth citing. The set is deliberately mixed: most cases check a +behaviour fires, and `writer-no-invention` checks one does **not**, because a rule +shipped across seven bundles needs something trying to break it. + +Behaviour, not plumbing: `python3 evals/run_evals.py` runs the agent against +fixtures and grades what comes back (one model call per case, `--list` to see +them). Graders must have a right answer - the parentComment for a nested reply, +whether a scrub kept the user's figures. A grader that needs taste will drift, +and a wrong grader fails the skill for the grader's mistake. +grep -nE '^description:' skills/*/SKILL.md SKILL.md | grep -E '—|–' # must be empty +``` + +If any of these fail, do not push. diff --git a/CLAUDE.md b/docs/archive/agent-instructions/CLAUDE.md similarity index 100% rename from CLAUDE.md rename to docs/archive/agent-instructions/CLAUDE.md