buildr-workspace-architect

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

Trigger	This Skill?	Instead Use
New project description via advanced operator	YES	—
Resume an existing workspace	NO	buildr-executor
Execute a generated workspace	NO	buildr-executor
Create a vault item	NO	buildr-smith
Research an external source	NO	buildr-scout
Direct operator invocation (basic/legacy path)	NO	buildr-operator

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

Phase	Markdown	JSON	Produced By
1	PREFLIGHT_PURPOSE.md	PREFLIGHT_PURPOSE.json	Purpose Extraction
2	PREFLIGHT_ABSENCE_MAP.md	PREFLIGHT_ABSENCE_MAP.json	Absence Mapping
3	PREFLIGHT_ARCHITECTURE.md	PREFLIGHT_ARCHITECTURE.json	Minimal-Inevitable Architecture
3	PREFLIGHT_ACCEPTANCE.md	PREFLIGHT_ACCEPTANCE.json	Acceptance Criteria Packaging
4	PREFLIGHT_CHALLENGE.md	PREFLIGHT_CHALLENGE.json	Skeptical Challenge
4	PREFLIGHT_DECISIONS.md	PREFLIGHT_DECISIONS.json	Decision Record
5	PREFLIGHT_APPROVAL.md	PREFLIGHT_APPROVAL.json	Approval Synthesis
5	PREFLIGHT_BUILD_ORDER.md	—	Build Order

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.

Category	What to examine
security_abuse_and_threats	AuthZ/AuthN model, tenancy boundaries, secrets management, injection surfaces, abuse vectors
privacy_and_data_governance	PII handling, data retention, deletion rights, jurisdictional constraints, consent model
payments_and_money_movement	Payment processing, refunds, disputes, currency handling, financial compliance
operational_reliability	SLO expectations, disaster recovery, backup strategy, monitoring hooks (as requirements, not implementation)
accessibility_and_inclusive_design	WCAG level, assistive technology support, responsive requirements (if user-facing UI exists)
legal_and_policy_constraints	Licensing, export controls, industry-specific regulations, terms of service requirements

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 followi

---

Content truncated.