Decisions
User Tasks
Summary
Connect the Opus system to GitHub for version control workflow and automation.
Problem / Motivation
Changes need to be tracked, pushed, and managed via GitHub. Currently manual.
Proposed Solution
Automated git workflows — commit conventions, auto-push, PR creation.
Open Questions
1. GitHub MCP Server
Question: Should we use the GitHub MCP server for richer API access beyond the gh CLI?
| Option | Description |
|---|
| A) Yes, add GitHub MCP | Richer API access, better PR/issue management |
B) No, gh CLI is sufficient | Simpler setup, fewer dependencies |
Recommendation: Option A - More capabilities for automation.
Decision:
2. Backup Convention
Question: What gets pushed (vault, src, configs) vs what doesn’t (.env, local state)?
| Option | Description |
|---|
| A) Document explicit convention | Clear list of what’s tracked and what isn’t |
| B) Rely on .gitignore only | No separate documentation |
Recommendation: Option A - Explicit is better than implicit.
Decision:
Phase Overview
| Phase | Description | Status |
|---|
| Phase 1 | Basic git workflow | done |
| Phase 2 | Automation & backup | — |
Phase 1: Basic Git Workflow — done
Goal: Establish basic git repository and workflow.
| File / Feature | Details | Owner | Status |
|---|
| Commit conventions | Define commit message format | opus | done |
| Remote repository | Set up GitHub remote | opus | done |
| Branch strategy | Configure branch strategy | opus | done |
Result: Git repo initialized, GitHub remote created, branch strategy configured.
Phase 2: Automation & Backup — —
Goal: Automate git workflows and establish backup conventions.
| File / Feature | Details | Owner | Status |
|---|
| Auto-commit after feature completion | Triggered on feature done | opus | — |
| GitHub Actions CI/CD | Quartz deploy workflow (.github/workflows/quartz-deploy.yml) | opus | done |
| PR templates | Linked to feature requests | opus | — |
auto-changelog hook | Stop hook: generate changelog entry at session end | opus | — |
| Backup convention | Define what gets pushed vs what doesn’t; document or automate via Stop hook | mv | — |
Prerequisites / Gap Analysis
Requirements
| Requirement | Description |
|---|
| REQ-1 | Git repository initialized |
| REQ-2 | GitHub remote configured |
Current State
| Component | Status | Details |
|---|
| Git repository | done | Initialized with .gitignore |
| GitHub remote | done | Private repo created |
| Branch strategy | done | Main branch configured |
| Auto-commit | — | Not yet implemented |
| CI/CD | — | Not yet implemented |
Gap (What’s missing?)
| Gap | Effort | Blocker? |
|---|
| Auto-commit hook | Med | No |
| CI/CD pipeline | Med | No |
| Backup convention documentation | Low | No |
Test
Manual tests
| Test | Expected | Actual | Last |
|---|
| Push changes to GitHub | Code pushed successfully | pending | - |
| Commit message follows conventions | Clean, traceable commits | pending | - |
| Backup convention documented | Clear what’s protected by git | pending | - |
AI-verified tests
| Scenario | Expected behavior | Verification method |
|---|
| … | … | … |
E2E tests
Integration tests
Unit tests
| Component | Tests | Coverage |
|---|
| … | … | … |
History
| Date | Event | Details |
|---|
| 2026-02-26 | Created | From brain dump |
| 2026-02-26 | Phase 1 complete | .gitignore, initial commit, branch main, private GitHub repo |
| 2026-02-27 | Renumbered | From FR-028 to FR-018 |
| 2026-03-20 | GitHub Actions | Quartz deploy workflow added for Cloudflare Pages |
References