Skip to main content

organize

Retroactively group existing issues into tracker-native projects. Use when the user says "organize issues", "group issues into projects", or wants to create project boards for existing sprint issues.

Governing Artifacts​

ADR-0015 · ADR-0016 · ADR-0026 · SPEC-0014 · SPEC-0019

Usage​

/sdd:organize [SPEC-XXXX or spec-name] [--project <name>] [--dry-run] [--module <name>]
Required Tools
  • Read
  • Glob
  • Grep
  • Bash
  • Write
  • Edit
  • ToolSearch
  • AskUserQuestion

Overview​

Harness portability. This skill runs on any agent harness that loads Agent Skills — Claude Code, Codex CLI, OpenCode, Crush. Tool names used below (AskUserQuestion, Task, TeamCreate, SendMessage, TaskCreate, ToolSearch, mcp__*, $\{CLAUDE_PLUGIN_ROOT\}) denote capabilities, not hard requirements: map each to your harness's equivalent or use the documented fallback per $\{CLAUDE_PLUGIN_ROOT\}/references/harness-compat.md. References to CLAUDE.md mean the project memory file (CLAUDE.md, AGENTS.md, or CRUSH.md) per harness-compat § "Project Memory File". A citation of the form shared-patterns.md § "Section" names one ## heading in that file — load only that section (see its "How to Read This File" note), never the whole file. Invocation and arguments. Where your harness has no command layer (Crush, Codex CLI, OpenCode) this skill is reached from its description, not a slash command: the /sdd:\{name\} form below is Claude Code namespacing. $ARGUMENTS means whatever arrived with the invocation: take the target and any --flags from the request that triggered this skill, and when neither is present follow this skill's documented no-argument path instead of reporting missing arguments (harness-compat § "Invocation and Arguments").

You are retroactively grouping existing tracker issues into tracker-native projects and enriching project workspaces. You use a three-tier intervention model that lets the operator control how invasive the changes are. See 📝 ADR-0012 and SPEC-0011.

Process​

