Import a tasks.md into the coco tracker as an epic with dependencies, and create matching issues in the configured issue tracker.

Coco Import Skill

Import a tasks.md into the coco tracker and optionally create matching issues in the configured issue tracker.

When to Use

Importing tasks as part of the coco pipeline
Called by /coco:phase (Step D) or /coco:planning-session tactical
When tasks.md exists in specs/{feature}/ and needs to be loaded into the tracker

Prerequisites: tasks.md must exist. If missing, use the tasks skill first.

Prerequisites

Completed specs/{feature}/tasks.md with sub-phases and dependency info
.coco/config.yaml exists with project configuration

Setup

Read .coco/config.yaml for project.specs_dir and issue_tracker config.
Determine the current feature by:
- Checking the current git branch name
- Strip the feature/ prefix (or whatever pr.branch.feature_prefix is) from the branch name
- Looking for the matching directory in {specs_dir}/{stripped-name}/
- Or from conversation context if a feature was recently discussed
Read {specs_dir}/{feature}/tasks.md (required). If missing, instruct user to use the tasks skill first.
Each tracker command is a separate Bash tool call: coco-tracker <command> [args]

Execution

Step 1: Parse tasks.md

Extract:

Feature name from the # Tasks: header
Sub-Phases -- each ## Sub-Phase N: section becomes a tracker task
Parallel markers -- [P] tasks within a sub-phase
Dependencies -- parse "Dependencies & Execution Order" section

Step 2: Create Tracker Epic

coco-tracker epic-create "{feature-name}"

Step 3: Create Tracker Tasks (one per sub-phase)

IMPORTANT: All coco-tracker create arguments MUST be single-line. Never put literal newlines inside --description, --title, or --metadata values. Use semicolons or commas to separate items within a description. Put each command on one line (no \ continuations).

For each sub-phase:

coco-tracker create --epic "{epic-id}" --title "Sub-Phase {N}: {title}" --description "{single-line summary; task list}" --priority {priority} --metadata '{"sub_phase": N, "issue_key": null, "feature_branch": "{current-branch-name}"}'

If tasks.md includes owns_files annotations (file ownership per sub-phase), include them in metadata:

coco-tracker create --epic "{epic-id}" --title "Sub-Phase {N}: {title}" --description "{single-line summary; task list}" --priority {priority} --metadata '{"sub_phase": N, "issue_key": null, "feature_branch": "{current-branch-name}", "owns_files": ["src/auth/**", "tests/auth/**"]}'

Step 4: Set Dependencies

For each dependency (one Bash tool call per dep-add):

coco-tracker dep-add {phase-1-id} --blocks {phase-2-id}

coco-tracker dep-add {phase-2-id} --blocks {phase-3-id}

Repeat for all user stories blocking Polish, etc.

Step 5: Issue Tracker Bridge

Read .coco/config.yaml issue_tracker.provider:

If "linear":

Create project:

Use: mcp__plugin_linear_linear__create_project
Parameters:
  name: "{feature-name}"
  team: {from config issue_tracker.linear.team}
  summary: "{feature description from design.md}"
  labels: {from config issue_tracker.linear.labels}

Create one issue per sub-phase:

Use: mcp__plugin_linear_linear__create_issue
Parameters:
  title: "Sub-Phase {N}: {title}"
  description: "{purpose}\n\n## Tasks\n- [ ] {task_1}\n- [ ] {task_2}"
  team: {from config issue_tracker.linear.team}
  project: "{project-id from step 1}"
  labels: {from config issue_tracker.linear.labels}

Store issue keys in tracker metadata:

coco-tracker update {task-id} --metadata '{"issue_key": "{ISSUE-KEY}"}'

If "github":

Read issue_tracker.github.use_projects from config (default: true).

If Projects V2 enabled (use_projects: true):

Create a GitHub Project for the feature:

gh project create --owner {github.owner} --title "{feature-name}" --format json

Capture the project number from output.

Link the project to the repository:

gh project link {project_number} --owner {github.owner} --repo {github.repo}

Resolve Status field and option IDs:
```
gh project field-list {project_number} --owner {github.owner} --format json
```
Find the "Status" field. Extract field_id and option IDs for each status value (Todo, In Progress, In Review, Done).

Cache project metadata to .coco/state/gh-projects.json:

