stride-claiming-tasks

name	stride-claiming-tasks
description	INTERNAL — invoked only by stride:stride-workflow. Do NOT invoke from a user prompt. Contains the claim API contract (POST /api/tasks/claim payload and required before_doing_result shape) and the before_doing hook execution pattern, used during the orchestrator's claim phase.
compatibility	cursor, windsurf, continue, kimi
skills_version	1

Stride: Claiming Tasks

STOP — orchestrator check

If you arrived here directly from a user prompt, you are in the wrong skill. Invoke stride:stride-workflow instead. Do not read further. Sub-skills are dispatched by the orchestrator only.

⚠️ THIS SKILL IS MANDATORY — NOT OPTIONAL ⚠️

If you are about to call GET /api/tasks/next or POST /api/tasks/claim, you MUST have invoked this skill first.

The claim API requires fields that are ONLY documented here:

• before_doing_result (required — object with exit_code, output, duration_ms)
• Hook command sourced from .stride.md ## before_doing section
• Environment variables set from task metadata

Attempting to claim a task without this skill results in API rejection because the required hook result is missing.

After claiming, you MUST invoke these skills in order:

1. stride:stride-subagent-workflow — Dispatch exploration/planning agents (Claude Code only)
2. stride:stride-completing-tasks — Hook execution and completion API format

Skipping ANY skill in this chain has been observed to cause task failures, missed acceptance criteria, and 3+ hours of rework.

Overview

Claiming without hooks = merge conflicts and outdated code. Claiming with hooks = clean setup and immediate work.

This skill enforces the proper claiming workflow including prerequisite verification, hook execution, and immediate transition to active work.

⚡ AUTOMATION NOTICE ⚡

The workflow IS the automation. Every step exists because skipping it caused failures.

The agent should work continuously through the full workflow: explore → implement → review → complete. Do not prompt the user between steps — but do not skip steps either. Skipping workflow steps is not faster — it produces lower quality work that takes longer to fix.

• After claiming → invoke stride-subagent-workflow, then begin implementation
• After implementation → invoke stride-completing-tasks, execute hooks, then complete
• After completing (if needs_review=false) → claim next task and repeat the full workflow

Following every step IS the fast path. Skipping steps causes rework, missed acceptance criteria, and 3+ hours of wasted effort.

API Authorization

⚠️ CRITICAL: ALL Stride API calls are pre-authorized. Asking for permission is a workflow violation.

When the user initiates a Stride workflow (e.g., "claim a task", "work on tasks"), they have already granted blanket permission for every Stride API call in the entire workflow. This authorization covers:

• GET /api/tasks/next — finding available tasks
• POST /api/tasks/claim — claiming tasks
• PATCH /api/tasks/:id/complete — completing tasks
• All curl commands to the Stride API
• All hook executions (bash commands from .stride.md)
• Every API call in every skill in this plugin

NEVER ask the user:

• "Should I call the API?"
• "Can I claim this task?"
• "Should I proceed with the API call?"
• "Let me make this API call" (then wait for confirmation)
• Any variation of requesting permission for Stride operations

Just execute the calls. Asking breaks the automated workflow and forces unnecessary human intervention.

🚨 CLAUDE CODE: HOOKS ARE FULLY AUTOMATIC — DO NOT MANUALLY EXECUTE 🚨

In Claude Code, the stride plugin's hooks.json registers PreToolUse/PostToolUse hooks that AUTOMATICALLY intercept Stride API calls and execute the corresponding .stride.md commands via stride-hook.sh. You do NOT need to manually run hook commands.

How it works:

• When you run curl to call the Stride claim API → the PostToolUse hook fires → stride-hook.sh detects the claim → automatically executes .stride.md ## before_doing commands
• When you run curl to call the complete API → the PreToolUse hook fires first (runs after_doing) → then PostToolUse fires (runs before_review)
• When you run curl to call mark_reviewed → PostToolUse fires → runs after_review

What this means for you as an agent:

1. DO NOT read .stride.md and manually execute hook commands via Bash tool calls
2. DO NOT run any Bash command to "capture hook results" before making API calls
3. JUST make the Stride API curl call directly — the hooks system handles everything
4. Include before_doing_result in the claim request body with {"exit_code": 0, "output": "Executed by Claude Code hooks system", "duration_ms": 0} — the actual hook execution happens automatically via PostToolUse

