feat: add proposal for user documentation (README.md)
Create OpenSpec proposal to add comprehensive user-facing documentation that explains setup, configuration, and usage of implemented features. The proposal includes: - Framework introduction and feature overview - Prerequisites and setup instructions - Complete workflow documentation (all 7 slash commands) - Quick start guide for experienced users - Directory structure explanation - Profile setup shortcut (using Claude to help populate from docs) Focuses only on implemented features, excludes aspirational/unimplemented functionality like automated CV generation. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Markus Graf
@@ -0,0 +1,314 @@
|
||||
# Tasks: Add User Documentation (README.md)
|
||||
|
||||
## Overview
|
||||
Create comprehensive user-facing documentation in README.md that covers setup, configuration, and usage of all implemented features.
|
||||
|
||||
## Prerequisites
|
||||
- Review all implemented slash commands in src/.claude/commands/
|
||||
- Review archived OpenSpec changes to understand implemented features
|
||||
- Review CLAUDE.md for current framework instructions
|
||||
|
||||
## Task Breakdown
|
||||
|
||||
### 1. Create README.md Structure
|
||||
**Description**: Create README.md file in repository root with complete documentation structure.
|
||||
|
||||
**Steps**:
|
||||
1. Create README.md in repository root
|
||||
2. Add title and brief tagline
|
||||
3. Create section headers:
|
||||
- About
|
||||
- Features
|
||||
- Prerequisites
|
||||
- Setup
|
||||
- Quick Start
|
||||
- Workflow
|
||||
- Directory Structure
|
||||
- Commands Reference
|
||||
- Troubleshooting (optional)
|
||||
|
||||
**Validation**: File exists at /Users/markus.graf/workspace/Bewerbungszauberer/README.md
|
||||
|
||||
**Estimated effort**: 15 minutes
|
||||
|
||||
---
|
||||
|
||||
### 2. Write About and Features Sections
|
||||
**Description**: Document what the framework is and what it can do (implemented features only).
|
||||
|
||||
**Steps**:
|
||||
1. Write brief description of framework purpose (job application document generation)
|
||||
2. Mention Claude Code as the AI agent platform
|
||||
3. List implemented features:
|
||||
- Application workspace management
|
||||
- Profile validation
|
||||
- Document analysis and strategy generation
|
||||
- Cover letter generation
|
||||
- Swiss format PDF conversion
|
||||
- Application email generation
|
||||
4. Emphasize markdown-based workflow with slash commands
|
||||
|
||||
**Validation**: Sections accurately describe framework without mentioning unimplemented features
|
||||
|
||||
**Estimated effort**: 20 minutes
|
||||
|
||||
---
|
||||
|
||||
### 3. Document Prerequisites
|
||||
**Description**: List all requirements users need before using the framework.
|
||||
|
||||
**Steps**:
|
||||
1. Document required prerequisites:
|
||||
- Claude Code installation (with link/reference)
|
||||
2. Document optional prerequisites:
|
||||
- Pandoc (for PDF conversion)
|
||||
- LaTeX/pdflatex (for PDF conversion)
|
||||
3. Note system requirements (macOS, Linux, Windows with appropriate tools)
|
||||
4. Clarify what's required vs optional
|
||||
|
||||
**Validation**: All prerequisites are accurate and necessary
|
||||
|
||||
**Estimated effort**: 10 minutes
|
||||
|
||||
---
|
||||
|
||||
### 4. Write Setup Instructions
|
||||
**Description**: Provide step-by-step setup guide for new users.
|
||||
|
||||
**Steps**:
|
||||
1. Write setup steps:
|
||||
- Step 1: Install Claude Code
|
||||
- Step 2: Create working directory (e.g., "my-applications")
|
||||
- Step 3: Copy src/ directory contents to working directory
|
||||
- Step 4: Navigate to working directory in terminal
|
||||
- Step 5: Fill out profile.md
|
||||
2. Document profile setup shortcut:
|
||||
- Create subdirectory (e.g., "documents/")
|
||||
- Add existing CV, certificates, portfolio
|
||||
- Prompt Claude to help populate profile from documents
|
||||
3. Provide example commands for each step
|
||||
|
||||
**Validation**: New user can follow instructions without prior knowledge
|
||||
|
||||
**Estimated effort**: 25 minutes
|
||||
|
||||
---
|
||||
|
||||
### 5. Create Quick Start Guide
|
||||
**Description**: Provide condensed guide for experienced users or second-time usage.
|
||||
|
||||
**Steps**:
|
||||
1. Write minimal quick start sequence:
|
||||
```bash
|
||||
# 1. Setup
|
||||
cp -r src/* my-applications/
|
||||
cd my-applications/
|
||||
# Edit profile.md
|
||||
|
||||
# 2. Create application
|
||||
/new-application "Company - Job Title"
|
||||
|
||||
# 3. Add job posting to input/
|
||||
|
||||
# 4. Generate documents
|
||||
/populate-application
|
||||
/write-cover-letter
|
||||
/convert-cover-letter
|
||||
/write-application-email
|
||||
```
|
||||
2. Note assumptions (Claude Code installed, terminal familiarity)
|
||||
|
||||
**Validation**: Experienced user can complete workflow quickly
|
||||
|
||||
**Estimated effort**: 15 minutes
|
||||
|
||||
---
|
||||
|
||||
### 6. Document Complete Workflow
|
||||
**Description**: Provide detailed end-to-end workflow with explanations.
|
||||
|
||||
**Steps**:
|
||||
1. Document step-by-step workflow:
|
||||
- Step 0: Validate profile (`/validate-profile`)
|
||||
- Step 1: Create application (`/new-application "Company - Role"`)
|
||||
- Step 2: Add job posting/documents to input/
|
||||
- Step 3: Populate application (`/populate-application`)
|
||||
- Step 4: Review and refine application.md
|
||||
- Step 5: Validate application (`/validate-application`)
|
||||
- Step 6: Generate cover letter (`/write-cover-letter`)
|
||||
- Step 7: Review cover-letter.md
|
||||
- Step 8: Convert to PDF (`/convert-cover-letter`)
|
||||
- Step 9: Add CV and cover letter PDF to attachments/
|
||||
- Step 10: Generate email (`/write-application-email`)
|
||||
- Step 11: Review and send
|
||||
2. Add brief explanation for each step
|
||||
3. Note which steps are optional or can be repeated
|
||||
|
||||
**Validation**: Workflow matches implemented features and actual usage patterns
|
||||
|
||||
**Estimated effort**: 30 minutes
|
||||
|
||||
---
|
||||
|
||||
### 7. Create Commands Reference
|
||||
**Description**: Document all implemented slash commands with usage examples.
|
||||
|
||||
**Steps**:
|
||||
1. Document each command with:
|
||||
- Command name
|
||||
- Description
|
||||
- Syntax/parameters
|
||||
- Example usage
|
||||
- Common flags
|
||||
2. Commands to document:
|
||||
- `/validate-profile`
|
||||
- `/new-application "Company - Job Title"`
|
||||
- `/populate-application`
|
||||
- `/validate-application [optional-app-name]`
|
||||
- `/write-cover-letter [optional-app-name] [--skip-validation] [--force]`
|
||||
- `/convert-cover-letter`
|
||||
- `/write-application-email [optional-app-name] [--skip-validation] [--force]`
|
||||
3. Use realistic examples (e.g., "TechCorp - Senior Developer")
|
||||
|
||||
**Validation**: All commands in src/.claude/commands/ are documented
|
||||
|
||||
**Estimated effort**: 30 minutes
|
||||
|
||||
---
|
||||
|
||||
### 8. Document Directory Structure
|
||||
**Description**: Explain the directory layout users will work with.
|
||||
|
||||
**Steps**:
|
||||
1. Create visual directory tree example:
|
||||
```
|
||||
my-applications/
|
||||
├── profile.md
|
||||
├── CLAUDE.md
|
||||
├── .claude/
|
||||
│ ├── commands/
|
||||
│ └── templates/
|
||||
└── applications/
|
||||
└── pending/
|
||||
└── 2025-11-10-Company-Role/
|
||||
├── application.md
|
||||
├── input/
|
||||
├── cover-letter.md
|
||||
├── application-email.md
|
||||
└── attachments/
|
||||
```
|
||||
2. Explain purpose of each key file/folder:
|
||||
- profile.md: Personal and professional information
|
||||
- CLAUDE.md: AI assistant instructions
|
||||
- .claude/: Framework commands and templates
|
||||
- applications/pending/: Active applications
|
||||
- input/: Job postings and research materials
|
||||
- attachments/: Final PDFs to send
|
||||
|
||||
**Validation**: Structure reflects actual directory layout after setup
|
||||
|
||||
**Estimated effort**: 20 minutes
|
||||
|
||||
---
|
||||
|
||||
### 9. Add Troubleshooting Section (Optional)
|
||||
**Description**: Document common issues and solutions.
|
||||
|
||||
**Steps**:
|
||||
1. Add troubleshooting section (if helpful)
|
||||
2. Document common issues:
|
||||
- Profile validation failures → run `/validate-profile`
|
||||
- PDF conversion issues → check Pandoc/LaTeX installation
|
||||
- Missing documents → verify attachments/ folder contents
|
||||
3. Keep concise - detailed troubleshooting is in CLAUDE.md for AI
|
||||
|
||||
**Validation**: Troubleshooting addresses most common user issues
|
||||
|
||||
**Estimated effort**: 15 minutes
|
||||
|
||||
---
|
||||
|
||||
### 10. Add Maintenance and Best Practices
|
||||
**Description**: Provide guidance on keeping the framework useful over time.
|
||||
|
||||
**Steps**:
|
||||
1. Document profile maintenance:
|
||||
- Update profile.md after new projects, certifications, roles
|
||||
- Keeps generated documents accurate and current
|
||||
2. Note best practices:
|
||||
- Review generated documents before sending
|
||||
- Personalize AI-generated content
|
||||
- Keep input/ folder organized with relevant documents
|
||||
3. Framework updates:
|
||||
- Note that src/ contains framework source
|
||||
- Updates can be applied by selectively copying updated files
|
||||
|
||||
**Validation**: Users understand ongoing maintenance requirements
|
||||
|
||||
**Estimated effort**: 10 minutes
|
||||
|
||||
---
|
||||
|
||||
### 11. Add Examples and Use Cases
|
||||
**Description**: Provide concrete examples that illustrate usage.
|
||||
|
||||
**Steps**:
|
||||
1. Create example scenario:
|
||||
- User applying to "TechCorp - Senior Developer" position
|
||||
- Show command sequence with actual parameters
|
||||
- Show example file contents where helpful
|
||||
2. Maintain consistent example throughout README
|
||||
3. Use realistic but generic company names
|
||||
|
||||
**Validation**: Examples are clear and illustrate actual usage patterns
|
||||
|
||||
**Estimated effort**: 20 minutes
|
||||
|
||||
---
|
||||
|
||||
### 12. Proofread and Validate
|
||||
**Description**: Review documentation for accuracy, clarity, and completeness.
|
||||
|
||||
**Steps**:
|
||||
1. Read through entire README as if you're a new user
|
||||
2. Verify all commands exist in src/.claude/commands/
|
||||
3. Check that no unimplemented features are documented
|
||||
4. Verify all code snippets are accurate
|
||||
5. Check markdown formatting renders correctly
|
||||
6. Ensure consistent tone and voice
|
||||
7. Fix typos and grammatical errors
|
||||
|
||||
**Validation**:
|
||||
- No references to unimplemented features
|
||||
- All commands are accurate
|
||||
- Documentation is clear and actionable
|
||||
|
||||
**Estimated effort**: 20 minutes
|
||||
|
||||
---
|
||||
|
||||
## Dependencies
|
||||
- None (documentation only, no code dependencies)
|
||||
|
||||
## Verification Checklist
|
||||
- [ ] README.md exists in repository root
|
||||
- [ ] Contains all required sections (About, Features, Prerequisites, Setup, Workflow, Commands)
|
||||
- [ ] Setup instructions are clear and complete
|
||||
- [ ] All implemented slash commands are documented
|
||||
- [ ] No references to unimplemented features (e.g., automated CV generation)
|
||||
- [ ] Examples use realistic scenarios
|
||||
- [ ] Directory structure reflects actual layout
|
||||
- [ ] Markdown formatting is correct
|
||||
- [ ] Links (if any) are valid
|
||||
- [ ] Documentation is accessible to non-technical users
|
||||
- [ ] Proofread for typos and clarity
|
||||
|
||||
## Total Estimated Effort
|
||||
Approximately 3-4 hours for comprehensive documentation.
|
||||
|
||||
## Notes
|
||||
- Focus on user needs, not developer needs
|
||||
- Keep language clear and jargon-free
|
||||
- Use examples liberally
|
||||
- Prioritize clarity over comprehensiveness
|
||||
- The goal is to enable new users to successfully use the framework
|
||||
Reference in New Issue
Block a user