Create Git Issue

Turn the current conversation context into a PRD and then publish implementation issues as thin, dependency-aware vertical slices.

Workflow position:

```
break-req
```
first, to resolve product/technical decisions.
```
create-git-issue
```
second, to publish PRD + implementation slices and routing hints.
```
run-with-it
```
third, to perform final runtime routing and execution.

create-git-issue

must never claim final routing authority.

Issue Tracker Vocabulary

Use these canonical triage roles when creating and labeling issues:

Category roles:

```
bug
```
```
enhancement
```

State roles:

```
needs-triage
```
```
needs-info
```
```
ready-for-agent
```
```
ready-for-human
```
```
wontfix
```

Labeling rules:

Every published issue should have exactly one category role and one state role.
New PRD issues should default to category
```
enhancement
```
and state
```
needs-triage
```
.
New implementation slice issues should default to category
```
enhancement
```
and state
```
ready-for-agent
```
.
If your tracker uses different label strings, map them from these canonical names consistently.
If a mapping is ambiguous, ask one focused clarification question before publishing.

Publishing Policy

Prefer the GitHub CLI for all tracker writes.

Before publishing any PRD or implementation issue, check whether

gh

can be used:

bash

command -v gh >/dev/null 2>&1 && gh repo view >/dev/null 2>&1

If that succeeds, use

gh issue create

for the PRD parent issue and every implementation slice issue.

Use body files so multiline Markdown is preserved:

bash

gh issue create --title "<PRD title>" --body-file <prd-body-file>.md --label enhancement --label needs-triage
gh issue create --title "<slice title>" --body-file <slice-body-file>.md --label enhancement --label ready-for-agent

gh

is not found, the user is not authenticated, the repository cannot be inferred, or any

gh issue create

command fails, do not keep retrying through another GitHub integration. Save the work locally instead.

Local fallback output must create exactly two Markdown files in the workspace root:

```
prd.md
```
contains the complete PRD that would have been published as the parent issue.
```
issues.md
```
contains every approved implementation slice issue, in dependency order.

When writing local fallback files:

Include the issue title, intended labels, parent relationship, and body for each item.
In
```
issues.md
```
, use the local parent reference
```
prd.md
```
.
Preserve all approved issue template content, including technical context snapshots and acceptance criteria.
Tell the user that GitHub publishing was skipped and name the two local files.

Process

1. Reuse break-req outputs first

Before asking the user any clarifying questions, look for existing break-req artifacts in this priority order:

```
technical_requirements.md
```
in the workspace root
Any
```
technical_requirements.md
```
in docs, planning, or requirements folders
Conversation history where a break-req session already resolved decisions

If found, treat those decisions as the default source of truth and continue from them.

Do not ask the user to repeat answers that are already explicitly resolved there.

Only ask follow-up questions for unresolved, contradictory, or missing decisions needed to publish PRD/issues.

2. Gather context

Work from existing conversation context.

If the user passes an issue reference (issue number, URL, or path), fetch that issue and read its body and comments before drafting.

3. Explore codebase

If you have not already explored the codebase, do so to understand the current state.

Use domain glossary vocabulary and respect ADRs in the area you are touching.

4. Draft PRD first

Do not start by interviewing the user. First synthesize a PRD from what you already know.

Sketch major modules that will be built or modified, looking for deep modules with stable, testable interfaces.

Then check with the user only for deltas from break-req outputs:

Whether module boundaries match expectations
Which modules should be tested

Use this PRD template:

<prd-template>

Problem Statement

The problem from the user's perspective.

Solution

The solution from the user's perspective.

User Stories

A long, numbered list in the format:

As an <actor>, I want a <feature>, so that <benefit>

Implementation Decisions

Modules to build or modify
Interfaces likely to change
Technical clarifications
Architectural decisions
Schema changes
API contracts
Specific interactions

Do not include file paths or code snippets.

Testing Decisions

What makes a good test (external behavior over implementation details)
Which modules will be tested
Prior art in the codebase

Out of Scope

