@geraldmaron/construct 1.0.16 → 1.0.18

package/skills/security/blue-team.md

@@ -1,6 +1,8 @@
 ---
 name: security-blue-team
 description: Use this skill when defending systems, responding to incidents, or building detection and monitoring capabilities.
+inputs: [system-design]
+artifactType: guidance
 ---
 # Blue Team
 

package/skills/security/code-audit.md

@@ -1,6 +1,8 @@
 ---
 name: security-code-audit
 description: Use this skill when reviewing source code for security vulnerabilities through static analysis.
+inputs: [code]
+artifactType: vulnerability-report
 ---
 # Code Audit
 

package/skills/security/pentest.md

@@ -1,6 +1,8 @@
 ---
 name: security-pentest
 description: Use this skill when testing web applications or APIs for security vulnerabilities.
+inputs: [system-design, binary]
+artifactType: pentest-report
 ---
 # Penetration Testing
 

package/skills/security/red-team.md

@@ -1,6 +1,8 @@
 ---
 name: security-red-team
 description: Use this skill when planning or executing offensive security assessments, adversary emulation, or attack simulations.
+inputs: [system-design, binary]
+artifactType: pentest-report
 ---
 # Red Team
 

package/skills/security/threat-intel.md

@@ -1,6 +1,8 @@
 ---
 name: security-threat-intel
 description: Use this skill when performing OSINT, threat modeling, or building threat intelligence programs.
+inputs: [system-design]
+artifactType: threat-model
 ---
 # Threat Intelligence
 

package/skills/security/vuln-research.md

@@ -1,6 +1,8 @@
 ---
 name: security-vuln-research
 description: Use this skill when analyzing binaries, fuzzing software, or developing exploits for security research.
+inputs: [target-binary-or-software]
+artifactType: vulnerability-report
 ---
 # Vulnerability Research
 

package/skills/strategy/competitive-landscape.md

@@ -1,6 +1,8 @@
 ---
 name: strategy-competitive-landscape
 description: Use when the team needs a structured read on market positioning before committing direction.
+inputs: [competitor-data, market-signals]
+artifactType: competitive-analysis
 ---
 # Competitive Landscape Analysis
 

package/skills/strategy/jobs-to-be-done.md

@@ -0,0 +1,38 @@
+---
+name: strategy-jobs-to-be-done
+description: "Use when: user research needs to uncover the job a user is hiring a product to do — the underlying progress they seek — rather than feature requests or stated preferences."
+inputs: [user-signals-or-interviews]
+artifactType: jtbd-summary
+---
+# Jobs To Be Done
+
+Use this skill when user research needs to surface the underlying job a user is trying to get done, not the features they ask for.
+
+Users describe solutions ("add a dark mode"); the job is the progress they're trying to make and the context that triggers it. Building to stated features without the job produces local optima nobody hires.
+
+## Steps
+
+1. **Anchor on a real episode**, not a hypothetical. "Tell me about the last time you…" — recent, specific, remembered.
+2. **Trace the timeline**: the trigger (what changed that made them act), the struggle with the current approach, what they tried, and the outcome they were after.
+3. **Separate the job from the solution.** "I want X feature" → ask "what would X let you do that you can't now?" Keep climbing until you reach a stable goal that doesn't reference your product.
+4. **Capture the forces**: push (problems with the status quo), pull (attraction of a new way), and anxieties/habits that hold them back. Adoption is decided by these four forces.
+5. **Watch for non-consumption**: people who have the job but use nothing, or a manual workaround — often the clearest signal of the job.
+6. **State the job** as `When <situation>, I want to <motivation>, so I can <expected outcome>` — sourced to the episodes, not invented.
+
+## Output shape
+
+```
+## Job statement(s)
+- When <situation>, I want to <motivation>, so I can <outcome> — evidence: <episode refs>
+
+## Forces
+- push: … · pull: … · anxiety: … · habit: …
+
+## Non-consumption / workarounds observed
+```
+
+## Verification bar
+
+- Each job statement traces to a specific recounted episode, not a generalization or an assumption about "users".
+- Solution language ("add X") is climbed back to the underlying job, not recorded as the job.
+- Forces and non-consumption come from what was observed/said, labeled where inferred.