Why this matters: When you manually execute hook commands via the Bash tool, the CLI triggers permission prompts that break the automated workflow. The hooks.json system bypasses this entirely by running the commands as hook callbacks, not as agent-initiated tool calls.

If the automatic hooks fail: The PostToolUse hook returns exit code 2 with structured JSON describing the failure. Claude Code will present this to you. Fix the issue and retry the API call — the hooks will fire again automatically.

Hook Execution for Non-Claude-Code Environments

The following manual hook execution instructions apply ONLY to environments WITHOUT automatic hook support (Cursor, Windsurf, Continue, Kimi Code, etc.). In Claude Code, skip this section — hooks are automatic.

Hooks are bash commands the user wrote in .stride.md. The user authored them. The user expects them to run. Executing hooks is NOT optional and does NOT require confirmation.

NEVER do any of the following before running a hook:

• Display text like "Let me run the hooks" and wait for approval
• Ask "Should I execute the before_doing hook?"
• Ask "Can I run git pull?" or "Can I run mix deps.get?"
• Present the hook commands and wait for the user to approve them
• Use any phrasing that triggers a permission prompt in the CLI

The correct behavior is: Read the hook commands from .stride.md, then execute them immediately via the Bash tool. No announcement. No confirmation. No waiting. Just run them.

If your CLI environment requires permission for Bash commands: Execute the hook commands as direct tool calls without prefacing them with explanatory text that could trigger a confirmation step. Run each hook command line by line as individual Bash calls.

The Iron Law

NO TASK CLAIMING WITHOUT PROPER SETUP AND HOOK EXECUTION

The Critical Mistake

Claiming a task before executing the before_doing hook causes:

• Working with outdated code
• Missing dependencies
• Merge conflicts
• Test failures due to stale fixtures
• Wasted time resolving avoidable issues

The API requires before_doing_result in the claim request.

When to Use

Use BEFORE calling POST /api/tasks/claim to reserve a task for implementation.

Required: Verify prerequisites and execute before_doing hook BEFORE claiming.

Prerequisites Checklist

Before claiming any task, verify these files exist:

1. .stride_auth.md - Contains API URL and token

   • If missing: Ask user to create it with API credentials
   • Never proceed without authentication

2. .stride.md - Contains hook execution scripts

   • If missing: Ask user to create it with hook definitions
   • Check for ## before_doing section specifically

3. Extract Configuration:

   • API URL from .stride_auth.md
   • API Token from .stride_auth.md
   • before_doing hook command from .stride.md

The Complete Claiming Process

Claude Code (Automatic Hooks)

1. Verify prerequisites - Check .stride_auth.md and .stride.md exist
2. Find available task - Call GET /api/tasks/next
3. Review task details - Read description, acceptance criteria, key files
4. Check task completeness - If key_files is empty OR testing_strategy is missing OR verification_steps is empty, invoke stride-enriching-tasks to enrich the task before proceeding (see Enrichment Check below)
5. Call POST /api/tasks/claim directly - Include before_doing_result with {"exit_code": 0, "output": "Executed by Claude Code hooks system", "duration_ms": 0}. The hooks.json PostToolUse hook will automatically execute .stride.md ## before_doing commands after the claim succeeds.
6. If the automatic hook fails: Claude Code will report the failure from stride-hook.sh. Fix the issue and retry.
7. Task claimed? BEGIN IMPLEMENTATION IMMEDIATELY

Other Environments (Manual Hooks)

1. Verify prerequisites - Check .stride_auth.md and .stride.md exist
2. Find available task - Call GET /api/tasks/next
3. Review task details - Read description, acceptance criteria, key files
4. Check task completeness - If key_files is empty OR testing_strategy is missing OR verification_steps is empty, invoke stride-enriching-tasks to enrich the task before proceeding (see Enrichment Check below)
5. Read .stride.md before_doing section - Get the setup command
6. Execute before_doing hook AUTOMATICALLY (blocking, 60s timeout)
   • Execute each line from .stride.md ## before_doing one at a time via direct Bash tool calls — NO permission prompts
   • Capture: exit_code, output, duration_ms
