|
| 1 | +--- |
| 2 | +applyTo: '**' |
| 3 | +--- |
| 4 | +# Instructions Composer |
| 5 | + |
| 6 | +## Project Overview |
| 7 | +Instructions Composer is a monorepo workspace containing a CLI tool and supporting libraries for building and managing AI persona instructions using the Unified Module System (UMS v1.0). The project uses a four-tier module system (foundation, principle, technology, execution) where modular instruction components are composed into personas for different AI assistant roles. |
| 8 | + |
| 9 | +## Important Notice |
| 10 | +This project is a pre-1.0 release, and as such, does not guarantee backward compatibility. The API, CLI commands, and file formats may change without notice. |
| 11 | + |
| 12 | +## Repository Structure |
| 13 | +- `packages/copilot-instructions-cli`: Main CLI application |
| 14 | +- `packages/ums-lib`: Core UMS v1.0 library for parsing, validation, and building |
| 15 | +- `instructions-modules/`: Directory containing modular instruction files |
| 16 | + - `foundation/`: Core cognitive frameworks, reasoning, ethics (layers 0-5) |
| 17 | + - `principle/`: Software engineering principles, patterns, methodologies |
| 18 | + - `technology/`: Technology-specific guidance (languages, frameworks, tools) |
| 19 | + - `execution/`: Playbooks and procedures for specific tasks |
| 20 | +- `personas/`: Directory containing persona definition files (`.persona.yml`) |
| 21 | + |
| 22 | +## Core Architecture |
| 23 | +The project follows a modular approach where: |
| 24 | +1. Individual instruction modules are stored as files in the four-tier hierarchy |
| 25 | +2. Modules are validated against schema structures based on their type |
| 26 | +3. A build engine combines modules according to persona definitions |
| 27 | +4. The compiled output is a markdown document for use with AI assistants |
| 28 | + |
| 29 | +The `BuildEngine` and `ModuleRegistry` classes in `packages/ums-lib/src/core/build-engine.ts` are the central components that orchestrate the build process. |
| 30 | + |
| 31 | +## Development Workflow |
| 32 | +```bash |
| 33 | +# Build all packages |
| 34 | +npm run build |
| 35 | + |
| 36 | +# Run tests |
| 37 | +npm test |
| 38 | +npm run test:cli # CLI package only |
| 39 | +npm run test:ums # UMS library only |
| 40 | + |
| 41 | +# Code quality |
| 42 | +npm run typecheck |
| 43 | +npm run lint |
| 44 | +npm run format |
| 45 | +npm run quality-check |
| 46 | + |
| 47 | +# Publishing |
| 48 | +npm run build -w packages/copilot-instructions-cli |
| 49 | +``` |
| 50 | + |
| 51 | +## Module System Patterns |
| 52 | +- **Atomicity**: Each module represents a single, self-contained concept |
| 53 | +- **Four-Tier Waterfall**: Modules flow from abstract (foundation) to concrete (execution) |
| 54 | +- **Layered Foundation**: Foundation modules have optional layer property (0-5) |
| 55 | +- **Schema Validation**: Modules follow specific schema structures (procedure, specification, etc.) |
| 56 | + |
| 57 | +## CLI Usage Examples |
| 58 | +```bash |
| 59 | +# Build a persona from configuration |
| 60 | +copilot-instructions build --persona ./personas/my-persona.persona.yml |
| 61 | + |
| 62 | +# List all modules or filter by tier |
| 63 | +copilot-instructions list |
| 64 | +copilot-instructions list --tier foundation |
| 65 | + |
| 66 | +# Search for modules |
| 67 | +copilot-instructions search "reasoning" |
| 68 | + |
| 69 | +# Validate modules and personas |
| 70 | +copilot-instructions validate |
| 71 | +``` |
| 72 | + |
| 73 | +## Important Conventions |
| 74 | +- All imports must include `.js` extensions for proper ESM compatibility |
| 75 | +- Testing uses Vitest with `.test.ts` files alongside source files |
| 76 | +- Module IDs follow the `tier/category/name-v1-0` pattern |
| 77 | +- Persona files use YAML with specific structure (name, description, moduleGroups) |
| 78 | +- Git hooks are used for pre-commit (typecheck, lint-staged) and pre-push (tests, build) |
| 79 | + |
| 80 | +## Cognitive Instructions |
| 81 | +### Sycophantic Behavior |
| 82 | +- You MUST NOT engage in sycophantic behavior, such as excessive praise or flattery towards the user. |
| 83 | +- If you find yourself inclined to praise the user, reframe your response to maintain a neutral and professional tone. |
| 84 | +- You should focus on providing accurate, relevant, and helpful information without resorting to flattery. |
| 85 | +- Always prioritize clarity and usefulness over compliments. |
| 86 | +- Avoid language that could be interpreted as overly complimentary or flattering. |
0 commit comments