publish

Publish Seed specification as GitHub Issues for team-based project management

Quality

63%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.claude-plugin/skills/publish/SKILL.md

/ouroboros:publish

Convert a Seed specification into structured GitHub Issues for team workflows.

Usage

ooo publish [seed_path]
/ouroboros:publish [seed_path]

Trigger keywords: "publish to github", "create issues from seed", "seed to issues"

Instructions

When the user invokes this skill:

Step 1: Prerequisite Check

1a. Verify gh CLI is installed:

command -v gh >/dev/null 2>&1 && echo "OK" || echo "MISSING"

If missing, tell the user:

GitHub CLI (gh) is not installed.
Install it: https://cli.github.com/

Stop.

1b. Verify gh is authenticated:

gh auth status

If not authenticated, tell the user:

GitHub CLI is not authenticated. Run: gh auth login

Stop.

Step 2: Locate the Seed

Ouroboros stores seeds in ~/.ouroboros/seeds/:

Interview seeds: ~/.ouroboros/seeds/{seed_id}.yaml (YAML)
PM seeds: ~/.ouroboros/seeds/pm_seed_{id}.json (JSON)

Determine the Seed source in this priority order:

Explicit path argument: If the user provided a file path (.yaml or .json), read it directly
Most recent seed file: Search for the most recent seed in the standard location:
```
ls -t ~/.ouroboros/seeds/*.yaml ~/.ouroboros/seeds/*.json 2>/dev/null | head -5
```
If multiple seeds exist, present the top candidates via AskUserQuestion and let the user choose.
Conversation context: If ooo seed or ooo pm was just run in this conversation and the seed path was reported, use that path.

If no seed is found:

No Seed found. Run `ooo seed` or `ooo pm` first to generate a specification.

Stop.

Step 3: Parse the Seed

Detect the file format by extension and parse accordingly:

For YAML seeds (from ooo interview + ooo seed): Read the YAML file and extract:

goal → Epic title and description
constraints → Listed in Epic body
acceptance_criteria → Checklist items in Epic + distributed to Task issues
ontology_schema → Documentation section in Epic
evaluation_principles → Quality criteria reference
exit_conditions → Definition of Done
metadata.ambiguity_score → Confidence indicator
metadata.seed_id → Used for duplicate detection

For JSON seeds (from ooo pm): Read the JSON file and extract fields using the actual PMSeed schema:

PMSeed field	Maps to
`pm_id`	Seed identifier (for duplicate detection)
`product_name`	Epic title prefix
`goal`	Epic Goal section
`constraints`	Epic Constraints section (array of strings)
`success_criteria`	Acceptance Criteria checklist (array of strings)
`user_stories`	User Stories section (array of `{persona, action, benefit}`)
`deferred_items`	Deferred Items section (array of strings)
`decide_later_items`	Open Questions section (array of strings)
`assumptions`	Assumptions section (array of strings)

Format user stories as: "As a {persona}, I want to {action}, so that {benefit}."

If any field is missing or empty, omit that section from the Epic body rather than failing.

Step 4: Detect Repository

4a. Attempt auto-detection from current directory:

gh repo view --json nameWithOwner -q '.nameWithOwner' 2>/dev/null

4b. Present the target repo choice via AskUserQuestion:

If auto-detection succeeded:

{
  "questions": [{
    "question": "Publish Seed as GitHub Issues to this repository?",
    "header": "Target Repository",
    "options": [
      {"label": "<detected_repo>", "description": "Use current repository"},
      {"label": "Other", "description": "I'll specify a different owner/repo"}
    ],
    "multiSelect": false
  }]
}

If auto-detection failed (not in a git repo):

{
  "questions": [{
    "question": "Which GitHub repository should the issues be created in? (format: owner/repo)",
    "header": "Target Repository"
  }]
}

If the user chose "Other", ask:

{
  "questions": [{
    "question": "Enter the target repository (format: owner/repo):",
    "header": "Target Repository"
  }]
}

Store the resolved repository as TARGET_REPO. All subsequent gh commands MUST include -R <TARGET_REPO> to ensure they target the correct repository.

Step 5: Duplicate Check

Before creating issues, check if this seed was already published:

gh issue list -R <TARGET_REPO> --label "ouroboros" --state all --search "<seed_id or pm_id>" --limit 5 --json number,title,state

The search uses the seed's unique identifier (metadata.seed_id for YAML seeds, pm_id for JSON seeds). This works because Step 7 persists the identifier in the Epic body (see the Seed ID field in the Epic template).

If matching issues are found, warn the user via AskUserQuestion:

{
  "questions": [{
    "question": "Found existing Ouroboros issues that may be from the same seed:\n\n<list of matching issues>\n\nCreate new issues anyway?",
    "header": "Duplicate Warning",
    "options": [
      {"label": "Create anyway", "description": "Proceed with new issues"},
      {"label": "Cancel", "description": "Do not create duplicate issues"}
    ],
    "multiSelect": false
  }]
}

If "Cancel": Stop.

Step 6: Plan Issue Structure

Before creating issues, present the planned structure to the user for review.

