Imported from robwestz/BlLdR (skills/buildr-workspace-architect/SKILL.md). Install upstream with npx skills add robwestz/BlLdR --skill buildr-workspace-architect. Copyright stays with the author.

Buildr Workspace Architect

What This Skill Does

Takes a human project description and runs a mandatory five-phase architecture pipeline that produces structured artifacts. These artifacts gate workspace generation: no workspace may be created unless this skill outputs PREFLIGHT_APPROVAL.json with status: approved.

What This Skill Does NOT Do

• It does not generate workspaces (that is operator-like generation).
• It does not execute workspaces (that is buildr-executor).
• It does not replace the operator pipeline — it precedes it.
• It does not make implementation decisions — it makes architectural commitments.
• It is not advisory — its approval gate is mandatory and blocking.

Why This Is a System Skill

This skill orchestrates a multi-phase pipeline that gates a critical system boundary (workspace generation). It cannot be expressed as a vault item because:

• Vault items are single-purpose, self-contained instructions (max 60 lines for skills).
• This pipeline requires five sequential phases with inter-phase dependencies, binary gates, and structured artifact generation.
• It governs the system itself, not a task within a project.
• It satisfies the governance classification: "a system-level pipeline for orchestrating the Buildr system itself."
• It avoids the "Comfortable Package" anti-pattern: removing this skill would leave workspace generation ungated — a material regression in output quality. See references/architecture.md for the full justification.

Trigger Rules

This skill activates exclusively for new workspace-generation requests in the advanced flow. It never competes with executor, smith, or scout triggers.

Required Inputs

• project_description: The full human project description (string, non-empty).
• project_slug: Derived by the advanced operator per slug rules (string, [a-z0-9-], max 64 chars).

Staging Path

All artifacts are written to:

v2/.buildr/preflight/<project-slug>/

Output Artifacts

Both formats are required because:

• Markdown is for human review, discussion, and audit trail.
• JSON is for machine consumption: future forge/bridge validation, automated checks, and programmatic ingestion into workspace generation.

The Pipeline

Phase 1: PURPOSE EXTRACTION
    |  Gate: all CRI fields populated, >= 1 purpose claim
    v
Phase 2: ABSENCE MAPPING
    |  Gate: all 6 ELS categories addressed, no unaddressed unknowns
    v
Phase 3: MINIMAL-INEVITABLE ARCHITECTURE
    |  Gate: N >= max(5, ceil(purpose_claims * 2)) acceptance criteria
    v
Phase 4: SKEPTICAL CHALLENGE
    |  Gate: all decisions have >= 2 alternatives, no ungated high-risk decisions
    v
Phase 5: APPROVAL SYNTHESIS
    |  Gate: all prior gates passed, status is approved|rejected|insufficient_information
    v
Output: PREFLIGHT_APPROVAL.json

Phase 1: Purpose Extraction

Objective

Extract the project's purpose from the human description and freeze it as structured, testable claims. Separate what the project IS from what the project DOES from who the project SERVES.

Required Inputs

