Skip to content

copilot instructions

Jump to bottom
Ryan Newington edited this page Sep 4, 2025 · 1 revision

ACMA Wiki Copilot Instructions

Project Overview

This is a documentation wiki for ACMA (Active Configuration Management Agent), a PowerShell-based identity management and configuration system. The wiki uses GitHub Pages markdown format.

Key Architecture Concepts

Core Components

  • Schema Management: Object classes, attributes, and bindings (Configure schema.md, Object classes.md, Attributes.md)
  • Rules Engine: Business logic validation (Rules.md, Rule groups.md, various *rule.md files)
  • Constructors: Object creation and attribute population patterns (Class constructors.md, Attribute constructors.md)
  • PowerShell Integration: Cmdlet-based management (PowerShell.md, PowerShell quick reference guide.md)

Documentation Patterns

  • Command Reference: Each PowerShell cmdlet has its own .md file (e.g., Add-AcmaObject.md, Get-AcmaObjects.md)
  • Concept Guides: High-level explanations of system components
  • Configuration Guides: Step-by-step setup instructions

File Naming Conventions

  • PowerShell cmdlets: Verb-AcmaNoun.md format
  • Concepts: Descriptive names with spaces (e.g., Advanced value comparison rule.md)
  • Core topics: Single word or short phrases (e.g., Rules.md, Transforms.md)

Content Structure Patterns

  • Use clear hierarchical headings (##, ###)
  • Include code examples in PowerShell syntax highlighting
  • Cross-reference related topics with markdown links
  • Use consistent terminology: "object classes", "attributes", "constructors", "rules"

Syntax and Technical Accuracy

  • ACMA Declarative Language: Use %constantName% syntax for constants (NOT {constant:name})
  • Attribute References: Use {attributeName} syntax for attribute values
  • PowerShell Cmdlets: Follow exact Verb-AcmaNoun naming conventions
  • Parameter Names: Use precise parameter names as defined in the system
  • Configuration Examples: Ensure all examples use correct syntax and realistic values

Key Files for Understanding System

  • Home.md: Main entry point and navigation
  • Installation.md: Setup procedures
  • Configure schema.md: Core data model setup
  • PowerShell quick reference guide.md: Essential cmdlets
  • Lab environment definition.md: Development setup

When Editing Documentation

  • Maintain consistency with existing PowerShell cmdlet documentation format
  • Ensure proper cross-linking between related concepts
  • Use ACMA-specific terminology consistently
  • Include practical examples for configuration concepts
  • Reference the resources/acma-demo.acmax demo file when applicable

Documentation Quality Standards

Technical Writing Principles

  • Concise Technical Prose: Use clear, factual descriptions without marketing language or excessive bullet points
  • Accuracy First: Ensure all syntax examples, parameter names, and code snippets are technically correct
  • Professional Tone: Maintain a technical reference style appropriate for system administrators and developers
  • Structured Information: Organize content logically with clear headings and consistent formatting

Content Standards

  • No Marketing Language: Avoid sales-oriented phrases, excessive enthusiasm, or promotional content
  • Precise Syntax: Use correct ACMA declarative language syntax (%constantName% for constants, {attributeName} for attributes)
  • Factual Descriptions: Focus on what components do, not why they're "powerful" or "flexible"
  • Technical Examples: Provide realistic configuration scenarios with proper syntax and parameter usage

Formatting Guidelines

  • Tables: Use clean, focused tables without unnecessary "Use Cases" or promotional columns
  • Code Blocks: Include properly formatted configuration examples with correct syntax
  • Cross-References: Link to related concepts using exact document names in square brackets
  • Consistency: Maintain uniform terminology and formatting across all documentation

Images and Resources

  • Images stored in images/ directory
  • Demo configurations in resources/ directory
  • Use relative paths for internal links

Documentation Maintenance Guidelines

Quality Preservation

  • Preserve Technical Prose: Maintain existing technical writing style rather than converting to marketing bullet points
  • Avoid Content Degradation: Do not transform concise technical descriptions into promotional language
  • Respect Original Format: When updating content, preserve the document's established structure and tone
  • Technical Reference Standard: All documentation should read as professional technical reference material

Common Pitfalls to Avoid

  • Converting technical descriptions to marketing-style bullet points
  • Adding unnecessary "benefits" or "advantages" sections to technical references
  • Using promotional language like "powerful", "flexible", "comprehensive" without technical context
  • Creating overly verbose explanations when concise technical descriptions suffice
  • Adding "use cases" columns to operator or parameter tables unless specifically requested

Edit Verification

  • Syntax Validation: Always verify ACMA declarative language syntax in examples
  • Cross-Reference Check: Ensure internal links use correct document names
  • Consistency Review: Maintain terminology and formatting consistency with existing documentation
  • Technical Accuracy: Validate that all technical details are correct and current

Clone this wiki locally