Roadmap

Asana is synced via asana_sync.py (REST API), not via MCP. Check for the script in this priority order:

1. scripts/asana_sync.py in the current repo
2. ~/Github/claude-hub/scripts/asana_sync.py (canonical copy, always present after sync-machines)

Run: python scripts/asana_sync.py --help 2>&1 || python ~/Github/claude-hub/scripts/asana_sync.py --help 2>&1

• Pass (either path): Print Asana: REST script ready (<path>)
• Fail (both missing): Print Asana: DISCONNECTED — asana_sync.py not found in repo or claude-hub. → Ask user whether to continue without Asana sync or abort.

Also verify ASANA_PAT is set: doppler secrets get ASANA_PAT --project claude-code --config prd --plain 2>/dev/null

• If found: use doppler run --project claude-code --config prd -- python <script_path> --json
• If not found: check env var ASANA_PAT directly; if missing, warn and skip Asana sync.

0c: GitHub CLI

Run gh auth status via Bash.

• Pass: Print GitHub: Authenticated as <username>
• Fail: Print GitHub: NOT AUTHENTICATED — git diff will still work but PR operations won't. (non-blocking, continue)

0d: Config File

Read .claude/roadmap.json. Validate all required fields exist.

• Pass: Print Config: Loaded (<linear_project> → <asana_project_name>)
• Fail: Create interactively (ask user for team, project, Asana project name).

Print a summary block:

Pre-flight check:
  Linear:  OK
  Asana:   OK
  GitHub:  OK
  Config:  Loaded
Proceeding with full sync.

If any critical tool (Linear or Asana) is disconnected, stop and resolve before proceeding.

Phase 1: Load Config

1. Already validated in Phase 0. Use the loaded config.
2. If Phase 0 created it interactively, re-read and confirm.

Required config structure:

{
  "linear_team": "<team name>",
  "linear_project": "<project name>",
  "asana_project_name": "<asana project name>",
  "artifact_dirs": ["Docs/", "output/"],
  "artifact_extensions": [".html", ".md", ".txt", ".docx", ".pptx"],
  "priority_labels": {
    "P0": "P0 Critical",
    "P1": "P1 High",
    "P2": "P2 Medium",
    "P3": "P3 Low"
  },
  "sprint_duration_weeks": {
    "Sprint 1": 2,
    "Sprint 2": 4,
    "Sprint 3": 4,
    "Backlog": 8
  }
}

Phase 2: Scan Repo Artifacts

1. Use Glob to find files in the configured artifact_dirs matching artifact_extensions.
2. For each file found:
   • HTML: Extract <title> tag content or first <h1> text as the artifact title.
   • Markdown: Read first # heading as the artifact title.
   • Other (.txt, .docx, .pptx): Use the filename (without extension) as the title.
   • Read the first 5 lines for a brief context summary.
   • Record: {path, title, type, modified_date}
3. Classify artifacts into categories:
   • Plan — filenames starting with Plan_ or containing "plan"
   • Analysis — filenames starting with Analysis_ or containing "analysis", "gap", "research"
   • Reference — filenames containing "SLA", "matrix", "manual", "training", "schema"
   • Report — filenames containing "report", "summary", "review"
   • Other — everything else
4. Print artifact summary: Found X artifacts (Y Plans, Z Analysis, ...)

Phase 3: Fetch Existing Linear Issues

1. Call mcp__linear__list_issues with project: <config.linear_project>, limit: 250.
2. Build a lookup map: {normalized_title -> {id, identifier, title, labels, description}}
   • Normalize: lowercase, strip [P0-1] style prefixes, strip leading/trailing whitespace.
3. Print: Found X existing issues in Linear project "<name>"

Phase 4: Review Current Session Work

1. Run git diff --name-only to see files changed (unstaged + staged).
2. Run git diff --cached --name-only for staged-only changes.
3. Review the conversation context for:
   • Ideas or enhancements discussed
   • Plans created or approved
   • Features requested or designed
   • Problems identified that need solutions
