skills/DEPLOYMENT-QUESTIONS.md

# Deployment Architecture Questions

## Current Understanding

**Development flow**:
```
~/proj/skills/            → Develop & test skills
     ↓ (manual copy)
~/proj/dotfiles/claude/skills/  → Source of truth for deployment
     ↓ (nix home-manager)
~/.claude/skills/         → Runtime (Claude Code)
~/.config/opencode/skills/      → Runtime (OpenCode)
```

**Project-local flow**:
```
<project>/.opencode/command/  → Project-specific commands
     ↓ (auto-loaded by OpenCode)
Available only in that project
```

## Questions to Answer

### 1. Repository Relationship

**Current model**: Manual copy from skills repo to dotfiles

**Questions**:
- Should `~/proj/skills` be a submodule of dotfiles?
- Should dotfiles symlink to skills repo instead of copying?
- Is the manual copy step intentional (review gate)?
- How do we keep them in sync?

**Options**:
```
A) Manual copy (current)
   - Pro: Review gate, dotfiles is source of truth
   - Con: Easy to get out of sync

B) Git submodule
   - dotfiles includes skills as submodule
   - Nix deploys from submodule
   - Pro: Version controlled, atomic
   - Con: Submodule complexity

C) Symlink in Nix
   - home.file.".claude/skills/foo".source = ~/proj/skills/skills/foo
   - Pro: No copy, always in sync
   - Con: Development changes immediately live

D) Separate repos, manual sync
   - Keep current model
   - Add deployment script to help
   - Pro: Clear separation, review step
   - Con: Manual process
```

**My take**: Option D feels right. Skills repo is for development/experimentation, dotfiles is for stable deployment. The copy step is a deployment decision point.

### 2. OpenCode Agents

**What we know**:
- OpenCode has "agents" concept (keybind: `<leader>a` for agent list)
- Commands can specify agent via frontmatter: `agent: plan`
- Skills plugin loaded via `"plugin": ["opencode-skills"]`

**Questions**:
- What agents exist? (plan, code, debug, etc.?)
- Do agents have different capabilities?
- Should skills target specific agents?
- Do skills work across all agents by default?

**Need to research**:
- OpenCode docs on agents
- Check `.opencode/command/` for agent examples
- Test if skills work with different agents

**Hypothesis**: Skills are agent-agnostic, agents are just different personalities/modes. Commands can route to specific agents, but skills work with whoever invokes them.

### 3. Global vs Project-Local Skills

**Global skills** (`~/.config/opencode/skills/`):
- Available in all projects
- Examples: worklog, niri-window-capture, screenshot-latest
- Deployed via Nix from dotfiles

**Project-local** (`.opencode/command/`):
- Available only in that project
- Examples: /test (nix flake check), /rebuild (nixos-rebuild)
- Loaded directly from project directory

**Questions**:
- Can `.opencode/` contain `skills/` not just `command/`?
- What's the difference between a skill and a command?
- Should project-local be commands or skills?

**Current understanding**:
- **Commands** = User-invoked slash commands (`/test`)
- **Skills** = AI-invoked based on intent (natural language)
- Project-local are commands because they're explicit actions
- Skills are almost always global (AI decides when to use)

**Exception**: Could have project-specific skills
- Example: "Django migration skill" only for Django projects
- Pattern: `.opencode/skills/django-migrations/SKILL.md`
- Loaded when working in that project

### 4. Security-Sensitive Skills

**niri-window-capture is unique**:
- High security risk
- Requires user configuration before deployment
- Needs audit logging
- Should users be able to enable/disable at runtime?

**Questions**:
- Should security-sensitive skills be opt-in after deployment?
- How to prevent accidental invocation?
- Should there be a "skills.disabled" list?
- How to make security review part of deployment workflow?

**Options**:
```
A) Deploy but document requirements
   - Skills always available after deployment
   - User must review SECURITY.md
   - User configures niri block-out rules
   - Trust deployment decision

B) Deploy with enable flag
   - Skill deployed but inactive
   - User runs: enable-skill niri-window-capture
   - Requires acknowledgment of security docs
   - More complex

C) Don't deploy by default
   - Security-sensitive skills opt-in only
   - User manually deploys after review
   - Separate deployment process
```

**My take**: Option A. If user deploys to dotfiles and rebuilds, they've made the decision. Security docs in skill are sufficient warning.

### 5. Deployment Helper Tools

**Current**: Manual process
1. Copy skill to dotfiles
2. Edit claude.nix
3. Edit opencode.nix
4. Rebuild
5. Restart agents

**Questions**:
- Should we automate this?
- Should deployment script update Nix configs?
- Should there be validation before deployment?
- Should there be rollback capability?

**Created**: `bin/deploy-skill.sh` (copies + shows instructions)

**Could add**:
- Automatic Nix config updates
- Validation (check SKILL.md exists, security docs present)
- Test suite (does skill work before deploying?)
- Rollback (remove from dotfiles + Nix configs)

## Decisions Needed

### Immediate (for current skills)

1. **Deploy screenshot-latest?**
   - Low risk, useful globally
   - Decision: Yes, deploy

2. **Deploy niri-window-capture?**
   - High risk, requires review
   - Decision: After user reviews SECURITY.md

3. **Update DEPLOYMENT.md with final model?**
   - Document chosen approach
   - Decision: Pending answers above

### Short-term (for future skills)

4. **Research OpenCode agents**
   - Understand agent model
   - Document in DEPLOYMENT.md
   - Decision: Research needed

5. **Define project-local skill pattern**
   - When to use vs global
   - How to structure
   - Decision: Pending research

6. **Enhance deployment tooling**
   - Auto-update Nix configs?
   - Validation checks?
   - Decision: After more experience

## Proposed Deployment Model (Draft)

### For Global Skills

**Development**:
1. Develop in `~/proj/skills/skills/<name>/`
2. Test locally with symlink
3. Iterate until stable

**Deployment**:
1. Run: `./bin/deploy-skill.sh <name>`
2. Review security docs if present
3. Edit `~/proj/dotfiles/home/claude.nix` (add skill)
4. Edit `~/proj/dotfiles/home/opencode.nix` (add skill)
5. Commit to dotfiles: `git add && git commit -m "Add <name> skill"`
6. Rebuild: `sudo nixos-rebuild switch --flake .#delpad`
7. Restart agents

**Maintenance**:
- Update in skills repo
- Copy to dotfiles when stable
- Rebuild to deploy updates

### For Project-Local Commands

**Development**:
1. Create in `<project>/.opencode/command/<name>.md`
2. Restart OpenCode to load
3. Test in that project

**No deployment needed** - auto-loaded from project directory

### For Project-Local Skills (if needed)

**Pattern** (hypothetical):
1. Create in `<project>/.opencode/skills/<name>/SKILL.md`
2. OpenCode loads from project directory?
3. Available only when working in that project

**Need to verify**: Does OpenCode support `.opencode/skills/`?

## Next Steps

1. Research OpenCode agents documentation
2. Test project-local skills pattern
3. Make deployment decision for screenshot-latest
4. Review SECURITY.md for niri-window-capture
5. Update DEPLOYMENT.md with final model
6. Document in dotfiles after deployment

## References

- Dotfiles workflow: `~/proj/dotfiles/docs/skills-and-commands-workflow.md`
- OpenCode docs: https://opencode.ai/docs
- Current deployment: DEPLOYMENT.md
- Security analysis: skills/niri-window-capture/SECURITY.md