<!-- Governing: ADR-0016 (Workspace Mode), SPEC-0014 REQ "Artifact Path Resolution" -->

  1. Resolve artifact paths: Follow the Artifact Path Resolution pattern from $\{CLAUDE_PLUGIN_ROOT\}/references/shared-patterns.md § "Artifact Path Resolution" to determine the spec directory. If $ARGUMENTS contains --module &lt;name>, resolve paths relative to that module. The resolved spec directory is \{spec-dir\}.

  2. Parse arguments: Extract from $ARGUMENTS:

    • Spec identifier: a SPEC number (e.g., SPEC-0007) or capability directory name
    • --project &lt;name>: Use a single combined project with this name for all issues. Default: per-epic.
    • --dry-run: Preview what would be created without making changes. Default: off.
    • --module &lt;name>: Resolve artifact paths relative to the named module. Default: none.

    If no spec identifier is provided, list available specs by globbing \{spec-dir\}/*/spec.md, read the title from each, and use AskUserQuestion to ask which spec to organize.

  3. Resolve spec: Follow the plugin's $\{CLAUDE_PLUGIN_ROOT\}/references/shared-patterns.md § "Spec Resolution" (which uses \{spec-dir\} from the Artifact Path Resolution pattern).

  4. Read spec: Read \{spec-dir\}/\{capability-name\}/spec.md and design.md to understand the spec number, requirement names, and architecture. Validate spec pairing per $\{CLAUDE_PLUGIN_ROOT\}/references/shared-patterns.md § "Spec Pairing Validation".

  5. Detect tracker: Follow the "Config Resolution" and "Tracker Detection" flows in the plugin's $\{CLAUDE_PLUGIN_ROOT\}/references/shared-patterns.md § "Config Resolution" and § "Tracker Detection". Also read Projects settings from the ### SDD Configuration section in CLAUDE.md for cached project IDs and enrichment config (Views, Columns, Iteration Weeks). If no tracker is found, error — projects require a tracker.

  6. Find existing issues: Search the tracker for issues whose body references the spec number.

    • GitHub: gh issue list --search "SPEC-XXXX" --json number,title,body,labels --limit 100
    • Gitea: tea api --login \{login\} 'repos/\{owner\}/\{repo\}/issues?q=SPEC-XXXX&type=issues&state=all&limit=50' (see $\{CLAUDE_PLUGIN_ROOT\}/references/shared-patterns.md § "Gitea Access")
    • GitLab: Use MCP tools or glab issue list --search "SPEC-XXXX"
    • Jira: Use MCP tools to search issues with JQL containing the spec number
    • Linear: Use MCP tools to search issues containing the spec number
    • Beads: No-op — Beads epics ARE the grouping, so inform the user and exit

  7. Identify epics vs stories: Classify each found issue:

    • Epics: Issues with titles starting with "Implement " or that have an epic label
    • Stories: All other issues referencing the spec

  8. Assess project state (Governing: SPEC-0011 REQ "Organize Three-Tier Intervention"):

    For each project (existing or to-be-created), assess its current state:

    • Does the project exist? Is it linked to the repository?
    • Does it have a description? A README?
    • Does it have named views (GitHub: All Work, Board, Roadmap)?
    • Does it have an iteration/Sprint field (GitHub)?
    • Does it have board columns (Gitea: Todo, In Progress, In Review, Done)?
    • Does it have milestones for epics (Gitea)?
    • Are native dependency links set (Gitea)?
    • Are all issues correctly grouped and labeled? Does each carry exactly one size/* label (per $\{CLAUDE_PLUGIN_ROOT\}/references/shared-patterns.md § "Size Labels")?
    • Are ### Branch and ### PR Convention sections present in issue bodies?

    Present findings to the operator and offer three intervention tiers via AskUserQuestion:

    (a) Leave as-is: Report the current state and exit. No changes made.

    (b) Restructure workspace only: Add/fix project-level structure without touching any issues:

    • Create project if missing, link to repository
    • Add/update project description and README
    • Create/rename named views (GitHub)
    • Add iteration field (GitHub)
    • Create board columns (Gitea)
    • Create milestones (Gitea)
    • Add all issues to the project (if not already)

    (c) Complete refactor: All tier (b) changes PLUS:

    • Re-group issues across epics (move misplaced stories)
    • Fix/add labels using the try-then-create pattern (see $\{CLAUDE_PLUGIN_ROOT\}/references/shared-patterns.md § "Try-Then-Create Label Pattern")
    • Give every issue exactly one size/* label per $\{CLAUDE_PLUGIN_ROOT\}/references/shared-patterns.md § "Size Labels" — add a missing one, collapse duplicates, and never re-size an issue that already has exactly one
    • Create native dependency links (Gitea)
    • Update issue bodies with ### Branch and ### PR Convention sections (if missing)

  9. Execute chosen tier: Carry out the selected intervention. All enrichment steps use graceful degradation: if a feature is unavailable for the tracker, skip and log "Skipped {step}: {tracker} does not support {feature}".

    GitHub workspace enrichment (tier b/c):

    • Set project description referencing the spec
    • Write project README via GraphQL (agent-navigable context with spec refs, ADR links, story index, dependencies)
    • Create "Sprint" iteration field via GraphQL with cycle length from CLAUDE.md Projects > Iteration Weeks (default: 2 weeks)
    • Create named views via GraphQL using CLAUDE.md Projects > Views (default: "All Work" table, "Board" board, "Roadmap" roadmap)

    Gitea workspace enrichment (tier b/c), all through tea (see $\{CLAUDE_PLUGIN_ROOT\}/references/shared-patterns.md § "Gitea Access"):

    • Create milestones (one per epic) with tea milestones create, assign stories with tea issues edit --milestone
    • Configure board columns from CLAUDE.md Projects > Columns (default: Todo, In Progress, In Review, Done)

    Tier (c) additional steps:

    • Re-label issues using the try-then-create pattern (see $\{CLAUDE_PLUGIN_ROOT\}/references/shared-patterns.md § "Try-Then-Create Label Pattern")
    • Create Gitea native dependency links (tea api -X POST repos/\{owner\}/\{repo\}/issues/\{index\}/dependencies)
    • Add ### Branch / ### PR Convention to issue bodies that lack them (same logic as /sdd:enrich)

  10. --dry-run mode: If --dry-run is set, report the assessment and what WOULD be done at each tier, but don't modify anything.

  11. Report results: Provide a summary:

    • Tier selected and actions taken
    • Number of projects created, enriched, or reused
    • Number of issues organized/updated
    • Skipped enrichments (graceful degradation)
    • Any failures encountered (with issue numbers)
    • Whether CLAUDE.md Projects section was updated with project IDs

Step 0a: Tier 4 issues sync (v5.0.0+)​

<!-- Governing: ADR-0026 (Tiered Index Freshness), SPEC-0019 REQ "Tier 4 Always-Sync Issues for Sprint Skills" -->

Before discovering existing issues (Step 5), sync the \{repo\}-issues qmd collection from the tracker so the local cache reflects current issue state. This is Tier 4 of the freshness model: always sync at consumer entry, subject to a 5-minute deduplication window.

  1. Read .sdd/issues/_meta.json (per $\{CLAUDE_PLUGIN_ROOT\}/references/tracker-sync.md § "Cursor Management"). If last_sync is within the last 5 minutes, skip the sync and proceed silently.
  2. Otherwise, invoke the per-tracker fetch+normalize per $\{CLAUDE_PLUGIN_ROOT\}/references/tracker-sync.md with the cursor for incremental fetch. Print: "Syncing N issues from {tracker}…".
  3. On sync failure, surface a one-line warning per $\{CLAUDE_PLUGIN_ROOT\}/references/tracker-sync.md § "Failure Modes and Degradation" and proceed with live tracker queries (the pre-v5 path) for this run. Do NOT block; organize is the user's primary intent.

Step 12: Tier 1 mutation update (v5.0.0+)​

<!-- Governing: ADR-0026 (Tiered Index Freshness), SPEC-0019 REQ "Tier 1 Mutation-Aware Updates" -->

After tier (c) interventions modify issue bodies (labels, project links surfaced in body, etc.), trigger a narrow re-sync of \{repo\}-issues so the qmd index reflects the changes. Use the canonical update pattern from $\{CLAUDE_PLUGIN_ROOT\}/references/qmd-helpers.md § "Update Patterns".

  1. Re-fetch the modified issues via per-tracker fetch+normalize (only those touched in tier (c)).
  2. Run qmd update.
  3. Best-effort and silent on success. On failure, append a one-line warning ("Index refresh failed for \{repo\}-issues — run /sdd:index update manually") and report the organize step itself as successful.

If tier (a) (report-only) or tier (b) (project-level only, no issue-content changes) was selected, skip Step 12 — there's nothing to re-index for \{repo\}-issues.

Rules​

  • Tier (a) MUST NOT modify anything — report only
  • Tier (b) MUST NOT modify issue content — only project-level structure (views, README, columns, iterations, milestones)
  • Tier (c) MAY modify issue content (labels, body sections, grouping)
  • MUST present the three-tier choice to the operator before making changes (Governing: SPEC-0011 REQ "Organize Three-Tier Intervention")
  • MUST skip projects that already exist (idempotent)
  • MUST probe for project tools at runtime where the harness can (ToolSearch); where it cannot, assume them absent and take the documented CLI path (harness-compat § Capability Map)
  • Failures MUST be reported but MUST NOT stop processing remaining issues
  • MUST follow the Config Resolution pattern from $\{CLAUDE_PLUGIN_ROOT\}/references/shared-patterns.md § "Config Resolution" to read configuration from CLAUDE.md
  • MUST check CLAUDE.md Projects for cached project IDs before creating
  • When writing config to CLAUDE.md, preserve existing keys
  • MUST link created projects to the repository for trackers that support project-repository associations (e.g., GitHub Projects V2 via gh project link, Gitea)
  • MUST use the try-then-create pattern (see $\{CLAUDE_PLUGIN_ROOT\}/references/shared-patterns.md § "Try-Then-Create Label Pattern") for all label applications in tier (c) (Governing: SPEC-0011 REQ "Auto-Create Labels")
  • Tier (c) MUST leave every issue it touches with exactly one size/* label per $\{CLAUDE_PLUGIN_ROOT\}/references/shared-patterns.md § "Size Labels", unless #### Sizing > Enabled is false
  • MUST degrade gracefully when tracker features are unavailable — skip and report, never fail (Governing: SPEC-0011 REQ "Graceful Degradation")
  • No --review support (utility skill)
  • v5.0.0+: MUST trigger Tier 4 issues sync on entry per Step 0a — sync from tracker before discovering issues, subject to 5-min dedup. On failure, fall back to live queries with a warning (Governing: 📝 ADR-0026, SPEC-0019 REQ "Tier 4 Always-Sync Issues for Sprint Skills")
  • v5.0.0+: MUST trigger Tier 1 update of \{repo\}-issues after tier (c) interventions per Step 12 — best-effort, silent on success (Governing: 📝 ADR-0026, SPEC-0019 REQ "Tier 1 Mutation-Aware Updates")

Config Reference​

This skill reads and writes the Projects subsection of the ### SDD Configuration section in CLAUDE.md. See the plugin's $\{CLAUDE_PLUGIN_ROOT\}/references/shared-patterns.md § "Config Resolution" for the canonical format and defaults. All keys are optional with sensible defaults. When writing, merge — do not overwrite.

Example Invocations​

organize our existing GitHub issues into a project board
/sdd:organize
retroactively group these issues into tracker projects by spec
we have 50 stale issues; group them under the right epics
set up a Gitea project board for the open issues from SPEC-0017