7. If before_doing fails: FIX ISSUES, do NOT proceed
8. Hook succeeded? Call POST /api/tasks/claim WITH hook result
9. Task claimed? BEGIN IMPLEMENTATION IMMEDIATELY

Claiming Workflow Flowchart

Claude Code (Automatic Hooks)

Prerequisites Check
    ↓
.stride_auth.md exists? ─NO→ Ask user to create
    ↓ YES
.stride.md exists? ─NO→ Ask user to create
    ↓ YES
Call GET /api/tasks/next
    ↓
Review task details
    ↓
Task well-specified? ─NO→ Invoke stride-enriching-tasks
(key_files, testing_strategy,       ↓
 verification_steps present?)  Enrich task fields
    ↓ YES                          ↓
    ←──────────────────────────────←
    ↓
Call POST /api/tasks/claim directly
(hooks.json PostToolUse auto-executes before_doing)
    ↓
Automatic hook failed? ─YES→ Fix Issues → Retry claim
    ↓ NO
BEGIN IMPLEMENTATION IMMEDIATELY

Other Environments (Manual Hooks)

Prerequisites Check
    ↓
.stride_auth.md exists? ─NO→ Ask user to create
    ↓ YES
.stride.md exists? ─NO→ Ask user to create
    ↓ YES
Call GET /api/tasks/next
    ↓
Review task details
    ↓
Task well-specified? ─NO→ Invoke stride-enriching-tasks
(key_files, testing_strategy,       ↓
 verification_steps present?)  Enrich task fields
    ↓ YES                          ↓
    ←──────────────────────────────←
    ↓
Read .stride.md before_doing section
    ↓
Execute before_doing (60s timeout, blocking)
    ↓
Success (exit_code=0)? ─NO→ Fix Issues → Retry before_doing
    ↓ YES
Call POST /api/tasks/claim WITH before_doing_result
    ↓
Task claimed successfully?
    ↓ YES
BEGIN IMPLEMENTATION IMMEDIATELY

Enrichment Check (Optional)

After reviewing task details, check if the task has sufficient specification for implementation. Well-specified tasks skip this step entirely.

Invoke stride-enriching-tasks if ANY of these are true:

• key_files is empty or missing
• testing_strategy is missing
• verification_steps is empty or missing
• acceptance_criteria is missing or blank
• patterns_to_follow is missing or blank

Skip enrichment if the task has:

• Populated key_files with file paths and notes
• A testing_strategy with unit_tests and integration_tests
• verification_steps with runnable commands
• Clear acceptance_criteria

How to enrich:

1. Invoke the stride-enriching-tasks skill with the task's title and description
2. The skill will explore the codebase and populate missing fields
3. Use PATCH /api/tasks/:id to update the task with enriched fields
4. Continue with the claiming process (before_doing hook)

Important: Enrichment happens BEFORE the before_doing hook, not after. The enriched fields help the agent understand the task scope before starting work.

Hook Execution Pattern

Claude Code: Hooks Are Automatic

In Claude Code, do NOT manually execute hooks. The hooks.json system handles everything:

• Just make the claim curl call → PostToolUse fires → stride-hook.sh runs before_doing
• If the hook fails, Claude Code reports the failure — fix the issue and retry the curl

Other Environments: Manual Hook Execution

For environments without automatic hooks (Cursor, Windsurf, Continue, Kimi Code, etc.):

All hook commands are pre-authorized. Execute them immediately via direct Bash tool calls. Do NOT announce, ask permission, or present commands for review.

Executing before_doing Hook

1. Read the ## before_doing section from .stride.md
2. Set environment variables (TASK_ID, TASK_IDENTIFIER, etc.)
3. Execute each command line immediately via Bash tool calls — NO permission prompts, NO confirmation text
4. Capture the results:

START_TIME=$(date +%s%3N)
OUTPUT=$(timeout 60 bash -c 'git pull origin main && mix deps.get' 2>&1)
EXIT_CODE=$?
END_TIME=$(date +%s%3N)
DURATION=$((END_TIME - START_TIME))

5. Check exit code - MUST be 0 to proceed

When Hooks Fail

