-
Notifications
You must be signed in to change notification settings - Fork 1
refactor(prompts): migrate prompt library and align label governance #750
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Closed
Closed
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,69 @@ | ||
| --- | ||
| file_type: documentation | ||
| title: "Prompt Library Refactor & Migration - Issue Index" | ||
| description: "Parent and child specs for migrating organisation-wide prompts from .github/prompts to root prompts/" | ||
| version: "1.0.0" | ||
| created_date: "2026-06-01" | ||
| last_updated: "2026-06-01" | ||
| status: draft | ||
| --- | ||
|
|
||
| # Prompt Library Refactor & Migration — Issue Index | ||
|
|
||
| ## 3-Bullet Summary | ||
|
|
||
| - Value: Consolidates reusable prompts into root `prompts/` so teams get one canonical, org-wide library. | ||
| - Risks: Breaking existing `/prompt` references, duplicate prompt intent, and inconsistent LightSpeed standards. | ||
| - Next step: Execute child 01-1 classification and freeze a migration matrix before moving files. | ||
|
|
||
| ## Scope | ||
|
|
||
| This project defines the migration of prompts currently in `.github/prompts/` into root `prompts/` where prompts are organisation-wide and reusable across repositories. | ||
|
|
||
| Prompts that are `.github` control-plane specific stay in `.github/prompts/`. | ||
|
|
||
| ## Execution Docs | ||
|
|
||
| - `ISSUE_EXECUTION_PLAN.md` — run sequence and controls for `/opsx:propose` | ||
| - `ISSUE_REGISTER.md` — canonical parent/child issue tracker | ||
| - `RUN_LOG.md` — execution logging template for proposal runs | ||
| - `ISSUE_DRAFTS.md` — manual fallback issue bodies | ||
| - `openspec/` — standard OpenSpec proposal files | ||
| - `openspec-strict/` — strict parser variant (frontmatter: `name/about/labels`) | ||
|
|
||
| ## Directory Structure | ||
|
|
||
| ```text | ||
| refactor-migrate-prompts/ | ||
| ├── INDEX.md | ||
| ├── parents/ | ||
| │ └── 01-prompt-scope-classification-and-target-architecture.md | ||
| ├── children/ | ||
| │ ├── 01-1-inventory-and-classify-prompts.md | ||
| │ ├── 01-2-refactor-org-wide-prompts-to-root-standard.md | ||
| │ ├── 01-3-migrate-files-update-cross-references-and-deprecations.md | ||
| │ └── 01-4-validation-and-rollout.md | ||
| └── artifacts/ | ||
| └── migration-matrix.md | ||
| ``` | ||
|
|
||
| ## Parent/Child Breakdown | ||
|
|
||
| 1. Parent 01: Prompt scope classification and target architecture | ||
| 2. Child 01-1: Inventory and classify every `.github/prompts/*.prompt.md` | ||
| 3. Child 01-2: Refactor org-wide prompts to LightSpeed canonical style | ||
| 4. Child 01-3: Move files, add compatibility redirects, update references | ||
| 5. Child 01-4: Validate usage paths, quality gates, and rollout controls | ||
|
|
||
| ## Initial Review Outcome | ||
|
|
||
| - Current state: root `prompts/` already exists as canonical org-wide directory (7 stable prompts). | ||
| - Gap: `.github/prompts/` includes a mixed set of repo-local and potentially org-wide prompts. | ||
| - Decision rule: move only prompts that are tool/repo agnostic and useful across projects; keep GitHub control-plane automation prompts local. | ||
|
|
||
| ## References | ||
|
|
||
| - [Current .github prompt library](https://github.com/lightspeedwp/.github/tree/develop/.github/prompts) | ||
| - [Root prompts directory](https://github.com/lightspeedwp/.github/tree/develop/prompts) | ||
| - [Active projects directory](https://github.com/lightspeedwp/.github/tree/develop/.github/projects/active) | ||
| - `/Users/ash/.codex/worktrees/f767/.github/AGENTS.md` | ||
118 changes: 118 additions & 0 deletions
118
.github/projects/active/refactor-migrate-prompts/ISSUE_DRAFTS.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,118 @@ | ||
| --- | ||
| file_type: documentation | ||
| title: "Issue Drafts - Refactor Migrate Prompts" | ||
| description: "Manual fallback issue drafts aligned to OpenSpec strict proposal files" | ||
| version: "1.0.0" | ||
| last_updated: "2026-06-01" | ||
| status: active | ||
| --- | ||
|
|
||
| # Issue Drafts | ||
|
|
||
| ## Parent Epic Draft | ||
|
|
||
| - Title: `[Epic] Prompt library scope classification and migration governance` | ||
| - Template: `.github/ISSUE_TEMPLATE/05-epic.md` | ||
| - Labels: `status:needs-planning`, `priority:important`, `type:task`, `area:documentation`, `area:automation` | ||
|
|
||
| ### Body | ||
|
|
||
| Define and execute the migration strategy for prompt assets between `.github/prompts/` and root `prompts/`. | ||
|
|
||
| #### Goals | ||
|
|
||
| 1. Establish canonical prompt boundaries. | ||
| 2. Execute migration with explicit mapping, refactoring, and validation. | ||
| 3. Prevent path breakage with deprecation guidance and updated indexes. | ||
|
|
||
| #### Acceptance Criteria | ||
|
|
||
| - [ ] Final prompt matrix approved. | ||
| - [ ] Approved move set refactored to root standard. | ||
| - [ ] References and discoverability updated in both prompt directories. | ||
| - [ ] Validation completed for formatting, links, and smoke usage paths. | ||
|
|
||
| #### Child Issue Links | ||
|
|
||
| - [ ] Child 01-1 Inventory/classification | ||
| - [ ] Child 01-2 Refactor org-wide prompts | ||
| - [ ] Child 01-3 Migrate references/deprecations | ||
| - [ ] Child 01-4 Validation/rollout controls | ||
|
|
||
| ## Child Drafts | ||
|
|
||
| ### Child 01-1 | ||
|
|
||
| - Title: `[Task] Inventory and classify .github prompt assets with final target mapping` | ||
| - Template: `.github/ISSUE_TEMPLATE/22-audit.md` | ||
| - Labels: `status:needs-review`, `priority:important`, `type:audit`, `area:documentation` | ||
|
|
||
| Deliverables: | ||
|
|
||
| 1. Final migration matrix covering all source prompts. | ||
| 2. Explicit rename/target mapping for every moved prompt. | ||
| 3. Successor mapping for every merged/deprecated prompt. | ||
|
|
||
| Acceptance criteria: | ||
|
|
||
| - [ ] Matrix coverage equals source prompt count. | ||
| - [ ] Every `move` has a concrete `prompts/*.prompt` target path. | ||
| - [ ] Every `merge/deprecate` has a named successor prompt. | ||
| - [ ] Action counts are internally consistent with matrix rows. | ||
|
|
||
| ### Child 01-2 | ||
|
|
||
| - Title: `[Task] Refactor org-wide prompts to root prompts standard` | ||
| - Template: `.github/ISSUE_TEMPLATE/20-documentation.md` | ||
| - Labels: `status:needs-review`, `priority:important`, `type:documentation`, `area:documentation` | ||
|
|
||
| Deliverables: | ||
|
|
||
| 1. Refactored root prompt targets for all approved move items. | ||
| 2. Standardised frontmatter and section structure. | ||
| 3. Execution evidence listing produced files and validation checks. | ||
|
|
||
| Acceptance criteria: | ||
|
|
||
| - [ ] All move targets exist at mapped paths. | ||
| - [ ] Prompt files have consistent frontmatter and structure. | ||
| - [ ] Legacy intent is preserved during transition. | ||
| - [ ] Output evidence file documents completion and counts. | ||
|
|
||
| ### Child 01-3 | ||
|
|
||
| - Title: `[Task] Migrate files, update prompt references, and add deprecation paths` | ||
| - Template: `.github/ISSUE_TEMPLATE/01-task.md` | ||
| - Labels: `status:needs-review`, `priority:normal`, `type:task`, `area:documentation`, `area:automation` | ||
|
|
||
| Deliverables: | ||
|
|
||
| 1. Updated `prompts/README.md` with migrated prompt catalogue. | ||
| 2. Updated `.github/prompts/README.md` clarifying control-plane-only scope. | ||
| 3. Deprecation notes for legacy prompts that moved or merged. | ||
|
|
||
| Acceptance criteria: | ||
|
|
||
| - [ ] Both prompt READMEs reflect canonical boundaries. | ||
| - [ ] Legacy prompts include clear successor path notes where required. | ||
| - [ ] Link checks pass for prompt indexes and cross-references. | ||
| - [ ] Migration guidance is explicit and reproducible. | ||
|
|
||
| ### Child 01-4 | ||
|
|
||
| - Title: `[Task] Validate migrated prompt library and define rollout controls` | ||
| - Template: `.github/ISSUE_TEMPLATE/12-testing-coverage.md` | ||
| - Labels: `status:needs-review`, `priority:normal`, `type:task`, `area:quality`, `area:documentation` | ||
|
|
||
| Deliverables: | ||
|
|
||
| 1. Validation checklist and evidence (format, links, smoke usage). | ||
| 2. Known caveats and compatibility notes. | ||
| 3. Rollout and fallback guidance for one release cycle. | ||
|
|
||
| Acceptance criteria: | ||
|
|
||
| - [ ] Markdown/frontmatter validation passes for migrated files. | ||
| - [ ] Prompt index and cross-reference links resolve correctly. | ||
| - [ ] Representative prompt usage smoke tests are documented. | ||
| - [ ] Rollout notes specify fallback behaviour and sunset timing. |
48 changes: 48 additions & 0 deletions
48
.github/projects/active/refactor-migrate-prompts/ISSUE_EXECUTION_PLAN.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,48 @@ | ||
| --- | ||
| file_type: documentation | ||
| title: "Issue Execution Plan - Refactor Migrate Prompts" | ||
| description: "Operational plan for converting OpenSpec proposals into GitHub issues with template alignment" | ||
| version: "1.0.0" | ||
| last_updated: "2026-06-01" | ||
| status: active | ||
| --- | ||
|
|
||
| # Issue Execution Plan | ||
|
|
||
| ## 3-Bullet Summary | ||
|
|
||
| - Value: converts the completed spec pack into linked, trackable GitHub issues. | ||
| - Risks: template/label mismatch if `/opsx:propose` ignores `template-map` hints. | ||
| - Next step: run the strict OpenSpec files in order and record resulting issue URLs. | ||
|
|
||
| ## Sequence | ||
|
|
||
| 1. Propose parent epic. | ||
| 2. Propose each child issue. | ||
| 3. Link child issues back to parent. | ||
| 4. Update run log and issue register. | ||
|
|
||
| ## Proposal Commands | ||
|
|
||
| 1. `/opsx:propose .github/projects/active/refactor-migrate-prompts/openspec-strict/parents/01-epic-prompt-library-scope-and-migration-governance.md` | ||
| 2. `/opsx:propose .github/projects/active/refactor-migrate-prompts/openspec-strict/children/01-1-task-inventory-and-classify-prompts.md` | ||
| 3. `/opsx:propose .github/projects/active/refactor-migrate-prompts/openspec-strict/children/01-2-task-refactor-org-wide-prompts-to-root-standard.md` | ||
| 4. `/opsx:propose .github/projects/active/refactor-migrate-prompts/openspec-strict/children/01-3-task-migrate-files-update-references-and-deprecations.md` | ||
| 5. `/opsx:propose .github/projects/active/refactor-migrate-prompts/openspec-strict/children/01-4-task-validation-and-rollout-controls.md` | ||
|
|
||
| ## Template Mapping (Expected) | ||
|
|
||
| 1. Parent epic -> `.github/ISSUE_TEMPLATE/05-epic.md` | ||
| 2. Child 01-1 -> `.github/ISSUE_TEMPLATE/22-audit.md` | ||
| 3. Child 01-2 -> `.github/ISSUE_TEMPLATE/20-documentation.md` | ||
| 4. Child 01-3 -> `.github/ISSUE_TEMPLATE/01-task.md` | ||
| 5. Child 01-4 -> `.github/ISSUE_TEMPLATE/12-testing-coverage.md` | ||
|
|
||
| ## Post-Proposal Checklist | ||
|
|
||
| - [ ] Issue created for parent epic. | ||
| - [ ] Four child issues created. | ||
| - [ ] Parent/child links added in issue bodies. | ||
| - [ ] Labels verified (`status:*`, `priority:*`, `type:*`, `area:*`). | ||
| - [ ] `RUN_LOG.md` updated with result and issue URL. | ||
| - [ ] `ISSUE_REGISTER.md` updated with final IDs and status. |
18 changes: 18 additions & 0 deletions
18
.github/projects/active/refactor-migrate-prompts/ISSUE_REGISTER.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,18 @@ | ||
| --- | ||
| file_type: documentation | ||
| title: "Issue Register - Refactor Migrate Prompts" | ||
| description: "Canonical register for parent/child issue IDs, status, and evidence links" | ||
| version: "1.0.0" | ||
| last_updated: "2026-06-01" | ||
| status: active | ||
| --- | ||
|
|
||
| # Issue Register | ||
|
|
||
| | Key | OpenSpec File | Template | GitHub Issue URL | Status | Owner | Evidence | | ||
| |---|---|---|---|---|---|---| | ||
| | EPIC-01 | `openspec-strict/parents/01-epic-prompt-library-scope-and-migration-governance.md` | `05-epic.md` | `https://github.com/lightspeedwp/.github/issues/736` | open | Ash | `Parent with linked children` | | ||
| | CHILD-01-1 | `openspec-strict/children/01-1-task-inventory-and-classify-prompts.md` | `22-audit.md` | `https://github.com/lightspeedwp/.github/issues/737` | open | Ash | `artifacts/migration-matrix.md` | | ||
| | CHILD-01-2 | `openspec-strict/children/01-2-task-refactor-org-wide-prompts-to-root-standard.md` | `20-documentation.md` | `https://github.com/lightspeedwp/.github/issues/738` | open | Ash | `artifacts/01-2-refactor-output.md` | | ||
| | CHILD-01-3 | `openspec-strict/children/01-3-task-migrate-files-update-references-and-deprecations.md` | `01-task.md` | `https://github.com/lightspeedwp/.github/issues/739` | open | Ash | `artifacts/01-3-migration-output.md` | | ||
| | CHILD-01-4 | `openspec-strict/children/01-4-task-validation-and-rollout-controls.md` | `12-testing-coverage.md` | `https://github.com/lightspeedwp/.github/issues/740` | open | Ash | `artifacts/01-4-validation-output.md` | |
82 changes: 82 additions & 0 deletions
82
.github/projects/active/refactor-migrate-prompts/RUN_LOG.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,82 @@ | ||
| --- | ||
| file_type: documentation | ||
| title: "Run Log - /opsx:propose Execution" | ||
| description: "Execution log for OpenSpec proposal runs and issue creation outcomes" | ||
| version: "1.0.0" | ||
| last_updated: "2026-06-01" | ||
| status: active | ||
| --- | ||
|
|
||
| # Run Log | ||
|
|
||
| ## Instructions | ||
|
|
||
| For each `/opsx:propose` execution, append one entry using the template below. | ||
|
|
||
| ```markdown | ||
| ### YYYY-MM-DD HH:MM TZ - <file-key> | ||
| - command: `/opsx:propose <path>` | ||
| - expected-template: `<issue-template-file>` | ||
| - result: `success | failed | partial` | ||
| - github-issue-url: `<url-or-TBD>` | ||
| - labels-applied: `[label1, label2, ...]` | ||
| - notes: `<parser behaviour, overrides, or fixes>` | ||
| ``` | ||
|
|
||
| ## Entries | ||
|
|
||
| ### 2026-06-01 19:10 Europe/Berlin - setup | ||
| - command: `n/a` | ||
| - expected-template: `n/a` | ||
| - result: `success` | ||
| - github-issue-url: `n/a` | ||
| - labels-applied: `[]` | ||
| - notes: `Run log initialized. Ready for /opsx:propose execution.` | ||
|
|
||
| ### 2026-06-01 19:22 Europe/Berlin - EPIC-01 | ||
| - command: `/opsx:propose .github/projects/active/refactor-migrate-prompts/openspec-strict/parents/01-epic-prompt-library-scope-and-migration-governance.md` | ||
| - expected-template: `.github/ISSUE_TEMPLATE/05-epic.md` | ||
| - result: `success` | ||
| - github-issue-url: `https://github.com/lightspeedwp/.github/issues/736` | ||
| - labels-applied: `[status:needs-planning, priority:important, type:task, area:documentation, area:automation]` | ||
| - notes: `Issue created and parent child section added.` | ||
|
|
||
| ### 2026-06-01 19:23 Europe/Berlin - CHILD-01-1 | ||
| - command: `/opsx:propose .github/projects/active/refactor-migrate-prompts/openspec-strict/children/01-1-task-inventory-and-classify-prompts.md` | ||
| - expected-template: `.github/ISSUE_TEMPLATE/22-audit.md` | ||
| - result: `success` | ||
| - github-issue-url: `https://github.com/lightspeedwp/.github/issues/737` | ||
| - labels-applied: `[status:needs-review, priority:important, type:audit, area:documentation]` | ||
| - notes: `Parent backlink added.` | ||
|
|
||
| ### 2026-06-01 19:23 Europe/Berlin - CHILD-01-2 | ||
| - command: `/opsx:propose .github/projects/active/refactor-migrate-prompts/openspec-strict/children/01-2-task-refactor-org-wide-prompts-to-root-standard.md` | ||
| - expected-template: `.github/ISSUE_TEMPLATE/20-documentation.md` | ||
| - result: `success` | ||
| - github-issue-url: `https://github.com/lightspeedwp/.github/issues/738` | ||
| - labels-applied: `[status:needs-review, priority:important, type:documentation, area:documentation]` | ||
| - notes: `Parent backlink added.` | ||
|
|
||
| ### 2026-06-01 19:24 Europe/Berlin - CHILD-01-3 | ||
| - command: `/opsx:propose .github/projects/active/refactor-migrate-prompts/openspec-strict/children/01-3-task-migrate-files-update-references-and-deprecations.md` | ||
| - expected-template: `.github/ISSUE_TEMPLATE/01-task.md` | ||
| - result: `success` | ||
| - github-issue-url: `https://github.com/lightspeedwp/.github/issues/739` | ||
| - labels-applied: `[status:needs-review, priority:normal, type:task, area:documentation, area:automation]` | ||
| - notes: `Parent backlink added.` | ||
|
|
||
| ### 2026-06-01 19:27 Europe/Berlin - CHILD-01-4 | ||
| - command: `/opsx:propose .github/projects/active/refactor-migrate-prompts/openspec-strict/children/01-4-task-validation-and-rollout-controls.md` | ||
| - expected-template: `.github/ISSUE_TEMPLATE/12-testing-coverage.md` | ||
| - result: `partial` | ||
| - github-issue-url: `https://github.com/lightspeedwp/.github/issues/740` | ||
| - labels-applied: `[status:needs-review, priority:normal, type:task, area:documentation, area:testing]` | ||
| - notes: `Original label area:quality does not exist in repository; normalized to area:testing. Parent backlink added.` | ||
|
|
||
| ### 2026-06-01 19:41 Europe/Berlin - label taxonomy sync | ||
| - command: `manual label sync + issue label correction` | ||
| - expected-template: `n/a` | ||
| - result: `success` | ||
| - github-issue-url: `https://github.com/lightspeedwp/.github/issues/740` | ||
| - labels-applied: `[status:needs-review, priority:normal, type:task, area:documentation, area:quality]` | ||
| - notes: `Added canonical label area:quality to .github/labels.yml and GitHub repository labels, then switched issue #740 from area:testing to area:quality.` |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Avoid using absolute local file paths (e.g.,
/Users/ash/...) in documentation as they are environment-specific and will not resolve for other contributors or in CI environments. Please use a relative path to referenceAGENTS.mdinstead.