Defame1297/holocron
0
0 Fork 0
Code Issues 18 Pull Requests 1 Actions Packages Projects Releases 3 Wiki Activity

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

Open
Claude wants to merge 5 commits from feat/148-instructions-author into main
pull from: feat/148-instructions-author
merge into: Defame1297:main
Conversation 0 Commits 5 Files Changed 32
+1051 -78
Claude commented 2026-10-01 07:09:50 +00:00
Collaborator
Copy link
Copy source

Summary

  • New instructions-author skill (v0.1.0): scaffolds and revises .apm/instructions/*.instructions.md via scripts/new-instructions.sh, a minimal template, and create/improve flows.
  • Verification recipe (references/verify.md) uses a real apm compile --dry-run plus a throwaway-package install, because apm compile --validate always exits 0 and hides the missing-description, missing-applyTo and empty-body warnings.
  • Gotchas demonstrated in bats against real apm 0.28.0: Claude Code drops description; an unquoted applyTo installs with no paths: (loads in every session); compile writes no CLAUDE.md once rules are installed.
  • Wiring: forge routing row (+ author-routes.md, version-bump.md), one-line pointer in apm-workflow/references/compile.md, and ADR-0022 patch bumps for forge (1.0.3) and apm-workflow (1.0.2).
  • Research docs for the primitive (schema, target mapping, gotchas, sources) added earlier on this branch.
  • Versions: kyberforge 2.0.2 -> 2.1.0, catalog 0.5.2 (root apm.yml, executables.allow key, marketplace.json).

Notes

  • factory-audit has no instructions flow yet (#151), so forge's clean-context rerun is skipped for instructions files; stated in author-routes.md.
  • apm-workflow/references/compile.md line 66 (empty apm compile exits 1) looks stale for 0.28.0; left untouched as out of scope.

Test plan

  • factory-audit on instructions-author: validate, provenance and Vale clean; qualitative review resolved
  • scripts/skill-size-check.sh (ADR-0020 budgets)
  • apm audit --ci and apm pack --check-clean
  • Full bats suite: 440 tests, 0 failures
  • Pre-push hooks pass

Fixes #148

🤖 Generated with Claude Code

https://claude.ai/code/session_01KkT7RSDwDbmrM9T34b6sTi

## Summary - New `instructions-author` skill (v0.1.0): scaffolds and revises `.apm/instructions/*.instructions.md` via `scripts/new-instructions.sh`, a minimal template, and create/improve flows. - Verification recipe (`references/verify.md`) uses a real `apm compile --dry-run` plus a throwaway-package install, because `apm compile --validate` always exits 0 and hides the missing-`description`, missing-`applyTo` and empty-body warnings. - Gotchas demonstrated in bats against real apm 0.28.0: Claude Code drops `description`; an unquoted `applyTo` installs with no `paths:` (loads in every session); compile writes no `CLAUDE.md` once rules are installed. - Wiring: `forge` routing row (+ `author-routes.md`, `version-bump.md`), one-line pointer in `apm-workflow/references/compile.md`, and ADR-0022 patch bumps for `forge` (1.0.3) and `apm-workflow` (1.0.2). - Research docs for the primitive (schema, target mapping, gotchas, sources) added earlier on this branch. - Versions: kyberforge 2.0.2 -> 2.1.0, catalog 0.5.2 (root `apm.yml`, `executables.allow` key, `marketplace.json`). ## Notes - `factory-audit` has no instructions flow yet (#151), so forge's clean-context rerun is skipped for instructions files; stated in `author-routes.md`. - `apm-workflow/references/compile.md` line 66 (empty `apm compile` exits 1) looks stale for 0.28.0; left untouched as out of scope. ## Test plan - [x] `factory-audit` on `instructions-author`: validate, provenance and Vale clean; qualitative review resolved - [x] `scripts/skill-size-check.sh` (ADR-0020 budgets) - [x] `apm audit --ci` and `apm pack --check-clean` - [x] Full bats suite: 440 tests, 0 failures - [x] Pre-push hooks pass Fixes #148 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01KkT7RSDwDbmrM9T34b6sTi
Claude added 3 commits 2026-10-01 07:09:51 +00:00
docs(kyberforge): refresh apm instructions primitive research for #148 529ed31cef 
The existing schema doc covered only Claude and Copilot and called missing
description and empty content errors when apm 0.28.0 only warns. Rewrite it
with the applyTo grammar and add per-target compile/install mapping and a
gotchas doc (unquoted globs, install-vs-compile discovery, dedup and
overwrite behaviour), all verified against the apm 0.28.0 binary.

Refs: #148

Co-Authored-By: Claude Code <[email protected]>
Claude-Session: https://claude.ai/code/session_01KkT7RSDwDbmrM9T34b6sTi
feat(kyberforge): add instructions-author skill for .apm/instructions files c52e351954 
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
fix(kyberforge): bump forge and apm-workflow skill versions for #148 6328816584 
ADR-0022 requires a metadata.version raise on every changed skill; the
routing row and compile pointer added for instructions-author touched both.

Refs #148

Co-Authored-By: Claude Code <[email protected]>
Claude-Session: https://claude.ai/code/session_01KkT7RSDwDbmrM9T34b6sTi
plugins/kyberforge/.apm/skills/instructions-author/SKILL.md
@@ -0,0 +16,4 @@
- claude-code-memory-docs
---
## Gotchas
Defame1297 commented 2026-10-01 15:53:32 +00:00
Owner
Copy link
Copy source

Are all of these really gotcha's? Or things that should be added as rules/requirements or generalisatons elsewhere?

Are all of these really gotcha's? Or things that should be added as rules/requirements or generalisatons elsewhere?
plugins/kyberforge/.apm/skills/instructions-author/SKILL.md
@@ -0,0 +43,4 @@
- **One topic per file.** Two topics are two files.
- **Scope.** Omit `applyTo` only for a rule that must load in every session, and tell the user it then costs context at every launch.
- **Stem.** It becomes the deployed filename, and install overwrites a hand-authored rule of the same name on most targets without a prompt. Check for a collision before choosing it.
- **Body.** Bullets, paths in backticks, nothing assuming another file is loaded, under 200 lines.
Defame1297 commented 2026-10-01 16:01:05 +00:00
Owner
Copy link
Copy source

Is it clear what should be an instruction and what typer of info/content should be in the bod (either here or in the template?)

Is it clear what should be an instruction and what typer of info/content should be in the bod (either here or in the template?)
plugins/kyberforge/.apm/skills/instructions-author/SKILL.md Outdated
@@ -0,0 +54,4 @@
`factory-audit` has no instructions checks yet, so nothing else gates the file; report only what the verification showed.
**Commit verification.** Once verification is clean, run `rtk git add` and `rtk git commit`. Re-run `rtk git log --oneline -1` and confirm the hash changed from Step 1's. A non-empty `git diff --stat` is not proof: staged-but-uncommitted work is lost if the tree is cleaned up. Report done only once the hash has changed.
Defame1297 commented 2026-10-01 15:58:49 +00:00
Owner
Copy link
Copy source

Commit steps should be out of scope for author skills.

Commit steps should be out of scope for author skills.
plugins/kyberforge/.apm/skills/instructions-author/assets/templates/instructions.md Outdated
@@ -0,0 +8,4 @@
---
# FILL IN: one topic per file
- FILL IN: the first rule, stated as a bullet.
Defame1297 commented 2026-10-01 16:01:28 +00:00
Owner
Copy link
Copy source

See body comment in skill.md

See body comment in skill.md
Defame1297 added 2 commits 2026-10-01 17:09:52 +00:00
refactor(kyberforge): address #154 review and drop commit steps from author skills d576695bb9 
- instructions-author: keep two Gotchas, move the rest to the Step 2 contract
  and verify.md; add references/content.md on what belongs in an instructions
  file and tighten the template bullets to match
- instructions-author, skill-author, agent-author: remove the commit
  verification step; committing is out of scope for author skills
- skill-author 1.0.6, agent-author 1.0.4 (ADR-0022 patch bumps)

Refs #148

Co-Authored-By: Claude Code <[email protected]>
Claude-Session: https://claude.ai/code/session_01KkT7RSDwDbmrM9T34b6sTi
fix(kyberforge): address independent review of #154 68fa2abb62 
Quote the template description so the raw scaffold is valid YAML, reject
newline-containing names in new-instructions.sh, correct the empty-compile
facts (exit 1, --clean exits 0), and finish removing commit steps from the
skill-author, agent-author and forge references. Adds regression tests.

Refs #148

Co-Authored-By: Claude Code <[email protected]>
Claude-Session: https://claude.ai/code/session_01KkT7RSDwDbmrM9T34b6sTi
This pull request doesn't have enough required approvals yet. 0 of 1 approvals granted from users or teams on the allowlist.
This pull request has changes requested by an official reviewer.
You are not authorized to merge this pull request.
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u origin feat/148-instructions-author:feat/148-instructions-author
git checkout feat/148-instructions-author
Sign in to join this conversation.
Reviewers
No Reviewers
Defame1297
Labels
Clear labels
Compat/Breaking
Breaking change that won't be backward compatible
 Kind/Bug
Something is not working
 Kind/Documentation
Documentation changes
 Kind/Enhancement
Improve existing functionality
 Kind/Feature
New functionality
 Kind/Security
This is security issue
 Kind/Testing
Issue or pull request related to testing
Priority
Critical
1
The priority is critical
Priority
High
2
The priority is high
Priority
Medium
3
The priority is medium
Priority
Low
4
The priority is low
Reviewed
Confirmed
1
Issue has been confirmed
Reviewed
Duplicate
2
This issue or pull request already exists
Reviewed
Invalid
3
Invalid issue
Reviewed
Won't Fix
3
This issue won't be fixed
Status
Blocked
1
Something is blocking this issue or pull request
Status
Need More Info
2
Feedback is required to reproduce issue or to continue work
Status
Abandoned
3
Somebody has started to work on this but abandoned work
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
Claude (Claude Code AI - Gitea MCP) renovate-bot Defame1297
No Assignees
2 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: Defame1297/holocron#154