Python Blueprint Authoring

---
name: python-blueprint-authoring
description: Author a review-ready greenfield `blueprint.md` contract for a new or baseline-only Python repository, reusing the locked blueprint v1 schema already consumed by `python-project-init-greenfield`.
complexity: high
risk_profile:
  - ambiguity_sensitive
  - multi_agent_handoff
  - destructive_action
inputs:
  - target repository or project name and proof that the lane is truly greenfield or baseline-only
  - project purpose and baseline scope for Project Overview
  - exact required skill names that already exist in the current library
  - concrete toolchain choices and versions for Toolchain Expectation
  - concrete packages, paths, entrypoints, and other locatable structure for Structural Invariants
  - measurable quality targets and concrete sensing assertions for Quality Thresholds and Acceptance Criteria
outputs:
  - review-ready greenfield blueprint.md using the locked blueprint v1 section order
  - stop-and-ask feedback when required skills are missing, structure is abstract, or the request is in the wrong lane
  - a contract that python-project-init-greenfield can consume without schema translation or guessed locators
use_when:
  - a new or baseline-only Python repository needs its first review-ready blueprint.md
  - the task is to author or repair a greenfield blueprint before execution starts
  - the contract must stay inside the locked blueprint v1 shape already consumed by python-project-init-greenfield
do_not_use_when:
  - the repository already has meaningful structure, migration pressure, or retrofit conflict surfaces; use python-retrofit-plan-authoring
  - the task is to execute a valid blueprint; use python-project-init-greenfield
  - the task is to review or approve an existing blueprint
  - the request lacks tool choices, verifiable acceptance targets, or locatable structural details that cannot be derived safely from explicit intent or the repository name
---

# Purpose
Turn greenfield Python repository intent into a review-ready `blueprint.md` that `python-project-init-greenfield` can consume without reinterpretation.

# Trigger / When to use
Use this skill when:
- a new or baseline-only Python repository needs its first review-ready `blueprint.md`
- the task is to author or repair a greenfield blueprint before execution starts
- the workflow needs exact-name `Required Skills` validation, concrete `Structural Invariants`, and explicit stop-and-ask handling for ambiguity
- the authored contract must stay inside the locked blueprint v1 shape already used by `python-project-init-greenfield`

Do not use this skill when:
- the repository already has meaningful structure, migration pressure, or retrofit conflict surfaces; use `python-retrofit-plan-authoring`
- the task is to execute a valid blueprint; use `python-project-init-greenfield`
- the task is to review or approve an existing blueprint
- the request lacks tool choices or verifiable acceptance targets, or lacks package names or other locatable structural details that cannot be derived safely from explicit intent or the repository name; if a package name is derived, record the concrete derived name in the authored blueprint before handoff

# Inputs
- the target repository or project name and proof that the lane is truly greenfield or baseline-only
- the intended project purpose and baseline scope for `## Project Overview`
- exact required skill names that already exist in the current library
- concrete toolchain choices and versions for `## Toolchain Expectation`
- concrete packages, paths, entrypoints, and other locatable structure for `## Structural Invariants`
- measurable quality targets and concrete sensing assertions for `## Quality Thresholds` and `## Acceptance Criteria`
- explicit human clarification whenever the request is abstract, contradictory, missing a locatable detail, or routed to the wrong lane

# Process
1. Confirm lane fit first.
   - Use this skill only for new or baseline-only Python repositories.
   - If the request is really retrofit planning, route to `python-retrofit-plan-authoring`.
   - If the request is execution or review, hand off to `python-project-init-greenfield` or reviewer flow instead of absorbing those roles.
2. Reuse the locked blueprint v1 contract exactly.
   - Author only the heading order already consumed by `python-project-init-greenfield`.
   - Do not invent a new section, alias, compatibility layer, or alternate block format.
3. Validate `Required Skills` before drafting the final contract.
   - Check every named skill against the current library using exact directory names.
   - Treat `_` versus `-`, case changes, guessed aliases, and invented placeholders as invalid.
   - If any named skill is absent, stop and ask instead of normalizing or deferring the problem downstream.
4. Write the blueprint in the locked section order:
   1. `## Project Overview`
   2. `## Required Skills`
   3. `## Toolchain Expectation`
   4. `## Structural Invariants`
   5. `## Quality Thresholds`
   6. `## Acceptance Criteria`
5. Write `## Project Overview` as concise human-readable baseline intent.
   - Summarize the repository purpose and baseline goals.
   - Do not hide missing structural decisions behind general prose.
6. Write `## Required Skills` with exact current-library names and explicit roles.
   - Keep each listed skill locatable as `skills/<skill-name>/` in the active library.
   - Preserve an optional marker only as `(Optional)` after the exact skill name when truly needed.
7. Write `## Toolchain Expectation` and `## Structural Invariants` with concrete, executor-usable detail.
   - Name real tools, versions, package names, paths, and entrypoints.
   - If the request says only “modern layout”, “good defaults”, or similar abstract goals, stop and ask.
   - If structural details are contradictory or cannot be located in the filesystem, stop and ask.
8. Write `## Quality Thresholds` and `## Acceptance Criteria` as verifiable contract surfaces.
   - Under `## Acceptance Criteria`, place a fenced `yaml [sensing-assertions]` block immediately below the heading.
   - Every assertion record must include `kind`, `target`, and `expected`.
   - Keep human explanation outside the machine-readable block.
