--- name: FP Workflow description: This skill should be used when the user asks to "start working on issue", "what should I work on", "pick up task", "continue work", "find next task", "hand off", or "end session". Provides agent work session patterns for the FP CLI including claiming work, logging progress, and VCS-based change tracking. --- # FP Workflow Skill **Agent work session patterns for the FP CLI** ## Core Workflow Concepts ### Issue Status Lifecycle Issues have three states: 1. **todo** - Planned, not yet started (no VCS tracking) 2. **in-progress** - Actively being worked on (VCS base captured) 3. **done** - Completed (VCS tip captured) ### Issue Priority Issues can have an optional priority: `low`, `medium`, `high`, or `critical`. - Priority affects display order: within the same status, higher priority issues appear first - Sort order: critical → high → medium → low → (no priority) - Use `--priority` flag when creating or updating issues ### VCS-Based Change Tracking FP automatically tracks changes using your version control system (git or jj): - **When issue becomes `in-progress`**: Captures current VCS ref as the `base` commit - **When issue becomes `done`**: Captures current VCS ref as the `tip` commit - **Range (base..tip)**: Shows exactly what changed for this issue This replaces manual snapshots - VCS handles all change tracking automatically. ### Work Session Flow ``` 1. Session Start → Get your agent name 2. Find Work → Discover next actionable task (status: todo) 3. Claim Work → Mark issue as in-progress (captures base ref) 4. Do Work → Implement, test, iterate 5. COMMIT → Commit changes before logging (enforced by hooks) 6. Log Progress → Add comments after committing 7. Complete → Mark as done (captures tip ref) 8. Hand Off → Log final status before session ends ``` ### Commit-First Rule **You must commit before logging progress.** The plugin enforces this with PreToolUse hooks that block `fp comment` and `fp issue update` calls when uncommitted changes exist. The workflow rhythm is: **code → commit → log → repeat** This ensures: - VCS history accurately reflects progress - Comments reference committed work, not in-flight changes - Context survives compaction (commits are durable) ## Essential Commands ### 1. Identify Yourself **Check who you are:** ```bash fp agent whoami ``` This tells you your agent name (e.g., "swift-falcon"). Your identity is set automatically when your session starts and stored in the `$FP_AGENT_NAME` environment variable. **Note:** Use `$FP_AGENT_NAME` in commands. If the variable is not set (e.g., in subagents), get your name with: ```bash FP_AGENT_NAME=$(fp agent whoami 2>&1 | grep "Name:" | awk '{print $2}') ``` ### 2. Find Next Task **See the full issue tree:** ```bash fp tree ``` This shows all issues with their hierarchy, status, and dependencies. **List tasks by status:** ```bash fp issue list --status todo # Available to pick up fp issue list --status in-progress # Currently being worked on fp issue list --status done # Completed work fp issue list # All issues ``` **Analyze dependencies:** When looking at the tree output, identify tasks that: - Have no dependencies, OR - Have all dependencies in "done" status - Are not already being worked on (check recent activity) ### 3. Claim Work **Start working on an issue:** ```bash fp issue update --status in-progress FP-2 ``` When you mark an issue as `in-progress`, the system automatically: - Captures the current VCS ref as the base commit - Sets this as your current issue in the workspace **Log that you're starting:** ```bash fp comment FP-2 "Starting work. First step: [describe what you'll do]" ``` ### 4. View Changes **See what's changed since you started:** ```bash fp issue diff FP-2 # Full diff fp issue diff FP-2 --stat # Just file stats ``` **List changed files:** ```bash fp issue files FP-2 ``` For parent issues with children, these commands automatically aggregate changes from all descendants. ### 5. Manually Assign Commits If automatic VCS tracking missed commits (e.g., you forgot to mark the issue as in-progress before starting work), use `fp issue assign` to retroactively link commits: ```bash fp issue assign FP-2 # Assign current HEAD to issue fp issue assign FP-2 --rev abc123 # Assign specific commit fp issue assign FP-2 --rev a1,b2 # Assign multiple commits fp issue assign FP-2 --reset # Clear all assigned revisions ``` This updates the issue's revision tracking metadata. ### 6. Log Progress **Add comments as you make progress:** ```bash fp comment FP-2 "Completed schema design. Added User, Session, Token models to src/models/" ``` ### 7. Mark Completion **When work is done:** ```bash fp issue update --status done FP-2 fp comment FP-2 "Task completed. [Summary of what was done]" ``` This automatically captures the current VCS ref as the tip commit. ## Best Practices ### Starting a Session 1. **Check your identity:** ```bash fp agent whoami ``` 2. **Review recent activity:** ```bash fp log --limit 10 ``` 3. **Check the current state:** ```bash fp tree ``` 4. **Look for available work:** ```bash fp issue list --status todo # Not started fp issue list --status in-progress # In progress (maybe continue) ``` 5. **If continuing work, load context:** ```bash fp context FP-2 ``` This shows the issue details. ### During Work 1. **Comment frequently** - At minimum: - When you start a task - When you complete a significant milestone - When you discover important information - When you encounter problems 2. **Check your progress:** ```bash fp issue diff FP-2 --stat # Quick view of changed files fp issue files FP-2 # List of files changed ``` 3. **Keep status current**: - `todo` when not yet started - `in-progress` when actively working - `done` when complete ### Ending a Session 1. **Log your progress:** ```bash fp comment FP-2 "End of session. Completed: [list]. Next steps: [list]" ``` 2. **Update status appropriately:** - If done: `--status done` - If partially done: keep as `in-progress` with clear comment about state 3. **Don't leave issues in limbo** - Always leave a comment explaining state ## Common Patterns ### Pattern: Pick Up Where You Left Off ```bash # 1. Check what's currently in progress fp issue list --status in-progress # 2. Load context for the issue fp context FP-5 # 3. Review recent activity fp log FP-5 --limit 5 # 4. See what's changed so far fp issue diff FP-5 --stat # 5. Continue work and log fp comment FP-5 "Resuming work. Current focus: [what you're doing]" ``` ### Pattern: Taking Over From Another Agent ```bash # 1. Identify the issue fp issue show FP-3 # 2. Review what was done fp log FP-3 # 3. See the changes made so far fp issue diff FP-3 --stat # 4. Load full context fp context FP-3 # 5. Log that you're taking over fp comment FP-3 "Taking over. Will continue with: [next steps]" ``` ### Pattern: Breaking Down Work ```bash # While working on FP-4, you realize it's too big # 1. Create sub-issues fp issue create --title "Authentication middleware" --parent FP-4 fp issue create --title "Authorization checks" --parent FP-4 fp issue create --title "Token refresh logic" --parent FP-4 # 2. Document in parent fp comment FP-4 "Broke down into sub-tasks: FP-10, FP-11, FP-12. Will work on these sequentially." # 3. Work on sub-issues fp issue update --status in-progress FP-10 ``` ### Pattern: Checking Parent Issue Progress ```bash # For a parent issue, see aggregated changes from all children fp issue diff FP-1 --stat # Shows all changes across descendants fp issue files FP-1 # Lists all files changed by descendants ``` ### Pattern: Fixing Tracking After the Fact If you made commits before marking an issue as in-progress (so the base ref wasn't captured), use `fp issue assign` to manually link commits: ```bash # 1. Find the commits you made for this issue jj log # or: git log --oneline # 2. Assign them to the issue fp issue assign FP-5 --rev abc123,def456 # 3. Verify the issue now tracks those commits fp issue diff FP-5 --stat ``` ## Anti-Patterns (Avoid These) ### ❌ Logging before committing ```bash # BAD: Log progress with uncommitted changes (will be blocked by hooks) # ... make changes ... fp comment FP-2 "Added auth middleware" # BLOCKED - uncommitted changes # GOOD: Commit first, then log # ... make changes ... jj describe -m "Add auth middleware" && jj new # or: git commit -am "..." fp comment FP-2 "Committed: Added auth middleware" # ALLOWED ``` ### ❌ Silent progress (no comments) ```bash # BAD: Work on issue for 2 hours without any comments # Context is lost if session compacts # GOOD: Commit and comment at key milestones jj describe -m "Create base models" && jj new fp comment FP-2 "Committed: Created base models" # ... work ... jj describe -m "Add validation logic" && jj new fp comment FP-2 "Committed: Added validation logic" ``` ### ❌ Leaving work in ambiguous state ```bash # BAD: End session without final comment fp issue update --status in-progress FP-2 # Still in progress, but what's the state? # GOOD: Clear handoff fp comment FP-2 "End of session. Completed auth middleware. TODO: Add rate limiting. File: src/middleware/auth.ts is 80% done." ``` ### ❌ Not using VCS tracking ```bash # BAD: Manually tracking what files changed # GOOD: Let fp handle it fp issue diff FP-2 --stat # See exactly what changed fp issue files FP-2 # Get the file list ``` ## Integration with Context Commands ### Loading Context for Work Use `fp context` to get issue details: ```bash # Load context for specific issue fp context FP-2 # Load with child issues fp context FP-2 --include-children # Machine-readable format (for processing) fp context FP-2 --format json ``` ### Session Start Context When your session starts, the SessionStart hook automatically runs: ```bash fp context --session-start --session-id ``` This provides: - Your agent identity - Current open issues - Recent activity summary ### Pre-Compact Context Before context compaction, the PreCompact hook runs: ```bash fp context --current --format compact ``` This preserves critical information about what you were working on. ## Querying Activity ### View Recent Activity ```bash # Last 20 activities (default) fp log # Last 50 activities fp log --limit 50 # Activity for specific issue fp log FP-2 # Activity by specific agent fp log --author swift-falcon # Your own activity fp log --author $FP_AGENT_NAME ``` ### Understanding Activity Log The activity log shows: - Timestamp - Author (agent or user) - Issue ID - Action type and details Use this to: - Understand what happened while you were away - See who worked on what - Track status transitions - Find recent comments ## Quick Reference ### Start Session Checklist - [ ] `fp agent whoami` - Know who you are - [ ] `fp tree` - See the full picture - [ ] `fp log --limit 10` - Check recent activity - [ ] `fp issue list --status todo` - See available work - [ ] `fp issue list --status in-progress` - See current work ### During Work Checklist - [ ] Mark issue as `in-progress` to start tracking - [ ] **Commit before logging** (hooks enforce this) - [ ] Comment after each commit to document progress - [ ] Use `fp issue diff/files` to see progress - [ ] Keep status current (todo → in-progress → done) ### End Session Checklist - [ ] Add final comment with progress and next steps - [ ] Update status appropriately - [ ] Ensure all changes are logged - [ ] **Run review** - Use `fp-review` skill to assign commits to issues - [ ] Don't leave work in ambiguous state ## Troubleshooting ### "I don't know what to work on" ```bash fp tree # See full picture fp issue list --status todo # See available work fp issue list --status in-progress # See active work # Pick tasks with no dependencies or all dependencies done ``` ### "Lost context after compaction" ```bash fp context FP-X # Reload issue details fp log FP-X --limit 10 # Read recent activity fp issue diff FP-X --stat # See what's changed fp tree # Understand issue hierarchy ``` ### "What changed in this issue?" ```bash fp issue diff FP-X # Full diff fp issue diff FP-X --stat # File stats only fp issue files FP-X # List of changed files ``` ## Summary The FP workflow is designed for seamless agent collaboration: 1. **Always identify yourself** with `fp agent whoami` 2. **Find actionable work** using `fp tree` and `fp issue list --status todo` 3. **Claim with status in-progress** to start VCS tracking 4. **Code → Commit → Log** (commit-first is enforced by hooks) 5. **View changes** with `fp issue diff` and `fp issue files` 6. **Mark done** when complete (captures final commit ref) 7. **Hand off cleanly** with clear final comments The commit-first rule ensures VCS history accurately reflects progress and comments reference durable, committed work.