Blueprint Crafting

Produces frozen, convergence-checked upstream artifacts — product spec, architecture design, iteration plan, executable summary, and research — for parallel-development to consume as authoritative references. The two skills form a specify then implement pipeline.

Core Positioning

Constrained production, not check-only

Most upstream artifacts arrive incomplete. This skill does not merely validate; it authors, rewrites, researches, and checks them to convergence. Every activity (author / rewrite / research / check) has a constraints-profile — the deterministic checks that form its convergence oracle.

• Process axis (the convergence loop ran well): the artifact's constraints-profile is satisfied + adversarial reviewer has no Blocker + decisions resolved + no drift. Deterministic, high-confidence, convergeable.
• Outcome axis (is the artifact right): is this the correct product / design / conclusion. Only the user/market can judge. Always human_confirm_required.

Good output = process-axis convergence, NOT "the artifact is correct." The two axes are kept separate in the verdict (see arch-design §1).

What it does NOT do

• Does not converge "is this the correct product/design/conclusion" (outcome axis — human/market only).
• Does not implement code. That is parallel-development's job.

Scope

• In: produce convergence-checked upstream artifacts (author / rewrite / research / check), each gated by its constraints-profile.
• Out: outcome axis ("correct product/direction/conclusion" — human only); code implementation (parallel-development).

Scope Guard (entry-time detection)

Runs as the first step of invocation, before any production work. The guard keys on the deliverable, not on the word "document":

• In scope: the deliverable is an upstream artifact itself (a spec, arch-design, iteration plan, executable summary, or research artifact) — produced or converged.
• Out of scope: the deliverable is source/test code (a feature, bug fix, refactor, or tests). Emit a misuse hint and route to parallel-development.

Misuse hints (terse; fire without loading the full scope detail):

• Implement a feature / fix a bug / refactor code → this skill produces the spec, not the code. Route: parallel-development.
• Execute/follow an existing plan to deliver code → that is plan-driven implementation, not artifact authoring. Route: parallel-development (plan-driven mode).
• "Is this the right product direction / is this research conclusion true?" → outcome axis, human only. This skill converges the constraints-profile, not the conclusion.

The guard is soft: it reminds and routes, does not refuse. A user may knowingly proceed on a partial fit.

Quick Start

