---
name: eck:quick-task
version: "0.7.4"
description: "Express SDD lifecycle for quick/lightweight tasks: Spec→Design→Develop→Validate→Deploy with complexity routing, mode-aware gates, and optional --deploy and --trace flags."
disable-model-invocation: false
---

# Quick Task

Fast, lightweight task execution for small changes that don't need the full core loop.

> No plan mode. No ceremony. Just describe what you want and it ships.

Quick task: $ARGUMENTS

---

## Visual Framework

Follow the `output:visual-framework` primitive for all terminal output displayed to the user via the Bash tool.

### ANSI Colors

Declare these variables at the top of **every** Bash tool call:

```bash
source $ECK_HOME/colors.sh
```

Every color sequence **must** end with `${RESET}`. No exceptions.

### Status Symbols

| Symbol | Meaning          | Color       |
| ------ | ---------------- | ----------- |
| `[*]`  | Active / running | `${CYAN}`   |
| `[x]`  | Completed        | `${GREEN}`  |
| `[!]`  | Error            | `${RED}`    |
| `[-]`  | Skipped          | `${DIM}`    |
| `[>]`  | In progress      | `${YELLOW}` |
| `[ ]`  | Pending          | `${DIM}`    |

### Summary Boxes

Display at checkpoints and at the end of the skill using the visual framework box format.

---

## Task Registration

| Stage | Subject            | Active Form        | Statusline      |
| ----- | ------------------ | ------------------ | --------------- |
| 0     | Stage 0: Calibrate | Calibrating mode   | Calibrate (0/5) |
| 1     | Stage 1: Spec      | Scoping task       | Spec (1/5)      |
| 2     | Stage 2: Design    | Planning approach  | Design (2/5)    |
| 3     | Stage 3: Develop   | Developing changes | Develop (3/5)   |
| 4     | Stage 4: Validate  | Validating changes | Validate (4/5)  |
| 5     | Stage 5: Deploy    | Deploying changes  | Deploy (5/5)    |

### Statusline Stage Updates

At the **start** of each stage, update the statusline:

```bash
bash $ECK_HOME/update-stage.sh "{Statusline text from table}"
```

At **skill completion** (success or error), reset:

```bash
bash $ECK_HOME/update-stage.sh
```

### Task Management

Register stages as tasks in Claude's TaskList for progress visibility:

- **Stage 0**: Register all stages (1–5, or 1–4 if no `--deploy`) via `TaskCreate`:
  ```
  TaskCreate: subject="Stage {N}: {name}", description="{Active Form from table}"
  ```
- **At each stage start**: `TaskUpdate` to `in_progress`
- **At each stage end**: `TaskUpdate` to `completed`

This MUST be done so the user can see progress during execution.

---

## Usage

```
/eck:quick-task fix the typo in README.md
/eck:quick-task add error handling to the login function
/eck:quick-task --deploy update the version constant to 2.1.0
/eck:quick-task --trace --deploy refactor the retry logic in auth.js
/eck:quick-task --rigor lite --force migrate config loader to async
```

### Flags

| Flag                             | Purpose                                                   |
| -------------------------------- | --------------------------------------------------------- |
| `--deploy`                       | Doc updates, push + ff-merge to main, close tracker issue |
| `--trace`                        | Express AC-IDs (QAC-\*) in commit trailer                 |
| `--rigor lite\|standard\|strict` | Override development rigor                                |
| `--force`                        | Proceed even at medium complexity tier                    |

---

## Stage 0: Calibrate

### Inputs

- `$ARGUMENTS` (task description + flags)
- `.claude/project-constants.md` (project type level, dev rigor)

### Activities

1. Parse `$ARGUMENTS` for task description and flags (`--deploy`, `--trace`, `--rigor`, `--force`)
2. Resolve development mode via `mode:read-dev-rigor` primitive
3. Create quick-task guard bypass marker so lifecycle phase guards allow code writes regardless of current phase:
   ```bash
   touch .claude/.quick-task-active
   ```
4. Display mode banner

### Outputs

- Resolved mode (lite / standard / strict)
- Parsed flags

### Exit Criteria

- Mode resolved and banner displayed
- All flags parsed and validated

---

## Stage 1: Spec

### Inputs

- Task description from `$ARGUMENTS`
- Codebase state

### Activities

