workspace-architect 1.5.0 → 1.5.2

package/README.md

@@ -1,62 +1,177 @@
 # Workspace Architect
 
-A comprehensive library of specialized AI personas and chat modes for GitHub Copilot, accessible via CLI.
+A comprehensive library of specialized AI personas and chat modes for GitHub Copilot, ranging from architectural planning and specific tech stacks to advanced cognitive reasoning models.
 
-## Usage
+## Overview
 
-You can use this tool directly with `npx` without installing it:
+Workspace Architect is a CLI tool and library designed to enhance your experience with GitHub Copilot. It provides a curated collection of:
+
+*   **Instructions**: Detailed guidelines to set the context for Copilot.
+*   **Prompts**: Reusable prompts for specific tasks like code review or refactoring.
+*   **Chat Modes**: Specialized personas (e.g., "Azure Architect", "React Expert") to guide the conversation.
+*   **Collections**: Grouped assets for specific domains (e.g., "Web Development", "DevOps").
+
+## Why Workspace Architect?
+
+*   **Curated Collections**: Don't waste time hunting for individual prompts. Download a complete "Web Development" or "DevOps" suite in one command.
+*   **Zero Friction**: No installation required. Just run `npx workspace-architect` in any folder.
+*   **Universal Portability**: Works with any project structure. Assets are simple Markdown files that live in your repo.
+*   **Lightweight**: No complex MCP servers or heavy dependencies. Just pure context for Copilot.
+*   **Algorithmic Curation**: Our collections are continuously monitored by an intelligent TF-IDF/Cosine Similarity engine to ensure they always include the most relevant assets and exclude outdated ones with zero regression.
+
+## For Consumers
+
+### Usage
+
+You can use this tool directly with `npx` without installing it globally:
 
 ```bash
-npx workspace-architect download instructions:basic-setup
+npx workspace-architect list
 ```
 
-### Commands
+### Asset Types
+
+*   **Instructions (`instructions`)**: These are system-level instructions or "custom instructions" you can add to your `.github/copilot-instructions.md` or use to prime a session.
+*   **Prompts (`prompts`)**: Specific queries or templates to ask Copilot to perform a task.
+*   **Chat Modes (`chatmodes`)**: Specialized persona definitions that define how Copilot should behave, reason, and respond.
+*   **Collections (`collections`)**: Bundles of the above assets tailored for specific roles or workflows.
+
+### CLI Reference
 
 #### List Available Assets
 
+View all available assets or filter by type:
+
 ```bash
+# List all assets
 npx workspace-architect list
-# or list specific type
+
+# List only instructions
 npx workspace-architect list instructions
+
+# List only collections
+npx workspace-architect list collections
 ```
 
 #### Download an Asset
 
-```bash
-npx workspace-architect download <type>:<name>
-```
+Download a specific asset to your project. By default, assets are downloaded to `.github/<type>/`.
 
-Example:
 ```bash
-npx workspace-architect download prompts:code-review
+npx workspace-architect download <type>:<name>
 ```
 
-Options:
-- `-d, --dry-run`: Simulate the download without writing files.
-- `-f, --force`: Overwrite existing files without asking.
-- `-o, --output <path>`: Specify the output path (default: `.github/<type>`).
+**Examples:**
 
-## Development
-
-### Local Testing
-
-1. Install dependencies:
-   ```bash
-   npm install
-   ```
+```bash
+# Download a specific instruction file
+npx workspace-architect download instructions:reactjs
 
-2. Run the CLI locally:
-   ```bash
-   node bin/cli.js list
-   ```
+# Download a collection of assets
+npx workspace-architect download collections:web-frontend-development
+```
 