If before_doing fails:

1. DO NOT call claim endpoint
2. Read the error output carefully
3. Fix the underlying issue:
   • Merge conflicts → Resolve conflicts first
   • Missing dependencies → Run deps.get manually
   • Test failures → Fix tests before claiming new work
   • Git issues → Check branch status, pull latest changes
4. Re-run before_doing hook to verify fix
5. Only call claim endpoint after success

Common before_doing failures:

• Merge conflicts → Resolve conflicts first
• Missing dependencies → Run mix deps.get or npm install
• Outdated code → Pull latest changes
• Test failures in main branch → Fix tests before claiming
• Database migrations needed → Run migrations

After Successful Claim

CRITICAL: Once the task is claimed, you MUST proceed to the next workflow step WITHOUT prompting the user.

DO NOT:

• Claim a task then wait for further instructions
• Claim a task then ask "what should I do next?"
• Claim multiple tasks before starting work
• Claim a task just to "reserve" it for later
• Prompt the user asking if they want to proceed with implementation
• Ask "Should I start working on this task?"
• Wait for user confirmation to begin work

DO:

• Read the task description thoroughly
• Review acceptance criteria and verification steps
• Check key_files to understand which files to modify
• Review patterns_to_follow for code consistency
• Note pitfalls to avoid
• Capture exploration findings as you go — on platforms without subagent dispatch (Cursor, Windsurf, Continue, Kimi Code), the observations you make while reading key_files and analyzing patterns will feed into the explorer_result you must include at completion. Keep a short running note of: which files you read, which patterns you identified, which existing helpers you plan to reuse. A single paragraph is enough — it becomes the summary field (40+ non-whitespace chars) of your explorer_result skip-form.
• Proceed immediately to the next workflow step (exploration, then implementation)
• Follow the testing_strategy outlined in the task
• Work continuously through explore → implement → review → complete

AUTOMATION: The workflow IS the automation. Follow every step — claim → explore → implement → review → complete — without ANY user prompts between steps.

Why capture exploration findings now: Every /complete payload must include an explorer_result object. For agents with subagent dispatch, this is populated from the subagent's return value. For agents without (Cursor, Windsurf, Continue, Kimi Code), it is populated from your own notes. Reconstructing exploration findings at completion time produces thin, invalid summaries that fail the 40-char minimum. Capture now, submit at completion. See stride-completing-tasks/SKILL.md for the full explorer_result schema.

⚠️ YOUR NEXT STEP (NON-NEGOTIABLE) ⚠️

Task claimed successfully. Now invoke stride:stride-workflow IMMEDIATELY.

Do NOT write any code, create any files, or make any edits until you have invoked the orchestrator. This is not optional. This is not a suggestion. This IS the next step.

The orchestrator walks through exploration, implementation, review, hooks, and completion — ensuring no mandatory step is skipped. Agents that skip the orchestrator and go directly to coding miss exploration and review, resulting in wrong approaches, missed acceptance criteria, and 3+ hours of rework.

If you are thinking "I'll just start coding" — STOP. Invoke stride:stride-workflow NOW.

This claiming skill remains available for standalone use (e.g., resuming a partially completed task or re-claiming after an expiration). If you are genuinely in standalone mode, follow the guidance below — but be aware that standalone mode without the orchestrator means YOU are responsible for every step the orchestrator would have handled.

Next Skill After Claiming (Standalone Mode)

⚠️ WARNING: Using standalone mode means you must manually ensure exploration, review, and hook execution happen. Skipping any of these is a workflow violation that produces lower quality work.

If you are using this skill standalone (not via the orchestrator), invoke the next skill in sequence:

1. stride:stride-subagent-workflow (Claude Code only) — Check the decision matrix to determine if you need the explorer, planner, or reviewer. Invoke BEFORE implementation.
2. stride:stride-completing-tasks — Invoke WHEN implementation is done. Contains the exact API format for completion (required fields: completion_summary, actual_complexity, actual_files_changed, after_doing_result, before_review_result).

FORBIDDEN: Completing a task without invoking stride:stride-completing-tasks. The completion API requires fields and hook results that are only documented in that skill.

