atxtechbro / atxtechbro/dotfiles
docs: create commands/README.md documenting AI provider agnostic slash command architecture
- Dominant language
- Shell
- Stars
- 27
- Forks
- 2
- PR merge metrics
- No merged PRs in 30d
Description
## Problem
**Spilled Coffee Principle Violation**: The slash command system uses vendor-agnostic storage with symlinks, but this architecture is not properly documented. If laptop dies, you lose knowledge of:
1. **Where commands actually live**: `commands/templates/` (NOT `.claude/command-templates/`)
2. **Symlink structure**: Which directories are provider-specific symlinks vs source
3. **Edit workflow**: Always edit source files, never symlinked copies
4. **Provider agnostic design**: One source serves all AI providers
## Current Architecture (Discovered)
**Source files** (in source control):
- ✅ `commands/templates/close-issue.md`
- ✅ `commands/templates/retro.md`
**Provider symlinks** (created by setup.sh, NOT in source control):
- `.claude/command-templates/` → `commands/templates/`
- `.amazonq/commands/` → generated from `commands/templates/`
- `.cursor/commands/` → similar pattern
## Requirements
### 1. Create `commands/README.md`
Comprehensive documentation including:
**Architecture Overview:**
- AI provider agnostic design philosophy
- Source location: `commands/templates/` (canonical files)
- Provider-specific symlinks vs generated files
- Reference to [Anthropic slash commands docs](https://docs.anthropic.com/en/docs/claude-code/slash-commands)
**Edit Workflow:**
- ✅ **ALWAYS EDIT**: `commands/templates/file.md` (source files)
- ❌ **NEVER EDIT**: `.claude/command-templates/file.md` (symlinks)
- Setup.sh creates symlinks automatically
- Command generation process for each provider
**File Locations:**
- Source: `https://github.com/atxtechbro/dotfiles/tree/main/commands/templates`
- NOT: `https://github.com/atxtechbro/dotfiles/tree/main/.claude` (doesn't exist in source)
### 2. Source Control Symlinks Decision
**Evaluate**: Should symlinks be checked into source control for spilled coffee compliance?
- **Pros**: Immediate visibility, full architecture in git
- **Cons**: Git symlink platform compatibility issues
### 3. Update Existing Documentation
- Update main README.md to point to `commands/README.md`
- Update any references pointing to `.claude/` paths
- Ensure setup.sh process is documented
## Benefits
1. **Spilled Coffee Compliance**: Architecture survives laptop death
2. **AI Provider Agnosticism**: Clear separation of content from provider structure
3. **Developer Onboarding**: New contributors understand system immediately
4. **Future Iteration**: Easy to find and modify core slash commands
5. **Official Integration**: Links to Anthropic's documentation
## Acceptance Criteria
- [ ] `commands/README.md` created with comprehensive architecture docs
- [ ] Clear "edit source not symlinks" rule documented
- [ ] Links to Anthropic slash commands documentation
- [ ] Symlink vs source control decision made and documented
- [ ] Setup.sh symlink creation process explained
- [ ] File location URLs point to correct GitHub paths
- [ ] Main README.md updated to reference new documentation
## Success Criteria
Future developers (including future you) can:
1. **Find commands**: Know that `commands/templates/` is the source
2. **Edit correctly**: Never accidentally edit symlinked copies
3. **Understand architecture**: See the provider-agnostic design
4. **Recover from laptop death**: Recreate symlink structure from docs
## Related
Discovered during #776 audit - confusion about which file to edit revealed undocumented symlink architecture violating spilled coffee principle.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start by reading setup.sh, README.md, and the files under commands/templates/ to verify how source files, provider symlinks, and generated files are handled. Create commands/README.md, update README.md and any .claude/ references, and document the source-control symlink decision, Anthropic link, setup process, and correct GitHub paths. Done means the acceptance criteria are covered and the edit workflow is unambiguous.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- bash
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100