alex/dotfiles
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

initial commit

Browse Source
This commit is contained in:
alex
2026-03-08 14:37:55 +00:00
commit 4da672cbc7
62 changed files with 3460 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

52
.config/opencode/skills/doc-coverage/SKILL.md Normal file
View File

@@ -0,0 +1,52 @@
---
name: doc-coverage
description: Documentation coverage checklist and update procedures — load when completing a feature or change set
---
## When to Use
Load this skill when a feature or change set is nearing completion. Documentation is a **completion gate** — a task is not done until docs are handled.
## Coverage Checklist
For every completed change set, verify documentation coverage:
### 1. README
- [ ] Does the README reflect the current state of the project?
- [ ] Are new features, commands, or configuration options documented?
- [ ] Are removed features cleaned up from the README?
### 2. Docs directory (`docs/*`)
- [ ] Are there relevant docs files that need updating?
- [ ] Do new features need their own doc page?
- [ ] Are API changes reflected in API documentation?
### 3. AGENTS.md / agent definitions
- [ ] Did this change alter workflow, policies, or agent behavior?
- [ ] If yes, update AGENTS.md or the relevant agent definition file.
### 4. Inline documentation
- [ ] Are complex functions/components documented with comments explaining **why**, not **what**?
- [ ] Are public APIs documented with parameter descriptions?
## Update Procedure
1. Review the list of changed files and their purpose.
2. Identify which documentation files are affected.
3. Read the current state of each affected doc file.
4. Update docs to reflect the implemented changes — keep descriptions accurate and concise.
5. If a change removes functionality, remove or update the corresponding documentation.
6. If creating a new feature, add documentation in the most appropriate location.
## Anti-patterns
- **Never leave stale docs.** If you changed behavior, the docs must change too.
- **Never create placeholder docs.** "TODO: document this" is not documentation.
- **Never duplicate content across doc files.** Link to the canonical source instead.
- **Never wait for the user to ask.** If docs need updating, update them proactively as part of the change set.
## Delegation
- The **librarian** subagent is the specialist for documentation work.
- Lead should delegate doc coverage review to librarian after coder completes implementation.
- Librarian reads the changes, identifies doc gaps, and writes/updates documentation.

102
.config/opencode/skills/git-workflow/SKILL.md Normal file
View File

@@ -0,0 +1,102 @@
---
name: git-workflow
description: Procedures for git commits, worktrees, branches, and GitHub PRs — load before any git operation
---
## Git Commit Procedure
1. Run `git status` to see all untracked and modified files.
2. Run `git diff` (staged + unstaged) to review changes that will be committed.
3. Run `git log --oneline -5` to see recent commit message style.
4. Draft a Conventional Commit message (`feat:`, `fix:`, `chore:`, `refactor:`, `docs:`, `test:`):
- Focus on **why**, not **what**.
- 1-2 sentences max.
- Match the repository's existing style.
5. Check for secrets: do NOT commit `.env`, credentials, key files, or `.megamemory/` contents.
6. If `.megamemory/` is not in `.gitignore`, add it before the first commit.
7. Stage relevant files: `git add <files>` (not blindly `git add .`).
8. Commit: `git commit -m "<message>"`.
9. Run `git status` after commit to verify success.
## Git Worktree Procedure
### When to use worktrees:
- Always use a worktree for new feature work to keep `main` clean.
- **One worktree per independent workstream.** If implementing multiple unrelated features, create separate worktrees for each.
### Deciding on worktree count:
- **1 worktree**: Single feature, or 2 tightly-coupled features sharing state/files.
- **2+ worktrees**: Features that touch different domains, have different risk profiles, or could ship independently. Each gets its own worktree, branch, and PR.
### Creating a worktree for a new feature:
```bash
# From project root
git worktree add .worktrees/<feature-name> -b <branch-name>
```
### Creating multiple worktrees for independent workstreams:
```bash
# From project root — create all worktrees upfront
git worktree add .worktrees/<workstream-1> -b feat/<workstream-1>
git worktree add .worktrees/<workstream-2> -b feat/<workstream-2>
```
### Working in a worktree:
- All file edits, test runs, and dev server starts must use the worktree path.
- Example: `workdir="/path/to/project/.worktrees/my-feature"` for all bash commands.
- **Each coder invocation must target a specific worktree** — never mix worktrees in one coder dispatch.
### Completing a worktree:
```bash
# From main working tree
git checkout main
git merge <branch-name>
git worktree remove .worktrees/<feature-name>
git branch -d <branch-name> # optional cleanup
```
### Completing multiple worktrees (independent PRs):
Complete and merge each worktree independently. If workstream-2 depends on workstream-1, merge workstream-1 first, then rebase workstream-2 before merging.
## GitHub PR Procedure
### Push and create PR:
```bash
# Push branch
git push -u origin <branch-name>
# Create PR with heredoc body
gh pr create --title "<title>" --body "$(cat <<'EOF'
## Summary
- <bullet 1>
- <bullet 2>
## Changes
- <file/area>: <what changed>
## Testing
- <how it was validated>
EOF
)"
```
### Check CI status:
```bash
gh run list # List recent workflow runs
gh run view <run-id> # View specific run details
gh pr checks <pr-number> # Check statuses on a PR
```
### Issue operations:
```bash
gh issue list # List open issues
gh issue view <number> # View specific issue
gh issue comment <number> -b "<comment>" # Add comment
```
## Safety Rules
- **Never `git push --force` to `main`/`master`** unless the user explicitly confirms.
- **Never skip hooks** (`--no-verify`) unless the user explicitly requests it.
- **Never `git commit --amend`** unless: (1) explicitly requested OR pre-commit hook auto-modified files, (2) HEAD was created in this session, AND (3) commit has NOT been pushed to remote.
- If commit fails due to pre-commit hook, fix the issue and create a NEW commit.

