Imported from urban233/ntn-ingest (.agents/skills/blueprint-to-issues/SKILL.md). Install upstream with npx skills add urban233/ntn-ingest --skill blueprint-to-issues. Copyright stays with the author.

blueprint-to-issues

Turns a large architecture or product specification into a structured, dependency-ordered GitHub issue backlog that a team can execute in parallel.

The governing principle is parallelism without collision: every issue must be independently executable by a developer with the right skill level and time availability, while the shared contracts that span issues are identified and locked down before any implementation begins.

Output is markdown only. The user pastes issues into GitHub manually (or via gh/API automation later). Skill does not publish to GitHub directly.

Entry point

Before doing anything, check what has been provided:

• If a blueprint document is already in the conversation or attached → skip the intake questions and proceed directly to Phase 1.
• If no document is present → ask for it in a single message: "Please paste or attach the architecture/product spec you want to decompose." Wait for it before continuing.

Do not ask any other questions until you have the document. The document is the source of truth for everything that follows.

Phase 1 — Extract the shared-contracts ledger

Before decomposing into issues, identify everything the blueprint already pins down that must not be re-decided independently during implementation. These are the shared contracts: schemas, envelopes, taxonomies, and boundaries that multiple issues will depend on.

Look specifically for:

• Named schemas and envelopes — object models, job/request/response structures, revision/concurrency tokens, payload manifests.
• Error taxonomies — stable top-level error codes and their meanings.
• Identity and lifecycle rules — UUID conventions, revision semantics, mutation effects (CREATE/UPDATE/DELETE).
• Authority boundaries — which component owns what (persistence, rendering, execution, etc.) and what it must never do.
• Naming conventions and namespaces — stable identifier prefixes, versioning schemes, type-ID formats.
• Capability/version negotiation contracts — how components discover what the other side supports.

Output the ledger as backlog/shared-contracts-ledger.md (see template in references/ledger-template.md). This file is a fixed input for every downstream feature-spec-creator v2 session — it is not open for re-decision during implementation.

If the blueprint does not pin something down, do not invent a decision. Leave it as an open question for the individual issue's implementation spec.

Phase 2 — Decompose into issues

Slice the blueprint into issues using its own structure as the primary guide. If the blueprint contains capability-edition tables, component-ownership tables, or object/relationship catalogs, use those as natural boundaries.

Each issue represents one cohesive unit of implementation work — typically one component, one object type with its jobs, one integration adapter, or one bounded subsystem.

Tag every issue with exactly three labels

Component/domain — derived from the blueprint's own vocabulary where possible. Do not invent new names when the blueprint names things. Use whatever the blueprint calls its subsystems — e.g. persistence, auth, api-gateway, worker-queue, plugin-registry, ui-shell, event-bus, external-adapter:<provider>. These are illustrative; always prefer the project's own terminology.

Size — based on how many new contracts/schemas the issue introduces and whether it requires a heavyweight kernel executor:

• S — touches only locally-scoped logic, no new shared schemas, no new kernel executors. Completable in a focused session.
• M — introduces one or two new typed schemas or one integration adapter. Clear scope but non-trivial.
• L — introduces multiple interacting schemas, a new execution boundary, or a new cross-cutting contract. Requires sustained focus.

Tier — computed from the dependency graph in Phase 3:

• tier:0 — foundational; nothing else can start without this.
• tier:1 — domain features that depend on tier:0 but are independent of each other.
• tier:2 — integrations, adapters, and derived features that depend on tier:1 outputs.
• tier:3 — tooling, copilot, and external-interface layers built on top of tier:2.

Issue body template

Every issue uses this structure (see references/issue-template.md for the full template):

## Motivation
One paragraph. Why does this exist? Which blueprint section drives it?
Reference the section by name/number, not by quoting it.

## Scope
What is included in this issue. Be specific about object types, job types,
API surfaces, or UI components.

## Non-goals
What is explicitly excluded. Prevents scope creep during implementation.

## Acceptance criteria
Numbered list. Concrete, verifiable. Not "it works" — "submitting the same
request twice with the same idempotency key returns the original result and
does not create a second record in the database".