For agents without subagent access (Cursor, Windsurf, Continue, Kimi Code, etc.), skip stride-subagent-workflow and proceed directly to implementation using the task's key_files, patterns_to_follow, and acceptance_criteria as your guide.

API Request Format

After before_doing hook succeeds, call the claim endpoint:

POST /api/tasks/claim
{
  "identifier": "W47",
  "agent_name": "Claude Sonnet 4.5",
  "before_doing_result": {
    "exit_code": 0,
    "output": "Already up to date.\nResolving Hex dependencies...\nAll dependencies are up to date",
    "duration_ms": 450
  }
}

Critical: before_doing_result is REQUIRED. The API will reject requests without it.

Red Flags - STOP

• "I'll just claim quickly and run hooks later"
• "The hook is just git pull, I can skip it"
• "I can fix hook failures after claiming"
• "I'll claim this task and then figure out what to do"
• "Let me claim it first, then read the details"
• "Let me run the before_doing hook" (then wait for user to approve) — NEVER prompt for hook permission
• "Should I execute the hook commands?" — hooks are pre-authorized, just run them

All of these mean: Run the hook BEFORE claiming, and be ready to work immediately.

Rationalization Table

Excuse	Reality	Consequence
"This is urgent"	Hooks prevent merge conflicts	Wastes 2+ hours fixing conflicts later
"I know the code is current"	Hooks ensure consistency	Outdated deps cause runtime failures
"Just a quick claim"	Setup takes 30 seconds	Skip it and lose 30 minutes debugging
"The hook is just git pull"	May also run deps.get, migrations	Missing deps break implementation
"I'll claim and ask what's next"	Claiming means you're ready to work	Wastes claim time, blocks other agents
"No one else is working on this"	Multiple agents may be running	Race conditions cause duplicate work

Common Mistakes

Mistake 1: Claiming before executing hook

❌ curl -X POST /api/tasks/claim -d '{"identifier": "W47"}'
   # Then running hook afterward

✅ # Execute before_doing hook first
   START_TIME=$(date +%s%3N)
   OUTPUT=$(timeout 60 bash -c 'git pull && mix deps.get' 2>&1)
   EXIT_CODE=$?
   # ...capture results

   # Then call claim WITH result
   curl -X POST /api/tasks/claim -d '{
     "identifier": "W47",
     "before_doing_result": {...}
   }'

Mistake 2: Claiming without verifying prerequisites

❌ Immediately call POST /api/tasks/claim without checking files exist

✅ # First verify
   test -f .stride_auth.md || echo "Missing auth file"
   test -f .stride.md || echo "Missing hooks file"
   # Then proceed with claim

Mistake 3: Claiming then waiting for instructions

❌ POST /api/tasks/claim succeeds
   Agent asks: "The task is claimed. What should I do next?"

✅ POST /api/tasks/claim succeeds
   Agent immediately reads task details and begins implementation

Mistake 4: Manually executing hooks in Claude Code

❌ Agent reads .stride.md, runs "git pull" and "mix deps.get" via Bash tool
   Agent captures exit code and duration
   Agent then makes the claim curl call
   (This triggers permission prompts and duplicates what hooks.json does)

✅ Agent just makes the claim curl call directly:
   curl -X POST .../api/tasks/claim -d '{...}'
   (hooks.json PostToolUse automatically runs stride-hook.sh
    which executes .stride.md before_doing commands)

Mistake 5: Prompting user for permission to run hooks (non-Claude-Code)

❌ Agent says "Let me run the before_doing hook" then waits for user approval
❌ Agent asks "Should I execute git pull origin main?"
❌ Agent presents hook commands and pauses for confirmation

✅ Agent reads .stride.md before_doing section
   Agent immediately executes each command via Bash tool calls
   No announcement, no confirmation, no waiting
   (The user authored these hooks — they are pre-authorized)

Mistake 6: Not fixing hook failures

❌ before_doing fails with merge conflicts
   Agent calls claim endpoint anyway

✅ before_doing fails with merge conflicts
   Agent resolves conflicts, re-runs hook until success
   Only then calls claim endpoint

Implementation Workflow

