Script Kit Agent Workflow

Mandatory workflow for all code changes. Do NOT ask users to test. Do NOT skip verification.

Quick-Start Checklist (Do First)

1. Read CLAUDE.md before changing code
2. Check .hive/issues.jsonl for tasks/context
3. TDD: write failing test → implement → refactor
4. Update bead status when starting/completing work
5. Include correlation_id in all log entries/spans
6. UI changes: test via stdin JSON protocol (never CLI args)
7. Before every commit: cargo check && cargo clippy --all-targets -- -D warnings && cargo test

The Fix-Verify Loop

1. EXPLORE: Understand the problem
   - Use Task tool with explore agent for codebase search
   - Read relevant files, identify root cause before coding

2. FIX: Make the code change
   - Keep changes minimal and focused

3. BUILD: Compile and verify
   cargo check && cargo clippy --all-targets -- -D warnings

4. LAUNCH: Run the app with logging
   echo '{"type":"show"}' | SCRIPT_KIT_AI_LOG=1 ./target/debug/script-kit-gpui 2>&1

5. CHECK LOGS: Verify the fix
   grep -i "keyword" ~/.scriptkit/logs/script-kit-gpui.jsonl

6. VISUAL VERIFY (if UI change):
   - Write test script with captureScreenshot()
   - Save PNG to ./test-screenshots/
   - READ the PNG file to actually verify

7. RUN TESTS: cargo test

Log Modes

Mode	Command	Use Case
Compact AI logs	SCRIPT_KIT_AI_LOG=1	Default for AI agents
Full debug logs	RUST_LOG=debug	Deep debugging
Specific module	RUST_LOG=script_kit::theme=debug	Target one module

Anti-Patterns (Never Do These)

• "The user should test this manually"
• "I made the change, it should work"
• Making a fix without checking logs
• Capturing screenshot but not reading the PNG
• Skipping cargo check before launch
• Not using SCRIPT_KIT_AI_LOG=1 or RUST_LOG=debug

Success Indicators

• Explored codebase before fixing
• Made targeted fix based on understanding
• cargo check + cargo clippy pass
• Launched app and checked relevant logs
• Logs confirm the change took effect
• cargo test passes
• (If visual) Screenshot captured AND read

Session Completion ("Landing the Plane")

Work is not done until git push succeeds.

1. File issues for remaining work
2. If code changed: run quality gates (check/clippy/test)
3. Update issue status
4. Push to remote:

   git pull --rebase && git push && git status
   

5. Clean up (stashes/branches)
6. Verify everything committed + pushed
7. Hand off context for next session

Rules:

• Never stop before pushing
• Never say "ready to push when you are"
• If push fails: resolve and retry until success

References

• Scenario Testing - Automated scenario-based testing
• Dev Workflow - Hot reload and debugging