diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000000..a9858f51c2 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,77 @@ +--- +applyTo: "**" +--- + +# OUDS Web — AI Agent Instructions + +You are working in **OUDS Web** (Orange Unified Design System — Web), a multi-brand design system built as a fork of Bootstrap 5.3.6. +Version: 1.1.0 | Main branch: `ouds/main` | Brands: Orange, Sosh, Orange Compact + +--- + +## Standards — Apply Always + +The following standards define mandatory conventions. Always apply them when writing or reviewing code: + +- **[Code Conventions](.packmind/standards/ouds-code-conventions.md)** — HTML/SCSS/JS style rules: `!default` on variables, forbidden direct properties (`border-radius`, `transition`), forbidden values (`border: none`, `lighten()`), token usage, JS no-semicolons, template literals. + +- **[Accessibility WCAG 2.1 AA](.packmind/standards/ouds-accessibility-wcag.md)** — Non-negotiable: `@include focus-visible()`, ARIA attributes, `.visually-hidden`, keyboard navigation, 4.5:1 contrast, 44×44px touch targets, RTL support. + +- **[Design Token System](.packmind/standards/ouds-design-tokens.md)** — 3-tier hierarchy (raw → semantic → component). Never edit auto-generated files (`_raw.scss`, `_semantic.scss`, `_component.scss`, `_*-custom-props.scss`). Colors via `var(--#{$prefix}color-*)`. New tokens in all 3 brands. + +- **[Component Patterns](.packmind/standards/ouds-component-patterns.md)** — CSS custom property declaration at top of class, state overrides via variable overrides, `scss-docs-start/end` markers, `// OUDS mod:` comments, JS BaseComponent pattern. + +--- + +## Commands — Use for Specific Workflows + +When the user asks to perform a specific task, load and follow the appropriate command: + +- **[ouds-create-component](.packmind/commands/ouds-create-component.md)** — Full step-by-step guide for creating a new SCSS/JS component (SCSS structure, tokens per brand, ARIA, JS boilerplate, tests, docs). + +- **[ouds-diagnose-error](.packmind/commands/ouds-diagnose-error.md)** — Diagnostic workflow for Stylelint, ESLint, Sass build, CI, token, JS test, and Pa11y errors. + +- **[ouds-decision-routing](.packmind/commands/ouds-decision-routing.md)** — 4 decision trees (where to put code, which token, multi-brand updates, testing strategy). + +- **[ouds-lookup](.packmind/commands/ouds-lookup.md)** — Quick lookup index: maps any topic to the right standard, command, or skill. + +- **[ouds-validate-tokens](.packmind/commands/ouds-validate-tokens.md)** — Read-only audit: cross-brand token presence check and anti-pattern detection for SCSS component files. + +--- + +## Skills — Domain Knowledge + +Load these skills when deep conceptual understanding is needed: + +- **[ouds-token-strategy](.packmind/skills/ouds-token-strategy.md)** — Full token architecture: pipeline, layer hierarchy, CSS custom property bridge for dark mode, color token dual-track, consumption patterns. Load when asked about tokens, dark mode, or brand differentiation. + +- **[ouds-multi-brand-sync](.packmind/skills/ouds-multi-brand-sync.md)** — 3-brand architecture: what is shared, what differs, when to update all brands, brand entry point pattern, testing multi-brand changes. + +- **[ouds-knowledge-base](.packmind/skills/ouds-knowledge-base.md)** — Full glossary (154 terms), build pipeline, npm scripts reference, CI/CD jobs, release process, and project file map. Load when encountering unfamiliar terms or working on build/infra. + +--- + +## Critical Constraints (Always Active) + +1. **Never hardcode** colors (`#ff7900`), spacing (`16px`), or dimensions — use OUDS tokens. +2. **Never use `border-radius: X` or `transition: X` directly** — use `@include border-radius()` / `@include transition()`. +3. **Never edit auto-generated token files**: `_raw.scss`, `_semantic.scss`, `_component.scss`, `_*-custom-props.scss` — only `_composite.scss` is editable. +4. **Never commit `dist/`** files — they are build artifacts. +5. **Never put JavaScript** in `packages//` — JS is shared via `js/src/`. +6. **Color tokens for dark mode** → always `var(--#{$prefix}color-*)`, never the SCSS variable directly. +7. **Accessibility**: never remove `:focus-visible` styles, always add ARIA attributes to interactive components, never use `display: none` for screen-reader content. + +--- + +## Project Quick Facts + +| | | +|---|---| +| CSS prefix | `--bs-` (via `$prefix` in `scss/_config.scss`) | +| Brands | orange, sosh, orange-compact | +| JS components | 15 (all extend `BaseComponent`) | +| Token layers | raw → semantic → composite → component → CSS custom props | +| Build | `npm run dist` (CSS + JS) | +| Lint | `npm run lint` | +| Tests | `npm run test` | +| Dev servers | `:9001` (orange), `:9002` (sosh), `:9003` (orange-compact) | diff --git a/.github/skills/packmind-cli-list-commands/LICENSE.txt b/.github/skills/packmind-cli-list-commands/LICENSE.txt new file mode 100644 index 0000000000..f433b1a53f --- /dev/null +++ b/.github/skills/packmind-cli-list-commands/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/.github/skills/packmind-cli-list-commands/README.md b/.github/skills/packmind-cli-list-commands/README.md new file mode 100644 index 0000000000..de94fe1d00 --- /dev/null +++ b/.github/skills/packmind-cli-list-commands/README.md @@ -0,0 +1,26 @@ +# Packmind CLI List Commands + +A reference skill that helps AI coding agents discover available standards, commands, skills, and packages via the Packmind CLI. + +## What This Skill Provides + +Quick reference for all CLI listing commands: +- `packmind-cli standards list` - List coding standards +- `packmind-cli commands list` - List reusable commands +- `packmind-cli skills list` - List available skills +- `packmind-cli install --list` - List available packages + +## How to Use + +The AI agent will automatically use this skill when it needs to discover available artifacts in the Packmind organization. + +## Prerequisites + +Before using these commands, ensure you have: + +- **packmind-cli**: Required for all commands +- **Packmind account**: Login via `packmind-cli login` + +## License + +Apache 2.0 - See LICENSE.txt for details. diff --git a/.github/skills/packmind-cli-list-commands/SKILL.md b/.github/skills/packmind-cli-list-commands/SKILL.md new file mode 100644 index 0000000000..de2afff72c --- /dev/null +++ b/.github/skills/packmind-cli-list-commands/SKILL.md @@ -0,0 +1,53 @@ +--- +name: 'packmind-cli-list-commands' +description: 'Reference for Packmind CLI listing commands. This skill should be used when an agent needs to discover available standards, commands, or skills in the Packmind organization.' +license: 'Complete terms in LICENSE.txt' +--- + +# Packmind CLI List Commands + +List available Packmind artifacts (standards, commands, skills, packages) via the CLI. + +## IMPORTANT: Output Requirements + +When presenting results to the user, you MUST: +1. **Run the CLI command** using the Bash tool +2. **Preserve the full URLs** from the CLI output - these are clickable links to the Packmind webapp +3. **Display results as a list** showing slug, name, and the full URL for each item +4. **Never summarize or table-ify** the output in a way that hides the URLs + +Example output format to show the user: +``` +## Standards (3) + +- **my-standard-slug** + Name: My Standard Name + Link: https:///org/myorg/space/global/standards/abc123/summary + +- **another-standard** + Name: Another Standard + Link: https:///org/myorg/space/global/standards/def456/summary +``` + +## Commands Reference + +| Command | Purpose | +|---------|---------| +| `packmind-cli standards list` | List coding standards | +| `packmind-cli commands list` | List reusable commands | +| `packmind-cli skills list` | List available skills | +| `packmind-cli install --list` | List available packages | + +## Prerequisites + +Ensure packmind-cli is authenticated before running commands: + +```bash +packmind-cli whoami +``` + +If not logged in, authenticate first: + +```bash +packmind-cli login +``` diff --git a/.github/skills/packmind-create-command/LICENSE.txt b/.github/skills/packmind-create-command/LICENSE.txt new file mode 100644 index 0000000000..f433b1a53f --- /dev/null +++ b/.github/skills/packmind-create-command/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/.github/skills/packmind-create-command/README.md b/.github/skills/packmind-create-command/README.md new file mode 100644 index 0000000000..0390263384 --- /dev/null +++ b/.github/skills/packmind-create-command/README.md @@ -0,0 +1,37 @@ +# Command Creator + +A skill that guides AI coding agents through the process of creating reusable commands via the Packmind CLI. + +## What is a Command? + +Commands are structured, multi-step workflows that capture repeatable tasks, recipes, and automation patterns. They enable AI coding agents to execute complex tasks consistently following your team's established workflows. + +## How to Use + +Ask the AI agent to create a command. The agent will automatically use this skill to guide the process. + +### Example Prompts + +- "Create a command for setting up a new API endpoint" +- "Help me build a command that guides creating React components" +- "I want to create a command for our deployment workflow" +- "Create a new command for database migration setup" + +The AI agent will: + +1. Ask clarifying questions to understand the command's purpose +2. Help you define steps with proper formatting +3. Draft a markdown file for review +4. Get your approval before submission +5. Convert to JSON and run the CLI command to create the command + +## Prerequisites + +Before using this skill, ensure you have: + +- **packmind-cli**: Required for command creation +- **Packmind account**: Login via `packmind-cli login` + +## License + +Apache 2.0 - See LICENSE.txt for details. diff --git a/.github/skills/packmind-create-command/SKILL.md b/.github/skills/packmind-create-command/SKILL.md new file mode 100644 index 0000000000..ece56f9fd4 --- /dev/null +++ b/.github/skills/packmind-create-command/SKILL.md @@ -0,0 +1,347 @@ +--- +name: 'packmind-create-command' +description: 'Guide for creating reusable commands via the Packmind CLI. This skill should be used when users want to create a new command that captures multi-step workflows, recipes, or task automation for distribution to CoPilot.' +license: 'Complete terms in LICENSE.txt' +--- + +# Command Creator + +This skill provides a complete walkthrough for creating reusable commands via the Packmind CLI. + +## About Commands + +Commands are structured, multi-step workflows that capture repeatable tasks, recipes, and automation patterns. They help teams standardize common development workflows and enable CoPilot to execute complex tasks consistently. + +### What Commands Provide + +1. **Multi-step workflows** - Structured sequences of actions to accomplish a task +2. **Context validation** - Checkpoints to ensure requirements are met before execution +3. **When-to-use guidance** - Clear scenarios describing when the command is applicable +4. **Code snippets** - Optional examples demonstrating each step's implementation + +### Command Structure + +Every command is drafted as a markdown file with this structure: + +``` +# Command Name + +## Summary + +What the command does, why it's useful, and when it's relevant. + +## When to Use + +- Scenario 1 when this command applies +- Scenario 2 when this command applies + +## Context Validation Checkpoints + +- Question 1 to validate before proceeding? +- Question 2 to ensure context is clear? + +## Steps + +### Step Name + +What this step does and how to implement it. + +\`\`\`typescript +// Optional code example +\`\`\` + +### Another Step + +Description without code. +``` + +### Naming Guidelines + +The `# Title` heading is the **display name** shown in indexes and dashboards. The slug is auto-generated from it — never write the slug yourself. + +**Format:** Use **Title Case with spaces** — natural language, not a slug. +- Capitalize each significant word +- **Start with an action verb** (e.g., "Create", "Setup", "Configure") +- Use spaces between words, never hyphens or underscores +- Be descriptive and specific (2–5 words) + +**Examples:** +- Good: `"Create API Endpoint"`, `"Setup Database Migration"`, `"Configure CI Pipeline"` +- Bad: `"api-endpoint"` (slug format — use Title Case with spaces) +- Bad: `"setup migration"` (not Title Case) +- Bad: `"create-api-endpoint"` (slug format) + +### Markdown Structure Requirements + +The CLI validates the command after conversion. Ensure the markdown file meets these requirements: + +- **`# Title`**: Non-empty Title Case string starting with an action verb, descriptive and specific (2–5 words, e.g., "Create API Endpoint") +- **`## Summary`**: Non-empty string describing intent, value, and relevance +- **`## When to Use`**: At least one bullet item (non-empty strings) +- **`## Context Validation Checkpoints`**: At least one bullet item (non-empty strings) +- **`## Steps`**: At least one step subsection +- **`### Step Name`**: Non-empty string (step title) +- **Step body paragraph**: Non-empty string (implementation details) +- **Step body code block** (optional): Code fenced with language identifier (e.g., \`\`\`typescript) + +## Prerequisites + +Before creating a command, verify that packmind-cli is available: + +Check if packmind-cli is installed: + +```bash +packmind-cli --version +``` + +If not available, install it: + +```bash +npm install -g @packmind/cli +``` + +Then login to Packmind: + +```bash +packmind-cli login +``` + +## Command Creation Process + +### Step 1: Understanding the Command's Purpose + +Skip this step only when the command's workflow and steps are already clearly defined. + +To create an effective command, clearly understand: + +1. **What workflow does this command automate?** + - Example: "Setting up a new API endpoint with tests" + - Example: "Creating a new React component with proper structure" + +2. **When should this command be triggered?** + - Specific scenarios (e.g., "When adding a new feature") + - Specific contexts (e.g., "After creating a domain entity") + +Example clarifying questions: + +- "What multi-step workflow do you want to automate?" +- "What scenarios should trigger this command?" +- "What context needs to be validated before running this workflow?" + +### Step 2: Design Command in Markdown + +Transform the understanding from Step 1 into a complete markdown draft with steps and validation checkpoints. + +#### Draft Creation + +1. Create a draft markdown file in `.packmind/commands/_drafts/` (create the folder if missing) using filename `.md` (lowercase with hyphens) +2. Draft structure: + - `# ` (Title Case, action-verb prefix, 2–5 words) + - `## Summary` — what the command does, why it's useful, and when it's relevant + - `## When to Use` — bullet list of specific scenarios + - `## Context Validation Checkpoints` — bullet list of validation questions + - `## Steps` — each step as a `### ` subsection following the Step Writing Guidelines below + - For each step that benefits from a code example, add a language-annotated code block + +This draft file is the **only** file created during drafting — no separate files are needed. + +#### Step Writing Guidelines + +1. **Clear name** - Use a concise title (e.g., "Setup Dependencies", "Create Test File") +2. **Actionable description** - Explain what to do and how to implement it +3. **One concept per step** - Focus on a single action +4. **Optional code snippet** - Include when it clarifies the implementation + +**Good descriptions:** +- "Create a new file at \`src/components/{ComponentName}.tsx\` with the basic component structure including props interface and default export" + +**Bad descriptions:** +- "Create file" (too vague) + +#### Context Validation Checkpoints + +Questions that verify requirements before execution: + +**Good checkpoints:** +- "Is the component name and location specified?" +- "Are the API endpoint requirements (method, path, payload) defined?" + +**Bad checkpoints:** +- "Ready to start?" (doesn't validate anything) + +#### When-To-Use Scenarios + +Define specific, actionable scenarios: + +**Good scenarios:** +- "When adding a new REST endpoint to the API" +- "After creating a new domain entity that needs persistence" + +**Bad scenarios:** +- "When coding" (too broad) + +### Step 3: Review Before Submission + +**Before running the CLI command**, you MUST get explicit user approval: + +1. Show the user the complete command content in a formatted preview: + - Name + - Summary + - When to use scenarios + - Context validation checkpoints + - Each step with name, description, and code snippet (if any) + +2. **Provide the file path** to the markdown file (`.packmind/commands/_drafts/.md`) so users can open and edit it directly if needed. + +3. Ask: **"Here is the command that will be created on Packmind. The draft file is at \`\` if you want to review or edit it. Do you approve?"** + +4. **Wait for explicit user confirmation** before proceeding to Step 4. + +5. If the user requests changes, go back to earlier steps to make adjustments. + +### Step 4: Confirm and Submit + +1. **Re-read the markdown file** from disk to capture any user edits. + +2. **Compare with the original content** you created in Step 2. + +3. **If changes were detected**: + - Display the formatted preview again (same format as Step 3) + - Ask: **"The file was modified. Here is the updated content that will be sent. Do you confirm?"** + - **Wait for explicit confirmation** before proceeding. + +4. **If no changes**: Proceed directly to submission. + +5. **Convert the markdown to JSON** using these conversion rules: + - `# heading` → `name` + - `## Summary` content → `summary` + - `## When to Use` bullet items → `whenToUse[]` + - `## Context Validation Checkpoints` bullet items → `contextValidationCheckpoints[]` + - Each `### ...` under `## Steps` → step `name`, paragraph text → `description`, code block → `codeSnippet` (wrapped in markdown code fences with language identifier) + +6. Pipe the JSON directly to the CLI via stdin using a heredoc (no intermediate file needed): + +```bash +packmind-cli commands create --origin-skill packmind-create-command <<'EOF' +{"name":"...","summary":"...","whenToUse":[...],"contextValidationCheckpoints":[...],"steps":[...]} +EOF +``` + +Expected output on success: +``` +packmind-cli Command "Your Command Name" created successfully (ID: ) +View it in the webapp: +``` + +#### Troubleshooting + +**"Not logged in" error:** +```bash +packmind-cli login +``` + +**"Failed to resolve global space" error:** +- Verify your API key is valid +- Check network connectivity to Packmind server + +**Validation errors:** +- Ensure all required sections are present in the markdown file +- Check that the `## Steps` section has at least one `###` step subsection +- Verify code blocks have language annotations + +### Step 5: Cleanup + +After the command is **successfully created**, delete the draft markdown file in `.packmind/commands/_drafts/`. + +**Only clean up on success** - if the CLI command fails, keep the files so the user can retry. + +### Step 6: Offer to Add to Package + +After successful creation, check if the command fits an existing package: + +1. Run `packmind-cli install --list` to get available packages +2. If no packages exist, skip this step silently and end the workflow +3. Analyze the created command's name and summary against each package's name and description +4. If a package is a clear semantic fit (the command's domain/technology aligns with the package's purpose): + - Present to user: "This command seems to fit the `` package." + - Offer three options: + - Add to `` + - Choose a different package + - Skip +5. If no clear fit is found, skip silently (do not mention packages) +6. If user chooses to add: + - Run: `packmind-cli packages add --to --command ` + - Ask: "Would you like me to run `packmind-cli install` to sync the changes?" + - If yes, run: `packmind-cli install` + +## Complete Example + +Here's a complete example creating a command for setting up a new API endpoint: + +**File: .packmind/commands/_drafts/create-api-endpoint.md** +```markdown +# Create API Endpoint + +## Summary + +Set up a new REST API endpoint with controller, service, and tests following the hexagonal architecture pattern. + +## When to Use + +- When adding a new REST endpoint to the API +- When implementing a new backend feature that exposes HTTP endpoints + +## Context Validation Checkpoints + +- Is the HTTP method and path defined (e.g., POST /users)? +- Is the request/response payload structure specified? +- Is the associated use case or business logic identified? + +## Steps + +### Create Controller + +Create the controller file in the \`infra/http/controllers/\` directory with the endpoint handler and input validation. + +\`\`\`typescript +@Controller('users') +export class UsersController { + @Post() + async create(@Body() dto: CreateUserDTO) { + return this.useCase.execute(dto); + } +} +\`\`\` + +### Create Use Case + +Create the use case in the \`application/useCases/\` directory implementing the business logic. + +### Create Tests + +Create unit tests for the controller and use case in their respective \`.spec.ts\` files following the Arrange-Act-Assert pattern. + +### Register in Module + +Add the controller and use case to the appropriate NestJS module's \`controllers\` and \`providers\` arrays. +``` + +**Creating the command (piped via stdin):** +```bash +packmind-cli commands create --origin-skill packmind-create-command <<'EOF' +{"name":"Create API Endpoint","summary":"Set up a new REST API endpoint...","whenToUse":[...],"contextValidationCheckpoints":[...],"steps":[...]} +EOF +``` + +## Quick Reference + +| Section | Required | Description | +|---|---|---| +| `# Title` | Yes | Title Case, action-verb prefix, 2–5 words | +| `## Summary` | Yes | What, why, and when (one sentence) | +| `## When to Use` | Yes | Bullet list, at least one scenario | +| `## Context Validation Checkpoints` | Yes | Bullet list, at least one checkpoint | +| `## Steps` | Yes | Contains step subsections | +| `### Step Name` | Yes (≥1) | Step title | +| Step body (paragraph) | Yes | Implementation details | +| Step body (code block) | No | Markdown code block with language | diff --git a/.github/skills/packmind-create-package/LICENSE.txt b/.github/skills/packmind-create-package/LICENSE.txt new file mode 100644 index 0000000000..f433b1a53f --- /dev/null +++ b/.github/skills/packmind-create-package/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/.github/skills/packmind-create-package/README.md b/.github/skills/packmind-create-package/README.md new file mode 100644 index 0000000000..8ec1ccc9a7 --- /dev/null +++ b/.github/skills/packmind-create-package/README.md @@ -0,0 +1,34 @@ +# Package Creator + +A skill that guides AI coding agents through the process of creating Packmind packages via the CLI. + +## What is a Package? + +Packages are logical collections of standards, commands, and skills that can be distributed together. They help organize artifacts by technology, domain, team, or architectural layer. + +## How to Use + +Ask the AI agent to create a package. The agent will automatically use this skill to guide the process. + +### Example Prompts + +- "Create a package for our frontend standards" +- "Help me create a backend package" +- "I want to create a package for our NestJS conventions" + +The AI agent will: + +1. List existing packages to check naming conventions +2. Confirm the package name and description with you +3. Run the CLI command to create the package + +## Prerequisites + +Before using this skill, ensure you have: + +- **packmind-cli**: Required for package creation +- **Packmind account**: Login via `packmind-cli login` + +## License + +Apache 2.0 - See LICENSE.txt for details. diff --git a/.github/skills/packmind-create-package/SKILL.md b/.github/skills/packmind-create-package/SKILL.md new file mode 100644 index 0000000000..8983c50a51 --- /dev/null +++ b/.github/skills/packmind-create-package/SKILL.md @@ -0,0 +1,103 @@ +--- +name: 'packmind-create-package' +description: 'Guide for creating Packmind packages via the CLI. This skill should be used when users want to create a new package to organize standards, commands, and skills for distribution.' +license: 'Complete terms in LICENSE.txt' +--- + +# Package Creator + +Create Packmind packages—logical collections of standards, commands, and skills that can be distributed together. + +## About Packages + +A **Package** groups related artifacts by technology, domain, team, or architectural layer. Instead of managing individual items, packages let you distribute related content as a single unit. + +Examples: `frontend`, `backend-api`, `nestjs`, `e2e` + +## Prerequisites + +Verify packmind-cli is available: + +```bash +packmind-cli --version +``` + +If not installed: + +```bash +npm install -g @packmind/cli +packmind-cli login +``` + +## Workflow + +### Step 1: Check Existing Packages + +List existing packages to identify naming conventions: + +```bash +packmind-cli install --list +``` + +Review the output to: +- Avoid duplicate or conflicting names +- Follow existing naming conventions (lowercase, kebab-case slugs) +- Understand how packages are organized in this workspace + +### Step 2: Confirm with User + +Before creating, confirm the package details: + +``` +Package name: +Description: + +Proceed? +``` + +Wait for explicit user approval. + +### Step 3: Create the Package + +Run the CLI command: + +```bash +packmind-cli packages create "" --description="" +``` + +Or without description: + +```bash +packmind-cli packages create "" +``` + +### Expected Output + +On success: + +``` +Created: +You can see it at: https:///packages/ +You can install it with: packmind-cli packages install +``` + +## Naming Guidelines + +- **Name**: Human-readable, can include spaces (e.g., "Backend API") +- **Slug**: Auto-generated from name, lowercase with hyphens (e.g., "backend-api") +- **Collision handling**: If slug exists, server auto-increments (e.g., "frontend-2") + +## Troubleshooting + +| Error | Solution | +|-------|----------| +| "Not authenticated" | Run `packmind-cli login` | +| "Network error" | Check connection, retry | +| "Name must be at least 3 characters" | Use a longer name | + +## Next Steps + +After creating a package, content can be added via: + +1. **MCP tools**: Use `packageSlugs` parameter when creating standards/commands +2. **Web interface**: Navigate to the package URL and add items manually diff --git a/.github/skills/packmind-create-skill/LICENSE.txt b/.github/skills/packmind-create-skill/LICENSE.txt new file mode 100644 index 0000000000..f433b1a53f --- /dev/null +++ b/.github/skills/packmind-create-skill/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/.github/skills/packmind-create-skill/README.md b/.github/skills/packmind-create-skill/README.md new file mode 100644 index 0000000000..373d0d166e --- /dev/null +++ b/.github/skills/packmind-create-skill/README.md @@ -0,0 +1,53 @@ +# Create skill + +A skill that guides AI coding agents through the process of creating effective skills. + +## What is a Skill? + +Skills are modular, self-contained packages that extend AI coding agents' capabilities by providing specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific domains or tasks. + +## How to Use + +Simply ask the AI agent to create a skill. The agent will automatically use this skill to guide the process. + +### Example Prompts + +- "Create a skill for working with PDF files" +- "Help me build a skill that guides API integration with our backend" +- "I want to create a skill for our team's coding standards" +- "Create a new skill about adding CLI commands to the project" + +The AI agent will: + +1. Ask clarifying questions to understand the skill's purpose +2. Initialize the skill structure using the bundled scripts +3. Guide you through editing the SKILL.md content +4. Validate the skill before distribution +5. Help you distribute it via packmind-cli + +## Prerequisites + +Before using this skill, ensure you have: + +- **Python 3**: Required for skill initialization and validation +- **packmind-cli**: Required for skill distribution + +## Directory Structure + +``` +create-skill/ +├── SKILL.md # Instructions for the AI agent +├── README.md # This file (for humans) +├── LICENSE.txt # Apache 2.0 license +└── scripts/ + ├── init_skill.py # Initialize a new skill from template + └── quick_validate.py # Validate skill structure +``` + +## Attribution + +This skill is based on the original [skill-creator](https://github.com/anthropics/skills/tree/main/skills/skill-creator) from Anthropic's skills repository. + +## License + +Apache 2.0 - See LICENSE.txt for details. diff --git a/.github/skills/packmind-create-skill/SKILL.md b/.github/skills/packmind-create-skill/SKILL.md new file mode 100644 index 0000000000..b0c70d8a4d --- /dev/null +++ b/.github/skills/packmind-create-skill/SKILL.md @@ -0,0 +1,279 @@ +--- +name: 'packmind-create-skill' +description: 'Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends CoPilot''s capabilities with specialized knowledge, workflows, or tool integrations.' +license: 'Complete terms in LICENSE.txt' +--- + +# Create skill + +This skill provides guidance for creating effective skills. + +## About Skills + +Skills are modular, self-contained packages that extend CoPilot's capabilities by providing +specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific +domains or tasks—they transform CoPilot from a general-purpose agent into a specialized agent +equipped with procedural knowledge that no model can fully possess. + +### What Skills Provide + +1. Specialized workflows - Multi-step procedures for specific domains +2. Tool integrations - Instructions for working with specific file formats or APIs +3. Domain expertise - Company-specific knowledge, schemas, business logic +4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks + +### Anatomy of a Skill + +Every skill consists of a required SKILL.md file and optional bundled resources: + +``` +skill-name/ +├── SKILL.md (required) +│ ├── YAML frontmatter metadata (required) +│ │ ├── name: (required) +│ │ └── description: (required) +│ └── Markdown instructions (required) +└── Bundled Resources (optional) + ├── scripts/ - Executable code (Python/Bash/etc.) + ├── references/ - Documentation intended to be loaded into context as needed + └── assets/ - Files used in output (templates, icons, fonts, etc.) +``` + +#### SKILL.md (required) + +**Metadata Quality:** The `name` and `description` in YAML frontmatter determine when CoPilot will use the skill. Be specific about what the skill does and when to use it. Use the third-person (e.g. "This skill should be used when..." instead of "Use this skill when..."). + +#### Bundled Resources (optional) + +##### Scripts (`scripts/`) + +Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten. + +- **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed +- **Example**: `scripts/rotate_pdf.py` for PDF rotation tasks +- **Benefits**: Token efficient, deterministic, may be executed without loading into context +- **Note**: Scripts may still need to be read by CoPilot for patching or environment-specific adjustments + +##### References (`references/`) + +Documentation and reference material intended to be loaded as needed into context to inform CoPilot's process and thinking. + +- **When to include**: For documentation that CoPilot should reference while working +- **Examples**: `references/finance.md` for financial schemas, `references/mnda.md` for company NDA template, `references/policies.md` for company policies, `references/api_docs.md` for API specifications +- **Use cases**: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides +- **Benefits**: Keeps SKILL.md lean, loaded only when CoPilot determines it's needed +- **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md +- **Avoid duplication**: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files. + +##### Assets (`assets/`) + +Files not intended to be loaded into context, but rather used within the output CoPilot produces. + +- **When to include**: When the skill needs files that will be used in the final output +- **Examples**: `assets/logo.png` for brand assets, `assets/slides.pptx` for PowerPoint templates, `assets/frontend-template/` for HTML/React boilerplate, `assets/font.ttf` for typography +- **Use cases**: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified +- **Benefits**: Separates output resources from documentation, enables CoPilot to use files without loading them into context + +### Progressive Disclosure Design Principle + +Skills use a three-level loading system to manage context efficiently: + +1. **Metadata (name + description)** - Always in context (~100 words) +2. **SKILL.md body** - When skill triggers (<5k words) +3. **Bundled resources** - As needed by CoPilot (Unlimited\*) + +\*Unlimited because scripts can be executed without reading into context window. + +## Prerequisites + +Before running any skill scripts, verify that the required tools are available: + +### Python 3 + +Check if Python 3 is installed: + +```bash +python3 --version +``` + +If not available, install it: +- **macOS**: `brew install python3` +- **Ubuntu/Debian**: `sudo apt-get install python3` +- **Windows**: Download from https://python.org or use `winget install Python.Python.3` + +### Packmind CLI + +Check if packmind-cli is installed: + +```bash +packmind-cli --version +``` + +If not available, install it: + +```bash +npm install -g packmind-cli +``` + +## Skill Creation Process + +To create a skill, follow the "Skill Creation Process" in order, skipping steps only if there is a clear reason why they are not applicable. + +### Step 1: Understanding the Skill with Concrete Examples + +Skip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill. + +To create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback. + +For example, when building an image-editor skill, relevant questions include: + +- "What functionality should the image-editor skill support? Editing, rotating, anything else?" +- "Can you give some examples of how this skill would be used?" +- "I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?" +- "What would a user say that should trigger this skill?" + +To avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness. + +Conclude this step when there is a clear sense of the functionality the skill should support. + +### Step 2: Planning the Reusable Skill Contents + +To turn concrete examples into an effective skill, analyze each example by: + +1. Considering how to execute on the example from scratch +2. Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly + +Example: When building a `pdf-editor` skill to handle queries like "Help me rotate this PDF," the analysis shows: + +1. Rotating a PDF requires re-writing the same code each time +2. A `scripts/rotate_pdf.py` script would be helpful to store in the skill + +Example: When designing a `frontend-webapp-builder` skill for queries like "Build me a todo app" or "Build me a dashboard to track my steps," the analysis shows: + +1. Writing a frontend webapp requires the same boilerplate HTML/React each time +2. An `assets/hello-world/` template containing the boilerplate HTML/React project files would be helpful to store in the skill + +Example: When building a `big-query` skill to handle queries like "How many users have logged in today?" the analysis shows: + +1. Querying BigQuery requires re-discovering the table schemas and relationships each time +2. A `references/schema.md` file documenting the table schemas would be helpful to store in the skill + +To establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets. + +### Step 3: Initializing the Skill + +At this point, it is time to actually create the skill. + +Skip this step only if the skill being developed already exists, and iteration or packaging is needed. In this case, continue to the next step. + +**Before running the script**, verify that python3 and packmind-cli are available (see Prerequisites section). If not installed, install them first. + +When creating a new skill from scratch, always run the `init_skill.py` script. The script conveniently generates a new template skill directory that automatically includes everything a skill requires, making the skill creation process much more efficient and reliable. + +Usage: + +```bash +python3 scripts/init_skill.py --path +``` + +**IMPORTANT:** The `--path` argument must be the **parent directory** where the skill folder will be created, not the skill directory itself. The script automatically creates a subdirectory named after the skill. + +- ✅ Correct: `python3 scripts/init_skill.py my-skill --path .claude/skills` → creates `.claude/skills/my-skill/` +- ❌ Wrong: `python3 scripts/init_skill.py my-skill --path .claude/skills/my-skill` → creates `.claude/skills/my-skill/my-skill/` (nested!) + +The script: + +- Creates the skill directory at the specified path +- Generates a SKILL.md template with proper frontmatter and TODO placeholders +- Creates example resource directories: `scripts/`, `references/`, and `assets/` +- Adds example files in each directory that can be customized or deleted + +After initialization, customize or remove the generated SKILL.md and example files as needed. + +### Step 4: Edit the Skill + +When editing the (newly-generated or existing) skill, remember that the skill is being created for another instance of CoPilot to use. Focus on including information that would be beneficial and non-obvious to CoPilot. Consider what procedural knowledge, domain-specific details, or reusable assets would help another CoPilot instance execute these tasks more effectively. + +**File Placement Rule:** Always create files directly in their target subdirectory. Never create a file at the skill root and move it later. +- Reference docs → `references/filename.md` +- Scripts → `scripts/filename.py` +- Assets → `assets/filename.ext` +- Only `SKILL.md`, `README.md`, and `LICENSE.txt` belong at the skill root. + +#### Start with Reusable Skill Contents + +To begin implementation, start with the reusable resources identified above: `scripts/`, `references/`, and `assets/` files. Note that this step may require user input. For example, when implementing a `brand-guidelines` skill, the user may need to provide brand assets or templates to store in `assets/`, or documentation to store in `references/`. + +Also, delete any example files and directories not needed for the skill. The initialization script creates example files in `scripts/`, `references/`, and `assets/` to demonstrate structure, but most skills won't need all of them. + +#### Update SKILL.md + +**Writing Style:** Write the entire skill using **imperative/infinitive form** (verb-first instructions), not second person. Use objective, instructional language (e.g., "To accomplish X, do Y" rather than "You should do X" or "If you need to do X"). This maintains consistency and clarity for AI consumption. + +To complete SKILL.md, answer the following questions: + +1. What is the purpose of the skill, in a few sentences? +2. When should the skill be used? +3. In practice, how should CoPilot use the skill? All reusable skill contents developed above should be referenced so that CoPilot knows how to use them. + +### Step 5: Validating a Skill + +Before distributing, validate the skill to ensure it meets all requirements. + +**Before running the script**, verify that python3 is available (see Prerequisites section). If not installed, install it first. + +```bash +python3 scripts/quick_validate.py +``` + +The validation script checks: + +- YAML frontmatter format and required fields +- Skill naming conventions and directory structure +- Description completeness and quality + +If validation fails, fix the reported errors and run the validation again. + +### Step 6: Iterate + +After testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed. + +**Iteration workflow:** + +1. Use the skill on real tasks +2. Notice struggles or inefficiencies +3. Identify how SKILL.md or bundled resources should be updated +4. Implement changes and test again + +### Step 7: Distributing a Skill + +**After successful validation, always run the distribution command** to register the skill with Packmind. Do not skip this step. + +**Before running the command**, verify that packmind-cli is available (see Prerequisites section). If not installed, install it first. + +Run the following command with the actual skill path: + +```bash +packmind-cli skills add +``` + +This registers the skill with Packmind, making it available for deployment to target repositories and AI coding agents. + +### Step 8: Offer to Add to Package + +After successful distribution, check if the skill fits an existing package: + +1. Run `packmind-cli install --list` to get available packages +2. If no packages exist, skip this step silently and end the workflow +3. Analyze the created skill's name and description against each package's name and description +4. If a package is a clear semantic fit (the skill's domain/technology aligns with the package's purpose): + - Present to user: "This skill seems to fit the `` package." + - Offer three options: + - Add to `` + - Choose a different package + - Skip +5. If no clear fit is found, skip silently (do not mention packages) +6. If user chooses to add: + - Run: `packmind-cli packages add --to --skill ` + - Ask: "Would you like me to run `packmind-cli install` to sync the changes?" + - If yes, run: `packmind-cli install` diff --git a/.github/skills/packmind-create-skill/scripts/init_skill.py b/.github/skills/packmind-create-skill/scripts/init_skill.py new file mode 100644 index 0000000000..dc5859b411 --- /dev/null +++ b/.github/skills/packmind-create-skill/scripts/init_skill.py @@ -0,0 +1,303 @@ +#!/usr/bin/env python3 +""" +Skill Initializer - Creates a new skill from template + +Usage: + init_skill.py --path + +Examples: + init_skill.py my-new-skill --path skills/public + init_skill.py my-api-helper --path skills/private + init_skill.py custom-skill --path /custom/location +""" + +import sys +from pathlib import Path + + +SKILL_TEMPLATE = """--- +name: '{skill_name}' +description: '[TODO: Complete and informative explanation of what the skill does and when to use it. Include WHEN to use this skill - specific scenarios, file types, or tasks that trigger it.]' +--- + +# {skill_title} + +## Overview + +[TODO: 1-2 sentences explaining what this skill enables] + +## Structuring This Skill + +[TODO: Choose the structure that best fits this skill's purpose. Common patterns: + +**1. Workflow-Based** (best for sequential processes) +- Works well when there are clear step-by-step procedures +- Example: DOCX skill with "Workflow Decision Tree" → "Reading" → "Creating" → "Editing" +- Structure: ## Overview → ## Workflow Decision Tree → ## Step 1 → ## Step 2... + +**2. Task-Based** (best for tool collections) +- Works well when the skill offers different operations/capabilities +- Example: PDF skill with "Quick Start" → "Merge PDFs" → "Split PDFs" → "Extract Text" +- Structure: ## Overview → ## Quick Start → ## Task Category 1 → ## Task Category 2... + +**3. Reference/Guidelines** (best for standards or specifications) +- Works well for brand guidelines, coding standards, or requirements +- Example: Brand styling with "Brand Guidelines" → "Colors" → "Typography" → "Features" +- Structure: ## Overview → ## Guidelines → ## Specifications → ## Usage... + +**4. Capabilities-Based** (best for integrated systems) +- Works well when the skill provides multiple interrelated features +- Example: Product Management with "Core Capabilities" → numbered capability list +- Structure: ## Overview → ## Core Capabilities → ### 1. Feature → ### 2. Feature... + +Patterns can be mixed and matched as needed. Most skills combine patterns (e.g., start with task-based, add workflow for complex operations). + +Delete this entire "Structuring This Skill" section when done - it's just guidance.] + +## [TODO: Replace with the first main section based on chosen structure] + +[TODO: Add content here. See examples in existing skills: +- Code samples for technical skills +- Decision trees for complex workflows +- Concrete examples with realistic user requests +- References to scripts/templates/references as needed] + +## Resources + +This skill includes example resource directories that demonstrate how to organize different types of bundled resources: + +### scripts/ +Executable code (Python/Bash/etc.) that can be run directly to perform specific operations. + +**Examples from other skills:** +- PDF skill: \`fill_fillable_fields.py\`, \`extract_form_field_info.py\` - utilities for PDF manipulation +- DOCX skill: \`document.py\`, \`utilities.py\` - Python modules for document processing + +**Appropriate for:** Python scripts, shell scripts, or any executable code that performs automation, data processing, or specific operations. + +**Note:** Scripts may be executed without loading into context, but can still be read by CoPilot for patching or environment adjustments. + +### references/ +Documentation and reference material intended to be loaded into context to inform CoPilot's process and thinking. + +**Examples from other skills:** +- Product management: \`communication.md\`, \`context_building.md\` - detailed workflow guides +- BigQuery: API reference documentation and query examples +- Finance: Schema documentation, company policies + +**Appropriate for:** In-depth documentation, API references, database schemas, comprehensive guides, or any detailed information that CoPilot should reference while working. + +### assets/ +Files not intended to be loaded into context, but rather used within the output CoPilot produces. + +**Examples from other skills:** +- Brand styling: PowerPoint template files (.pptx), logo files +- Frontend builder: HTML/React boilerplate project directories +- Typography: Font files (.ttf, .woff2) + +**Appropriate for:** Templates, boilerplate code, document templates, images, icons, fonts, or any files meant to be copied or used in the final output. + +--- + +**Any unneeded directories can be deleted.** Not every skill requires all three types of resources. +""" + +EXAMPLE_SCRIPT = '''#!/usr/bin/env python3 +""" +Example helper script for {skill_name} + +This is a placeholder script that can be executed directly. +Replace with actual implementation or delete if not needed. + +Example real scripts from other skills: +- pdf/scripts/fill_fillable_fields.py - Fills PDF form fields +- pdf/scripts/convert_pdf_to_images.py - Converts PDF pages to images +""" + +def main(): + print("This is an example script for {skill_name}") + # TODO: Add actual script logic here + # This could be data processing, file conversion, API calls, etc. + +if __name__ == "__main__": + main() +''' + +EXAMPLE_REFERENCE = """# Reference Documentation for {skill_title} + +This is a placeholder for detailed reference documentation. +Replace with actual reference content or delete if not needed. + +Example real reference docs from other skills: +- product-management/references/communication.md - Comprehensive guide for status updates +- product-management/references/context_building.md - Deep-dive on gathering context +- bigquery/references/ - API references and query examples + +## When Reference Docs Are Useful + +Reference docs are ideal for: +- Comprehensive API documentation +- Detailed workflow guides +- Complex multi-step processes +- Information too lengthy for main SKILL.md +- Content that's only needed for specific use cases + +## Structure Suggestions + +### API Reference Example +- Overview +- Authentication +- Endpoints with examples +- Error codes +- Rate limits + +### Workflow Guide Example +- Prerequisites +- Step-by-step instructions +- Common patterns +- Troubleshooting +- Best practices +""" + +EXAMPLE_ASSET = """# Example Asset File + +This placeholder represents where asset files would be stored. +Replace with actual asset files (templates, images, fonts, etc.) or delete if not needed. + +Asset files are NOT intended to be loaded into context, but rather used within +the output CoPilot produces. + +Example asset files from other skills: +- Brand guidelines: logo.png, slides_template.pptx +- Frontend builder: hello-world/ directory with HTML/React boilerplate +- Typography: custom-font.ttf, font-family.woff2 +- Data: sample_data.csv, test_dataset.json + +## Common Asset Types + +- Templates: .pptx, .docx, boilerplate directories +- Images: .png, .jpg, .svg, .gif +- Fonts: .ttf, .otf, .woff, .woff2 +- Boilerplate code: Project directories, starter files +- Icons: .ico, .svg +- Data files: .csv, .json, .xml, .yaml + +Note: This is a text placeholder. Actual assets can be any file type. +""" + + +def title_case_skill_name(skill_name): + """Convert hyphenated skill name to Title Case for display.""" + return ' '.join(word.capitalize() for word in skill_name.split('-')) + + +def init_skill(skill_name, path): + """ + Initialize a new skill directory with template SKILL.md. + + Args: + skill_name: Name of the skill + path: Path where the skill directory should be created + + Returns: + Path to created skill directory, or None if error + """ + # Determine skill directory path + skill_dir = Path(path).resolve() / skill_name + + # Check if directory already exists + if skill_dir.exists(): + print(f"❌ Error: Skill directory already exists: {skill_dir}") + return None + + # Create skill directory + try: + skill_dir.mkdir(parents=True, exist_ok=False) + print(f"✅ Created skill directory: {skill_dir}") + except Exception as e: + print(f"❌ Error creating directory: {e}") + return None + + # Create SKILL.md from template + skill_title = title_case_skill_name(skill_name) + skill_content = SKILL_TEMPLATE.format( + skill_name=skill_name, + skill_title=skill_title + ) + + skill_md_path = skill_dir / 'SKILL.md' + try: + skill_md_path.write_text(skill_content) + print("✅ Created SKILL.md") + except Exception as e: + print(f"❌ Error creating SKILL.md: {e}") + return None + + # Create resource directories with example files + try: + # Create scripts/ directory with example script + scripts_dir = skill_dir / 'scripts' + scripts_dir.mkdir(exist_ok=True) + example_script = scripts_dir / 'example.py' + example_script.write_text(EXAMPLE_SCRIPT.format(skill_name=skill_name)) + example_script.chmod(0o755) + print("✅ Created scripts/example.py") + + # Create references/ directory with example reference doc + references_dir = skill_dir / 'references' + references_dir.mkdir(exist_ok=True) + example_reference = references_dir / 'api_reference.md' + example_reference.write_text(EXAMPLE_REFERENCE.format(skill_title=skill_title)) + print("✅ Created references/api_reference.md") + + # Create assets/ directory with example asset placeholder + assets_dir = skill_dir / 'assets' + assets_dir.mkdir(exist_ok=True) + example_asset = assets_dir / 'example_asset.txt' + example_asset.write_text(EXAMPLE_ASSET) + print("✅ Created assets/example_asset.txt") + except Exception as e: + print(f"❌ Error creating resource directories: {e}") + return None + + # Print next steps + print(f"\n✅ Skill '{skill_name}' initialized successfully at {skill_dir}") + print("\nNext steps:") + print("1. Edit SKILL.md to complete the TODO items and update the description") + print("2. Customize or delete the example files in scripts/, references/, and assets/") + print("3. Run the validator when ready to check the skill structure") + + return skill_dir + + +def main(): + if len(sys.argv) < 4 or sys.argv[2] != '--path': + print("Usage: init_skill.py --path ") + print("\nSkill name requirements:") + print(" - Hyphen-case identifier (e.g., 'data-analyzer')") + print(" - Lowercase letters, digits, and hyphens only") + print(" - Max 40 characters") + print(" - Must match directory name exactly") + print("\nExamples:") + print(" init_skill.py my-new-skill --path skills/public") + print(" init_skill.py my-api-helper --path skills/private") + print(" init_skill.py custom-skill --path /custom/location") + sys.exit(1) + + skill_name = sys.argv[1] + path = sys.argv[3] + + print(f"🚀 Initializing skill: {skill_name}") + print(f" Location: {path}") + print() + + result = init_skill(skill_name, path) + + if result: + sys.exit(0) + else: + sys.exit(1) + + +if __name__ == "__main__": + main() diff --git a/.github/skills/packmind-create-skill/scripts/quick_validate.py b/.github/skills/packmind-create-skill/scripts/quick_validate.py new file mode 100644 index 0000000000..af63613a44 --- /dev/null +++ b/.github/skills/packmind-create-skill/scripts/quick_validate.py @@ -0,0 +1,65 @@ +#!/usr/bin/env python3 +""" +Quick validation script for skills - minimal version +""" + +import sys +import os +import re +from pathlib import Path + +def validate_skill(skill_path): + """Basic validation of a skill""" + skill_path = Path(skill_path) + + # Check SKILL.md exists + skill_md = skill_path / 'SKILL.md' + if not skill_md.exists(): + return False, "SKILL.md not found" + + # Read and validate frontmatter + content = skill_md.read_text() + if not content.startswith('---'): + return False, "No YAML frontmatter found" + + # Extract frontmatter + match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL) + if not match: + return False, "Invalid frontmatter format" + + frontmatter = match.group(1) + + # Check required fields + if 'name:' not in frontmatter: + return False, "Missing 'name' in frontmatter" + if 'description:' not in frontmatter: + return False, "Missing 'description' in frontmatter" + + # Extract name for validation + name_match = re.search(r'name:\s*(.+)', frontmatter) + if name_match: + name = name_match.group(1).strip() + # Check naming convention (hyphen-case: lowercase with hyphens) + if not re.match(r'^[a-z0-9-]+$', name): + return False, f"Name '{name}' should be hyphen-case (lowercase letters, digits, and hyphens only)" + if name.startswith('-') or name.endswith('-') or '--' in name: + return False, f"Name '{name}' cannot start/end with hyphen or contain consecutive hyphens" + + # Extract and validate description + desc_match = re.search(r'description:\s*(.+)', frontmatter) + if desc_match: + description = desc_match.group(1).strip() + # Check for angle brackets + if '<' in description or '>' in description: + return False, "Description cannot contain angle brackets (< or >)" + + return True, "Skill is valid!" + +if __name__ == "__main__": + if len(sys.argv) != 2: + print("Usage: python quick_validate.py ") + sys.exit(1) + + valid, message = validate_skill(sys.argv[1]) + print(message) + sys.exit(0 if valid else 1) diff --git a/.github/skills/packmind-create-standard/LICENSE.txt b/.github/skills/packmind-create-standard/LICENSE.txt new file mode 100644 index 0000000000..f433b1a53f --- /dev/null +++ b/.github/skills/packmind-create-standard/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/.github/skills/packmind-create-standard/README.md b/.github/skills/packmind-create-standard/README.md new file mode 100644 index 0000000000..d3bf4c057b --- /dev/null +++ b/.github/skills/packmind-create-standard/README.md @@ -0,0 +1,37 @@ +# Standard Creator + +A skill that guides AI coding agents through the process of creating coding standards via the Packmind CLI. + +## What is a Coding Standard? + +Coding standards are collections of rules that capture team conventions, best practices, and coding guidelines. They enable AI coding agents to follow your team's specific practices. + +## How to Use + +Ask the AI agent to create a coding standard. The agent will automatically use this skill to guide the process. + +### Example Prompts + +- "Create a standard for TypeScript naming conventions" +- "Help me build a coding standard for our React components" +- "I want to create a standard for error handling in our API" +- "Create a new standard for test file conventions" + +The AI agent will: + +1. Ask clarifying questions to understand the standard's purpose +2. Help you define rules with proper formatting +3. Draft a markdown file for review +4. Get your approval before submission +5. Convert to JSON and run the CLI command to create the standard + +## Prerequisites + +Before using this skill, ensure you have: + +- **packmind-cli**: Required for standard creation +- **Packmind account**: Login via `packmind-cli login` + +## License + +Apache 2.0 - See LICENSE.txt for details. diff --git a/.github/skills/packmind-create-standard/SKILL.md b/.github/skills/packmind-create-standard/SKILL.md new file mode 100644 index 0000000000..5f7453ee9c --- /dev/null +++ b/.github/skills/packmind-create-standard/SKILL.md @@ -0,0 +1,469 @@ +--- +name: 'packmind-create-standard' +description: 'Guide for creating coding standards via the Packmind CLI. This skill should be used when users want to create a new coding standard (or add rules to an existing standard) that captures team conventions, best practices, or coding guidelines for distribution to CoPilot.' +license: 'Complete terms in LICENSE.txt' +--- + +# Standard Creator + +This skill provides a complete walkthrough for creating coding standards via the Packmind CLI. + +## About Coding Standards + +Coding standards are collections of rules that capture team conventions, best practices, and coding guidelines. They help maintain consistency across codebases and enable CoPilot to follow your team's specific practices. + +### What Standards Provide + +1. **Consistent code style** - Rules that enforce naming conventions, formatting, and structure +2. **Best practices** - Guidelines for error handling, testing, security, and performance +3. **Domain knowledge** - Company-specific patterns, architectural decisions, and business logic +4. **Code examples** - Positive/negative examples that demonstrate correct vs incorrect usage + +### Standard Structure + +Every standard is drafted as a markdown file with this structure: + +``` +# Standard Name + +## Description + +What the standard covers and why. + +## Scope + +Comma-separated glob patterns for files where the standard applies (e.g., "**/*.ts", "**/*.spec.ts,**/*.test.ts"). + +## Rules + +### Rule description starting with action verb + +#### Positive Example + +\`\`\`typescript +// Valid code example +\`\`\` + +#### Negative Example + +\`\`\`typescript +// Invalid code example +\`\`\` + +### Another rule without examples +``` + +### Naming Guidelines + +The `# Title` heading is the **display name** shown in indexes and dashboards. The slug is auto-generated from it — never write the slug yourself. + +**Format:** Use **Title Case with spaces** — natural language, not a slug. +- Capitalize each significant word +- Use spaces between words, never hyphens or underscores +- Be descriptive and specific (2–5 words) — indicate the domain/technology and the aspect covered + +**Examples:** +- ✅ `"TypeScript Testing Conventions"`, `"React Component File Organization"`, `"Backend Error Handling"` +- ❌ `"typescript-testing-conventions"` (slug format — use Title Case with spaces) +- ❌ `"testing"` (too generic) +- ❌ `"good-practices"` (slug format and too vague) +- ❌ `"Standards for Code"` (describes meta-concept, not the actual domain) + +**Note**: The `summary` field is used in other workflows (like MCP) but not yet supported by the CLI. + +#### Understanding `scope` vs `summary` + +- **`scope`** (required by CLI): **WHERE** the standard applies — comma-separated glob patterns. + - Must be **glob patterns only** — never natural language descriptions. + - Examples: `"**/*.spec.ts,**/*.test.ts"`, `"**/*.tsx,**/*.jsx"`, `"src/domain/**/*.ts"` + - **Common patterns:** + - `**/*.ts` — all TypeScript files + - `**/*.spec.ts,**/*.test.ts` — all test files + - `**/*.tsx,**/*.jsx` — all React component files + - `src/domain/**/*.ts` — domain TypeScript files under src + - `packages/**/src/**/*.ts` — all package source files + - ⚠️ **Never write natural language** like "TypeScript files" or "React components" — the value is used as literal glob patterns for file matching, so natural language will match nothing. +- **`summary`** (optional, not yet CLI-supported): **WHEN/WHY** to apply - high-level purpose and trigger condition + - Examples: `"Apply when writing tests to ensure consistency"`, `"Use when handling user data for privacy compliance"` + +## Prerequisites + +Before creating a standard, verify that packmind-cli is available: + +Check if packmind-cli is installed: + +```bash +packmind-cli --version +``` + +If not available, install it: + +```bash +npm install -g @packmind/cli +``` + +Then login to Packmind: + +```bash +packmind-cli login +``` + +## Standard Creation Process + +To create a standard, follow this process in order, skipping steps only if there is a clear reason why they are not applicable. + +### Step 1: Clarify the Request + +Gather essential information before drafting the standard. + +#### Clarification Flow + +Study the user's request and identify critical gaps. The number of questions should match the request clarity: +- **1-2 questions** when the request is well-defined (clear scope, specific examples, detailed context) +- **3-5 questions** when the context is unclear or the request is vague + +**Examples of focused questions:** +- "Which service or file shows the expected pattern?" +- "Is there an existing doc or rule we must stay aligned with?" +- "What specific aspect matters most (mocking guidelines, naming conventions, assertion style)?" + +Introduce questions with a simple phrase about needing clarification, then list as bullet points—no numbering, no category headers. + +#### Repository Access Guardrail + +**Do not open or scan repository files unless the user explicitly points to them** (provides file paths or requests project-wide review). If source references are needed, ask the user to supply them. + +#### What to Capture + +Take brief notes on: +- Title or slug (if mentioned) +- Scope guardrails +- Key references +- Expected outcomes + +Keep notes concise—just enough to unlock drafting. + +### Step 2: Draft Standard in Markdown + +Transform the understanding into a complete markdown draft with rules and examples. + +#### Draft Creation + +1. Create a draft markdown file in `.packmind/standards/_drafts/` (create the folder if missing) using filename `.md` (lowercase with hyphens) +2. Draft structure: + - `# ` (Title Case, 2–5 words) + - `## Description` — what the standard covers and why it exists + - `## Scope` — comma-separated glob patterns (required) + - `## Rules` — each rule as a `### ` subsection following the Rule Writing Guidelines below + - For each rule that benefits from code examples, add: + - `#### Positive Example` with a language-annotated code block showing the compliant approach + - `#### Negative Example` with a language-annotated code block showing the anti-pattern + - If a rule doesn't benefit from code examples (e.g., process or organizational rules), skip examples for that rule + +This draft file is the **only** file created during drafting — no separate files are needed. + +#### Rule Writing Guidelines + +Each rule should follow these format requirements: + +1. **Start with an action verb** - Use imperative form (e.g., "Use", "Avoid", "Prefer", "Include") +2. **Be concise** - Max ~25 words per rule +3. **Be specific and actionable** - Avoid vague guidance +4. **Focus on one concept** - One rule per convention + +##### Avoid Rationale Phrases + +Rules describe **WHAT** to do, not **WHY**. Strip justifications and benefits—let examples demonstrate value. + +**Common fluff patterns to remove:** +- "to improve/provide/ensure..." (benefit phrases) +- "while maintaining/preserving..." (secondary concerns) +- "for better/enhanced..." (quality claims) +- "and enable/allow..." (future benefits) + +**Bad (includes rationale):** +> Document props with JSDoc comments to provide IDE intellisense and improve developer experience. + +**Good (action only):** +> Document component props with JSDoc comments (`/** ... */`) describing purpose, expected values, and defaults. + +##### Rule Splitting + +If a rule addresses 2+ distinct concerns, **proactively split** it into separate rules: + +**Bad (too broad):** +> Create centralized color constants in dedicated files for consistent palettes, using semantic naming based on purpose rather than specific color values. + +**Good (split into focused rules):** +- Define color constants in `theme/colors.ts` using semantic names (e.g., `primary`, `error`) +- Use semantic color tokens instead of literal hex values in components + +##### Inline Examples in Rules + +Inline examples (code, paths, patterns) within the rule content are **optional**. Only include them when they clarify something not obvious from the rule text. + +**Types of useful inline examples:** +- Code syntax: `const`, `async/await`, `/** ... */` +- File paths: `infra/repositories/`, `domain/entities/` +- Naming patterns: `.spec.ts`, `I{Name}` prefix + +**Good rules with inline examples:** +- "Use const instead of let for variables that are never reassigned" +- "Prefix interface names with I (e.g., `IUserService`)" +- "Place repository implementations in `infra/repositories/`" + +**Good rules without inline examples:** +- "Name root describe block after the class or function under test" +- "Run linting before committing changes" +- "Keep business logic out of controllers" + +**Bad rules:** +- "Write good code" (too vague) +- "Use const and prefix interfaces with I" (multiple concepts) +- "Don't use var" (no positive guidance) + +#### Examples Guidelines + +- Examples should be realistic and directly relevant to this codebase +- Each example should clearly demonstrate why the rule matters +- Keep code snippets minimal—only include what's necessary to illustrate the point +- Annotate every code block with its language (e.g., `typescript`, `sql`, `javascript`) + +Valid language values for code blocks: +- TYPESCRIPT, TYPESCRIPT_TSX +- JAVASCRIPT, JAVASCRIPT_JSX +- PYTHON, JAVA, GO, RUST, CSHARP +- PHP, RUBY, KOTLIN, SWIFT, DART, SQL +- HTML, CSS, SCSS, YAML, JSON +- MARKDOWN, BASH, GENERIC + +#### Draft Summary + +After saving the draft file, write a concise summary that captures: +- One sentence summarizing the standard's purpose +- A bullet list of all rules (each rule ~22 words max, imperative form, with inline code if helpful) + +Then proceed directly to Step 3. + +### Step 3: Review Before Submission + +**Before running the CLI command**, you MUST get explicit user approval: + +1. **Display a formatted recap** of the standard content: + +``` +--- +Name: + +Description: + +Scope: + +Rules: + +1. + - ✅ + - ❌ +2. + - ✅ + - ❌ +... +--- +``` + +2. **Provide the file path** to the markdown file so users can open and edit it directly if needed. + +3. Ask: **"Here is the standard that will be created on Packmind. The draft file is at `` if you want to review or edit it. Do you approve?"** + +4. **Wait for explicit user confirmation** before proceeding to Step 4. + +5. If the user requests changes, go back to earlier steps to make adjustments. + +### Step 4: Confirm and Submit + +1. **Re-read the markdown file** from disk to capture any user edits. + +2. **Compare with the original content** you created in Step 2. + +3. **If changes were detected**: + - Display the formatted recap again (same format as Step 3) + - Ask: **"The file was modified. Here is the updated content that will be sent. Do you confirm?"** + - **Wait for explicit confirmation** before proceeding. + +4. **If no changes**: Proceed directly to submission. + +5. **Convert the markdown to JSON** using these conversion rules: + - `# heading` → `name` + - `## Description` content → `description` + - `## Scope` content → `scope` + - Each `### ...` under `## Rules` → rule `content` + - `#### Positive Example` code block → `examples.positive` + - `#### Negative Example` code block → `examples.negative` + - Code fence language identifier → `examples.language` (UPPERCASED) + + **Important:** `examples` is a **single object** (not an array) — one positive/negative pair per rule. It is **optional** — omit entirely for rules without code examples. When present, all three fields (`positive`, `negative`, `language`) are required. + + **Expected JSON format:** + ```json + { + "name": "Standard Name", + "description": "What the standard covers and why.", + "scope": "**/*.spec.ts,**/*.test.ts", + "rules": [ + { + "content": "Rule description starting with action verb", + "examples": { + "positive": "// valid code", + "negative": "// invalid code", + "language": "TYPESCRIPT" + } + }, + { + "content": "Rule without examples" + } + ] + } + ``` + +6. Pipe the JSON directly to the CLI via stdin using a heredoc (no intermediate file needed): + +```bash +packmind-cli standards create --origin-skill packmind-create-standard <<'EOF' +{"name":"...","description":"...","scope":"...","rules":[...]} +EOF +``` + +Expected output on success: +``` +packmind-cli Standard "Your Standard Name" created successfully (ID: ) +``` + +#### Troubleshooting + +**"Not logged in" error:** +```bash +packmind-cli login +``` + +**"Failed to resolve global space" error:** +- Verify your API key is valid +- Check network connectivity to Packmind server + +**Validation errors:** +- Ensure all required sections are present in the markdown file +- Check that the `## Rules` section has at least one `###` rule subsection +- Verify code blocks have language annotations + +**"expected object, received array" error on examples:** +- The `examples` field must be a single object `{positive, negative, language}`, not an array +- Each rule supports at most one example pair + +### Step 5: Cleanup + +After the standard is **successfully created**, delete the draft markdown file in `.packmind/standards/_drafts/`. + +**Only clean up on success** - if the CLI command fails, keep the files so the user can retry. + +### Step 6: Offer to Add to Package + +After successful creation, check if the standard fits an existing package: + +1. Run `packmind-cli install --list` to get available packages +2. If no packages exist, skip this step silently and end the workflow +3. Analyze the created standard's name, description, and scope against each package's name and description +4. If a package is a clear semantic fit (the standard's domain/technology aligns with the package's purpose): + - Present to user: "This standard seems to fit the `` package." + - Offer three options: + - Add to `` + - Choose a different package + - Skip +5. If no clear fit is found, skip silently (do not mention packages) +6. If user chooses to add: + - Run: `packmind-cli packages add --to --standard ` + - Ask: "Would you like me to run `packmind-cli install` to sync the changes?" + - If yes, run: `packmind-cli install` + +## Complete Example + +Here's a complete example creating a TypeScript testing standard: + +**File: .packmind/standards/_drafts/testing-conventions.md** +```markdown +# TypeScript Testing Conventions + +## Description + +Enforce consistent testing patterns in TypeScript test files to improve readability, maintainability, and reliability of the test suite. + +## Scope + +**/*.spec.ts,**/*.test.ts + +## Rules + +### Use descriptive test names that explain the expected behavior + +#### Positive Example + +\`\`\`typescript +it('returns empty array when no items match filter') +\`\`\` + +#### Negative Example + +\`\`\`typescript +it('test filter') +\`\`\` + +### Follow Arrange-Act-Assert pattern in test structure + +#### Positive Example + +\`\`\`typescript +const input = createInput(); +const result = processInput(input); +expect(result).toEqual(expected); +\`\`\` + +#### Negative Example + +\`\`\`typescript +expect(processInput(createInput())).toEqual(expected); +\`\`\` + +### Use one assertion per test for better error isolation + +#### Positive Example + +\`\`\`typescript +it('validates name', () => { expect(result.name).toBe('test'); }); +it('validates age', () => { expect(result.age).toBe(25); }); +\`\`\` + +#### Negative Example + +\`\`\`typescript +it('validates user', () => { expect(result.name).toBe('test'); expect(result.age).toBe(25); }); +\`\`\` + +### Avoid using 'should' at the start of test names - use assertive verb-first naming +``` + +**Creating the standard (piped via stdin):** +```bash +packmind-cli standards create --origin-skill packmind-create-standard <<'EOF' +{"name":"TypeScript Testing Conventions","description":"Enforce consistent testing patterns...","scope":"**/*.spec.ts,**/*.test.ts","rules":[...]} +EOF +``` + +## Quick Reference + +| Section | Required | Description | +|---|---|---| +| `# Title` | Yes | Title Case, descriptive, 2–5 words | +| `## Description` | Yes | What and why | +| `## Scope` | Yes (CLI) | Comma-separated glob patterns | +| `## Rules` | Yes | Contains rule subsections | +| `### Rule text` | Yes (≥1) | Rule text (verb-first, max ~25 words) | +| `#### Positive Example` | No | Valid code in fenced block | +| `#### Negative Example` | No | Invalid code in fenced block | diff --git a/.github/skills/packmind-onboard/LICENSE.txt b/.github/skills/packmind-onboard/LICENSE.txt new file mode 100644 index 0000000000..f433b1a53f --- /dev/null +++ b/.github/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/.github/skills/packmind-onboard/README.md b/.github/skills/packmind-onboard/README.md new file mode 100644 index 0000000000..a67977da63 --- /dev/null +++ b/.github/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/.github/skills/packmind-onboard/SKILL.md b/.github/skills/packmind-onboard/SKILL.md new file mode 100644 index 0000000000..219a18787a --- /dev/null +++ b/.github/skills/packmind-onboard/SKILL.md @@ -0,0 +1,599 @@ +--- +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 + +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: + +```bash +packmind-cli install --list +``` + +Parse the output to get package names. + +### No packages exist + +Auto-create package using repository name: + +```bash +packmind-cli packages create "${REPO_NAME}-standards" +``` + +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) +- Run: `packmind-cli packages create ` + +Remember the selected/created package name for later reference. + +--- + +## 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 formats defined above. + +### 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... +``` + +### Generation Rules + +- 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 + +### 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. + +--- + +## Step 10 — Completion Summary + +### 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-cli packages add --to --standard + packmind-cli commands create + 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 +============================================================ +``` + +--- + +## 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 `packmind-cli install --list` returns no packages: + +Auto-create a package using the repository name. + +--- + +### 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/.github/skills/packmind-onboard/references/ci-local-workflow-parity.md b/.github/skills/packmind-onboard/references/ci-local-workflow-parity.md new file mode 100644 index 0000000000..188e6572d6 --- /dev/null +++ b/.github/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/.github/skills/packmind-onboard/references/file-template-consistency.md b/.github/skills/packmind-onboard/references/file-template-consistency.md new file mode 100644 index 0000000000..5ef3cefa65 --- /dev/null +++ b/.github/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/.github/skills/packmind-onboard/references/role-taxonomy-drift.md b/.github/skills/packmind-onboard/references/role-taxonomy-drift.md new file mode 100644 index 0000000000..0629128ab7 --- /dev/null +++ b/.github/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/.github/skills/packmind-onboard/references/test-data-construction.md b/.github/skills/packmind-onboard/references/test-data-construction.md new file mode 100644 index 0000000000..55691efc8a --- /dev/null +++ b/.github/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/.github/skills/packmind-update-playbook/LICENSE.txt b/.github/skills/packmind-update-playbook/LICENSE.txt new file mode 100644 index 0000000000..f433b1a53f --- /dev/null +++ b/.github/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/.github/skills/packmind-update-playbook/SKILL.md b/.github/skills/packmind-update-playbook/SKILL.md new file mode 100644 index 0000000000..0bdb298f93 --- /dev/null +++ b/.github/skills/packmind-update-playbook/SKILL.md @@ -0,0 +1,180 @@ +--- +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 + +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. + +**⚠️ 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 `references/domain-*.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 | Reference File | Output | +|----------|----------------|--------| +| Standards | `references/domain-standards.md` | Standards change report | +| Commands | `references/domain-commands.md` | Commands change report | +| Skills | `references/domain-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 + +#### 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/.github/skills/packmind-update-playbook/references/agent-skills-specification.md b/.github/skills/packmind-update-playbook/references/agent-skills-specification.md new file mode 100644 index 0000000000..142fbbc383 --- /dev/null +++ b/.github/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/.github/skills/packmind-update-playbook/references/domain-commands.md b/.github/skills/packmind-update-playbook/references/domain-commands.md new file mode 100644 index 0000000000..eaa338fba0 --- /dev/null +++ b/.github/skills/packmind-update-playbook/references/domain-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/.github/skills/packmind-update-playbook/references/domain-skills.md b/.github/skills/packmind-update-playbook/references/domain-skills.md new file mode 100644 index 0000000000..d28a29bf17 --- /dev/null +++ b/.github/skills/packmind-update-playbook/references/domain-skills.md @@ -0,0 +1,75 @@ +# 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](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. + +### 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](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/.github/skills/packmind-update-playbook/references/domain-standards.md b/.github/skills/packmind-update-playbook/references/domain-standards.md new file mode 100644 index 0000000000..9f28cf2ddc --- /dev/null +++ b/.github/skills/packmind-update-playbook/references/domain-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/.packmind/commands/ouds-create-component.md b/.packmind/commands/ouds-create-component.md new file mode 100644 index 0000000000..1bdc945c79 --- /dev/null +++ b/.packmind/commands/ouds-create-component.md @@ -0,0 +1,358 @@ +--- +name: ouds-create-component +description: > + Step-by-step workflow for creating a new SCSS and/or JavaScript component in OUDS Web. + Covers SCSS structure, token setup, multi-brand token files, JS component boilerplate, + ARIA/accessibility requirements, and testing checklist. +when_to_use: + - Creating a new UI component not yet in OUDS Web + - Adding a new form component (scss/forms/) + - Creating an OUDS-specific component beyond Bootstrap + - Scaffolding a new JavaScript-driven interactive component +--- + +# Command: Create a New OUDS Web Component + +## When to Use + +- You need to create a new SCSS component (`scss/_my-component.scss`) +- You need a form component (`scss/forms/_my-component.scss`) +- The component requires interactive behavior (new `js/src/my-component.js`) +- You need to add component tokens to all brand packages + +## Checkpoints + +- Is this component truly new, or a variant/modification of an existing one? +- Does it need JavaScript (interactive: toggle, dismiss, expand)? Or CSS-only? +- Do component tokens already exist in `packages/*/scss/tokens/_component.scss`? +- Is it brand-specific or shared across all 3 brands? + +--- + +## Steps + +### 1. Create the SCSS file + +Create `scss/_my-component.scss` (or `scss/forms/_my-component.scss` for form components). + +Follow this exact structure: + +```scss +// scss/_my-component.scss + +// +// My Component +// + +// Root-level variable (only if needed globally, e.g., for shared border-radius) +#{$ouds-root-selector} { + --#{$prefix}my-component-border-radius: #{$ouds-my-component-border-radius-default}; +} + +.my-component { + // scss-docs-start my-component-css-vars + --#{$prefix}my-component-padding-y: #{$ouds-my-component-space-padding-block}; + --#{$prefix}my-component-padding-x: #{$ouds-my-component-space-padding-inline}; + --#{$prefix}my-component-color: #{$ouds-color-content-default}; + --#{$prefix}my-component-bg: #{$ouds-color-bg-primary}; + --#{$prefix}my-component-border-color: #{$ouds-color-border-default}; + // scss-docs-end my-component-css-vars + + display: flex; + padding: var(--#{$prefix}my-component-padding-y) var(--#{$prefix}my-component-padding-x); + color: var(--#{$prefix}my-component-color); + background-color: var(--#{$prefix}my-component-bg); + border: $ouds-border-width-default solid var(--#{$prefix}my-component-border-color); + @include border-radius(var(--#{$prefix}my-component-border-radius)); + @include transition($transition-base); + + // States — override CSS custom properties, not CSS properties + &:hover { + --#{$prefix}my-component-bg: #{$ouds-color-bg-secondary}; + } + + &:focus-visible { + @include focus-visible(); + } + + &:disabled, + &[aria-disabled="true"] { + --#{$prefix}my-component-color: #{$ouds-color-content-disabled}; + pointer-events: none; + cursor: not-allowed; + } +} + +// Variants +.my-component-variant { + --#{$prefix}my-component-bg: #{$ouds-color-surface-brand}; +} +``` + +Rules to follow: +- Use design tokens, never hardcode values (`16px`, `#ff7900`) +- Use `@include border-radius()` and `@include transition()` — never direct properties +- Use `var(--#{$prefix}color-*)` for all colors (enables dark mode) +- Use `border: 0` not `border: none` +- Always add `// scss-docs-start` / `// scss-docs-end` markers +- Use `color: var(...)` for interactive states by overriding CSS custom properties + +### 2. Import the SCSS in the brand entry point(s) + +Add the import to `packages//scss/ouds-web.scss` for **all 3 brands**: + +```scss +// In ouds-web.scss — OUDS Web components section +@import "@ouds/web-common/scss/my-component"; +``` + +If it's a form component, also add to `scss/_forms.scss`: + +```scss +@import "forms/my-component"; +``` + +### 3. Add component tokens to all 3 brand packages + +**Do not edit `_raw.scss`, `_semantic.scss`, or `_component.scss`** — they are auto-generated. + +If waiting for design pipeline tokens, add temporary fallbacks to `scss/_variables.scss`: + +```scss +// scss/_variables.scss — temporary until token is auto-generated +// TODO: replace with OUDS token when pipeline delivers +$ouds-my-component-border-radius-default: $ouds-border-radius-default !default; +$ouds-my-component-space-padding-block: $ouds-space-padding-block-medium !default; +$ouds-my-component-space-padding-inline: $ouds-space-padding-inline-medium !default; +``` + +For composite tokens (elevation, icons, font-stacks), add to **each** `_composite.scss`: + +```scss +// packages/orange/scss/tokens/_composite.scss +$ouds-my-component-elevation: $ouds-elevation-raised !default; + +// packages/sosh/scss/tokens/_composite.scss +$ouds-my-component-elevation: $ouds-elevation-raised !default; + +// packages/orange-compact/scss/tokens/_composite.scss +$ouds-my-component-elevation: $ouds-elevation-raised !default; +``` + +> **⚠️** When real tokens arrive via the design pipeline PR, remove the temporary variables from `_variables.scss`. + +### 4. Add ARIA and accessibility requirements to the markup + +Review the component's interaction pattern and add the required ARIA: + +| Pattern | Required | +|---|---| +| Toggles open/closed | `aria-expanded="true/false"` on trigger | +| Has a label from nearby text | `aria-labelledby="id-of-label"` | +| Icon-only button | `aria-label="Action name"` + `aria-hidden="true"` on icon | +| Dynamic content update | `aria-live="polite"` or `role="status"` | +| Disabled state | `aria-disabled="true"` | +| Loading/busy state | `aria-busy="true"` | + +```html + + + +``` + +### 5. Create the JS component (if interactive) + +Create `js/src/my-component.js` following this template: + +```javascript +'use strict' + +import BaseComponent from './base-component.js' +import EventHandler from './dom/event-handler.js' +import { defineJQueryPlugin } from './util/index.js' + +const NAME = 'mycomponent' +const DATA_KEY = `bs.${NAME}` +const EVENT_KEY = `.${DATA_KEY}` +const DATA_API_KEY = '.data-api' + +const EVENT_SHOW = `show${EVENT_KEY}` +const EVENT_SHOWN = `shown${EVENT_KEY}` +const EVENT_HIDE = `hide${EVENT_KEY}` +const EVENT_HIDDEN = `hidden${EVENT_KEY}` +const EVENT_CLICK_DATA_API = `click${EVENT_KEY}${DATA_API_KEY}` + +const CLASS_NAME_SHOW = 'show' +const SELECTOR_DATA_TOGGLE = '[data-bs-toggle="mycomponent"]' + +const Default = {} +const DefaultType = {} + +class MyComponent extends BaseComponent { + constructor(element, config) { + super(element, config) + } + + static get Default() { return Default } + static get DefaultType() { return DefaultType } + static get NAME() { return NAME } + + // Public + show() { + const showEvent = EventHandler.trigger(this._element, EVENT_SHOW) + if (showEvent.defaultPrevented) { + return + } + this._element.classList.add(CLASS_NAME_SHOW) + this._element.setAttribute('aria-expanded', true) + EventHandler.trigger(this._element, EVENT_SHOWN) + } + + hide() { + const hideEvent = EventHandler.trigger(this._element, EVENT_HIDE) + if (hideEvent.defaultPrevented) { + return + } + this._element.classList.remove(CLASS_NAME_SHOW) + this._element.setAttribute('aria-expanded', false) + EventHandler.trigger(this._element, EVENT_HIDDEN) + } + + dispose() { + super.dispose() + } + + static jQueryInterface(config) { + return this.each(function () { + const data = MyComponent.getOrCreateInstance(this, config) + if (typeof config === 'string') { + if (typeof data[config] === 'undefined') { + throw new TypeError(`No method named "${config}"`) + } + data[config]() + } + }) + } +} + +EventHandler.on(document, EVENT_CLICK_DATA_API, SELECTOR_DATA_TOGGLE, function (event) { + event.preventDefault() + MyComponent.getOrCreateInstance(this).show() +}) + +defineJQueryPlugin(MyComponent) + +export default MyComponent +``` + +Register the JS component in `js/index.umd.js` and `js/index.esm.js`: + +```javascript +export { default as MyComponent } from './src/my-component.js' +``` + +### 6. Write unit tests + +Create `js/tests/unit/my-component.spec.js`: + +```javascript +import MyComponent from '../../../js/src/my-component.js' + +describe('MyComponent', () => { + let element + + beforeEach(() => { + element = document.createElement('div') + document.body.appendChild(element) + }) + + afterEach(() => { + document.body.removeChild(element) + }) + + describe('show', () => { + it('should add show class', () => { + const component = new MyComponent(element) + component.show() + expect(element.classList.contains('show')).toBeTrue() + }) + }) +}) +``` + +Run: `npm run js-test` + +### 7. Create the documentation page + +Create `site/src/content/docs/components/my-component.mdx` using this pattern: + +```mdx +--- +title: My Component +description: Brief description of what the component does and when to use it. +--- + +import Example from '…/…/components/Example.astro' + +## Overview + +Brief description. When to use this component. + +## Basic usage + + +
My component content
+ + +## Variants + + +
Variant content
+ +``` + +### 8. Build and verify + +```bash +# Build CSS and JS +npm run dist + +# Lint +npm run lint + +# Run JS tests +npm run js-test + +# Start docs server and verify visual output for all brands +npm run start +# Orange: http://localhost:9001/orange/ +# Sosh: http://localhost:9002/sosh/ +# Orange Compact: http://localhost:9003/orange-compact/ + +# Test dark mode: add data-bs-theme="dark" to container in browser +# Test RTL: add dir="rtl" to in browser +``` + +### Pre-checklist before PR + +- [ ] Design tokens used — no hardcoded values +- [ ] `@include border-radius()` and `@include transition()` — no direct properties +- [ ] `border: 0` — not `border: none` +- [ ] ARIA attributes present and correct +- [ ] `.visually-hidden` on icon-only labels +- [ ] `@include focus-visible()` on `:focus-visible` +- [ ] Dark mode: colors use `var(--#{$prefix}color-*)` +- [ ] RTL: no physical directional hardcoding +- [ ] Tokens added to all 3 brand packages (if new tokens created) +- [ ] `npm run lint` passes +- [ ] `npm run dist` succeeds +- [ ] No `dist/` files committed diff --git a/.packmind/commands/ouds-decision-routing.md b/.packmind/commands/ouds-decision-routing.md new file mode 100644 index 0000000000..5202310a22 --- /dev/null +++ b/.packmind/commands/ouds-decision-routing.md @@ -0,0 +1,202 @@ +--- +name: ouds-decision-routing +description: > + Four decision trees for common OUDS Web development questions: + where to put code, which token to use, whether to update all brands, and how to test a change. +when_to_use: + - You are unsure where to place new code (SCSS, JS, tokens, docs, tests) + - You need to choose the right design token for a CSS property + - You modified a shared file and want to know if all 3 brands need updates + - You need to decide which tests to run for your change type +--- + +# Command: OUDS Web Decision Routing + +## When to Use + +- At any decision point: "Where does this code go?", "Which token?", "Multi-brand update needed?", "How to test?" + +--- + +## Steps + +### Decision Tree 1 — Where should I put this code? + +Follow this tree to locate the right file: + +``` +START: I need to add/modify code +│ +├─ Is it a design token value (color, spacing, dimension)? +│ ├─ YES → Is it a composite token (elevation, font-stack, icon)? +│ │ ├─ YES → Edit packages//scss/tokens/_composite.scss ✅ +│ │ └─ NO → Wait for auto-generated PR from design team ⏸️ +│ │ (Figma → DTCG → Style Dictionary pipeline) +│ │ +├─ Is it SCSS for a component? +│ ├─ YES → Is it specific to one brand? +│ │ ├─ YES → packages//scss/ (rare; consult team first) +│ │ └─ NO → Is it a new component? +│ │ ├─ YES → Create scss/_my-component.scss + update brand token files +│ │ └─ NO → Edit existing scss/_component.scss +│ │ +├─ Is it JavaScript? +│ ├─ YES → js/src/ (shared across all brands — never in packages//) +│ │ +├─ Is it a Bootstrap SCSS variable override? +│ ├─ YES → scss/_variables.scss (light) / scss/_variables-dark.scss (dark) +│ │ +├─ Is it a Sass mixin or function? +│ ├─ YES → scss/mixins/_name.scss or scss/_functions.scss +│ │ Then update scss/_mixins.scss or scss/_functions.scss index +│ │ +├─ Is it documentation? +│ ├─ YES → site/src/content/docs/
/.mdx +│ │ Astro handles brand routes automatically +│ │ +├─ Is it a unit test? +│ ├─ YES → js/tests/unit/.spec.js +│ │ +└─ Is it build configuration? + └─ YES → build/