4. Identify new artifacts created this session (new files in artifact_dirs).
5. Identify code written that represents new features (new .py files, new dashboard pages).
6. Build a list of ideas from this session, each with:
   • title: short descriptive name
   • priority: P0/P1/P2/P3 (based on urgency, executive mention, transcript frequency)
   • type: Feature / Improvement / Bug
   • description: what it is and why it matters
   • effort: S/M/L/XL
   • source: where the idea came from (conversation, transcript, code observation)
   • artifacts: list of related artifact file paths from Phase 2
   • deliverables: expected file paths, DB tables, etc.
   • dependencies: what it depends on or blocks

Phase 5: Create/Update Linear Issues

For each idea from Phase 4:

5a: Deduplication Check

1. Normalize the idea title (lowercase, strip prefixes).
2. Compare against the Phase 3 lookup map.
3. Match criteria: >70% word overlap in title OR same core concept.

5b: If Duplicate Found → Merge

1. Use mcp__linear__save_issue with the existing issue id to update:
   • Append to the description with a section:

     ---
     ### Update from Terminal Session (YYYY-MM-DD)
     **Source:** <where this came from>
     **Additional context:** <new information>
     **New artifacts linked:**
     - [artifact_title](artifact_path)
     

2. Report as: Merged into IVA-XXX (existing: "<title>")

5c: If New → Create