You are the producer: author the Markdown artifact, then run the deterministic convergence with produce.py. The outer ring (solidforge:plan-reviewer) is an LLM agent you spawn separately — pass its findings via --outer to reach process_converged. Do not read infra/scripts/*.py to reverse-engineer operator CLIs; produce.py is the one entry point and chains the operators as libraries (the individual CLIs are not shell-pipeable — normalizer emits a {plan_model, coverage} wrapper while the others take a bare plan-model, so shell chaining fails silently green). infra/test/end_to_end.py shows the library-API shape (how the operators compose in Python) — it is a developer reference, NOT a produce.py CLI example; produce.py usage is steps 3–4 below, so do not read end_to_end to learn it.

Run in order; do not wait for the user between steps.

1. Author the artifact (your primary work — write Markdown) covering its anchors — arch-design §3 lists the per-type anchors, infra/scripts/constraints.json the profile each artifact_type must satisfy. Author to clean-cut discipline: one claim domain per doc (a second unrelated domain forks a new doc; the original keeps an anchor reference); every fact, value, and enumeration stated ONCE and referenced by anchor elsewhere — restatement is the desync generator; shared terms and marker strings defined once in a terms section; cross-domain contracts in one integration doc. Before freezing a multi-section artifact, self-check cross-section desync (the dominant late-round csr defect class): grep every cross-section storyline in all its word forms, across every file it touches — restated enumerations and term variants are the findings this check exists to prevent. Classify external presentation behavior (ADR #21): a claim about how an external system presents the integration (lock screen / carplay / share sheet / widget / system UI) is experiment-class — a fetched page proving the API exists is NOT evidence of what the user sees; when no fetchable authoritative source specifies the presentation, mark it a resolve-now ODP whose resolution is a spike or a device experiment (or defer it explicitly) — never write it as a satisfied assumption. Surface completeness: every user-visible surface the change touches carries at least one observable AC (surface name + expected observation). The plan-reviewer checks both as warning-tier advisory. Present user-ruling moments as decision packets (ADR #22): an ODP (or any decision) routed to the user arrives recommendation-first, never as a bare option list. Layer by decision class — L1 light (preference/idiom, no evidence dependency): the decision-item format alone; L2 research-backed (load-bearing AND evidence-dependent — the discriminating facts not yet established, whether external and fetchable-or-experimentable or codebase-local and not yet read): run the evidence pass FIRST (multi-source web dispatches the researcher per ADR #13; single-source or codebase-local is self-authored per ADR #3; the sub-object lands in plan_model["research"] and passes research_constraints), then present recommendation → cited claims → options × [evidence fit / cost / reversibility / risk] table → cost → rollback; L3 SWOT (strategy/positioning class): a SWOT table whose S/W cells carry the rationale and whose option set carries the alternatives, embedding the L2 evidence table when evidence-dependent — class conflict resolves to the higher layer. The honest fallback — insufficient basis plus the named cheapest evidence step — is a valid presentation when the information cannot be fetched (for an ADR #21 experiment-open ODP, the recommendation IS the spike). Every layer ends with a decision line naming the decision owner: the packet recommends, the human decides (outcome axis). The decision-item format, quoted verbatim from its English carrier ~/.claude/CLAUDE.md (the flow-managed derivative; the ~/.pi master is Chinese and stays normative — a labeled quotation; sync on carrier change is maintainer discipline per ADR #22, not the master-first flow): recommendation → rationale → alternatives → cost → rollback; when there is no recommendation, state what information is missing.
2. Build plan-model.json. Normalize a source with normalizer.normalize(text, format=fmt) (returns {plan_model, coverage} — keep the plan_model half) or construct it directly, then set plan_model["anchors"] for every required anchor (author-supplied is authoritative; the normalizer's keyword detection is an advisory fallback). The field contract — required top-level fields, every item field's semantics, and the subset_tags three-way classification (executable / upstream_only / downstream_only) — is infra/schemas/plan-model.schema.json; every field carries a description, so author against the schema directly. Do NOT read plan_model.py / freeze.py / constraints_check.py to reverse-engineer the fields — those are embody/check logic, not the contract; the schema is the single source of truth.
3. python3 infra/scripts/produce.py plan-model.json --out-dir docs/ → runs the inner ring + freeze; prints process_converged (false until the outer ring is supplied) and writes <name>.queue.md + .run-record.json. Fix any named inner Blocker (anchor / authority / ODP) and re-run.
4. Spawn solidforge:plan-reviewer (pass the spec via the authority chain so the seam-quality checks are active — the spec absent → the checks degrade to a coverage note); save its findings to findings.json; re-run python3 infra/scripts/produce.py plan-model.json --outer findings.json --out-dir docs/ → process_converged=true on a clean outer ring.

If memory says the docs were already converged, read the frozen .run-record.json / .queue.md to judge whether re-converge is needed — the verdict lives in the run-record, not in the infra source.

When This Skill Is Invoked

The operational entry point is produce.py (see Quick Start above) — the stages below are the conceptual lifecycle it orchestrates as library calls; you do not invoke the individual operator CLIs (they are not shell-pipeable).

Execute the convergence lifecycle for the detected artifact type and activity. The full target lifecycle (operators land across iterations I2–I7; see docs/iteration-plan.md):

1. Scope Guard (before any work) — out-of-scope (code) → misuse hint + route to parallel-development.

2. Normalize — heterogeneous source format (rich md / Cursor .plan.md / work-package) → plan-model, graded extraction (latch high-confidence / prose semantic-infer low-confidence). Note: research-notes is NOT a normalizer input format — research artifacts populate plan_model["research"] directly (see step 3), bypassing item-normalization, because the research.{claims,sources,cost_ledger,staging} shape has no item-parser. [iteration I2]

   Anchor detection (the completeness input to step 3) is bilingual keyword-based (English + Chinese; aliases in constraints.json → anchor_detection, ADR #15). It is a heuristic: the normalizer tags anchors_meta.source = normalizer-extracted, so an undetected anchor degrades to a coverage note — never a Blocker (ADR #12, rule 4). For a doc the keyword map under-detects (unusual terminology, a language beyond the aliases), author-supply the anchors map instead: set plan_model.anchors directly and anchors_meta.source = author-supplied — that map is authoritative, so a missing required anchor becomes a real Blocker (the honest, strong input for the inner ring).

3. Constraints-check (inner ring, deterministic over the plan-model) — run the artifact's constraints-profile: completeness (anchors), authority-chain, ODP-tracker, and (for research) sources-cited / staging / cost-bounded / provenance. For the research activity, multi-source web gathering is dispatched to the solidforge:researcher agent (it returns the research sub-object; the loop places it into plan_model["research"]); the constraints-checker then converges it. Profiles live in a registry (constraints.json), not hardcoded. [iterations I3, I4]
4. Adversarial review (outer ring) — independent solidforge:plan-reviewer finds gaps / over-engineering / contradictions / blind spots. [iteration I5]
5. Verdict — process_converged (high confidence) + rightness: human_confirm_required (constant). [iteration I6]
6. Freeze — frozen plan-model (round-trip-compatible with parallel-development plan_queue.py on the executable subset) + spec run-record. [iteration I7]

Current build status

This is the I0 scaffold. Loaded and routing-correct; the operators above are built across I2–I7. What exists now:

• This SKILL.md (activation boundary + scope guard + routing to the design docs).
• The plan-model handshake contract: schema + round-trip assertion with plan_queue.py on the executable subset (iteration I1, ADR #1).
• The outer-ring solidforge:plan-reviewer agent + findings schema + precision self-check (iteration I5; the agent definition is the deliverable; precision is an LLM eval, not a deterministic gate — ADR #10).
• The normalizer: heterogeneous source format (Cursor .plan.md / rich md / work-package) → plan-model with graded extraction (latch high-confidence / prose semantic-infer low-confidence). Heuristics advisory, never a Blocker (rule 4). Anchor detection is bilingual keyword-based (English + Chinese; ADR #15); an undetected anchor degrades to coverage (ADR #12), or author-supply the map for an authoritative check.
• The constraints-checker: inner-ring deterministic gate over the plan-model (anchors + authority-chain + resolve-now ODP), profiles in a registry (constraints.json), not hardcoded (rule 2).
• The research constraints-profile: the v1 subset (sources-cited / staging-via-convergence / cost-bounded = Blocker; provenance-tag = warning), modeled on fedaot-kb (ADR #4).
• The verdict-emitter + spec run-record: two-field verdict (process_converged + rightness: human_confirm_required constant), field-isolated — a green process axis never changes the outcome-axis constant.

All iterations I0–I7 converged (process-axis acceptance gate, iteration-plan §6, met): normalize → constraints-check → research-constraints → solidforge:plan-reviewer → verdict → freeze, end-to-end (produce + defect-repair + round-trip proven in end_to_end.py). The skill is at the process-axis acceptance gate; content correctness stays outcome axis (human).

Authority Chain

• docs/arch-design.md = authoritative spec.
• docs/iteration-plan.md = execution blueprint (on conflict, arch-design wins).
• docs/design-decisions.md = decision log (ADRs).

Self-Checks (Definition of Done)

A skill change is not done while any self-check fails (workspace rule 1). Run before commit:

python3 skills/blueprint-crafting/infra/test/trigger_check.py      # bidirectional activation boundary
python3 skills/blueprint-crafting/infra/test/disconnect_check.py   # structure + loading-chain
python3 skills/blueprint-crafting/infra/test/plan_model_schema.py  # plan-model schema validator (self-tests)
python3 skills/blueprint-crafting/infra/test/round_trip.py         # executable-subset round-trip with plan_queue.py
python3 skills/blueprint-crafting/infra/test/plan_reviewer_precision.py  # plan_reviewer scaffolding gate (I5; precision eval is LLM, ADR #10)
python3 skills/blueprint-crafting/infra/test/normalizer_goldens.py       # 3-format normalizer goldens (I2; latch vs semantic-infer)
python3 skills/blueprint-crafting/infra/test/constraints_check_goldens.py # constraints-checker: 6 exemplars pass, anchor/authority fail (I3)
python3 skills/blueprint-crafting/infra/test/research_constraints_goldens.py # research v1: sources/staging/cost Blocker, provenance warning (I4)
python3 skills/blueprint-crafting/infra/test/run_record_schema.py  # run-record schema validator (I6)
python3 skills/blueprint-crafting/infra/test/run_record.py         # verdict field-isolation: rightness constant (I6)
python3 skills/blueprint-crafting/infra/test/end_to_end.py         # capstone: produce + converge + defect-repair + round-trip (I7)
python3 skills/blueprint-crafting/infra/test/freeze_goldens.py     # freeze operator: emits a pd-parseable .queue.md + schema-valid .run-record.json (Unit 3)
python3 skills/blueprint-crafting/infra/test/produce_goldens.py    # produce.py orchestrator: one-command convergence (inner -> verdict -> freeze) + --outer + defect/research
python3 skills/blueprint-crafting/infra/test/lint_self.py          # dogfood: lints this skill's own infra (ruff check + format; mirrors the fast_gate)

Coordination with parallel-development

• Handshake: the executable subset of the plan-model (item_id / seq / depends_on / dod_ref) is round-trip-compatible with plan_queue.py's Phase −1 frozen queue. NOT globally isomorphic — upstream-only metadata is tagged and ignored downstream; downstream-only blueprint_subset is left empty / "downstream-filled" (ADR #1).
• Spec AC seam (Option A, bc ADR #2): the spec's acceptance-criteria entries carry — seam: <public-boundary-name> tails (AC-ENTRY shape defined in arch-design.md §3 product spec); parallel-development LATCHES the declared seam at Phase-0 derivation (derive only when absent — its intent-blueprint.md rich path).
• Spec re-open (pd wrong-seam escalation): when parallel-development escalates a declared-but-wrong seam (its blueprint-defect flag or its pre-freeze refusal report, naming the spec AC), the frozen spec re-enters this skill's convergence loop as a REVISION, with three stated semantics —
  1. TRIGGER: a pd-side wrong-seam escalation naming the spec AC.
  2. RE-OPEN: the existing run-record gains a re-open entry in its coverage/caveats string-array fields (the schema is closed; no schema change); the FULL loop re-runs on the corrected spec — re-normalize (corrected spec markdown → regenerated plan-model.json; produce.py takes an already-authored plan-model, not the spec), produce.py re-runs, convergence re-checks; the spec version bump rides a spec-version: line at the spec top (the convention this clause introduces — bc's docs carry no frontmatter today; the CONSUMER is the pd re-latch agent reading the spec text).
  3. PROPAGATION: the corrected spec propagates to the running pd task via its authority_chain re-read at the re-latch. Structural invariant: the correction is seam-local — the re-frozen .queue.md must be structurally identical; if the re-convergence diverges structurally, pd's queue Revision Channel + plan_queue.py sync is the named fallback (pd's path, not this skill's). A refactoring spec's ACs DECLARE the seam from the locked tests' observed boundary (the spec-declares principle extended — not pd's derive fallback).
• Coupling mode (independence): this skill copies parallel-development's patterns (disconnect_check, schema/validator, plan-queue parse) and does NOT import its code (workspace rule 7). Deleting parallel-development/ leaves this skill working standalone.
• files_touched boundary: this skill owns blueprint-crafting/; it does not write into parallel-development/. The two couple via an artifact (the frozen plan-model), not via file mutation.

Reference Files

• arch-design.md - authoritative architecture spec (positioning, dual-ring over documents, artifact contract × constraints-profile, core operators, convergence stop condition, coordination with parallel-development)
• iteration-plan.md - execution blueprint (iterations I0–I7, complexity tiers, dependency DAG, validation gates, process-axis acceptance gate)
• design-decisions.md - ADR log (executable-subset round-trip, determinism over the model, constrained production, research constraints-profile, skill name, single-skill-with-modes, research v1 subset)