@geraldmaron/construct 1.2.0 → 1.2.2

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. -->

package/templates/docs/rfcs/templates/rfc-platform.template.md

@@ -0,0 +1,72 @@
+# Platform RFC: {title}
+
+- **Date**: {YYYY-MM-DD}
+- **Author**: {name}
+- **Status**: draft | in-review | accepted | rejected | superseded
+- **Change type**: breaking | non-breaking | additive
+- **Affects**: {API | SDK | schema | event | config | permission model | protocol}
+- **Supersedes**: {RFC title or N/A}
+
+<!--
+Use this when the proposal changes a contract consumed by other systems:
+APIs, SDKs, schemas, event payloads, permission models, config shapes, or protocols.
+
+Use rfc.md instead for proposals that do not touch external contracts.
+-->
+
+## Summary
+<!-- One paragraph. What contract is changing, in what direction, and why. -->
+
+## Motivation
+<!-- What problem or limitation in the current contract drives this change? Cite evidence: consumer pain points, incidents, performance data, support load. Explain why the current interface cannot simply be extended. -->
+
+## Breaking change declaration
+<!-- Be explicit: what is breaking, what is not. List every removed, renamed, or semantically changed interface element. Omitting a breaking change here is a contract violation. -->
+
+## Proposed contract
+<!-- The new interface in full. Schemas, endpoint signatures, payload shapes, permission rules, config fields. Be precise enough that a consumer can write against this spec without asking questions. -->
+
+```mermaid
+sequenceDiagram
+  participant Consumer
+  participant Platform
+  participant Backend
+  Consumer->>Platform: contract call
+  Platform->>Backend: validate and execute
+  Backend-->>Platform: result
+  Platform-->>Consumer: response
+  Note over Platform,Backend: error path — validation failure returns typed error
+```
+
+## Backwards compatibility strategy
+<!-- How existing consumers are supported during transition. Options: versioning, dual-write, feature flags, shim layer, deprecation window. State which and why. -->
+
+## Migration guide
+<!-- Step-by-step: what a consumer must change, in what order, with examples. If migration tooling is provided, describe it. If migration is manual, estimate effort. -->
+
+## Versioning and deprecation
+<!-- Version scheme for this interface. Deprecation timeline for the old version: announcement date, sunset date, removal date. Include who owns communicating the deprecation to consumers. -->
+
+## Consumer impact analysis
+<!-- List known consumers. For each: what breaks, what changes, what stays compatible, estimated migration effort. Flag consumers that require coordinated migration. -->
+
+## Rollout plan
+<!-- How the new contract ships alongside the old one. Dual-version period, traffic migration, kill switch, removal gate. Include the observable signal that triggers each phase. -->
+
+## Operational requirements
+<!-- Observability, rate limits, error handling, fallback behavior, and admin controls required for the new contract to be supportable. -->
+
+## Tradeoffs and alternatives
+<!-- Other contract designs considered. For each: what it is, why it was not chosen. -->
+
+## Risks
+<!-- Compatibility gaps, consumer adoption risk, timing risk, coordination failure. For each: likelihood, impact, mitigation. -->
+
+## Verification
+<!-- How we confirm the migration succeeded and the old version can be safely removed. Metrics, tests, observable evidence. -->
+
+## Unresolved questions
+<!-- Genuine unknowns. Each names an owner and a decision deadline. -->
+
+## References
+<!-- Related ADRs, prior RFCs, API design guidelines, consumer runbooks, tickets. -->

package/templates/homebrew/construct.rb

@@ -8,7 +8,7 @@
 # scratch on every `v*` tag push — it downloads sha256 sidecars from the
 # GitHub Release, fills in the version and per-platform URLs/SHAs, and pushes
 # directly to the tap. The placeholder SHAs below are only used when seeding
-# the tap by hand the first time (see docs/maintenance/homebrew-tap.md).
+# the tap by hand the first time (see docs/operations/maintenance/homebrew-tap.md).
 class Construct < Formula
   desc "Deployable AI R&D operating system for coding agents — runs locally or for teams"
   homepage "https://github.com/geraldmaron/construct"

package/templates/workflows/new-feature.yml

@@ -13,28 +13,28 @@ inputs:
 
 artifacts:
   - template: prd.md
-    path: "docs/prd/${feature_name}.md"
+    path: "docs/specs/prd/${feature_name}.md"
     title: "PRD: ${feature_name}"
 
   - template: adr.md
-    path: "docs/adr/${feature_name}.md"
+    path: "docs/decisions/adr/${feature_name}.md"
     title: "ADR: ${feature_name}"
     depends_on:
-      - "docs/prd/${feature_name}.md"
+      - "docs/specs/prd/${feature_name}.md"
 
   - template: test-plan.md
     path: "docs/test-plans/${feature_name}.md"
     depends_on:
-      - "docs/adr/${feature_name}.md"
+      - "docs/decisions/adr/${feature_name}.md"
 
 beads_items:
   - type: feature
     title: "${feature_name}: spec"
-    link_to: "docs/prd/${feature_name}.md"
+    link_to: "docs/specs/prd/${feature_name}.md"
 
   - type: feature
     title: "${feature_name}: design"
-    link_to: "docs/adr/${feature_name}.md"
+    link_to: "docs/decisions/adr/${feature_name}.md"
     depends_on_prior: true
 
   - type: feature
@@ -49,5 +49,5 @@ checks:
   - name: prd-precedes-adr
     kind: file-order
     files:
-      - "docs/prd/${feature_name}.md"
-      - "docs/adr/${feature_name}.md"
+      - "docs/specs/prd/${feature_name}.md"
+      - "docs/decisions/adr/${feature_name}.md"