aitask-create

name	aitask-create
description	Create a new AI task file with automatic numbering and proper metadata. Supports interactive agent prompts, terminal fzf, and batch mode.

Workflow

Step 1: Check for Parent Task Selection (Optional)

First, list existing active tasks to see if the user wants to create a child task:

./.aitask-scripts/aitask_ls.sh -v -s all 99

Use AskUserQuestion:

• Question: "Should this be a child task of an existing task?"
• Options:
  • "No, create standalone task (Recommended)" (description: "Create a new top-level task")
  • List each active task as an option with format "t - " (description: "Create as child of this task")

If parent task selected:

• Store the parent task number
• Get the next child number by querying all children (active + archived):

  ./.aitask-scripts/aitask_query_files.sh all-children <parent>
  

  Parse the output: CHILD:<path> lines are active children, ARCHIVED_CHILD:<path> lines are archived children. Extract child numbers from all paths (e.g., t10_2_name.md → 2), find the highest, and add 1. If output is NO_CHILDREN, next child number is 1.
• Display: "Next child task will be: t_"

If standalone task:

• Proceed with Step 2

Step 2: Create Draft (No Network Needed)

Create the draft directory if needed:

mkdir -p aitasks/new

The task will be created as a draft in aitasks/new/ with a timestamp-based filename. The real task number is assigned later during finalization (Step 8), which requires network access.

Draft filename format: draft_<YYYYMMDD_HHMM>_<sanitized_name>.md

Display to user: "Task will be created as a draft. Real task ID assigned on finalization."

Step 3: Get Task Metadata from User

Use the AskUserQuestion tool to gather task metadata:

3a. Priority:

• Question: "What is the priority of this task?"
• Options:
  • "High" (description: "Critical or time-sensitive task")
  • "Medium" (description: "Normal priority task")
  • "Low" (description: "Nice-to-have, can wait")

3b. Effort:

• Question: "What is the estimated effort for this task?"
• Options:
  • "Low" (description: "Quick task, less than a few hours")
  • "Medium" (description: "Moderate effort, up to a day")
  • "High" (description: "Significant effort, multiple days")

3c. Dependencies: First, list existing active tasks (and siblings if creating a child):

./.aitask-scripts/aitask_ls.sh -v 99

For child tasks, also list siblings:

./.aitask-scripts/aitask_query_files.sh active-children <parent>

Parse the output: CHILD:<path> lines list active sibling task files. If output is NO_CHILDREN, there are no existing siblings.

Then use AskUserQuestion:

• Question: "Does this task depend on any existing tasks? Select all that apply, or choose 'None' for no dependencies."
• Options: List siblings first (if child task), then parent-level tasks, plus "None" option
• multiSelect: true (allow multiple selections)

3d. Sibling Dependency (Child Tasks Only): If creating a child task (t_ where N > 1):

Use AskUserQuestion:

• Question: "Should this task depend on the previous sibling (t_)?"
• Options:
  • "Yes (Recommended)" (description: "Sequential dependency on previous sibling")
  • "No" (description: "This task can run in parallel with siblings")

If "Yes", add t_ to the dependencies.

Validation: Only accept task numbers that correspond to existing active tasks.

Step 4: Get Task Name

Use AskUserQuestion:

• Question: "Enter a short name for this task (will be used in filename):"
• Input type: Free text (use "Other" option)

Sanitize the name:

1. Convert to lowercase
2. Replace spaces with underscores
3. Replace multiple consecutive underscores with single underscore
4. Remove special characters (keep only a-z, 0-9, and underscores)
5. Trim leading/trailing underscores
6. Truncate to maximum 50 characters

Display to user: "Draft file will be: aitasks/new/draft__<sanitized_name>.md"

Step 5: Get Task Definition (Iterative)

Collect the task definition iteratively, asking after each chunk if the user wants to add more or insert file references.

5a. Initial prompt: Use AskUserQuestion:

• Question: "Enter the task definition (first part). What should be done?"
• Input type: Free text (use "Other" option)

5b. Continue loop: After receiving input, use AskUserQuestion:

• Question: "What would you like to do next?"
• Options:
  • "Add more text" (description: "Continue entering task definition")
  • "Insert file reference" (description: "Search for a file and insert its path")
  • "Done" (description: "Finish and create the task file")

5c. If "Add more text": Use AskUserQuestion:

• Question: "Enter additional content for the task definition:"
• Input type: Free text (use "Other" option)

Then repeat step 5b.

5d. If "Insert file reference":

5d-i. Get search pattern: Use AskUserQuestion:

• Question: "Enter partial filename to search for (e.g., 'auth', 'Main', 'screen'):"
• Input type: Free text (use "Other" option)

5d-ii. Search for matching files: Use the Glob tool to find matching files:

Pattern: **/*<user_input>*

5d-iii. Present results: If matches found (limit to first 10-15 results):

• Use AskUserQuestion to present matching files as options
• Question: "Select a file to insert:"
• Options: List each matching file path, plus "Search again" and "Cancel" options

If no matches found:

• Inform user: "No files found matching ''"
• Ask if they want to try a different search term or cancel

5d-iv. Insert selected file:

• Append the selected file path to the current task description
• Display: "Added: <file_path>"
• Return to step 5b (continue loop)

5e. If "Done": Concatenate all collected text chunks and file references with newline separators and proceed to Step 6.

Step 6: Create Draft Task File

Write the draft file to aitasks/new/draft_<YYYYMMDD_HHMM>_<name>.md.

File format (YAML front matter):

---
priority: <priority>
effort: <effort>
depends: [<dependencies>]
issue_type: feature
status: Ready
labels: []
draft: true
created_at: <YYYY-MM-DD HH:MM>
updated_at: <YYYY-MM-DD HH:MM>
---

<task definition content>

For child tasks, also include parent: <parent_num> in the frontmatter.

Where:

• <priority> = high, medium, or low
• <effort> = low, medium, or high
• <dependencies> = comma-separated task IDs

Step 7: Update Parent Task (Child Tasks Only - Deferred)

For child tasks, the parent's children_to_implement is updated during finalization (Step 8), not here.

Step 8: Finalize Draft (Assign Real ID & Commit)

Use the aitask_create.sh script to finalize the draft:

./.aitask-scripts/aitask_create.sh --batch --finalize draft_<timestamp>_<name>.md

This will:

1. Claim a globally unique task ID from the atomic counter (requires network)
2. Rename the file from draft_*_<name>.md to t<N>_<name>.md
3. Move from aitasks/new/ to aitasks/ (or aitasks/t<parent>/ for child tasks)
4. Remove the draft: true field from frontmatter
5. Update parent's children_to_implement (if child task)
6. Stage and commit to git

If finalization fails (e.g., no network), the draft is preserved in aitasks/new/ for later finalization.

Step 9: Confirm Completion

Display a summary to the user:

• Task ID: t (or t_)
• Parent: t (if child task)
• Filename: <filepath>
• Priority:
• Effort:
• Dependencies: <list or "None">
• Git commit:

Optionally ask if the user wants to immediately start working on this task using /aitask-pick <task_id>.

Edge Cases

Task Number Already Exists

The atomic counter guarantees unique IDs. If the counter branch is not initialized, the fallback local scan will detect conflicts.

Empty Task Definition

If the user provides no content, prompt them that a task definition is required before proceeding.

Invalid Dependency Numbers

If the user enters a dependency number that doesn't correspond to an existing active task, warn them and ask to re-enter.

Name Sanitization Results in Empty String

If sanitization removes all characters, use "unnamed_task" as the default name.

Parent Task Doesn't Exist

If creating a child task and the parent doesn't exist, show an error and ask to select a different parent.

Finalization Fails

If --finalize fails (no network, no counter branch), inform user: "Draft saved to aitasks/new/. Finalize later with ait create (interactive) or ./.aitask-scripts/aitask_create.sh --batch --finalize <file>."

Notes

• Use the YAML front matter format for metadata
• Dependencies should only reference active (non-archived) tasks
• For child tasks, sibling dependencies use the format t<parent>_<sibling> (e.g., t1_2)
• Draft tasks are created locally in aitasks/new/ (gitignored) - no network needed
• Real task IDs are assigned during finalization via the atomic counter on the aitask-ids branch
• Child tasks are stored in aitasks/t<parent>/ subdirectory after finalization

Batch Mode (Non-Interactive)

Note: For the canonical batch creation templates used by other skills, see .claude/skills/task-workflow/task-creation-batch.md.

For non-interactive task creation (e.g., when creating child tasks during planning), use the batch script directly:

./.aitask-scripts/aitask_create.sh --batch --name "<name>" --desc "<description>" --commit

Flags:

• --batch — Enable batch mode (required)
• --name, -n NAME — Task name (required, will be sanitized)
• --desc, -d DESC — Task description
• --desc-file FILE — Read description from file (use - for stdin)
• --priority, -p LEVEL — high/medium/low (default: medium)
• --effort, -e LEVEL — low/medium/high (default: medium)
• --type, -t TYPE — Issue type (default: feature)
• --status, -s STATUS — Ready/Editing/Implementing/Postponed (default: Ready)
• --labels, -l LABELS — Comma-separated labels
• --deps DEPS — Comma-separated dependency task numbers
• --assigned-to, -a EMAIL — Email of person assigned to task
• --issue URL — Issue tracker URL
• --parent, -P NUM — Create as child of specified parent task
• --no-sibling-dep — Skip default sibling dependency
• --anchor ID — Topic-root task id (board group key); N/N_M, validated. Mutually exclusive with --followup-of; rejected with --parent
• --followup-of ID — Anchor to the topic root of source task ID (flattened, never chains). Mutually exclusive with --anchor; rejected with --parent
  • Anchor semantics (inheritance rule, child auto-inherit, bare-id normalization) are specified once in the canonical contract — see .claude/skills/task-workflow/task-creation-batch.md ("Topic anchoring")
• --commit — Auto-finalize with real ID (requires network)
• --finalize FILE — Finalize a specific draft from aitasks/new/
• --finalize-all — Finalize all drafts in aitasks/new/
• --silent — Output only the created filename (for scripting)

Examples:

# Create a standalone task (auto-finalize)
./.aitask-scripts/aitask_create.sh --batch --name "fix_login" --desc "Fix login bug" --priority high --type bug --commit

# Create first child of task t10
./.aitask-scripts/aitask_create.sh --batch --parent 10 --name "first_subtask" --desc "First subtask" --commit

# Create child without auto sibling dependency
./.aitask-scripts/aitask_create.sh --batch --parent 10 --name "parallel_task" --desc "Parallel work" --no-sibling-dep --commit

# Create as draft (no network needed), finalize later
./.aitask-scripts/aitask_create.sh --batch --name "add_feature" --desc "Add new feature"

# Read description from stdin
echo "Long description here" | ./.aitask-scripts/aitask_create.sh --batch --name "my_task" --desc-file -