@geraldmaron/construct 1.0.0

package/skills/docs/init-docs.md

@@ -0,0 +1,160 @@
+<!--
+skills/docs/init-docs.md — Skill: init-docs — Initialize Project Documentation Structure — `init docs`, `create docs structure`, `set up documentation`, `docs scaffold`, `
+
+## Trigger keywords `init docs`, `create docs structure`, `set up documentation`, `docs scaffold`, `documentation init`
+-->
+# Skill: init-docs — Initialize Project Documentation Structure
+
+## Trigger keywords
+`init docs`, `create docs structure`, `set up documentation`, `docs scaffold`, `documentation init`
+
+## What this skill does
+
+When invoked, gather the user's intent and create a tailored documentation directory structure. The structure serves as both human reference and **required operational project state** — all LLMs working in this project, including Construct, should read these docs to understand purpose, decisions, constraints, and active reality before acting.
+
+---
+
+## Step 1 — Gather intent (ask these questions)
+
+Ask the user **all at once** (single message, not one at a time):
+
+1. **What is this project?** A brief description (one sentence is fine)
+2. **What doc types will you have?** Examples: architecture decisions, API reference, runbooks, user guides, changelogs, onboarding guides, RFCs, design docs, data models, deployment guides
+3. **Who is the audience?** Engineers, external users, both, or internal team only
+4. **Tech stack?** (affects whether API reference sections are needed)
+5. **Monorepo or single-service?** Affects directory depth
+
+---
+
+## Step 2 — Generate the structure
+
+Based on answers, create the `docs/` directory and appropriate subdirectories. Use this as a base — add or remove sections based on the user's answers:
+
+### Core structure (always include)
+
+```
+docs/
+├── README.md                  # Required docs contract and navigation index
+└── architecture.md            # Canonical architecture and invariants
+
+.cx/
+├── context.md                 # Human-readable resumable context
+├── context.json               # Machine-readable resumable context
+└── workflow.json              # Canonical workflow/task state
+```
+
+### Add based on doc types mentioned
+
+| Doc type mentioned | Create |
+|-------------------|--------|
+| Architecture / design | `docs/architecture/` with `overview.md` skeleton |
+| API reference | `docs/api/` with `README.md` skeleton |
+| Runbooks / ops | `docs/runbooks/` with `README.md` + `incident-response.md` skeleton |
+| Onboarding | `docs/onboarding/` with `README.md` + `local-setup.md` skeleton |
+| Changelog / releases | `docs/releases/` with `README.md` if the user explicitly wants public release history |
+| RFCs | `docs/rfcs/` with `README.md` + `0001-template.md` |
+| Data models | `docs/data-models/` with `README.md` skeleton |
+| User guides | `docs/guides/` with `README.md` skeleton |
+| Deployment | `docs/deployment/` with `README.md` + `environments.md` |
+
+---
+
+## Step 3 — Make the core docs explicit project state
+
+The required core documents are the operational state surface for the repo. All LLMs working here should read and maintain them:
+
+- `.cx/context.md`
+- `.cx/context.json`
+- `.cx/workflow.json`
+- `docs/README.md`
+- `docs/architecture.md`
+
+Fill these in based on the user's answers and the actual repo shape. Treat them as required maintenance targets, not decorative docs.
+
+---
+
+## Step 4 — Create skeleton files
+
+Each created file should have a minimal, useful skeleton — not just a title. Skeletons should include:
+- A one-line description of what goes in this file
+- Section headings relevant to the doc type
+- A note at the top that the file is required project state and all LLMs should keep it current.
+
+### `docs/README.md` skeleton
+
+```markdown
+# [Project Name] — Documentation
+
+> Required project state. All LLMs working in this repo, including Construct, should keep this file updated.
+
+## What's here
+
+| Directory | Contents |
+|-----------|----------|
+[fill based on created subdirs]
+
+## Ownership
+
+Maintained by: [team/person or Construct]
+Last updated: [date]
+```
+
+### `docs/architecture/overview.md` skeleton (if architecture dir created)
+
+```markdown
+# Architecture Overview
+
+> Required project state. All LLMs working in this repo, including Construct, should keep this file updated.
+
+## System overview
+
+[Describe the system in 2-3 sentences]
+
+## Key components
+
+[List main components and their responsibilities]
+
+## Data flow
+
+[Describe how data moves through the system]
+
+## Key decisions
+
+Link to `.cx/decisions/` or the canonical project decision log used in this repo.
+```
+
+---
+
+## Step 5 — Tell the repo how upkeep works
+
+After creating the files, instruct the user:
+
+> After init, all LLMs working in this repo should read `.cx/context.md`, `.cx/context.json`, `.cx/workflow.json`, `docs/README.md`, and `docs/architecture.md` as project state. When work changes project reality, update the affected file before calling the work done.
+
+Also create or update `.cx/context.md` with a summary of what was just set up:
+
+```markdown
+# Project Context
+
+Updated: [date]
+
+## Documentation structure initialized
+
+Created docs/ with: [list created dirs]
+Core docs: .cx/context.md, .cx/context.json, .cx/workflow.json, docs/README.md, docs/architecture.md
+Project type: [type]
+Stack: [stack]
+
+## What agents should know
+
+[Fill with any key constraints, active work, or decisions the user mentioned]
+```
+
+---
+
+## Routing
+
+After completing the docs init:
+- If the user has architecture questions → `@cx-explorer` or `@cx-docs-keeper` to explore and update `docs/architecture/`
+- If the user wants to document a decision → record it in `.cx/decisions/` or the repo's canonical decision log
+- If the user wants to add API docs → `@cx-docs-keeper` to generate stubs from code

package/skills/docs/init-project.md

@@ -0,0 +1,50 @@
+<!--
+skills/docs/init-project.md — Project Initialization — Use when: starting work on a new project or joining an existing one without doc
+
+Use when: starting work on a new project or joining an existing one without doc structure. ## Command
+-->
+# Project Initialization
+
+Use when: starting work on a new project or joining an existing one without doc structure.
+
+## Command
+```bash
+construct init-docs [path]   # defaults to current directory
+```
+
+## What it creates
+```
+.cx/                    ← agent session memory and decisions
+  context.md
+  context.json
+  workflow.json
+  decisions/
+  research/
+  reviews/
+docs/                   ← human-readable project documentation
+  README.md
+  architecture.md
+  runbooks/
+```
+
+## After init
+1. Treat `.cx/context.md`, `.cx/context.json`, `.cx/workflow.json`, `docs/README.md`, and `docs/architecture.md` as required project state.
+2. Read them at the start of every meaningful session.
+3. Update them whenever work changes active reality: decisions, workflow phase, architecture assumptions, or documentation contract.
+4. Run `construct serve` to see the project in the dashboard.
+
+## For cx-docs-keeper
+At session start, check the core docs set. If missing, suggest running `construct init-docs`.
+At session end, update the affected core docs so the next LLM session inherits current project reality.
+
+## For all LLMs working in the repo
+
+These files are not optional documentation. They are the repo's shared operating state:
+
+- `.cx/context.md`
+- `.cx/context.json`
+- `.cx/workflow.json`
+- `docs/README.md`
+- `docs/architecture.md`
+
+If your work changes project reality, update the affected file before calling the task done.

package/skills/docs/prd-workflow.md

@@ -0,0 +1,57 @@
+<!--
+skills/docs/prd-workflow.md — Workflow for producing a PRD and connecting it to workflow task packets.
+
+Guides cx-product-manager through requirements gathering, user research, and writing a PRD
+to docs/prd/. Once approved, the PRD feeds /plan feature to create bead packets in
+.cx/workflow.json — closing the loop from discovery to execution.
+-->
+# PRD Workflow
+
+Use when: the user asks to create a PRD, platform spec, business case, RFC, or requirements document.
+
+Choose the document type before drafting:
+
+| Template | Use when |
+|---|---|
+| `prd` | Customer-facing product capabilities, user workflows, end-user requirements |
+| `prd-platform` | Internal platform, APIs, SDKs, developer tooling, operational infrastructure, shared services |
+| `prd-business` | Strategic bets, market positioning, business model changes, make-vs-buy, pricing strategy |
+| `meta-prd` | Requirements about the product operating system itself: agent workflows, evidence pipelines, templates, evaluation loops, governance |
+| `rfc` | Technical or architectural proposals that need structured review before implementation — no contract changes |
+| `rfc-platform` | Proposals that change an external contract: API, SDK, schema, event payload, permission model, protocol |
+
+Style constraint: do not produce a wall of bullets. Use paragraphs for reasoning and narrative, tables for comparison, and bullets only where scanability helps. Keep em dashes rare.
+
+## Steps
+
+1. **cx-product-manager** produces the requirements package
+2. **cx-ux-researcher** grounds requirements in user behavior (invoke in parallel for new features)
+3. **cx-researcher** fills any evidence gaps
+4. **Write to the appropriate `docs/` subdirectory** using the selected template. Each `get_template()` call resolves `.cx/templates/docs/` first, then the Construct default.
+
+   | Template | Output path |
+   |---|---|
+   | `prd` | `docs/prd/{YYYY-MM-DD}-{slug}.md` |
+   | `prd-platform` | `docs/prd-platform/{YYYY-MM-DD}-{slug}.md` |
+   | `prd-business` | `docs/prd-business/{YYYY-MM-DD}-{slug}.md` |
+   | `meta-prd` | `docs/meta-prd/{YYYY-MM-DD}-{slug}.md` |
+   | `rfc` | `docs/rfc/{YYYY-MM-DD}-{slug}.md` |
+   | `rfc-platform` | `docs/rfc/{YYYY-MM-DD}-{slug}.md` |
+5. **cx-docs-keeper** updates `.cx/context.md` with a link to the PRD
+
+## File naming
+- `docs/{template-type}/{YYYY-MM-DD}-{slug}.md`
+- Examples:
+  - `docs/prd/2026-04-search-autocomplete.md`
+  - `docs/prd-platform/2026-04-events-api-v2.md`
+  - `docs/prd-business/2026-04-enterprise-tier.md`
+  - `docs/meta-prd/2026-04-product-intelligence-workflow.md`
+  - `docs/rfc/2026-04-storage-backend-migration.md`
+
+## PRD lifecycle
+- Draft → stakeholder review → approved → link to implementation tasks
+- Once shipped, update status field to `shipped` and add a link to the implementation
+
+## After approval → beads
+
+Once the PRD is approved, run `/plan feature {feature-slug}` to produce a structured implementation plan and import it as workflow task packets (beads) into `.cx/workflow.json`. Link the resulting `.cx/plans/` file back in the PRD as the implementation reference.

package/skills/docs/prfaq-workflow.md

@@ -0,0 +1,25 @@
+<!--
+skills/docs/prfaq-workflow.md — Working-backwards PRFAQ generation from PRDs or evidence.
+-->
+# PRFAQ Workflow
+
+Use when: the user asks for a PRFAQ, working-backwards doc, launch narrative, or FAQ grounded in product evidence.
+
+## Modes
+
+- **From PRD**: load the PRD, related evidence brief, customer profiles, and linked docs.
+- **From evidence**: gather evidence first. If evidence is below threshold, write a signal brief instead.
+
+## Steps
+
+1. Load `get_template("prfaq")`.
+2. Identify PM flavor and product area.
+3. Draft problem statement from evidence, not positioning.
+4. Write the press release in shipped-state language.
+5. Write external FAQ for customers and internal FAQ for engineering, sales, support, security, finance, and leadership.
+6. Include unknowns as `TBD` with what would resolve them.
+7. Save to `.cx/product-intel/prfaqs/` until approved.
+
+## Approval
+
+Stop before marking a PRFAQ approved or publishing it as a document of record.

package/skills/docs/product-intelligence-review.md

@@ -0,0 +1,22 @@
+<!--
+skills/docs/product-intelligence-review.md — Evaluate Product Intelligence artifacts before they become docs of record.
+-->
+# Product Intelligence Review
+
+Use when: reviewing PRDs, Meta PRDs, PRFAQs, evidence briefs, signal briefs, customer profiles, or backlog proposals.
+
+## Rubric
+
+Score each dimension as pass, warning, or fail:
+
+- Evidence grounding: claims cite source material or state evidence gaps.
+- PM flavor fit: platform, product, enterprise, ai-product, or growth concerns are handled when relevant.
+- Acceptance criteria: observable and pass/fail.
+- Scope discipline: goals, non-goals, and tradeoffs are explicit.
+- Approval safety: external writes and approved status are gated.
+- Storage readiness: artifact path is under `.cx/product-intel/`, `docs/prd/`, or `docs/meta-prd/` so hybrid retrieval can index it.
+- Readability: balanced paragraphs, tables, and bullets. Few em dashes.
+
+## Output
+
+Return findings first, ordered by severity. Include concrete fixes and cite section names or file paths.

package/skills/docs/product-intelligence-workflow.md

@@ -0,0 +1,62 @@
+<!--
+skills/docs/product-intelligence-workflow.md — Native Construct workflow for product evidence, synthesis, and product docs.
+
+Use this to move from raw product evidence to PRDs, Meta PRDs, PRFAQs, signal briefs,
+customer profiles, and backlog proposals without creating a separate sidecar system.
+-->
+# Product Intelligence Workflow
+
+Use when: the request involves customer evidence, PM synthesis, product requirements, PRDs, PRFAQs, customer profiles, product signals, or backlog proposals.
+
+## Operating model
+
+Product Intelligence is a Construct-native loop:
+
+1. Capture evidence into `.cx/product-intel/sources/` or link existing sources.
+2. Normalize evidence into field notes, customer profiles, and evidence briefs.
+3. Synthesize themes, asks, pain points, product areas, and confidence.
+4. Select the PM flavor: product, platform, enterprise, ai-product, or growth.
+5. Select the artifact: signal brief, evidence brief, PRD, Meta PRD, PRFAQ, product intelligence report, or backlog proposal.
+6. Gate external writes and approved-doc status through the primary persona.
+7. Sync searchable artifacts through the hybrid file/Postgres/vector storage path.
+
+## PM flavor selection
+
+- **product**: user workflow, adoption, JTBD, UX surface, success metrics.
+- **platform**: APIs, SDKs, integrations, admin controls, compatibility, migration, operational burden.
+- **enterprise**: buyer/admin/evaluator split, compliance, security review, procurement, rollout controls.
+- **ai-product**: model behavior, evals, human review, traceability, trust and correction.
+- **growth**: activation, conversion, packaging, pricing assumptions, lifecycle metrics.
+
+Load the core product-manager role guidance and the selected overlay before drafting.
+
+## Artifact selection
+
+- Use `signal-brief` when evidence is real but below the PRD threshold.
+- Use `evidence-brief` before committing requirements.
+- Use `customer-profile` for durable account memory.
+- Use `prd` for customer-facing product capabilities.
+- Use `meta-prd` for product operating systems, agent workflows, templates, governance, and evaluation loops.
+- Use `prfaq` for working-backwards launch narrative and FAQ.
+- Use `backlog-proposal` before creating or updating external issues.
+- Use `product-intelligence-report` for cross-source synthesis.
+
+## Storage
+
+Write working artifacts under `.cx/product-intel/` unless they are docs of record. Approved PRDs live in `docs/prd/`; approved Meta PRDs live in `docs/meta-prd/`.
+
+The hybrid storage layer indexes `.cx/product-intel/`, `docs/prd/`, and `docs/meta-prd/`. When Postgres is configured, `construct storage sync` can persist these artifacts into shared SQL rows. The vector layer scores the same documents for local, remote, or file-backed semantic retrieval.
+
+## Approval boundaries
+
+Stop and ask the primary persona before:
+
+- writing to Jira, Linear, GitHub Issues, or another external tracker
+- marking a PRD, Meta PRD, or PRFAQ approved
+- promoting a weak signal into committed requirements
+- deleting or rewriting customer profile history
+- importing product docs into implementation tasks
+
+## Quality bar
+
+Product Intelligence output must cite evidence, distinguish observation from inference, name confidence, and avoid a wall of bullets. Keep em dashes rare. Use paragraphs for reasoning, tables for comparisons, and bullets for scanability.

package/skills/docs/product-signal-workflow.md

@@ -0,0 +1,27 @@
+<!--
+skills/docs/product-signal-workflow.md — Synthesize product signals from evidence.
+-->
+# Product Signal Workflow
+
+Use when: the user asks what customers are asking for, what themes are emerging, whether evidence is strong enough, or what should become a PRD.
+
+## Steps
+
+1. Gather relevant evidence briefs, customer profiles, notes, tickets, research, and product docs.
+2. Group evidence into themes, asks, pain points, affected personas, product areas, and counter-signals.
+3. Assign confidence: high, medium, or low.
+4. Choose the next artifact:
+   - signal brief for weak or early evidence
+   - evidence brief for decision-ready synthesis
+   - PRD or PRFAQ for strong customer-facing product demand
+   - Meta PRD for operating-system or process changes
+   - backlog proposal for tracker changes after approval
+5. Store synthesis in `.cx/product-intel/signals/` or `.cx/product-intel/evidence-briefs/`.
+
+## Evidence threshold
+
+Default threshold for PRD-ready evidence: at least two independent customers, three independent mentions, one severe enterprise blocker, or a clear strategic mandate with named risk. If the threshold is not met, write a signal brief instead of inventing requirements.
+
+## Quality bar
+
+Separate asks from requirements. Separate observation from inference. Name what evidence would change the recommendation.

package/skills/docs/research-workflow.md

@@ -0,0 +1,28 @@
+<!--
+skills/docs/research-workflow.md — Research Workflow — Use when: the user asks to research a topic, investigate a question, or gather e
+
+Use when: the user asks to research a topic, investigate a question, or gather evidence for a decision. ## Steps
+-->
+# Research Workflow
+
+Use when: the user asks to research a topic, investigate a question, or gather evidence for a decision.
+
+## Steps
+
+1. **Clarify the question** — one specific question the research must answer
+2. **Run cx-researcher or cx-docs-researcher** — use the appropriate agent:
+   - Library/API/framework questions → cx-docs-researcher
+   - Market, competitive, general evidence → cx-researcher
+3. **Structure findings** using the template from `get_template("research-brief")` — resolves `.cx/templates/docs/research-brief.md` (override) then `templates/docs/research-brief.md` (shipped)
+4. **Write to `.cx/research/{topic-slug}.md`** — cx-docs-keeper owns this
+5. **Reference the research doc** in the requesting agent's output (link by path)
+
+## File naming
+- Topic slug: lowercase, hyphens, no spaces — e.g., `firebase-auth-v9-migration.md`
+- Date prefix for time-sensitive research: `2026-04-langfuse-v2-vs-v3.md`
+
+## When research feeds a decision
+→ Also create `.cx/decisions/ADR-{NNN}-{slug}.md` referencing the research doc
+
+## When research feeds a PRD
+→ Reference it in the PRD's References section

package/skills/docs/runbook-workflow.md

@@ -0,0 +1,24 @@
+<!--
+skills/docs/runbook-workflow.md — Runbook Workflow — Use when: creating operational procedures for services, alerts, or recurring ope
+
+Use when: creating operational procedures for services, alerts, or recurring operations. ## Steps
+-->
+# Runbook Workflow
+
+Use when: creating operational procedures for services, alerts, or recurring operations.
+
+## Steps
+
+1. **cx-sre** or **cx-release-manager** identifies the need
+2. **Write to `docs/runbooks/{service}-{operation}.md`** using the template from `get_template("runbook")` — resolves `.cx/templates/docs/runbook.md` (override) then `templates/docs/runbook.md` (shipped)
+3. **Link from the relevant alert** or monitoring dashboard
+4. **cx-docs-keeper** adds to `.cx/context.md` if it's a critical path runbook
+
+## File naming
+- `docs/runbooks/langfuse-restart.md`
+- `docs/runbooks/db-migration.md`
+- `docs/runbooks/incident-response.md`
+
+## Review cadence
+- Runbooks should be tested (table-top or live) at least quarterly
+- Update `Last updated` field after each use or review