GitHub Copilot Instructions for chef-vault

# GitHub Copilot Instructions for chef-vault

---

## 1. Repository Analysis & Structure

### Project Purpose
**chef-vault** is a Ruby gem that enables encryption of Chef Data Bag Items using the public keys of Chef nodes, allowing only those nodes to decrypt the values. It is a critical part of the Chef ecosystem for secure secret management.

### Folder Structure Diagram
```
chef-vault/
├── .github/           # GitHub workflows, CODEOWNERS, Copilot instructions
├── bin/               # Executable scripts (e.g., chef-vault CLI)
├── coverage/          # Test coverage reports
├── dev/               # Dockerfiles and dev environment setup
├── features/          # Cucumber BDD feature tests
│   ├── step_definitions/ # Step definitions for Cucumber
│   └── support/           # Cucumber environment config
├── habitat/           # Habitat packaging and test scripts
├── hooks/             # Git hooks (e.g., pre-commit)
├── lib/               # Main Ruby library code
│   ├── chef/knife/        # Knife plugin commands
│   └── chef-vault/        # Core gem logic
├── spec/              # RSpec unit tests
│   ├── chef-vault/        # Unit tests for core logic
│   └── chef/              # Helper specs
├── tmp/               # Temp files for test runs
├── vendor/            # Bundled dependencies
├── .expeditor/        # Expeditor build automation config
├── CHANGELOG.md       # Changelog
├── CODE_OF_CONDUCT.md # Code of conduct
├── CONTRIBUTING.md    # Contribution guidelines
├── DEMO.md            # Demo instructions
├── Gemfile            # Ruby gem dependencies
├── Gemfile.lock       # Locked gem versions
├── KNIFE_EXAMPLES.md  # Knife command examples
├── LICENSE            # Apache 2.0 License
├── Rakefile           # Rake build/test tasks
├── README.md          # Main documentation
├── sonar-project.properties # SonarQube config
├── THEORY.md          # Vault design and theory
├── UPGRADE.md         # Vault upgrade instructions
├── VERSION            # Gem version
```

### Technologies Used
- **Languages:** Ruby
- **Frameworks:** Chef, RSpec, Cucumber, Aruba
- **Build/Automation:** Rake, Bundler, Expeditor, Habitat, Docker
- **Linting:** Chefstyle, RuboCop
- **CI/CD:** Buildkite, Expeditor, SonarQube

### File Modification Guidelines
- **Safe to Modify:**
  - `lib/`, `spec/`, `features/`, `dev/`, `habitat/`, `README.md`, `CHANGELOG.md`, `Rakefile`, `Gemfile`, `Gemfile.lock`, `.github/`
- **Prohibited/Generated:**
  - `coverage/`, `vendor/`, `tmp/`, `chef-vault-*.gem`, files in `.expeditor/` (except by automation), `VERSION` (bump only via release process)
- **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 `tmp/`.

---

## 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, Cucumber for features).
- 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/`), Cucumber for BDD (`features/`).
- Run tests with:
  - `bundle exec rspec spec/`
  - `bundle exec rake features`
- 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 ChefVault::Item do
  it 'loads a vault item' do
    # ... test code ...
  end
end
```

#### Example Cucumber Feature
```gherkin
Feature: Vault creation
  Scenario: Create a new vault
    Given I have a valid config
    When I run "knife vault create ..."
    Then the vault should be created
```

---

## 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`/`rake test`: Run all tests
  - `rake coverage`: Run unit tests with coverage
  - `rake features`: Run Cucumber features
- **Bundler:**
  - `bundle install`: Install dependencies
- **SonarQube:**
  - Config: `sonar-project.properties`
  - Coverage: SimpleCov, RSpec

---

## 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 Docker (see `dev/`), Habitat, or native Ruby.
- **Prohibited:** Never edit files in `coverage/`, `vendor/`, `tmp/`, or generated files.
- **Platform:** macOS, Linux, Windows (see Dockerfiles).
- **Integration:** Chef ecosystem, Habitat, Expeditor, SonarQube.

---

## 10. Code Quality & Standards
- **Style:** Chefstyle, RuboCop (`bundle exec chefstyle -a`)
- **Conventions:** Ruby best practices, Chef community standards
- **Security:** No secrets in code, use vaults for sensitive data
- **License:** Apache 2.0 (see LICENSE)
- **Performance:** Avoid unnecessary computation, optimize for large vaults
- **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, vault keys

---

## 12. Build & Development Environment
- **Setup:**
  - `bundle install`
  - Use Docker (`dev/`) for isolated Ruby environments
  - Use Habitat for packaging
- **Build:**
  - `rake` (all tests)
  - `rake coverage` (unit test coverage)
  - `rake features` (Cucumber)
- **Troubleshooting:**
  - See `dev/readme.md` for Docker issues
  - For coverage: ensure SimpleCov is enabled

---

## 13. Integration & Dependencies
- **Ecosystem:** Chef Infra, Habitat, Expeditor, SonarQube
- **External Services:** Chef server, Rubygems, Jira (via MCP)
- **API:** Knife plugins, Chef API

---

## 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/`, `tmp/`, auto-generated files
- **Troubleshooting:** See `dev/readme.md`, `README.md`, and coverage reports
- **Build/Test Commands:**
  - `bundle install`
  - `bundle exec rspec spec/`
  - `bundle exec rake features`
  - `bundle exec chefstyle -a`
  - `rake coverage`
- **Performance:** Use sparse mode for large vaults

---

## 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/`
- **Cucumber:** `bundle exec rake features`
- **Chefstyle:** `bundle exec chefstyle -a`
- **Gem Management:** Use `Gemfile`, do not edit `Gemfile.lock` directly
- **Testing:** Use mocks for Chef server/API, test all edge/error cases
- **Coverage:** SimpleCov enabled in `spec_helper.rb`

### Go, Node.js, Python, Java
- **Not used in this repo.**

---

## 19. Advanced Configuration Management
- **Config files:** `.expeditor/config.yml`, `sonar-project.properties`, `dev/Dockerfile.*`, `habitat/plan.sh`, `habitat/plan.ps1`
- **Env vars:** See Dockerfiles and Habitat plans 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

---

## 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)
- [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

---

*Generated for the chef-vault repository. For questions, see `README.md`, `CONTRIBUTING.md`, or contact the CODEOWNERS.*