@geraldmaron/construct 1.2.1 → 1.2.2

package/templates/docs/prds/templates/_template.md

@@ -0,0 +1,206 @@
+# PRD: {title}
+
+- **Date**: {YYYY-MM-DD}
+- **Owner**: {name}
+- **Status**: draft | in-review | approved | shipped | deprecated
+
+<!--
+Use this for a product capability, user workflow, or customer-facing requirement set.
+Use meta-prd.md instead when defining the requirements for a product system, agent,
+process, template, evaluation loop, or operating model.
+
+Before drafting, read rules/common/framing.md.
+
+Owning specialist: cx-product-manager (see rules/common/doc-ownership.md).
+Construct must route PRD authoring to cx-product-manager rather than drafting directly.
+doing so is how requirements traceability, user grounding, and external research fire.
+
+Write with a balance of short paragraphs, tables, and bullets. Bullets are for scans,
+not the whole document. Keep em dashes rare; prefer commas, periods, or parentheses.
+-->
+
+## Summary
+<!--
+One paragraph (3-5 sentences) that a busy reader can use as the whole PRD.
+What the change is, who it's for, why now, and what changes when it ships.
+No solutions in this section that aren't decided. No ticket IDs. No team names.
+-->
+
+## Background
+<!--
+Context the reader needs to evaluate this PRD without asking around.
+Include relevant prior work (linked PRDs, ADRs, RFCs), observed signals, and
+the current state of the user experience or system. State what is already
+true today so the reader can compare against the proposed change.
+
+Cite evidence: support tickets, interviews, telemetry, sales calls, research.
+Avoid roadmap-speak ("this is a Q3 priority"); state what is happening to users.
+-->
+
+## Problem
+<!--
+The specific user or business outcome that is currently blocked. One or two
+paragraphs. State the pain, not the solution.
+
+Must NOT reference:
+- Jira / Linear ticket IDs or "this came from ticket X"
+- Roadmap items, OKR line items, or quarterly goals
+- "The team decided we should build this"
+
+Must reference:
+- Observed user behavior, quantitative signals, or qualitative evidence
+- The specific outcome that is not currently achievable
+- The constraint that makes this non-trivial today
+-->
+
+## Goals
+<!--
+What success looks like, in outcome terms. Three to five goals max. Each
+goal is the *change* you want, not the activity. Order by importance.
+
+Examples:
+- Reduce p95 onboarding time from 12m to under 4m for new accounts.
+- Eliminate the manual reconciliation step our top 20 customers do every Monday.
+- Halve the support volume for "where is my data" questions.
+-->
+
+## Outcome
+<!--
+What is concretely different for users, the business, or the system once this
+ships and is adopted. This is the observable end state: written from the
+user's perspective when possible. The acceptance criteria below should be the
+falsifiable evidence that this outcome was achieved.
+
+A reader should be able to compare the current state (Background) to this
+section and see the delta in plain language.
+-->
+
+## User flow
+
+```mermaid
+flowchart TD
+  A[User starts] --> B{Current friction?}
+  B -->|Yes| C[Proposed path]
+  B -->|No| D[Existing path]
+  C --> E[Success outcome]
+  D --> E
+```
+
+## In scope and out of scope
+
+| | Description |
+|---|---|
+| **In scope** | <what this PRD covers and commits to ship> |
+| **Out of scope** | <related work explicitly deferred: name the reason> |
+| **Adjacent (deferred)** | <work that's a natural follow-up but not in this PRD> |
+
+<!--
+Be specific. "Authentication" is too vague; "OAuth login for the web dashboard,
+not for the CLI" is right. The Out of scope list is a tool for protecting
+schedule and reviewer attention: use it.
+-->
+
+## Phases
+
+<!--
+Phases are how this work ships, not how it's organized internally. Each phase
+is independently shippable and provides observable user value (or a clearly
+defined platform capability). Avoid "phase 1: backend, phase 2: frontend".
+that's a task list, not a phasing.
+
+Each phase below holds its own goal, status, functional requirements (FR),
+and non-functional requirements (NFR), with acceptance criteria written
+inline next to each requirement. Use `FR-<phase>.<n>` and `NFR-<phase>.<n>`
+so requirements can be referenced from reviews and tests.
+
+Status values: not started | in progress | shipped | deferred.
+
+NFR categories to consider: performance, reliability, security, privacy,
+accessibility, observability, compliance, cost. Numeric targets where possible.
+-->
+
+### Phase 1: <name>
+
+- **Goal**: <what this phase delivers>
+- **Status**: not started
+
+**Functional**
+
+- **FR-1.1**: <imperative statement of what the system must do>
+  - *Acceptance*: <observable, falsifiable condition a reviewer can check without asking the author>
+- **FR-1.2**: <...>
+  - *Acceptance*: <...>
+
+**Non-functional**
+
+- **NFR-1.1**: <category>: <target with number>
+  - *Acceptance*: <how this is measured and what counts as pass>
+
+### Phase 2: <name>
+
+- **Goal**: <what this phase delivers>
+- **Status**: not started
+
+**Functional**
+
+- **FR-2.1**: <...>
+  - *Acceptance*: <...>
+- **FR-2.2**: <...>
+  - *Acceptance*: <...>
+
+**Non-functional**
+
+- **NFR-2.1**: <category>: <target>
+  - *Acceptance*: <...>
+
+### Phase 3: <name>
+
+- **Goal**: <what this phase delivers>
+- **Status**: not started
+
+**Functional**
+
+- **FR-3.1**: <...>
+  - *Acceptance*: <...>
+
+**Non-functional**
+
+- **NFR-3.1**: <category>: <target>
+  - *Acceptance*: <...>
+
+## Success metrics
+<!--
+How we will know this worked in production over time, beyond the per-requirement
+acceptance criteria. Leading vs. lagging. Avoid vanity metrics.
+-->
+
+| Metric | Baseline | Target |
+|---|---|---|
+| {name} | {current} | {goal} |
+
+## Constraints
+<!--
+Budget, timeline, platform, team, legal, technical debt: anything that shapes
+the solution and isn't a requirement.
+-->
+
+## Dependencies
+<!--
+Teams, services, contracts, data sources, vendor timelines. Each dependency
+should name an owner and the date it must be ready by.
+-->
+
+## Risks and mitigations
+
+| Risk | Likelihood | Impact | Mitigation |
+|---|---|---|---|
+| <risk> | low / med / high | low / med / high | <how this is reduced or what we accept> |
+
+## Open questions
+
+| Question | Owner | Decision needed by |
+|---|---|---|
+| <unknown> | <name> | <YYYY-MM-DD> |
+
+## References
+<!-- Linked research, prior PRDs, ADRs, tickets, designs. -->

