executing-quick-tasks

<user_command>/kata:quick-task</user_command>

Quick mode is the same system with a shorter path:

• Spawns kata-planner (quick mode) + kata-executor(s)
• Skips kata-phase-researcher, kata-plan-checker, kata-verifier
• Quick tasks live in .planning/quick/ separate from planned phases
• Updates STATE.md "Quick Tasks Completed" table (NOT ROADMAP.md)

Use when: You know exactly what to do and the task is small enough to not need research or verification.

<execution_context> Orchestration is inline - no separate workflow file. Quick mode is deliberately simpler than full Kata. </execution_context>

Read model profile for agent spawning:

MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")

Default to "balanced" if not set.

Model lookup table:

Store resolved models for use in Task calls below.

Step 1: Pre-flight validation

Check that an active Kata project exists:

if [ ! -f .planning/ROADMAP.md ]; then
  echo "Quick mode requires an active project with ROADMAP.md."
  echo "Run /kata:new-project first."
  exit 1
fi

If validation fails, stop immediately with the error message.

Quick tasks can run mid-phase - validation only checks ROADMAP.md exists, not phase status.

Step 2: Get task description

Prompt user interactively for the task description:

AskUserQuestion(
  header: "Quick Task",
  question: "What do you want to do?",
  followUp: null
)

Store response as $DESCRIPTION.

If empty, re-prompt: "Please provide a task description."

Generate slug from description:

slug=$(echo "$DESCRIPTION" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//' | cut -c1-40)

Step 3: Calculate next quick task number

Ensure .planning/quick/ directory exists and find the next sequential number:

# Ensure .planning/quick/ exists
mkdir -p .planning/quick

# Find highest existing number and increment
last=$(ls -1d .planning/quick/[0-9][0-9][0-9]-* 2>/dev/null | sort -r | head -1 | xargs -I{} basename {} | grep -oE '^[0-9]+')

if [ -z "$last" ]; then
  next_num="001"
else
  next_num=$(printf "%03d" $((10#$last + 1)))
fi

Step 4: Create quick task directory

Create the directory for this quick task:

QUICK_DIR=".planning/quick/${next_num}-${slug}"
mkdir -p "$QUICK_DIR"

Report to user:

Creating quick task ${next_num}: ${DESCRIPTION}
Directory: ${QUICK_DIR}

Store $QUICK_DIR for use in orchestration.

Step 4.5: Read context files

Read files before spawning agents using the Read tool. The @ syntax does not work across Task() boundaries - content must be inlined.

Read this file:

• .planning/STATE.md (required)

Store content for use in Task prompts below.

Step 5: Spawn planner (quick mode)

Spawn kata-planner with quick mode context:

Task(
  prompt="
<planning_context>

**Mode:** quick
**Directory:** ${QUICK_DIR}
**Description:** ${DESCRIPTION}

**Project State:**
${STATE_CONTENT}

</planning_context>

<constraints>
- Create a SINGLE plan with 1-3 focused tasks
- Quick tasks should be atomic and self-contained
- No research phase, no checker phase
- Target ~30% context usage (simple, focused)
</constraints>

<output>
Write plan to: ${QUICK_DIR}/${next_num}-PLAN.md
Return: ## PLANNING COMPLETE with plan path
</output>
",
  subagent_type="kata-planner",
  model="{planner_model}",
  description="Quick plan: ${DESCRIPTION}"
)

After planner returns:

1. Verify plan exists at ${QUICK_DIR}/${next_num}-PLAN.md
2. Extract plan count (typically 1 for quick tasks)
3. Report: "Plan created: ${QUICK_DIR}/${next_num}-PLAN.md"

If plan not found, error: "Planner failed to create ${next_num}-PLAN.md"

Step 6: Spawn executor

Read the plan content before spawning using the Read tool:

• ${QUICK_DIR}/${next_num}-PLAN.md

Spawn kata-executor with inlined plan (use the STATE_CONTENT from step 4.5):

Task(
  prompt="
Execute quick task ${next_num}.

<plan>
${PLAN_CONTENT}
</plan>

<project_state>
${STATE_CONTENT}
</project_state>

<constraints>
- Execute all tasks in the plan
- Commit each task atomically
- Create summary at: ${QUICK_DIR}/${next_num}-SUMMARY.md
- Do NOT update ROADMAP.md (quick tasks are separate from planned phases)
</constraints>
",
  subagent_type="kata-executor",
  model="{executor_model}",
  description="Execute: ${DESCRIPTION}"
)

After executor returns:

1. Verify summary exists at ${QUICK_DIR}/${next_num}-SUMMARY.md
2. Extract commit hash from executor output
3. Report completion status

If summary not found, error: "Executor failed to create ${next_num}-SUMMARY.md"

Note: For quick tasks producing multiple plans (rare), spawn executors in parallel waves per phase-execute patterns.

Step 7: Update STATE.md

Update STATE.md with quick task completion record.

7a. Check if "Quick Tasks Completed" section exists:

Read STATE.md and check for ### Quick Tasks Completed section.

7b. If section doesn't exist, create it:

Insert after ### Blockers/Concerns section:

### Quick Tasks Completed

| #   | Description | Date | Commit | Directory |
| --- | ----------- | ---- | ------ | --------- |

7c. Append new row to table:

| ${next_num} | ${DESCRIPTION} | $(date +%Y-%m-%d) | ${commit_hash} | [${next_num}-${slug}](./quick/${next_num}-${slug}/) |

7d. Update "Last activity" line:

Find and update the line:

Last activity: $(date +%Y-%m-%d) - Completed quick task ${next_num}: ${DESCRIPTION}

Use Edit tool to make these changes atomically

Step 8: Final commit and completion

Stage and commit quick task artifacts:

# Stage quick task artifacts
git add ${QUICK_DIR}/${next_num}-PLAN.md
git add ${QUICK_DIR}/${next_num}-SUMMARY.md
git add .planning/STATE.md

# Commit with quick task format
git commit -m "$(cat <<'EOF'
docs(quick-${next_num}): ${DESCRIPTION}

Quick task completed.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
EOF
)"

Get final commit hash:

commit_hash=$(git rev-parse --short HEAD)

Display completion output:

---

Kata > QUICK TASK COMPLETE

Quick Task ${next_num}: ${DESCRIPTION}

Summary: ${QUICK_DIR}/${next_num}-SUMMARY.md
Commit: ${commit_hash}

---

Ready for next task: /kata:quick-task

<success_criteria>

• ROADMAP.md validation passes
• User provides task description
• Slug generated (lowercase, hyphens, max 40 chars)
• Next number calculated (001, 002, 003...)
• Directory created at .planning/quick/NNN-slug/
• ${next_num}-PLAN.md created by planner
• ${next_num}-SUMMARY.md created by executor
• STATE.md updated with quick task row
• Artifacts committed </success_criteria>