microsoft / microsoft/hve-core
docs: add documentation for new Jira/GitLab skills and workflows
- Dominant language
- Python
- Stars
- 1.5k
- Forks
- 301
- Avg merge
- 3d 3h
- Merged PRs (30d)
- 92
Description
## Summary
PR #978 (https://github.com/microsoft/hve-core/pull/978) introduces a significant set of new Jira and GitLab integration components. This issue tracks the documentation needed to cover these new skills, agents, instructions, and prompts so users can discover and adopt them.
## New Components Requiring Documentation
### Jira Python CLI Skill
- **Path**: `.github/skills/jira/jira/`
- **Commands**: `search`, `get`, `comments`, `fields`, `create`, `update`, `transition`, `comment`
- **Authentication**: `JIRA_URL`, `JIRA_EMAIL`, `JIRA_TOKEN` environment variables
- **Documentation needed**: Getting-started guide, command reference, environment setup, and usage examples for each command
### GitLab Python CLI Skill
- **Path**: `.github/skills/gitlab/gitlab/`
- **Commands**: `mr-list`, `mr-get`, `mr-create`, `mr-update`, `mr-comment`, `mr-notes`, `pipeline-get`, `pipeline-run`, `pipeline-jobs`, `job-log`
- **Authentication**: `GITLAB_URL`, `GITLAB_TOKEN`, `GITLAB_PROJECT` (optional, auto-detected from git remote)
- **Features**: `--fields` option for concise output, git remote auto-detection for project identification
- **Documentation needed**: Getting-started guide, command reference, environment setup, `--fields` usage, and pipeline workflow examples
### Jira Backlog Manager Agent
- **Path**: `.github/agents/jira/jira-backlog-manager.agent.md`
- **Workflows**: Discovery, triage, execution, single-issue operations
- **State tracking**: `.copilot-tracking/jira-issues/`
- **Documentation needed**: Agent overview, workflow descriptions, example invocations, and state file conventions
### Jira PRD-to-WIT Agent
- **Path**: `.github/agents/jira/jira-prd-to-wit.agent.md`
- **Workflow**: 5-phase PRD analysis and Jira issue hierarchy planning (planning-only, no mutations)
- **Documentation needed**: Agent overview, phase descriptions, input/output conventions, and example usage
### Jira Instructions (5 files)
| File | Purpose |
|------|---------|
| `jira-backlog-discovery.instructions.md` | Discovery protocol with 3 paths: user-centric, artifact-driven, JQL-based |
| `jira-backlog-planning.instructions.md` | Reference specification for planning files, field conventions, Jira command catalog |
| `jira-backlog-triage.instructions.md` | Triage workflow for field recommendations and duplicate detection |
| `jira-backlog-update.instructions.md` | Execution workflow consuming planning handoffs |
| `jira-wit-planning.instructions.md` | PRD work item planning reference specification |
### Jira Prompts (4 files)
| Prompt | Key Inputs |
|--------|------------|
| `jira-discover-issues.prompt.md` | project, documents, jql, searchTerms, includeComments, autonomy |
| `jira-execute-backlog.prompt.md` | handoff (required), autonomy, dryRun |
| `jira-prd-to-wit.prompt.md` | project, artifacts, autonomy |
| `jira-triage-issues.prompt.md` | project, jql, maxIssues, autonomy |
### Collection Manifests
- New `jira` and `gitlab` collection YAML and markdown manifests
- Updated `hve-core-all` collection to include new components
- Regenerated plugin outputs under `plugins/`
## Documentation Scope
1. **Docs site pages** — Add pages under `docs/` covering the Jira and GitLab skills, agents, and prompt workflows (following existing patterns in the getting-started and customization sections)
2. **Cross-references** — Ensure the new components are linked from existing index pages and navigation where appropriate
3. **Examples** — Include practical usage examples and typical workflow walkthroughs for both Jira and GitLab integrations
## Related
- Introduced in PR #978: https://github.com/microsoft/hve-core/pull/978
Contributor guide
Research direction
Start with the existing getting-started and customization patterns under docs/, then review the Jira and GitLab skill paths, agent files, instruction and prompt files, and collection manifests named in the issue. Document setup, commands, workflows, examples, and cross-references for both integrations. Done means the new pages and navigation links cover the listed components and the regenerated plugin outputs are represented.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- github, gitlab, python
- Domain
- developer-experience, documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100