Explicitly excluded work.

Further Notes

Any additional constraints or context.

</prd-template>

5. Publish PRD issue

Publish the PRD to the issue tracker as the parent issue using

gh issue create

Apply the

enhancement

and

needs-triage

labels.

Capture the created PRD issue URL or number. Use it as the parent reference for all implementation slice issues.

If GitHub publishing is unavailable, write the PRD body to

prd.md

and continue preparing the implementation slice issues for

issues.md

Do not close or modify unrelated issues.

6. Break PRD into tracer-bullet slices

Convert the approved PRD into thin vertical-slice issues.

Each slice must be end-to-end (schema, API, UI, tests), demoable on its own, and as small as possible.

Prefer AFK slices over HITL slices where possible.

<vertical-slice-rules> - Each slice delivers a narrow but complete path through all integration layers - A completed slice is independently verifiable - Prefer many thin slices over few thick slices </vertical-slice-rules>

7. Quiz user on issue breakdown

Present a numbered list for review. For each slice include:

Title
Type: HITL or AFK
Blocked by: slice dependencies
User stories covered

Ask:

Is granularity right (too coarse or too fine)?
Are dependencies correct?
Should any slices be merged or split?
Are HITL and AFK assignments correct?

Iterate until approved.

8. Publish implementation issues

Create one issue per approved slice using the template below.

If GitHub publishing is available, use

gh issue create

for each approved slice.

If GitHub publishing is unavailable, append each approved slice issue to

issues.md

instead.

Before publishing each issue, derive a stack snapshot from the codebase and include it in the issue body so implementation agents can align with existing patterns.

Capture at minimum:

UI stack and UI component libraries in use
Backend/runtime stack and framework versions
Package ecosystems and key dependencies (for example npm, NuGet, pip, Maven, Gradle)
Existing architecture patterns and module boundaries
Integration constraints (API contracts, schema ownership, migration expectations)
Dependency policy for this slice: reuse existing libraries by default, and only add new dependencies when clearly justified

Publish or write local issues in dependency order (blockers first).

Apply

ready-for-agent

to each issue.

Set each slice issue to reference the PRD issue as parent. If using local fallback, reference

prd.md

as the parent.

Include machine-readable routing hints in every implementation issue. These hints guide planning only and must not bind runtime orchestration. State explicitly in each issue that run-with-it remains the final runtime routing authority.

<issue-template> ## Parent

A reference to the PRD parent issue.

What to build

A concise end-to-end description of this slice.

Agent Routing

yaml

agent_routing:
  complexity_hint: <quite-easy|easy|medium|medium-hard|complex|holy-fuck>
  required_capability: <fast|balanced|advanced>
  parallel_safe: <true|false>
  cost_preference: <low|balanced|high>
  speed_preference: <low|balanced|high>
  ownership_scope:
    - <path-or-module-scope>
  verification:
    - <verification-hint>

Technical Context Snapshot

Current stack in scope

UI framework and UI libraries currently used
Backend framework/runtime currently used
Data layer tooling currently used

Dependencies in scope

Existing packages/libraries this slice should reuse
New dependency additions allowed for this slice: yes/no
If yes, justification and alternatives considered

Architecture alignment

Existing module boundaries to respect
Existing service/component patterns to follow
ADRs or architectural constraints to follow
```
create-git-issue
```
provides routing hints only; it must not assign concrete agent/model names
```
run-with-it
```
remains the final runtime routing authority

Integration touchpoints

APIs/events/contracts affected
Schemas/migrations/data contracts affected
Backward compatibility expectations

Acceptance criteria

Criterion 1
Criterion 2
Criterion 3

Blocked by

Reference to blocking issue(s), if any

Or "None - can start immediately".

</issue-template>

Output Checklist

```
gh
```
availability checked before publishing
Each implementation issue includes a technical context snapshot (stack, dependencies, architecture, integration touchpoints)
Parent/blocked-by relationships set correctly

create-git-issue

NPX Install

Tags

SKILL.md Content