diff --git a/.github/instructions/style.plans.instructions.md b/.github/instructions/style.plans.instructions.md new file mode 100644 index 0000000..778ba2d --- /dev/null +++ b/.github/instructions/style.plans.instructions.md @@ -0,0 +1,675 @@ +--- +description: "Planning Document Standards: Format and structure requirements for migration plans, implementation guides, and project roadmaps." +applyTo: "documentation/plans/**/*.md" +--- + +# Planning Document Standards + +## Purpose + +This document defines the structure, formatting, and content requirements for all planning documents stored in `documentation/plans/`. These standards ensure consistency, enable accurate time estimation, and provide clear execution pathways for infrastructure changes. + +--- + +## Document Types + +### Migration Plans +Files prefixed with `plan-` that detail transitioning from one state to another. + +**Examples:** +- `plan-gitcryptMigration.md` — Implementing git-crypt for secret management +- `plan-ansibleSetup.md` — Setting up Ansible control node +- `plan-promptDistribution.md` — Centralizing prompt repository + +### Implementation Guides +Step-by-step instructions for deploying new technologies or systems. + +### Roadmaps +Long-term strategic plans spanning multiple phases or quarters. + +--- + +## Required Document Structure + +### 1. Header Section + +Every plan must begin with: + +```markdown +# [Descriptive Title]: [Specific Goal] + +## Overview + +[2-3 sentence summary of what this plan accomplishes and why it matters] + +**[Primary Metric]:** [Value/Target] +**[Secondary Metric]:** [Value/Target] (optional) +**End State:** [Concrete description of success] + +**Estimated Time to Complete:** X-Y hours (first-time setup) | A-B hours (experienced operator) +``` + +**Example:** +```markdown +# Ansible Control Node Setup: Path to Production Readiness + +## Overview + +Transform **Watchtower** (Raspberry Pi 5) into a production-ready Ansible control node capable of managing the entire homelab infrastructure. + +**Control Node:** Watchtower (10.0.0.200) — Raspberry Pi 5, ARM Cortex-A76, 16GB RAM +**Managed Nodes:** Heimdall (10.0.0.151), Waldorf (10.0.0.251), Watchtower (localhost) +**End State:** Fully configured Ansible environment with validated connectivity, encrypted secrets, and role scaffolding. + +**Estimated Time to Complete:** 2-3 hours (first-time setup) | 45-60 minutes (experienced operator) +``` + +--- + +### 2. Time Breakdown Table + +**Required immediately after Overview section:** + +```markdown +## Time Breakdown by Phase + +| Phase | Description | Time Estimate | +|-------|-------------|---------------| +| **Phase 1** | [Phase Name] | XX-YY minutes | +| **Phase 2** | [Phase Name] | XX-YY minutes | +| **Phase 3** | [Phase Name] | XX-YY minutes | +| **Phase N** | [Phase Name] | XX-YY minutes | +| **Total** | End-to-End [Process Name] | **X-Y hours** | +``` + +**Guidelines:** +- Use **bold** for phase numbers and total row +- Time estimates should be ranges (min-max) in minutes or hours +- Total should sum to the overall estimate in the Overview +- Include 3-6 phases typically (not too granular, not too broad) + +**For plans with multiple options:** + +```markdown +## Time Breakdown by Implementation Option + +| Option | Approach | Initial Setup Time | Ongoing Maintenance | +|--------|----------|-------------------|---------------------| +| **Option 1** | [Method] | X-Y hours | Z min/operation | +| **Option 2** | [Method] | X-Y hours | Z min/operation | +| **Option 3** | [Method] | X-Y hours | Z min/operation | + +**Recommended:** Option [N] (detailed time breakdown below) + +### Option [N]: Detailed Phase Breakdown + +| Phase | Description | Time Estimate | +|-------|-------------|---------------| +[Standard phase table as above] +``` + +--- + +### 3. Prerequisites Section + +**Required before Phase 1:** + +```markdown +## Prerequisites + +- [ ] [Requirement 1] +- [ ] [Requirement 2] +- [ ] [Requirement 3] +- [ ] [Optional: Requirement 4 (optional, but recommended)] +``` + +**Guidelines:** +- Use checkboxes (`- [ ]`) for trackability +- List in order of validation (check access before checking software versions) +- Distinguish between required and optional prerequisites +- Include both technical and knowledge prerequisites + +--- + +### 4. Phase Sections + +**Each phase must include:** + +```markdown +## Phase [N]: [Phase Name] +**Estimated Time:** XX-YY minutes + +[1-2 sentence phase description explaining the goal] + +### Step [N]: [Step Name] +**Time:** X-Y minutes + +[Step instructions with code blocks, explanations, and verification steps] + +**[Optional Section: Why/Security Note/Troubleshooting]:** +[Additional context if needed] +``` + +**Step-Level Requirements:** +- Each step must have individual time estimate +- Include verification commands where applicable +- Add `# Expected: [output]` comments to commands +- Use consistent heading levels (## for Phase, ### for Step) + +**Example:** +```markdown +## Phase 1: Control Node Foundation (Watchtower Setup) +**Estimated Time:** 20-30 minutes + +### Step 1: Install Ansible Toolchain +**Time:** 10-15 minutes (depends on network speed) + +Connect to Watchtower via SSH and install the complete Ansible stack: + +```bash +# SSH to Watchtower +ssh chester@10.0.0.200 + +# Update package index +sudo apt update + +# Verify Ansible installation +ansible --version +# Expected: ansible [core 2.x.x] or newer +``` + +**Why these tools:** +- `ansible`: Execution engine +- `ansible-lint`: Code quality enforcement +``` + +--- + +### 5. Troubleshooting Section + +**Required before final checklist:** + +```markdown +## Troubleshooting + +### Issue: [Symptom Description] + +**Cause:** [Root cause explanation] + +**Fix:** +```bash +[Commands to resolve] +``` + +[Optional: Additional context or prevention tips] +``` + +**Guidelines:** +- Anticipate 3-5 common failure modes +- Use consistent format: Issue → Cause → Fix +- Include verification steps in the fix +- Order by likelihood (most common first) + +--- + +### 6. Summary/Checklist Section + +**Required at end of document:** + +```markdown +## Summary Checklist + +- [ ] [Major milestone 1] +- [ ] [Major milestone 2] +- [ ] [Major milestone 3] +- [ ] [Verification step] +- [ ] [Documentation updated] +- [ ] [Changes committed to Git] + +**Environment Status:** 🟢 **PRODUCTION READY** | 🟡 **TESTING** | 🔴 **NOT READY** +``` + +**Optional sections:** +```markdown +## Migration Checklist + +**Pre-Migration:** +- [ ] [Backup step] +- [ ] [Verification step] + +**Migration Steps:** +- [ ] [Core steps from the plan] + +**Post-Migration:** +- [ ] [Validation] +- [ ] [Documentation] +- [ ] [Cleanup] +``` + +--- + +### 7. Document Metadata (Footer) + +**Required at very end:** + +```markdown +--- + +**Document Version:** X.Y +**Last Updated:** [Month DD, YYYY] +**Author:** [Author Name/Tool] +**Review Cycle:** [Quarterly | Monthly | After infrastructure changes] +``` + +--- + +## Formatting Standards + +### Time Estimates + +**Range Format:** +- Use ranges for uncertainty: `10-15 minutes`, `2-3 hours` +- Larger range for first-time: `2-3 hours (first-time)` +- Smaller range for experienced: `45-60 minutes (experienced)` + +**Never use:** +- Exact times without ranges: ❌ `15 minutes` +- Vague estimates: ❌ `about an hour`, `quickly` + +### Code Blocks + +**Always specify language:** +```markdown +```bash +# Good: Language specified +``` + +```markdown +``` +# Bad: Generic code block +``` +``` + +**Include expected outputs:** +```bash +ansible --version +# Expected: ansible [core 2.x.x] or newer +``` + +**Add comments explaining why:** +```bash +# Generate ED25519 key (modern, secure, fast) +ssh-keygen -t ed25519 -C "ansible@watchtower" +``` + +### Emphasis & Highlighting + +**Use bold for:** +- Phase names in tables +- **Important:** warnings or critical notes +- **Goal:** objective statements +- Key metrics in overview + +**Use inline code for:** +- File paths: `ansible/ansible.cfg` +- Commands: `git-crypt unlock` +- Variables: `vault_password_file` +- Package names: `ansible-lint` + +**Use INFO blocks for decisions:** +```markdown +**Key Decisions:** +- `host_key_checking = False`: Simplifies homelab automation (acceptable for trusted private network) +- `forks = 3`: Limits parallel execution (prevents overwhelming Pi resources) +``` + +### Lists & Tables + +**Checkbox lists for trackable items:** +```markdown +- [ ] Ansible toolchain installed +- [ ] SSH keys distributed +- [ ] First playbook run successful +``` + +**Markdown tables for comparisons:** +```markdown +| Option | Pros | Cons | Time | +|--------|------|------|------| +| A | Fast | Complex | 1h | +| B | Simple | Slow | 3h | +``` + +### Links & References + +**Internal links use relative paths:** +```markdown +See [ansible/.ansible-lint](ansible/.ansible-lint) for configuration. +``` + +**External links use full URLs:** +```markdown +Git-crypt Documentation: https://github.com/AGWA/git-crypt +``` + +**Related documentation section:** +```markdown +## Related Documentation + +- [SECURITY_AUDIT_REPORT.md](../documentation/SECURITY_AUDIT_REPORT.md) - Security findings +- [SOP-001](../documentation/SOPs/SOP-001-Example.md) - Related procedure +``` + +--- + +## Optional Sections (Use When Applicable) + +### Rollback Plan + +For destructive or risky migrations: + +```markdown +## Rollback Plan + +If [technology] causes issues: + +```bash +# 1. Stop service +# 2. Restore backup +# 3. Revert configuration +``` + +**Recovery Time:** Estimated X-Y minutes +``` + +### Migration Strategy (Multi-Week Plans) + +For staged rollouts: + +```markdown +## Migration Strategy +**Total Timeline:** [N] weeks (staged rollout) | [M] days (aggressive deployment) + +### Week 1: [Phase Name] +**Time:** X-Y hours + +[Objectives] + +### Week 2: [Phase Name] +**Time:** X-Y hours + +[Objectives] +``` + +### Security Considerations + +For security-sensitive plans: + +```markdown +## Security Considerations + +### [Area of Concern] +- [Risk description] +- [Mitigation strategy] +- [Verification method] +``` + +### Maintenance & Next Steps + +For ongoing operations: + +```markdown +## Maintenance & Next Steps + +### Ongoing Operations + +**[Operation Name]:** +```bash +[Command] +``` + +### Future Enhancements + +1. **[Enhancement Name]:** + - [Description] + - [Estimated effort] +``` + +--- + +## Success Criteria Template + +Each plan should define measurable success criteria: + +```markdown +## Success Criteria + +- ✅ [Technical validation 1] +- ✅ [Technical validation 2] +- ✅ [Functional test passed] +- ✅ [Documentation updated] +- ✅ [Zero errors in logs] + +**Estimated Migration Time:** [Same as in overview] +**Maintenance:** [Ongoing time commitment] +``` + +--- + +## File Naming Convention + +**Pattern:** `plan-[technology][Action].md` + +**Examples:** +- `plan-ansibleSetup.md` — Setup/installation guide +- `plan-gitcryptMigration.md` — Migration from one state to another +- `plan-promptDistribution.md` — Distribution/deployment plan + +**Rules:** +- Use camelCase for multi-word components +- No spaces or special characters +- Prefix always `plan-` +- Suffix always `.md` + +--- + +## Quality Checklist + +Before committing a planning document, verify: + +- [ ] Overview includes total time estimate +- [ ] Time breakdown table present and accurate +- [ ] Prerequisites listed with checkboxes +- [ ] Each phase has time estimate +- [ ] Each step has individual time estimate +- [ ] Code blocks specify language +- [ ] Expected outputs documented +- [ ] Troubleshooting section included +- [ ] Summary checklist present +- [ ] Document metadata complete +- [ ] All links are valid +- [ ] Formatting consistent with examples +- [ ] Success criteria defined +- [ ] Related documentation referenced + +--- + +## Anti-Patterns (Common Mistakes) + +❌ **Missing time estimates:** +```markdown +## Phase 1: Setup +### Step 1: Install tools +``` + +✅ **Correct format:** +```markdown +## Phase 1: Setup +**Estimated Time:** 20-30 minutes + +### Step 1: Install tools +**Time:** 10-15 minutes +``` + +--- + +❌ **Vague success criteria:** +```markdown +- Everything works +- No errors +``` + +✅ **Specific validation:** +```markdown +- ✅ All nodes respond to `ansible all -m ping` +- ✅ Zero lint errors when running `ansible-lint playbooks/*.yml` +- ✅ Validation playbook completes with exit code 0 +``` + +--- + +❌ **Commands without context:** +```bash +git-crypt unlock +cat nodes/waldorf/plex/.env.secrets +``` + +✅ **Commands with verification:** +```bash +# Unlock with the key +git-crypt unlock ~/homelab-secrets.key + +# Verify decryption worked +cat nodes/waldorf/plex/.env.secrets +# Expected: plaintext secrets (not binary data) +``` + +--- + +❌ **Flat structure (no phases):** +```markdown +# Setup Guide +## Step 1 +## Step 2 +## Step 3 +[... 20 more steps ...] +``` + +✅ **Hierarchical organization:** +```markdown +# Setup Guide + +## Phase 1: Foundation (30-40 min) +### Step 1 (10 min) +### Step 2 (20 min) + +## Phase 2: Configuration (20-30 min) +### Step 3 (15 min) +### Step 4 (10 min) +``` + +--- + +## Example Template + +Use this as a starting point for new planning documents: + +```markdown +# [Title]: [Goal] + +## Overview + +[Description] + +**[Key Metric 1]:** [Value] +**[Key Metric 2]:** [Value] +**End State:** [Success description] + +**Estimated Time to Complete:** X-Y hours (first-time) | A-B hours (experienced) + +--- + +## Time Breakdown by Phase + +| Phase | Description | Time Estimate | +|-------|-------------|---------------| +| **Phase 1** | [Name] | XX-YY minutes | +| **Phase 2** | [Name] | XX-YY minutes | +| **Total** | End-to-End | **X-Y hours** | + +--- + +## Prerequisites + +- [ ] [Requirement 1] +- [ ] [Requirement 2] + +--- + +## Phase 1: [Name] +**Estimated Time:** XX-YY minutes + +### Step 1: [Action] +**Time:** X-Y minutes + +```bash +# Commands +``` + +--- + +## Phase 2: [Name] +**Estimated Time:** XX-YY minutes + +### Step 2: [Action] +**Time:** X-Y minutes + +--- + +## Troubleshooting + +### Issue: [Problem] +**Cause:** [Explanation] +**Fix:** +```bash +# Solution +``` + +--- + +## Summary Checklist + +- [ ] [Milestone 1] +- [ ] [Milestone 2] + +**Environment Status:** 🟢 **PRODUCTION READY** + +--- + +**Document Version:** 1.0 +**Last Updated:** [Date] +**Author:** [Name] +**Review Cycle:** Quarterly +``` + +--- + +## Enforcement + +This standard applies to: +- All files in `documentation/plans/` +- Migration guides +- Implementation roadmaps +- Multi-phase technical projects + +**Exclusions:** +- Quick reference guides (use KBA format instead) +- Single-step procedures (use SOP format instead) +- Architecture diagrams (standalone) + +--- + +**Document Version:** 1.0 +**Last Updated:** April 12, 2026 +**Author:** FrankGPT (Ansible Architect Mode) +**Review Cycle:** Quarterly or when planning format needs evolve