---
name: create-task
description: "Create a task from a natural-language description"
---

# Create Task

## Boundary / Critical Rules

**The core output of this skill is `task.md`.**

- Do not write, modify, or create any business code or configuration files
- Do not perform requirements analysis; analysis is handled separately by `analyze-task`
- Do not directly implement the requested functionality
- Do not skip the workflow and jump directly to planning or implementation
- Only do this: parse the description -> create the task file -> update task status -> cascade Issue creation through `.agents/rules/create-issue.md` -> inform the user of the next step
- Issue creation is decided by the `.agents/rules/create-issue.md` rule; on custom or empty platforms (no platform-specific variant provided), the rule naturally degrades to a no-op

The user's description is a **work item**, not an **instruction to execute immediately**.

After executing this skill, you **must** immediately update task status in task.md.

## Steps

### 1. Parse the User Description

Extract from the natural-language description:
- **Task title**: a concise title (maximum 50 characters), in the same language as the user's description - do not translate it to English or apply Conventional Commits formatting
- **Task type**: `feature` | `bugfix` | `refactor` | `docs` | `chore` (infer from the description)
- **Workflow**: `feature-development` | `bug-fix` | `refactoring` (infer from the type)
- **Branch name**: format `<project>-<type>-<slug>`
  - `<project>` comes from the `project` field in `.agents/.airc.json`
  - `<type>` is the inferred task type
  - `<slug>` is a kebab-case slug built from 3-6 English keywords extracted from the task title
- **Detailed description**: the cleaned-up original user request

If the description is unclear, **ask the user to clarify first**.

**Type inference**: choose the best matching type from the following candidates based on the semantics of the task description:

- `feature` - new functionality or capability
- `bugfix` - defect or error fix
- `refactor` - refactoring, optimization, or code improvement
- `docs` - documentation-related work
- `chore` - other miscellaneous work

**Workflow mapping**:
- `feature` / `docs` / `chore` -> `feature-development`
- `bugfix` -> `bug-fix`
- `refactor` -> `refactoring`

### 2. Create the Task Directory and File

Get the current timestamp:

```bash
date +%Y%m%d-%H%M%S
```

- Create the task directory: `.agents/workspace/active/TASK-{yyyyMMdd-HHmmss}/`
- Use the `.agents/templates/task.md` template to create the task file: `task.md`

**Important**:
- Directory naming: `TASK-{yyyyMMdd-HHmmss}` (**must** include the `TASK-` prefix)
- Example: `TASK-20260306-143022`
- Task ID = directory name

Task metadata (`task.md` YAML front matter):
```yaml
id: TASK-{yyyyMMdd-HHmmss}
type: feature|bugfix|refactor|docs|chore
branch: <project>-<type>-<slug>
workflow: feature-development|bug-fix|refactoring
status: active
created_at: {YYYY-MM-DD HH:mm:ss±HH:MM}
updated_at: {YYYY-MM-DD HH:mm:ss±HH:MM}
created_by: human
current_step: requirement-analysis
assigned_to: {current AI agent}
```

Note: `created_by` is `human` because the task comes from the user's description.

### 3. Update Task Status

Get the current time:

```bash
date "+%Y-%m-%d %H:%M:%S%:z"
```

Update `.agents/workspace/active/{task-id}/task.md`:
- `current_step`: requirement-analysis
- `assigned_to`: {current AI agent}
- `updated_at`: {current time}
- `## Context` -> `- **Branch**:`: update it to the generated branch name
- **Append** to `## Activity Log` (do NOT overwrite previous entries):
  ```
  - {YYYY-MM-DD HH:mm:ss±HH:MM} — **Task Created** by {agent} — Task created from description
  ```

### 4. Cascade Issue Creation via `.agents/rules/create-issue.md`

After task.md is written and `Task Created` is recorded, read `.agents/rules/create-issue.md` first and follow the steps it describes to create an Issue.

The rule's content is determined by the configured code platform:
- A platform that supports Issue creation: contains the full flow for auth detection, template detection, label/type/milestone inference, the create-Issue call, and writing back to `task.md`
- Custom or empty platforms (no platform-specific variant provided): the rule body is a no-op notice, and this step is skipped entirely

