From d2ad89d907dd020018b54ed722e1cacca37f57ee Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Mon, 30 Jun 2025 18:01:57 +0000 Subject: [PATCH] docs: Setup GitHub Pages and reorganize documentation - I created a /docs folder structured for GitHub Pages. - I moved user-facing documentation from README.md to /docs, including: - docs/index.md (new landing page) - docs/getting-started.md - docs/usage.md - docs/configuration.md - docs/module-development.md - I updated content in /docs with clear titles, headings, internal navigation, and tables of contents. - I shortened README.md to be a concise summary, linking to the GitHub Pages site (with a placeholder URL). - I added a placeholder badge for GitHub Pages to README.md. - I created CONTRIBUTING.md with a section on how to update documentation. - I provided instructions for enabling GitHub Pages in the repository settings. --- CONTRIBUTING.md | 51 ++++++ README.md | 320 ++----------------------------------- docs/configuration.md | 73 +++++++++ docs/getting-started.md | 23 +++ docs/index.md | 28 ++++ docs/module-development.md | 121 ++++++++++++++ docs/usage.md | 139 ++++++++++++++++ 7 files changed, 444 insertions(+), 311 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 docs/configuration.md create mode 100644 docs/getting-started.md create mode 100644 docs/index.md create mode 100644 docs/module-development.md create mode 100644 docs/usage.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..8568a97 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,51 @@ +# Contributing to Copilot Instructions Builder CLI + +First off, thank you for considering contributing to the Copilot Instructions Builder CLI! Your help is greatly appreciated. Whether it's reporting a bug, discussing improvements, or submitting a pull request, every contribution is valuable. + +## How to Contribute + +We follow a standard GitHub workflow for contributions: + +1. **Fork the Repository**: Start by forking the [main repository]([YOUR_GITHUB_REPO_URL_HERE]) to your own GitHub account. +2. **Clone Your Fork**: Clone your forked repository to your local machine. + ```bash + git clone https://github.com/YOUR_USERNAME/copilot-instructions-builder.git + ``` +3. **Create a Branch**: Create a new branch for your changes. Choose a descriptive name (e.g., `feature/add-new-command` or `bugfix/resolve-merge-conflict`). + ```bash + git checkout -b your-branch-name + ``` +4. **Make Your Changes**: Implement your feature, fix the bug, or improve the documentation. +5. **Test Your Changes**: If you've added code that should be tested, please add tests and ensure all tests pass (`npm test`). +6. **Commit Your Changes**: Write clear, concise commit messages. + ```bash + git commit -m "feat: Add new feature" -m "Detailed description of the feature." + ``` +7. **Push to Your Fork**: Push your changes to your forked repository. + ```bash + git push origin your-branch-name + ``` +8. **Submit a Pull Request (PR)**: Open a pull request from your branch to the `main` branch of the original repository. Provide a clear description of your changes in the PR. + +## Updating Documentation + +Our user-facing documentation is located in the `/docs` folder. This content is used to generate our GitHub Pages documentation site. + +Key documentation files include: +- `docs/index.md`: The main landing page for the documentation. +- `docs/getting-started.md`: Installation and initial setup. +- `docs/usage.md`: How to use the CLI commands. +- `docs/configuration.md`: Details on the `copilot-instructions.config.js` file. +- `docs/module-development.md`: How to create custom modules. + +**If your contribution affects any user-facing aspects of the project (e.g., new commands, changes to existing commands, configuration options, module structure), please ensure you update the relevant parts of the documentation in the `/docs` folder.** + +Updates to these files will be reflected on the GitHub Pages site after they are merged. + +## Code of Conduct + +While we don't have a formal Code of Conduct document yet, we expect all contributors to interact respectfully and constructively. Please be kind and considerate when communicating. + +--- + +Thank you again for your interest in contributing! diff --git a/README.md b/README.md index 558ba5b..9f97fd7 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,7 @@ [![npm version](https://badge.fury.io/js/copilot-instructions-builder.svg)](https://badge.fury.io/js/copilot-instructions-builder) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/) +[![Documentation Status](https://img.shields.io/badge/docs-view_site-success)]([YOUR_GITHUB_PAGES_URL_HERE]) A powerful CLI application for building GitHub Copilot instruction files from modular, hierarchical components. Create sophisticated instruction sets using a three-tier architecture: **Base Instructions** → **Domain-Specific Layers** → **Task-Specific Modules**. @@ -30,272 +31,16 @@ A powerful CLI application for building GitHub Copilot instruction files from mo npm install -g copilot-instructions ``` -### Initialize a New Project - -```bash -copilot-instructions init -``` - -### Quick Build with Modules - -```bash -# Build with specific modules -copilot-instructions build --base programming-fundamentals --domain frontend/react --task ui-components - -# Build from configuration file -copilot-instructions build - -# Build specific profile -copilot-instructions build --profile production -``` - -### List Available Modules - -```bash -# List all modules -copilot-instructions list - -# Filter by type and tags -copilot-instructions list --type domain --tags react,frontend -``` - -## 🏗️ Architecture Overview - -### Hierarchical Instruction System - -``` -Base Instructions (Foundation) - ↓ -Domain Layers (Technology-specific) - ↓ -Task Modules (Use case-specific) - ↓ -.copilot-instructions.md (Output) -``` - -### Module Types - -- **Base Instructions**: General programming principles, code quality, documentation standards -- **Domain Layers**: Technology-specific guidance (React, Node.js, Python, etc.) -- **Task Modules**: Specific use cases (API development, UI components, testing, etc.) - -## 📁 Project Structure - -``` -copilot-instructions-builder/ -├── src/ -│ ├── core/ # Core composition engine -│ │ ├── composer.js # Main instruction composition -│ │ ├── resolver.js # Dependency resolution -│ │ ├── conflict-resolver.js # Conflict handling -│ │ └── ... -│ ├── modules/ # Module management -│ ├── commands/ # CLI commands -│ └── utils/ # Utilities and helpers -├── modules/ # Built-in instruction modules -│ ├── base/ # Foundation modules -│ ├── domains/ # Technology-specific modules -│ └── tasks/ # Use case modules -└── templates/ # Output templates -``` - -## 🔧 CLI Commands - -### Core Operations - -```bash -# Initialize project configuration -copilot-instructions init - -# List available modules -copilot-instructions list [--type base|domain|task] [--tags react,frontend] - -# Build instructions from modules -copilot-instructions build --base programming-fundamentals --domain frontend/react --task ui-components - -# Add module to existing config -copilot-instructions add frontend/vue - -# Validate configuration -copilot-instructions validate - -# Show module dependencies -copilot-instructions deps frontend/react - -# Search modules -copilot-instructions search "api development" -``` - -### Configuration-Driven Operations - -```bash -# Build from configuration file -copilot-instructions build - -# Build specific profile -copilot-instructions build --profile production - -# Use custom config file -copilot-instructions build --config ./configs/backend.config.js - -# Build all profiles -copilot-instructions build --all-profiles -``` - -## 📝 Module Structure - -Each instruction module follows a standardized JSON format: - -```json -{ - "id": "module-identifier", - "name": "Module Display Name", - "type": "base|domain|task", - "version": "1.0.0", - "dependencies": ["required-module-ids"], - "conflicts": ["conflicting-module-ids"], - "tags": ["react", "frontend", "ui"], - "priority": 100, - "metadata": { - "description": "Module description", - "author": "author-name", - "category": "frontend|backend|testing|devops|general" - }, - "instructions": { - "sections": [ - { - "id": "section-identifier", - "title": "Section Title", - "priority": 100, - "merge_strategy": "replace|append|prepend|smart_merge", - "content": ["instruction 1", "instruction 2"], - "conditions": { - "include_if": ["tag1", "tag2"], - "exclude_if": ["tag3"], - "require_modules": ["module-id"] - } - } - ] - }, - "variables": { - "projectName": "{{PROJECT_NAME}}", - "framework": "{{FRAMEWORK}}" - } -} -``` - -## 🎯 Key Features - -### Smart Dependency Resolution - -- **Cycle Detection**: Prevents circular dependencies with detailed error reporting -- **Topological Sorting**: Ensures correct module loading order -- **Conflict Detection**: Identifies and resolves module conflicts automatically - -### Intelligent Merging - -- **Content-Aware**: Understands different types of content (rules, examples, guidelines) -- **Deduplication**: Removes duplicate instructions automatically -- **Priority-Based**: Respects module and section priorities during merging - -### Template Variables - -```json -{ - "variables": { - "projectName": "{{PROJECT_NAME}}", - "framework": "{{FRAMEWORK || 'React'}}" - } -} -``` - -Supports: - -- Simple variables: `{{VAR}}` -- Default values: `{{VAR || 'default'}}` -- Function calls: `{{func(args)}}` - -### Conditional Instructions - -```json -{ - "conditions": { - "include_if": ["react", "frontend"], - "exclude_if": ["vue"], - "require_modules": ["base-frontend"], - "conflict_with": ["legacy-module"] - } -} -``` - -## ⚙️ Configuration - -### Project Configuration File - -Create a [`copilot-instructions.config.js`](./docs/builder-config.md) file: - -```javascript -module.exports = { - profiles: { - development: { - modules: ['programming-fundamentals', 'frontend/react', 'ui-components'], - variables: { - PROJECT_NAME: 'My App', - FRAMEWORK: 'React', - }, - }, - production: { - modules: [ - 'programming-fundamentals', - 'frontend/react', - 'ui-components', - 'performance-optimization', - ], - }, - }, - output: { - file: '.copilot-instructions.md', - template: 'default', - }, -}; -``` - -## 🔍 Examples - -### Building a React Frontend Project - -```bash -# Quick command approach -copilot-instructions build \ - --base programming-fundamentals,code-quality \ - --domain frontend/react \ - --task ui-components,performance-optimization - -# Configuration approach -copilot-instructions init -# Edit copilot-instructions.config.js -copilot-instructions build --profile frontend -``` - -### Building a Node.js API - -```bash -copilot-instructions build \ - --base programming-fundamentals,documentation \ - --domain backend/nodejs \ - --task api-development,database-design -``` - -### Custom Module Discovery +## 📚 Documentation -```bash -# Search for modules -copilot-instructions search "testing" -copilot-instructions search "performance" +For detailed documentation, including setup, usage, configuration, and module development, please visit our **[GitHub Pages documentation site]([YOUR_GITHUB_PAGES_URL_HERE])**. -# List modules by category -copilot-instructions list --type task --tags api,backend -``` +The full documentation includes: +- Getting Started Guide +- Detailed Usage Instructions +- Configuration Options +- Module Development Guide +- Project Architecture and more. ## 🛠️ Development @@ -308,53 +53,6 @@ copilot-instructions list --type task --tags api,backend 5. Run tests: `npm test` 6. Submit a pull request -### Adding Custom Modules - -Create new modules in the [`modules/`](./modules/) directory following the [module structure](#-module-structure). See our [architecture documentation](./docs/architecture-plan.md) for detailed guidelines. - -### Testing - -```bash -# Run all tests -npm test - -# Run specific test suites -npm run test:unit -npm run test:integration -npm run test:performance -``` - -## 🔧 Advanced Features - -### Error Handling - -The CLI provides detailed error messages and recovery suggestions: - -- **Circular Dependencies**: Suggests breaking changes -- **Module Conflicts**: Offers interactive resolution -- **Invalid Configuration**: Provides schema validation help -- **Template Errors**: Includes variable debugging information - -### Performance Optimizations - -- **Lazy Loading**: Modules loaded only when needed -- **Incremental Builds**: Only rebuild changed dependencies -- **Parallel Processing**: Concurrent resolution of independent modules -- **Multi-level Caching**: Optimized module and result caching - -## 📚 Documentation - -- [Architecture Plan](./docs/architecture-plan.md) - Detailed technical architecture -- [Configuration Guide](./docs/builder-config.md) - Configuration options and examples -- [Module Development](./docs/module-development.md) - Creating custom modules -- [API Reference](./docs/api-reference.md) - Programmatic usage - -## 🤝 Support - -- 📧 Issues: [GitHub Issues](https://github.com/your-org/copilot-instructions-builder/issues) -- 💬 Discussions: [GitHub Discussions](https://github.com/your-org/copilot-instructions-builder/discussions) -- 📖 Wiki: [Project Wiki](https://github.com/your-org/copilot-instructions-builder/wiki) - ## 📄 License This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details. diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..829dfae --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,73 @@ +# Configuration + +The Copilot Instructions Builder CLI uses a JavaScript configuration file, typically named `copilot-instructions.config.js`, to manage how your instruction files are built. This file defines profiles, modules, variables, and output settings. + +## Table of Contents +- [Project Configuration File](#project-configuration-file) + - [Example `copilot-instructions.config.js`](#example-copilot-instructionsconfigjs) + - [Configuration Structure](#configuration-structure) +- [Using Profiles](#using-profiles) + +## Project Configuration File + +You can create this file manually or by using the `copilot-instructions init` command as described in the **[Getting Started Guide](./getting-started.md#initialize-a-new-project)**. It should be placed in the root directory of your project. + +**Example `copilot-instructions.config.js`:** +```javascript +module.exports = { + profiles: { + development: { + modules: ['programming-fundamentals', 'frontend/react', 'ui-components'], + variables: { + PROJECT_NAME: 'My App', + FRAMEWORK: 'React', + }, + }, + production: { + modules: [ + 'programming-fundamentals', + 'frontend/react', + 'ui-components', + 'performance-optimization', + ], + variables: { + PROJECT_NAME: 'My Production App', + FRAMEWORK: 'React', + }, + }, + }, + output: { + file: '.copilot-instructions.md', // Output file name + template: 'default', // Output template (e.g., default, markdown, json) + }, + // Optional: Global settings for all profiles + // globalVariables: { + // COMPANY_NAME: 'My Company', + // }, + // modulePaths: ['./custom-modules'], // Paths to custom module directories +}; +``` + +### Configuration Structure: + +The configuration object exported by `copilot-instructions.config.js` can have the following main properties: + +* **`profiles`**: (Object) A collection where each key is a profile name (e.g., `development`, `production`). Each profile object contains: + * **`modules`**: (Array of Strings) An array of module IDs to include for this profile. These modules define the actual instructions. For more on creating modules, see the **[Module Development Guide](./module-development.md)**. + * **`variables`**: (Object) Key-value pairs for template substitution within the instructions provided by the modules. These allow for dynamic content in your Copilot instructions. +* **`output`**: (Object) Settings related to the generated output file. + * **`file`**: (String) The name of the generated Copilot instructions file (default: `.copilot-instructions.md`). + * **`template`**: (String) The template to use for formatting the output (e.g., `default`, `markdown`, `json`). +* **`globalVariables`** (Optional Object): Defines variables that apply to all profiles. Profile-specific variables will override global variables if they share the same key. +* **`modulePaths`** (Optional Array of Strings): Specifies directories where custom modules are located. This allows the CLI to discover modules beyond any built-in ones. Refer to the **[Module Development Guide](./module-development.md)** for creating custom modules. + +## Using Profiles + +Profiles allow you to maintain different instruction sets for various contexts (e.g., development vs. production, different project types). You can build instructions for a specific profile using the `--profile` flag with the `build` command: + +```bash +copilot-instructions build --profile development +``` +For more details on build commands, see the **[Usage Guide](./usage.md#configuration-driven-operations)**. + +If no profile is specified when running `copilot-instructions build`, the CLI behavior might vary (e.g., use a profile named `default` if it exists, or require a profile to be explicitly named). Check the specific version's documentation or CLI help (`copilot-instructions build --help`) for precise default behaviors. diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000..1980806 --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,23 @@ +# Getting Started + +This guide will walk you through installing the Copilot Instructions Builder CLI and starting your first project. + +## Installation + +To use the CLI, you need to have Node.js (version 18.0.0 or higher) installed. You can install the CLI globally using npm: + +```bash +npm install -g copilot-instructions +``` +This will make the `copilot-instructions` command available in your terminal. + +## Initialize a New Project + +Once installed, you can initialize a new project. Navigate to your desired project directory and run: + +```bash +copilot-instructions init +``` +This command creates a default configuration file (usually `copilot-instructions.config.js`) in your current directory. This file is where you'll define your instruction profiles, modules, and variables. + +After initialization, you'll want to understand and customize this configuration. Learn more about it in the **[Configuration Guide](./configuration.md)**. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..77f1a90 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,28 @@ +# Copilot Instructions Builder CLI + +A powerful CLI application for building GitHub Copilot instruction files from modular, hierarchical components. Create sophisticated instruction sets using a three-tier architecture: **Base Instructions** → **Domain-Specific Layers** → **Task-Specific Modules**. + +## 🚀 Features + +- **Hierarchical Module System**: Compose instructions from base, domain, and task-specific modules +- **Smart Dependency Resolution**: Automatic dependency management with cycle detection +- **Intelligent Conflict Resolution**: Handle module conflicts with multiple resolution strategies +- **Advanced Merging**: Smart content merging with semantic understanding +- **Template Variables**: Dynamic content generation with variable substitution +- **Conditional Instructions**: Include/exclude sections based on context and conditions +- **Priority-Based Ordering**: Sophisticated priority calculation for optimal instruction ordering +- **Interactive CLI**: Both command-driven and configuration-driven workflows +- **Performance Optimized**: Caching, lazy loading, and parallel processing + +## 📖 Table of Contents + +This documentation is organized into the following sections: + +- **[Getting Started](./getting-started.md)**: Installation and project initialization. +- **[Usage](./usage.md)**: How to use the CLI for building instructions, listing modules, and more. +- **[Configuration](./configuration.md)**: Detailed guide on the project configuration file. +- **[Module Development](./module-development.md)**: How to create your own custom modules. + +For developers interested in the project's architecture or task planning: +- **[Architecture Plan](./architecture-plan.md)**: Technical details of the CLI's design. +- **[Tasks](./tasks.md)**: Development tasks (primarily for contributors). diff --git a/docs/module-development.md b/docs/module-development.md new file mode 100644 index 0000000..4cff28f --- /dev/null +++ b/docs/module-development.md @@ -0,0 +1,121 @@ +# Module Development + +Developing custom modules allows you to tailor GitHub Copilot's guidance to your project's specific needs, coding standards, and architectural patterns. This guide explains the structure of a module and how to create your own. + +## Table of Contents +- [Module Structure](#module-structure) + - [Example JSON Structure](#example-json-structure) + - [Key Fields Explained](#key-fields-explained) +- [Creating Custom Modules](#creating-custom-modules) + +## Module Structure + +Each instruction module is a JSON file that defines its properties, dependencies, and the instructions it provides. + +### Example JSON Structure +```json +{ + "id": "module-identifier", + "name": "Module Display Name", + "type": "base|domain|task", + "version": "1.0.0", + "dependencies": ["required-module-ids"], + "conflicts": ["conflicting-module-ids"], + "tags": ["react", "frontend", "ui"], + "priority": 100, + "metadata": { + "description": "A concise description of what this module does.", + "author": "Your Name or Team", + "category": "frontend|backend|testing|devops|general|custom" + }, + "instructions": { + "sections": [ + { + "id": "section-identifier", + "title": "Descriptive Section Title", + "priority": 100, + "merge_strategy": "replace|append|prepend|smart_merge", + "content": [ + "Instruction point 1: Be clear and concise.", + "Instruction point 2: Use active voice.", + "Instruction point 3: Provide examples where helpful, like {{EXAMPLE_VARIABLE}}." + ], + "conditions": { + "include_if": ["tag1", "another-module-id"], + "exclude_if": ["specific-tag-to-avoid"], + "require_modules": ["essential-module-dependency"] + } + } + ] + }, + "variables": { + "EXAMPLE_VARIABLE": "This is an example value for a variable.", + "projectName": "{{PROJECT_NAME}}", + "framework": "{{FRAMEWORK || 'DefaultFramework'}}" + } +} +``` + +### Key Fields Explained: + +* **`id`**: (String) A unique identifier for the module (e.g., `custom-auth-rules`). This ID is used in dependencies and configurations. +* **`name`**: (String) A human-readable name for the module (e.g., "Custom Authentication Rules"). +* **`type`**: (String) The type of module. Must be one of: + * `base`: Foundational instructions, broadly applicable. + * `domain`: Instructions specific to a technology or area (e.g., `frontend/react`, `backend/nodejs`). + * `task`: Instructions for a specific development task (e.g., `api-design`, `ui-component-style`). +* **`version`**: (String) The version of the module (e.g., `1.0.0`), following semantic versioning if possible. +* **`dependencies`**: (Array of Strings) A list of module IDs that this module depends on. These will be loaded and processed before this module. +* **`conflicts`**: (Array of Strings) A list of module IDs that this module conflicts with. The CLI will attempt to resolve these conflicts based on its configuration. +* **`tags`**: (Array of Strings) Keywords or tags associated with the module, used for searching and conditional inclusion (e.g., `security`, `performance`, `react`). +* **`priority`**: (Number) A numerical value indicating the importance of this module or its instructions relative to others. Higher numbers typically mean higher priority. +* **`metadata`**: (Object) Contains additional information about the module. + * **`description`**: (String) A brief explanation of the module's purpose. + * **`author`**: (String) The creator of the module. + * **`category`**: (String) Helps in organizing modules (e.g., `frontend`, `data`, `utils`). +* **`instructions`**: (Object) Defines the actual instructional content. + * **`sections`**: (Array of Objects) Modules can have one or more sections, each representing a block of related instructions. + * **`id`**: (String) A unique identifier for the section within the module. + * **`title`**: (String) The title of the instruction section, often used as a heading. + * **`priority`**: (Number) Priority for this specific section, influencing its order or precedence during merges. + * **`merge_strategy`**: (String) How this section's content should be merged if another module provides a section with the same ID or title. Options: + * `replace`: This section replaces the other. + * `append`: Content from this section is added after the other. + * `prepend`: Content from this section is added before the other. + * `smart_merge`: The CLI attempts an intelligent merge (details depend on CLI capabilities). + * **`content`**: (Array of Strings) The actual lines of instruction. + * **`conditions`**: (Object) Rules to determine if this section should be included. + * `include_if`: (Array of Strings) Include if any of these tags or module IDs are active. + * `exclude_if`: (Array of Strings) Exclude if any of these tags or module IDs are active. + * `require_modules`: (Array of Strings) Include only if all these module IDs are present and active. +* **`variables`**: (Object) Defines variables that can be used within the `content` of instructions (e.g., `{{MY_VARIABLE}}`). These can be placeholders for values provided by profiles or global settings from the `copilot-instructions.config.js`. Supports default values like `{{VAR || 'default_value'}}`. For more on how variables are supplied, see the **[Configuration Guide](./configuration.md#configuration-structure)**. + +## Creating Custom Modules: + +1. **Create a JSON File**: Start by creating a new `.json` file for your module (e.g., `my-custom-auth.json`). +2. **Define the Module**: Populate the file using the structure and fields described above. Ensure you provide at least `id`, `name`, `type`, and `instructions`. +3. **Place Your Module**: Put your custom module file into a directory that the CLI can access. It's recommended to create a dedicated folder (e.g., `custom-modules/`) in your project. +4. **Configure Module Path**: Add the path to this directory in your `copilot-instructions.config.js` file under the `modulePaths` array. For example: + ```javascript + // in copilot-instructions.config.js + module.exports = { + // ... other configurations + modulePaths: ['./custom-modules'], // CLI will look for modules here + }; + ``` + See the **[Configuration Guide](./configuration.md#configuration-structure)** for more on `modulePaths`. +5. **Use Your Module**: Reference the module by its `id` in the `modules` array of any profile within your `copilot-instructions.config.js`. + ```javascript + // in copilot-instructions.config.js + module.exports = { + profiles: { + myProfile: { + modules: ['base-common', 'my-custom-auth'], // Added your custom module + // ... + }, + }, + // ... + }; + ``` + +By following these steps, you can extend the capabilities of the Copilot Instructions Builder with your own tailored instruction sets. This allows for fine-grained control over the guidance GitHub Copilot receives, ensuring it aligns perfectly with your project's unique requirements. diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 0000000..03f021b --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,139 @@ +# Usage + +This section explains how to use the Copilot Instructions Builder CLI to manage and build your instruction sets. + +## Table of Contents +- [Quick Build with Modules](#quick-build-with-modules) +- [List Available Modules](#list-available-modules) +- [CLI Commands](#cli-commands) + - [Core Operations](#core-operations) + - [Configuration-Driven Operations](#configuration-driven-operations) +- [Examples](#examples) + - [Building a React Frontend Project](#building-a-react-frontend-project) + - [Building a Node.js API](#building-a-nodejs-api) + - [Custom Module Discovery](#custom-module-discovery) + +## Quick Build with Modules + +You can quickly build instruction files by specifying modules directly on the command line or by using a project configuration file. + +```bash +# Build with specific modules +copilot-instructions build --base programming-fundamentals --domain frontend/react --task ui-components + +# Build from configuration file +copilot-instructions build +``` +Building from a configuration file is powerful for managing complex setups. See the **[Configuration Guide](./configuration.md)** for details on this file. + +```bash +# Build specific profile from configuration +copilot-instructions build --profile production +``` +Profiles are also defined in the **[Configuration Guide](./configuration.md)**. + +## List Available Modules + +Discover available modules that you can use in your project: + +```bash +# List all modules +copilot-instructions list + +# Filter by type and tags +copilot-instructions list --type domain --tags react,frontend +``` + +## CLI Commands + +The CLI offers a range of commands for various operations. + +### Core Operations + +These commands work directly without necessarily needing a full configuration file, though some can be influenced by it. + +```bash +# Initialize project configuration (creates copilot-instructions.config.js) +copilot-instructions init +# Learn more in the [Getting Started Guide](./getting-started.md#initialize-a-new-project) and [Configuration Guide](./configuration.md) + +# List available modules +copilot-instructions list [--type base|domain|task] [--tags react,frontend] + +# Build instructions from modules specified directly +copilot-instructions build --base programming-fundamentals --domain frontend/react --task ui-components + +# Add module to an existing config file (if present) +copilot-instructions add frontend/vue +# This modifies your [copilot-instructions.config.js](./configuration.md) + +# Validate configuration +copilot-instructions validate +# Checks the syntax and integrity of your [copilot-instructions.config.js](./configuration.md) + +# Show module dependencies +copilot-instructions deps frontend/react + +# Search modules +copilot-instructions search "api development" +``` + +### Configuration-Driven Operations + +These commands primarily rely on a `copilot-instructions.config.js` file. See the **[Configuration Guide](./configuration.md)** for how to set this up. + +```bash +# Build from configuration file (uses default profile or requires one if no default) +copilot-instructions build + +# Build specific profile defined in the configuration +copilot-instructions build --profile production + +# Use custom config file path +copilot-instructions build --config ./configs/backend.config.js + +# Build all profiles defined in the configuration +copilot-instructions build --all-profiles +``` + +## Examples + +Here are a few examples of how you might use the CLI. + +### Building a React Frontend Project + +```bash +# Quick command approach (modules specified directly) +copilot-instructions build \ + --base programming-fundamentals,code-quality \ + --domain frontend/react \ + --task ui-components,performance-optimization + +# Configuration approach (modules defined in copilot-instructions.config.js) +copilot-instructions init +# Then, edit copilot-instructions.config.js (see [Configuration Guide](./configuration.md)) +copilot-instructions build --profile frontend +``` + +### Building a Node.js API + +```bash +# Example using direct module specification +copilot-instructions build \ + --base programming-fundamentals,documentation \ + --domain backend/nodejs \ + --task api-development,database-design +``` + +### Custom Module Discovery + +```bash +# Search for modules related to "testing" +copilot-instructions search "testing" + +# Search for modules related to "performance" +copilot-instructions search "performance" + +# List task modules tagged with "api" and "backend" +copilot-instructions list --type task --tags api,backend +```