zzstoatzz.io
+16
-39
.claude/commands/onboard.md
+16
-39
.claude/commands/onboard.md
···
1
-
this is meant to help you quickly understand what/where the project is and what to work on next (i.e. onboard yourself).
1
+
# onboard
2
2
3
-
## Instructions
3
+
get up to speed on the project quickly.
4
4
5
-
1. **Read STATUS.md** at the root of the repository
6
-
- Understand the long-term, medium-term, and short-term vision
7
-
- Review the current technical state
8
-
- Note what's working, what's in progress, and known issues (via gh cli)
9
-
- THIS FILE MAY BE OUTDATED - CHECK GIT STATUS AND COMMITS FOR TRUTH
5
+
## instructions
10
6
11
-
2. **Review Key Files**
12
-
- `README.md` - project overview and quick start
13
-
- `AGENTS.md` - critical reminders and technical details
14
-
- Recent commits (`git log --oneline -10`)
15
-
- Current git status (`git status`)
7
+
1. **read STATUS.md** - the living document with project vision, recent work, and technical state
8
+
2. **check recent commits** - `git log --oneline -10` for what's actively changing
9
+
3. **check git status** - any uncommitted work in progress
10
+
4. **review open issues** - `gh issue list` for known priorities
16
11
17
-
3. **Assess Codebase State**
18
-
- Check active branches and recent work
19
-
- Review any TODO comments or incomplete features
20
-
- Look at test coverage and known failures
12
+
## then
21
13
22
-
4. **Propose Next Best Step**
14
+
propose the next best step based on:
15
+
- immediate priorities listed in STATUS.md
16
+
- known issues blocking progress
17
+
- in-progress work needing completion
23
18
24
-
Prioritize based on:
25
-
- **Short-term vision items** from STATUS.md (highest priority)
26
-
- **Known issues** that are blocking or high-impact
27
-
- **In-progress work** that needs completion
28
-
- **Missing critical features** for core functionality
29
-
- **Technical debt** that impedes progress
19
+
present your recommendation and ask for confirmation before proceeding.
30
20
31
-
Present:
32
-
- **Recommended next step** with clear rationale
33
-
- **Why this step** (how it advances the vision)
34
-
- **What needs to be done** (specific tasks)
35
-
- **Potential challenges** or considerations
36
-
- **Alternative options** if there are multiple viable paths
21
+
## tone
37
22
38
-
5. **Ask for Confirmation**
39
-
- Present the proposal clearly
40
-
- Ask if the user wants to proceed with this step
41
-
- Offer to explore alternatives if needed
42
-
43
-
44
-
## Tone
45
-
- Action-oriented and specific
46
-
- Concisely curious about existing decisions and trade-offs
47
-
23
+
- action-oriented and specific
24
+
- concisely curious about existing decisions and trade-offs (don't assume, ask)
+23
-75
.claude/commands/status-update.md
+23
-75
.claude/commands/status-update.md
···
1
-
# Status Update
1
+
# status update
2
2
3
-
Write a comprehensive status update to `STATUS.md` at the root of the repository.
3
+
update STATUS.md after completing significant work.
4
4
5
-
## Purpose
6
-
7
-
This command prepares the repository for a new agent/contributor by documenting the project's current state. It should be run before clearing agent memory so the next session can quickly understand the vision and technical state.
8
-
9
-
## Status Update Structure
10
-
11
-
The status update should be organized into three vision layers:
12
-
13
-
### 1. Long-Term Vision
14
-
The original inspiration and ultimate goal:
15
-
- Why this project exists
16
-
- What problem it solves (Spotify/Apple Music walled gardens, artist distribution barriers)
17
-
- How ATProto enables the solution (portable social networks, decentralized music distribution)
18
-
- The dream state of the platform
19
-
20
-
### 2. Medium-Term Vision
21
-
Where we're heading in the next few months:
22
-
- Core features to build
23
-
- Technical milestones
24
-
- Integration goals with ATProto ecosystem
25
-
- User experience improvements
26
-
27
-
### 3. Short-Term Vision
28
-
Immediate next steps and current priorities:
29
-
- Active work streams
30
-
- Known issues to fix
31
-
- Performance improvements
32
-
- Documentation needs
33
-
34
-
## Technical State
35
-
36
-
Document the current implementation:
37
-
38
-
### Architecture
39
-
- Backend: language, framework, hosting, database
40
-
- Frontend: framework, runtime, hosting, styling approach
41
-
- Storage: where audio files live
42
-
- Auth: ATProto OAuth implementation details
43
-
- Deployment: CI/CD setup, automation
44
-
45
-
### What's Working
46
-
- List functioning features
47
-
- Note deployment status (URLs, health)
48
-
- Highlight successful integrations
5
+
## when to update
49
6
50
-
### What's In Progress
51
-
- Active development areas
52
-
- Features being built
53
-
- Refactors underway
7
+
after shipping something notable:
8
+
- new features or endpoints
9
+
- bug fixes worth documenting
10
+
- architectural changes
11
+
- deployment/infrastructure changes
12
+
- incidents and their resolutions
54
13
55
-
### Known Issues
56
-
- Technical debt
57
-
- Bugs
58
-
- Performance problems
59
-
- Missing features
14
+
## how to update
60
15
61
-
### Technical Decisions
62
-
Why certain choices were made:
63
-
- Why Python/FastAPI vs alternatives (e.g., Rust)
64
-
- Why current deployment architecture
65
-
- Trade-offs accepted
66
-
- Future flexibility considerations
16
+
1. add a new subsection under `## recent work` with today's date
17
+
2. describe what shipped, why it matters, and any relevant PR numbers
18
+
3. update `## immediate priorities` if priorities changed
19
+
4. update `## technical state` if architecture changed
67
20
68
-
## Instructions
21
+
## structure
69
22
70
-
1. Read the current `README.md`, `AGENTS.md`, recent status updates in `sandbox/`, and key source files
71
-
2. Check `git status` and recent commits to understand current work
72
-
3. Scan the codebase structure (`backend/src/backend/`, `frontend/src/`)
73
-
4. Review the tech stack in `pyproject.toml` and `frontend/package.json`
74
-
5. Synthesize into a clear, chronological narrative
75
-
6. Write to `STATUS.md` in the root directory
76
-
7. Update this timestamp in the file: `Status as of: YYYY-MM-DD HH:MM UTC`
23
+
STATUS.md follows this structure:
24
+
- **long-term vision** - why the project exists
25
+
- **recent work** - chronological log of what shipped (newest first)
26
+
- **immediate priorities** - what's next
27
+
- **technical state** - architecture, what's working, known issues
77
28
78
-
## Tone
29
+
old content is automatically archived to `.status_history/` - you don't need to manage this.
79
30
80
-
- Direct and technical
81
-
- Honest about limitations and trade-offs
82
-
- Optimistic about vision
83
-
- Practical about current state
84
-
- Useful for someone with no prior context
31
+
## tone
85
32
33
+
direct, technical, honest about limitations. useful for someone with no prior context.