## Shared-contract anchors
Which entries in shared-contracts-ledger.md this issue must treat as fixed
inputs. List by ledger entry name, not by copying the content.

## Open questions for implementation
Decisions the blueprint deliberately leaves to the implementer. These seed the
interrogate-me session in feature-spec-creator v2. Be specific — vague
questions produce vague implementation specs.

## Dependencies
`depends-on: #<issue-number>` for each blocking issue.

Issue lifecycle status

Every generated issue must include a YAML "status" field. New issues begin as "planned". The allowed values are:

• "planned": dependency-aware backlog item that has not started.
• "in_progress": an approved implementation spec exists or implementation is actively underway.
• "blocked": work cannot continue because a stated dependency, decision, or external condition is unresolved; record the blocker in Developer notes.
• "completed": implementation and its acceptance evidence are recorded.

The implementation workflow—not this skill—moves statuses after generation. Never delete completed issue files: their accepted scope, dependencies, and acceptance criteria are part of the project delivery history.

Phase 3 — Build the dependency graph and wave structure

After drafting all issues, perform a structured analysis pass.

3.1 Build the dependency graph

For each issue, list every other issue whose output it requires before it can start. Be precise: "requires the job-service envelope schema" is a dependency; "is related to" is not.

3.2 Topological sort into waves

Compute waves from the dependency graph:

• Wave 0 — issues with no dependencies. These must be done first and are typically serial (one owner) because they define the shared substrate.
• Wave N — issues whose dependencies are all in waves 0..N-1.

Check that the wave structure actually supports the team size:

• If Wave 0 contains more items than one person can complete in a reasonable sprint, flag it: some items may need to be sequenced within Wave 0 or assigned to a single dedicated owner.
• If Wave 1 fans out to fewer items than the team size, flag idle capacity.
• If a single Wave-1 item blocks more than half the team, flag it as a critical-path risk.

3.3 Run the contention pass

Two issues in the same wave can collide without a formal dependency edge if they share a file, module, or schema. Check for:

• Multiple issues that write to the same schema or enum.
• Multiple issues that extend the same registry or plugin contract.
• Multiple issues that modify the same base class or interface.

For every collision found, decide one of:

1. Add a dependency edge (one issue must finish before the other starts).
2. Split the shared piece into its own upstream issue.
3. Flag it for the team lead to assign both to the same developer.

Mark every contention with a ⚠ CONTENTION annotation in the overview file.

Phase 4 — Output

Produce the following files. Save all to backlog/.

backlog/shared-contracts-ledger.md

See references/ledger-template.md.

backlog/overview.md

Contains:

• Wave diagram — a table showing each wave, the issues in it, their component/domain tag, size, and assigned-developer slot (left blank for the team to fill in).
• Critical-path issues — any issue that, if delayed, delays the entire downstream wave.
• Contention flags — the ⚠ CONTENTION list with resolution recommendations.
• Parallelism summary — how many issues are available to start in each wave, and what skill areas they require, so a team can self-assign by expertise.

backlog/issues/<slug>.md

One file per issue, named <tier>-<component>-<short-title>.md, e.g. tier0-persistence-project-model.md.

Each file contains the complete issue body as defined in Phase 2, plus a YAML frontmatter block:

---
title: "<Issue title>"
status: planned
labels: ["<component/domain>", "<size>", "<tier>"]
depends-on: []   # list of slugs
contention: []   # list of slugs this issue may collide with
---

Quality bar before delivery

• Every issue references only shared-contract entries that exist in the ledger — no invented schemas.
• Every acceptance criterion is verifiable without reading the blueprint.
• Every "open question for implementation" is genuinely open (not already answered by the blueprint or the ledger).
• The wave structure supports at least one path where the stated team size can work in parallel from Wave 1 onward.
• Every same-wave pair that shares a file or schema has a contention flag or a resolved dependency edge.
• No issue is so large that it cannot be completed in a two-week sprint by a mid-level developer; split if so.
• Every generated issue frontmatter contains "status: planned".

Reference files

Read these before writing their corresponding output: