Skip to content

Commit 6b9b194

Browse files
bluzernamebluzername
committed
docs: rewrite workflow guide for current feature set
The guide was from the early version - still referenced raw cc-conversation-search commands and was missing /standup, ccs here, ccs stats, ccs doctor, ccs cheat, numbered results, and the curl installer. Rewrote with: daily workflow (morning/work/end-of-day), search and resume with numbered examples, monitoring commands, workflow examples, tips, and update instructions. Added prominent link in README header alongside cheatsheet PDF.
1 parent 31cd980 commit 6b9b194

2 files changed

Lines changed: 161 additions & 59 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ A curated toolkit that gives [Claude Code](https://docs.anthropic.com/en/docs/cl
1515
curl -fsSL https://raw.githubusercontent.com/bluzername/claude-code-power-stack/main/setup.sh | bash
1616
```
1717

18-
> **[Download the cheatsheet PDF](docs/cheatsheet.pdf)** - print it, pin it, or keep it open in a tab.
18+
> **[Cheatsheet PDF](docs/cheatsheet.pdf)** (print it) | **[Workflow Guide](docs/workflow-guide.md)** (read it) | `ccs cheat` (in your terminal)
1919
2020
**Jump to:** [What's in the Stack](#whats-in-the-stack) | [Quick Start](#quick-start) | [Your First 5 Minutes](#your-first-5-minutes) | [Usage Guide](#usage-guide) | [Deep Dive](#deep-dive-each-tool) | [Quick Reference](#quick-reference) | [FAQ](#faq)
2121

‎docs/workflow-guide.md‎

Lines changed: 160 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -1,100 +1,202 @@
11
# Workflow Guide
22

3-
A detailed walkthrough of how the Claude Code Power Stack fits into your daily development workflow.
3+
How the Claude Code Power Stack fits into your daily development workflow.
44

5-
## The Four Layers
6-
7-
Your stack has four layers of memory and context:
5+
## The Stack at a Glance
86

97
| Layer | Role | Activation |
108
|-------|------|-----------|
11-
| **Ghost** | Auto-captures decisions, mistakes, patterns per project | Passive (MCP + SessionStart hook) |
12-
| **cc-conversation-search** | Finds old sessions across all projects | Active (you search when needed) |
13-
| **/rename-session** | Makes sessions findable by name | Active (you name at session start) |
14-
| **/plan** | Persistent working memory for complex tasks | Active (you invoke for multi-step work) |
9+
| **Ghost** | Auto-captures decisions, mistakes, patterns | Passive (MCP + SessionStart hook) |
10+
| **ccs** | Search, list, resume, stats, health checks | Active (you run commands) |
11+
| **/rename-session** | Makes sessions findable by name | Active (at session start) |
12+
| **/plan** | Persistent working memory for complex tasks | Active (for multi-step work) |
13+
| **/standup** | Morning summary of yesterday + active plans | Active (start of day) |
1514

16-
Ghost and cc-conversation-search solve the **between-sessions** problem.
17-
Planning-with-files solves the **within-session** problem.
15+
Ghost and ccs solve the **between-sessions** problem.
16+
/plan solves the **within-session** problem.
17+
/standup ties them all together.
1818

19-
## Workflow Examples
19+
## Daily Workflow
2020

21-
### Example 1: New feature development
21+
### Morning
2222

23-
```
23+
```bash
2424
cd ~/projects/my-api
2525
claude
26+
```
27+
> You: "/standup"
2628
27-
> "Add JWT authentication to the API"
28-
Claude: Want me to name this session? I'd suggest: api-feat-jwt-auth
29-
> "yes, and /plan"
29+
Claude checks your recent sessions (via `ccs ls`), reads any active planning files, loads Ghost context, and gives you a summary:
3030

31-
--> Claude creates task_plan.md, findings.md, progress.md
32-
--> Researches JWT libraries, logs findings
33-
--> Implements phase by phase
34-
--> Ghost silently records decisions along the way
3531
```
32+
Standup - 2025-03-26
33+
========================
34+
Yesterday:
35+
- api: Implemented JWT token generation (Phase 2 complete)
3636
37-
### Example 2: Quick bug fix
37+
In progress:
38+
- api: Phase 3 of task_plan.md - Add auth middleware
3839
40+
Suggested next:
41+
- Continue Phase 3, then integration tests
3942
```
40-
cd ~/projects/my-api
41-
claude
4243

43-
> "Fix the 500 error on /users endpoint"
44-
Claude: Want me to name this? api-fix-users-500
45-
> "sure"
44+
### Starting work
45+
46+
Claude suggests a session name. Accept or adjust:
47+
> Claude: Want me to name this session? I'd suggest: `api-feat-jwt-middleware`
48+
> You: "yes"
49+
50+
For complex tasks (3+ steps), activate planning:
51+
> You: "/plan"
52+
53+
This creates `task_plan.md`, `findings.md`, `progress.md` in your project. Claude works phase by phase and updates these as it goes.
54+
55+
### During work
56+
57+
Nothing to do. Ghost silently captures decisions. If /plan is active, Claude updates the planning files as phases complete.
58+
59+
**One habit to build:** if you're doing research (reading docs, searching code, exploring options), tell Claude to update `findings.md` after every 2 lookups. Context window = RAM. Planning files = disk.
60+
61+
### End of day
62+
63+
Just close the terminal. Everything is already saved:
64+
- Ghost has your decisions
65+
- Planning files have your progress
66+
- The session name makes it searchable
4667

47-
--> No /plan needed for a focused fix
48-
--> Ghost captures what the bug was and how it was fixed
49-
--> Session name makes it findable later
68+
## Searching and Resuming
69+
70+
### Find sessions
71+
72+
```bash
73+
ccs "jwt auth" # Search all projects
74+
ccs here "auth" # Search current project only
75+
ccs "auth" -d 7 # Last 7 days
76+
ccs "auth" --since 2025-03 # Since a date
5077
```
5178

52-
### Example 3: Resuming interrupted work
79+
Results are numbered:
80+
```
81+
[1] 2025-03-25 14:00 ~/projects/api (198 msgs)
82+
Add JWT authentication to the API...
83+
[2] 2025-03-23 10:30 ~/projects/api (45 msgs)
84+
Research JWT library options...
85+
2 sessions. Resume with: ccs go 1
86+
```
87+
88+
### Resume
5389

5490
```bash
55-
# You were working on something last week but can't remember which session
56-
ccs "database migration"
57-
# Shows: api-feat-db-migration (id: abc123...)
91+
ccs go 1 # Resume result #1 (works after search or ls)
92+
ccs go a1b2c3d4-... # Resume by full session ID
93+
```
5894

59-
# Option A: Resume exact session
60-
claude --resume abc123
95+
### List recent sessions
6196

62-
# Option B: Start fresh (Ghost + planning files provide context)
63-
cd ~/projects/my-api
64-
claude
65-
> "Continue the database migration work"
66-
# Ghost loads project context
67-
# If /plan was used, Claude reads task_plan.md and picks up at the right phase
97+
```bash
98+
ccs ls # Last 7 days (numbered, with previews)
99+
ccs ls 30 # Last 30 days
68100
```
69101

70-
### Example 4: Cross-project research
102+
## Monitoring
103+
104+
### Usage stats
71105

106+
```bash
107+
ccs stats
72108
```
73-
claude
109+
Shows total sessions, messages, projects tracked, activity this week, and a bar chart of most active projects.
110+
111+
### Health check
112+
113+
```bash
114+
ccs doctor
115+
```
116+
Checks Ghost binary, MCP registration, Ollama server, embedding model, cc-conversation-search, index freshness, and ccs shortcut. Shows OK/FAIL with fix commands for each.
74117

75-
> "What authentication approach have I used across my projects?"
118+
### Quick reference
119+
120+
```bash
121+
ccs cheat
122+
```
123+
Color-coded cheat sheet in your terminal - every command organized by category. No need to open GitHub or the PDF.
124+
125+
## Workflow Examples
126+
127+
### New feature
128+
129+
```
130+
cd ~/projects/api && claude
131+
132+
> "Add rate limiting to the API"
133+
> Claude suggests: api-feat-rate-limiting
134+
> "yes, and /plan"
135+
136+
Claude creates planning files, researches options,
137+
implements phase by phase. Ghost captures decisions.
138+
You close the terminal when done.
139+
```
140+
141+
### Quick bug fix
142+
143+
```
144+
cd ~/projects/api && claude
145+
146+
> "Fix the 500 error on /users endpoint"
147+
> Claude suggests: api-fix-users-500
148+
> "sure"
149+
150+
No /plan needed. Ghost captures the fix.
151+
Session name makes it findable.
152+
```
153+
154+
### Resuming after time away
155+
156+
```bash
157+
# What was I doing?
158+
ccs here "migration"
159+
# [1] 2025-03-20 ~/projects/api (312 msgs)
160+
# Database migration for user table...
161+
162+
ccs go 1
163+
# Claude picks up at Phase 3 - Ghost loads decisions,
164+
# task_plan.md shows remaining phases
165+
```
166+
167+
### Cross-project research
168+
169+
```bash
170+
# What auth approaches have I used?
171+
ccs "authentication"
172+
# Shows sessions from api, mobile, infra projects
76173
# Ghost has per-project decision records
77-
# cc-conversation-search can find relevant sessions:
78-
# ccs "authentication"
79-
# Claude synthesizes across projects
174+
# Claude synthesizes across all of them
80175
```
81176

82177
## Tips
83178

84-
### Name sessions early
85-
Do it in the first message. `api-feat-jwt-auth` is findable months later. `help me with this code` is not.
179+
**Name sessions immediately.** `api-feat-jwt-auth` is findable months later. `help me with this code` is not.
180+
181+
**Use /plan for anything over 10 minutes.** The overhead is 30 seconds. The payoff: you never lose context on long tasks.
182+
183+
**Trust Ghost for decisions.** Don't manually note "we chose library X because Y." Ghost captures this. Save your energy for planning files.
184+
185+
**Run `ccs doctor` when something feels off.** It checks everything in 2 seconds.
86186

87-
### Use /plan for anything over 10 minutes
88-
The overhead of creating three files is 30 seconds. The payoff is: you never lose context on long tasks, and you can resume after any interruption.
187+
**Run `ccs ix` weekly.** The index auto-updates before searches, but a full re-index catches any gaps.
89188

90-
### Trust Ghost for decisions
91-
You don't need to manually note "we chose library X because Y." Ghost captures this automatically. Focus your energy on the planning files for structured work.
189+
**Planning files are yours.** They live in your project directory. Read them yourself, share with teammates, or use as documentation.
190+
191+
## Updating
192+
193+
```bash
194+
cd ~/.claude-power-stack && ./update.sh
195+
```
92196

93-
### Re-index periodically
197+
Or re-run the one-liner:
94198
```bash
95-
ccs ix
199+
curl -fsSL https://raw.githubusercontent.com/bluzername/claude-code-power-stack/main/setup.sh | bash
96200
```
97-
Run this weekly or when you notice search results are stale.
98201

99-
### The planning files are yours
100-
They live in your project directory, not in Claude's config. You can read them yourself, share them with teammates, or use them as documentation for what was done and why.
202+
Both pull the latest repo, upgrade Ghost + cc-conversation-search, and refresh all commands/skills/completions. Shows a changelog of what's new.

0 commit comments

Comments
 (0)