{
  "features": {
    "{feature-name}": {
      "project_number": {N},
      "project_id": "PVT_...",
      "status_field_id": "PVTSSF_...",
      "status_options": {
        "Todo": "opt-id-1", "In Progress": "opt-id-2",
        "In Review": "opt-id-3", "Done": "opt-id-4"
      }
    }
  }
}

Ensure .coco/state/ directory exists. If gh-projects.json already exists, merge into the features key.

Create issues and add to project. Run each sub-phase as separate Bash tool calls (no loops).

IMPORTANT gh issue create rules:
- Use --body-file - <<'EOF' for issue bodies (NOT --body "$(cat <<'EOF'...)" which triggers permission prompts)
- Do NOT include --repo — gh detects the repo automatically when run from within it
- --label takes comma-separated values: --label "spec-driven,enhancement". Read label names from issue_tracker.github.labels in config. Do NOT invent labels — only use labels that exist in the repo.
a. Create the issue (capture the URL from output):
```
gh issue create --title "Sub-Phase {N}: {title}" --label "{comma-separated labels from issue_tracker.github.labels in config}" --body-file - <<'EOF'
{description}
EOF
```
b. Add issue to project using the URL printed by gh issue create:
```
gh project item-add {project_number} --owner {github.owner} --url {issue_url from step a}
```
c. Set initial status to "Todo":
```
gh project item-edit --project-id {project_id} --id {item_id} --field-id {status_field_id} --single-select-option-id {status_options["Todo"]}
```
d. Store issue number and project item ID in tracker metadata:
```
coco-tracker update {task-id} --metadata '{"issue_key": "#{N}", "gh_project_item_id": "{item_id}", "gh_project_number": {project_number}}'
```
Repeat steps a-d for each sub-phase. Steps a-d for a single sub-phase depend on each other (run sequentially), but separate sub-phases are independent.

If Projects V2 disabled (use_projects: false):

Create issues using gh (use labels from issue_tracker.github.labels in config):

gh issue create --title "Sub-Phase {N}: {title}" --label "{comma-separated labels from issue_tracker.github.labels in config}" --body-file - <<'EOF'
{description}
EOF

Store issue numbers in tracker metadata:

coco-tracker update {task-id} --metadata '{"issue_key": "#{N}"}'

If "none":

Skip issue creation. Log "Issue tracker bridge skipped."

Step 6: Verify (GATE)

coco-tracker epic-status {epic-id}

coco-tracker list --json --epic {epic-id}

All must pass:

Every tracker task exists with correct dependencies
If issue tracker configured: every task has issue_key in metadata
Dependencies match sub-phase ordering from tasks.md

Step 7: Report

Output:

Epic ID and name
Number of tasks created
Dependency graph summary
Issue tracker project/issues (if applicable)
First available task: coco-tracker ready --json --epic {epic-id}
Suggested next step (explain both options to the user):
- /coco:execute -- Runs one task at a time, pausing after each for you to review. Best when you want to stay hands-on, inspect changes between tasks, or are working on something unfamiliar.
- /coco:loop -- Runs all tasks autonomously in sequence with circuit-breaker protection (stops after repeated failures). Best when you're confident in the design and want to let Claude work through the epic unattended.

Design-Only Mode (Light Tier)

When tasks.md doesn't exist but design.md does (light-tier feature):

Read the design from {specs_dir}/{feature}/design.md (legacy fallback: spec.md)

Create a single-task epic directly from the design:

coco-tracker epic-create "{feature-name}"

coco-tracker create --epic "{epic-id}" --title "{feature-name}: {design overview}" --description "{single-line acceptance criteria}" --metadata '{"issue_key": null, "feature_branch": "{current-branch-name}", "light_tier": true}'

No dependencies to set (single task)
Run issue tracker bridge (Step 5) as normal -- creates one issue
Run verification (Step 6) and report (Step 7) as normal

Design-only mode is triggered by:

/coco:planning-session tactical routing to Light tier
/coco:phase classifying the feature as Light tier
Explicit request when tasks.md is missing and design.md exists

Dry Run Mode

If the conversation context indicates a dry run is desired:

Print what would be created (tasks, deps, issues)
Show dependency graph as ASCII
Ask for confirmation before proceeding

import