199
.config/opencode/skills/work-decomposition/SKILL.md Normal file
View File

@@ -0,0 +1,199 @@
---
name: work-decomposition
description: Procedure for decomposing multi-feature requests into independent workstreams — load when user requests 3+ features or features span independent domains
---
## When to Load
Load this skill when any of these conditions are true:
- User requests **3 or more distinct features** in a single message or session.
- Requested features span **independent domains** (e.g., frontend-only + backend API + new service).
- Requested features have **mixed risk profiles** (e.g., UI tweak + encryption + new auth surface).
This skill supplements planning. Load it **before the PLAN phase** and follow the procedure below.
## Decomposition Procedure
### Step 1: Identify Features
List each distinct feature the user requested. A feature is a user-visible capability or behavior change.
Rules:
- If a request contains sub-features that can be independently shipped and tested, count them separately.
- "Add temperature display" and "add optimize button" are two features, even if both touch the same page.
- "Encrypted API key storage" and "wire recommendations to use stored keys" are two features — storage is infrastructure, wiring is application logic.
### Step 2: Assess Independence
For each pair of features, evaluate:
- Do they share modified files?
- Does one depend on the other's output/data?
- Do they touch the same data models or APIs?
- Could one ship to production without the other?
Group features that share hard dependencies into the same **workstream**. Features with no shared dependencies are **independent workstreams**.
### Step 3: Classify Risk Profile
For each workstream, classify its highest-risk feature:
| Risk | Triggers | Quality Pipeline |
|------|----------|-----------------|
| **Low** | Frontend-only, config changes, copy/UI tweaks | Tier 3 (fast) |
| **Medium** | New API endpoints, data model changes, third-party integrations | Tier 2 (standard) |
| **High** | Auth/security changes, encryption, new service surfaces (MCP, webhooks, SSO), data migration, secret handling | Tier 1 (full) + human checkpoint |
### Step 4: Allocate Workstreams → Worktrees
Each independent workstream gets its own:
- **Worktree**: `.worktrees/<workstream-name>`
- **Branch**: `feat/<workstream-name>`
- **PR**: Separate pull request for independent review
- **Quality pipeline**: Independent coder → reviewer → tester cycle
Exception: Two low-risk features that touch the same area (e.g., two UI tweaks in the same component) may share a worktree if they can be implemented and committed sequentially.
### Step 5: Order Workstreams
- If workstreams have dependencies, order them so dependent work starts after its prerequisite is merged or at least reviewed.
- If independent, dispatch in parallel (multiple coders simultaneously).
- Prefer shipping lower-risk workstreams first — they unblock value sooner and reduce in-flight complexity.
### Step 6: Present Decomposition to User
**Before proceeding to implementation**, present the decomposition to the user:
```
Proposed workstreams:
1. [workstream-name] (risk: low/medium/high)
Features: [list]
Worktree: .worktrees/[name]
Branch: feat/[name]
Estimated pipeline: Tier [1/2/3]
2. [workstream-name] (risk: low/medium/high)
...
Execution order: [1] → [2] (or [1] and [2] in parallel)
Human checkpoints: [list any high-risk decisions needing approval]
```
Wait for user approval before proceeding. If the user adjusts grouping, update accordingly.
## Human Checkpoint Triggers
The Lead **MUST** stop and ask the user for explicit approval before dispatching coder work when **ANY** of these conditions are met:
### Mandatory Checkpoints
1. **Security-sensitive design**: Encryption approach, auth model/flow, secret storage mechanism, token management, permission model changes.
2. **Architectural ambiguity**: Multiple valid approaches with materially different tradeoffs that aren't resolvable from codebase context alone (e.g., MCP SDK vs REST endpoints, embedded vs external service, SQL vs NoSQL for new data).
3. **Vision-dependent features**: Features where the user's intended UX, behavior model, or product direction isn't fully specified (e.g., "improve recommendations" — improve how? what inputs? what output format?).
4. **New external dependencies**: Adding a new service, SDK, or infrastructure component not already in the project.
5. **Data model changes with migration impact**: New models or schema changes that affect existing production data.
### Checkpoint Format
When triggering a checkpoint, present:
- The specific design decision that needs input
- 2-3 concrete options with pros/cons/tradeoffs
- Your recommendation and rationale
- What you'll do if the user doesn't respond (safe default)
### What Is NOT a Checkpoint
Do not interrupt the user for:
- Implementation details (naming, file organization, code patterns)
- Choices fully determined by existing codebase conventions
- Decisions already covered by prior user answers or megamemory guidance
## Coder Dispatch Rules
### One Feature Per Coder — No Exceptions
Each coder invocation must implement **exactly one feature** or a tightly-coupled subset of one feature. This is a hard rule, not a guideline.
### Why This Matters
- Focused prompts produce higher-quality implementations
- Each feature goes through its own review/test cycle independently
- Failures in one feature don't block others
- Commits stay atomic and revertable
### Parallel Dispatch
If features are independent (different files, no shared state), dispatch multiple coder invocations **simultaneously in the same message**. This is faster than sequential single-feature dispatches.
### Coder Prompt Requirements
Each coder dispatch MUST include:
1. **Single feature** description with acceptance criteria
2. **Specific file paths and edit points** from discovery (not vague references)
3. **Discovered values verbatim**: i18n keys, API signatures, component names, existing patterns
4. **Worktree path** for all file operations
5. **Active megamemory concept ID** for the task
6. **Quality tier** so coder understands the expected rigor
### Anti-patterns — Never Do These
- ❌ Sending 2+ unrelated features to one coder invocation
- ❌ Saying "implement the phased plan" without specifying which single feature
- ❌ Including features the critic said to defer or drop
- ❌ Embedding unresolved blockers as "constraints" for the coder to figure out
- ❌ Proceeding past a RESOLVE verdict without actually resolving the blockers
## Commit Strategy
Within each workstream/worktree:
- **One commit per feature** after it passes review/test
- Conventional Commit format: `feat: <what and why>`
- If a workstream contains 2 closely-related features, commit them separately (not as one giant diff)
## Decomposition Decision Examples
### Example: 4 features requested (like session ses_3328)
```
User requests: optimize button, temperature display, AI recommendations with key storage, MCP server
Analysis:
- Optimize button: frontend-only, low risk, independent
- Temperature: backend+frontend, medium risk, independent
- AI recommendations + key storage: backend, HIGH risk (encryption, secrets), independent
- MCP server: new service surface, HIGH risk (auth, architecture), independent
Decomposition:
Workstream 1: optimize-and-temp (low/medium risk, Tier 2)
- .worktrees/optimize-and-temp, feat/optimize-and-temp
- Coder A: optimize button → review → test → commit
- Coder B: temperature display → review → test → commit
- PR #1
Workstream 2: ai-recommendations (HIGH risk, Tier 1)
- .worktrees/ai-recommendations, feat/ai-recommendations
- Human checkpoint: encryption approach + key storage design
- Coder C: encrypted key CRUD → security review → test → commit
- Coder D: wire recommendations → review → test → commit
- PR #2
Workstream 3: mcp-server (HIGH risk, Tier 1) — or DEFERRED per critic
- Human checkpoint: MCP SDK vs REST, auth model
- .worktrees/mcp-server, feat/mcp-server
- Coder E: MCP implementation → security review → adversarial test → commit
- PR #3
```
### Example: 2 tightly-coupled features
```
User requests: add dark mode toggle + persist theme preference
Analysis:
- Toggle and persistence are tightly coupled (same state, same UX flow)
- Both touch settings page + theme context
Decomposition:
Single workstream: dark-mode (medium risk, Tier 2)
- One worktree, one branch, one PR
- Coder A: toggle + persistence together (they share state)
- Or split if toggle is pure UI and persistence is API: two coder calls
```