package/skills/strategy/market-research-methods.md

@@ -1,6 +1,8 @@
 ---
 name: strategy-market-research-methods
 description: Use when the team needs to validate assumptions before committing resources, or when a decision is being made on vibes rather than signal.
+inputs: [market-signals, user-signals]
+artifactType: market-brief
 ---
 # Market Research Methods
 

package/skills/strategy/narrative-arc.md

@@ -1,6 +1,8 @@
 ---
 name: strategy-narrative-arc
 description: Use when the argument must move people, not just inform them. Strategic narrative is the difference between a document that gets read and one that changes what people do.
+inputs: [market-signals, user-signals]
+artifactType: positioning
 ---
 # Strategic Narrative Construction
 

package/skills/strategy/pricing-positioning.md

@@ -1,6 +1,8 @@
 ---
 name: strategy-pricing-positioning
 description: Use when the team needs to set price, adjust positioning, or defend either to stakeholders.
+inputs: [market-signals, competitor-data]
+artifactType: positioning
 ---
 # Pricing and Positioning
 

package/skills/utility/clean-code.md

@@ -1,6 +1,8 @@
 ---
 name: utility-clean-code
 description: Patterns and heuristics for identifying and removing AI-generated code smells. Use when cleaning up output from AI coding tools.
+inputs: [code]
+artifactType: refactor
 ---
 # AI Slop Removal
 

package/specialists/prompts/cx-architect.md

@@ -16,6 +16,7 @@ You have inherited enough unmaintainable systems to be permanently suspicious of
 **Failure mode warning**: If the ADR has no "options rejected" section, the decision wasn't made: it defaulted. Defaulted decisions are the ones that bite hardest.
 
 **Role guidance**: call `get_skill("roles/architect")` before drafting.
+**Templates**: call `get_template("adr")` before authoring an ADR so the section structure, framing rules, and rejected-alternatives requirement come from the canonical template rather than memory. Use `list_templates` to discover overrides.
 **Strategy grounding**: for decisions with long-term interface or data model implications, check `.cx/knowledge/decisions/strategy/` for any declared strategy documents before choosing. A decision that contradicts a declared Bet or enables a Non-bet must surface the conflict explicitly in the ADR's OPTIONS CONSIDERED section. If no strategy documents exist, proceed without: do not block the workflow or invent strategy.
 
 When the architecture domain is clear, also load exactly one relevant overlay before drafting:

package/specialists/prompts/cx-designer.md

@@ -32,7 +32,7 @@ When the user asks for a visual deliverable, choose the lightest artifact that h
 - walkthroughs and demo videos: use the available browser/demo tooling and follow a discover → rehearse → record flow instead of jumping straight to recording
 
 Tool and skill discipline:
-- prefer existing visual tools such as `construct wireframe` or equivalent Mermaid/HTML outputs before inventing bespoke formats
+- prefer the bundled generator before inventing bespoke formats: `construct wireframe "<description>" --type=<layout|flow|state|sequence|er|user-journey>` writes a diffable artifact to `.cx/wireframes/`. Use `layout` for screens, `flow`/`user-journey` for paths, `state`/`sequence`/`er` for system diagrams. It is zero-dependency and text-first; do not add a diagramming library
 - use `list_skills` and `search_skills` to load the host's relevant visual skill when the ask is a deck, presentation, polished UI exploration, or demo video
 - if the user provides source material like a `.pptx`, export, or PDF, ingest it first so the deliverable is grounded in the actual content
 

package/specialists/prompts/cx-engineer.md

