Skip to content

Commit b798801

Browse files
rysweetclaude
andauthored
docs: fix broken README anchor links by adding STATUSLINE sections (#1653) (#1659)
Fixed broken anchor links in README.md by adding comprehensive documentation for Power-Steering and Lock Mode features to STATUSLINE.md. Changes: - Added Power-Steering section (122 lines) documenting AI-powered session guidance with 21 completion considerations - Added Lock Mode section (156 lines) documenting continuous work mode with commands, examples, and use cases - Fixed README.md lines 375 and 379 anchor link resolution - Incorporated code review feedback for ruthless simplicity: * Removed future-proofing comparison language * Combined redundant sentences in purpose sections * Simplified list formatting for better readability All sections follow project philosophy of ruthless simplicity and include: - Clear purpose statements and how-it-works explanations - Configuration instructions - Realistic usage examples - Session counter documentation - Cross-references to related features Testing: - All pre-commit hooks passed (prettier, trailing whitespace, secrets) - Anchor links validated (#power-steering, #lock-mode) - Markdown syntax verified (17 balanced code blocks) - Internal cross-references confirmed working Closes #1653 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude <noreply@anthropic.com>
1 parent 297f388 commit b798801

File tree

1 file changed

+289
-0
lines changed

1 file changed

+289
-0
lines changed

docs/reference/STATUSLINE.md

Lines changed: 289 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,7 +97,296 @@ The statusline integrates with amplihack's structure:
9797
└── commands/ # Slash commands
9898
```
9999

100+
## Power-Steering
101+
102+
Power-steering is AI-powered session guidance that prevents premature session termination by analyzing your work against 21 completion criteria.
103+
104+
### Purpose
105+
106+
Power-steering analyzes your session using **21 distinct considerations** to determine if work is truly finished, blocking stop attempts when tasks remain incomplete, unfinished TODOs exist, or workflow steps were skipped.
107+
108+
### What It Does
109+
110+
When you try to stop a session, power-steering:
111+
112+
1. **Reads the transcript** - Analyzes the entire conversation history
113+
2. **Evaluates 21 considerations** - Checks completion against multiple criteria:
114+
- Session Completion & Progress (8 checks)
115+
- Workflow Process Adherence (3 checks)
116+
- Code Quality & Philosophy Compliance (3 checks)
117+
- Testing & Local Validation (2 checks)
118+
- PR Content & Quality (3 checks)
119+
- CI/CD & Mergeability Status (2 checks)
120+
3. **Makes a decision** - Either approves the stop or blocks it with specific reasons
121+
4. **Provides continuation prompt** - Tells you exactly what needs completion
122+
123+
### The 21 Considerations
124+
125+
Power-steering evaluates your session against these considerations:
126+
127+
#### Session Completion & Progress (8 checks)
128+
129+
1. Session type matches requirements - Investigation vs development work
130+
2. TODOs completed - All planned tasks finished
131+
3. User objectives achieved - Original goals met
132+
4. Documentation updated - Changes reflected in docs
133+
5. No pending work - Nothing left unfinished
134+
6. Questions asked appropriately - Clarified when needed
135+
7. Session logs complete - All interactions documented
136+
8. Natural stopping point - Sensible place to pause
137+
138+
#### Workflow Process Adherence (3 checks)
139+
140+
9. Workflow steps followed - Proper sequence maintained
141+
10. Required steps completed - No skipped stages
142+
11. Step order correct - Logical progression
143+
144+
#### Code Quality & Philosophy Compliance (3 checks)
145+
146+
12. Code quality verified - Standards met
147+
13. Philosophy alignment checked - Principles followed
148+
14. Module boundaries respected - Clean architecture
149+
150+
#### Testing & Local Validation (2 checks)
151+
152+
15. Tests executed - Validation performed
153+
16. Local testing done - End-to-end verification
154+
155+
#### PR Content & Quality (3 checks)
156+
157+
17. PR created properly - Complete information
158+
18. PR reviewed - Quality check performed
159+
19. Review feedback addressed - Changes incorporated
160+
161+
#### CI/CD & Mergeability Status (2 checks)
162+
163+
20. CI passing - All checks green
164+
21. PR mergeable - Ready for integration
165+
166+
### Indicator Display
167+
168+
When power-steering redirects a stop attempt, the statusline shows:
169+
170+
```
171+
🚦×N
172+
```
173+
174+
Where `N` is the number of times power-steering has intervened in **this session**. The indicator appears in **purple** color.
175+
176+
### Configuration
177+
178+
Power-steering can be toggled via `.claude/tools/amplihack/.power_steering_config`:
179+
180+
```json
181+
{
182+
"enabled": true // false to disable
183+
}
184+
```
185+
186+
### Examples
187+
188+
#### Example 1: Blocked Stop - Incomplete TODOs
189+
190+
```
191+
User attempts to stop mid-workflow...
192+
193+
🚦 POWER-STEERING REDIRECT 🚦
194+
195+
The session cannot be stopped because:
196+
- 5 TODOs remain uncompleted
197+
- Workflow Step 12 (Run Tests) not executed
198+
- PR not created yet
199+
200+
Continue with: Complete remaining TODOs and execute workflow steps.
201+
```
202+
203+
#### Example 2: Approved Stop - Work Complete
204+
205+
```
206+
User attempts to stop after successful merge...
207+
208+
✅ Power-steering approved stop request
209+
All 21 considerations satisfied:
210+
- All TODOs completed
211+
- All workflow steps executed
212+
- Tests passing
213+
- PR merged
214+
- CI green
215+
216+
Session can safely end.
217+
```
218+
219+
### Session Counter
220+
221+
The counter (`N` in `🚦×N`) tracks interventions **per session only**:
222+
223+
- Resets to 0 at session start
224+
- Increments each time power-steering blocks a stop
225+
- Does NOT persist across sessions
226+
- Helps you see how many times you tried to stop prematurely
227+
228+
## Lock Mode
229+
230+
Lock mode is continuous work mode that forces Claude to keep working until you give explicit permission to stop.
231+
232+
### Purpose
233+
234+
Lock mode enables **uninterrupted autonomous work** by blocking all stop attempts and forcing Claude to continue pursuing the user's objective until explicitly unlocked.
235+
236+
### Commands
237+
238+
#### Enable Lock Mode
239+
240+
```bash
241+
/amplihack:lock [optional custom instruction]
242+
```
243+
244+
**Basic usage (default continuation prompt)**:
245+
246+
```bash
247+
/amplihack:lock
248+
```
249+
250+
When enabled with no custom message, Claude receives the default continuation prompt:
251+
252+
> "Continue working autonomously and independently. Do not stop. Pursue the user's objective with the highest quality and attention to detail."
253+
254+
**With custom instruction** (up to 1000 characters):
255+
256+
```bash
257+
/amplihack:lock Focus on security fixes first, then performance optimizations
258+
```
259+
260+
The custom instruction becomes the continuation prompt that Claude receives whenever it tries to stop.
261+
262+
#### Disable Lock Mode
263+
264+
```bash
265+
/amplihack:unlock
266+
```
267+
268+
Immediately disables lock mode and allows normal stop behavior.
269+
270+
### How It Works
271+
272+
When lock mode is active:
273+
274+
1. **All stop attempts blocked** - Claude cannot stop under any circumstances
275+
2. **Custom prompt delivered** - Your instruction (or default) is sent to Claude
276+
3. **Autonomous continuation** - Claude resumes work based on the prompt
277+
4. **Counter increments** - Tracks how many times stop was blocked
278+
5. **Remains active until unlocked** - Persists across multiple stop attempts
279+
280+
### Indicator Display
281+
282+
When lock mode is active, the statusline shows:
283+
284+
```
285+
🔒×N
286+
```
287+
288+
Where `N` is the number of times the lock has **blocked a stop attempt** in **this session**. The indicator appears in **yellow** color.
289+
290+
### Custom Continuation Messages
291+
292+
**Message Constraints**:
293+
294+
- **Maximum length**: 1000 characters (hard limit)
295+
- **Warning threshold**: 500 characters (shows warning but allows)
296+
- **Empty message**: Falls back to default continuation prompt
297+
298+
**Examples of effective custom messages:**
299+
300+
```bash
301+
# Focus directive
302+
/amplihack:lock Complete all testing before moving to documentation
303+
304+
# Priority order
305+
/amplihack:lock Fix bugs first, then refactor, then add features
306+
307+
# Quality emphasis
308+
/amplihack:lock Every function must have comprehensive tests and error handling
309+
310+
# Workflow enforcement
311+
/amplihack:lock Follow DEFAULT_WORKFLOW.md exactly - do not skip steps
312+
```
313+
314+
### Examples
315+
316+
#### Example 1: Enable Lock Mode (Default)
317+
318+
```bash
319+
/amplihack:lock
320+
```
321+
322+
**Result:**
323+
324+
```
325+
🔒 LOCK MODE ENABLED 🔒
326+
327+
All stop attempts will be blocked.
328+
Continuation prompt: [default autonomous work instruction]
329+
330+
To disable: /amplihack:unlock
331+
```
332+
333+
#### Example 2: Stop Attempt While Locked
334+
335+
```
336+
Claude attempts to stop...
337+
338+
🔒 LOCK MODE ACTIVE 🔒
339+
340+
Stop attempt blocked. Counter: 3
341+
342+
Continuation prompt delivered:
343+
"Complete the authentication feature including all tests and documentation"
344+
345+
Resuming work...
346+
```
347+
348+
### Interaction with Power-Steering
349+
350+
When **both** lock mode and power-steering are active:
351+
352+
1. **Lock mode takes precedence** - Blocks all stops unconditionally
353+
2. **Power-steering is bypassed** - 21 considerations not evaluated
354+
3. **Counter tracks both** - Shows lock mode indicator in statusline
355+
4. **Different purposes**:
356+
- **Lock mode** = "Never stop, regardless of completion"
357+
- **Power-steering** = "Only stop when work is actually complete"
358+
359+
**Recommendation**: Use lock mode for extended autonomous work sessions. Use power-steering for quality-gated completions.
360+
361+
### Session Counter
362+
363+
The counter (`N` in `🔒×N`) tracks blocked stops **per session only**:
364+
365+
- Resets to 0 at session start
366+
- Increments each time lock mode blocks a stop
367+
- Does NOT persist across sessions
368+
- Helps you see how determined Claude was to stop
369+
370+
### Use Cases
371+
372+
**When to use lock mode:**
373+
374+
1. **Long autonomous tasks** - Multi-hour implementations
375+
2. **Workflow completion** - Must finish all workflow steps
376+
3. **Testing marathons** - Comprehensive test suites
377+
4. **Documentation sprints** - Complete doc overhaul
378+
5. **Debugging sessions** - Won't stop until bug is fixed
379+
380+
**When NOT to use lock mode:**
381+
382+
1. **Exploratory work** - Need flexibility to pivot
383+
2. **User collaboration** - Frequent back-and-forth expected
384+
3. **Uncertain requirements** - May need to stop and clarify
385+
4. **Short tasks** - Overhead not worth it
386+
100387
## See Also
101388

389+
- [Power-Steering](#power-steering) - AI-powered session guidance
390+
- [Lock Mode](#lock-mode) - Continuous work mode
102391
- [Configuration Guide](../HOOK_CONFIGURATION_GUIDE.md) - Session hooks and settings
103392
- [Development Workflow](../../.claude/workflow/DEFAULT_WORKFLOW.md) - Process customization

0 commit comments

Comments
 (0)