1. Read relevant code to understand the problem space — research the area of the codebase affected by the task
2. **MUST** estimate complexity using file count and line-change heuristics before proceeding:

   | Tier    | Files | Lines | Action                                                    |
   | ------- | ----- | ----- | --------------------------------------------------------- |
   | Trivial | 1-2   | <20   | Proceed                                                   |
   | Small   | 3-5   | <50   | Proceed with note                                         |
   | Medium  | 5-10  | <100  | Suggest `dev-task --rigor lite`, allow `--force` override |
   | Large   | 10+   | 100+  | Hard reject -> `/eck:design`                              |

3. If complexity is Medium and `--force` not set, display suggestion and STOP
4. If complexity is Large, display rejection and STOP
5. Create a tracker issue via `tracker:issue-create` (resolved through `tracker:router`, which reads `<TRACKER_TYPE>` from `.claude/project-constants.md`). Use a conventional-commit title (`type(scope): description`) and body containing Problem, Changes, and Acceptance Criteria sections. Capture the issue key from the response.
6. If `--trace`: auto-generate 1-3 `QAC-*` criteria from the task description. Present them for a single Y/n confirmation. Format: `QAC-001`, `QAC-002`, etc.
7. Display assessment:
   ```
   [>] Quick task: {description}
       Tier: {tier} ({file_count} files, ~{line_count} lines)
       Mode: {mode}
       Issue: #{number}
   ```

### Outputs

- Complexity tier classification
- Tracker issue key
- QAC-\* criteria list (if `--trace`)

### Exit Criteria

- Complexity is Trivial, Small, or Medium with `--force`
- Tracker issue created
- QAC criteria confirmed (if `--trace`)

---

## Stage 2: Design

### Inputs

- Task description
- Complexity tier from Stage 1

### Activities

1. Identify all files to modify using `codebase:search` and `codebase:read` primitives
2. Determine execution strategy based on change type:
   - **Code changes**: Agent dispatch (e.g., `backend-developer` for .py/.go/.java/.rb, `frontend-developer` for .tsx/.jsx/.vue, `database-specialist` for migrations)
   - **Config/doc-only changes**: Inline execution (no agent dispatch needed)
3. Note any risks or dependencies between changes
4. Display planned approach:
   ```
   [>] Design: {file_count} files identified
       Strategy: {agent dispatch | inline}
       Files: path/to/file1.js, path/to/file2.js
   ```

### Outputs

- File list to modify
- Execution strategy (agent dispatch or inline)
- Risk notes (if any)

### Exit Criteria

- All target files identified
- Execution strategy determined
- Approach displayed to user

---

## Stage 3: Develop

### Inputs

- Task description
- File list and execution strategy from Stage 2
- Complexity tier from Stage 1
- QAC-\* criteria (if `--trace`)

### Activities

1. For code changes: dispatch to the appropriate domain agent via `Agent` tool (e.g., `backend-developer`, `frontend-developer`, `database-specialist`). Provide the agent with: task description, identified files, complexity tier, and any QAC criteria (if `--trace`).
2. For config/doc-only changes: execute inline (no agent dispatch needed)
3. Make the changes directly — no branching, no plan file
4. Keep changes minimal and focused on the stated task
5. Display each change as it's made:
   ```
   [x] Modified: path/to/file.js (added error handling)
   ```

### Outputs

- Modified files

### Exit Criteria

- All changes applied
- No unrelated modifications

---

## Stage 4: Validate

### Inputs

- Modified files from Stage 3
- Resolved development mode

### Activities

1. **MUST** run quality gates based on development mode using review primitives. Do NOT skip verification even for trivial-tier tasks:
   - **Lite**: `review:test` only
   - **Standard**: `review:test` + `review:lint`
   - **Strict**: `review:test` + `review:lint` + `review:typecheck`
2. If tests fail, attempt fix (one retry only)
3. If still failing, STOP and report:
   ```
   [!] Tests failing after fix attempt
       Run /eck:validate for full diagnosis
   ```
4. If `--deploy`: check and update impacted documentation. Read `<DOC_PLATFORM>` from `.claude/project-constants.md`:
   - **If Local markdown:** Update relevant docs (README.md, DEV-GUIDE.md, USER-GUIDE.md, CHANGELOG.md)
   - **If Confluence:** Update relevant pages via `docs:doc-update` (resolved through `docs:router`)
   - Only update sections directly affected by the change
   - Skip if the change has zero documentation impact