@@ -44,7 +44,7 @@ Construct may dispatch you in response to a `handoff.received`, `incident.handof
 **Fence (declared in specialists/role-manifests.json → engineer):**
 - Allowed paths: `lib/**`, `bin/**`, `src/**`, `app/**`, `tests/**`, `docs/**`
 - Allowed bd labels: `bug`, `feature`, `task`, `engineering`, `fix`
-- Approval required: any commit, any push, any edit to protected files (`specialists/registry.json`, `install.sh`, `claude/settings.template.json`)
+- Approval required: any commit, any push, any edit to protected files (`specialists/registry.json`, `lib/setup.mjs`, `claude/settings.template.json`)
 
 You may edit production code, write tests, and run verification freely inside your fence. You **must not commit or push** without explicit user approval per `rules/common/commit-approval.md`. Stage edits, run verification, and stop.
 

package/specialists/prompts/cx-operations.md

@@ -16,6 +16,7 @@ A beautiful plan is worthless if it can't be executed in the right sequence. You
 **Failure mode warning**: If every task can run in parallel, the dependency graph wasn't drawn. Real plans have sequences, and real sequences have blockers.
 
 **Role guidance**: call `get_skill("roles/operator")` before drafting.
+**Templates**: call `get_template("runbook")` before authoring an operational runbook and `get_template("incident-report")` before authoring a post-incident writeup, so the section structure and required fields come from the canonical template rather than memory. Use `list_templates` to discover overrides.
 
 Start only after cx-architect and cx-engineer have produced a plan and cx-devil-advocate feedback is resolved.
 

package/specialists/prompts/cx-rd-lead.md

@@ -16,6 +16,7 @@ Most "problems" that arrive on your desk are actually hypotheses masquerading as
 **Failure mode warning**: If you can't write a falsifiable hypothesis, you don't have an R&D task: you have a planning task being treated as R&D to avoid committing to a spec.
 
 **Role guidance**: call `get_skill("roles/architect")` before drafting.
+**Templates**: call `get_template("research-brief")` before authoring so the section structure comes from the canonical template rather than memory. Use `list_templates` to discover overrides.
 **Evidence policy**: hypotheses must be grounded in evidence, not plausibility. Follow `rules/common/research.md` (most-recent-first, primary sources, verified URLs) when citing external literature, benchmarks, or published results to motivate an R&D task.
 **Strategy grounding**: before proposing an R&D direction, check `.cx/knowledge/decisions/strategy/` for declared Bets and Non-bets. A research direction that contradicts a Non-bet requires explicit surfacing and user decision before proceeding.
 

package/specialists/prompts/cx-sre.md

@@ -16,6 +16,7 @@ You have been paged at 2am enough times to know that reliability problems are de
 **Failure mode warning**: If there's no alert definition before deployment, nobody planned for failure. The first alert will be a user report.
 
 **Role guidance**: call `get_skill("roles/operator.sre")` before drafting.
+**Templates**: call `get_template("runbook")` before authoring a runbook and `get_template("incident-report")` before authoring a postmortem, so the section structure and required fields come from the canonical template rather than memory. Use `list_templates` to discover overrides.
 
 For each observability or reliability initiative, define:
 

package/specialists/registry.json

@@ -50,7 +50,8 @@
       "skills": [
         "ai/orchestration-workflow",
         "operating/orchestration-reference",
-        "operating/change-management"
+        "operating/change-management",
+        "operating/unstructured-triage"
       ],
       "perspective": {
         "bias": "Over-routing to cx-engineer, false simplicity, plans where every task runs in parallel",
@@ -200,7 +201,8 @@
         ]
       },
       "skills": [
-        "docs/research-workflow"
+        "docs/research-workflow",
+        "strategy/jobs-to-be-done"
       ],
       "perspective": {
         "bias": "Ideal-user personas, invisible friction, 'users will figure it out'",
@@ -269,7 +271,7 @@
       "modelTier": "standard",
       "reasoningEffort": "medium",
       "codexSandbox": "read-only",
-      "claudeTools": "Read,Grep,Glob,LS,WebSearch,WebFetch,list_skills,get_skill,search_skills,memory_search,memory_add_observations",
+      "claudeTools": "Read,Grep,Glob,LS,WebSearch,WebFetch,list_skills,get_skill,search_skills,get_template,list_templates,memory_search,memory_add_observations",
       "promptFile": "specialists/prompts/cx-researcher.md",
       "embedOrientation": {
         "focusAreas": [
@@ -291,7 +293,8 @@
       },
       "skills": [
         "docs/research-workflow",
-        "devops/dependency-management"
+        "devops/dependency-management",
+        "docs/transcript-synthesis"
       ],
       "perspective": {
         "bias": "Undated sources, version-specific claims without citation, blog posts treated as authoritative",
@@ -389,7 +392,8 @@
       },
       "skills": [
         "devops/observability",
-        "devops/database"
+        "devops/database",
+        "operating/raw-data-structuring"
       ],
       "perspective": {
         "bias": "Vanity metrics, post-hoc success definitions, averages that hide distributions",
@@ -645,7 +649,8 @@
         ]
       },
       "skills": [
-        "quality-gates/review-work"
+        "quality-gates/review-work",
+        "quality-gates/premortem"
       ],
       "perspective": {
         "bias": "Plans that are too elegant, 'unlikely' failure modes, scope drift with stable acceptance criteria",
@@ -1070,7 +1075,7 @@
       "modelTier": "standard",
       "reasoningEffort": "medium",
       "codexSandbox": "workspace-write",
-      "claudeTools": "Read,Grep,Glob,LS,Edit,Write,Bash,list_skills,get_skill,search_skills,memory_search,memory_add_observations",
+      "claudeTools": "Read,Grep,Glob,LS,Edit,Write,Bash,list_skills,get_skill,search_skills,get_template,list_templates,memory_search,memory_add_observations",
       "promptFile": "specialists/prompts/cx-docs-keeper.md",
       "embedOrientation": {
         "focusAreas": [
@@ -1094,7 +1099,8 @@
       "skills": [
         "docs/adr-workflow",
         "docs/runbook-workflow",
-        "docs/init-docs"
+        "docs/init-docs",
+        "docs/memo-and-decision-capture"
       ],
       "perspective": {
         "bias": "Completed work with no context update, decisions 'everyone understands' but nobody wrote down",
@@ -1193,7 +1199,8 @@
         ]
       },
       "skills": [
-        "frontend-design/accessibility"
+        "frontend-design/accessibility",
+        "frontend-design/screen-reader-testing"
       ],
       "perspective": {
         "bias": "ARIA added to pass audits, keyboard navigation never tested, contrast that 'looks fine' but fails the spec",
@@ -1280,7 +1287,8 @@
         ]
       },
       "skills": [
-        "ai/prompt-optimizer"
+        "ai/prompt-optimizer",
+        "ai/trace-triage"
       ],
       "perspective": {
         "bias": "Stable-looking medians hiding variance, trace analyses looking only at successes, promotions on too few traces",
@@ -1322,7 +1330,8 @@
       "skills": [
         "devops/data-engineering",
         "devops/database",
-        "devops/observability"
+        "devops/observability",
+        "operating/raw-data-structuring"
       ],
       "perspective": {
         "bias": "Non-idempotent pipelines, unwritten data contracts, quality gates added after the first corruption incident",

package/specialists/role-manifests.json

@@ -73,7 +73,7 @@
         "allowedPaths": ["lib/**", "bin/**", "src/**", "app/**", "tests/**", "docs/**"],
         "allowedBdLabels": ["bug", "feature", "task", "engineering", "fix"],
         "allowedCommands": ["bd create", "bd note", "bd update", "bd link", "bd label", "bd close", "node", "npm", "git status", "git diff", "git log"],
-        "approvalRequired": ["commit", "push", "edit:specialists/registry.json", "edit:install.sh", "edit:claude/settings.template.json"]
+        "approvalRequired": ["commit", "push", "edit:specialists/registry.json", "edit:lib/setup.mjs", "edit:claude/settings.template.json"]
       },
       "outputs": {
         "bdLabels": ["engineering", "fix"],

package/templates/docs/test-plan.md

@@ -0,0 +1,96 @@
+# Test Plan: {feature or system name}
+
+- **Date**: {YYYY-MM-DD}
+- **Owner**: {name or role}
+- **Status**: draft | in-review | approved | executed
+- **Related**: {PRD / ADR paths or none}
+
+<!--
+Use this when a feature, migration, or system change needs a deliberate
+verification strategy before it ships. The plan is the contract between
+what was specified and what will be proven; every scenario below must
+trace to a requirement or an observed risk, never to guesswork.
+
+Before drafting, read rules/common/framing.md and rules/common/no-fabrication.md.
+Acceptance criteria must be binary pass/fail. If a criterion cannot be
+checked without asking the author, it is not done. Cite the requirement
+(FR/NFR id, ADR decision, ticket) each scenario verifies.
+-->
+
+## Scope
+<!--
+What is under test and what is explicitly not. Name the components, surfaces,
+or behaviors covered. The out-of-scope list protects reviewer attention and
+makes coverage gaps deliberate rather than accidental.
+-->
+
+| | Description |
+|---|---|
+| **In scope** | <what this plan verifies> |
+| **Out of scope** | <related behavior deliberately not tested here, and why> |
+
+## Test strategy
+<!--
+The levels of testing applied and why each is justified. Map levels to risk:
+unit for logic, integration for contracts and boundaries, end-to-end for
+user-visible flows, manual/exploratory for what automation cannot reach.
+State what each level is responsible for so coverage gaps are visible.
+-->
+
+| Level | What it covers | Why it lives at this level |
+|---|---|---|
+| Unit | <logic, pure functions, edge cases> | <reason> |
+| Integration | <contracts, boundaries, data access> | <reason> |
+| End-to-end | <user-visible flows> | <reason> |
+| Manual / exploratory | <what automation cannot reach> | <reason> |
+
+## Key scenarios
+<!--
+The scenarios that prove the change works. Each scenario names the requirement
+it verifies, the setup, the action, and the binary acceptance criterion. A
+reviewer must be able to run or read the scenario and decide pass/fail without
+asking the author.
+-->
+
+| ID | Scenario | Verifies | Acceptance (binary pass/fail) |
+|---|---|---|---|
+| TC-1 | <setup, action, expected result> | <FR/NFR id or risk> | <observable condition> |
+| TC-2 | <...> | <...> | <...> |
+
+## Risks and edge cases
+<!--
+The failure modes and boundary conditions worth explicit attention: empty
+inputs, concurrency, partial failure, large data, permission boundaries,
+rollback. For each, state how the plan covers it or why the residual risk
+is accepted.
+-->
+
+| Risk / edge case | Likelihood | Impact | Coverage or accepted reason |
+|---|---|---|---|
+| <condition> | low / med / high | low / med / high | <how it is tested, or why accepted> |
+
+## Environments and data
+<!--
+Where tests run and what data they use. Name the environments, fixtures,
+seed data, and any external dependencies (sandboxes, stubs, recorded
+responses). Flag data that must be synthetic or anonymized.
+-->
+
+## Entry and exit criteria
+<!--
+Entry: what must be true before testing starts (build available, environment
+provisioned, dependencies stubbed). Exit: what must be true to call testing
+done (all blocking scenarios pass, known issues triaged, coverage threshold
+met). Both are checklists a reviewer can verify.
+-->
+
+**Entry criteria**
+
+- <condition that must hold before execution begins>
+
+**Exit criteria**
+
+- <condition that must hold to declare the plan executed>
+
+## References
+<!-- PRD, ADR, RFC, related test plans, prior incidents. -->