aiwg
Version:
Deployment tool and support utility for AI context. Copies agents, skills, commands, rules, and behaviors into the paths each AI platform reads (Claude Code, Codex, Copilot, Cursor, Warp, OpenClaw, and 6 more) so one source of truth works across 10 platfo
185 lines (135 loc) • 5.88 kB
Markdown
# Ops Issue Tracking Rules
**Enforcement Level**: MEDIUM
**Scope**: Issue creation, labeling, and progress tracking across ops repositories
## Principle
Consistent issue tracking makes operational work searchable, filterable, and auditable. Standard labels, phased work patterns, and commit-issue linking turn a pile of tickets into an operational history that anyone can navigate — including agents.
## Mandatory Rules
### Rule 1: Use Standard Label Format
All ops issues MUST use the standard label taxonomy. Labels follow a `category: value` format with consistent casing.
**Required label categories**:
| Category | Format | Values | Example |
|----------|--------|--------|---------|
| **host** | `host: <hostname>` | Actual hostname | `host: compute-03` |
| **priority** | `priority: <level>` | critical, high, medium, low | `priority: high` |
| **area** | `area: <domain>` | storage, network, security, monitoring, backup, compute, services | `area: storage` |
| **status** | `status: <state>` | blocked, in-progress, needs-review, waiting-on-parts | `status: blocked` |
| **type** | `type: <kind>` | incident, maintenance, migration, standup, decommission | `type: migration` |
| **release** | `release/<version>` | CalVer version | `release/v2026.3.3` |
**Label rules**:
- Use lowercase for all label values
- One `priority:` label per issue (required)
- One or more `host:` labels if host-specific (required for sysops)
- One or more `area:` labels (required)
- `status:` labels updated as work progresses
- `type:` label assigned at creation
**FORBIDDEN**:
```
# Inconsistent casing and format
Host: Compute-03
PRIORITY: HIGH
storage
```
**REQUIRED**:
```
host: compute-03
priority: high
area: storage
type: maintenance
```
### Rule 2: Use Phased Work Breakdown for Multi-Step Operations
Large operational tasks (migrations, host standup, decommissions) MUST be broken into sequential phased issues. Each phase is a separate issue with explicit dependencies.
**Pattern**:
```markdown
# Phase 1: Preparation
Title: [compute-03] ZFS migration phase 1: backup and validation
Labels: host: compute-03, area: storage, type: migration, priority: high
Body:
## Objective
Back up existing data and validate backup integrity.
## Dependencies
Blocked-by: (none — first phase)
Blocks: roctinam/sysops#16 (phase 2: partition and pool creation)
## Acceptance Criteria
- [ ] Full backup completed to /backup/compute-03/
- [ ] Backup integrity verified with checksums
- [ ] Backup size matches source within 5%
# Phase 2: Execution
Title: [compute-03] ZFS migration phase 2: partition and pool creation
Labels: host: compute-03, area: storage, type: migration, priority: high
Body:
## Dependencies
Blocked-by: roctinam/sysops#15 (phase 1: backup)
Blocks: roctinam/sysops#17 (phase 3: data migration)
# Phase 3: Migration
Title: [compute-03] ZFS migration phase 3: data restore and verification
Labels: host: compute-03, area: storage, type: migration, priority: high
Body:
## Dependencies
Blocked-by: roctinam/sysops#16 (phase 2: pool creation)
```
**Phase naming convention**: `[hostname] <operation> phase N: <description>`
### Rule 3: Link Commits to Issues
Every commit that addresses an ops issue MUST reference the issue in the commit message using conventional commit format.
**Required format**:
```
type(scope): subject
Body text explaining what and why.
Refs: roctinam/sysops#15
```
**Closing keywords** (when the commit completes the issue):
```
fix(compute-03): repair ZFS pool degraded mirror
Replaced failed drive /dev/sdb, resilvered pool.
Closes: roctinam/sysops#15
```
**Valid closing keywords**: `Closes:`, `Fixes:`, `Resolves:`
**Cross-repo commits**:
```
feat(ansible): add ZFS monitoring role
Fleet-wide ZFS health monitoring via node_exporter.
Refs: roctinam/sysops#15
Closes: roctinam/devops#30
```
### Rule 4: Track Progress Through Issue Comments
For multi-step procedures, post progress updates as issue comments at each significant checkpoint. This creates an audit trail and allows others to see current status without asking.
**Progress comment format**:
```markdown
## Progress Update — 2026-03-24 14:30
### Completed
- [x] Backed up /data to /backup/compute-03/ (45 GB, sha256 verified)
- [x] Confirmed backup accessible from recovery host
### In Progress
- [ ] Partitioning new drives (ETA: 15 min)
### Blocked
- (none)
### Next Steps
1. Create ZFS pool after partitioning
2. Begin data restore
```
**When to post updates**:
- After completing each major step
- When encountering a blocker
- When handing off to another person or agent
- Before and after any destructive operation
### Rule 5: Cross-Repo Issue References in Context
When creating issues that relate to work in other repos, include the cross-repo context in a Dependencies section. Follow the fully qualified reference format from ops-cross-repo rules.
**Required in issue body when cross-repo dependencies exist**:
```markdown
## Dependencies
Blocks: roctinam/devops#30 (fleet monitoring deploy)
Blocked-by: roctinam/itops#12 (DNS record creation)
Related: roctinam/sysops#18 (similar migration on compute-04)
```
## Detection
- Issues missing required labels (priority, area)
- sysops issues missing `host:` label
- Multi-step operations in a single issue instead of phased breakdown
- Commits touching ops repos without issue references
- Large issues with no progress comments over 48 hours
- Inconsistent label format (wrong casing, missing category prefix)
## Enforcement
- **On violation**: Flag during issue creation or commit review
- **Severity**: MEDIUM — inconsistency degrades searchability and audit trails but does not cause operational harm
- **Recovery**: Add missing labels, split oversized issues into phases, update commit messages with issue references on next commit