1. Call mcp__linear__save_issue with:
   • team: from config
   • project: from config
   • title: [P#] <Short descriptive title>
   • labels: ["<priority_label>", "<type_label>"]
     • Priority labels: P0 Critical, P1 High, P2 Medium, P3 Low (from config)
     • Type labels: Feature, Improvement, Bug (these must already exist in Linear)
   • priority: 1 (P0 Urgent), 2 (P1 High), 3 (P2 Normal), 4 (P3 Low)
   • description: Use this template:

     ## <Title>
     
     **Source:** <where this idea came from>
     **Effort:** S (1 session) | M (2-3 sessions) | L (4-5 sessions) | XL (6+ sessions)
     **Terminal:** <terminal identifier or session description>
     
     ### What
     <1-3 sentences describing the enhancement and why it matters>
     
     ### Builds On
     <List existing pages, pipelines, or components this leverages. "None (greenfield)" if new.>
     
     ### Deliverables
     - <file paths, DB tables, new pages>
     
     ### Dependencies
     - Depends on: <other enhancements or infrastructure needed first>
     - Blocks: <what can't start until this is done>
     
     ### Linked Artifacts
     - [<artifact_title>](<relative_path>) — <brief description>
     

2. If dependencies reference other issues, use blocks or relatedTo params.
3. Report as: Created IVA-XXX: "<title>"

5d: Never Silently Skip

• Every idea MUST result in either a "Created" or "Merged into" action.
• Print a summary table after all issues are processed:

| Action | Issue | Title |
|--------|-------|-------|
| Created | IVA-XXX | [P1] New Enhancement |
| Merged into | IVA-YYY | [P0-3] Existing Enhancement |
| Created | IVA-ZZZ | [P2] Another Idea |

Phase 6: Asana Sync

Always execute this phase. Asana is synced exclusively via asana_sync.py (REST API). Do NOT use Asana MCP tools.

Locate the script

Use whichever path exists (check in this order):

1. scripts/asana_sync.py (current repo)
2. ~/Github/claude-hub/scripts/asana_sync.py (canonical, always present)

Run command: doppler run --project claude-code --config prd -- python <script_path> --json <file.json>

6a: Build the Project Structure JSON

1. Gather all Linear issues (Phase 3 list + newly created in Phase 5).
2. Group into sections by priority:
   • Sprint 1 (P0 Critical) — all P0-labeled issues
   • Sprint 2 (P1 High) — all P1-labeled issues
   • Sprint 3 (P2 Medium) — all P2-labeled issues
   • Backlog (P3 Low) — all P3-labeled issues
3. Calculate sprint date ranges from today:

   Sprint 1: today → today + sprint_duration_weeks["Sprint 1"] weeks
   Sprint 2: Sprint 1 end + 1 day → + sprint_duration_weeks["Sprint 2"] weeks
   Sprint 3: Sprint 2 end + 1 day → + sprint_duration_weeks["Sprint 3"] weeks
   Backlog:  Sprint 3 end + 1 day → + sprint_duration_weeks["Backlog"] weeks
   

4. Within each sprint, stagger task dates sequentially by effort:
   • S: 3-day window M: 7-day L: 14-day XL: 21-day
5. Map priorities: P0/P1 → "high", P2 → "medium", P3 → "low".
6. Build JSON matching the asana_sync.py schema:

   {
     "project_name": "<config.asana_project_name>",
     "sections": [
       {
         "name": "Sprint 1 — P0 Critical",
         "tasks": [
           {
             "name": "[P0] <title>",
             "description": "<Linear issue description>",
             "start_date": "YYYY-MM-DD",
             "due_date": "YYYY-MM-DD",
             "assignee": "me",
             "priority": "high"
           }
         ]
       }
     ]
   }
   

7. Write JSON to a temp file (e.g., /tmp/asana_sync_<timestamp>.json).

6b: Run the Sync

doppler run --project claude-code --config prd -- python <script_path> --json /tmp/asana_sync_<timestamp>.json

The script handles create-or-update idempotently — safe to re-run. It will:

• Create the project if it doesn't exist
• Create sections that don't exist
• Create tasks that don't exist
• Update tasks that already exist (by name match)
• Report created/updated counts and project URL

6c: Report Asana Results

Parse stdout from the script for the summary line and project URL. Print:

Asana Sync Complete:
  Project: "<name>"
  Created: X tasks
  Updated: Y tasks
  URL: https://app.asana.com/0/<project_gid>

6d: Report Asana Results

Asana Sync Complete:
  Project: "<name>" (GID: <gid>)
  Updated: X tasks
  Created: Y tasks
  Unchanged: Z tasks
  Orphaned: W tasks (no Linear match)
  URL: <project_url>

Phase 7: Final Report

Print a complete summary to the screen:

## Roadmap Sync Complete

### Linear
| Action | Count |
|--------|-------|
| Issues Created | X |
| Issues Updated (Merged) | Y |
| Total in Project | Z |

### Artifacts
| Type | Count |
|------|-------|
| Plans | X |
| Analysis | Y |
| Reference | Z |
| Reports | W |
| Total Linked | N |

### Asana
| Action | Count |
|--------|-------|
| Tasks Updated | X |
| Tasks Created | Y |
| Tasks Unchanged | Z |
| Orphaned | W |
| Project URL | <url> |

Phase 8: Ask For Confirmation Before Merging

Before committing and merging, ask the user to review the roadmap changes:

Print a summary block:

========================================
ROADMAP SYNC COMPLETE — READY TO COMMIT?
========================================

Linear Issues:
  Created: X
  Merged: Y
  Total in project: Z

Asana Tasks:
  Created: X
  Updated: Y
  Project URL: <url>

Artifacts Linked: X files

Files to Commit:
  - WorkDoneSummary.md
  - Any new artifacts in docs/output/
  - Any .claude/roadmap.json updates

Ready to:
  1. Commit changes
  2. Create PR
  3. Wait for CI
  4. Merge to main
  5. Return to main & pull latest

Proceed? (y/n)

Wait for user input. If user types anything other than y or yes:

• Print: Commit cancelled. Changes are still staged. You can review and commit manually later.
• Exit the skill without committing
• STOP HERE

If user confirms (y/yes):

• Proceed to Phase 9

Phase 9: Ship Operations (Commit → Push → PR → Merge)

Only execute if user confirmed in Phase 8.

9a: Stage Files

git add WorkDoneSummary.md
git add .claude/roadmap.json (if it was created/updated)
git add docs/ (if new artifacts exist)

9b: Commit

git commit -m "$(cat <<'EOF'