package/templates/docs/prds/templates/meta-prd.template.md

@@ -0,0 +1,177 @@
+# Meta PRD: {title}
+
+- **Date**: {YYYY-MM-DD}
+- **Owner**: {name}
+- **Status**: draft | in-review | approved | shipped | deprecated
+
+<!--
+Use this when the subject is the product operating system itself: an agent workflow,
+document standard, evidence pipeline, evaluation loop, template family, governance
+process, or internal product intelligence capability.
+
+A normal PRD defines what a product capability must do for users. A Meta PRD defines
+how the organization decides, documents, validates, and improves the product work.
+
+Write with a balance of structured paragraphs, compact tables, and selective bullets.
+Avoid a wall of bullets. Keep em dashes rare; prefer commas, periods, or parentheses.
+-->
+
+## Summary
+<!--
+One paragraph (3-5 sentences). What product practice or operating system is
+being defined or changed, who runs it, and what becomes different about how
+the org decides, documents, or evaluates work once this ships.
+-->
+
+## Background
+<!--
+The current state of the operating system: which workflow, template, eval
+loop, or governance process is in play today, and what's actually happening
+when teams or agents use it. Cite real examples: recent PRDs, prior decisions,
+trace evidence, support tickets: not hypotheticals.
+-->
+
+## Problem
+<!--
+The failure mode in the current process. Name who feels it, how often, and
+what breaks downstream. Keep solutions out of this section.
+
+Examples of the right shape:
+- "PRDs ship without rejected alternatives, so reviewers re-litigate decisions
+  three weeks in. Happens on ~40% of PRDs in the last quarter."
+- "Postmortems are written by the on-call who shipped the bug, so the action
+  items reflect their proposals: not independent review."
+-->
+
+## Goals
+<!--
+What success looks like for the operating system. Three to five outcomes max.
+Examples: "PRDs cite primary sources by default", "Postmortems get peer
+review before publish", "ADR rejection rate drops from 60% to under 20%".
+-->
+
+## Outcome
+<!--
+What is concretely different about how work moves through the org once this
+operating model is adopted. Written from the practitioner's perspective:
+"When I open a PRD, I'm prompted to record rejected alternatives before
+the doc enters review."
+-->
+
+## In scope and out of scope
+
+| | Description |
+|---|---|
+| **In scope** | <which templates, workflows, agents, gates, or evals are touched> |
+| **Out of scope** | <related operating systems explicitly deferred: name the reason> |
+| **Adjacent (deferred)** | <natural follow-up changes not in this Meta PRD> |
+
+## Principles
+<!--
+Durable rules this operating system must preserve across phases. Each
+principle should be testable enough to guide tradeoffs when phases conflict.
+-->
+
+## Inputs and evidence
+<!--
+What evidence the system consumes: customer notes, interviews, traces, Jira
+issues, PRDs, research, analytics, support tickets, prior decisions. State
+minimum evidence thresholds where useful (e.g. "two independent customer
+interviews before a PRD enters review").
+-->
+
+## Phases
+
+<!--
+Each phase below holds its own goal, status, workflow requirements (MR),
+and document + evaluation requirements (DR), with acceptance criteria
+inline next to each. Use `MR-<phase>.<n>` and `DR-<phase>.<n>` so
+requirements can be referenced from reviews, traces, and evals.
+
+MR = Workflow requirement: how the process or agent workflow must behave;
+observable in generated artifacts, workflow state, or tool behavior.
+
+DR = Document + evaluation requirement: how outputs are shaped, reviewed,
+and scored; required sections, evidence rules, citation rules, formatting
+constraints, anti-patterns, rubric dimensions, pass/fail checks.
+
+Status values: not started | in progress | shipped | deferred.
+-->
+
+### Phase 1: <name>
+
+- **Goal**: <what this phase delivers>
+- **Status**: not started
+
+**Workflow**
+
+- **MR-1.1**: <imperative statement of how the workflow must behave>
+  - *Acceptance*: <how a reviewer or trace verifies this without asking the author>
+- **MR-1.2**: <...>
+  - *Acceptance*: <...>
+
+**Document + evaluation**
+
+- **DR-1.1**: <required section, evidence rule, citation rule, formatting constraint, or anti-pattern>
+  - *Acceptance*: <rubric dimension, pass/fail check, or trace signal that proves it>
+
+### Phase 2: <name>
+
+- **Goal**: <what this phase delivers>
+- **Status**: not started
+
+**Workflow**
+
+- **MR-2.1**: <...>
+  - *Acceptance*: <...>
+- **MR-2.2**: <...>
+  - *Acceptance*: <...>
+
+**Document + evaluation**
+
+- **DR-2.1**: <...>
+  - *Acceptance*: <...>
+
+### Phase 3: <name>
+
+- **Goal**: <what this phase delivers>
+- **Status**: not started
+
+**Workflow**
+
+- **MR-3.1**: <...>
+  - *Acceptance*: <...>
+
+**Document + evaluation**
+
+- **DR-3.1**: <...>
+  - *Acceptance*: <...>
+
+## Human approval gates
+<!--
+Where a person must review, approve, reject, or supply missing context before
+the system writes externally or treats a document as approved. Name the gate,
+the reviewer role, and the timeout policy if no reviewer responds.
+-->
+
+## Failure modes and mitigations
+
+| Failure mode | Likelihood | Impact | Mitigation |
+|---|---|---|---|
+| <how this could go wrong if followed too literally, over-automated, or used with weak evidence> | low / med / high | low / med / high | <guardrail or escape hatch> |
+
+## Rollout
+<!--
+How this operating model becomes the default. Migration steps, owners,
+training, deprecation date for the older template or workflow. Name what
+happens to in-flight work (grandfathered or migrated).
+-->
+
+## Open questions
+
+| Question | Owner | Decision needed by |
+|---|---|---|
+| <unknown that could change the operating model> | <name> | <YYYY-MM-DD> |
+
+## References
+<!-- Linked examples, prior PRDs, Meta PRDs, research, tickets, traces, or decisions. -->

package/templates/docs/prds/templates/prd-business.template.md

@@ -0,0 +1,61 @@
+# Business PRD: {title}
+
+- **Date**: {YYYY-MM-DD}
+- **Owner**: {name}
+- **Status**: draft | in-review | approved | shipped | deprecated
+
+<!--
+Use this for strategic bets, market positioning decisions, business model changes,
+partnership structures, pricing strategy, and make-vs-buy decisions.
+
+This is not a feature spec. It defines the bet, the market thesis, the alternatives
+rejected, and what would have to be true for this to work.
+
+Use prd.md for customer-facing product capabilities.
+Use prd-platform.md for internal platform and developer-facing capabilities.
+-->
+
+## The bet
+<!-- One or two sentences: what we are committing to and why now. This should be falsifiable. -->
+
+## Market thesis
+<!-- The one-paragraph view of market shape, buyer behavior, and where value accrues. Every decision in this document links back here or challenges it. -->
+
+## Problem and opportunity
+<!-- What is broken in the market or business today? What does the opportunity look like at full scale? State the pain and the size of the prize: with evidence. -->
+
+## Strategic goals
+<!-- What this decision achieves at the business level: position, revenue, defensibility, optionality. Tie to company objectives. -->
+
+## Alternatives rejected
+<!-- The other credible paths that were considered. For each: what it is, why it was rejected, and what would have to change to reconsider it. No strawmen. -->
+
+## What must be true
+<!-- The conditions that have to hold for this bet to pay off. Make them explicit so they can be monitored. -->
+
+## Competitive analysis
+<!-- For each relevant competitor: business model (unit economics, distribution, defensibility), not just feature surface. Avoid feature parity tables that ignore economics. -->
+
+## Make vs. buy vs. partner
+<!-- If applicable: the build/buy/partner tradeoffs with rationale. Include cost, control, speed, and strategic leverage. -->
+
+## Go-to-market implications
+<!-- Pricing, packaging, channels, positioning changes. What motion this requires from sales, marketing, or customer success. -->
+
+## Financial frame
+<!-- Revenue model, cost structure, expected unit economics. Include the range of outcomes, not just the upside case. -->
+
+## Kill criteria
+<!-- The leading indicator and the threshold at which this strategy is revisited or abandoned. Without this, bad bets survive longer than they should. -->
+
+## Risks
+<!-- Market, execution, regulatory, competitive, and technical risks. Rate each by likelihood and impact. State the mitigation or acceptance rationale. -->
+
+## Constraints
+<!-- Budget, timeline, team, regulatory, or partner dependencies that shape the scope of this decision. -->
+
+## Open questions
+<!-- Genuine unknowns. Each names an owner and a decision deadline. -->
+
+## References
+<!-- Market research, customer interviews, financial models, prior decisions, analyst reports, competitor filings. -->

package/templates/docs/prds/templates/prd-platform.template.md

@@ -0,0 +1,81 @@
+# Platform PRD: {title}
+
+- **Date**: {YYYY-MM-DD}
+- **Owner**: {name}
+- **Status**: draft | in-review | approved | shipped | deprecated
+
+<!--
+Use this for capabilities consumed by internal systems, developers, operators, or other
+services: not directly by end users. Covers APIs, SDKs, admin surfaces, data contracts,
+shared infrastructure, and operational tooling.
+
+Use prd.md instead for customer-facing product capabilities.
+Use meta-prd.md for requirements about the product operating system itself.
+
+Name the platform actor precisely: platform builder, application developer, security admin,
+operator. "Developer" is too broad.
+-->
+
+## Problem
+<!-- What is broken, missing, or blocking a platform actor or downstream system? One paragraph. State the operational or integration pain, not the solution. -->
+
+## Platform actors
+<!-- Who consumes this capability? Name roles precisely (app developer, ops engineer, data analyst, etc.). Include scale and current workaround. Cite evidence: tickets, incidents, support load. -->
+
+## Goals and non-goals
+<!-- Goals: what success looks like for the consumers. Non-goals: explicitly scoped out. -->
+
+## Platform flow
+
+```mermaid
+flowchart TD
+  A[Consumer] --> B[Platform API]
+  B --> C[Core service]
+  C --> D[Response / event]
+```
+
+## API and interface contract
+<!-- The surface being defined: endpoints, schemas, SDK methods, event payloads, config shapes, permission models. Number each contract item (C-1, C-2, …). -->
+
+## Functional requirements
+<!-- What the system must do. Number them (FR-1, FR-2, …). -->
+
+## Non-functional requirements
+<!-- Performance SLOs, reliability targets, security, compliance, scalability limits. Include numeric targets. -->
+
+## Backwards compatibility and versioning
+<!-- Is this a new contract or a change to an existing one? If a change: breaking vs. non-breaking, versioning strategy, and how existing consumers are supported. -->
+
+## Migration and rollout
+<!-- How consumers move to the new contract. Include migration steps, tooling, timeline, and who is responsible. Flag any coordination with downstream teams. -->
+
+## Operational requirements
+<!-- Observability (metrics, logs, traces), auditability, rate limits, failure modes, fallback behavior, support diagnostics, admin controls. These are product requirements, not afterthoughts. -->
+
+## Acceptance criteria
+<!-- Observable, falsifiable conditions a reviewer can check. Include integration and contract tests where relevant. -->
+
+## Success metrics
+<!-- How we know this worked: adoption, error rate, latency, support ticket reduction. Leading vs. lagging. -->
+
+| Metric | Baseline | Target |
+|---|---|---|
+| {name} | {current} | {goal} |
+
+## Risks and mitigations
+
+| Risk | Likelihood | Impact | Mitigation |
+|---|---|---|---|
+| {risk} | low / med / high | low / med / high | {mitigation} |
+
+## Consumer impact
+<!-- What changes for existing consumers. What breaks, what degrades, what stays the same. Link to migration guide if needed. -->
+
+## Dependencies
+<!-- Upstream services, data contracts, team availability, vendor timelines. -->
+
+## Open questions
+<!-- Genuine unknowns. Each question names an owner and a decision deadline. -->
+
+## References
+<!-- Linked designs, prior PRDs, ADRs, incidents, runbooks, tickets. -->

package/templates/docs/prds/templates/prfaq.template.md

@@ -0,0 +1,38 @@
+# PRFAQ: {title}
+
+- **Date**: {YYYY-MM-DD}
+- **Owner**: {name}
+- **Status**: draft | in-review | approved
+
+<!--
+Use for working-backwards product thinking. A PRFAQ can be generated from a PRD
+or directly from evidence, but it must not invent customer demand.
+-->
+
+## One-sentence summary
+<!-- One sentence for an executive reader. Name the audience and outcome. -->
+
+## Problem statement
+<!-- Two or three paragraphs grounded in evidence. Explain the customer problem, why now, and what is missing today. -->
+
+```mermaid
+flowchart LR
+  A[Customer need] --> B[Current workaround]
+  B --> C[Proposed capability]
+  C --> D[Outcome after launch]
+```
+
+## Press release
+<!-- Write as if the capability has shipped. Focus on customer outcome, not implementation. Include a spokesperson quote and a customer quote — mark a hypothetical quote as such; never invent an attributed one (rules/common/no-fabrication.md). -->
+
+## External FAQ
+<!-- Customer-facing questions and answers. Keep answers concrete and honest about limits. -->
+
+## Internal FAQ
+<!-- Questions from engineering, sales, support, security, finance, and leadership. Include unknowns as TBD with what would resolve them. Cover the launch/success metrics: what target defines success and by when. -->
+
+## Evidence appendix
+<!-- Source links, customer quotes, related issues, research, and PRDs. -->
+
+## Review tracking
+<!-- Reviewer, function, decision, date, and required follow-up. -->

package/templates/docs/rfcs/README.md

@@ -0,0 +1,22 @@
+---
+cx_doc_id: 019ddb68-5aed-7dcf-829c-e5e0bea4e511
+created_at: "2026-04-29T22:42:22.573Z"
+updated_at: "2026-04-29T22:42:22.573Z"
+generator: construct/init-docs
+body_hash: "sha256:ce40ad549fb8706ceb73055550c09928256233e3a074acbee4e5ce38126fce2d"
+---
+<!--
+templates/docs/rfcs/README.md: lane guide for RFCs.
+
+Generated from the Construct documentation lane templates. Keep this lane focused on one document
+family. If it no longer has a distinct purpose, prune it or merge it elsewhere.
+-->
+
+# RFCs
+
+Architecture and implementation proposals that need review before a decision.
+
+## Starter templates
+
+- [_template.md](./templates/_template.md)
+- [rfc-platform.template.md](./templates/rfc-platform.template.md)

package/templates/docs/rfcs/templates/_template.md

@@ -0,0 +1,58 @@
+# RFC: {title}
+
+- **Date**: {YYYY-MM-DD}
+- **Author**: {name}
+- **Status**: draft | in-review | accepted | rejected | superseded
+- **Supersedes**: {RFC title or N/A}
+- **Superseded by**: {RFC title or N/A}
+
+<!--
+Use this for significant technical or architectural proposals that need structured
+review before implementation begins. An RFC is not an ADR (which records a decision
+already made): it is the proposal that leads to one.
+
+Use rfc-platform.md instead when the proposal introduces breaking changes to a
+contract, API, schema, or protocol consumed by other systems.
+-->
+
+## Summary
+<!-- One paragraph. What is being proposed and why. Someone who reads only this should understand the intent. -->
+
+## Motivation
+<!-- What problem or limitation drives this proposal? Include evidence: incidents, performance data, support tickets, developer friction. Explain why the status quo is not acceptable. -->
+
+## Proposed design
+<!-- The concrete proposal. Enough detail for reviewers to evaluate feasibility and tradeoffs. The sequence below shows the proposed behavior in context — include the happy path and at least one error path. -->
+
+```mermaid
+sequenceDiagram
+  participant Client
+  participant Service
+  participant Store
+  Client->>Service: request
+  Service->>Store: read or write
+  Store-->>Service: result
+  Service-->>Client: response
+  Note over Service,Store: error path — Store unavailable → Service returns degraded response
+```
+
+## Tradeoffs and alternatives
+<!-- The other credible designs considered. For each: what it is, why it was not chosen, and under what conditions it would be preferred. No strawmen. -->
+
+## Drawbacks
+<!-- What this proposal makes harder, slower, or more expensive. Include technical debt, operational complexity, and team burden. -->
+
+## Risks
+<!-- What could go wrong during implementation or in production. For each: likelihood, impact, and mitigation. -->
+
+## Rollout
+<!-- How this change ships. Phased rollout, feature flags, dark launch, migration path, deprecation timeline. -->
+
+## Verification
+<!-- How we confirm the proposal achieved its goals. Tests, metrics, observable evidence. -->
+
+## Unresolved questions
+<!-- Genuine unknowns that remain. Each names an owner and a decision deadline. These should be resolved before the RFC is accepted. -->
+
+## References
+<!-- Related ADRs, prior RFCs, design docs, tickets, research, external standards. -->