• project_description (the human's words, unmodified)

Process

1. Read the full project description without filtering.
2. Extract purpose claims: discrete, testable statements about what the project must achieve. Each claim must be falsifiable — you could build a test that either passes or fails.
3. Extract CRI (Commercial Reality Invariants):
   • target_customer_or_user_class: Who uses this? Be specific. "Users" is not acceptable.
   • primary_user_job_to_be_done: One sentence. What job does the user hire this product to do?
   • business_outcome_hypothesis: What measurable outcome improves if this succeeds?
   • monetization_model: One of none | subscription | usage | transaction_fee | ads | enterprise_contract | other. If the intent is clearly for-profit but monetization is unspecified, set to unknown.
   • must_have_constraints: Time, budget, compliance constraints. Each marked user_stated or unknown.
   • kill_switch_triggers: Binary conditions that should stop the project entirely (e.g., "if we cannot process payments within 4 weeks, stop").
4. Identify explicit assumptions: what the description takes for granted.
5. Identify explicit exclusions: what the description rules out.
6. Identify provisional scope: what the description implies but does not confirm.

Mandatory Questions to Resolve

• Is the purpose singular or compound? If compound, can it be decomposed?
• Are there implicit users not named in the description?
• Does the description contain contradictions?
• Are there unstated commercial constraints?

Written Outputs

• PREFLIGHT_PURPOSE.md: Narrative purpose extraction with CRI summary.
• PREFLIGHT_PURPOSE.json: Structured payload per preflight-handoff.schema.json, including all CRI fields.

Completion Condition (binary)

Phase 1 is COMPLETE when ALL of the following are true:

• At least one purpose_claim exists and is falsifiable.
• target_customer_or_user_class is populated and not "users" or "everyone."
• primary_user_job_to_be_done is a single sentence.
• business_outcome_hypothesis is populated.
• monetization_model is populated (may be unknown — triggers gate in Phase 5).
• Both .md and .json artifacts are written to staging.

Fail Conditions

• Zero extractable purpose claims from the description.
• Description is too vague to identify even one target user class.
• Description contains irreconcilable contradictions that cannot be flagged as known unknowns.

If Phase 1 fails: write PREFLIGHT_PURPOSE.json with status: insufficient_information and required_missing_inputs listing what is needed. The pipeline terminates — no downstream phases run.

What Phase 2 May Trust

• purpose_claims are stable (will not be revised by later phases unless preflight is reopened).
• target_customer_or_user_class is stable.
• assumptions and exclusions are provisional — Phase 2 may add to them but not remove confirmed ones.
• monetization_model value is frozen — downstream phases may flag it but not change it.

Phase 2: Absence Mapping

Objective

Systematically identify what is NOT in the project description: missing information, unstated assumptions, known unknowns, and expensive-late-failure risks. This phase makes the invisible visible.

Required Inputs

• PREFLIGHT_PURPOSE.json (Phase 1 output)
• project_description (original)

Process

1. Read Phase 1 outputs.
2. For each purpose_claim, ask: what information is needed to build this that the description does not provide?
3. For each assumption, ask: what happens if this assumption is wrong?
4. Run the Expensive-Late-Failure Scan (ELS) across all six mandatory categories.
5. Classify each absence as:
   • derivable: Can be inferred with high confidence from context (e.g., location implies payment provider).
   • askable: Must be answered by the user before proceeding.
   • deferrable: Can be deferred to execution without architectural risk.
   • blocking: Cannot proceed without resolution; architecturally load-bearing.

ELS (Expensive-Late-Failure Scan)

Each of the following six categories MUST be addressed. Use not_applicable only with a one-line proof of why.

For each category, produce els_risks[] entries with:

• risk: What could go wrong.
• why_late_discovery_is_expensive: Concrete cost of discovering this late (rework hours, compliance fines, data breach).
• earliest_cheap_mitigation_stage: preflight | workspace_gen | execution.
• residual_open_risk: true if the risk cannot be fully mitigated at the identified stage.

Written Outputs

• PREFLIGHT_ABSENCE_MAP.md: Narrative absence map with ELS section.
• PREFLIGHT_ABSENCE_MAP.json: Structured payload per schema, including els_risks[].

Completion Condition (binary)

Phase 2 is COMPLETE when ALL of the following are true:

• Every purpose_claim from Phase 1 has at least one associated absence check (even if the result is "no gaps found").
• All six ELS categories are addressed (each with at least one entry or an explicit not_applicable with proof).
• Every identified absence is classified (derivable | askable | deferrable | blocking).
• No blocking absence remains without being escalated to required_missing_inputs.
• Both .md and .json artifacts are written to staging.

Fail Conditions

• One or more blocking absences exist that cannot be resolved through derivation.
• The description lacks enough substance to even map absences meaningfully.

If Phase 2 fails due to blocking absences: write PREFLIGHT_ABSENCE_MAP.json with all identified absences. Write PREFLIGHT_APPROVAL.json with status: insufficient_information and required_missing_inputs listing the blocking items. The pipeline terminates.

ELS Binary Gate

If residual_open_risk: true for ANY item under payments_and_money_movement or privacy_and_data_governance: Phase 5 cannot set status to approved UNLESS:

• Status is set to insufficient_information, OR
• User-explicit acceptance is recorded in PREFLIGHT_DECISIONS.json with owner_of_decision: user_explicit.

What Phase 3 May Trust

• The absence map is comprehensive within the limits of the available description.
• ELS categories have been addressed — Phase 3 does not re-scan.
• derivable absences may be resolved by Phase 3 through architectural decisions (recorded in decisions).
• blocking absences, if any survived, have already terminated the pipeline.

Phase 3: Minimal-Inevitable Architecture

Objective

Define the smallest set of architectural components that satisfies ALL purpose claims while respecting ALL constraints from Phases 1-2. Nothing speculative. Nothing optional. Only what is inevitable given the approved purpose.

Required Inputs

• PREFLIGHT_PURPOSE.json (Phase 1)
• PREFLIGHT_ABSENCE_MAP.json (Phase 2)

Process

1. Read Phase 1 and Phase 2 outputs.
2. For each purpose_claim, determine the minimum architectural components required to satisfy it.
3. Merge overlapping components — if two claims require the same component, it appears once.
4. For each component in the minimal set:
   • State why it is inevitable (which purpose claims require it).
   • State what happens if it is removed (which claims break).
   • Classify as core (required for any purpose claim) or supporting (required for integration/operation).
5. Define the non_goals list: components or capabilities explicitly excluded from the minimal set, with justification for each exclusion.
6. Produce the acceptance criteria package (see below).
7. Record any architectural decisions made in this phase in PREFLIGHT_DECISIONS.json.

Acceptance Criteria Packaging

Define acceptance criteria that become normative for later execution:

• Each criterion has a stable acceptance_id (format: AC-NNN).
• Each criterion is objectively verifiable: pass/fail, not subjective.
• Subjective checks ("looks good", "feels responsive", "seems accessible") are forbidden. Replace with measurable proxies:
  • "Routes exist and return 200" instead of "navigation works"
  • "Form submits data and returns confirmation" instead of "form looks right"
  • "Error states render for invalid input" instead of "errors are handled"
  • "Auth gate returns 401 for unauthenticated requests" instead of "auth is secure"
• Each criterion maps to at least one purpose_claim via purpose_claim_refs[].
• non_goals are listed: capabilities explicitly excluded from acceptance.

Minimum count rule: N >= max(5, ceil(number_of_purpose_claims * 2)). If this minimum cannot be met, Phase 3 fails.

UI quality rule: If any criterion references UI quality, it must specify measurable proxies (routes exist, forms submit, error states render, auth gates enforce). Exception: projects explicitly marked as non-UI in CRI.

Written Outputs

• PREFLIGHT_ARCHITECTURE.md: Narrative architecture with minimal-inevitable set and justifications.
• PREFLIGHT_ARCHITECTURE.json: Structured payload per schema.
• PREFLIGHT_ACCEPTANCE.md: Narrative acceptance criteria with mappings.
• PREFLIGHT_ACCEPTANCE.json: Structured payload per schema.

Completion Condition (binary)

Phase 3 is COMPLETE when ALL of the following are true:

• Every purpose_claim is satisfied by at least one component in the minimal-inevitable set.
• Every component has a justification (which claims require it, what breaks without it).
• non_goals list is populated (at least one exclusion, even if obvious).
• Acceptance criteria count meets minimum: N >= max(5, ceil(purpose_claims * 2)).
• Every acceptance criterion is objectively verifiable (no subjective language).
• Every acceptance criterion maps to at least one purpose_claim.
• All four artifacts (.md and .json for architecture and acceptance) are written to staging.

Fail Conditions

• A purpose_claim cannot be satisfied by any conceivable minimal component.
• Acceptance criteria minimum cannot be met even with generous interpretation.
• Two purpose claims require mutually exclusive architectural components with no resolution.

If Phase 3 fails: write artifacts with the failure documented. Write PREFLIGHT_APPROVAL.json with status: rejected and rejection_reasons. The pipeline terminates.

What Phase 4 May Trust

• The minimal-inevitable set is the proposed architecture — Phase 4 challenges it but does not redesign from scratch.
• Acceptance criteria are proposed — Phase 4 may flag criteria that are insufficient but does not rewrite them.
• Component justifications are available for challenge.

What Remains Provisional

• The minimal-inevitable set is provisional until it survives Phase 4 challenge.
• Acceptance criteria are provisional until Phase 4 confirms they are testable and sufficient.

Phase 4: Skeptical Challenge

Objective

Challenge every architectural commitment from Phase 3. For each component in the minimal-inevitable set, demand justification. For each exclusion, demand proof it is safe to exclude. Surface decisions that carry high reversal cost. Record all decisions formally.

Required Inputs

• PREFLIGHT_PURPOSE.json (Phase 1)
• PREFLIGHT_ABSENCE_MAP.json (Phase 2)
• PREFLIGHT_ARCHITECTURE.json (Phase 3)
• PREFLIGHT_ACCEPTANCE.json (Phase 3)

Process

1. Read all prior phase outputs.
2. For each component in the minimal-inevitable set:
   • Challenge: "Is this truly inevitable, or merely conventional?"
   • Challenge: "Could the purpose claims be satisfied without this component?"
   • Challenge: "Does this component introduce complexity disproportionate to its purpose?"
3. For each exclusion in non_goals:
   • Challenge: "Is this exclusion safe, or does it create a latent risk?"
   • Challenge: "Will a user reasonably expect this capability?"
4. For each ELS risk with residual_open_risk: true:
   • Challenge: "Is the mitigation plan sufficient, or is the risk being minimized?"
5. Produce decision records for every significant architectural commitment.

Decision Record Requirements

For each major architectural commitment, record:

• decision_id: Stable identifier (format: DEC-NNN).
• decision_statement: One sentence, testable (e.g., "The system uses PostgreSQL as the primary datastore").
• alternatives_considered: At least two real alternatives (not strawmen). Each must be a genuinely viable option.
• rejection_rationale_per_alternative: Specific, causal reason for rejecting each alternative. Not "it's worse" — why specifically.
• selected_rationale: Why the chosen option is correct, tied to purpose_claims and minimal_inevitable_set.
• reversibility_cost_if_wrong: low | medium | high with a concrete reason (e.g., "high: requires full data migration and schema rewrite").
• owner_of_decision: user_explicit | inferred_high_confidence | inferred_low_confidence.

Challenge-Loop Rule

One challenge pass only. Phase 4 performs exactly one challenge pass over Phase 3 outputs.

• Items that survive challenge: confirmed and recorded in decisions.
• Items that fail challenge: recorded as open_risks or adjusted in the architecture (adjustment recorded in decisions with rationale).
• Unresolved items: carried forward as known_unknowns with explicit open_risks entries into Phase 5.

No iteration between Phase 3 and Phase 4. The cost of one thorough challenge pass is lower than unbounded iteration. The architecture at this stage is minimal-inevitable, not optimal — further iteration optimizes prematurely. If the challenge reveals fundamental flaws, the correct response is rejected, not more iteration.

Decision Record Binary Gate

Phase 5 CANNOT approve if:

• Any decision has reversibility_cost_if_wrong: high AND owner_of_decision is NOT user_explicit, UNLESS there is a recorded known_unknowns entry with a mitigation plan tied to that decision_id.

Written Outputs

• PREFLIGHT_CHALLENGE.md: Narrative challenge results, organized by component.
• PREFLIGHT_CHALLENGE.json: Structured payload per schema.
• PREFLIGHT_DECISIONS.md: Narrative decision record with rationales.
• PREFLIGHT_DECISIONS.json: Structured payload per schema, array of decision records.

Completion Condition (binary)

Phase 4 is COMPLETE when ALL of the following are true:

• Every component in the minimal-inevitable set has been challenged.
• Every exclusion in non_goals has been challenged.
• Every ELS risk with residual_open_risk: true has been challenged.
• Every significant architectural commitment has a decision record.
• Every decision record has alternatives_considered with at least two entries.
• The decision record binary gate is satisfiable (no ungated high-risk decisions).
• All four artifacts are written to staging.

Fail Conditions

• The challenge reveals a fundamental flaw that cannot be resolved by adjusting the minimal set — the purpose itself is incoherent.
• A high-reversibility-cost decision has owner_of_decision: inferred_low_confidence and no mitigation plan exists.

If Phase 4 reveals fundamental flaws: record the flaws in challenge artifacts. Write PREFLIGHT_APPROVAL.json with status: rejected and rejection_reasons. The pipeline terminates.

What Phase 5 May Trust

• Components that survived challenge are confirmed.
• Decision records are complete and gated.
• Open risks are explicitly documented with mitigation plans where available.

What Remains Provisional

• Nothing is provisional after Phase 4. All architectural commitments are either confirmed, adjusted, or flagged as open risks.

Phase 5: Approval Synthesis

Objective

Synthesize all phase outputs into a final approval determination. Verify all binary gates from prior phases. Produce the approval artifact that gates workspace generation.

Required Inputs

• All artifacts from Phases 1-4.

Process

1. Verify Phase 1 gate: All CRI fields populated, at least one purpose claim.
2. Verify Phase 2 gate: All six ELS categories addressed.
3. Verify Phase 2 ELS gate: No residual_open_risk: true under payments_and_money_movement or privacy_and_data_governance without user-explicit acceptance or insufficient_information status.
4. Verify Phase 3 gate: Acceptance criteria count meets minimum.
5. Verify Phase 4 decision gate: No ungated high-risk decisions.
6. Verify CRI monetization gate: If monetization_model: unknown for a clearly for-profit intent, status must be insufficient_information unless explicitly excluded via non_goals with user-explicit acknowledgment.
7. Compile approval_basis: the set of evidence supporting the determination.
8. Compile open_risks: risks acknowledged but accepted.
9. Compile non_goals: capabilities explicitly excluded.
10. Determine status: approved | rejected | insufficient_information.
11. If approved: produce PREFLIGHT_BUILD_ORDER.md with recommended execution sequencing.

Status Determination Rules

approved when:

• All Phase 1-4 binary gates pass.
• approval_basis is non-empty.
• No blocking absences remain.
• All CRI constraints are satisfied or explicitly deferred with user acceptance.
• The minimal-inevitable set survived challenge.

rejected when:

• Any phase produced irreconcilable contradictions.
• The purpose is incoherent or internally contradictory.
• A mandatory architectural component is impossible given stated constraints.
• Challenge revealed fundamental flaws with no resolution path.

insufficient_information when:

• Blocking absences remain that require user input.
• CRI fields cannot be populated from the available description.
• monetization_model: unknown for clearly for-profit intent without explicit exclusion.
• ELS risks under payments_and_money_movement or privacy_and_data_governance have residual_open_risk: true without user-explicit acceptance.

Written Outputs

• PREFLIGHT_APPROVAL.md: Narrative synthesis with determination rationale.
• PREFLIGHT_APPROVAL.json: Structured payload per schema. Must include:
  • status: approved | rejected | insufficient_information
  • approval_basis: Non-empty array of evidence strings (if approved).
  • rejection_reasons: Array of specific reasons (if rejected).
  • required_missing_inputs: Array of missing items (if insufficient_information).
  • open_risks: Array of acknowledged risks.
  • non_goals: Array of excluded capabilities.
  • minimal_inevitable_set: Array of confirmed architectural components.
  • allowed_next_step: workspace_generation | rerun_preflight | user_input_required | project_cancelled.
• PREFLIGHT_BUILD_ORDER.md (only if approved): Recommended build order based on architectural dependencies, component criticality, and risk mitigation priority.

Completion Condition (binary)

Phase 5 is COMPLETE when ALL of the following are true:

• All prior phase gates have been explicitly verified (not assumed).
• status is one of the three valid values.
• If approved: approval_basis is non-empty and allowed_next_step is workspace_generation.
• If rejected: rejection_reasons is non-empty and allowed_next_step is rerun_preflight or project_cancelled.
• If insufficient_information: required_missing_inputs is non-empty and allowed_next_step is user_input_required.
• Both .md and .json artifacts are written to staging.
• PREFLIGHT_BUILD_ORDER.md exists if and only if status is approved.

Fail Conditions

Phase 5 itself does not fail — it produces one of three valid statuses. If the synthesis process encounters an internal inconsistency (e.g., all gates pass but no approval basis can be stated), this indicates a bug in a prior phase. In this case, set status: rejected with rejection_reasons describing the internal inconsistency.

Git, Retention, and Immutability Rules

Gitignore

v2/.buildr/ SHOULD be added to .gitignore by default. It is a runtime staging area.

Exception for audit trails: If the team requires reproducible evidence of preflight decisions, the following files MAY be committed:

• PREFLIGHT_APPROVAL.json
• PREFLIGHT_DECISIONS.json
• PREFLIGHT_ACCEPTANCE.json

This is a team-level decision, not a system default. The default is gitignored.

Retention

• Reruns for the same slug (non-approved): Overwrite all existing artifacts in the directory.
• Reruns for a slug with approved artifacts: Create a new directory with timestamp suffix per collision handling rules. The original approved artifacts are preserved.
• Abandoned runs: Cleaned up on next run for the same slug (overwrite rule applies). No automatic cleanup otherwise.

Immutability

• After status: approved: All artifacts in the staging directory are immutable. They may not be modified unless preflight is explicitly reopened (new run with a new timestamped slug, or user-triggered reopen).
• Reopening preflight: Requires explicit user action. Creates a new run. The previous approved artifacts are preserved under their original slug (or timestamped variant).
• After status: rejected or insufficient_information: Artifacts are mutable — they will be overwritten on the next run for the same slug.

Canonical Reference

• Execution procedure: This file (SKILL.md).
• Machine-readable contract: references/preflight-handoff.schema.json.
• Phase depth and anti-patterns: references/phases.md.
• Contract explanations: references/contracts.md.
• Approval semantics: references/approval.md.
• System placement justification: references/architecture.md.
• Operator integration: references/integration-with-operator.md.
• Ground repository backlog (schemas, validation, ingest, vault, docs): ../../improve.md (repo path v2/improve.md). Optional; run after v2 files exist — does not change preflight procedure.

SKILL.md is authoritative for procedure. The schema is authoritative for payload structure. Reference files provide depth and justification but do not override either.