feat(kyberforge): add instructions-author skill for .apm/instructions files

Scaffolds and revises apm instructions files, with a throwaway-package verification recipe because `apm compile --validate` always exits 0 and Claude Code drops `description`. Routed from forge and linked from apm-workflow's compile reference. Bumps kyberforge to 2.1.0 and the catalog to 0.5.2. Fixes #148 Co-Authored-By: Claude Code <[email protected]> Claude-Session: https://claude.ai/code/session_01KkT7RSDwDbmrM9T34b6sTi
2026-10-01 06:46:39 +00:00
1 parent 529ed31cef
commit c52e351954
@@ -0,0 +1,63 @@
+---
+source_keys:
+  - apm-cli-0-28-0-experiments
+  - apm-docs-site
+  - claude-code-memory-docs
+  - github-copilot-custom-instructions-docs
+  - cursor-rules-docs
+---
+
+# What each target receives
+
+Verified against apm 0.28.0 and throwaway installs. Reached from `SKILL.md` Step 2 when the question is which target keeps which field. Source-file syntax is in `references/schema.md`.
+
+## Two output paths
+
+`apm install` writes one native file per instruction into each target's rules directory. `apm compile` writes root context files that concatenate instruction bodies, grouped by `applyTo`. Treat install as the primary path for Claude Code and Copilot, and compile as the path for targets with no native instructions directory.
+
+## Install: deployed path and transform
+
+| Target | Deployed path | Transform |
+|---|---|---|
+| copilot | `.github/instructions/<n>.instructions.md` | Verbatim copy |
+| claude | `.claude/rules/<n>.md` | `applyTo` becomes a `paths:` list; `description` dropped; no frontmatter at all without `applyTo` |
+| cursor | `.cursor/rules/<n>.mdc` | `applyTo` becomes `globs`; `description` kept; no `alwaysApply` written |
+| windsurf | `.windsurf/rules/<n>.md` | `trigger: glob` plus `globs`, or `trigger: always_on`; `description` dropped |
+| kiro | `.kiro/steering/<n>.md` | `inclusion: fileMatch` plus `fileMatchPattern`, or `inclusion: always`; `description` dropped |
+| antigravity | `.agents/rules/<n>.md` | `trigger: glob` plus `globs`, or no frontmatter; `description` dropped |
+| grok-build | `.grok/rules/<n>.instructions.md` | Verbatim copy |
+| codex, gemini, opencode and the rest | none | Reach instructions only through compile |
+
+Windsurf, Kiro, Antigravity and Cursor do not deploy at user scope.
+
+## Field survival
+
+| Field | Claude | Copilot | Cursor | Windsurf, Kiro, Antigravity | Compiled root file |
+|---|---|---|---|---|---|
+| `applyTo` | as `paths` | verbatim | as `globs` | as each target's glob key | grouping only |
+| `description` | dropped | kept | kept | dropped | dropped |
+| `author`, `version` | dropped | kept only because the file is verbatim | dropped | dropped | dropped |
+
+For Claude Code the body's first line or heading is the only descriptive text that survives, so the body must explain itself.
+
+## Ownership and overwrite
+
+- Claude, Cursor, Windsurf, Kiro and Antigravity treat each deployed file as apm-owned: install replaces a hand-authored file at the same path without a prompt. Copilot skips an unmanaged file ("local files exist, not managed by APM") until `apm install --force`.
+- Removing or renaming a source makes the next install delete the file it deployed.
+
+## Compile
+
+- `--target claude` writes `CLAUDE.md`; Gemini writes `GEMINI.md` and `AGENTS.md`; every other target writes `AGENTS.md`.
+- Compile skips instructions already deployed natively, for Claude, Copilot and Antigravity only. With rules populated, `--target claude` exits 0, prints "produced no output files" and writes nothing. `--force-instructions` (alias `--no-dedup`) overrides.
+- Cursor, Windsurf, Kiro, Grok, Codex and OpenCode have no dedup: compile writes `AGENTS.md` that repeats rules the tool already loads natively.
+- A compile with no instruction primitives exits 0.
+
+## Native format facts
+
+- Claude Code reads `.claude/rules/**/*.md` recursively. `paths` is the only field it reads, as a list or a comma-separated string; other fields are ignored. A rule without `paths` loads at every launch. Frontmatter that fails to parse is ignored and the rule loads without `paths`.
+- Copilot path-specific files need `applyTo` as a quoted comma-joined string; `excludeAgent` is the only other documented key. Repository-wide instructions are the separate `.github/copilot-instructions.md`.
+- Cursor ignores a plain `.md` in `.cursor/rules`. A rule with only a `description` is "Apply Intelligently", not always-on.
+
+## Unverified
+
+Cursor's handling of a YAML-list `globs`, Copilot's handling of unknown frontmatter keys, and runtime behaviour on Windsurf, Kiro and Antigravity. Say so rather than asserting any of them.