9. Run the authoring self-check before handoff.
   - Confirm section order, assertion-block placement, exact-name skill validation, locatable structure, and greenfield lane fit.
   - Confirm the draft stays upstream-authoring-only and does not widen into executor changes.
10. Stop at `review-ready`.
    - Do not approve the blueprint.
    - Hand the draft to reviewer flow once the contract is complete.

# Examples
- Positive: Author a greenfield `blueprint.md` for an empty weather repository that lists `sense-env-scaffold`, `python-testing-pytest`, and `python-type-hints-strict` by exact library name, declares `src/weather_service/main.py`, and puts a `yaml [sensing-assertions]` block immediately under `## Acceptance Criteria`.
- Negative: Draft a blueprint for an existing repository that needs migration, guess a missing skill as `python_testing_pytest`, or write `Structural Invariants` as “use a modern src layout with good defaults”.

# Outputs
- a review-ready greenfield `blueprint.md` using the locked blueprint v1 section order
- exact stop-and-ask feedback when required skills are missing, structure is abstract, or the request is in the wrong lane
- a contract that `python-project-init-greenfield` can consume without schema translation or guessed locators

# Validation

## Required Checks
- all six blueprint v1 sections are present in exact order: Project Overview → Required Skills → Toolchain Expectation → Structural Invariants → Quality Thresholds → Acceptance Criteria
- every schema v1 field is populated with concrete, executor-usable values; no section is left empty or abstract
- no TBD placeholder or abstract style words (e.g. "modern", "sensible", "clean") appear in any locked field
- `## Acceptance Criteria` starts with a parseable `yaml [sensing-assertions]` block immediately below the heading
- every sensing assertion includes `kind`, `target`, and `expected`
- every named required skill matches a real current-library directory name exactly

## Quality Checks (best effort)
- naming conventions are consistent across package names, paths, and entrypoints
- toolchain dependency choices are justified or accompanied by rationale notes
- `## Project Overview` is concise and hides no missing structural decisions behind general prose
- sensing assertions cover the main structural invariants declared in `## Structural Invariants`

## On Soft Fail
- mark blueprint as INCOMPLETE at the top of the draft
- list every missing or abstract section explicitly
- do not block output; deliver the partial draft with gaps flagged so the reviewer can act

# Failure Handling

## Missing Context
- BLOCKED — if project intent, package name, or key structural decisions are not provided and cannot be safely derived from explicit context, stop and ask before proceeding
- list the specific missing inputs explicitly; do not fabricate locators, package names, or sensing assertions to fill gaps

## Ambiguous Requirement
- note the assumption explicitly as a sub-bullet under an existing section of the blueprint (e.g., under `## Implementation Notes`)
- proceed with best-effort draft using the stated assumption
- flag the assumption clearly so the reviewer and `python-project-init-greenfield` consumer can evaluate it before handoff

## Execution Limitation
- if the schema v1 reference (`references/blueprint-contract.md`) cannot be read, note the limitation explicitly in the draft
- fall back to the known locked section order and block placement rules embedded in this skill's Process
- do not invent new sections or omit required ones to work around the limitation

# Verification
- confirm the section order is exactly Project Overview -> Required Skills -> Toolchain Expectation -> Structural Invariants -> Quality Thresholds -> Acceptance Criteria
- confirm `## Acceptance Criteria` starts with a parseable `yaml [sensing-assertions]` block
- confirm every sensing assertion includes `kind`, `target`, and `expected`
- confirm every named required skill matches a real current-library directory name exactly
- confirm package names, paths, entrypoints, and tool choices are concrete enough for executor consumption
- confirm greenfield-only lane fit is explicit and retrofit requests are rerouted instead of absorbed
- confirm the skill stays in authoring scope and does not imply executor or reviewer approval

# Red Flags
- the request mixes “create the first baseline” with “preserve and migrate these existing files”
- a named required skill does not exist in `skills/`
- `Structural Invariants` contain only style words such as “clean”, “modern”, or “sensible”
- acceptance prose appears before the `yaml [sensing-assertions]` block
- the request tries to make `python-blueprint-authoring` choose execution-time behavior or modify the executor schema

# Common Rationalizations
- “The executor can normalize the skill name later.”
- “We can leave the structure abstract because greenfield repos are easy.”
- “This repo mostly exists already, but blueprint authoring is close enough.”
- “The sensing assertions can be added after init works once.”
- “A missing required skill can stay as a placeholder for now.”

# Boundaries
- Do not execute the blueprint.
- Do not approve the authored blueprint.
- Do not invent a new blueprint schema or widen the executor contract.
- Do not normalize, alias, or silently replace missing skill names.
- Do not invent package names, paths, entrypoints, tool choices, or sensing assertions when the request is abstract.
- Do not absorb retrofit planning, runtime routing, or reviewer responsibilities.

# Local references
- `examples.md`: layered blueprint-authoring scenarios, stop-and-ask cases, and lane-mismatch examples
- `checklist.md`: repeatable review-ready checks for this higher-risk authoring skill
- `references/blueprint-contract.md`: locked blueprint v1 section order, block placement, and parser-facing authoring rules
- `references/required-skills-validation.md`: exact-name library validation rules, optional-item handling, and blocking missing-skill behavior
- `references/greenfield-lane-boundaries.md`: greenfield-only fit rules and rerouting boundaries versus retrofit or execution
- `references/structural-invariants-locatability.md`: concrete locatability rules for packages, paths, entrypoints, and stop-and-ask triggers