KollectTools
/
MCP-OpenProject
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
MCP-OpenProject/.claude/commands/speckit.updateOP.md

9.2 KiB
Raw Blame History

description
Sync OpenProject work packages with current feature specs and tasks — creates milestones, phases, and child tasks as needed.

User Input

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

Outline

  1. Setup:

    • Resolve remote URL: Run git remote get-url origin to get the remote URL. All commit references in this skill MUST use <remote-url>/commit/<hash> format. Never use bare hashes.
    • Run .specify/scripts/powershell/check-prerequisites.ps1 -Json from repo root and parse FEATURE_DIR, BRANCH, and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'''m Groot' (or double-quote if possible: "I'm Groot").
    • If the script fails (no feature branch, no specs directory, or prerequisites not met): proceed to step 2a (ad-hoc mode).

  2. Determine development stage: Check which design artifacts exist in FEATURE_DIR:

    • spec.md exists → at least "specify" stage
    • plan.md exists → at least "plan" stage
    • tasks.md exists → at least "tasks" stage
    • Tasks with [X] checkboxes → "implement" stage (in progress)
    • No artifacts at all → "none" stage (proceed to step 2a)

    2a. Ad-hoc mode (no SpecKit artifacts available):

    • This handles cases where:
      • The branch is not a SpecKit feature branch (e.g., main, fix/something, hotfix/urgent)
      • No specs/ directory exists for this branch
      • The user wants to log work to an existing WP without full SpecKit setup
    • Ask the user: "No SpecKit feature detected for this branch. Which OpenProject work package should I update?"
    • Accept one of:
      • A WP ID (e.g., #10423 or 10423)
      • A search term to find the WP (use mcp__openproject__list_work_packages with project ID 229 and present matching results)
      • "new" to create a new work package
      • "skip" to abort the OP update
    • If the user provides a WP ID or selects from search results:
      • Get the commits to be logged: git log --oneline origin/HEAD..HEAD (or from user input)
      • Add a comment to the selected WP with commit links (<remote-url>/commit/<hash>) and summary
      • Report what was logged and skip steps 3–8
    • If the user says "new" or no search results match:
      • Ask for a subject (suggest one based on the branch name or recent commit messages)
      • Ask for a type (Task, Feature, Bug, etc.) — list available types via mcp__openproject__list_types if needed
      • Optionally ask for description, priority, and assignee
      • Create the WP via mcp__openproject__create_work_package with project ID 229
      • Then log commits to the newly created WP (same as WP ID flow above)
      • Report the new WP ID and what was logged, skip steps 3–8
    • If the user says "skip": abort and return without error

  3. Load context:

    • Read spec.md to extract feature title and user stories
    • If tasks.md exists: Read it to extract phases, task counts, OP WP IDs (from — OP #NNNNN in phase headers), and task details
    • Read CLAUDE.md for the OpenProject Work Package IDs table and existing mappings

  4. Find or create the Milestone work package:

    • Extract the feature number and name from the branch name (e.g., 001-ai-etl-platform)
    • Search OpenProject for an existing Milestone WP matching this feature:
      • Use mcp__openproject__list_work_packages with project ID 229 and filter by type "Milestone"
      • Look for a WP whose subject contains the feature number or name
    • If found: Display the milestone WP (ID, subject, status) and confirm with user
    • If NOT found: Offer to create one:
      • Propose title: {feature-number} - {Feature Name from spec.md} (e.g., "001 - Core ETL + Visual Designer (V1)")
      • Propose description from spec.md summary
      • Ask user for confirmation before creating via mcp__openproject__create_work_package
    • Store the milestone WP ID for subsequent steps

  5. Stage: "tasks" — Sync Phases as Work Packages:

    • Skip this step if tasks.md does not exist
    • Parse all phase headers from tasks.md: ## Phase N: Description — OP #NNNNN
    • For each phase:
      • If OP WP ID is present in the header: Verify the WP exists via mcp__openproject__get_work_package
        • If it exists: Compare the subject and update if the description has changed (use mcp__openproject__update_work_package)
        • If it does NOT exist (stale ID): Flag it and offer to create a new WP
      • If NO OP WP ID in the header: Create a new Phase WP:
        • Type: "Phase" (or "Task" if Phase type unavailable — check mcp__openproject__list_types first)
        • Subject: Phase N: Description (e.g., "Phase 3: US-1 — Manage Users and Roles")
        • Description: Include the phase purpose, task count, checkpoint criteria, and user story goal
        • After creation, update the tasks.md phase header to include — OP #NewID
    • Create milestone relations: For each phase WP, create a requires relation from the phase to the milestone (if not already linked):
      • Use mcp__openproject__list_relations on the phase WP to check existing relations
      • If no requires relation to the milestone exists, create one via mcp__openproject__create_relation
    • Create inter-phase dependencies: Parse the dependency graph from tasks.md (look for "Depends on: Phase N" notes and the dependency graph section):
      • For each dependency, create a follows relation (phase X follows phase Y)
      • Check existing relations first to avoid duplicates
    • Report summary: phases found, created, updated, relations created

  6. Stage: "implement" — Sync Tasks as Child Work Packages:

    • Skip this step if NOT in "implement" stage (no [X] tasks) unless the user explicitly requests task sync
    • For each phase in tasks.md:
      • Get the phase WP ID from the header
      • Use mcp__openproject__list_work_packages to find existing child WPs under this phase (filter by parent if supported, or list all project WPs and filter by subject prefix)
      • Parse all tasks in the phase: - [ ] T### [P?] [US?] Description
      • For each task:
        • If a matching child WP exists (match by task ID in subject, e.g., "T042"):
          • Compare status: if task is [X] in tasks.md but WP is not closed → update WP status
          • Compare subject: if description changed → update WP subject
        • If NO matching child WP exists: Create one:
          • Type: "Task"
          • Subject: T### — Description (e.g., "T042 — Implement refresh token denylist in backend/etl/.../TokenDenylistService.java")
          • Set parent to the phase WP ID (use direct API PATCH with _links.parent.href since MCP update_work_package does not support parent — see CLAUDE.md constraints)
        • Batch creation: Process tasks in batches to avoid rate limiting. Create up to 10 WPs at a time, then pause briefly.
    • Update task completion status:
      • For tasks marked [X] in tasks.md: Update the corresponding WP status to "Closed" (or appropriate status)
      • For tasks marked [ ]: Ensure WP is in "New" or "In progress" status
    • Report summary: tasks found, created, updated, status synced

  7. Update CLAUDE.md (if new WP IDs were created):

    • Update the OpenProject Work Package IDs table in CLAUDE.md with any new phase WP IDs
    • Update task counts if they changed
    • Add any new relation IDs

  8. Update tasks.md (if new phase WP IDs were assigned):

    • Update phase headers with newly assigned OP WP IDs: ## Phase N: Description — OP #NewID

  9. Report: Output a summary table:

    | Action       | Count | Details                          |
|--------------|-------|----------------------------------|
| Milestone    | 1     | #XXXXX (found/created)           |
| Phases       | N     | M created, K updated, J existing |
| Tasks        | N     | M created, K updated             |
| Relations    | N     | M requires, K follows            |
| Files Updated| N     | tasks.md, CLAUDE.md              |
    • List any errors or items that need manual attention
    • Suggest next steps (e.g., "Run /speckit.implement to start implementation")

Operating Rules

  1. Never delete work packages — only create or update. If a WP seems orphaned, flag it for manual review.
  2. Always check before creating — search for existing WPs before creating new ones to avoid duplicates.
  3. Preserve existing OP WP IDs — if a phase header already has an OP ID, trust it unless the WP doesn't exist.
  4. Respect MCP limitations:
    • Relations are CRD only (no update) — to change a relation type, delete and recreate
    • Parent-child cannot be set via update_work_package — use direct API PATCH with _links.parent.href
    • Milestones cannot have children — use requires relations instead
  5. Batch operations — when creating many WPs, process in batches of 10 to avoid overwhelming the API.
  6. Confirm destructive-ish actions — ask user before bulk-creating WPs (e.g., "About to create 23 phase WPs. Proceed?").
  7. Log activity — after creating or updating WPs, add a comment with context (e.g., "Synced from tasks.md phase header").