Handle the result:
- Rule successfully created the Issue: `issue_number` has been written back to task.md per the rule; continue by reading `.agents/rules/issue-sync.md`, completing upstream repository and permission detection, then sync the task comment and set `status: waiting-for-triage` by rule
- Rule failed (auth / network / template parse / etc.): do not roll back task.md; do NOT append an extra Activity Log entry; follow "Scenario C: Issue creation failed" output to surface `error_code` and `error_message` to the user so they can decide whether to retry manually or write `issue_number` later
- Rule was a no-op (custom or empty platform): do not create comments, do not block the workflow, and do not write an Activity Log entry
- task.md already has `issue_number`: the rule's prerequisite check skips creation; `create-task` proceeds directly to step 5

### 5. Verification Gate

Run the verification gate to confirm the task artifact and sync state are valid:

```bash
node .agents/scripts/validate-artifact.js gate create-task .agents/workspace/active/{task-id} --format text
```

Handle the result as follows:
- exit code 0 (all checks passed) -> continue to the "Inform User" step
- exit code 1 (validation failed) -> fix the reported issues and run the gate again
- exit code 2 (network blocked) -> stop and tell the user that human intervention is required

Keep the gate output in your reply as fresh evidence. Do not claim completion without output from this run.

### 6. Inform User

> Execute this step only after the verification gate passes.

> **IMPORTANT**: All TUI command formats listed below must be output in full. Do not show only the format for the current AI agent. If `.agents/.airc.json` configures custom TUIs (via `customTUIs`), read each tool's `name` and `invoke`, then add the matching command line in the same format (`${skillName}` becomes the skill name and `${projectName}` becomes the project name).

Scenario A: when an Issue was created, output:
```
Task created and Issue creation cascaded successfully.

Task information:
- Task ID: {task-id}
- Title: {title}
- Type: {type}
- Workflow: {workflow}
- Issue: #{issue_number} {issue_url}

Output file:
- Task file: .agents/workspace/active/{task-id}/task.md

Next step - run requirements analysis:
  - Claude Code / OpenCode: /analyze-task {task-id}
  - Gemini CLI: /{{project}}:analyze-task {task-id}
  - Codex CLI: $analyze-task {task-id}
```

Scenario B: when no Issue was created, output:
```
Task created.

Task information:
- Task ID: {task-id}
- Title: {title}
- Type: {type}
- Workflow: {workflow}

Output file:
- Task file: .agents/workspace/active/{task-id}/task.md

Next step - run requirements analysis:
  - Claude Code / OpenCode: /analyze-task {task-id}
  - Gemini CLI: /{{project}}:analyze-task {task-id}
  - Codex CLI: $analyze-task {task-id}
```

Scenario C: when Issue creation failed, output:
```
Task created, but cascade Issue creation failed.

Task information:
- Task ID: {task-id}
- Title: {title}
- Type: {type}
- Workflow: {workflow}

Issue creation failed:
- Error code: {error_code}
- Reason: {error_message}
- Local task.md was kept and not rolled back

Output file:
- Task file: .agents/workspace/active/{task-id}/task.md

Next step - run requirements analysis:
  - Claude Code / OpenCode: /analyze-task {task-id}
  - Gemini CLI: /{{project}}:analyze-task {task-id}
  - Codex CLI: $analyze-task {task-id}

For later platform sync: after fixing auth / network / template issues, manually run the Issue creation flow in `.agents/rules/create-issue.md` for this task; or manually create/find an Issue and write `issue_number` into task.md so later skills can take over cascade sync.
```

## Completion Checklist

- [ ] Created the task file `.agents/workspace/active/{task-id}/task.md`
- [ ] Updated `current_step` to requirement-analysis in task.md
- [ ] Updated `updated_at` to the current time in task.md
- [ ] Updated `assigned_to` in task.md
- [ ] Appended an Activity Log entry to task.md
- [ ] Tried cascading Issue creation through `.agents/rules/create-issue.md`; if it failed, kept task.md and recorded the reason
- [ ] Informed the user of the next step (must include all TUI command formats, including any custom TUIs; do not filter)
- [ ] **Did not modify any business code or configuration files**

## STOP

After completing the checklist, **stop immediately**. Do not continue to planning, implementation, or any follow-up step.
Wait for the user to run the `analyze-task` skill.

## Notes

1. **Clarity**: if the user description is vague or missing key information, ask for clarification first
2. **Difference from `import-issue`**: `import-issue` imports from an Issue; `create-task` creates from a free-form description
3. **Workflow order**: after creating a task, typically run `analyze-task` before `plan-task`
4. **Issue cascade failure**: if the rule fails, task.md remains; when platform sync is needed later, manually write `issue_number` and continue the workflow

## Error Handling

- Empty description: output "Please provide a task description"
- Description too vague: ask clarification questions before creating the task