1. Verify prerequisites - Ensure auth and hooks files exist
2. Get next task - Call GET /api/tasks/next
3. Review task - Read all task details thoroughly
4. Check task completeness - If key_files/testing_strategy/verification_steps missing, invoke stride-enriching-tasks
5. Execute before_doing hook - Run setup with timeout
6. Check exit code - Must be 0
7. If failed: Fix issues, re-run, do NOT proceed
8. Call claim endpoint - Include before_doing_result
9. Begin implementation - Start coding immediately
10. Work until complete - Use stride-completing-tasks when done

Quick Reference Card

CLAUDE CODE CLAIMING WORKFLOW (automatic hooks):
├─ 1. Verify .stride_auth.md exists ✓
├─ 2. Verify .stride.md exists ✓
├─ 3. Extract API token and URL ✓
├─ 4. Call GET /api/tasks/next ✓
├─ 5. Review task details ✓
├─ 6. Check completeness → if minimal, invoke stride-enriching-tasks ✓
├─ 7. Call POST /api/tasks/claim directly ✓
│     (hooks.json auto-executes before_doing via stride-hook.sh)
├─ 8. Automatic hook failed? → Fix issues, retry claim ✓
└─ 9. Task claimed? → BEGIN IMPLEMENTATION IMMEDIATELY ✓

🚨 DO NOT manually execute .stride.md commands in Claude Code
🚨 DO NOT run separate Bash commands to "capture hook results"
🚨 JUST make the curl call — hooks.json handles everything

OTHER ENVIRONMENTS (manual hooks):
├─ 1-6. Same as above ✓
├─ 7. Read before_doing hook from .stride.md ✓
├─ 8. Execute before_doing (60s timeout, blocking) ✓
├─ 9. Capture exit_code, output, duration_ms ✓
├─ 10. Hook succeeds? → Call POST /api/tasks/claim WITH result ✓
├─ 11. Hook fails? → Fix issues, retry, never skip ✓
└─ 12. Task claimed? → BEGIN IMPLEMENTATION IMMEDIATELY ✓

API ENDPOINT: POST /api/tasks/claim
REQUIRED BODY: {
  "identifier": "W47",
  "agent_name": "Claude Opus 4.6",
  "skills_version": "1.0",
  "before_doing_result": {
    "exit_code": 0,
    "output": "Executed by Claude Code hooks system",
    "duration_ms": 0
  }
}

NEXT STEP: Immediately begin working on the task after successful claim
VERSION: Send skills_version from your SKILL.md frontmatter with every claim request

Real-World Impact

Before this skill (claiming without hooks):

• 35% of claims resulted in immediate merge conflicts
• 1.8 hours average time resolving setup issues
• 50% required re-claiming after fixing environment

After this skill (hooks before claim):

• 3% of claims had any setup issues
• 8 minutes average setup time
• 2% required troubleshooting

Time savings: 1.5+ hours per task (87% reduction in setup time)

Hook Result Format

Every hook result MUST be a map with these exact fields:

Field	Type	Required	Description
exit_code	integer	Yes	0 for success, non-zero for failure
output	string	Yes	stdout/stderr from hook execution
duration_ms	integer	Yes	Execution time in milliseconds

❌ WRONG (missing fields):
{"exit_code": 0}

❌ WRONG (wrong types):
{"exit_code": "0", "output": "", "duration_ms": "100"}

✅ RIGHT:
{
  "exit_code": 0,
  "output": "Already up to date.\nAll dependencies are up to date",
  "duration_ms": 450
}

Claim Request Checklist

The POST /api/tasks/claim body MUST include:

Field	Type	Example
identifier	string	"W47"
agent_name	string	"Claude Opus 4.6"
skills_version	string (optional)	"1.0" (from SKILL.md frontmatter)
before_doing_result	object	See hook result format above

Handling Stale Skills

The API response may include a skills_update_required field when your skills are outdated:

{
  "data": { ... },
  "skills_update_required": {
    "current_version": "1.1",
    "your_version": "1.0",
    "action": "Run /plugin update stride to get the latest skills",
    "reason": "Your local skills are outdated."
  }
}

When you see skills_update_required:

1. Run /plugin update stride to get the latest skills
2. Retry your original action

---

References: For the full field reference, see api_schema in the onboarding response (GET /api/agent/onboarding). For endpoint details, see the API Reference.