# Core Workflow Parity Milestone Design

> Historical design record for the currently selected backlog slice. This file is the chosen design for that slice, but it remains planning context rather than a live contributor instruction document.

> Authority note: `FEATURE-GAP-ANALYSIS.md` is the broader backlog inventory. This spec is the authoritative design only for the selected milestone slice documented here.

## Summary

This milestone adds four bounded, public-API-confirmed capability slices to `clickup-cli`: custom field discovery and filtering, richer task creation parity, task links and multi-list operations, and spaces CRUD parity. The goal is to deepen the CLI's existing workflow surface without compromising its automation contract or turning the milestone into a broad product-surface expansion.

This is a public repository milestone. Every phase should produce reviewable, human-readable changes with clear user-facing value and no AI- or workflow-specific noise in public artifacts.

## Problem

`clickup-cli` has a strong baseline for tasks, comments, docs, folders, lists, spaces, tags, and team lookups, but the current surface still has visible parity gaps in day-to-day ClickUp workflows.

The highest-confidence next step is not a new top-level domain like time tracking, goals, or chat. It is closing the most obvious gaps inside the surfaces the repo already owns, while keeping behavior bounded and compatible with the existing JSON-only stdout and dry-run-first contract.

## In Scope

### 1. Custom field discovery and search/filter parity

- Add first-class discovery for custom fields.
- Add task query ergonomics for custom-field-based filtering.
- Include closely related discovery surfaces only where they clearly support this workflow, such as task type listing.

### 2. Richer task-create parity

- Expand `tasks create` toward confirmed v2 parity for common create-time fields.
- Target practical task-creation flags such as due/start dates, time estimate, points, inline custom fields, and custom item type selection where the API supports them cleanly.
- Keep the first cut focused on create-time task payload parity, not adjacent follow-up workflows like attachments or checklists.

### 3. Task links and multi-list operations

- Add linked-task workflows distinct from dependency workflows.
- Add add/remove-to-extra-list flows and task-to-lists inspection.
- Keep these operations clearly separate from task move semantics, which already exist.

### 4. Spaces CRUD parity

- Add `spaces create`, `spaces update`, and `spaces delete`.
- Match the CLI's existing dry-run and JSON response conventions.
- Treat this as bounded hierarchy parity work, not a broader admin/governance expansion.

## Out of Scope

- Comments beyond tasks
- Checklists
- Time tracking and timers
- Views and saved-query workflows
- Goals and key results
- Templates
- Webhooks
- Attachments
- Admin-heavy, enterprise, experimental, or API-uncertain surfaces

These stay in `FEATURE-GAP-ANALYSIS.md` after this milestone unless a later milestone selects them.

## Phase Design

### Phase 1: Custom Field Discovery and Search/Filter Parity

Goal: make custom fields discoverable and usable as a first-class query surface.

Why first: richer task creation depends on better field/type visibility, and this phase closes the current write-without-discovery asymmetry.

### Phase 2: Richer Task-Create Parity

Goal: make `tasks create` materially closer to ClickUp's confirmed v2 create surface.

Why second: it builds on the discovery work from Phase 1 and improves one of the CLI's most important existing commands.

### Phase 3: Task Links and Multi-List Operations

Goal: complete the missing non-dependency task relationship workflows.

Why third: it remains within the task domain but is independent enough to review and verify separately.

### Phase 4: Spaces CRUD Parity

Goal: close the remaining obvious hierarchy asymmetry between spaces and the already-supported folders/lists CRUD surface.

Why fourth: it is bounded, lower-risk, and a clean final phase for the milestone.

## Constraints

- Preserve Python 3.9 compatibility.
- Preserve JSON-only stdout and stderr-only errors.
- Preserve honest `--dry-run` previews for every mutation.
- Prefer API-certain, bounded behavior over speculative surface expansion.
- Keep phases reviewable and public-repo friendly.
- Avoid bundling unrelated refactors unless they are required to support the selected feature slice safely.

## Success Criteria

- Each selected gap area has a clear CLI surface and tests.
- New commands and flags fit existing naming and help-text conventions.
- Existing task workflows remain backward compatible except for explicitly documented additive behavior.
- The milestone release story is easy to explain in a public changelog.
- At milestone completion, the four implemented items are removed from `FEATURE-GAP-ANALYSIS.md` and unselected items remain.

## Risks

| Risk | Why it matters | Mitigation |
|------|----------------|------------|
| Task-create parity sprawls | Create-time parity can quietly absorb attachments/checklists/other setup flows | Keep the phase limited to confirmed task payload fields and reject adjacent workflow creep |
| Custom-field filtering gets inconsistent | Discovery, search, and create can diverge if introduced piecemeal | Use Phase 1 to establish the discovery/query shape before broadening create |
| Multi-list ops blur with move behavior | Users may confuse move vs add/remove-to-list behavior | Keep command names and help text explicit about the semantic difference |
| Public-repo milestone gets noisy | Too many unrelated additions make the release harder to explain | Keep four focused phases and leave deferred items in the gap doc |

## Final Cleanup Rule

When this milestone is fully implemented and verified, update `FEATURE-GAP-ANALYSIS.md` by removing only these four selected items. Do not collapse or rewrite the rest of the document unless another milestone explicitly changes its scope.