-3. Link the package to test `npx` behavior locally (simulated):
-   ```bash
-   npm link
-   npx workspace-architect list
-   ```
+**Options:**
+
+*   `-d, --dry-run`: Simulate the download without writing files. Useful to see where files will be placed.
+*   `-f, --force`: Overwrite existing files without asking for confirmation.
+*   `-o, --output <path>`: Specify a custom output directory.
+
+## For Contributors
+
+We welcome contributions! Whether you want to add a new persona, improve existing prompts, or curate a collection, here is how you can help.
+
+### Project Structure
+
+*   `assets/`: Contains the source markdown and JSON files for all assets.
+    *   `chatmodes/`: Persona definitions.
+    *   `collections/`: JSON files defining groups of assets.
+    *   `instructions/`: Contextual guidelines.
+    *   `prompts/`: Reusable prompt templates.
+*   `bin/`: Contains the CLI entry point (`cli.js`).
+*   `scripts/`: Utility scripts for maintenance and analysis.
+
+### Development Setup
+
+1.  **Clone the repository**:
+    ```bash
+    git clone https://github.com/archubbuck/workspace-architect.git
+    cd workspace-architect
+    ```
+
+2.  **Install dependencies**:
+    ```bash
+    npm install
+    ```
+
+3.  **Run the CLI locally**:
+    You can test your changes by running the CLI script directly:
+    ```bash
+    node bin/cli.js list
+    ```
+
+4.  **Test with Local Registry (Verdaccio)**:
+    For a more accurate simulation of the end-user experience, we use Verdaccio as a local npm registry.
+
+    *   **Start the registry**:
+        ```bash
+        npm run start:registry
+        ```
+    *   **Publish to local registry**:
+        In a new terminal:
+        ```bash
+        npm run publish:local
+        ```
+    *   **Run with `npx`**:
+        ```bash
+        npx --registry http://localhost:4873 workspace-architect list
+        ```
+
+5.  **Quick Local Link (Alternative)**:
+    For rapid iteration without publishing, you can link the package:
+    ```bash
+    npm link
+    npx workspace-architect list
+    ```
+
+### Adding New Assets
+
+1.  Create a new markdown file in the appropriate folder (`assets/instructions`, `assets/prompts`, or `assets/chatmodes`).
+2.  **Naming Convention**: The filename becomes the ID.
+    *   Example: `assets/instructions/my-guide.md` becomes `instructions:my-guide`.
+    *   Extensions like `.chatmode.md` or `.prompt.md` are stripped from the ID but help with organization.
+3.  **Metadata**: You can optionally add YAML frontmatter to your markdown files to provide a description and title.
+
+    ```markdown
+    ---
+    title: My Custom Guide
+    description: A guide for setting up X.
+    ---
+    # Content starts here...
+    ```
+
+### Creating Collections
+
+Collections are JSON files located in `assets/collections/`. They group multiple assets together.
+
+**Format:**
+
+```json
+{
+  "name": "My Collection",
+  "description": "A collection for X development.",
+  "items": [
+    "instructions:reactjs",
+    "prompts:code-review",
+    "chatmodes:expert-architect"
+  ]
+}
+```
 
-## Adding New Assets
+### Scripts
 
-1. Create a new markdown file in `assets/instructions`, `assets/prompts`, or `assets/chatmodes`.
-2. The file name will be the ID used for downloading (e.g., `assets/instructions/my-guide.md` -> `instructions:my-guide`).
+*   **`npm run generate-manifest`**: Generates `assets-manifest.json`. This file is used by the CLI in production to know what assets are available without scanning the file system. **Run this before submitting a PR.**
+*   **`npm run analyze`**: Runs `scripts/analyze-collections.js`. This is an intelligent analysis tool that uses TF-IDF and Cosine Similarity to continuously monitor and regenerate collection profiles. It ensures collections always point to the most relevant assets with zero regression.
+    *   Use `npm run analyze -- --add` to automatically add high-confidence matches.
+    *   Use `npm run analyze -- --remove` to remove low-confidence items.
+*   **`npm run fetch-upstream`**: Syncs assets from the upstream `github/awesome-copilot` repository (requires configuration).

package/assets-manifest.json

@@ -1,6 +1,6 @@
 {
   "version": "1.0.0",
-  "generatedAt": "2025-11-22T00:14:40.955Z",
+  "generatedAt": "2025-11-22T00:52:18.247Z",
   "assets": {
     "chatmodes:4.1-Beast": {
       "path": "assets/chatmodes/4.1-Beast.chatmode.md",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workspace-architect",
-  "version": "1.5.0",
+  "version": "1.5.2",
   "description": "A comprehensive library of specialized AI personas and chat modes for GitHub Copilot, ranging from architectural planning and specific tech stacks to advanced cognitive reasoning models.",
   "bin": {
     "workspace-architect": "./bin/cli.js"
@@ -11,7 +11,7 @@
     "analyze": "node scripts/analyze-collections.js",
     "generate-manifest": "node scripts/generate-manifest.js",
     "prepublishOnly": "npm run generate-manifest",
-    "sync": "node scripts/sync.js",
+    "fetch-upstream": "node scripts/fetch-upstream-assets.js",
     "release": "release-it",
     "publish:local": "npm run release && npm publish --registry http://localhost:4873"
   },