Merge pull request #300 from chef/nikhil/copilot-instructions

Add GitHub Copilot instructions for chef-cli

Author: ashiqueps

.github/copilot-instructions.md

@@ -0,0 +1,398 @@
+# GitHub Copilot Instructions for chef-cli
+
+---
+
+## 1. Repository Analysis & Structure
+
+### Project Purpose
+**chef-cli** is a Ruby gem that provides a command line interface for Chef Infra practitioners. It is a streamlined development and deployment workflow tool for the Chef platform, offering everything needed to be successful using Chef Infra, Chef InSpec, and Chef Habitat. The tool builds Chef Infra Policyfiles to provide an awesome experience that encourages quick iteration and testing.
+
+### Folder Structure Diagram
+```
+chef-cli/
+├── .buildkite/          # Buildkite CI configuration
+├── .expeditor/           # Expeditor build automation config
+├── .github/              # GitHub workflows, CODEOWNERS, Copilot instructions
+├── .ruby-lsp/            # Ruby LSP configuration
+├── bin/                  # Executable scripts (chef-cli CLI)
+├── coverage/             # Test coverage reports
+├── dev-doc/              # Development documentation
+├── habitat/              # Habitat packaging and test scripts
+│   ├── plan.ps1          # Windows Habitat plan
+│   ├── plan.sh           # Linux Habitat plan
+│   └── tests/            # Habitat test scripts
+├── lib/                  # Main Ruby library code
+│   ├── chef-cli.rb       # Main entry point
+│   ├── chef-cli/         # Core gem logic
+│   │   ├── command/      # CLI command implementations
+│   │   ├── completions/  # Shell completion scripts
+│   │   ├── cookbook_profiler/ # Cookbook analysis tools
+│   │   ├── licensing/    # License management
+│   │   ├── policyfile/   # Policyfile-related services
+│   │   ├── policyfile_services/ # Policyfile operations
+│   │   ├── service_exception_inspectors/ # Error handling
+│   │   └── skeletons/    # Code generation templates
+│   └── kitchen/          # Test Kitchen integration
+├── spec/                 # RSpec unit tests
+│   ├── shared/           # Shared test contexts
+│   ├── unit/             # Unit test specifications
+│   └── test_helpers.rb   # Test helper utilities
+├── .gitignore            # Git ignore patterns
+├── .rspec                # RSpec configuration
+├── .rubocop.yml          # RuboCop configuration
+├── CHANGELOG.md          # Version history
+├── chef-cli.gemspec      # Gem specification
+├── CODE_OF_CONDUCT.md    # Code of conduct
+├── CONTRIBUTING.md       # Contribution guidelines
+├── Gemfile               # Ruby gem dependencies
+├── Gemfile.lock          # Locked gem versions
+├── Guardfile             # Guard automation config
+├── LICENSE               # Apache 2.0 License
+├── post-bundle-install.rb # Post-bundle installation script
+├── Rakefile              # Rake build/test tasks
+├── README.md             # Main documentation
+├── report.spdx.json      # SPDX license report
+├── sonar-project.properties # SonarQube configuration
+└── VERSION               # Gem version
+```
+
+### Technologies Used
+- **Languages:** Ruby (>= 3.1)
+- **Frameworks:** Chef Infra, RSpec, Test Kitchen
+- **Build/Automation:** Rake, Bundler, Expeditor, Habitat, Buildkite
+- **Linting:** Chefstyle, RuboCop, Cookstyle
+- **CI/CD:** Buildkite, Expeditor, SonarQube
+- **Package Management:** Habitat, Omnibus
+
+### File Modification Guidelines
+- **Safe to Modify:**
+  - `lib/`, `spec/`, `dev-doc/`, `habitat/`, `README.md`, `CHANGELOG.md`, `Rakefile`, `Gemfile`, `Gemfile.lock`, `.github/`, `.buildkite/`
+- **Prohibited/Generated:**
+  - `coverage/`, `vendor/`, files in `.expeditor/` (except by automation), `VERSION` (bump only via release process), `Gemfile.lock` (modify via bundle commands only)
+- **Never Modify:**
+  - License headers, copyright blocks, and files marked as auto-generated
+
+### Code Generation Patterns
+- Do not modify files generated by Rake, Bundler, or Expeditor directly.
+- Do not edit files in `coverage/`, `vendor/`, or auto-generated directories.
+
+---
+
+## 2. Development Workflow Integration
+
+### Jira Integration (atlassian-mcp-server)
+- When a Jira ID is provided, fetch the issue using the atlassian-mcp-server MCP server.
+- Read the story, analyze requirements, and plan implementation before coding.
+
+### Workflow Phases
+#### **Phase 1: Initial Setup & Analysis**
+- Prompt: "Jira ID provided: `<JIRA_ID>`. Fetching issue details and analyzing requirements."
+- Analyze repository structure and dependencies.
+- Plan implementation and confirm with user.
+- **Approval Gate:** "Ready to proceed with implementation. Continue?"
+
+#### **Phase 2: Implementation Phase**
+- Implement code changes and update documentation.
+- Prompt: "Implementation complete. Ready for testing. Continue?"
+- **Approval Gate:** Confirm before moving to testing.
+
+#### **Phase 3: Testing Phase**
+- Create/modify unit tests (RSpec for Ruby).
+- Run all tests and ensure >80% coverage (CRITICAL REQUIREMENT).
+- Prompt: "Testing complete. Coverage: XX%. Ready to create PR?"
+- **Approval Gate:** Confirm before PR creation.
+
+#### **Phase 4: Pull Request Creation**
+- Use Jira ID as branch name (e.g., `PROJ-123`).
+- Use GH CLI for all git operations (no profile-based auth).
+- Prompt: "PR created. Review and merge when ready."
+
+---
+
+## 3. Testing Requirements (Critical)
+**ALL code changes MUST include comprehensive unit tests.**
+- **>80% test coverage is a HARD REQUIREMENT.**
+- Use RSpec for unit tests (`spec/`).
+- Run tests with:
+  - `bundle exec rspec spec/`
+  - `bundle exec rake style:chefstyle`
+  - `bundle exec rake style:cookstyle`
+- Coverage report: `coverage/index.html` (generated by SimpleCov)
+- Test both positive/negative, edge cases, and error conditions.
+- Use mocks for external dependencies.
+- Tests must be independent and order-agnostic.
+- **Verify coverage:**
+  - `open coverage/index.html` (macOS)
+  - Ensure SimpleCov reports >80%.
+- **Emphasize:** No PR will be accepted without >80% coverage.
+
+#### Example RSpec Test Structure
+```ruby
+require 'spec_helper'
+describe ChefCLI::Command::Install do
+  it 'installs a policyfile' do
+    # ... test code ...
+  end
+end
+```
+
+#### Example Test with Mocking
+```ruby
+require 'spec_helper'
+describe ChefCLI::PolicyfileServices::Install do
+  let(:policyfile_lock) { instance_double(ChefCLI::PolicyfileLock) }
+  
+  it 'validates the policyfile lock' do
+    expect(service).to receive(:validate_lockfile)
+    service.run
+  end
+end
+```
+
+---
+
+## 4. Pull Request Creation Process
+- **Branch name:** Use Jira ID (e.g., `PROJ-123`)
+- **Commands:**
+  - Branch: `git checkout -b <JIRA_ID>`
+  - Stage/commit: `git add . && git commit --signoff -m "<JIRA_ID>: description"`
+  - Amend signoff: `git commit --amend --signoff --no-edit`
+  - Push: `git push origin <JIRA_ID>`
+  - Create PR: `gh pr create --base main --head <JIRA_ID> --title "<JIRA_ID>: <summary>" --body-file pr_description.html --label "Type: Enhancement"`
+- **PR Description (HTML):**
+  - Summary of changes
+  - Link to Jira ticket: `<a href="https://jira.example.com/browse/<JIRA_ID>">Jira Ticket</a>`
+  - List of changes
+  - Testing performed and coverage results
+  - List of files modified
+  - Screenshots/examples if applicable
+
+---
+
+## 5. DCO (Developer Certificate of Origin) Compliance
+- **ALL commits MUST use `--signoff`**
+- Example: `git commit --signoff -m "<JIRA_ID>: description"`
+- To amend: `git commit --amend --signoff --no-edit`
+- **Builds will fail without DCO signoff.**
+- All commit examples in this guide include `--signoff`.
+
+---
+
+## 6. Build System Integration Analysis
+- **Expeditor:**
+  - Config: `.expeditor/config.yml`
+  - Skip labels: `Expeditor: Skip All`, `Expeditor: Skip Version Bump`, `Expeditor: Skip Changelog`, `Expeditor: Skip Habitat`, `Expeditor: Skip Omnibus`
+  - Use skip labels for docs/test-only changes to avoid unnecessary builds.
+  - Build channels: `main` (see config)
+  - Automation: version bump, changelog, gem build, habitat pipeline
+- **Rake:**
+  - `rake`: Default task (runs tests and style checks)
+  - `bundle exec rspec spec/`: Run unit tests
+  - `bundle exec rake style:chefstyle`: Run Ruby style checks
+  - `bundle exec rake style:cookstyle`: Run cookbook style checks
+- **Bundler:**
+  - `bundle install`: Install dependencies
+  - `bundle exec`: Run commands with correct gem environment
+- **SonarQube:**
+  - Config: `sonar-project.properties`
+  - Coverage: SimpleCov, RSpec
+- **Habitat:**
+  - Linux plan: `habitat/plan.sh`
+  - Windows plan: `habitat/plan.ps1`
+  - Tests: `habitat/tests/test.sh`, `habitat/tests/test.ps1`
+
+---
+
+## 7. Label Management System
+- **Actual labels:**
+  - `Type: Bug`, `Type: Enhancement`, `Type: Regression`, `Aspect: Documentation`, `Aspect: Testing`, `Aspect: Security`, `Expeditor: Skip All`, `Expeditor: Skip Version Bump`, `Expeditor: Skip Changelog`, `Expeditor: Skip Habitat`, `Expeditor: Skip Omnibus`, `Priority: Critical/Medium/Low`, `Platform: <platform>`
+- **Docs/test-only:** Use `Aspect: Documentation`, `Aspect: Testing`, and Expeditor skip labels
+- **Feature:** `Type: Enhancement`
+- **Bug:** `Type: Bug`
+- **Test-only:** `Aspect: Testing`, `Expeditor: Skip Version Bump`
+- **Decision Matrix:**
+  - Docs: `Aspect: Documentation`, `Expeditor: Skip All`
+  - Test: `Aspect: Testing`, `Expeditor: Skip Version Bump`
+  - Feature: `Type: Enhancement`
+  - Bug: `Type: Bug`
+
+---
+
+## 8. Prompt-Based Execution Protocol
+- After each major step, summarize what was completed.
+- Before next step, state what will be done and ask: "Do you want me to continue with the next step?"
+- List remaining steps.
+- Wait for user approval before proceeding.
+- **Example:**
+  - "Phase 1 complete: Jira analysis and planning. Next: Implementation. Continue?"
+  - "Remaining: Implementation, Testing, PR Creation."
+
+---
+
+## 9. Repository-Specific Guidelines
+- **Build:** Use Rake tasks, Bundler, and Expeditor automation.
+- **Dependencies:** Managed via Bundler (`Gemfile`).
+- **Dev Environment:** Use native Ruby (>= 3.1), Habitat, or Chef Workstation.
+- **Prohibited:** Never edit files in `coverage/`, `vendor/`, or generated files.
+- **Platform:** macOS, Linux, Windows (see Habitat plans).
+- **Integration:** Chef ecosystem, Habitat, Expeditor, SonarQube, Buildkite.
+
+---
+
+## 10. Code Quality & Standards
+- **Style:** Chefstyle, RuboCop, Cookstyle (`bundle exec rake style:chefstyle`)
+- **Conventions:** Ruby best practices, Chef community standards
+- **Security:** No secrets in code, use Chef Vault for sensitive data
+- **License:** Apache 2.0 (see LICENSE)
+- **Performance:** Optimize for large cookbooks and policies
+- **Review:** CODEOWNERS: `@chef/chef-workstation-reviewers`, `@chef/chef-workstation-approvers`, `@chef/chef-workstation-owners` (all files); `@chef/docs-team` (`*.md`)
+
+---
+
+## 11. Security and Compliance Requirements
+- **CVE Awareness:** Monitor dependencies
+- **FIPS:** Ensure FIPS compliance if required
+- **License Headers:** Do not remove/modify
+- **Scanning:** Use SonarQube, RuboCop
+- **Authentication:** Chef server, policyfile operations
+
+---
+
+## 12. Build & Development Environment
+- **Setup:**
+  - `bundle install`
+  - Use Habitat (`habitat/`) for isolated environments
+  - Ruby >= 3.1 required
+- **Build:**
+  - `rake` (all tests and style)
+  - `bundle exec rspec spec/` (unit tests)
+  - `bundle exec rake style:chefstyle` (Ruby style)
+  - `bundle exec rake style:cookstyle` (cookbook style)
+- **Troubleshooting:**
+  - See `dev-doc/README.md` for development setup
+  - For coverage: ensure SimpleCov is enabled in `spec_helper.rb`
+
+---
+
+## 13. Integration & Dependencies
+- **Ecosystem:** Chef Infra, Chef Workstation, Habitat, Expeditor, SonarQube
+- **External Services:** Chef server, Rubygems, Jira (via MCP)
+- **API:** Chef Infra API, Policyfile services, cookbook management
+
+---
+
+## 14. Release & CI/CD Awareness
+- **Pipelines:** Buildkite, Expeditor, Habitat
+- **Release:** Automated via Expeditor, Rubygems publish
+- **Channels:** `main` branch, see `.expeditor/config.yml`
+- **Notifications:** Slack: `chef-ws-notify`
+
+---
+
+## 15. Code Ownership & Review Process
+- **CODEOWNERS:**
+  - All files: `@chef/chef-workstation-reviewers`, `@chef/chef-workstation-approvers`, `@chef/chef-workstation-owners`
+  - Markdown: `@chef/docs-team`
+- **Review:** At least one approval from owners/approvers required
+
+---
+
+## 16. Important Development Notes
+- **Work locally**; do not edit files directly in remote or generated folders
+- **Ask for clarification** if requirements are unclear
+- **Never modify:** `coverage/`, `vendor/`, auto-generated files
+- **Troubleshooting:** See `dev-doc/README.md`, `README.md`, and coverage reports
+- **Build/Test Commands:**
+  - `bundle install`
+  - `bundle exec rspec spec/`
+  - `bundle exec rake style:chefstyle`
+  - `bundle exec rake style:cookstyle`
+- **CLI Commands:** `chef-cli generate`, `chef-cli install`, `chef-cli push`, `chef-cli update`, `chef-cli export`
+
+---
+
+## 17. Example Workflow Execution
+**Feature Implementation Example:**
+1. User: "Implement feature X for Jira ID PROJ-123"
+2. Copilot: "Phase 1: Fetching Jira PROJ-123, analyzing requirements...\nReady to proceed with implementation. Continue?\nRemaining: Implementation, Testing, PR Creation."
+3. User: "Continue"
+4. Copilot: "Phase 2: Implementing feature X...\nImplementation complete. Ready for testing. Continue?\nRemaining: Testing, PR Creation."
+5. User: "Continue"
+6. Copilot: "Phase 3: Running tests...\nCoverage: 92%. Ready to create PR?\nRemaining: PR Creation."
+7. User: "Continue"
+8. Copilot: "Phase 4: Creating PR...\nPR created. Review and merge when ready."
+
+**Bug Fix Example:**
+- Use `Type: Bug` label, follow same workflow
+
+**Docs Change Example:**
+- Use `Aspect: Documentation`, `Expeditor: Skip All` labels
+
+---
+
+## 18. Technology-Specific Guidelines
+### Ruby
+- **Bundler:** `bundle install`
+- **RSpec:** `bundle exec rspec spec/`
+- **Chefstyle:** `bundle exec rake style:chefstyle`
+- **Cookstyle:** `bundle exec rake style:cookstyle`
+- **Gem Management:** Use `Gemfile`, do not edit `Gemfile.lock` directly
+- **Testing:** Use mocks for Chef API/server, test all edge/error cases
+- **Coverage:** SimpleCov enabled in `spec_helper.rb`
+- **Ruby Version:** >= 3.1 required
+
+### Chef Infra Integration
+- **Policyfiles:** Core functionality for cookbook management
+- **Chef Server API:** Authentication and communication
+- **Test Kitchen:** Integration testing support
+- **Cookbook Generation:** Template-based code generation
+
+---
+
+## 19. Advanced Configuration Management
+- **Config files:** `.expeditor/config.yml`, `sonar-project.properties`, `habitat/plan.sh`, `habitat/plan.ps1`, `.buildkite/`
+- **Env vars:** See Habitat plans and Buildkite configs for required variables
+- **Secrets:** Never commit secrets; use Chef Vault for secret management
+- **Database:** Not applicable
+- **MCP server:** For Jira integration, configure atlassian-mcp-server as needed
+
+---
+
+## 20. Key Commands & CLI Usage
+### chef-cli Command Reference
+- **Generate:** `chef-cli generate cookbook COOKBOOK_NAME`
+- **Install:** `chef-cli install [POLICYFILE]`
+- **Update:** `chef-cli update [POLICYFILE]`
+- **Push:** `chef-cli push POLICY_GROUP [POLICYFILE]`
+- **Export:** `chef-cli export [POLICYFILE] DESTINATION`
+- **Diff:** `chef-cli diff [POLICY_FILE] [POLICY_GROUP]`
+- **Shell Init:** `chef-cli shell-init SHELL_NAME`
+- **Gem:** `chef-cli gem COMMAND`
+- **Exec:** `chef-cli exec COMMAND`
+
+### Development Commands
+- **Test:** `bundle exec rspec spec/`
+- **Style:** `bundle exec rake style:chefstyle`
+- **Coverage:** Open `coverage/index.html`
+- **Build Gem:** `gem build chef-cli.gemspec`
+- **Install Local:** `gem install chef-cli-*.gem`
+
+---
+
+## Validation Checklist
+- [x] Repository structure diagram
+- [x] DCO signoff requirements in all commit examples
+- [x] >80% test coverage requirement mentioned multiple times
+- [x] Actual repository labels (not generic ones)
+- [x] Build system integration (Expeditor, Rake, Bundler, Habitat)
+- [x] Prompt-based workflow examples
+- [x] Technology-specific testing patterns
+- [x] Complete Git workflow with proper commands
+- [x] Security and compliance requirements
+- [x] Troubleshooting section
+- [x] Example interaction patterns
+- [x] Chef-CLI specific commands and usage
+
+---
+
+*Generated for the chef-cli repository. For questions, see `README.md`, `CONTRIBUTING.md`, or contact the CODEOWNERS.*