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

1. Read .coco/config.yaml for project.specs_dir and issue_tracker config.
2. 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
3. Read {specs_dir}/{feature}/tasks.md (required). If missing, instruct user to use the tasks skill first.
4. Each tracker command is a separate Bash tool call: coco-tracker <command> [args]

Execution

Step 1: Parse tasks.md

Extract:

1. Feature name from the # Tasks: header
2. Sub-Phases -- each ## Sub-Phase N: section becomes a tracker task
3. Parallel markers -- [P] tasks within a sub-phase
4. Dependencies -- parse "Dependencies & Execution Order" section
5. **owns_files**: annotations -- file globs per sub-phase (optional)
6. **test_plan**: annotations -- FR-### IDs and levels per sub-phase (optional; none means "no tests, decided")

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/**"]}'

If tasks.md includes test_plan annotations, include them too. This is the sub-phase's test budget -- the executor reads it to decide which tests to write, and the PR body reports the diff against it:

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/**"], "test_plan": [{"fr": "FR-001", "level": "unit"}, {"fr": "FR-002", "level": "integration"}]}'

For a sub-phase annotated **test_plan**: none, pass "test_plan": [] -- an empty array records "no tests, decided", while an absent key reads as "not yet determined".

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":

1. 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}

2. 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}

3. 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):

1. Create a GitHub Project for the feature:

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

   Capture the project number from output.
2. Link the project to the repository:

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

3. 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).
4. 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.

5. 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):

1. 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

2. 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, and each is verified by querying the tracker -- not by recalling what you did. This checklist previously read as prose and was self-reported against; an import once finished with every task carrying issue_key: null and the checklist passed anyway. The gate one stage later caught it, which is one stage too late.

Run these and read the output:

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

• Every sub-phase in tasks.md appears as a task (compare counts)
• depends_on matches the sub-phase ordering in tasks.md
• If an issue tracker is configured and issue_tracker.per_task_issues is not false: no task has a null issue_key. Check it directly --- coco-tracker list --json --epic {epic-id} | jq '[.[] | select(.metadata.issue_key == null)] | length' must print 0. If it does not, backfill before reporting success.

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):

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

2. 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, "test_strategy": "{single-line TDD verdict and not-worth-testing list}"}'

   Light-tier designs have no FR-### IDs, so there is no test_plan array. Carry the design's ## Test Strategy across as a single-line test_strategy string instead -- there is no tasks.md for the executor to read it from. Collapse it to one line (semicolons between items); never embed a literal newline in --metadata. Code review reads the design and the PR body directly, not task metadata.

Match this heading case-insensitively and tolerate a trailing *(mandatory)*: a design written ## Test strategy is the same section, and treating it as absent silently drops the budget.

If the design has no ## Test Strategy section, omit the key rather than inventing one. 3. No dependencies to set (single task) 4. Run issue tracker bridge (Step 5) as normal -- creates one issue 5. 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:

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