Skip to content

Make the repo an APM producer (ai-toolkit) with .apm/ as source of truth#15

Merged
DevSecNinja merged 10 commits into
mainfrom
copilot/feat-apm-investigate-artifacts
Jun 21, 2026
Merged

Make the repo an APM producer (ai-toolkit) with .apm/ as source of truth#15
DevSecNinja merged 10 commits into
mainfrom
copilot/feat-apm-investigate-artifacts

Conversation

Copilot AI commented Jun 20, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Turns this repo into an APM (Agent Package Manager) producer named ai-toolkit, so consumers can install every primitive as native harness commands (Copilot, Claude, Cursor, OpenCode, Gemini, Windsurf):

apm install DevSecNinja/ai-toolkit

⚠️ Requires renaming the GitHub repo to ai-toolkit for the install path to resolve (badges left pointing at the current slug until then).

Architecture: .apm/ is the single source of truth

Primitives are authored directly under .apm/prompts/ in native APM format. INDEX.md and the README index are generated from .apm/ — there is no parallel browsable tree to keep in sync. This makes it trivial to grow into .apm/instructions/, .apm/agents/, .apm/hooks/ and .apm/skills/: just add the folder.

(This supersedes the original approach in this PR, which kept prompts/** as source and generated .apm/ — a double tree that would compound complexity as scope grows. See the discussion in the review threads.)

Changes

  • .apm/prompts/*.prompt.md — 10 prompt primitives migrated from the old prompts/** tree, bodies preserved byte-for-byte. Required description + category frontmatter; optional title/tags/model/platform/example/notes.
  • apm.yml — producer manifest (name: ai-toolkit, includes: auto). version bumped by release-please via extra-files.
  • scripts/generate-index.sh — rewritten to generate INDEX.md + README index from .apm/ frontmatter. Output is fully deterministic (no timestamp), so re-running produces no diff and PR index runs don't attempt spurious commits/pushes.
  • tests/validate-prompts.sh — rewritten to validate .apm/ primitives (frontmatter, description, category, non-empty body).
  • .github/workflows/markdown-validation.yml — path filters point at .apm/prompts/**/*.prompt.md (the new source of truth) so validation runs for changes to shipped primitives.
  • Removed prompts/**, scripts/generate-apm-primitives.sh, and the feedback-link script/workflow.
  • release-please — .github/workflows/release-please.yml (central DevSecNinja/.github@v1.7.0 reusable, App-token auth), release-please-config.json (release-type: simple, bumps apm.yml via extra-files), .release-please-manifest.json. Replaces the old post-release sync-apm-version.yml/.sh, fixing the pinned-install version-staleness.
  • docs/apm.md — producer guide: source-of-truth model, generation, consumption, per-harness landing paths, release-please versioning.
  • Updated README.md (keyword-rich, harness-neutral), CONTRIBUTING.md, PROMPT_TEMPLATE.md, the add-prompt prompt, copilot-instructions.md, devcontainer + welcome.

Versioning / first release

Manifest + apm.yml are seeded at 0.0.0 so the first release-please run cuts 0.1.0 (a feat: commit pre-1.0.0 bumps the minor under this config). The release PR opens as a draft (draft-pull-request: true).

Manual prerequisites for release-please (per the org onboarding guide)

  1. Install the DevSecNinja Release Please GitHub App on the repo.
  2. Add RELEASE_PLEASE_APP_ID (variable) + RELEASE_PLEASE_APP_PRIVATE_KEY (secret).
  3. Enable Settings → Actions → General → "Allow GitHub Actions to create and approve pull requests".

Notes for reviewers

  • Primitives are authored, not generated — edit .apm/prompts/** directly and rerun bash scripts/generate-index.sh.
  • validate-prompts.sh now covers .apm/prompts/** and .github/prompts/**.
  • Command names are <category><name> (e.g. coding-code-review-assistant) to avoid cross-category collisions.

Copilot AI changed the title [WIP] Investigate how this repo can produce artifacts Make the repo an APM producer with generated prompt primitives Jun 20, 2026
Copilot AI requested a review from DevSecNinja June 20, 2026 20:12
DevSecNinja
DevSecNinja reviewed Jun 20, 2026
View reviewed changes
Comment thread apm.yml Outdated
# The installable prompt primitives live under .apm/prompts/ and are generated
# from the browsable prompts/ collection by scripts/generate-apm-primitives.sh.
name: gpt-prompts
version: 1.0.0

@DevSecNinja DevSecNinja Jun 20, 2026

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we make this somehow sync up with the GH release version?

Comment thread apm.yml Outdated
# https://microsoft.github.io/apm/producer/
#
# This manifest turns the repository into an APM producer. Consumers can run
# apm install DevSecNinja/gpt-prompts

@DevSecNinja DevSecNinja Jun 20, 2026

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if we should limit ourselves to gpt-prompts and maybe we should rename the project as well as the GitHub project? What is the most common name for these kind of repos?

@DevSecNinja DevSecNinja requested a review from Copilot June 20, 2026 20:20
Copilot AI reviewed Jun 20, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR turns the prompt collection into an APM (Agent Package Manager) producer, keeping prompts/** as the single source of truth while committing generated .apm/prompts/*.prompt.md artifacts and updating CI to keep them in sync.

Changes:

  • Add apm.yml producer manifest and documentation for producing/consuming APM primitives.
  • Introduce scripts/generate-apm-primitives.sh to deterministically generate .apm/prompts/*.prompt.md from prompts/**.
  • Update the existing index-generation workflow and docs to include .apm/prompts generation and syncing.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 1 comment.

Show a summary per file
File Description
scripts/generate-apm-primitives.sh New generator that transforms prompts/** into APM prompt primitives under .apm/prompts/.
apm.yml Adds the APM producer manifest (includes .apm/ artifacts via includes: auto).
.github/workflows/generate-index.yml Runs APM primitive generation alongside index generation and commits .apm/prompts updates.
docs/apm.md Adds a producer guide explaining artifacts, generation, and consumption paths.
README.md Documents APM installation and links to the producer guide.
CONTRIBUTING.md Adds a contribution tip to regenerate and commit .apm/prompts artifacts.
INDEX.md Updates the auto-generated “Last updated” timestamp.
.apm/prompts/analysis-data-analysis.prompt.md Generated APM primitive for the Analysis prompt.
.apm/prompts/coding-code-review-assistant.prompt.md Generated APM primitive for the Coding prompt.
.apm/prompts/coding-debug-helper.prompt.md Generated APM primitive for the Coding prompt.
.apm/prompts/home-assistant-automation-renamer.prompt.md Generated APM primitive for the Home Assistant prompt.
.apm/prompts/home-assistant-notification-optimizer.prompt.md Generated APM primitive for the Home Assistant prompt.
.apm/prompts/productivity-email-follow-up-tracker.prompt.md Generated APM primitive for the Productivity prompt.
.apm/prompts/productivity-focus-time-blocker.prompt.md Generated APM primitive for the Productivity prompt.
.apm/prompts/productivity-ooo-task-handoff-planner.prompt.md Generated APM primitive for the Productivity prompt.
.apm/prompts/productivity-outlook-inbox-zero-triage.prompt.md Generated APM primitive for the Productivity prompt.
.apm/prompts/writing-technical-documentation.prompt.md Generated APM primitive for the Writing prompt.

Comment thread docs/apm.md Outdated
Comment on lines +60 to +69
`apm install` deploys each prompt to every detected harness, for example:

| Harness | Where the prompt lands | How to invoke |
|---------|------------------------|---------------|
| GitHub Copilot | `.github/prompts/<name>.prompt.md` | prompts picker |
| Claude Code | `.claude/commands/<name>.md` | `/<name>` |
| Cursor | `.cursor/commands/<name>.md` | `/<name>` |
| OpenCode | `.opencode/commands/<name>.md` | `/<name>` |
| Gemini | `.gemini/commands/<name>.toml` | `/<name>` |
| Windsurf | `.windsurf/workflows/<name>.md` | workflows menu |
@DevSecNinja

DevSecNinja commented Jun 20, 2026

Copy link
Copy Markdown
Owner

@copilot can you process the review comments?

Copilot AI commented Jun 20, 2026

Copy link
Copy Markdown
Contributor Author

@copilot can you process the review comments?

Processed the review comments in ee245dc:

  • docs/apm.md placeholder inconsistency — the harness table and its lead-in sentence now consistently use <category>-<name> (e.g. coding-code-review-assistant), matching the actual generated command names.
  • Sync apm.yml version with the GH release — added scripts/sync-apm-version.sh and a Sync APM Version workflow (.github/workflows/sync-apm-version.yml) that fires on release: published/edited, strips any leading v from the tag, writes it into apm.yml, and commits back to main. Cutting a GitHub release now drives the manifest version (also runnable via workflow_dispatch). Documented under a new "Versioning" section in docs/apm.md.
  • Naming / rename question — left name: gpt-prompts as-is since I can't rename the GitHub repo from here, but for context: there's no single dominant convention for these collections. Common patterns are awesome-* (e.g. awesome-prompts), *-prompts / prompt-library / prompt-collection, and harness-specific names like copilot-prompts or claude-prompts. Since this now ships as an APM package, the package name is what consumers type in apm install <owner>/<repo>, so the repo name and APM name ideally match. gpt-prompts is clear and accurate; if you want to signal multi-harness support, something like prompt-library or ai-prompts would read more harness-neutral. Happy to update apm.yml/docs once you settle on a name.

Copilot AI requested a review from DevSecNinja June 20, 2026 20:33
DevSecNinja and others added 2 commits June 21, 2026 07:25
@DevSecNinja
refactor: Invert to .apm/ as source of truth and rename to ai-toolkit
fae79f2 
Make .apm/ the single source of truth for APM primitives instead of
generating it from a parallel prompts/** tree. The browsable index
(INDEX.md + README) is now generated FROM .apm/, eliminating the
double-generation flow and making it trivial to grow into instructions,
agents and hooks under .apm/.

- Migrate all 10 prompts into native APM source primitives under
  .apm/prompts/ with description/category (+ optional title, tags, model,
  platform, example, notes). Prompt bodies preserved byte-for-byte.
- Remove prompts/**, scripts/generate-apm-primitives.sh, and the
  feedback-link script/workflow (per-file feedback links dropped in favor
  of the future site).
- Rewrite generate-index.sh to read .apm/ frontmatter; rewrite
  validate-prompts.sh to validate .apm/ primitives.
- Rename package to ai-toolkit (apm.yml, README, docs, devcontainer,
  welcome, contributing, templates, copilot-instructions).
- Document the version-sync lag and recommend workflow_dispatch pre-bump
  for pinned installs.

Note: GitHub repo must be renamed to ai-toolkit for
`apm install DevSecNinja/ai-toolkit` to resolve.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@github-actions
docs: Update index [skip ci]
66df1e6
@DevSecNinja

DevSecNinja commented Jun 21, 2026

Copy link
Copy Markdown
Owner

Pushed fae79f2 — reworked this PR based on the discussion in the review threads.

Architecture inverted: .apm/ is now the single source of truth.
The original approach kept prompts/** as source and generated .apm/. That double tree is the complexity that would compound as we add instructions/agents/hooks. Now primitives are authored directly under .apm/prompts/ in native APM format, and INDEX.md + the README index are generated from .apm/. Adding new primitive types is just a new folder (.apm/instructions/, .apm/agents/, .apm/hooks/, .apm/skills/).

What changed:

  • Migrated all 10 prompts into enriched APM source files (description/category required; optional title/tags/model/platform/example/notes). Prompt bodies preserved byte-for-byte (verified; caught + fixed a bug where fenced ## Step headings in the Outlook prompt were being parsed as section breaks).
  • Deleted prompts/**, scripts/generate-apm-primitives.sh, and the feedback-link script/workflow (per-file feedback links are better regenerated by the planned site than embedded).
  • Rewrote generate-index.sh (reads .apm/ frontmatter) and validate-prompts.sh (validates .apm/ primitives). Both pass; index generation is idempotent.
  • Updated apm.yml, docs/apm.md, README.md, CONTRIBUTING.md, PROMPT_TEMPLATE.md, the add-prompt prompt, copilot-instructions.md, devcontainer + welcome.

Resolving the three threads:

  1. Version ↔ GH release sync — kept the release-triggered sync-apm-version.sh workflow. Documented its one real flaw in docs/apm.md: the bump lands on main after the tag, so the tagged tree still holds the old version. apm install from latest is always correct; for pinned installs, pre-bump via workflow_dispatch before tagging.
  2. Naming — renamed package to ai-toolkit (broad/brandable, room for non-prompt primitives). Discovery is handled via a keyword-rich README headline + topics rather than the slug. ⚠️ The GitHub repo still needs to be renamed to ai-toolkit for apm install DevSecNinja/ai-toolkit to resolve — flagged in README/docs.
  3. docs placeholder <category>-<name> — carried forward; the table is consistent.

DevSecNinja and others added 2 commits June 21, 2026 07:49
@DevSecNinja
ci: Integrate release-please for versioning and releases
0077681 
Adopt the central DevSecNinja/.github release-please reusable workflow to
drive semver bumping, CHANGELOG.md generation, tagging and GitHub Releases
from Conventional Commits.

- Add .github/workflows/release-please.yml calling the reusable workflow
  @v1.7.0 with App-token auth (vars.RELEASE_PLEASE_APP_ID +
  secrets.RELEASE_PLEASE_APP_PRIVATE_KEY).
- Add release-please-config.json (release-type: simple) and
  .release-please-manifest.json pinned at 1.0.0.
- Bump apm.yml version inside the release PR via the config's extra-files
  (generic updater keyed off the `x-release-please-version` annotation), so
  the tagged commit always carries the matching version — fixing the
  pinned-install staleness of the old post-release sync.
- Remove the superseded sync-apm-version.yml workflow and
  sync-apm-version.sh script.
- Document the release-please flow in docs/apm.md and update
  copilot-instructions.md.

Note: requires the GitHub App installed on the repo, the
RELEASE_PLEASE_APP_ID variable + RELEASE_PLEASE_APP_PRIVATE_KEY secret, and
"Allow GitHub Actions to create and approve pull requests" enabled.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@github-actions
docs: Update index [skip ci]
17d9ecd
@DevSecNinja

DevSecNinja commented Jun 21, 2026

Copy link
Copy Markdown
Owner

Pushed 0077681 — integrated release-please for versioning/releases, matching the DevSecNinja/.github reusable-workflow pattern.

Added:

  • .github/workflows/release-please.yml — calls DevSecNinja/.github/.github/workflows/release-please.yml@v1.7.0 (pinned SHA), App-token auth via vars.RELEASE_PLEASE_APP_ID + secrets.RELEASE_PLEASE_APP_PRIVATE_KEY. (No notify-irm job — that's homelab-specific and needs a secret this repo doesn't have.)
  • release-please-config.json — release-type: simple, include-v-in-tag: true, skip-github-release: false (this repo has no separate tag-triggered release.yml, so release-please creates the GitHub Release itself).
  • .release-please-manifest.json — pinned at 1.0.0.

Version-sync, properly fixed: release-please-config.json uses extra-files to bump apm.yml's version: inside the release PR (generic updater keyed off the # x-release-please-version annotation). The bump now lands in the tagged commit, so pinned installs (@1.2.3) resolve to a tree whose apm.yml actually says 1.2.3. This supersedes the old post-release sync-apm-version.yml / sync-apm-version.sh, which I removed — closing the version-sync thread for real.

Docs: rewrote the Versioning section in docs/apm.md and updated copilot-instructions.md.

⚠️ Manual prerequisites (per the org onboarding guide) — you mentioned you'll handle the App id/secret:

  1. Install the DevSecNinja Release Please App on this repo.
  2. Add RELEASE_PLEASE_APP_ID (variable) + RELEASE_PLEASE_APP_PRIVATE_KEY (secret).
  3. Enable Settings → Actions → General → "Allow GitHub Actions to create and approve pull requests".

Note: the manifest/apm.yml are pinned at 1.0.0 with no v1.0.0 tag yet. The first merge to main with a feat:/fix: commit will open a release PR for the next version. To stamp the current state as v1.0.0, push an empty commit with a Release-As: 1.0.0 footer.

DevSecNinja and others added 2 commits June 21, 2026 08:23
@DevSecNinja
chore: Seed version at 0.0.0 for first 0.1.0 release
4bf7f01 
Pin the release-please manifest and apm.yml at 0.0.0 so the first
release-please run bumps to 0.1.0 (a feat commit pre-1.0.0 bumps the
minor under this config).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@github-actions
docs: Update index [skip ci]
a8d0b7d
@DevSecNinja DevSecNinja changed the title Make the repo an APM producer with generated prompt primitives Make the repo an APM producer (ai-toolkit) with .apm/ as source of truth Jun 21, 2026
@DevSecNinja

DevSecNinja commented Jun 21, 2026

Copy link
Copy Markdown
Owner

@copilot Can you review this PR?

Copilot AI commented Jun 21, 2026

Copy link
Copy Markdown
Contributor Author

@copilot Can you review this PR?

Review completed. I found two issues worth fixing before merge:

  1. Medium — prompt validation CI no longer runs for shipped primitives
    .github/workflows/markdown-validation.yml:7-12 still filters on prompts/**/*.md, but prompts/ was removed and .apm/prompts/ is now source of truth. Changes to shipped primitives can skip tests/validate-prompts.sh in CI. Suggested fix: replace the stale path filter with .apm/prompts/**/*.prompt.md (or .apm/**).

  2. Medium — PR index workflow can fail because generation is non-deterministic
    scripts/generate-index.sh:42 writes the current timestamp on every run. On pull_request, .github/workflows/generate-index.yml:36-51 then detects a diff and tries to commit/push it back. Fork PR tokens are read-only, so even already-regenerated PRs can fail due only to the timestamp. Suggested fix: make generated output deterministic, or make PR runs verify cleanliness without pushing.

I also ran bash tests/validate-prompts.sh successfully. bash scripts/generate-index.sh only produced the expected timestamp-only diff, which I discarded locally.

@DevSecNinja

DevSecNinja commented Jun 21, 2026

Copy link
Copy Markdown
Owner

@copilot Can you fix the findings mentioned in the last comment?

Copilot AI commented Jun 21, 2026

Copy link
Copy Markdown
Contributor Author

@copilot Can you fix the findings mentioned in the last comment?

Fixed both findings:

  1. Stale CI path filter — markdown-validation.yml now triggers on .apm/prompts/**/*.prompt.md instead of the removed prompts/**, so changes to shipped primitives run validate-prompts.sh again.
  2. Non-deterministic index generation — generate-index.sh no longer stamps a timestamp into INDEX.md. Output is now idempotent (verified across repeated runs), so already-regenerated PRs produce no diff and the generate-index workflow won't try to push timestamp-only changes (which fails on read-only fork tokens).

README.md is unchanged after regeneration and validate-prompts.sh passes.

@DevSecNinja DevSecNinja marked this pull request as ready for review June 21, 2026 08:48
@DevSecNinja DevSecNinja merged commit 48e2190 into main Jun 21, 2026
3 checks passed
@DevSecNinja DevSecNinja deleted the copilot/feat-apm-investigate-artifacts branch June 21, 2026 08:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments
@DevSecNinja DevSecNinja Awaiting requested review from DevSecNinja DevSecNinja is a code owner

Assignees

@DevSecNinja DevSecNinja

Copilot code review Copilot

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@DevSecNinja