### Outputs

- Test results (pass/fail)
- Lint results (if standard/strict)
- Type check results (if strict)
- Updated docs (if `--deploy`)

### Exit Criteria

- All mode-appropriate quality gates pass
- Docs updated if impacted (if `--deploy`)

---

## Stage 5: Deploy

### Inputs

- Modified files from Stages 3–4
- Tracker issue key from Stage 1
- QAC-\* criteria (if `--trace`)

### Activities

1. **MUST** stage only the files changed in Stage 3 (and Stage 4 doc updates if `--deploy`). Do NOT stage unrelated files
2. Generate commit message from task description using `validation:commit-format`
3. Append tracker reference to commit body:
   - **GitHub Issues with `--deploy`**: `Closes #<number>` (auto-closes on push to main)
   - **GitHub Issues without `--deploy`**: `Refs #<number>` (traceability without premature close)
   - **JIRA**: `Refs: KEY-123` (traceability only; actual close happens later in this stage)
   - **Linear**: `Refs: KEY-123` (traceability only; actual close happens later in this stage)
   - **Local**: `Refs: KEY-123` (traceability only; actual close happens later in this stage)
4. If `--trace`: append `Satisfies: QAC-001, QAC-002, ...` trailer to commit body
5. Commit via `vcs/git:commit` primitive
6. **If `--deploy`:**
   - Push dev branch via `vcs/git:push` primitive
   - Fast-forward merge to main via `vcs/git:merge` primitive (strategy: `ff-only`)
   - If `--ff-only` fails, STOP and report the conflict — never force-push
   - Close tracker issue explicitly via `tracker:router` (non-blocking):
     - **GitHub Issues**: Already closed via `Closes #N` commit message — verify with `tracker/gh-cli:issue-view`
     - **JIRA**: `tracker:issue-transition` (id: issue key, target_status: `done`)
     - **Linear**: `tracker:issue-transition` (id: issue key, target_status: `done`)
     - **Local**: `tracker:issue-close` (id: issue key)
     - Non-blocking: log warning on failure, never halt
   - Return to dev branch
7. Display summary box (always show Issue line):
   ```
   +-- Quick Task Complete -----------------------------------+
   |                                                          |
   |  Task             {description}                          |
   |  Files changed    {count}                                |
   |  Commit           {short_sha} {message}                  |
   |  Issue            #{number}                              |
   |  Traceability     QAC-001, QAC-002 (if --trace)          |
   |  Deployed         yes/no                                 |
   |  Duration         {time}                                 |
   |                                                          |
   +----------------------------------------------------------+
   ```

### Outputs

- Git commit with SHA
- Push/merge status (if `--deploy`)
- Tracker issue closed (if `--deploy`)

### Exit Criteria

- Commit created successfully
- Commit message passes `validation:commit-format`
- **If `--deploy`:** both dev and main branches pushed, back on dev branch, tracker issue closed or close-warning logged

---

## Error Handling

Follow the `output:error-handler` primitive for all error conditions.

- At completion (success or error), remove the quick-task guard bypass marker: `rm -f .claude/.quick-task-active`
- If task is too complex for /eck:quick-task, suggest `/eck:design` with the same arguments
- If complexity is Medium, suggest `dev-task --rigor lite` as alternative (allow `--force` override)
- Never make changes outside the scope of the stated task
- If verification fails after one retry, stop and report -- do not force-commit broken code
- If `--ff-only` merge fails, stop and report the conflict -- never force-push
- At completion (success or error), clean up: `rm -f .claude/.quick-task-active && bash $ECK_HOME/update-stage.sh`

---

## Related Documents

- `mode:read-dev-rigor` primitive -- development mode resolution
- `validation:commit-format` primitive -- commit message validation
- `review:test`, `review:lint`, `review:typecheck` primitives -- quality gates
- `vcs/git:commit`, `vcs/git:push`, `vcs/git:merge` primitives -- git operations
- `tracker:router` -- tracker abstraction (issue-create, issue-transition, issue-close)
- `docs:router` -- documentation platform abstraction
- `codebase:search`, `codebase:read` primitives -- code exploration
- `agent:fresh-context` primitive -- agent dispatch
- `output:visual-framework` primitive -- terminal output conventions
- `output:error-handler` primitive -- error handling conventions
