From 8721482d16504b497d594ae5526b83134cafdbcd Mon Sep 17 00:00:00 2001 From: packmind-bot Date: Wed, 17 Jun 2026 03:12:47 +0000 Subject: [PATCH 1/2] chore(packmind): nightly artifacts update --- apps/api/packmind-lock.json | 2 +- apps/cli/packmind-lock.json | 2 +- apps/e2e-tests/packmind-lock.json | 2 +- apps/frontend/packmind-lock.json | 2 +- packages/integration-tests/packmind-lock.json | 2 +- packages/migrations/packmind-lock.json | 2 +- packages/packmind-lock.json | 2 +- packages/ui/packmind-lock.json | 2 +- packmind-lock.json | 2 +- 9 files changed, 9 insertions(+), 9 deletions(-) diff --git a/apps/api/packmind-lock.json b/apps/api/packmind-lock.json index 9e3a2de07..8bf23b5a0 100644 --- a/apps/api/packmind-lock.json +++ b/apps/api/packmind-lock.json @@ -11,7 +11,7 @@ "gitlab_duo", "packmind" ], - "installedAt": "2026-06-16T03:12:26.672Z", + "installedAt": "2026-06-17T03:12:44.721Z", "artifacts": { "user:standard:nestjs-module-hierarchy": { "name": "NestJS Module Hierarchy", diff --git a/apps/cli/packmind-lock.json b/apps/cli/packmind-lock.json index c7adaaf3c..78d4b7a0c 100644 --- a/apps/cli/packmind-lock.json +++ b/apps/cli/packmind-lock.json @@ -11,7 +11,7 @@ "gitlab_duo", "packmind" ], - "installedAt": "2026-06-16T03:12:27.021Z", + "installedAt": "2026-06-17T03:12:45.033Z", "artifacts": { "user:standard:cli-command-structure": { "name": "CLI Command Structure", diff --git a/apps/e2e-tests/packmind-lock.json b/apps/e2e-tests/packmind-lock.json index 0cf47fcf0..f9cdcf86c 100644 --- a/apps/e2e-tests/packmind-lock.json +++ b/apps/e2e-tests/packmind-lock.json @@ -11,7 +11,7 @@ "gitlab_duo", "packmind" ], - "installedAt": "2026-06-16T03:12:27.337Z", + "installedAt": "2026-06-17T03:12:45.320Z", "artifacts": { "user:standard:e2e-page-object": { "name": "[E2E] Page object", diff --git a/apps/frontend/packmind-lock.json b/apps/frontend/packmind-lock.json index 2d3aa9db8..33ef9a80c 100644 --- a/apps/frontend/packmind-lock.json +++ b/apps/frontend/packmind-lock.json @@ -11,7 +11,7 @@ "gitlab_duo", "packmind" ], - "installedAt": "2026-06-16T03:12:27.646Z", + "installedAt": "2026-06-17T03:12:45.612Z", "artifacts": { "user:standard:frontend-data-flow": { "name": "Frontend Data Flow", diff --git a/packages/integration-tests/packmind-lock.json b/packages/integration-tests/packmind-lock.json index 6cdfbb164..f89c5ee3a 100644 --- a/packages/integration-tests/packmind-lock.json +++ b/packages/integration-tests/packmind-lock.json @@ -11,7 +11,7 @@ "gitlab_duo", "packmind" ], - "installedAt": "2026-06-16T03:12:28.363Z", + "installedAt": "2026-06-17T03:12:46.247Z", "artifacts": { "user:standard:integration-tests-structure-and-patterns": { "name": "Integration Tests Structure and Patterns", diff --git a/packages/migrations/packmind-lock.json b/packages/migrations/packmind-lock.json index ef1b77963..2a34998fc 100644 --- a/packages/migrations/packmind-lock.json +++ b/packages/migrations/packmind-lock.json @@ -11,7 +11,7 @@ "gitlab_duo", "packmind" ], - "installedAt": "2026-06-16T03:12:28.638Z", + "installedAt": "2026-06-17T03:12:46.521Z", "artifacts": { "user:command:create-or-update-model-and-typeorm-schemas": { "name": "Create or update model and TypeORM schemas", diff --git a/packages/packmind-lock.json b/packages/packmind-lock.json index bdce2ef48..e0ea1740a 100644 --- a/packages/packmind-lock.json +++ b/packages/packmind-lock.json @@ -11,7 +11,7 @@ "gitlab_duo", "packmind" ], - "installedAt": "2026-06-16T03:12:28.041Z", + "installedAt": "2026-06-17T03:12:45.952Z", "artifacts": { "user:standard:back-end-repositories-sql-queries-using-typeorm": { "name": "Back-end repositories SQL queries using TypeORM", diff --git a/packages/ui/packmind-lock.json b/packages/ui/packmind-lock.json index 3bbea99d0..345bc6daf 100644 --- a/packages/ui/packmind-lock.json +++ b/packages/ui/packmind-lock.json @@ -11,7 +11,7 @@ "gitlab_duo", "packmind" ], - "installedAt": "2026-06-16T03:12:28.934Z", + "installedAt": "2026-06-17T03:12:46.802Z", "artifacts": { "user:standard:front-end-ui-and-design-systems": { "name": "Front-end UI and Design Systems", diff --git a/packmind-lock.json b/packmind-lock.json index d704edb6b..52e795f22 100644 --- a/packmind-lock.json +++ b/packmind-lock.json @@ -15,7 +15,7 @@ "gitlab_duo", "packmind" ], - "installedAt": "2026-06-16T03:12:25.740Z", + "installedAt": "2026-06-17T03:12:43.940Z", "artifacts": { "user:skill:cli-e2e-test-authoring": { "name": "cli-e2e-test-authoring", From a6e82c666738af50bc05292db75fa30c9dc0a120 Mon Sep 17 00:00:00 2001 From: packmind-bot Date: Thu, 18 Jun 2026 03:12:15 +0000 Subject: [PATCH 2/2] chore(packmind): nightly artifacts update --- .../skills/cli-e2e-test-authoring/SKILL.md | 192 +++++++++ .opencode/skills/packmind-onboard/LICENSE.txt | 177 ++++++++ .opencode/skills/packmind-onboard/README.md | 46 +++ .opencode/skills/packmind-onboard/SKILL.md | 328 +++++++++++++++ .../0.16.0/completion-summary.md | 64 +++ .../packmind-versions/0.16.0/create-items.md | 240 +++++++++++ .../0.16.0/create-package.md | 5 + .../packmind-versions/0.16.0/list-packages.md | 5 + .../0.16.0/select-package.md | 3 + .../0.23.0/completion-summary.md | 69 ++++ .../packmind-versions/0.23.0/create-items.md | 185 +++++++++ .../0.23.0/create-package.md | 18 + .../packmind-versions/0.23.0/list-packages.md | 5 + .../0.23.0/select-package.md | 10 + .../references/ci-local-workflow-parity.md | 221 ++++++++++ .../references/file-template-consistency.md | 180 +++++++++ .../references/role-taxonomy-drift.md | 199 +++++++++ .../references/test-data-construction.md | 136 +++++++ .../packmind-update-playbook/LICENSE.txt | 177 ++++++++ .../skills/packmind-update-playbook/SKILL.md | 143 +++++++ .../packmind-versions/0.21.0/apply-changes.md | 50 +++ .../packmind-versions/0.23.0/apply-changes.md | 110 +++++ .../references/agent-skills-specification.md | 255 ++++++++++++ .../references/create-command-procedure.md | 102 +++++ .../references/create-skill-procedure.md | 97 +++++ .../references/create-standard-procedure.md | 62 +++ .../steps/analyze-commands.md | 57 +++ .../steps/analyze-skills.md | 77 ++++ .../steps/analyze-standards.md | 76 ++++ .../working-with-playground-app/SKILL.md | 182 +++++++++ .../references/frontend-domain-structure.md | 33 ++ .../working-with-pm-design-kit/SKILL.md | 341 ++++++++++++++++ .../references/component-catalog.md | 118 ++++++ apps/api/packmind-lock.json | 4 +- apps/cli/packmind-lock.json | 4 +- apps/e2e-tests/packmind-lock.json | 4 +- apps/frontend/packmind-lock.json | 4 +- packages/integration-tests/packmind-lock.json | 4 +- ...ate-or-update-model-and-typeorm-schemas.md | 101 +++++ packages/migrations/packmind-lock.json | 8 +- packages/packmind-lock.json | 4 +- packages/ui/packmind-lock.json | 4 +- packmind-lock.json | 380 +++++++++++++++++- 43 files changed, 4471 insertions(+), 9 deletions(-) create mode 100644 .opencode/skills/cli-e2e-test-authoring/SKILL.md create mode 100644 .opencode/skills/packmind-onboard/LICENSE.txt create mode 100644 .opencode/skills/packmind-onboard/README.md create mode 100644 .opencode/skills/packmind-onboard/SKILL.md create mode 100644 .opencode/skills/packmind-onboard/packmind-versions/0.16.0/completion-summary.md create mode 100644 .opencode/skills/packmind-onboard/packmind-versions/0.16.0/create-items.md create mode 100644 .opencode/skills/packmind-onboard/packmind-versions/0.16.0/create-package.md create mode 100644 .opencode/skills/packmind-onboard/packmind-versions/0.16.0/list-packages.md create mode 100644 .opencode/skills/packmind-onboard/packmind-versions/0.16.0/select-package.md create mode 100644 .opencode/skills/packmind-onboard/packmind-versions/0.23.0/completion-summary.md create mode 100644 .opencode/skills/packmind-onboard/packmind-versions/0.23.0/create-items.md create mode 100644 .opencode/skills/packmind-onboard/packmind-versions/0.23.0/create-package.md create mode 100644 .opencode/skills/packmind-onboard/packmind-versions/0.23.0/list-packages.md create mode 100644 .opencode/skills/packmind-onboard/packmind-versions/0.23.0/select-package.md create mode 100644 .opencode/skills/packmind-onboard/references/ci-local-workflow-parity.md create mode 100644 .opencode/skills/packmind-onboard/references/file-template-consistency.md create mode 100644 .opencode/skills/packmind-onboard/references/role-taxonomy-drift.md create mode 100644 .opencode/skills/packmind-onboard/references/test-data-construction.md create mode 100644 .opencode/skills/packmind-update-playbook/LICENSE.txt create mode 100644 .opencode/skills/packmind-update-playbook/SKILL.md create mode 100644 .opencode/skills/packmind-update-playbook/packmind-versions/0.21.0/apply-changes.md create mode 100644 .opencode/skills/packmind-update-playbook/packmind-versions/0.23.0/apply-changes.md create mode 100644 .opencode/skills/packmind-update-playbook/references/agent-skills-specification.md create mode 100644 .opencode/skills/packmind-update-playbook/references/create-command-procedure.md create mode 100644 .opencode/skills/packmind-update-playbook/references/create-skill-procedure.md create mode 100644 .opencode/skills/packmind-update-playbook/references/create-standard-procedure.md create mode 100644 .opencode/skills/packmind-update-playbook/steps/analyze-commands.md create mode 100644 .opencode/skills/packmind-update-playbook/steps/analyze-skills.md create mode 100644 .opencode/skills/packmind-update-playbook/steps/analyze-standards.md create mode 100644 .opencode/skills/working-with-playground-app/SKILL.md create mode 100644 .opencode/skills/working-with-playground-app/references/frontend-domain-structure.md create mode 100644 .opencode/skills/working-with-pm-design-kit/SKILL.md create mode 100644 .opencode/skills/working-with-pm-design-kit/references/component-catalog.md create mode 100644 packages/migrations/.opencode/commands/create-or-update-model-and-typeorm-schemas.md diff --git a/.opencode/skills/cli-e2e-test-authoring/SKILL.md b/.opencode/skills/cli-e2e-test-authoring/SKILL.md new file mode 100644 index 000000000..57840e50b --- /dev/null +++ b/.opencode/skills/cli-e2e-test-authoring/SKILL.md @@ -0,0 +1,192 @@ +--- +name: 'cli-e2e-test-authoring' +description: 'Guide for adding new end-to-end tests for the Packmind CLI. This skill should be used when creating new test specs in the `apps/cli-e2e-tests/` directory that exercise CLI commands against a real binary and API.' +--- + +# CLI E2E Test Authoring + +## Overview + +Add end-to-end tests that exercise the Packmind CLI binary (`dist/apps/cli/main.cjs`) in realistic conditions. Tests run the actual CLI as a child process and, when authentication is needed, interact with a running API via HTTP gateways. + +## Test File Location + +All spec files live in `apps/cli-e2e-tests/src/` and follow the naming convention `.spec.ts`. + +## Choosing a Test Wrapper + +Two wrappers are available depending on whether the command requires authentication. + +### Unauthenticated commands — `describeWithTempSpace` + +Provides an isolated temporary directory. No API required. + +```typescript +import { describeWithTempSpace, runCli } from './helpers'; + +describeWithTempSpace('my-command without auth', (getContext) => { + let result: Awaited>; + + beforeEach(async () => { + const { testDir } = await getContext(); + result = await runCli('my-command', { cwd: testDir }); + }); + + it('exits with code 1', () => { + expect(result.returnCode).toBe(1); + }); + + it('shows an error message', () => { + expect(result.stdout).toContain('No credentials found'); + }); +}); +``` + +### Authenticated commands — `describeWithUserSignedUp` + +Extends `describeWithTempSpace` by creating a real user account, signing in, and generating an API key. Requires a running API at `http://localhost:4200`. + +```typescript +import { describeWithUserSignedUp, runCli } from './helpers'; + +describeWithUserSignedUp('my-command with auth', (getContext) => { + let result: Awaited>; + + beforeEach(async () => { + const { apiKey, testDir } = await getContext(); + result = await runCli('my-command', { apiKey, cwd: testDir }); + }); + + it('succeeds', () => { + expect(result.returnCode).toBe(0); + }); + + it('displays expected output', () => { + expect(result.stdout).toContain('Expected text'); + }); +}); +``` + +The context object from `describeWithUserSignedUp` provides: + +| Field | Description | +|----------------|--------------------------------------------------| +| `testDir` | Isolated temporary directory | +| `apiKey` | Valid API key for the created user | +| `user` | User object (email, etc.) | +| `organization` | Organization the user belongs to | +| `spaceId` | Global space ID for the organization | +| `gateway` | Authenticated gateway to call the API directly | + +## Setting Up Test Preconditions + +### Git repository + +Commands that interact with git (e.g. `diff`, `install`) require a git repo. Call `setupGitRepo` in `beforeEach`: + +```typescript +import { setupGitRepo } from './helpers'; + +beforeEach(async () => { + const { testDir } = await getContext(); + await setupGitRepo(testDir); +}); +``` + +### Creating API resources + +Use `gateway` from the context to seed data before running the CLI: + +```typescript +beforeEach(async () => { + const { gateway, spaceId, testDir } = await getContext(); + await setupGitRepo(testDir); + await gateway.commands.create({ spaceId, /* ... */ }); + await gateway.packages.create({ spaceId, /* ... */ }); +}); +``` + +### File manipulation + +Use file helpers to create or modify files in the test directory: + +```typescript +import { readFile, updateFile, fileExists } from './helpers'; + +const content = readFile('path/to/file.md', testDir); +updateFile('path/to/file.md', 'new content', testDir); +const exists = fileExists('path/to/file.md', testDir); +``` + +## Assertion Patterns + +Split assertions into individual `it` blocks. Store the CLI result in a block-scoped `let` variable populated by `beforeEach`: + +```typescript +let result: Awaited>; + +beforeEach(async () => { + result = await runCli('some-command', { apiKey, cwd: testDir }); +}); + +it('succeeds', () => { + expect(result.returnCode).toBe(0); +}); + +it('displays the summary', () => { + expect(result.stdout).toContain('1 change submitted'); +}); +``` + +## Nesting Describes for Multi-Step Scenarios + +For commands that require chained operations (e.g. install then modify then diff), nest `describe` blocks. Each level adds its own `beforeEach` that builds on the parent context: + +```typescript +describeWithUserSignedUp('diff command', (getContext) => { + beforeEach(async () => { + // setup: git repo + seed data + install + }); + + describe('when a change is submitted', () => { + beforeEach(async () => { + // modify file + run diff --submit + }); + + it('succeeds', () => { /* ... */ }); + + describe('when running diff again', () => { + beforeEach(async () => { + // run diff without --submit + }); + + it('excludes the already-submitted change', () => { /* ... */ }); + }); + }); +}); +``` + +## Feature Flags + +Before writing the test, ask the user: **"Is the feature under test gated by a feature flag?"** + +If yes, the test must create a user whose email is at `@packmind.com` so the flag is enabled. This is controlled by the `underFeatureFlag` fixture option. Add `.use({ underFeatureFlag: true })` immediately after the test wrapper import, before any `describe` or `it` blocks: + +```typescript +// When using testWithApi: +testWithApi.use({ underFeatureFlag: true }); + +// When using testWithUserSignedUp: +testWithUserSignedUp.use({ underFeatureFlag: true }); +``` + +Without this option, the fixture creates a user at `@example.com`, which does not have feature flags enabled, and the feature under test would not be accessible. + +## Adding a New Gateway + +When the CLI command under test requires seeding a new type of API resource: + +1. Add the interface method to `helpers/IPackmindGateway.ts`. All exposed methods must be typed with `Gateway` or `PublicGateway` (imported from `@packmind/types`) +2. Create `helpers/gateways/NewResourceGateway.ts` implementing the interface +3. Add a lazy getter to `helpers/gateways/PackmindGateway.ts` (reset on `initializeWithApiKey`) +4. Re-export from `helpers/index.ts` \ No newline at end of file diff --git a/.opencode/skills/packmind-onboard/LICENSE.txt b/.opencode/skills/packmind-onboard/LICENSE.txt new file mode 100644 index 000000000..f433b1a53 --- /dev/null +++ b/.opencode/skills/packmind-onboard/LICENSE.txt @@ -0,0 +1,177 @@ + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS diff --git a/.opencode/skills/packmind-onboard/README.md b/.opencode/skills/packmind-onboard/README.md new file mode 100644 index 000000000..a67977da6 --- /dev/null +++ b/.opencode/skills/packmind-onboard/README.md @@ -0,0 +1,46 @@ +# Packmind Onboarding Skill + +Read-only codebase analysis skill that identifies non-linter architectural patterns and generates draft Packmind Standards and Commands. + +## What It Does + +1. **Detects existing configuration** - Shows what's already configured (standards, commands, agent docs) +2. **Detects your stack** - Language, monorepo structure, architecture markers +3. **Analyzes for non-linter patterns** - 4 architectural analyses across code organization, workflows, and testing +4. **Generates draft artifacts** - Max 5 Standards and 5 Commands per run +5. **Applies on your choice** - Nothing written without explicit confirmation + +**Works with any language** - JavaScript, TypeScript, Python, Go, Ruby, Java, and more. + +## Available Analyses + +| Category | Analyses | +|----------|----------| +| **Infrastructure** | CI/Local Workflow Parity | +| **Code Organization** | File Template Consistency, Role Taxonomy Drift | +| **Testing** | Test Data Construction | + +## Usage + +Ask your AI agent to onboard: +- "Onboard this project to Packmind" +- "Analyze this codebase for standards" +- "Generate coding standards for this project" + +## What You'll Discover + +- **Test data patterns**: "23 factories with 1166 usages across test files" +- **File boilerplate**: "All UseCases extend AbstractMemberUseCase with same structure" +- **Workflow gaps**: "CI runs security scan, no local equivalent" +- **Role drift**: "3 role definitions with inconsistent naming across modules" + +## What It Skips (Linter-Enforceable) + +- ESLint disable counts +- TypeScript strict violations +- Formatting issues +- Import ordering + +## License + +Apache 2.0 - See LICENSE.txt for details. diff --git a/.opencode/skills/packmind-onboard/SKILL.md b/.opencode/skills/packmind-onboard/SKILL.md new file mode 100644 index 000000000..97aba3c8e --- /dev/null +++ b/.opencode/skills/packmind-onboard/SKILL.md @@ -0,0 +1,328 @@ +--- +name: 'packmind-onboard' +description: 'Complete automated onboarding: analyzes codebase, creates package, and generates standards & commands via CLI. Automatic package creation when none exist, user selection when packages are available.' +license: 'Complete terms in LICENSE.txt' +--- + +# packmind-onboard +Run "packmind-cli --version" to get the current cli installation. + +Find the highest version at or below the cli version in this list: +- 0.16.0 +- 0.23.0 +Remember this value as $PACKMIND_CLI_VERSION for the rest of the skill. + + +Action skill. Provides **complete automated onboarding** for Packmind: +1. Creates or selects a package +2. Analyzes codebase for patterns +3. Generates draft Standards and Commands +4. Creates items via CLI + +Automatic package creation when none exist, user selection when packages are available. + +## Guarantees + +- **Read-only analysis.** Analysis phase does not modify any project files. +- **Drafts before creation.** All items are written as drafts first, allowing review before creation. +- **Preserve existing.** Never overwrite existing artifacts. If a slug already exists, create `-2`, `-3`, etc. +- **Evidence required.** Every reported insight must include file-path evidence (and line ranges when feasible). +- **Focused output.** Max **5 Standards** and **5 Commands** generated per run. +- **Graceful failure.** Partial failures don't lose successful work; failed drafts are preserved. +- **User control.** When packages exist, users confirm package selection before creation. + +## Definitions + +- **Pattern (non-linter):** a convention a linter cannot reliably enforce (module boundaries, cross-domain communication, workflow parity, error semantics, etc). +- **Evidence:** `path[:line-line]` entries; omit line ranges only when the file isn't text-searchable. + +--- + +## Step 0 — Introduction + +Print exactly: + +``` +I'll start the Packmind onboarding process. I'll create your first standards and commands and send them to your Packmind organization. This usually takes ~3 minutes. +``` + + +--- + +## Step 1 — Get Repository Name + +Get the repository name for package naming: + +```bash +basename "$(git rev-parse --show-toplevel)" +``` + +Remember this as the repository name for package creation in Step 2. + +Also run `packmind-cli whoami` and extract the `Host:` value from the output. Remember this URL for the completion summary. + + +--- + +## Step 2 — Package Handling + +Handle package creation or selection. + +### Check existing packages + +List available packages by following [`packmind-versions/$PACKMIND_CLI_VERSION/list-packages.md`](packmind-versions/$PACKMIND_CLI_VERSION/list-packages.md). + +Parse the output to get package names and slugs. + +### No packages exist + +Auto-create a package using the repository name. Follow [`packmind-versions/$PACKMIND_CLI_VERSION/create-package.md`](packmind-versions/$PACKMIND_CLI_VERSION/create-package.md) using `${REPO_NAME}-standards` as the package name. + +The create-package step will determine the space. Capture the chosen space slug as `$SPACE_SLUG` and the new package slug as `$PACKAGE_SLUG`. + +Print: +``` +No existing packages found — created a new one: ${REPO_NAME}-standards +``` + +### One package exists + +Ask via AskUserQuestion: +- "Add to `{package-name}`?" +- "Create new package instead" + +### Multiple packages exist + +Ask via AskUserQuestion: +- List each existing package as an option +- Include "Create new package" option + +### If "Create new package" is selected + +- Ask for package name (suggest `${REPO_NAME}-standards` as default) +- Follow [`packmind-versions/$PACKMIND_CLI_VERSION/create-package.md`](packmind-versions/$PACKMIND_CLI_VERSION/create-package.md) using the chosen name. +- The create-package step will determine the space. Capture the chosen space slug as `$SPACE_SLUG` and the new package slug as `$PACKAGE_SLUG`. + +### If an existing package is selected + +Follow [`packmind-versions/$PACKMIND_CLI_VERSION/select-package.md`](packmind-versions/$PACKMIND_CLI_VERSION/select-package.md). + +### After this step + +Remember `$PACKAGE_SLUG` (the slug of the selected/created package) and `$SPACE_SLUG` for later reference — they will be used together in Step 9 to ensure items are added to the correct package in the correct space (as `@$SPACE_SLUG/$PACKAGE_SLUG`). + + +--- + +## Step 3 — Announce + +Print exactly: + +``` +packmind-onboard: analyzing codebase (read-only) +Target package: [package-name] +``` + + +--- + +## Step 4 — Detect Existing Packmind and Agent Configuration + +Before analyzing, detect and preserve any existing Packmind/agent configuration. + +### Glob (broad, future-proof) +Glob for markdown in these roots (recursive): +- `.packmind/**/*.md` +- `.claude/**/*.md` +- `.agents/**/*.md` +- `**/skills/**/*.md` +- `**/rules/**/*.md` + +### Classify +Classify found files into counts: +- **standards**: `.packmind/standards/**/*.md` +- **commands**: `.packmind/commands/**/*.md` +- **other_docs**: any markdown under `.claude/`, `.agents/`, or any `skills/` or `rules/` directory outside `.packmind` + +If any exist, print exactly: + +``` +Existing Packmind/agent docs detected: + + Standards: [N] + + Commands: [M] + + Other docs: [P] +``` + +No overwrites. New files (if you Export) will be added next to the existing ones. + + +--- + +## Step 5 — Detect Project Stack (Minimal, Evidence-Based) + +### Language markers (check presence) +- JS/TS: `package.json`, `pnpm-lock.yaml`, `yarn.lock`, `tsconfig.json` +- Python: `pyproject.toml`, `requirements.txt`, `setup.py` +- Go: `go.mod` +- Rust: `Cargo.toml` +- Ruby: `Gemfile` +- JVM: `pom.xml`, `build.gradle`, `build.gradle.kts` +- .NET: `*.csproj`, `*.sln` +- PHP: `composer.json` + +### Architecture markers (check directories) +- Hexagonal/DDD: `src/application/`, `src/domain/`, `src/infra/` +- Layered/MVC: `src/controllers/`, `src/services/` +- Monorepo: `packages/`, `apps/` + +Print exactly: + +``` +Stack detected (heuristic): + + Languages: [..] + + Repo shape: [monorepo|single] + + Architecture markers: [..|none] +``` + + +--- + +## Step 6 — Run Analyses + +Read each reference file for detailed search patterns, thresholds, and insight templates. + +| Analysis | Reference File | Output focus | +|----------|----------------|--------------| +| File Template Consistency | `references/file-template-consistency.md` | Commands | +| CI/Local Workflow Parity | `references/ci-local-workflow-parity.md` | Commands | +| Role Taxonomy Drift | `references/role-taxonomy-drift.md` | Standards | +| Test Data Construction | `references/test-data-construction.md` | Standards | + +### Output schema (internal; do not print as-is to user) +For every finding, keep an internal record: + +``` +INSIGHT: +title: ... +why_it_matters: ... +confidence: [high|medium|low] +evidence: +- path[:line-line] +where_it_doesnt_apply: +- path[:line-line] +``` + + +--- + +## Step 7 — Generate All Drafts + +Generate all draft files in one batch, using the format defined for your CLI version. + +Read the **Draft Format** section in [`packmind-versions/$PACKMIND_CLI_VERSION/create-items.md`](packmind-versions/$PACKMIND_CLI_VERSION/create-items.md) and create draft files accordingly. + +### Generation Rules (all versions) + +- Generate drafts **only from discovered insights** (no invention) +- Use evidence from analysis to populate rules/steps +- Cap output: max **5 Standards** + **5 Commands** +- Never overwrite existing files; append `-2`, `-3`, etc. if slug exists + + +--- + +## Step 8 — Present Summary & Confirm + +Present the generated draft files and ask for confirmation: + +``` +============================================================ + ANALYSIS COMPLETE +============================================================ + +Target package: [package-name] +Stack detected: [languages], [monorepo?], [architecture markers] +Analyses run: [N] checks + +DRAFTS CREATED: + +Standards ([N]): + 1. [Name] → .packmind/standards/_drafts/[slug].draft.md + 2. ... + +Commands ([M]): + 1. [Name] → .packmind/commands/_drafts/[slug].draft.md + 2. ... + +Drafts are saved in .packmind/*/_drafts/ — you can review or edit them before creating. +============================================================ +``` + +Then ask via AskUserQuestion with three options: + +- **Create all now** — Proceed with creating all standards and commands +- **Let me review drafts first** — Pause to allow editing, re-run skill when ready +- **Cancel** — Exit without creating anything + + +--- + +## Step 9 — Create Items + +Follow [`packmind-versions/$PACKMIND_CLI_VERSION/create-items.md`](packmind-versions/$PACKMIND_CLI_VERSION/create-items.md). + + +--- + +## Step 10 — Completion Summary + +Follow [`packmind-versions/$PACKMIND_CLI_VERSION/completion-summary.md`](packmind-versions/$PACKMIND_CLI_VERSION/completion-summary.md). + + +--- + +## Edge Cases + +### Package creation fails + +If `packmind-cli packages create` fails: + +``` +❌ Failed to create package: [error message] + +Please check: + - You are logged in: `packmind-cli login` + - Your network connection is working + - The package name is valid + +Cannot proceed with onboarding until package is created. +``` + +Exit the skill. Do not proceed to analysis. + +### Not logged in + +If CLI commands fail with authentication errors: + +``` +❌ Not logged in to Packmind + +Please run: + packmind-cli login + +Then re-run this skill. +``` + +### No packages available + +If the package listing command returns no packages: + +Auto-create a package using the repository name. + + diff --git a/.opencode/skills/packmind-onboard/packmind-versions/0.16.0/completion-summary.md b/.opencode/skills/packmind-onboard/packmind-versions/0.16.0/completion-summary.md new file mode 100644 index 000000000..c41fd4869 --- /dev/null +++ b/.opencode/skills/packmind-onboard/packmind-versions/0.16.0/completion-summary.md @@ -0,0 +1,64 @@ +## Completion Summary (CLI 0.16.0) + +### All items created successfully + +``` +============================================================ + ✅ ONBOARDING COMPLETE +============================================================ + +Package: [package-name] +Created: [N] standards, [M] commands + +Your standards and commands have been created and deployed locally. + +Next steps: + - Reload your AI coding assistant to start using them + - Visit [host from packmind-cli whoami] to manage your standards and commands + - Run `packmind-cli install [package-slug]` in other repos to distribute them +============================================================ +``` + +Clean up successful draft files after creation. + +### Partial success (some items failed) + +``` +============================================================ + ⚠️ ONBOARDING COMPLETED WITH ERRORS +============================================================ + +Package: [package-name] +Created: [N] standards, [M] commands +Failed: [X] items + +Failed items: + • [item-name]: [error message] + +Failed drafts remain in .packmind/*/_drafts/ for review. +You can fix and re-run, or create manually with: + packmind-cli standards create .packmind/standards/_drafts/.json + packmind-cli packages add --to --standard + packmind-cli commands create .packmind/commands/_drafts/.json + packmind-cli packages add --to --command +============================================================ +``` + +Keep failed draft files for user to fix and retry. + +### No patterns discovered + +If analysis found no patterns: + +``` +============================================================ + ℹ️ NO PATTERNS DISCOVERED +============================================================ + +The analysis didn't find enough recurring patterns to generate standards or commands. + +This can happen with smaller codebases or projects with very diverse coding styles. +You can try again later as the codebase grows, or create standards manually with: + packmind-cli standards create +============================================================ +``` diff --git a/.opencode/skills/packmind-onboard/packmind-versions/0.16.0/create-items.md b/.opencode/skills/packmind-onboard/packmind-versions/0.16.0/create-items.md new file mode 100644 index 000000000..e2e02e0fc --- /dev/null +++ b/.opencode/skills/packmind-onboard/packmind-versions/0.16.0/create-items.md @@ -0,0 +1,240 @@ +## Draft Format (CLI 0.16.0) + +### Standard Draft Format + +For each Standard insight, create a Markdown file at `.packmind/standards/_drafts/.draft.md`: + +```markdown +# Standard Name + +What the standard covers and why. + +## Scope + +Where this standard applies (e.g., 'TypeScript files', 'React components'). + +## Rules + +### Rule starting with action verb + +Another rule can follow... + +## Examples + +### Good + +```typescript +// Valid code example +``` + +### Bad + +```typescript +// Invalid code example +``` +``` + +### Command Draft Format + +For each Command insight, create a Markdown file at `.packmind/commands/_drafts/.draft.md`: + +```markdown +# Command Name + +What the command does, why it's useful, and when it's relevant. + +## When to Use + +- Scenario when this command applies +- Another scenario... + +## Checkpoints + +- Question to validate before proceeding? + +## Steps + +### 1. Step Name + +What this step does and how to implement it. + +```typescript +// Optional code example +``` + +### 2. Another Step + +Description of next step... +``` + +--- + +## Create Items (CLI 0.16.0) + +### If user selected "Create all now" + +**IMPORTANT:** The CLI only accepts JSON playbook files, not markdown. Before calling the CLI, convert each `.draft.md` file to a `.json` file. + +#### Standard JSON Schema + +Convert the markdown draft to this JSON format: + +```json +{ + "name": "Standard name (from # heading)", + "description": "What the standard covers (from intro paragraph)", + "scope": "Where it applies (from ## Scope section)", + "rules": [ + { + "content": "Rule starting with action verb (from ### Rule headings under ## Rules)", + "examples": { + "positive": "Valid code example (from ### Good section)", + "negative": "Invalid code example (from ### Bad section)", + "language": "TYPESCRIPT" + } + } + ] +} +``` + +#### Command JSON Schema + +Convert the markdown draft to this JSON format: + +```json +{ + "name": "Command name (from # heading)", + "summary": "What it does and when (from intro paragraph)", + "whenToUse": ["Scenario 1", "Scenario 2 (from ## When to Use bullets)"], + "contextValidationCheckpoints": ["Question 1? (from ## Checkpoints bullets)"], + "steps": [ + { + "name": "Step name (from ### N. Step Name)", + "description": "Step description (from step content)", + "codeSnippet": "Optional code fence content" + } + ] +} +``` + +#### Conversion and Creation Process + +**For each standard draft:** + +1. Read the `.draft.md` file +2. Convert to JSON matching the schema above +3. Write the JSON to `.packmind/standards/_drafts/.json` +4. Run CLI command to create: +```bash +packmind-cli standards create .packmind/standards/_drafts/.json +``` +5. If creation succeeded, add to package: +```bash +packmind-cli packages add --to --standard +``` +6. Track result (success/failure) + +**For each command draft:** + +1. Read the `.draft.md` file +2. Convert to JSON matching the schema above +3. Write the JSON to `.packmind/commands/_drafts/.json` +4. Run CLI command to create: +```bash +packmind-cli commands create .packmind/commands/_drafts/.json +``` +5. If creation succeeded, add to package: +```bash +packmind-cli packages add --to --command +``` +6. Track result (success/failure) + +**Show progress:** +``` +Sending standards and commands to your Packmind organization... +✓ error-handling-pattern +✓ naming-conventions +✗ test-factory-patterns (error: duplicate name exists) +✓ run-full-test-suite + +Done: 3 created, 1 failed +``` + +### If user selected "Let me review drafts first" + +Print: +``` +Draft files ready for review at: + - .packmind/standards/_drafts/ + - .packmind/commands/_drafts/ + +Edit them as needed, then re-run this skill to continue. +``` + +Exit the skill. + +### If user selected "Cancel" + +Print: +``` +Onboarding cancelled. +Draft files remain at .packmind/*/_drafts/ if you want to review them later. +``` + +Exit the skill. + +--- + +### 9.1 Deploy Locally (after successful creation) + +Since the onboard skill is present, the user has configured an AI agent. Deploy the created artifacts locally using the package selected/created in Step 2: + +```bash +packmind-cli install +``` + +This deploys to agent-specific folders: + +| Agent | Standards | Commands | +|-------|-----------|----------| +| Claude | `.claude/rules/packmind/standard-[slug].md` | `.claude/commands/packmind/[slug].md` | +| Cursor | `.cursor/rules/packmind/standard-[slug].mdc` | `.cursor/commands/packmind/[slug].mdc` | +| Copilot | `.github/instructions/packmind-standard-[slug].instructions.md` | `.github/prompts/packmind-[slug].prompt.md` | + +### 9.2 Cleanup and Summary + +Delete the draft files, then print final summary: + +``` +============================================================ + PUBLISHED & DEPLOYED +============================================================ + +Standards and commands have been sent to your Packmind organization +and deployed to your AI coding assistant's configuration files. + +Standards: [N] + - [Name] (slug: [slug]) + → .packmind/standards/[slug].md + → [agent-specific path] + +Commands: [M] + - [Name] (slug: [slug]) + → .packmind/commands/[slug].md + → [agent-specific path] + +Draft files cleaned up. +============================================================ +``` + +**If user declines (N):** + +Print: + +``` +Draft files ready for review at: + - .packmind/standards/_drafts/ + - .packmind/commands/_drafts/ + +Edit them as needed, then re-run this skill to create them. +``` diff --git a/.opencode/skills/packmind-onboard/packmind-versions/0.16.0/create-package.md b/.opencode/skills/packmind-onboard/packmind-versions/0.16.0/create-package.md new file mode 100644 index 000000000..259e57a27 --- /dev/null +++ b/.opencode/skills/packmind-onboard/packmind-versions/0.16.0/create-package.md @@ -0,0 +1,5 @@ +## Create Package (CLI 0.16.0) + +```bash +packmind-cli packages create "" +``` diff --git a/.opencode/skills/packmind-onboard/packmind-versions/0.16.0/list-packages.md b/.opencode/skills/packmind-onboard/packmind-versions/0.16.0/list-packages.md new file mode 100644 index 000000000..1384951ba --- /dev/null +++ b/.opencode/skills/packmind-onboard/packmind-versions/0.16.0/list-packages.md @@ -0,0 +1,5 @@ +## List Packages (CLI 0.16.0) + +```bash +packmind-cli install --list +``` diff --git a/.opencode/skills/packmind-onboard/packmind-versions/0.16.0/select-package.md b/.opencode/skills/packmind-onboard/packmind-versions/0.16.0/select-package.md new file mode 100644 index 000000000..9a3cfa0f4 --- /dev/null +++ b/.opencode/skills/packmind-onboard/packmind-versions/0.16.0/select-package.md @@ -0,0 +1,3 @@ +## Select Existing Package (CLI 0.16.0) + +Spaces are not supported in this CLI version. Use the selected package slug directly as `$PACKAGE_SLUG`. diff --git a/.opencode/skills/packmind-onboard/packmind-versions/0.23.0/completion-summary.md b/.opencode/skills/packmind-onboard/packmind-versions/0.23.0/completion-summary.md new file mode 100644 index 000000000..34ba8b828 --- /dev/null +++ b/.opencode/skills/packmind-onboard/packmind-versions/0.23.0/completion-summary.md @@ -0,0 +1,69 @@ +## Completion Summary (CLI 0.23.0) + +### All items created successfully + +``` +============================================================ + ✅ ONBOARDING COMPLETE +============================================================ + +Package: [package-name] +Created: [N] standards, [M] commands + +Your standards and commands have been created and deployed locally. + +Next steps: + - Reload your AI coding assistant to start using them + - Visit [host from packmind-cli whoami] to manage your standards and commands + - Run `packmind-cli install @$SPACE_SLUG/[package-slug]` in other repos to distribute them +============================================================ +``` + +Clean up successful draft files after creation. + +### Partial success (some items failed) + +``` +============================================================ + ⚠️ ONBOARDING COMPLETED WITH ERRORS +============================================================ + +Package: [package-name] +Created: [N] standards, [M] commands +Failed: [X] items + +Failed items: + • [item-name]: [error message] + +Failed drafts remain in .packmind/*/_drafts/ for review. +You can fix and re-run, or create manually with: + cp .packmind/standards/_drafts/.draft.md .packmind/standards/_drafts/.md + packmind-cli playbook add --space .packmind/standards/_drafts/.md + cp .packmind/commands/_drafts/.draft.md .packmind/commands/_drafts/.md + packmind-cli playbook add --space .packmind/commands/_drafts/.md + packmind-cli playbook submit --no-review + packmind-cli packages add --to @/ --standard + packmind-cli packages add --to @/ --command +============================================================ +``` + +Keep failed draft files for user to fix and retry. + +### No patterns discovered + +If analysis found no patterns: + +``` +============================================================ + ℹ️ NO PATTERNS DISCOVERED +============================================================ + +The analysis didn't find enough recurring patterns to generate standards or commands. + +This can happen with smaller codebases or projects with very diverse coding styles. +You can try again later as the codebase grows, or create standards manually with: + cp .packmind/standards/_drafts/.draft.md .packmind/standards/_drafts/.md + packmind-cli playbook add --space .packmind/standards/_drafts/.md + packmind-cli playbook submit --no-review +============================================================ +``` diff --git a/.opencode/skills/packmind-onboard/packmind-versions/0.23.0/create-items.md b/.opencode/skills/packmind-onboard/packmind-versions/0.23.0/create-items.md new file mode 100644 index 000000000..4fba56c7b --- /dev/null +++ b/.opencode/skills/packmind-onboard/packmind-versions/0.23.0/create-items.md @@ -0,0 +1,185 @@ +## Draft Format (CLI 0.23.0) + +### Standard Draft Format + +For each Standard insight, create a Markdown file at `.packmind/standards/_drafts/.draft.md`: + +```markdown +# Standard Name + +What the standard covers and why. + +## Scope + +Where this standard applies (e.g., 'TypeScript files', 'React components'). + +## Rules + +- Rule starting with an action verb +- Another rule... +``` + +No code examples required for this version. + +### Command Draft Format + +For each Command insight, create a Markdown file at `.packmind/commands/_drafts/.draft.md`: + +```markdown +# Command Name + +What the command does, why it's useful, and when it's relevant. + +## When to Use + +- Scenario when this command applies +- Another scenario... + +## Checkpoints + +- Question to validate before proceeding? + +## Steps + +### 1. Step Name + +What this step does and how to implement it. + +### 2. Another Step + +Description of next step... +``` + +--- + +## Create Items (CLI 0.23.0) + +### If user selected "Create all now" + +The CLI accepts markdown files directly — no JSON conversion needed. + +**IMPORTANT:** The CLI derives the artifact name and slug from the filename. Strip the `.draft` suffix before adding by copying to a temporary file without `.draft`: + +**For each standard draft:** + +```bash +cp .packmind/standards/_drafts/.draft.md .packmind/standards/_drafts/.md +packmind-cli playbook add --space $SPACE_SLUG .packmind/standards/_drafts/.md +rm .packmind/standards/_drafts/.md +``` + +**For each command draft:** + +```bash +cp .packmind/commands/_drafts/.draft.md .packmind/commands/_drafts/.md +packmind-cli playbook add --space $SPACE_SLUG .packmind/commands/_drafts/.md +rm .packmind/commands/_drafts/.md +``` + +**After adding all items, submit:** + +```bash +packmind-cli playbook submit --no-review +``` + +**Show progress:** +``` +Sending standards and commands to your Packmind organization... ++ error-handling-pattern ++ naming-conventions ++ run-full-test-suite + +Submitting... +Done: 3 submitted +``` + +**After a successful submit, add each item to the package:** + +For each standard: +```bash +packmind-cli packages add --to @$SPACE_SLUG/$PACKAGE_SLUG --standard +``` + +For each command: +```bash +packmind-cli packages add --to @$SPACE_SLUG/$PACKAGE_SLUG --command +``` + +### If user selected "Let me review drafts first" + +Print: +``` +Draft files ready for review at: + - .packmind/standards/_drafts/ + - .packmind/commands/_drafts/ + +Edit them as needed, then re-run this skill to continue. +``` + +Exit the skill. + +### If user selected "Cancel" + +Print: +``` +Onboarding cancelled. +Draft files remain at .packmind/*/_drafts/ if you want to review them later. +``` + +Exit the skill. + +--- + +### 9.1 Deploy Locally (after successful creation) + +Since the onboard skill is present, the user has configured an AI agent. Deploy the created artifacts locally using the package selected/created in Step 2: + +```bash +packmind-cli install @$SPACE_SLUG/$PACKAGE_SLUG +``` + +This deploys to agent-specific folders: + +| Agent | Standards | Commands | +|-------|-----------|----------| +| Claude | `.claude/rules/packmind/standard-[slug].md` | `.claude/commands/packmind/[slug].md` | +| Cursor | `.cursor/rules/packmind/standard-[slug].mdc` | `.cursor/commands/packmind/[slug].mdc` | +| Copilot | `.github/instructions/packmind-standard-[slug].instructions.md` | `.github/prompts/packmind-[slug].prompt.md` | + +### 9.2 Cleanup and Summary + +Delete the draft files, then print final summary: + +``` +============================================================ + PUBLISHED & DEPLOYED +============================================================ + +Standards and commands have been sent to your Packmind organization +and deployed to your AI coding assistant's configuration files. + +Standards: [N] + - [Name] (slug: [slug]) + → .packmind/standards/[slug].md + → [agent-specific path] + +Commands: [M] + - [Name] (slug: [slug]) + → .packmind/commands/[slug].md + → [agent-specific path] + +Draft files cleaned up. +============================================================ +``` + +**If user declines (N):** + +Print: + +``` +Draft files ready for review at: + - .packmind/standards/_drafts/ + - .packmind/commands/_drafts/ + +Edit them as needed, then re-run this skill to create them. +``` diff --git a/.opencode/skills/packmind-onboard/packmind-versions/0.23.0/create-package.md b/.opencode/skills/packmind-onboard/packmind-versions/0.23.0/create-package.md new file mode 100644 index 000000000..5eea4ceb0 --- /dev/null +++ b/.opencode/skills/packmind-onboard/packmind-versions/0.23.0/create-package.md @@ -0,0 +1,18 @@ +## Create Package (CLI 0.23.0) + +### Select a space + +List available spaces: + +```bash +packmind-cli spaces list +``` + +- **Multiple spaces**: ask the user which space to use via AskUserQuestion, then remember the chosen slug as ``. +- **Single space**: use it directly — no user prompt needed. + +### Create the package + +```bash +packmind-cli packages create "" --space +``` diff --git a/.opencode/skills/packmind-onboard/packmind-versions/0.23.0/list-packages.md b/.opencode/skills/packmind-onboard/packmind-versions/0.23.0/list-packages.md new file mode 100644 index 000000000..b9796aaba --- /dev/null +++ b/.opencode/skills/packmind-onboard/packmind-versions/0.23.0/list-packages.md @@ -0,0 +1,5 @@ +## List Packages (CLI 0.23.0) + +```bash +packmind-cli packages list +``` diff --git a/.opencode/skills/packmind-onboard/packmind-versions/0.23.0/select-package.md b/.opencode/skills/packmind-onboard/packmind-versions/0.23.0/select-package.md new file mode 100644 index 000000000..aec8f309d --- /dev/null +++ b/.opencode/skills/packmind-onboard/packmind-versions/0.23.0/select-package.md @@ -0,0 +1,10 @@ +## Select Existing Package (CLI 0.23.0) + +Determine the space of the selected package: + +```bash +packmind-cli spaces list +``` + +- **Single space**: use it directly — set `$SPACE_SLUG` to its slug, no user prompt needed. +- **Multiple spaces**: ask the user via AskUserQuestion which space the selected package belongs to, then set `$SPACE_SLUG` to the chosen slug. diff --git a/.opencode/skills/packmind-onboard/references/ci-local-workflow-parity.md b/.opencode/skills/packmind-onboard/references/ci-local-workflow-parity.md new file mode 100644 index 000000000..188e6572d --- /dev/null +++ b/.opencode/skills/packmind-onboard/references/ci-local-workflow-parity.md @@ -0,0 +1,221 @@ +# CI / Local Workflow Parity + +Identify CI steps that cannot be run locally; propose "Pre-PR Quality Check" command. + +## Search Patterns + +### CI Configuration Files + +``` +# GitHub Actions +.github/workflows/*.yml +.github/workflows/*.yaml + +# GitLab CI +.gitlab-ci.yml +.gitlab-ci.yaml + +# CircleCI +.circleci/config.yml + +# Azure Pipelines +azure-pipelines.yml +azure-pipelines.yaml + +# Jenkins +Jenkinsfile + +# Travis CI +.travis.yml + +# Bitbucket Pipelines +bitbucket-pipelines.yml + +# Generic +ci.yml +ci.yaml +pipeline.yml +``` + +### Local Script Definitions + +``` +# Node.js +package.json (scripts section) +pnpm-workspace.yaml + +# Make +Makefile +makefile +GNUmakefile + +# Task runners +Taskfile.yml +Taskfile.yaml +Justfile +justfile + +# Python +pyproject.toml ([tool.poetry.scripts], [project.scripts]) +setup.py (entry_points) +tox.ini +noxfile.py + +# Ruby +Rakefile +bin/* + +# Go +Makefile +mage.go + +# Nx / Monorepo +nx.json +project.json +``` + +### Pre-commit Hooks + +``` +.husky/ +.husky/pre-commit +.husky/pre-push +.pre-commit-config.yaml +lefthook.yml +lint-staged.config.js +``` + +### Common CI Steps to Check + +``` +# Testing +npm test +npm run test +yarn test +pnpm test +pytest +go test +cargo test +dotnet test +mvn test +gradle test + +# Linting +npm run lint +eslint +prettier +pylint +flake8 +golangci-lint +cargo clippy +rubocop + +# Type checking +tsc --noEmit +mypy +pyright + +# Building +npm run build +yarn build +go build +cargo build +dotnet build +mvn package + +# Security scanning +npm audit +snyk +trivy +safety check +cargo audit + +# Code coverage +coverage +nyc +jest --coverage +codecov + +# E2E tests +cypress +playwright +selenium + +# Docker operations +docker build +docker-compose +``` + +## Analysis Method + +1. Parse local script definitions (package.json scripts, Makefile targets, etc.) +2. Parse CI config files (extract `run:` commands) +3. For each CI command: + - Check if equivalent exists locally + - Flag if no local entrypoint +4. Identify Docker-dependent steps that assume CI environment + +## Reporting Threshold + +Report only if: +- ≥1 meaningful CI step lacks local entrypoint + +## Insight Template + +``` +INSIGHT: + id: CILOCAL-[n] + title: "WORKFLOW GAP: [N] CI steps lack local entrypoints" + summary: "CI runs [steps] that cannot be easily reproduced locally." + confidence: [high|medium|low] + evidence: + ci_only_steps: + - step: "[command]" + ci_file: path[:line] + local_equivalent: "none" | "[partial match]" + local_scripts: + - path — defines [N] scripts +``` + +## Command Template + +When workflow gaps exist, propose: + +```yaml +name: "pre-pr-quality-check" +summary: "Run all CI checks locally before creating a PR" +whenToUse: + - "Before creating a pull request" + - "After completing a feature to verify CI will pass" + - "When CI fails and you want to debug locally" +contextValidationCheckpoints: + - "Are all dependencies installed?" + - "Is the development environment configured?" +steps: + - name: "Run linting" + description: "Execute lint checks" + codeSnippet: | + [extracted from CI or local scripts] + - name: "Run type checking" + description: "Verify type correctness" + codeSnippet: | + [extracted from CI or local scripts] + - name: "Run tests" + description: "Execute test suite" + codeSnippet: | + [extracted from CI or local scripts] + - name: "Run build" + description: "Verify build succeeds" + codeSnippet: | + [extracted from CI or local scripts] +``` + +## Gap Categories + +| Category | CI Example | Local Gap | +|----------|------------|-----------| +| **Security** | `npm audit --audit-level=high` | Often not in package.json scripts | +| **Coverage** | `--coverage --coverageThreshold` | Thresholds may differ locally | +| **E2E** | `cypress run` | May require specific env setup | +| **Docker** | `docker build` | Requires Docker daemon | +| **Secrets** | env var checks | Secrets not available locally | diff --git a/.opencode/skills/packmind-onboard/references/file-template-consistency.md b/.opencode/skills/packmind-onboard/references/file-template-consistency.md new file mode 100644 index 000000000..5ef3cefa6 --- /dev/null +++ b/.opencode/skills/packmind-onboard/references/file-template-consistency.md @@ -0,0 +1,180 @@ +# File Template Consistency + +Detect repeatable file templates and propose "Create X" commands for scaffolding. + +## Search Patterns + +### Common File Roles + +``` +# Controllers / Handlers +*Controller.ts +*Controller.js +*Handler.ts +*Handler.js +*controller.py +*_controller.rb +*Controller.java + +# Services +*Service.ts +*Service.js +*service.py +*_service.rb +*Service.java + +# Use Cases +*UseCase.ts +*UseCase.js +*Interactor.ts +*usecase.go +*_use_case.rb + +# Repositories +*Repository.ts +*Repository.js +*Repo.ts +*repository.py +*_repository.rb +*Repository.java + +# DTOs / Value Objects +*DTO.ts +*Dto.ts +*Request.ts +*Response.ts +*VO.ts +*ValueObject.ts + +# Mappers / Adapters +*Mapper.ts +*Adapter.ts +*Converter.ts + +# Components (Frontend) +*.component.tsx +*.component.ts +*Component.tsx +*Component.vue + +# Hooks (React) +use*.ts +use*.tsx +``` + +### Structure Markers to Extract + +``` +# Base classes / interfaces +extends Abstract +extends Base +implements I +implements Interface + +# Decorators / annotations +@Controller +@Injectable +@Service +@Repository +@Component +@Module +@Entity +@UseCase + +# Constructor injection +constructor( + private readonly + private final + @Inject + @Autowired + +# Standard methods +async execute( +async handle( +async run( +async invoke( +def execute( +def handle( +def call( + +# Required exports +export class +export default +export const +module.exports +``` + +### Directory Conventions + +``` +# Check for consistent placement +src/controllers/ +src/services/ +src/useCases/ +src/use-cases/ +src/application/ +src/domain/ +src/infra/ +src/infrastructure/ +src/repositories/ +src/handlers/ +``` + +## Analysis Method + +1. Identify file categories with ≥5 instances (by naming + directory) +2. Read 3-5 representative files per category +3. Extract shared structure: + - Base class/interface + - Required decorators + - Constructor pattern + - Standard method signatures + - Export pattern + +## Reporting Threshold + +Report only if: +- ≥5 files in category AND +- ≥3 share ≥2 structure markers + +## Insight Template + +``` +INSIGHT: + id: TMPL-[n] + title: "FILE PATTERN: [FileType] follows consistent template" + summary: "[N] [FileType] files share [markers]. Scaffolding can be automated." + confidence: [high|medium|low] + evidence: + - path[:line-line] — shows [marker] + template_markers: + - base_class: [name or none] + - decorators: [list] + - constructor_pattern: [description] + - required_methods: [list] + - export_pattern: [description] +``` + +## Command Template + +When a file pattern is detected, propose a command: + +```yaml +name: "create-[file-type]" +summary: "Scaffold a new [FileType] with standard structure" +whenToUse: + - "Adding a new [file-type] to the codebase" + - "Need consistent [file-type] structure" +contextValidationCheckpoints: + - "What is the name of the new [file-type]?" + - "Which module/domain does it belong to?" +steps: + - name: "Create file" + description: "Create [file-type] with standard template" + codeSnippet: | + [extracted template] + - name: "Add to index" + description: "Export from module index if pattern requires" + - name: "Create test file" + description: "Create corresponding test file" +``` diff --git a/.opencode/skills/packmind-onboard/references/role-taxonomy-drift.md b/.opencode/skills/packmind-onboard/references/role-taxonomy-drift.md new file mode 100644 index 000000000..0629128ab --- /dev/null +++ b/.opencode/skills/packmind-onboard/references/role-taxonomy-drift.md @@ -0,0 +1,199 @@ +# Role Taxonomy Drift + +Infer what Service/Handler/UseCase/Controller/Repository mean in practice and surface misnamed or mixed-responsibility hotspots. + +## Search Patterns + +### Common Role Names + +``` +# Controllers (HTTP/presentation) +*Controller.ts +*Controller.js +*controller.py +*_controller.rb +*Controller.java +*Controller.go + +# Handlers (event/command) +*Handler.ts +*Handler.js +*handler.py +*_handler.rb +*Handler.java + +# Services (business logic) +*Service.ts +*Service.js +*service.py +*_service.rb +*Service.java + +# Use Cases (application layer) +*UseCase.ts +*UseCase.js +*Interactor.ts +*use_case.py +*_use_case.rb + +# Repositories (data access) +*Repository.ts +*Repository.js +*Repo.ts +*repository.py +*_repository.rb +*Repository.java + +# Managers (ambiguous) +*Manager.ts +*Manager.js +*manager.py + +# Helpers/Utils (utility) +*Helper.ts +*Utils.ts +*helper.py +*_helper.rb +``` + +### Responsibility Indicators + +``` +# IO operations (should be in repos/adapters) +.save( +.find( +.delete( +.update( +fetch( +axios. +http. +database. +query( +.execute( + +# Business logic (should be in services/use cases) +validate +calculate +process +transform +apply +execute business rule + +# Presentation concerns (should be in controllers) +@Get( +@Post( +@Put( +@Delete( +res.json( +res.send( +response. +request. +@Query( +@Body( +@Param( + +# Event handling (should be in handlers) +@OnEvent( +@Subscribe( +.handle( +.process( +eventEmitter +``` + +### Mixed Responsibility Indicators + +``` +# Controller doing business logic +Controller.*{ + .*validate.* + .*calculate.* + .*process.* + +# Service doing IO directly +Service.*{ + .*\.save\( + .*\.find\( + .*fetch\( + .*database\. + +# Repository doing business logic +Repository.*{ + .*validate.* + .*calculate.* + .*transform.* + +# Handler doing presentation +Handler.*{ + .*res\.json\( + .*response\. +``` + +## Analysis Method + +1. **Enumerate files by role name**: Group by Controller/Service/UseCase/etc. +2. **Sample and analyze**: Read 3-5 files per role +3. **Classify actual responsibilities**: + - Presentation: HTTP handling, request/response + - Business logic: Validation, calculation, rules + - Data access: Persistence, external calls + - Orchestration: Coordinating other components +4. **Compare name vs actual**: Does "Service" do service things? +5. **Find mixed responsibilities**: Single file doing multiple concerns + +## Expected Responsibilities + +| Role | Expected | Red Flags | +|------|----------|-----------| +| **Controller** | HTTP handling, request mapping | Business logic, direct DB access | +| **Service** | Business logic, orchestration | HTTP concerns, raw queries | +| **UseCase** | Single business operation | Multiple concerns, infrastructure | +| **Handler** | Event/command processing | HTTP responses | +| **Repository** | Data access abstraction | Business rules, validation | +| **Manager** | Ambiguous - investigate | Often a code smell | + +## Drift Categories + +| Drift Type | Example | Impact | +|------------|---------|--------| +| **Bloated controller** | Controller with business logic | Hard to test, coupled | +| **Anemic service** | Service just delegates | Unnecessary layer | +| **Fat repository** | Repo with business rules | Logic in wrong layer | +| **Confused handler** | Handler doing everything | Unclear boundaries | +| **God manager** | Manager with all concerns | Unmaintainable | + +## Reporting Threshold + +Report only if: +- ≥3 files with same role name AND +- (Inconsistent responsibilities OR mixed concerns detected) + +## Insight Template + +``` +INSIGHT: + id: ROLE-[n] + title: "ROLE TAXONOMY: [role] has inconsistent meaning across codebase" + summary: "[role] files show [N] different responsibility patterns." + confidence: [high|medium|low] + evidence: + role_analysis: + - role: "Service" + expected: "business logic" + actual_patterns: + - "business logic" — [N] files + - "data access" — [N] files (drift) + - "HTTP handling" — [N] files (drift) + mixed_responsibility_hotspots: + - path[:line] — [role] doing [unexpected concern] + naming_inconsistencies: + - "UserService vs UserManager" — same responsibility + recommendations: + - "[file] should be renamed to [better name]" +``` + +## Standard/Command Suggestions + +- **Standard**: "Controllers handle HTTP only, delegate to use cases" +- **Standard**: "Services contain business logic, no IO" +- **Standard**: "Repositories abstract data access only" +- **Command**: "Extract business logic from controller" diff --git a/.opencode/skills/packmind-onboard/references/test-data-construction.md b/.opencode/skills/packmind-onboard/references/test-data-construction.md new file mode 100644 index 000000000..55691efc8 --- /dev/null +++ b/.opencode/skills/packmind-onboard/references/test-data-construction.md @@ -0,0 +1,136 @@ +# Test Data Construction Patterns + +Determine how tests construct data: helpers/builders, inline literals, fixtures, or mixed. + +## Search Patterns + +### Test File Locations + +``` +# Directories +test/ +tests/ +__tests__/ +spec/ +specs/ + +# File patterns +*.test.ts +*.test.js +*.test.tsx +*.test.jsx +*.spec.ts +*.spec.js +*.spec.tsx +*.spec.jsx +*_test.go +*_test.py +test_*.py +*Test.java +*Spec.scala +``` + +### Helper/Builder Patterns + +``` +# Factory functions +Factory +factory( +createMock +buildMock +make( +build( +generate( +fake( +stub( + +# Builder patterns +Builder +.build() +.create() +.with( +.having( + +# Test data libraries +faker +Faker +@faker-js +factory-girl +fishery +test-data-bot +FactoryBot +factory_bot +Fabricator +``` + +### Fixture/Seed Patterns + +``` +# Fixture files +fixtures/ +__fixtures__/ +seeds/ +mocks/ +stubs/ + +# Fixture loading +loadFixture +readFixture +importFixture +fixture( +seed( +``` + +### Inline Construction Indicators + +``` +# Direct object creation in tests +const mock = { +let testData = { +const input = { +new TestEntity( +Object.assign( +{ ...baseData, +``` + +## Classification Criteria + +| Pattern | Indicators | +|---------|------------| +| **Helpers/builders** | Dedicated factory functions reused across ≥3 test files | +| **Inline** | Objects created directly in test bodies; no shared helpers | +| **Fixtures** | External JSON/YAML files or fixture directories | +| **Mixed** | Multiple patterns without dominant approach | + +## Sampling Method + +1. List test files by path, sort ascending +2. Sample first 10 files (or all if <10) +3. For each file, classify primary data construction method +4. Detect shared builders: same helper imported in ≥3 tests + +## Reporting Threshold + +Report only if: +- ≥2 patterns appear in sample, OR +- Shared builder exists but many tests still use inline (inconsistency) + +## Insight Template + +``` +INSIGHT: + id: TEST-[n] + title: "TEST DATA: construction patterns vary ([X]% helpers, [Y]% inline, [Z]% fixtures)" + summary: "Test data is constructed using [dominant pattern]. [inconsistencies if any]" + confidence: [high|medium|low] + evidence: + - path[:line-line] — uses [pattern] + exceptions: + - path[:line-line] — diverges from dominant pattern +``` + +## Standard/Command Suggestions + +- **Standard**: "Use test factories for domain entities" (if inline dominant but factories exist) +- **Standard**: "Prefer builder pattern for complex test data" (if mixed patterns) +- **Command**: "Create test factory" (if helpers pattern established) diff --git a/.opencode/skills/packmind-update-playbook/LICENSE.txt b/.opencode/skills/packmind-update-playbook/LICENSE.txt new file mode 100644 index 000000000..f433b1a53 --- /dev/null +++ b/.opencode/skills/packmind-update-playbook/LICENSE.txt @@ -0,0 +1,177 @@ + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS diff --git a/.opencode/skills/packmind-update-playbook/SKILL.md b/.opencode/skills/packmind-update-playbook/SKILL.md new file mode 100644 index 000000000..e9efc2323 --- /dev/null +++ b/.opencode/skills/packmind-update-playbook/SKILL.md @@ -0,0 +1,143 @@ +--- +name: 'packmind-update-playbook' +description: 'Use when updating, adding, fixing, changing, or deprecating Packmind playbook artifacts (standards, commands, skills). Triggers on explicit phrases like "update packmind standard", "add a packmind skill", "fix packmind command", "change packmind playbook", "deprecate a standard". Also triggers — even without an explicit request — whenever the conversation reveals an opportunity: a new coding convention was just agreed on, a recurring pattern emerged, a workflow changed, a rule was found outdated, or the user says things like "we always do X", "let us remember to Y", "that is the pattern we use". If there is any chance the conversation established a convention or exposed a gap, invoke this skill proactively. This skill defines a mandatory workflow: do NOT edit artifact files directly — follow all phases regardless of change size.' +--- + +# Update Playbook +Run "packmind-cli --version" to get the current cli installation. + +Find the highest version at or below the cli version in this list: +- 0.21.0 +- 0.23.0 +Remember this value as $PACKMIND_CLI_VERSION for the rest of the skill. + +Evaluate the user's intent against existing Packmind artifacts (standards, commands, skills) to identify what needs creating or updating. Produce a structured change report, then apply approved changes using the `playbook` CLI workflow. + +**⚠️ MANDATORY WORKFLOW — This skill defines a strict sequence: Understanding Your Request → Summarizing Changes → Analyzing Playbook → Change Report → Applying Changes. Do NOT skip steps or edit artifact files directly. Even for a single-line change, follow every step. The workflow ensures changes are reviewed, approved, submitted, and propagated correctly.** + +## **Understanding Your Request** + +**STOP. This phase runs FIRST, before anything else. No file reads, no CLI commands, no subagents until this gate passes.** + +Analyze the user's input and conversation context to determine intent: + +#### Case A: No prior conversation / empty input + +The skill was invoked standalone with no context. Ask: + +"What Packmind artifact do you want to modify? For example: a **standard** (coding rule/convention), a **command** (multi-step workflow), or a **skill** (specialized capability). Please describe what you'd like to change." + +**BLOCK** — do not proceed until the user responds. + +#### Case B: Explicit intent found + +The user explicitly asked to update, add, fix, or change a Packmind artifact. Extract an **intent summary**: +- **Target artifact(s)**: which standard(s), command(s), or skill(s) to modify (or "new") +- **Kind of change**: create or update +- **Specifics**: any details the user provided about the change + +Proceed to Summarizing Changes with this validated intent. + +#### Case C: Opportunity detected from conversation + +The conversation reveals a playbook update opportunity — e.g., a convention was established, a pattern emerged, a workflow was changed, or a known artifact is now stale — but the user did not explicitly ask for a playbook update. Summarize the opportunity and ask: + +"I noticed an opportunity to update the Packmind playbook: ****. Would you like me to run the update workflow?" + +**BLOCK** — do not proceed until the user confirms. + +#### Case D: No intent and no opportunity + +If the conversation contains no references to modifying Packmind artifacts and no detectable update opportunity, tell the user: + +"I didn't detect any intent or opportunity to modify the Packmind playbook. What artifact would you like to update — a standard, command, or skill? Please describe the change." + +**BLOCK** — do not proceed until the user responds. + +### Summarizing Changes + +> Only proceed after Understanding Your Request validates intent (explicit request or confirmed opportunity). + +Summarize the validated intent before launching any subagents. Extract: +- Which artifact(s) the user wants to modify and what kind of change +- Any specifics the user provided about the desired change +- If prior conversation exists, relevant context that supports the intent (patterns observed, decisions made, problems encountered) + +This intent summary is passed as input to all subagents. + +### Analyzing Playbook + +> **CLI health check**: Before launching subagents, run `packmind-cli --version`. If it fails, stop immediately and tell the user: "The Packmind CLI is not available or not working. Please check your installation before proceeding." Do not continue. + +> **No subagent support?** If the `Task` tool is unavailable, perform all three domain analyses sequentially in the current session — run each `steps/analyze-*.md` analysis one after another before proceeding to Change Report. + +Launch all three as `Task(general-purpose)` subagents **simultaneously** — do not wait for one before starting the others. Each subagent handles its own listing, filtering, and deep analysis in one pass. + +Construct each prompt as: + +``` +## Validated Intent + + + +## Analysis Task + + +``` + +| Subagent | Step File | Output | +|----------|-----------|--------| +| Standards | `steps/analyze-standards.md` | Standards change report | +| Commands | `steps/analyze-commands.md` | Commands change report | +| Skills | `steps/analyze-skills.md` | Skills change report | + +For each domain, decide whether to launch or skip based on the validated intent's **target artifact type**: +- **Launch** if the intent mentions or affects that artifact type (standard, command, or skill) +- **Always launch skills** — skill accuracy must be checked against any behavioral change +- **Limit scope** to the targeted artifact type when the intent is explicit and narrow (e.g., "update standard X" → standards only, no commands or unrelated skills) + +### Change Report + +After all subagents complete, consolidate their reports. **Before numbering, deduplicate**: if multiple subagents propose modifying the same artifact, merge those into one entry combining both rationales — do not list the same artifact twice. **Number every change sequentially** so the user can selectively approve: + +``` +## Playbook Change Report + + + + + +### Skill Updates +1. [skill] : + +### New Skills +2. [skill] : + +### Standard Updates +3. [standard] : + +### New Standards +4. [standard] : + +### New Commands +5. [command] : + +### Command Updates +6. [command] : +``` + +**Only include sections that have actual changes** — omit empty sections entirely. Order by priority: skills first, then standards, then commands. + +Present this report and ask the user for approval: +- **Single change**: ask "Do you accept this change?" +- **Multiple changes**: ask "Which changes to apply?" and accept: + - **All**: apply every numbered change + - **Inclusion list**: "1, 3, 5" or "only 2 and 6" + - **Exclusion list**: "all but 4" or "everything except 2, 7" + +### Applying Changes + +Follow the procedure in [`packmind-versions/<$PACKMIND_CLI_VERSION>/apply-changes.md`](packmind-versions/<$PACKMIND_CLI_VERSION>/apply-changes.md). +Pass it the list of approved changes (with their numbers and details) from the Change Report above. + + diff --git a/.opencode/skills/packmind-update-playbook/packmind-versions/0.21.0/apply-changes.md b/.opencode/skills/packmind-update-playbook/packmind-versions/0.21.0/apply-changes.md new file mode 100644 index 000000000..7de5104a2 --- /dev/null +++ b/.opencode/skills/packmind-update-playbook/packmind-versions/0.21.0/apply-changes.md @@ -0,0 +1,50 @@ +# Applying Changes + +> **Prerequisite**: Run `packmind-cli --version`. If it fails, stop immediately and tell the user: "The Packmind CLI is not available or not working. Please check your installation before proceeding." Do not continue. + +## Step 1: Write new artifacts + +For each approved **new** artifact, read the corresponding creation procedure from `references/`, then write the file(s) at the specified location: + +| Artifact Type | Creation Procedure | Write Path | +|---|---|---| +| Standard | [create-standard-procedure.md](../references/create-standard-procedure.md) | `.packmind/standards/.md` | +| Command | [create-command-procedure.md](../references/create-command-procedure.md) | `.packmind/commands/.md` | +| Skill | [create-skill-procedure.md](../references/create-skill-procedure.md) | `//SKILL.md` | + +For skills: check which agent skills directory exists at the project root (`.claude/skills/`, `.cursor/skills/`, `.github/skills/`) — pick the first found in that priority order. If none exist, create `.claude/skills/`. + +After writing each new artifact, run `packmind-cli diff add -m ""` to submit it as a change proposal. This auto-submits the new artifact. The message must be non-empty and max 1024 characters. If this command fails, show the full error output, stop, and ask the user how to proceed — do not retry silently. + +## Step 2: Preview updates + +For each approved **update** to an existing artifact, edit the local installed files directly. Search the project root **and all subdirectories** (e.g. `src/backend/.cursor/skills/`, `packages/api/.packmind/standards/`): + +- **Standards**: `**/.packmind/standards/.md` (source of truth). Installed copies also exist in: + - Claude Code: `**/.claude/rules/packmind/` + - Cursor: `**/.cursor/rules/packmind/` + - GitHub Copilot: `**/.github/instructions/packmind-*` +- **Commands**: `**/.packmind/commands/.md` (source of truth). Installed copies also exist in: + - Claude Code: `**/.claude/commands/` + - Cursor: `**/.cursor/commands/` + - GitHub Copilot: `**/.github/prompts/` +- **Skills**: no `.packmind/` source — skills live directly in agent directories: + - Claude Code: `**/.claude/skills//` + - Cursor: `**/.cursor/skills//` + - GitHub Copilot: `**/.github/skills//` + +If the same artifact exists in multiple agent directories, edit the one matching the current session context: Claude Code → `.claude/`, Cursor → `.cursor/`, GitHub Copilot → `.github/`. If the context is unclear and multiple directories exist, list them and ask the user which agent directory to update. + +Run `packmind-cli diff` and present the output. List all artifacts included in the diff. Since it is not possible to select individual changes, **all detected modifications will be submitted together**. + +- If the diff contains only the intended changes, proceed to Step 3. +- If the diff contains **additional or unrelated artifacts**, inform the user by listing them and clarifying that they will be included in the submission as well. + +## Step 3: Submit updates + +Run `packmind-cli diff --submit -m ""` to submit the changes as proposals for human review on Packmind. If this command fails, show the full error output, stop, and ask the user how to proceed — do not retry silently. + +Once submitted, run `packmind-cli whoami` and extract the `Organization:` field from the output. Construct the review URL as `https://app.packmind.ai/org//space/global/review-changes/`. + +Tell the user: **"✅ Successfully sent to Packmind for review!"** +Then add in italics: *"Review and accept your change proposals at — once accepted, changes will be propagated and will replace all local copies."* diff --git a/.opencode/skills/packmind-update-playbook/packmind-versions/0.23.0/apply-changes.md b/.opencode/skills/packmind-update-playbook/packmind-versions/0.23.0/apply-changes.md new file mode 100644 index 000000000..2f00ba50d --- /dev/null +++ b/.opencode/skills/packmind-update-playbook/packmind-versions/0.23.0/apply-changes.md @@ -0,0 +1,110 @@ +# Applying Changes + +#### Pre-flight: Space Discovery + +Before writing any files, discover available spaces: + +1. Run `packmind-cli spaces list` to see available spaces. +2. If only **one space** exists, note its slug — the `--space` flag is optional for all commands. +3. If **multiple spaces** exist, note all slugs. The `--space` flag is **required** when staging **new** artifacts. For updates to existing artifacts, the space auto-resolves from the lock file. + +#### Group Changes by Intent + +Before touching any files, group the approved changes into logical **intents** — coherent units of related change that a human reviewer can understand as a single proposal. + +**Grouping rules**: +- Changes that serve the same purpose belong together (e.g., "update authentication patterns" = update auth standard + update auth skill) +- Unrelated changes get separate intents (e.g., "update auth patterns" and "fix test naming convention" are 2 intents) +- A single approved change = 1 intent +- Deprecations (removals) should be their own intent unless tightly coupled with a replacement + +Number the intents and present the grouping to the user: + +``` +## Submission Plan + +Intent 1: "" — changes #1, #3 +Intent 2: "" — change #5 +``` + +Proceed once the user confirms the grouping, or adjust if they suggest different groupings. + +#### For Each Intent (one at a time): + +##### Step 1: Write or edit artifact files locally + +Edit the files that belong to **your agent** — this lets the user review and test changes in their actual working environment. Do NOT edit files from other agents or the `.packmind/` source-of-truth copies. Only edit one copy per artifact; the CLI handles the rest. + +Determine which agent context you are running in. The agent directories are: +- Claude Code: `.claude/` +- Cursor: `.cursor/` +- GitHub Copilot: `.github/` + +**Important**: Packmind packages can be installed in subdirectories, not just the repo root. Search for `**/packmind-lock.json` across the entire project tree to find all installed locations. Each lock file lists all files per artifact with their agent — use the path matching your agent. + +Before writing or editing any artifact, read the corresponding creation procedure for content format and structure guidance: +- Standard: [create-standard-procedure.md](../../references/create-standard-procedure.md) +- Command: [create-command-procedure.md](../../references/create-command-procedure.md) +- Skill: [create-skill-procedure.md](../../references/create-skill-procedure.md) + +**For updated artifacts**, find and edit the file at your agent's path. The lock file tells you the exact relative path. Remember that artifacts may live in nested project directories (e.g. `packages/api/.claude/rules/packmind/`, `apps/backend/.claude/commands/`). + +**For new artifacts**, write files at the agent-specific location within the directory that contains the relevant `packmind-lock.json`: + +| Artifact Type | Claude Code | Cursor | GitHub Copilot | +|---|---|---|---| +| Standard | `.claude/rules/packmind/.md` | `.cursor/rules/packmind/.md` | `.github/instructions/packmind-.md` | +| Command | `.claude/commands/.md` | `.cursor/commands/.md` | `.github/prompts/.md` | +| Skill | `.claude/skills//SKILL.md` | `.cursor/skills//SKILL.md` | `.github/skills//SKILL.md` | + +If there are multiple `packmind-lock.json` locations and it's unclear where the new artifact should go, ask the user which project directory to target. + +**For deprecated artifacts (removal)** — do NOT delete the file yourself. The `playbook rm` command handles removal staging. Skip to Step 2. + +##### Step 2: Stage changes + +For each artifact written or edited in Step 1, stage it with `playbook add`: + +``` +packmind-cli playbook add +``` + +- If the organization has **multiple spaces** and this is a **new** artifact, add the `--space` flag: `packmind-cli playbook add --space ` +- For **updates**, the space auto-resolves from the lock file — no `--space` needed. +- For **deprecated artifacts**: run `packmind-cli playbook rm ` instead. + +If any command fails, show the full error output, stop, and ask the user how to proceed — do not retry silently. + +> **Mistake?** If you staged the wrong file, run `packmind-cli playbook unstage ` to undo it before submitting. + +##### Step 3: Review staged changes + +Run `packmind-cli playbook status` and present the output to the user. Verify: +- All intended changes for this intent are listed under staged changes +- No unintended changes are included +- Artifact types and change types (created/updated/removed) are correct + +Ask the user: **"These changes will be submitted as: ''. Confirm?"** + +**BLOCK** — do not proceed until the user confirms. + +##### Step 4: Submit this intent + +Run `packmind-cli playbook submit -m ""` to submit all staged changes as proposals for human review. + +> **The `-m` flag is mandatory.** Without it, the CLI opens an interactive text editor (vim/nano) waiting for the message — this blocks an AI agent indefinitely. Always pass the message inline with `-m`. + +The message should be a concise summary of the intent (max 1024 characters). If this command fails, show the full error output, stop, and ask the user how to proceed — do not retry silently. + +##### Step 5: Report and continue + +Tell the user: **"Submitted: ''"** + +If more intents remain, proceed to the next one (back to Step 1). + +#### After All Intents Are Submitted + +Once every intent has been submitted, run `packmind-cli whoami` and extract the `Organization:` field from the output. Construct the review URL as `https://app.packmind.ai/org//review-changes/`. + +Tell the user: **"All change proposals sent to Packmind for review!"** +Then add in italics: *"Review and accept your change proposals at — once accepted, changes will be propagated and will replace all local copies."* diff --git a/.opencode/skills/packmind-update-playbook/references/agent-skills-specification.md b/.opencode/skills/packmind-update-playbook/references/agent-skills-specification.md new file mode 100644 index 000000000..142fbbc38 --- /dev/null +++ b/.opencode/skills/packmind-update-playbook/references/agent-skills-specification.md @@ -0,0 +1,255 @@ + +> ## Documentation Index +> Fetch the complete documentation index at: https://agentskills.io/llms.txt +> Use this file to discover all available pages before exploring further. + +# Specification + +> The complete format specification for Agent Skills. + +This document defines the Agent Skills format. + +## Directory structure + +A skill is a directory containing at minimum a `SKILL.md` file: + +``` +skill-name/ +└── SKILL.md # Required +``` + + + You can optionally include [additional directories](#optional-directories) such as `scripts/`, `references/`, and `assets/` to support your skill. + + +## SKILL.md format + +The `SKILL.md` file must contain YAML frontmatter followed by Markdown content. + +### Frontmatter (required) + +```yaml theme={null} +--- +name: skill-name +description: A description of what this skill does and when to use it. +--- +``` + +With optional fields: + +```yaml theme={null} +--- +name: pdf-processing +description: Extract text and tables from PDF files, fill forms, merge documents. +license: Apache-2.0 +metadata: + author: example-org + version: "1.0" +--- +``` + +| Field | Required | Constraints | +| --------------- | -------- | ----------------------------------------------------------------------------------------------------------------- | +| `name` | Yes | Max 64 characters. Lowercase letters, numbers, and hyphens only. Must not start or end with a hyphen. | +| `description` | Yes | Max 1024 characters. Non-empty. Describes what the skill does and when to use it. | +| `license` | No | License name or reference to a bundled license file. | +| `compatibility` | No | Max 500 characters. Indicates environment requirements (intended product, system packages, network access, etc.). | +| `metadata` | No | Arbitrary key-value mapping for additional metadata. | +| `allowed-tools` | No | Space-delimited list of pre-approved tools the skill may use. (Experimental) | + +#### `name` field + +The required `name` field: + +* Must be 1-64 characters +* May only contain unicode lowercase alphanumeric characters and hyphens (`a-z` and `-`) +* Must not start or end with `-` +* Must not contain consecutive hyphens (`--`) +* Must match the parent directory name + +Valid examples: + +```yaml theme={null} +name: pdf-processing +``` + +```yaml theme={null} +name: data-analysis +``` + +```yaml theme={null} +name: code-review +``` + +Invalid examples: + +```yaml theme={null} +name: PDF-Processing # uppercase not allowed +``` + +```yaml theme={null} +name: -pdf # cannot start with hyphen +``` + +```yaml theme={null} +name: pdf--processing # consecutive hyphens not allowed +``` + +#### `description` field + +The required `description` field: + +* Must be 1-1024 characters +* Should describe both what the skill does and when to use it +* Should include specific keywords that help agents identify relevant tasks + +Good example: + +```yaml theme={null} +description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction. +``` + +Poor example: + +```yaml theme={null} +description: Helps with PDFs. +``` + +#### `license` field + +The optional `license` field: + +* Specifies the license applied to the skill +* We recommend keeping it short (either the name of a license or the name of a bundled license file) + +Example: + +```yaml theme={null} +license: Proprietary. LICENSE.txt has complete terms +``` + +#### `compatibility` field + +The optional `compatibility` field: + +* Must be 1-500 characters if provided +* Should only be included if your skill has specific environment requirements +* Can indicate intended product, required system packages, network access needs, etc. + +Examples: + +```yaml theme={null} +compatibility: Designed for Claude Code (or similar products) +``` + +```yaml theme={null} +compatibility: Requires git, docker, jq, and access to the internet +``` + + + Most skills do not need the `compatibility` field. + + +#### `metadata` field + +The optional `metadata` field: + +* A map from string keys to string values +* Clients can use this to store additional properties not defined by the Agent Skills spec +* We recommend making your key names reasonably unique to avoid accidental conflicts + +Example: + +```yaml theme={null} +metadata: + author: example-org + version: "1.0" +``` + +#### `allowed-tools` field + +The optional `allowed-tools` field: + +* A space-delimited list of tools that are pre-approved to run +* Experimental. Support for this field may vary between agent implementations + +Example: + +```yaml theme={null} +allowed-tools: Bash(git:*) Bash(jq:*) Read +``` + +### Body content + +The Markdown body after the frontmatter contains the skill instructions. There are no format restrictions. Write whatever helps agents perform the task effectively. + +Recommended sections: + +* Step-by-step instructions +* Examples of inputs and outputs +* Common edge cases + +Note that the agent will load this entire file once it's decided to activate a skill. Consider splitting longer `SKILL.md` content into referenced files. + +## Optional directories + +### scripts/ + +Contains executable code that agents can run. Scripts should: + +* Be self-contained or clearly document dependencies +* Include helpful error messages +* Handle edge cases gracefully + +Supported languages depend on the agent implementation. Common options include Python, Bash, and JavaScript. + +### references/ + +Contains additional documentation that agents can read when needed: + +* `REFERENCE.md` - Detailed technical reference +* `FORMS.md` - Form templates or structured data formats +* Domain-specific files (`finance.md`, `legal.md`, etc.) + +Keep individual [reference files](#file-references) focused. Agents load these on demand, so smaller files mean less use of context. + +### assets/ + +Contains static resources: + +* Templates (document templates, configuration templates) +* Images (diagrams, examples) +* Data files (lookup tables, schemas) + +## Progressive disclosure + +Skills should be structured for efficient use of context: + +1. **Metadata** (\~100 tokens): The `name` and `description` fields are loaded at startup for all skills +2. **Instructions** (\< 5000 tokens recommended): The full `SKILL.md` body is loaded when the skill is activated +3. **Resources** (as needed): Files (e.g. those in `scripts/`, `references/`, or `assets/`) are loaded only when required + +Keep your main `SKILL.md` under 500 lines. Move detailed reference material to separate files. + +## File references + +When referencing other files in your skill, use relative paths from the skill root: + +```markdown theme={null} +See [the reference guide](references/REFERENCE.md) for details. + +Run the extraction script: +scripts/extract.py +``` + +Keep file references one level deep from `SKILL.md`. Avoid deeply nested reference chains. + +## Validation + +Use the [skills-ref](https://github.com/agentskills/agentskills/tree/main/skills-ref) reference library to validate your skills: + +```bash theme={null} +skills-ref validate ./my-skill +``` + +This checks that your `SKILL.md` frontmatter is valid and follows all naming conventions. diff --git a/.opencode/skills/packmind-update-playbook/references/create-command-procedure.md b/.opencode/skills/packmind-update-playbook/references/create-command-procedure.md new file mode 100644 index 000000000..e891b9a2a --- /dev/null +++ b/.opencode/skills/packmind-update-playbook/references/create-command-procedure.md @@ -0,0 +1,102 @@ +# Create Command Procedure + +Write a new command file locally at `.packmind/commands/.md`. + +## Slug Derivation + +Derive the slug from the command title: lowercase, replace spaces with hyphens, remove special characters. + +**Example**: "Create API Endpoint" → `create-api-endpoint` + +**Write path**: `.packmind/commands/.md` + +**Directory check**: If `.packmind/commands/` does not exist, create it before writing the file. + +## File Format + +Use YAML frontmatter with a `description:` field, followed by the command body: + +```markdown +--- +description: 'One-sentence description of the command purpose and when to use it.' +--- + +Opening paragraph describing what this command does and its scope. + +## When to Use + +* When scenario 1 + +* When scenario 2 + +## Context Validation Checkpoints + +* [ ] What is the key input or configuration needed? + +* [ ] Does the target directory or file already exist? + +* [ ] Are there any prerequisites that must be met? + +* [ ] Is the current state clean enough to proceed? + +## Steps + +### Step 1: Verify prerequisites + +Explanatory text describing what this step does and why. + +\`\`\`language +// code example showing exactly what to do +\`\`\` + +### Step 2: Create core implementation + +Explanatory text describing what this step does and why. + +\`\`\`language +// code example showing exactly what to do +\`\`\` +``` + +### Critical Format Constraints + +- **File must be non-empty** — the parser rejects empty files +- **Without frontmatter**, the display name is auto-derived from the filename (only the first character is capitalized, e.g. `create-api-endpoint` → "Create-api-endpoint") +- **Use frontmatter `description:`** to provide a one-sentence summary of the command's purpose and when to use it +- The command body content is stored as-is — the parser is permissive about structure + +## Command Writing Guidelines + +### Body Structure + +1. **Opening paragraph** (required) — one paragraph directly after frontmatter, no `# H1` heading. Describes what the command does and its scope. +2. **"When to Use"** section (optional for procedural commands) — 2-6 bullet points using the "When..." pattern (e.g., `* When adding support for a new AI coding assistant`). +3. **"Context Validation Checkpoints"** section (optional for procedural commands) — 4-6 `* [ ]` checkbox questions the agent should verify before executing. +4. **"Steps"** section (required) — the core of the command. + +### Step Writing + +- Use `### Step N: Verb Object` format (e.g., `### Step 1: Add RenderMode enum value`, `### Step 5: Register deployer in registry`) +- Always start the step title with a verb: Add, Create, Implement, Write, Register, Update, Verify, Export +- Target 6-16 steps for complex commands +- Every step includes explanatory text followed by a code example showing exactly what to do +- End with a verification or quality gate step when applicable (e.g., "Verify link paths", "Run integration tests") + +### Template Variables + +- Use `{{variable}}` syntax for user-provided values (e.g., `{{version}}`, `{{today_date}}`) +- Use sparingly — only for values that change per invocation + +### Cross-References + +- Reference existing files and patterns as concrete examples to follow +- Use actual file paths from the codebase (e.g., `packages/types/src/deployments/RenderMode.ts`) +- Point to existing implementations as models (e.g., "Follow the pattern of existing integration tests like `cursor-deployment.spec.ts`") + +### Variant: Procedural Commands + +Simpler structure for release-style or operational commands: +- Skip "When to Use" and "Context Validation Checkpoints" sections +- Use numbered list steps (`1. **Step name**: description`) instead of `###` headers +- Include code blocks inline within list items where needed +- See `release-app.md` as an example of this pattern diff --git a/.opencode/skills/packmind-update-playbook/references/create-skill-procedure.md b/.opencode/skills/packmind-update-playbook/references/create-skill-procedure.md new file mode 100644 index 000000000..b1b2b84f2 --- /dev/null +++ b/.opencode/skills/packmind-update-playbook/references/create-skill-procedure.md @@ -0,0 +1,97 @@ +# Create Skill Procedure + +Write a new skill directory locally in an agent skills directory. + +## Write Path Selection + +Skills are stored in agent-specific directories: +- `.claude/skills/` (agent: claude) +- `.cursor/skills/` (agent: cursor) +- `.github/skills/` (agent: copilot) + +**Selection logic**: check which directories exist at the project root. Pick the first one found in priority order: +1. `.claude/skills/` +2. `.cursor/skills/` +3. `.github/skills/` + +If none exist, create `.claude/skills/` as the default. + +**Write path**: `//SKILL.md` + +## Slug Derivation + +Derive the skill name from the title: lowercase, replace spaces with hyphens, remove special characters. + +**Example**: "PDF Processing" → `pdf-processing` + +**Naming rules**: +- 1-64 characters +- Lowercase letters, numbers, and hyphens only +- Must not start or end with a hyphen +- Must not contain consecutive hyphens (`--`) +- Directory name MUST match the `name` field in SKILL.md frontmatter + +## Directory Structure + +``` +/ +├── SKILL.md # Required +├── references/ # Optional — detailed docs, specs, lookup tables +├── scripts/ # Optional — executable code agents can run +└── assets/ # Optional — templates, images, data files +``` + +**When to use each resource type:** +- **scripts/**: Executable code for tasks requiring deterministic reliability or repeatedly rewritten code (e.g. `scripts/rotate_pdf.py`). Token-efficient — may be executed without loading into context. +- **references/**: Documentation loaded into context as needed (schemas, API docs, domain knowledge). Keeps SKILL.md lean — avoid duplicating content between SKILL.md and references. +- **assets/**: Files used in output (templates, images, boilerplate) — not loaded into context, copied or modified by Claude during execution. + +## SKILL.md Format + +```markdown +--- +name: skill-name +description: 'What the skill does and when to use it. Third-person form. Include trigger keywords for auto-load.' +--- + +# Skill Title + +Body content with instructions, examples, and edge cases. +``` + +### Critical Format Constraints + +- **Directory name must match `name` field** — e.g. directory `pdf-processing/` requires `name: pdf-processing` +- **`name`**: 1-64 chars, lowercase + hyphens only, no leading/trailing/consecutive hyphens +- **`description`**: 1-800 chars (Packmind cap, tighter than the 1024 spec maximum), include specific keywords that help agents identify when to activate +- **Keep SKILL.md under 500 lines** — use `references/` for detailed content overflow +- **Both the directory path and the `SKILL.md` path** are valid references to a skill (they resolve to the same directory) + +### Description Writing Guidelines + +The description determines when the skill auto-loads. Write it to: +- **Stay within 800 characters.** This is a Packmind cap (the upstream spec allows 1024). The description is always loaded into agent context, so keep it lean. If you need more room to explain the skill, move detail into the SKILL.md body or a `references/` file. +- Describe what the skill does in **third-person form** (e.g. "This skill should be used when..." not "Use this skill when...") +- Include trigger phrases the user might say (e.g. "extract text from PDF", "fill PDF forms") +- Mention relevant keywords for discoverability + +**Good**: `'Extract text and tables from PDF files, fill PDF forms, and merge multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.'` + +**Poor**: `'Helps with PDFs.'` + +### Writing Style + +- Use **imperative/infinitive form** (verb-first instructions), not second person (e.g. "To accomplish X, do Y" not "You should do X") +- Write for another Claude instance — focus on non-obvious procedural knowledge, not general capabilities +- **File placement rule**: create files directly in their target subdirectory (`references/`, `scripts/`, `assets/`), never at skill root then move + +### Body Content Guidelines + +- Provide step-by-step instructions for the main workflow +- Include examples of inputs and outputs +- Document common edge cases +- **Progressive disclosure**: metadata (~100 words, always in context) → SKILL.md body (<5k words, loaded on trigger) → bundled resources (loaded as needed). Structure content accordingly. +- **No duplication**: information should live in either SKILL.md or references, not both. Keep SKILL.md lean with essential workflow guidance; move detailed schemas, specs, and examples to `references/`. +- **Large references**: if reference files exceed ~10k words, include grep search patterns in SKILL.md so Claude can locate relevant sections without loading the entire file + +For the complete format specification, see [agent-skills-specification.md](agent-skills-specification.md). diff --git a/.opencode/skills/packmind-update-playbook/references/create-standard-procedure.md b/.opencode/skills/packmind-update-playbook/references/create-standard-procedure.md new file mode 100644 index 000000000..70362d93a --- /dev/null +++ b/.opencode/skills/packmind-update-playbook/references/create-standard-procedure.md @@ -0,0 +1,62 @@ +# Create Standard Procedure + +Write a new standard file locally at `.packmind/standards/.md`. + +## Slug Derivation + +Derive the slug from the standard title: lowercase, replace spaces with hyphens, remove special characters. + +**Example**: "TypeScript Testing Conventions" → `typescript-testing-conventions` + +**Write path**: `.packmind/standards/.md` + +**Directory check**: If `.packmind/standards/` does not exist, create it before writing the file. + +## File Format + +The parser expects this exact structure: + +```markdown +# Standard Name + +Description text here. Explain what this standard covers and why it matters. + +## Rules + +* Rule 1 +* Rule 2 +* Rule 3 +``` + +### Critical Format Constraints + +- **No YAML frontmatter** — the file is pure markdown +- **Only `* ` or `- ` bullet rules are parsed** — `### Rule` subsections are NOT supported by the parser +- **`## Scope` is NOT parsed** (always returns empty string) — do not include it +- **Must have at least one real rule** — the parser rejects empty rules and silently filters out the placeholder text "No rules defined yet." +- The `## Rules` heading is recommended for clarity but technically optional — the parser finds rules from the first `* `/`- ` bullet even without it + +## Rule Writing Guidelines + +Each rule should: +- **Start with a verb** (imperative mood): "Use", "Prefer", "Avoid", "Return", "Define", "Extract" +- **Express one concept per rule** — split compound rules into separate bullets +- **Be concise** (~25 words max) — no rationale phrases like "because..." or "to ensure..." +- **Be actionable** — the developer should know exactly what to do +- **Avoid vague terms** — replace "appropriate", "properly", "correctly" with specifics + +### Good Rules + +```markdown +* Use `readonly` for properties that should not be reassigned after initialization +* Prefer named exports over default exports for better refactoring support +* Return early from functions to avoid deep nesting +``` + +### Bad Rules + +```markdown +* Make sure to properly handle errors (vague, no verb-first) +* Use TypeScript because it's safer and better (contains rationale) +* Functions should be small, well-named, and follow single responsibility (multiple concepts) +``` diff --git a/.opencode/skills/packmind-update-playbook/steps/analyze-commands.md b/.opencode/skills/packmind-update-playbook/steps/analyze-commands.md new file mode 100644 index 000000000..eaa338fba --- /dev/null +++ b/.opencode/skills/packmind-update-playbook/steps/analyze-commands.md @@ -0,0 +1,57 @@ +# Commands Domain Analysis + +Scan existing commands, identify which are relevant to the user's validated intent, then perform deep analysis on those in one pass. + +## What Commands Are + +Commands are reusable multi-step workflows distributed to AI coding agents. Each command has a name, summary, "when to use" list, context validation checkpoints, and numbered steps. Source files live in `**/.packmind/commands/.md`. Installed copies also exist in agent directories: +- Claude Code: `**/.claude/commands/` +- Cursor: `**/.cursor/commands/` +- GitHub Copilot: `**/.github/prompt/` +Search the project root and all subdirectories. + +## Instructions + +### Step 1: List Commands + +Run `packmind-cli commands list` to get slugs and names. Do NOT read individual command files yet. + +### Step 2: Filter Relevant Commands + +For each command in the list, ask: **Does the user's intent involve updating this command?** + +Relevant means: the intent explicitly targets this command, describes changes to its workflow steps, or references issues with its current behavior. Match by workflow topic using slug and name — no deep reading yet. + +Do NOT propose new commands — command creation is a deliberate, user-driven process. + +### Step 3: Deep Analyze Flagged Commands + +For each relevant command, read `**/.packmind/commands/.md`. Evaluate the command against the user's requested changes: +- Intent requests adding steps → propose adding them at the specified location +- Intent requests modifying steps → propose the specific modifications +- Intent requests removing steps → propose removal with rationale +- Intent requests updating "When to use" → propose the new triggers +- If conversation context exists, use it as supporting evidence for the evaluation + +Apply a HIGH BAR — only propose updates when there is strong evidence: +- The user's intent clearly describes a needed change +- A step references a tool, path, or API that no longer exists +- A critical gap is identified that the intent highlights + +Do NOT propose updates for minor wording or changes not supported by the user's intent. + +## Output Format + +```markdown +## Commands Change Report + +### Command Updates +(If none: "No updates needed.") + +#### Command Name (``) +- **Reason**: what changed or what's missing +- **Steps to add**: step name — description (insert after step N) +- **Steps to modify**: Step N: old → new +- **Steps to remove**: Step N: "step name" — reason +- **Checkpoints to add**: checkpoint question? +``` diff --git a/.opencode/skills/packmind-update-playbook/steps/analyze-skills.md b/.opencode/skills/packmind-update-playbook/steps/analyze-skills.md new file mode 100644 index 000000000..524bcc3f9 --- /dev/null +++ b/.opencode/skills/packmind-update-playbook/steps/analyze-skills.md @@ -0,0 +1,77 @@ +# Skills Domain Analysis + +Scan existing skills, identify which are relevant to the user's validated intent, then perform deep analysis on those in one pass. + +## What Skills Are + +Skills are modular packages providing specialized knowledge and workflows. Each skill has a `SKILL.md` with YAML frontmatter (`name`, `description`) and markdown body, plus optional `references/`, `scripts/`, and `assets/`. The `description` field determines when the skill auto-loads. Skills live in a platform-specific agent directory, at the project root or in any subdirectory (e.g. `src/backend/.cursor/skills/`): +- Claude Code: `**/.claude/skills//` +- Cursor: `**/.cursor/skills//` +- GitHub Copilot: `**/.github/skills//` +Search recursively for these directories. If multiple agent directories exist, pick one. + +For the complete format specification (frontmatter fields, naming rules, directory structure, progressive disclosure), see [agent-skills-specification.md](../references/agent-skills-specification.md). + +## Instructions + +### Step 1: List Skills + +Run `packmind-cli skills list` to get slugs, names, and descriptions. Do NOT read SKILL.md bodies or reference files yet. + +**Exclude default artifacts**: skip any skill whose slug starts with `packmind-`. These are managed by Packmind and must not be analyzed or modified by this workflow. + +### Step 2: Filter Relevant Skills + +For each skill in the list, ask: **Does the user's intent relate to this skill?** + +Relevant means: the intent explicitly targets this skill, describes changes to its domain or behavior, or highlights issues with its current content. + +Be GENEROUS in flagging existing skills for review — it's cheap to check and expensive to let skills go stale. (This intentionally differs from the HIGH BAR applied to standards: a stale skill actively misleads agents at runtime, so the cost of a false negative is high. Standards are noise-sensitive; skills are accuracy-sensitive.) + +Also identify **new skill ideas** if the user's intent suggests creating one. A new skill is warranted if: +- The intent describes specialized knowledge that no existing skill covers +- A decision table or heuristic is needed that a general model wouldn't know +- The user explicitly requests a new skill for a specific domain + +### Step 3: Deep Analyze Flagged Skills + +For each relevant skill, read the full `SKILL.md` and note its reference files. Keeping skills accurate is critical — stale skills actively mislead agents. Evaluate against the user's intent: +- Does the intent request changes to decision tables, patterns, or workflows? +- Does the intent highlight APIs, paths, patterns, or versions that changed? (update immediately) +- Does the intent describe domain knowledge the skill should provide but doesn't? (add content or reference) +- Does the intent flag anti-patterns that aren't documented? +- Does the intent suggest the skill's auto-load triggers need adjustment? (description may need tuning) +- If conversation context exists, use it as supporting evidence for the evaluation + +Flag even small inaccuracies — a skill that gives wrong guidance is worse than no skill. + +For each new skill idea, verify: +- This fits at least one skill archetype: team-specific conventions/domain logic not in public docs, a multi-step workflow with project-specific tools or paths, or a curated bundle of resources/knowledge that provides task-relevant context to agents +- It will be needed in future sessions (not a one-off) +- SKILL.md would stay under 5k words (plan references for overflow) + +For each new skill that passes validation, follow the procedure in [create-skill-procedure.md](../references/create-skill-procedure.md) to write the skill directory. + +## Output Format + +```markdown +## Skills Change Report + +### New Skills + + +#### skill-name +- **Reason**: why this skill is needed +- **Auto-load triggers**: when it should activate +- **Key contents**: decision tables, anti-patterns, references needed + +### Skill Updates + + +#### skill-name +- **Reason**: what changed or what's missing +- **SKILL.md changes**: sections to add/modify/remove +- **Reference file changes**: files to add/update/remove +- **Description update**: new description if auto-load triggers need adjustment + +``` diff --git a/.opencode/skills/packmind-update-playbook/steps/analyze-standards.md b/.opencode/skills/packmind-update-playbook/steps/analyze-standards.md new file mode 100644 index 000000000..9f28cf2dd --- /dev/null +++ b/.opencode/skills/packmind-update-playbook/steps/analyze-standards.md @@ -0,0 +1,76 @@ +# Standards Domain Analysis + +Scan existing standards, identify which are relevant to the user's validated intent, then perform deep analysis on those in one pass. + +## What Standards Are + +Standards are coding conventions distributed to AI coding agents. Each standard has a name (with `[TAG]` prefix), description, rules (imperative, ~25 words max each), and scope (file glob). Source files live in `**/.packmind/standards/.md`. Installed copies also exist in agent directories: +- Claude Code: `**/.claude/rules/packmind/` +- Cursor: `**/.cursor/rules/packmind/` +- GitHub Copilot: `**/.github/instructions/packmind-*` +Search the project root and all subdirectories. + +## Instructions + +### Step 1: List Standards + +Run `packmind-cli standards list` to get slugs, names, and descriptions. Do NOT read individual standard files yet. + +### Step 2: Filter Relevant Standards + +For each standard in the list, ask: **Does the user's stated intent relate to the domain this standard covers?** + +Relevant means: the intent targets this standard directly, involves changes to files matching the standard's scope, or describes modifications that could add, change, or invalidate a rule. Match by topic using slug, name, and description — no deep reading yet. + +Also identify **new standard ideas** if the user's intent suggests capturing a new convention. A new standard must meet ALL of: +- **Lintable**: mechanically verifiable by reading code (not subjective judgment) +- **Recurring**: pattern applies broadly or is a hard constraint (not a one-off) +- **Uncovered**: no existing standard already addresses it + +Skip general best practices any competent developer already knows. + +### Step 3: Deep Analyze Flagged Standards + +For each relevant existing standard, read `**/.packmind/standards/.md` and evaluate every rule against the user's intent: +- Rule aligns with the requested change → apply the modification +- Rule conflicts with the intent → update or remove as requested +- Intent describes a pattern this standard should cover but doesn't → gap, propose adding a rule +- If conversation context exists, use it as supporting evidence for the evaluation + +For each new standard idea, draft concrete rules and apply the lintability gate: +- **Mechanically verifiable**: can an agent check compliance by reading code? +- **Clear scope**: does it have a file glob where it applies? +- **Actionable**: does it say exactly what to do (not "prefer X" or "consider Y")? +- **Non-obvious**: would a senior developer NOT already do this without the rule? + +Prefer fewer, sharper rules. When in doubt, leave it out. + +## Output Format + +```markdown +## Standards Change Report + +### New Standards +(If none: "No new standards needed.") + +#### [TAG] Standard Name +- **Scope**: `file/glob/pattern` +- **Reason**: why this pattern warrants a standard +- **Rules**: + - Rule in imperative form (~25 words max) + +### Standard Updates +(If none: "No updates needed.") + +#### [TAG] Standard Name (``) +- **Reason**: what changed or what's missing +- **Rules to add**: new rule text +- **Rules to modify**: "old text" → "new text" +- **Rules to remove**: "rule text" — reason + +### Standards to Deprecate +(If none: "No deprecations needed.") + +#### [TAG] Standard Name (``) +- **Reason**: why no longer relevant +``` diff --git a/.opencode/skills/working-with-playground-app/SKILL.md b/.opencode/skills/working-with-playground-app/SKILL.md new file mode 100644 index 000000000..52f0fcdb7 --- /dev/null +++ b/.opencode/skills/working-with-playground-app/SKILL.md @@ -0,0 +1,182 @@ +--- +name: 'working-with-playground-app' +description: 'This skill provides guidance for building UI/UX prototypes in the Packmind playground app. It should be used when creating a new prototype, iterating on an existing prototype, or working with files in apps/playground/. Triggers on mentions of "playground", "prototype", or direct work within the apps/playground/ directory.' +--- + +# Working With the Playground App + +## Overview + +The playground app (`apps/playground/`) is a standalone Vite + React environment for iterating on UI/UX of Packmind features — both new and existing. Prototypes built here are meant to be easily convertible into production-ready code. + +## UX Design Thinking + +Before writing any code, think like a UX designer. The playground exists to explore how a feature *feels* to use — not just how it looks. Apply these principles to every prototype: + +### Design All States First + +Never prototype only the happy path. Before building, identify and plan for every state the user might encounter: + +- **Empty state** — What does the user see before any data exists? Guide them toward the first action. +- **Loading state** — What appears while data is being fetched? Use skeletons or spinners to set expectations. +- **Populated state** — The standard view with data. Test with both minimal and full datasets. +- **Error state** — What happens when something fails? Show a clear message and a recovery path. +- **Edge cases** — What about a single item? Hundreds? An extremely long name that might overflow? + +Prototype each state explicitly — use local state toggles or tabs to let reviewers switch between them. + +### Use Realistic, Varied Data + +Mock data should stress-test the design, not just fill space: + +- Include **long names** that could wrap or overflow, **short names** that could look sparse, and **special characters**. +- Vary counts: 0 items, 1 item, a handful, and many (50+). Layouts that work for 5 items often break at 50. +- Include **missing optional fields** — not every record will be complete. +- Use **recognizable but realistic** content so reviewers can evaluate readability, not just layout. + +### Design for Interaction + +Prototypes should be clickable and stateful, not static mockups: + +- Wire up buttons, toggles, and form inputs with local state so reviewers experience the flow. +- Simulate async operations (e.g., a brief delay before showing a success toast) to prototype timing and feedback. +- Show what happens *after* an action — does a list update? Does a confirmation appear? Does the user navigate somewhere? + +### Establish Visual Hierarchy + +Guide the user's eye to what matters most: + +- **One primary action per view.** If everything is bold, nothing is. Use a primary button for the main action, secondary/ghost for the rest. +- **Group related information** with spacing and borders, not just proximity. +- **Size and weight signal importance.** Headings, subheadings, and body text should create a clear reading order. +- **Use whitespace deliberately** — it separates sections and reduces cognitive load. + +### Make Affordance Obvious + +Users should understand what they can do without instructions: + +- **Clickable elements should look clickable.** Buttons look like buttons, links look like links. +- **Destructive actions should look dangerous** — use red/warning styling and require confirmation. +- **Disabled states should be visually distinct** and ideally explain *why* they're disabled (tooltip or helper text). +- **Feedback should be immediate** — hover states, active states, and loading indicators tell the user the system responded. + +### Manage Information Density + +Show enough to be useful, hide enough to avoid overwhelm: + +- **Lead with a summary, offer detail on demand.** Use accordions, expandable rows, or drill-down views for secondary information. +- **Don't front-load every field.** Tables and lists should show the most important 3–5 columns; offer a detail view for the rest. +- **Use progressive disclosure** — reveal complexity as the user engages deeper (overview → detail → advanced settings). + +### Stay Consistent With the Product + +Before designing something new, check how the existing product handles similar patterns: + +- **Browse `apps/frontend/src/domain/`** for existing feature implementations. If a similar interaction exists, match its layout and behavior before inventing alternatives. +- **Reuse established patterns** — if the product uses a sidebar + main content layout for listings, don't prototype a card grid for the same type of data without good reason. +- **Follow the same information architecture** — similar actions in the same position, similar data in the same format. +- When diverging from existing patterns, call it out explicitly so reviewers can evaluate the change intentionally. + +## Running the Playground + +To start the playground dev server: + +```bash +nx dev playground +``` + +The app runs on **localhost:4300**. It is not part of the Docker Compose setup — it runs in isolation via Vite's dev server. + +## Creating a New Prototype + +### 1. Create the Prototype Directory + +Each prototype lives under `apps/playground/src/prototypes/`. For non-trivial prototypes, create a dedicated folder organized by domain — mirroring the frontend app structure. Consult `references/frontend-domain-structure.md` for the domain folder list. + +``` +apps/playground/src/prototypes/ +├── index.ts # Prototype registry +├── ButtonsPrototype.tsx # Simple single-file prototype +└── my-feature/ # Multi-component prototype + ├── MyFeaturePrototype.tsx # Root component (entry point) + ├── components/ + │ ├── domain-a/ + │ │ ├── SomeComponent.tsx + │ │ └── AnotherComponent.tsx + │ └── domain-b/ + │ └── SomethingElse.tsx + └── types.ts # Shared types for this prototype +``` + +For simple prototypes (e.g., showcasing a single component), a single file is acceptable. + +### 2. Build the Prototype Component + +Create a default-exported React component: + +```tsx +import { PMBox, PMHeading } from '@packmind/ui'; + +export default function MyFeaturePrototype() { + return ( + + My Feature + {/* Prototype content */} + + ); +} +``` + +### 3. Register the Prototype + +Add the prototype to `apps/playground/src/prototypes/index.ts`: + +```tsx +import MyFeaturePrototype from './my-feature/MyFeaturePrototype'; + +export const prototypes: Prototype[] = [ + // ... existing prototypes + { + name: 'My Feature', + description: 'Optional description', + component: MyFeaturePrototype, + }, +]; +``` + +The prototype will appear in the dropdown selector in the playground nav bar. + +## Mandatory Rules + +### Data + +- **Always use stub/mock data.** Never make actual calls to the backend. Define realistic mock data inline or in a dedicated `data.ts` file within the prototype folder. + +### Dependencies + +- **Never install new dependencies** without explicit user approval. +- **Never modify files outside `apps/playground/`.** No changes to other apps or packages. + +### Reusing Existing Code + +- Prototypes **can** import presentational components and types from the frontend app (`apps/frontend/src/`) and shared type packages (`packages/`). +- Prototypes **must not** import services, gateways, hooks with side effects, or anything that calls the backend. + +### UI Components + +- Use `PM*` components from `@packmind/ui` (e.g., `PMBox`, `PMButton`, `PMHeading`, `PMVStack`, `PMHStack`, `PMText`). +- When a needed component is not available in the Packmind UI kit, browse [Chakra UI v3 components](https://www.chakra-ui.com/docs/components) for reference, then map to the corresponding `PM*` wrapper before using. If no wrapper exists, ask the user before using the raw Chakra component. +- Icons come from `react-icons/lu` (Lucide icons, prefixed with `Lu`). + +### Code Quality + +- Prototypes **must** be production-ready in structure. Follow React best practices: split responsibility, create as many components as needed, organize by domain. +- Use `useState`, `useCallback`, `useMemo` for local state and performance. +- Define TypeScript types for all data structures. +- Keep components focused — each component should have a single responsibility. + +## Resources + +### references/ + +- `frontend-domain-structure.md` — Domain folder structure from the frontend app, to guide component organization in prototypes. \ No newline at end of file diff --git a/.opencode/skills/working-with-playground-app/references/frontend-domain-structure.md b/.opencode/skills/working-with-playground-app/references/frontend-domain-structure.md new file mode 100644 index 000000000..5f2fa6b80 --- /dev/null +++ b/.opencode/skills/working-with-playground-app/references/frontend-domain-structure.md @@ -0,0 +1,33 @@ +# Frontend Domain Structure + +The frontend app (`apps/frontend/src/`) organizes code by domain. Prototypes should mirror this structure when splitting components. + +## Domain Folders + +``` +apps/frontend/src/domain/ +├── accounts/ +├── change-proposals/ +├── deployments/ +├── editions/ +├── git/ +├── llm/ +├── organizations/ +├── recipes/ +├── rules/ +├── setup/ +├── skills/ +├── spaces/ +├── sse/ +└── standards/ +``` + +## Shared Folder + +Cross-domain presentational components and utilities live in `apps/frontend/src/shared/`. + +## Component Conventions + +- Presentational components are reusable across domains +- Each domain folder groups components, hooks, and types related to that domain +- Prototypes should follow the same domain-based organization when splitting into multiple components diff --git a/.opencode/skills/working-with-pm-design-kit/SKILL.md b/.opencode/skills/working-with-pm-design-kit/SKILL.md new file mode 100644 index 000000000..ebc9a0472 --- /dev/null +++ b/.opencode/skills/working-with-pm-design-kit/SKILL.md @@ -0,0 +1,341 @@ +--- +name: 'working-with-pm-design-kit' +description: 'This skill provides guidance for using the Packmind UI component library (@packmind/ui). It should be used when building or modifying frontend UI with PM-prefixed components, working with Chakra UI in the Packmind codebase, or when questions arise about available components, theming, or layout patterns. Triggers on mentions of PM components, @packmind/ui, Chakra UI usage, design kit, or frontend component implementation.' +--- + +# Working With the PM Design Kit + +## Overview + +The Packmind design kit (`@packmind/ui`) is a component library built on top of Chakra UI v3. All components are prefixed with `PM` and provide a consistent, themed API across the application. The source lives in `packages/ui/`. + +**Import pattern**: Always import from `@packmind/ui`, never from Chakra UI directly. + +```tsx +import { PMButton, PMBox, PMHeading, PMText } from '@packmind/ui'; +``` + +## Component Selection Guide + +Before reaching for a raw `
` or Chakra primitive, check if a PM component exists. Consult `references/component-catalog.md` for the full inventory organized by category. + +### Decision Flow + +1. **Need a layout container?** Use `PMBox`, `PMVStack`, `PMHStack`, `PMFlex`, or `PMGrid`. +2. **Need text?** Use `PMHeading` (with `level` prop for semantic h1–h6) or `PMText` (with `variant` and `color`). +3. **Need a button?** Use `PMButton` with the appropriate `variant`: `primary` for main actions, `secondary`/`ghost` for secondary, `danger` for destructive. +4. **Need user input?** Use `PMInput`, `PMTextArea`, `PMSelect`, `PMCheckbox`, `PMSwitch`, or `PMRadioGroup`. +5. **Need feedback?** Use `pmToaster` for transient messages, `PMAlert` for inline messages, `PMConfirmationModal` for destructive confirmations. +6. **Need an overlay?** Use `PMDialog` for modals, `PMPopover` for contextual info, `PMDrawer` for side panels. +7. **Need to show nothing?** Use `PMEmptyState` with title, description, icon, and an action button. +8. **Need loading placeholders?** Use `PMSkeleton` for content areas, `PMSpinner` for inline indicators. +9. **Need a color indicator?** Use `PMColorSwatch` to display a color sample. +10. **No PM wrapper exists?** Check Chakra UI v3 docs, then ask the user before using a raw Chakra component. + +## Compound Component Patterns + +Several PM components use Chakra's compound pattern with dot notation. Always use the compound API — do not try to reconstruct these with standalone elements. + +```tsx +// Dialog + + + + + + Title + + + {/* body */} + + + + +// Accordion + + + Section 1 + Content here + + + +// Timeline + + + + + + + + Event + Details + + + + +// Tabs (compound pattern — preferred for flexible tab layouts) + + + First Tab + Second Tab + + First content + Second content + +``` + +**Key compound components**: `PMDialog`, `PMAccordion`, `PMTimeline`, `PMCarousel`, `PMCopiable`, `PMSelect`, `PMMenu`, `PMTreeView`, `PMTabs`, `PMTabsCompound`. + +Always wrap overlays (dialogs, popovers, drawers) inside `PMPortal` to escape stacking context issues. + +## Layout Patterns + +### Spacing + +Use `gap` on stacks/grids for consistent spacing between children — never use margin on individual children to create gaps. + +```tsx + + Title + Description + +``` + +### Full-Height Layouts + +For layouts that fill the viewport, use `height="100vh"` on the root, `flex="1"` on the expanding section, and `minHeight={0}` on flex children that need to scroll. + +### Grid Layouts + +Use `PMGrid` with `gridTemplateColumns` for multi-panel layouts: + +```tsx + + Sidebar + Main + Detail + +``` + +### Page Structure + +Use `PMPage` for full-page layouts with title, breadcrumbs, actions, and optional sidebar. Use `PMPageSection` for collapsible content sections within a page. + +## Typography + +### Headings + +Use `PMHeading` with the `level` prop for semantic HTML (h1–h6) and `color` for emphasis: + +```tsx +Page Title +Section Title +``` + +Available colors: `primary`, `secondary`, `tertiary`, `faded`, `primaryLight`, `secondaryLight`, `tertiaryLight`. + +### Body Text + +Use `PMText` with `variant` for size and `color` for emphasis: + +```tsx +Main content +Supporting text +``` + +Variants: `body`, `body-important`, `small`, `small-important`. +Colors: `primary`, `secondary`, `tertiary`, `error`, `faded`, `warning`, `success`, `primaryLight`, `secondaryLight`, `tertiaryLight`. + +## Theming + +Use semantic tokens — never hardcode hex colors or raw Chakra palette values. + +### Semantic Token Categories + +| Category | Tokens | Usage | +|----------|--------|-------| +| Background | `background.primary`, `.secondary`, `.tertiary`, `.faded` | Surface colors (dark to light) | +| Text | `text.primary`, `.secondary`, `.tertiary`, `.faded`, `.error`, `.warning`, `.success` | Text contrast levels | +| Border | `border.primary`, `.secondary`, `.tertiary` | Border contrast levels | + +### Status Colors + +Use the semantic color names for status indicators: +- **Success**: `green` palette or `text.success` +- **Error/Danger**: `red` palette or `text.error` +- **Warning**: `orange` palette or `text.warning` +- **Info/Primary**: `blue` palette + +```tsx +Delete +Validation failed +Active +``` + +## Form Patterns + +### Input Fields + +`PMInput` provides label, error state, and helper text out of the box: + +```tsx + setName(e.target.value)} + error={errors.name} + helperText="Must be unique within the organization" + maxLength={255} +/> +``` + +### Form Layout + +Group related fields with `PMFormContainer`: + +```tsx + + + + Save + +``` + +### Validation + +Show errors directly on inputs via the `error` prop — this adds a red border and displays the message below the field. Disable submit buttons during async operations with `isLoading`. + +## Feedback Patterns + +### Toasts (Transient Notifications) + +```tsx +import { pmToaster } from '@packmind/ui'; + +pmToaster.create({ + type: 'success', // 'success' | 'error' | 'warning' | 'info' | 'loading' + title: 'Saved', + description: 'Your changes have been saved.', + closable: true, + action: { label: 'Undo', onClick: handleUndo }, // optional +}); +``` + +### Confirmation Modals (Destructive Actions) + +```tsx +Delete} + title="Delete project?" + message="This action cannot be undone." + confirmText="Delete" + confirmColorScheme="red" + onConfirm={handleDelete} + isLoading={isDeleting} +/> +``` + +### Inline Alerts + +```tsx + + + Attention + This feature is in beta. + +``` + +### Empty States + +```tsx +} +> + Create Standard + +``` + +## Icons + +Icons come from `react-icons/lu` (Lucide icon set). Import with the `Lu` prefix: + +```tsx +import { LuTrash2, LuPlus, LuChevronDown } from 'react-icons/lu'; + + Add Item + +``` + +Control size via `fontSize` or `size` props on the icon element. + +## Responsive Design + +Use Chakra's responsive object syntax with breakpoints `base`, `sm`, `md`, `lg`, `xl`: + +```tsx + +``` + +Mobile-first approach: `base` styles apply to all sizes, then override at larger breakpoints. + +## Button Variant Guide + +| Variant | Usage | +|---------|-------| +| `primary` | Main action on the page (one per view) | +| `secondary` | Important but not primary actions | +| `tertiary` | Low-emphasis actions | +| `outline` | Alternative to secondary with border emphasis | +| `ghost` | Minimal actions (toolbar buttons, inline actions) | +| `success` | Positive confirmations | +| `warning` | Caution-required actions | +| `danger` | Destructive actions (delete, remove) | + +## Hooks + +`@packmind/ui` exports several hooks for common UI patterns: + +### useTableSort + +Manages sorting state for `PMTable`. Returns `sortKey`, `sortDirection`, `handleSort`, and `getSortDirection`: + +```tsx +import { useTableSort } from '@packmind/ui'; + +const { sortKey, sortDirection, handleSort, getSortDirection } = useTableSort({ + defaultSortKey: 'name', + defaultSortDirection: 'asc', +}); + + +``` + +### Chakra Re-exports + +- **pmUseFilter** — Chakra's `useFilter` for filtering collections +- **pmUseListCollection** — Chakra's `useListCollection` for managing list data (useful with `PMSelect`, `PMCombobox`) +- **pmUseToken** — Chakra's `useToken` for accessing design tokens programmatically + +```tsx +import { pmUseToken, pmUseListCollection } from '@packmind/ui'; +``` + +## Anti-Patterns + +- **Do not** import from `@chakra-ui/react` directly — always use `@packmind/ui` wrappers. +- **Do not** use inline styles or hardcoded colors — use semantic tokens and component props. +- **Do not** create custom modal/overlay implementations — use `PMDialog`, `PMDrawer`, or `PMPopover` with `PMPortal`. +- **Do not** build custom loading indicators — use `PMSkeleton` or `PMSpinner`. +- **Do not** use `as="h1"` on headings — use the `level` prop on `PMHeading` for semantic HTML. + +## Resources + +### references/ + +- `component-catalog.md` — Full inventory of all PM components and hooks with props, organized by category. \ No newline at end of file diff --git a/.opencode/skills/working-with-pm-design-kit/references/component-catalog.md b/.opencode/skills/working-with-pm-design-kit/references/component-catalog.md new file mode 100644 index 000000000..01caa5ae0 --- /dev/null +++ b/.opencode/skills/working-with-pm-design-kit/references/component-catalog.md @@ -0,0 +1,118 @@ +# PM Component Catalog + +Complete inventory of all PM-prefixed components in `@packmind/ui`, organized by category. Source: `packages/ui/src/lib/components/`. + +## Typography + +| Component | Key Props | Notes | +|-----------|-----------|-------| +| **PMHeading** | `level?: 'h1'–'h6'`, `color?: 'primary'\|'secondary'\|'tertiary'\|'faded'\|'primaryLight'\|'secondaryLight'\|'tertiaryLight'` | Use `level` for semantic HTML, not `as` | +| **PMText** | `variant?: 'body'\|'body-important'\|'small'\|'small-important'`, `color?: 'primary'\|'secondary'\|'tertiary'\|'error'\|'faded'\|'warning'\|'success'\|'primaryLight'\|'secondaryLight'\|'tertiaryLight'`, `as?: 'span'\|'p'\|'div'` | | +| **PMLink** | `variant?: 'plain'\|'navbar'\|'underline'\|'active'`, `to?: string` | Plain by default | +| **PMEm** | Chakra EmProps | Emphasis/italic text | +| **PMList** | Chakra ListProps | Ordered/unordered lists | + +## Form Controls + +| Component | Key Props | Notes | +|-----------|-----------|-------| +| **PMInput** | `label?: string`, `error?: string`, `helperText?: string`, `maxLength?: number` (default: 255) | Tertiary background, transparent border until error | +| **PMTextArea** | Chakra TextareaProps | Tertiary background | +| **PMLabel** | `required?: boolean`, `htmlFor?: string` | Renders `