feat: add scaffolding for github releases (#79)

Author: gblanc-1a

.gitignore

@@ -30,7 +30,6 @@ ovsx-*.log
 # Build outputs
 out/
 dist/
-lib/
 build/
 *.tsbuildinfo
 *.js.map
@@ -57,7 +56,6 @@ dist/
 downloads/
 eggs/
 .eggs/
-lib/
 lib64/
 parts/
 sdist/

AGENTS.md

@@ -2,6 +2,20 @@
 
 These are short, actionable notes to help an AI coding assistant be productive in this repository.
 
+**🚨 FIRST STEP: Read Folder-Specific Guidance 🚨**
+
+Before working in any folder, **MUST READ** the corresponding AGENTS.md file:
+- Working with tests? → Read `test/AGENTS.md` first
+- Writing E2E tests? → Read `test/e2e/AGENTS.md` first  
+- Creating adapters? → Read `src/adapters/AGENTS.md` first
+- Building services? → Read `src/services/AGENTS.md` first
+
+**Failure to read these guides will result in:**
+- Broken tests due to incorrect VS Code mocking
+- Duplicated utilities that already exist
+- Missing critical debugging strategies
+- Wasted time on solved problems
+
 ---
 
 ## Development Methodology

CONTRIBUTING.md

@@ -117,6 +117,10 @@ prompt-registry/
 │   ├── types/             # TypeScript type definitions
 │   ├── utils/             # Utility functions
 │   └── extension.ts       # Extension entry point
+├── templates/
+│   └── scaffolds/         # Project scaffolding templates
+│       ├── github/        # GitHub scaffold with CI/CD publishing
+│       └── apm/           # APM package template
 ├── test/
 │   ├── adapters/          # Adapter unit tests
 │   ├── services/          # Service unit tests
@@ -132,9 +136,30 @@ prompt-registry/
 
 - **`src/extension.ts`**: Extension activation and setup
 - **`src/types/registry.ts`**: Core type definitions
+- **`src/commands/ScaffoldCommand.ts`**: Project scaffolding command
 - **[Architecture](docs/contributor-guide/architecture.md)**: Detailed architecture documentation
 - **[Core Flows](docs/contributor-guide/core-flows.md)**: Key system flows and processes
 
+### Scaffolding System
+
+The extension includes a scaffolding system for creating new prompt projects:
+
+| Scaffold Type | Description | Template Location |
+|--------------|-------------|-------------------|
+| **GitHub** | Full-featured template with GitHub Releases CI for automated collection publishing | `templates/scaffolds/github/` |
+| **APM** | APM package template | `templates/scaffolds/apm/` |
+
+**GitHub Scaffold Features:**
+- GitHub Actions workflows for automated publishing
+- Collection validation scripts
+- Example prompts, instructions, and agents
+- Pre-commit hooks for validation
+
+When contributing to scaffolding:
+- Templates use `{{variable}}` syntax for substitution
+- Test changes with `npm run test:unit` (scaffold tests in `test/commands/`)
+- Ensure all generated files are valid and functional
+
 ---
 
 ## How to Contribute

docs/author-guide/validation.md

@@ -8,15 +8,10 @@ Validate your collection files before publishing to catch errors early.
 Ctrl+Shift+P → "Prompt Registry: Validate Collections"
 ```
 
-Validates all `.collection.yml` files in your `collections/` directory.
-
-## Validation with File References
-
-```bash
-Ctrl+Shift+P → "Prompt Registry: Validate Collections (Check File References)"
-```
-
-Also verifies that all referenced files (prompts, instructions, etc.) exist.
+Validates all `.collection.yml` files in your `collections/` directory, including:
+- Schema validation (required fields, formats)
+- File reference checking (all referenced files exist)
+- Duplicate detection (no duplicate IDs or names across collections)
 
 ## What Gets Validated
 
@@ -25,8 +20,10 @@ Also verifies that all referenced files (prompts, instructions, etc.) exist.
 | Required fields | `id`, `name`, `description`, `items` |
 | ID format | Lowercase letters, numbers, hyphens only |
 | Item paths | Valid relative paths |
-| Item kinds | One of: `prompt`, `instruction`, `chat-mode`, `agent` |
-| File references | Referenced files exist (with Check File References) |
+| Item kinds | One of: `prompt`, `instruction`, `agent`, `skill` |
+| File references | Referenced files exist |
+| Duplicate IDs | No two collections share the same ID |
+| Duplicate names | No two collections share the same name |
 
 ## Common Errors
 
@@ -37,11 +34,17 @@ Also verifies that all referenced files (prompts, instructions, etc.) exist.
 → Use only lowercase letters, numbers, and hyphens (e.g., `my-collection`)
 
 **Invalid item kind**
-→ Use one of: `prompt`, `instruction`, `chat-mode`, `agent`
+→ Use one of: `prompt`, `instruction`, `agent`, `skill`
 
 **File not found**
 → Check that the path in `items[].path` points to an existing file
 
+**Duplicate collection ID**
+→ Each collection must have a unique ID across the repository
+
+**Duplicate collection name**
+→ Each collection must have a unique name across the repository
+
 ## See Also
 
 - [Collection Schema](./collection-schema.md) — Full YAML reference

docs/contributor-guide/architecture/scaffolding.md

@@ -23,7 +23,7 @@ export enum ScaffoldType {
 **Awesome Copilot Template:**
 ```mermaid
 graph TD
-    A["templates/scaffolds/awesome-copilot/"]
+    A["templates/scaffolds/github/"]
     B["manifest.json<br/># Template metadata"]
     C["package.template.json<br/># Project package (with variables)"]
     D["README.template.md"]

docs/contributor-guide/architecture/validation.md

@@ -48,12 +48,14 @@ flowchart TD
     C --> D[SchemaValidator.validateCollection]
     D --> E[1. Schema validation AJV]
     D --> F[2. Format errors to user-friendly messages]
-    D --> G[3. Check file references optional]
+    D --> G[3. Check file references]
     D --> H[4. Generate best practice warnings]
-    E --> I[Display in Output Channel + VS Code Diagnostics]
-    F --> I
-    G --> I
-    H --> I
+    D --> I[5. Detect duplicate IDs/names]
+    E --> J[Display in Output Channel + VS Code Diagnostics]
+    F --> J
+    G --> J
+    H --> J
+    I --> J
 ```
 
 ## Error Formatting
@@ -62,16 +64,18 @@ flowchart TD
 |------------|---------|
 | Required field | `Missing required field: description` |
 | Pattern mismatch | `/id: must match pattern ^[a-z0-9-]+$` |
-| Enum violation | `kind: must be one of: prompt, instruction, chat-mode, agent` |
+| Enum violation | `kind: must be one of: prompt, instruction, agent, skill` |
 | Type mismatch | `/version: must be string` |
 | Length violation | `description: must be at most 500 characters` |
 | Additional property | `/: has unexpected property 'foo'` |
+| Duplicate ID | `Duplicate collection ID 'my-id' (also in other.collection.yml)` |
+| Duplicate name | `Duplicate collection name 'My Name' (also in other.collection.yml)` |
 
 ## Performance
 
 - **Schema Caching**: Compiled schemas cached in Map
 - **Lazy Loading**: Schemas loaded on first use
-- **Efficient File Checking**: Only when `checkFileReferences` enabled
+- **File Reference Checking**: Always enabled for complete validation
 
 ## Validation Schemas
 
@@ -95,7 +99,7 @@ The extension provides JSON Schema validation for all major configuration file t
 - `mcp` — Model Context Protocol server configurations
 - `display` — UI display preferences (color, icon, ordering)
 
-**Item types supported:** `prompt`, `instruction`, `chat-mode`, `agent`
+**Item types supported:** `prompt`, `instruction`, `agent`, `skill`
 
 **Validation features:**
 - File reference checking (when `checkFileReferences` enabled)

docs/migration-guide.md

@@ -0,0 +1,74 @@
+# Migration Guide
+
+This guide helps you migrate from deprecated project structures to the current GitHub scaffold format.
+
+## Adding GitHub Releases CI to Existing Collections
+
+If you have a repository with a `collections/` folder but no GitHub Actions workflow for publishing releases, follow these steps:
+
+### Quick Setup
+
+1. Run the scaffold command in your existing project directory:
+   ```bash
+   # From VS Code Command Palette: "Prompt Registry: Scaffold Project" → "GitHub"
+   ```
+
+2. Delete the generated example files:
+   ```bash
+   rm -rf prompts/example.prompt.md instructions/example.instructions.md agents/example.agent.md collections/example.collection.yml skills/example-skill
+   ```
+
+3. Push to main branch to trigger the first release.
+
+### What Gets Added
+
+- `.github/workflows/publish.yml` - Automated release workflow
+- `.github/actions/` - Reusable GitHub Actions
+- `scripts/` - Build and validation scripts
+- `package.json` - npm dependencies for validation
+
+## Migrating Chatmode Files to Agent Files {#chatmode-to-agent}
+
+The `chatmode` kind has been replaced by `agent`. If your collection files reference `.chatmode.md` files or use `kind: chatmode`, follow these steps:
+
+### Step 1: Rename Files
+
+Rename all `.chatmode.md` files to `.agent.md`:
+
+```bash
+# Find and rename all chatmode files
+find . -name "*.chatmode.md" -exec sh -c 'mv "$1" "${1%.chatmode.md}.agent.md"' _ {} \;
+```
+
+### Step 2: Update Collection YAML Files
+
+In your collection YAML files, change:
+
+```yaml
+# Before
+items:
+  - kind: chatmode
+    path: chatmodes/my-mode.chatmode.md
+
+# After  
+items:
+  - kind: agent
+    path: agents/my-mode.agent.md
+```
+
+### Step 3: Move Files to Agents Directory
+
+If you have a `chatmodes/` directory, rename it to `agents/`:
+
+```bash
+mv chatmodes agents
+```
+
+### Step 4: Update File References
+
+Search your codebase for any remaining references to chatmode files and update them.
+
+## Need Help?
+
+- [GitHub Scaffold Documentation](https://github.com/prompt-registry/docs)
+- [Collection Schema Reference](../docs/author-guide/collection-schema.md)

docs/reference/commands.md

@@ -85,8 +85,7 @@ This document lists all VS Code commands provided by the Prompt Registry extensi
 | Command | Title | Description |
 |---------|-------|-------------|
 | `promptRegistry.createCollection` | Create New Collection | Create a new prompt collection |
-| `promptRegistry.validateCollections` | Validate Collections | Validate collection YAML files |
-| `promptRegistry.validateCollectionsWithRefs` | Validate Collections (Check File References) | Validate collections including file references |
+| `promptRegistry.validateCollections` | Validate Collections | Validate collection YAML files including file references and duplicate detection |
 | `promptRegistry.validateApm` | Validate APM Package | Validate an APM package |
 | `promptRegistry.listCollections` | List All Collections | Display all collections |
 

package.json

@@ -105,11 +105,6 @@
         "title": "Validate APM Package",
         "category": "Prompt Registry"
       },
-      {
-        "command": "promptRegistry.validateCollectionsWithRefs",
-        "title": "Validate Collections (Check File References)",
-        "category": "Prompt Registry"
-      },
       {
         "command": "promptRegistry.listCollections",
         "title": "List All Collections",
@@ -712,7 +707,7 @@
     "lint": "eslint src --ext ts",
     "test": "npm run test:all",
     "test:one": "node scripts/run-single-test.js",
-    "test:unit": "npx mocha --ui tdd --require ./test/mocha.setup.js --require ./test/unit.setup.js 'test-dist/test/{adapters,commands,services,utils}/**/*.test.js' --timeout 5000",
+    "test:unit": "npx mocha --ui tdd --require ./test/mocha.setup.js --require ./test/unit.setup.js 'test-dist/test/{adapters,commands,services,utils,scripts}/**/*.test.js' --timeout 5000",
     "test:integration": "npm run compile-tests && node ./test/runExtensionTests.js",
     "test:all": "npm run compile-tests && npm run test:unit && npm run test:integration",
     "test:coverage": "npm run compile-tests && c8 npm run test:all",

src/adapters/GitHubAdapter.ts

@@ -10,6 +10,7 @@ import { promisify } from 'util';
 import { RepositoryAdapter } from './RepositoryAdapter';
 import { Bundle, SourceMetadata, ValidationResult, RegistrySource } from '../types/registry';
 import { Logger } from '../utils/logger';
+import { generateGitHubBundleId, formatByteSize } from '../utils/bundleNameUtils';
 
 const execAsync = promisify(exec);
 
@@ -522,8 +523,16 @@ export class GitHubAdapter extends RepositoryAdapter {
                 // Create bundle metadata
                 // Use manifest data if available, otherwise fall back to release data
                 // Use API URL instead of browser_download_url for proper authentication
+                // Bundle ID uses canonical generation function for consistency
+                const bundleId = generateGitHubBundleId(
+                    owner,
+                    repo,
+                    release.tag_name,
+                    manifest?.id,
+                    manifest?.version
+                );
                 const bundle: Bundle = {
-                    id: `${owner}-${repo}-${release.tag_name}`,
+                    id: bundleId,
                     name: manifest?.name || release.name || `${repo} ${release.tag_name}`,
                     version: manifest?.version || release.tag_name.replace(/^v/, ''),
                     description: manifest?.description || this.extractDescription(release.body),
@@ -532,14 +541,19 @@ export class GitHubAdapter extends RepositoryAdapter {
                     environments: manifest?.environments || this.extractEnvironments(release.body),
                     tags: manifest?.tags || this.extractTags(release.body),
                     lastUpdated: release.published_at,
-                    size: this.formatSize(bundleAsset.size),
+                    size: formatByteSize(bundleAsset.size),
                     dependencies: manifest?.dependencies || [],
                     license: manifest?.license || 'Unknown',
                     manifestUrl: manifestAsset.url,
                     downloadUrl: bundleAsset.url,
                     repository: this.source.url,
                 };
 
+                // Attach prompts array from manifest for content breakdown display
+                if (manifest?.prompts && Array.isArray(manifest.prompts)) {
+                    (bundle as any).prompts = manifest.prompts;
+                }
+
                 bundles.push(bundle);
             }
 
@@ -732,17 +746,4 @@ export class GitHubAdapter extends RepositoryAdapter {
 
         return tags;
     }
-
-    /**
-     * Format byte size to human readable
-     */
-    private formatSize(bytes: number): string {
-        if (bytes < 1024) {
-            return `${bytes} B`;
-        }
-        if (bytes < 1024 * 1024) {
-            return `${(bytes / 1024).toFixed(1)} KB`;
-        }
-        return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
-    }
 }