6a. Break down acceptance criteria into Task groups:

Analyze the acceptance criteria and group them into logical implementation units. Each unit becomes a Task issue. Use your understanding of the domain to create meaningful groupings (e.g., group by feature area, layer, or dependency order).

6b. Present the plan via AskUserQuestion:

{
  "questions": [{
    "question": "Here's the planned issue structure:\n\n**Epic**: <goal summary>\n\n**Tasks**:\n1. <task_1_title> — <brief scope>\n2. <task_2_title> — <brief scope>\n3. <task_3_title> — <brief scope>\n\nProceed with creating these issues?",
    "header": "Issue Plan",
    "options": [
      {"label": "Create issues", "description": "Publish to GitHub now"},
      {"label": "Modify plan", "description": "I want to adjust the structure first"}
    ],
    "multiSelect": false
  }]
}

If "Modify plan": Ask what to change, adjust, and re-present.

Step 7: Create GitHub Issues

IMPORTANT: Every gh command in this step MUST include -R <TARGET_REPO>.

Issue number extraction: gh issue create outputs a URL like https://github.com/owner/repo/issues/42. Extract the issue number by parsing the trailing digits:

EPIC_URL=$(gh issue create -R <TARGET_REPO> --title "..." --label "..." --body "...")
EPIC_NUM=$(echo "$EPIC_URL" | grep -o '[0-9]*$')

Apply the same extraction pattern for every Task issue created.

7a. Create labels (if they don't exist):

gh label create "ouroboros" -R <TARGET_REPO> --description "Created by Ouroboros publish" --color "6f42c1" 2>/dev/null || true
gh label create "epic" -R <TARGET_REPO> --description "Epic / parent issue" --color "0075ca" 2>/dev/null || true
gh label create "task" -R <TARGET_REPO> --description "Implementation task" --color "008672" 2>/dev/null || true

7b. Create the Epic issue:

gh issue create -R <TARGET_REPO> \
  --title "[Epic] <goal_summary>" \
  --label "ouroboros,epic" \
  --body "$(cat <<'BODY'
## Goal

<goal from seed>

## Constraints

<constraints as bullet list>

## Acceptance Criteria

- [ ] <criterion_1>
- [ ] <criterion_2>
- ...

## Ontology

| Field | Type | Description |
|-------|------|-------------|
| <field_name> | <type> | <description> |

## Evaluation Principles

| Principle | Weight | Description |
|-----------|--------|-------------|
| <name> | <weight> | <description> |

## Exit Conditions

<exit conditions as bullet list>

---

**Seed ID**: `<seed_id or pm_id>` | **Ambiguity Score**: <score> | **Seed**: `<seed_file_path>`
*Generated by [Ouroboros](https://github.com/Q00/ouroboros) via `ooo publish`*
BODY
)"

Capture the Epic issue number from the output.

7c. Create Task issues (one per implementation unit):

For each task:

gh issue create -R <TARGET_REPO> \
  --title "[Task] <task_title>" \
  --label "ouroboros,task" \
  --body "$(cat <<'BODY'
Parent: #<epic_number>

## Scope

<what this task covers>

## Acceptance Criteria

- [ ] <specific_criterion_1>
- [ ] <specific_criterion_2>

## Test Checklist

- [ ] <test_1>
- [ ] <test_2>
- [ ] <test_3>

## Pass Criteria

<measurable conditions for this task to be considered done>

---

*Part of [Epic] #<epic_number> | Generated by [Ouroboros](https://github.com/Q00/ouroboros) via `ooo publish`*
BODY
)"

7d. Update Epic with task links:

After all tasks are created, add a comment to the Epic:

gh issue comment <epic_number> -R <TARGET_REPO> --body "$(cat <<'BODY'
## Implementation Tasks

- [ ] #<task_1_number> — <task_1_title>
- [ ] #<task_2_number> — <task_2_title>
- [ ] #<task_3_number> — <task_3_title>

Track overall progress by checking off tasks as their issues are closed.
BODY
)"

Step 8: Summary

Present the results:

Published to <TARGET_REPO>:

  #<epic>  [Epic] <goal_summary>
    ├── #<task_1>  [Task] <task_1_title>
    ├── #<task_2>  [Task] <task_2_title>
    └── #<task_3>  [Task] <task_3_title>

View: https://github.com/<TARGET_REPO>/issues/<epic>

Then suggest next steps:

Next steps:
  - Assign tasks to team members on GitHub
  - Use GitHub Projects board for tracking
  - Run `ooo run` for AI-assisted implementation of individual tasks

Notes

No MCP required: This skill works entirely through gh CLI
Non-destructive: Creates new issues only, never modifies existing ones
Cross-repo support: All gh commands use -R <TARGET_REPO>, so seeds can be published to any repository the user has write access to
Works with both seed formats: YAML seeds from ooo seed and JSON seeds from ooo pm are both supported — the parser auto-detects format by file extension

Repository: Q00/ouroboros
Path: .claude-plugin/skills/publish/SKILL.md
Commit: f09fa36

Last updated: about 2 hours ago
First committed: 2 months ago

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.