publish · diff

git:20260628.1209907 to git:20261016.ed1d155

61 added, 315 removed. Audit A to A.

What this update changes in the checks

No check changed: every fixed check gives the same answer before and after this update.

A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.

---
name: publish
description: "Publish Seed specification as GitHub Issues for team-based project management"
---
# /ouroboros:publish
- Convert a Seed specification into structured GitHub Issues for team workflows.
-
- ## Usage
+ Convert a Seed into a GitHub Epic issue plus Task issues. Works entirely through the `gh` CLI (no MCP), creates new issues only, and never modifies existing ones.
```
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:**
-
- ```bash
- 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:**
+ Run commands with the active runtime's `run_shell` capability and ask every question with the active runtime's `ask_user` capability.
- ```bash
- gh auth status
- ```
+ ### Step 1: Prerequisites
- If not authenticated, tell the user:
- ```
- GitHub CLI is not authenticated. Run: gh auth login
- ```
- Stop.
+ Run `command -v gh`. If missing, tell the user to install it from https://cli.github.com/ and stop. Run `gh auth status`; if not authenticated, tell the user to run `gh auth login` and 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:
+ Seeds live in `~/.ouroboros/seeds/`: interview Seeds as `{seed_id}.yaml`, PM Seeds as `pm_seed_{id}.json`. In priority order:
- 1. **Explicit path argument**: If the user provided a file path (`.yaml` or `.json`), read it directly
- 2. **Most recent seed file**: Search for the most recent seed in the standard location:
- ```bash
- 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.
- 3. **Conversation context**: If `ooo seed` or `ooo pm` was just run in this conversation and the seed path was reported, use that path.
+ 1. An explicit `.yaml` or `.json` path argument.
+ 2. The most recent files from `ls -t ~/.ouroboros/seeds/*.yaml ~/.ouroboros/seeds/*.json 2>/dev/null | head -5`; if several exist, ask the user to choose.
+ 3. A Seed path reported by `ooo seed` or `ooo pm` earlier in this conversation.
- If no seed is found:
- ```
- No Seed found. Run `ooo seed` or `ooo pm` first to generate a specification.
- ```
- Stop.
+ If none is found, tell the user to run `ooo seed` or `ooo pm` first, and 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:**
-
- ```bash
- gh repo view --json nameWithOwner -q '.nameWithOwner' 2>/dev/null
- ```
+ Detect the format by extension. Omit any section whose field is missing or empty rather than failing.
- **4b. Present the target repo choice via AskUserQuestion:**
+ YAML Seed (`ooo interview` + `ooo seed`):
- If auto-detection succeeded:
- ```json
- {
- "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
- }]
- }
- ```
+ | Field | Use |
+ |-------|-----|
+ | `goal` | Epic title and Goal section |
+ | `constraints` | Constraints section |
+ | `acceptance_criteria` | Epic checklist, distributed to Task issues |
+ | `ontology_schema` | Ontology table (field, type, description) |
+ | `evaluation_principles` | Evaluation Principles table (name, weight, description) |
+ | `exit_conditions` | Exit Conditions (Definition of Done) |
+ | `metadata.ambiguity_score` | Confidence indicator |
+ | `metadata.seed_id` | Duplicate detection |
- If auto-detection failed (not in a git repo):
- ```json
- {
- "questions": [{
- "question": "Which GitHub repository should the issues be created in? (format: owner/repo)",
- "header": "Target Repository"
- }]
- }
- ```
+ JSON PM Seed (`ooo pm`, `PMSeed` schema):
- If the user chose "Other", ask:
- ```json
- {
- "questions": [{
- "question": "Enter the target repository (format: owner/repo):",
- "header": "Target Repository"
- }]
- }
- ```
+ | Field | Use |
+ |-------|-----|
+ | `pm_id` | Duplicate detection |
+ | `product_name` | Epic title prefix |
+ | `goal` | Goal section |
+ | `constraints` | Constraints section |
+ | `success_criteria` | Acceptance Criteria checklist |
+ | `user_stories` | User Stories, each as "As a **{persona}**, I want to **{action}**, so that **{benefit}**." |
+ | `deferred_items` | Deferred Items section |
+ | `decide_later_items` | Open Questions section |
+ | `assumptions` | Assumptions section |
- Store the resolved repository as `TARGET_REPO`. **All subsequent `gh` commands MUST include `-R <TARGET_REPO>`** to ensure they target the correct repository.
+ ### Step 4: Target repository
- ### Step 5: Duplicate Check
+ Run `gh repo view --json nameWithOwner -q '.nameWithOwner' 2>/dev/null`. If it returns a repo, ask whether to publish there or to another `owner/repo`; otherwise ask for `owner/repo`. Store the answer as `TARGET_REPO`. **Every later `gh` command MUST include `-R <TARGET_REPO>`.**
- Before creating issues, check if this seed was already published:
+ ### Step 5: Duplicate check
```bash
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:
- ```json
- {
- "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:**
-
- ```json
- {
- "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:
- ```bash
- 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):**
-
- ```bash
- 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:**
-
- ```bash
- 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:
-
- ```bash
- 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>
+ This finds earlier publishes because the Epic body records the Seed ID (Step 7). If matches exist, list them and ask whether to create anyway or cancel; on cancel, stop.
- ---
+ ### Step 6: Plan the issues
- *Part of [Epic] #<epic_number> | Generated by [Ouroboros](https://github.com/Q00/ouroboros) via `ooo publish`*
- BODY
- )"
- ```
+ Group the acceptance criteria into logical implementation units (by feature area, layer, or dependency order); each unit becomes one Task. Show the plan (Epic goal summary, then each Task title and brief scope) and ask whether to create the issues or modify the plan. On modify, ask what to change, adjust, and show it again.
- **7d. Update Epic with task links:**
+ ### Step 7: Create the issues
- After all tasks are created, add a comment to the Epic:
+ `gh issue create` prints the issue URL; take the number from its trailing digits (`grep -o '[0-9]*$'`). Pass bodies through a quoted heredoc (`--body "$(cat <<'BODY' ... BODY)"`).
- ```bash
- gh issue comment <epic_number> -R <TARGET_REPO> --body "$(cat <<'BODY'
- ## Implementation Tasks
+ 1. Create labels, ignoring "already exists":
+ ```bash
+ 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
+ ```
+ 2. Epic: title `[Epic] <goal summary>`, labels `ouroboros,epic`. Body: the Step 3 sections in order (Goal, Constraints, Acceptance Criteria as `- [ ]` items, Ontology, Evaluation Principles, Exit Conditions, plus the PM-only sections), then this footer:
+ ```
+ ---
- - [ ] #<task_1_number> — <task_1_title>
- - [ ] #<task_2_number> — <task_2_title>
- - [ ] #<task_3_number> — <task_3_title>
+ **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`*
+ ```
+ 3. Each Task: title `[Task] <task title>`, labels `ouroboros,task`. Body: `Parent: #<epic>`, then Scope, Acceptance Criteria (`- [ ]` items for this unit), Test Checklist, Pass Criteria (measurable done conditions), then this footer:
+ ```
+ ---
- Track overall progress by checking off tasks as their issues are closed.
- BODY
- )"
- ```
+ *Part of [Epic] #<epic> | Generated by [Ouroboros](https://github.com/Q00/ouroboros) via `ooo publish`*
+ ```
+ 4. Comment on the Epic (`gh issue comment <epic> -R <TARGET_REPO>`) with an "Implementation Tasks" checklist of `- [ ] #<task>: <title>` lines, noting progress is tracked by checking off tasks as their issues close.
### 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
+ Show `Published to <TARGET_REPO>:` with the Epic and its Tasks as a tree (`#<n> [Epic|Task] <title>`) and the link `https://github.com/<TARGET_REPO>/issues/<epic>`. Suggest next steps: assign tasks, track on a GitHub Projects board, run `ooo run` for AI-assisted implementation of individual tasks.
## RFC #1392 State Breadcrumb Footer
- Your final response MUST end with exactly one breadcrumb footer line:
-
- ```
- ◆ <current state> → next: <recommended action>
- ```
-
- Derive `<current state>` from live session state via `ouroboros_session_status` when that MCP projection is available; otherwise derive it from this skill's actual outcome. Never use a linear `Step N of M` footer because Ouroboros is an evolutionary loop. When the next action is genuinely a choice, list 2-3 honest options in the `next:` clause. The breadcrumb line must be the last line of the response.
+ End the final response with exactly one line `◆ <current state> → next: <recommended action>`. Derive the state from live session state via `ouroboros_session_status` when available, otherwise from this skill's actual outcome. Never use a linear `Step N of M` footer; when the next step is a real choice, list 2-3 options.