@geraldmaron/construct 1.0.7 → 1.0.9

package/{agents → specialists}/role-manifests.json

@@ -1,5 +1,5 @@
 {
-  "$comment": "Role manifests for the Construct-on-Construct role framework. Keyed by registry persona name (without cx- prefix, matching agents/registry.json). Empty entries reserve the slot for future onboarding without code change.",
+  "$comment": "Role manifests for the Construct-on-Construct role framework. Keyed by registry persona name (without cx- prefix, matching specialists/registry.json). Empty entries reserve the slot for future onboarding without code change.",
   "version": 1,
   "personas": {
     "sre": {
@@ -9,7 +9,7 @@
         "allowedPaths": ["docs/runbooks/**", "docs/incidents/**", "docs/postmortems/**"],
         "allowedBdLabels": ["incident", "sre", "reliability"],
         "allowedCommands": ["bd create", "bd note", "bd update", "bd link", "bd label"],
-        "approvalRequired": ["commit", "push", "edit:lib/**", "edit:bin/**", "edit:agents/**"]
+        "approvalRequired": ["commit", "push", "edit:lib/**", "edit:bin/**", "edit:specialists/**"]
       },
       "outputs": {
         "bdLabels": ["incident", "sre"],
@@ -57,7 +57,7 @@
         "allowedPaths": ["docs/**", "**/README.md", "CHANGELOG.md"],
         "allowedBdLabels": ["docs", "doc-drift", "changelog"],
         "allowedCommands": ["bd create", "bd note", "bd update", "bd label"],
-        "approvalRequired": ["commit", "push", "edit:lib/**", "edit:bin/**", "edit:agents/**"]
+        "approvalRequired": ["commit", "push", "edit:lib/**", "edit:bin/**", "edit:specialists/**"]
       },
       "outputs": {
         "bdLabels": ["docs", "doc-drift"],
@@ -72,8 +72,8 @@
       "fence": {
         "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"],
-        "approvalRequired": ["commit", "push", "edit:agents/registry.json", "edit:install.sh", "edit:claude/settings.template.json"]
+        "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"]
       },
       "outputs": {
         "bdLabels": ["engineering", "fix"],
@@ -89,7 +89,7 @@
         "allowedPaths": ["docs/adr/**", "docs/rfc/**", "docs/concepts/architecture.md", "docs/system-design/**"],
         "allowedBdLabels": ["architecture", "adr", "rfc", "design"],
         "allowedCommands": ["bd create", "bd note", "bd update", "bd label"],
-        "approvalRequired": ["commit", "push", "edit:lib/**", "edit:bin/**", "edit:agents/**"]
+        "approvalRequired": ["commit", "push", "edit:lib/**", "edit:bin/**", "edit:specialists/**"]
       },
       "outputs": { "bdLabels": ["architecture", "adr"], "docTypes": ["adr", "rfc", "rfc-platform", "architecture-overview", "system-design"] },
       "handoffCandidates": ["engineer", "platform-engineer", "reviewer"],
@@ -191,7 +191,7 @@
     "evaluator": { "events": ["handoff.received", "eval.regression"], "severityImmediate": [], "fence": { "allowedPaths": ["docs/evals/**", ".cx/evals/**", "tests/evals/**"], "allowedBdLabels": ["eval", "regression-eval"], "allowedCommands": ["bd create", "bd note", "bd update"], "approvalRequired": ["commit", "push", "edit:**"] }, "outputs": { "bdLabels": ["eval"], "docTypes": ["memo"] }, "handoffCandidates": ["engineer", "ai-engineer"], "killSwitchEnv": "CONSTRUCT_ROLE_EVALUATOR" },
     "trace-reviewer": { "events": ["handoff.received", "trace.anomaly"], "severityImmediate": [], "fence": { "allowedPaths": ["docs/traces/**", ".cx/traces/**"], "allowedBdLabels": ["trace", "observability"], "allowedCommands": ["bd create", "bd note", "bd update"], "approvalRequired": ["commit", "push", "edit:**"] }, "outputs": { "bdLabels": ["trace"], "docTypes": ["memo"] }, "handoffCandidates": ["sre", "ai-engineer", "engineer"], "killSwitchEnv": "CONSTRUCT_ROLE_TRACE_REVIEWER" },
     "test-automation": { "events": ["handoff.received"], "severityImmediate": [], "fence": { "allowedPaths": ["tests/**", "docs/test-automation/**"], "allowedBdLabels": ["test-automation", "ci", "test-infra"], "allowedCommands": ["bd create", "bd note", "bd update"], "approvalRequired": ["commit", "push", "edit:lib/**", "edit:bin/**"] }, "outputs": { "bdLabels": ["test-automation"], "docTypes": ["memo"] }, "handoffCandidates": ["qa", "engineer", "platform-engineer"], "killSwitchEnv": "CONSTRUCT_ROLE_TEST_AUTOMATION" },
-    "ai-engineer": { "events": ["handoff.received"], "severityImmediate": [], "fence": { "allowedPaths": ["docs/ai/**", "docs/agents/**", "agents/**", "skills/ai/**"], "allowedBdLabels": ["ai", "agent", "model"], "allowedCommands": ["bd create", "bd note", "bd update"], "approvalRequired": ["commit", "push", "edit:lib/**", "edit:bin/**"] }, "outputs": { "bdLabels": ["ai"], "docTypes": ["memo"] }, "handoffCandidates": ["engineer", "architect", "evaluator"], "killSwitchEnv": "CONSTRUCT_ROLE_AI_ENGINEER" },
+    "ai-engineer": { "events": ["handoff.received"], "severityImmediate": [], "fence": { "allowedPaths": ["docs/ai/**", "docs/specialists/**", "specialists/**", "skills/ai/**"], "allowedBdLabels": ["ai", "agent", "model"], "allowedCommands": ["bd create", "bd note", "bd update"], "approvalRequired": ["commit", "push", "edit:lib/**", "edit:bin/**"] }, "outputs": { "bdLabels": ["ai"], "docTypes": ["memo"] }, "handoffCandidates": ["engineer", "architect", "evaluator"], "killSwitchEnv": "CONSTRUCT_ROLE_AI_ENGINEER" },
     "business-strategist": { "events": ["handoff.received"], "severityImmediate": [], "fence": { "allowedPaths": ["docs/strategy/**", ".cx/knowledge/decisions/strategy/**"], "allowedBdLabels": ["strategy", "business"], "allowedCommands": ["bd create", "bd note", "bd update"], "approvalRequired": ["commit", "push", "edit:**"] }, "outputs": { "bdLabels": ["strategy"], "docTypes": ["memo", "strategy"] }, "handoffCandidates": ["product-manager", "researcher"], "killSwitchEnv": "CONSTRUCT_ROLE_BUSINESS_STRATEGIST" },
     "researcher": {
       "events": ["handoff.received", "research.requested", "evidence.requested"],
@@ -209,7 +209,7 @@
     "ux-researcher": { "events": ["handoff.received"], "severityImmediate": [], "fence": { "allowedPaths": ["docs/ux-research/**", ".cx/ux-research/**"], "allowedBdLabels": ["ux-research", "user-research"], "allowedCommands": ["bd create", "bd note", "bd update"], "approvalRequired": ["commit", "push", "edit:**"] }, "outputs": { "bdLabels": ["ux-research"], "docTypes": ["memo"] }, "handoffCandidates": ["product-manager", "designer", "researcher"], "killSwitchEnv": "CONSTRUCT_ROLE_UX_RESEARCHER" },
     "explorer": { "events": ["handoff.received"], "severityImmediate": [], "fence": { "allowedPaths": ["docs/explorations/**", ".cx/explorations/**"], "allowedBdLabels": ["exploration", "spike"], "allowedCommands": ["bd create", "bd note", "bd update"], "approvalRequired": ["commit", "push", "edit:**"] }, "outputs": { "bdLabels": ["exploration"], "docTypes": ["memo"] }, "handoffCandidates": ["engineer", "architect", "researcher"], "killSwitchEnv": "CONSTRUCT_ROLE_EXPLORER" },
     "operations": { "events": ["handoff.received"], "severityImmediate": [], "fence": { "allowedPaths": ["docs/ops/**", "docs/operations/**"], "allowedBdLabels": ["ops", "operations"], "allowedCommands": ["bd create", "bd note", "bd update"], "approvalRequired": ["commit", "push", "edit:**"] }, "outputs": { "bdLabels": ["ops"], "docTypes": ["memo", "runbook"] }, "handoffCandidates": ["sre", "platform-engineer", "release-manager"], "killSwitchEnv": "CONSTRUCT_ROLE_OPERATIONS" },
-    "orchestrator": { "events": ["handoff.received"], "severityImmediate": [], "fence": { "allowedPaths": ["docs/**", "plan.md", ".cx/context.md"], "allowedBdLabels": ["orchestration", "workflow", "dispatch"], "allowedCommands": ["bd create", "bd note", "bd update", "bd label", "bd link"], "approvalRequired": ["commit", "push", "edit:lib/**", "edit:bin/**", "edit:agents/**"] }, "outputs": { "bdLabels": ["orchestration", "dispatch"], "docTypes": ["memo"] }, "handoffCandidates": ["product-manager", "architect", "engineer", "security", "qa", "sre"], "killSwitchEnv": "CONSTRUCT_ROLE_ORCHESTRATOR" },
+    "orchestrator": { "events": ["handoff.received"], "severityImmediate": [], "fence": { "allowedPaths": ["docs/**", "plan.md", ".cx/context.md"], "allowedBdLabels": ["orchestration", "workflow", "dispatch"], "allowedCommands": ["bd create", "bd note", "bd update", "bd label", "bd link"], "approvalRequired": ["commit", "push", "edit:lib/**", "edit:bin/**", "edit:specialists/**"] }, "outputs": { "bdLabels": ["orchestration", "dispatch"], "docTypes": ["memo"] }, "handoffCandidates": ["product-manager", "architect", "engineer", "security", "qa", "sre"], "killSwitchEnv": "CONSTRUCT_ROLE_ORCHESTRATOR" },
     "rd-lead": { "events": ["handoff.received"], "severityImmediate": [], "fence": { "allowedPaths": ["docs/research/**", "docs/experiments/**", ".cx/experiments/**"], "allowedBdLabels": ["rd", "research", "experiment"], "allowedCommands": ["bd create", "bd note", "bd update"], "approvalRequired": ["commit", "push", "edit:**"] }, "outputs": { "bdLabels": ["rd"], "docTypes": ["memo", "research-brief"] }, "handoffCandidates": ["researcher", "architect", "ai-engineer"], "killSwitchEnv": "CONSTRUCT_ROLE_RD_LEAD" },
     "legal-compliance": { "events": ["handoff.received"], "severityImmediate": [], "fence": { "allowedPaths": ["docs/legal/**", "docs/compliance/**", "docs/security/**", ".cx/knowledge/**"], "allowedBdLabels": ["legal", "compliance", "privacy"], "allowedCommands": ["bd create", "bd note", "bd update"], "approvalRequired": ["commit", "push", "edit:**"] }, "outputs": { "bdLabels": ["legal", "compliance"], "docTypes": ["memo"] }, "handoffCandidates": ["security", "product-manager"], "killSwitchEnv": "CONSTRUCT_ROLE_LEGAL_COMPLIANCE" },
     "devil-advocate": { "events": ["handoff.received"], "severityImmediate": [], "fence": { "allowedPaths": ["docs/critiques/**"], "allowedBdLabels": ["critique", "devil-advocate"], "allowedCommands": ["bd create", "bd note", "bd update"], "approvalRequired": ["commit", "push", "edit:**"] }, "outputs": { "bdLabels": ["critique"], "docTypes": ["memo"] }, "handoffCandidates": ["architect", "product-manager", "engineer"], "killSwitchEnv": "CONSTRUCT_ROLE_DEVIL_ADVOCATE" }

package/templates/provider-scaffold/health.test.mjs

@@ -0,0 +1,30 @@
+/**
+ * templates/provider-scaffold/health.test.mjs — scaffold health test template.
+ *
+ * Verifies that the scaffolded provider's health() function can be called and
+ * returns a result with the expected shape. Replace the import path and add
+ * real assertions once the provider is implemented.
+ *
+ * Placeholder: %%PROVIDER_NAME%%
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { create } from '../../lib/providers/%%PROVIDER_NAME%%/index.mjs';
+
+describe('%%PROVIDER_NAME%% provider health', () => {
+  it('health() returns an object with an ok field', async () => {
+    const provider = create();
+    const result = await provider.health();
+    assert.ok(typeof result === 'object' && result !== null, 'health() must return an object');
+    assert.ok('ok' in result, 'health() result must have an ok field');
+    assert.ok(typeof result.ok === 'boolean', 'health().ok must be a boolean');
+  });
+
+  it('provider satisfies the contract shape', () => {
+    const provider = create();
+    assert.ok(provider.meta, 'provider must have a meta object');
+    assert.equal(provider.meta.id, '%%PROVIDER_NAME%%');
+    assert.ok(Array.isArray(provider.meta.capabilities), 'meta.capabilities must be an array');
+    assert.ok(typeof provider.health === 'function', 'provider must export health()');
+  });
+});

package/templates/provider-scaffold/index.mjs

@@ -0,0 +1,48 @@
+/**
+ * lib/providers/%%PROVIDER_NAME%%/index.mjs — %%PROVIDER_NAME%% provider.
+ *
+ * Capabilities: %%CAPABILITIES%%
+ *
+ * Generated by `construct scaffold provider %%PROVIDER_NAME%%`.
+ * Replace every TODO comment with a real implementation before using this
+ * provider in production.
+ */
+import { validateAllowlist } from '../contract.mjs';
+
+const PROVIDER_NAME = '%%PROVIDER_NAME%%';
+
+export function create({ env = process.env } = {}) {
+  return {
+    meta: {
+      id: PROVIDER_NAME,
+      displayName: '%%PROVIDER_NAME%%',
+      capabilities: ['%%CAPABILITIES%%'],
+      description: '%%PROVIDER_NAME%% provider (scaffolded — fill in details)',
+    },
+
+    configSchema: {
+      $schema: 'https://json-schema.org/draft/2020-12/schema',
+      type: 'object',
+      properties: {},
+    },
+
+    async health() {
+      // Replace with a real connectivity check that returns { ok, detail }. // construct-lint-ignore
+      return { ok: false, reason: 'not implemented' };
+    },
+
+    async read(resource, config = {}) {
+      const check = validateAllowlist(PROVIDER_NAME, resource, config);
+      if (!check.allowed) throw Object.assign(new Error(check.reason), { code: 'OUT_OF_SCOPE' });
+      // Replace with a real fetch against the remote system. // construct-lint-ignore
+      throw new Error('not implemented');
+    },
+
+    async search(query, config = {}) {
+      // Replace with a real query against the remote system; return an array of items. // construct-lint-ignore
+      throw new Error('not implemented');
+    },
+  };
+}
+
+export default create;

package/templates/workflows/cross-team-handoff.yml

@@ -0,0 +1,85 @@
+version: 1
+id: cross-team-handoff
+title: Cross-team handoff workflow
+description: Structured handoff across Eng, PM, Support, and Ops. Scaffolds the handoff brief, owner mapping, and success criteria so every receiving team has the context it needs before the sender is gone.
+
+inputs:
+  - name: project_name
+    prompt: "Project or feature being handed off (lowercase-hyphenated)"
+    required: true
+  - name: sending_team
+    prompt: "Team handing off (e.g. eng, pm, infra)"
+    required: true
+  - name: receiving_team
+    prompt: "Team taking ownership (e.g. support, ops, pm)"
+    required: true
+  - name: handoff_date
+    prompt: "Target handoff date (YYYY-MM-DD)"
+    default: "TBD"
+  - name: primary_contact
+    prompt: "Primary contact on the sending team"
+    default: "TBD"
+
+artifacts:
+  - template: memo.md
+    path: "docs/handoffs/${project_name}/brief.md"
+    title: "Handoff brief: ${project_name} from ${sending_team} to ${receiving_team}"
+
+  - template: rfc.md
+    path: "docs/handoffs/${project_name}/owner-mapping.md"
+    title: "Owner mapping: ${project_name}"
+    depends_on:
+      - "docs/handoffs/${project_name}/brief.md"
+
+  - template: prd.md
+    path: "docs/handoffs/${project_name}/success-criteria.md"
+    title: "Success criteria: ${project_name} post-handoff"
+    depends_on:
+      - "docs/handoffs/${project_name}/owner-mapping.md"
+
+  - template: runbook.md
+    path: "docs/handoffs/${project_name}/ops-runbook.md"
+    title: "Ops runbook: ${project_name}"
+    depends_on:
+      - "docs/handoffs/${project_name}/success-criteria.md"
+
+beads_items:
+  - type: task
+    title: "${project_name}: draft handoff brief (${sending_team})"
+    link_to: "docs/handoffs/${project_name}/brief.md"
+
+  - type: task
+    title: "${project_name}: agree owner mapping with ${receiving_team}"
+    link_to: "docs/handoffs/${project_name}/owner-mapping.md"
+    depends_on_prior: true
+
+  - type: task
+    title: "${project_name}: sign off success criteria"
+    link_to: "docs/handoffs/${project_name}/success-criteria.md"
+    depends_on_prior: true
+
+  - type: task
+    title: "${project_name}: ops runbook review and acceptance"
+    link_to: "docs/handoffs/${project_name}/ops-runbook.md"
+    depends_on_prior: true
+
+  - type: task
+    title: "${project_name}: handoff complete on ${handoff_date}"
+    depends_on_prior: true
+
+checks:
+  - name: brief-precedes-owner-mapping
+    kind: file-order
+    files:
+      - "docs/handoffs/${project_name}/brief.md"
+      - "docs/handoffs/${project_name}/owner-mapping.md"
+  - name: owner-mapping-precedes-success-criteria
+    kind: file-order
+    files:
+      - "docs/handoffs/${project_name}/owner-mapping.md"
+      - "docs/handoffs/${project_name}/success-criteria.md"
+  - name: success-criteria-precedes-runbook
+    kind: file-order
+    files:
+      - "docs/handoffs/${project_name}/success-criteria.md"
+      - "docs/handoffs/${project_name}/ops-runbook.md"

package/templates/workflows/engineering-onboarding.yml

@@ -0,0 +1,77 @@
+version: 1
+id: engineering-onboarding
+title: Engineering onboarding workflow
+description: Day-1 setup through week-1 checkpoint. Scaffolds the onboarding brief, access checklist, and milestone handoff artifacts so a new engineer has documented progress at each stage.
+
+inputs:
+  - name: engineer_name
+    prompt: "New engineer's full name"
+    required: true
+  - name: team_name
+    prompt: "Team name (e.g. platform, growth, infra)"
+    required: true
+  - name: manager_name
+    prompt: "Onboarding manager's name"
+    default: "TBD"
+  - name: start_date
+    prompt: "Start date (YYYY-MM-DD)"
+    default: "TBD"
+
+artifacts:
+  - template: onboarding.md
+    path: "docs/onboarding/${engineer_name}/brief.md"
+    title: "Onboarding brief: ${engineer_name}"
+
+  - template: runbook.md
+    path: "docs/onboarding/${engineer_name}/day-1-checklist.md"
+    title: "Day-1 checklist: ${engineer_name} on ${team_name}"
+    depends_on:
+      - "docs/onboarding/${engineer_name}/brief.md"
+
+  - template: runbook.md
+    path: "docs/onboarding/${engineer_name}/day-3-checkpoint.md"
+    title: "Day-3 checkpoint: ${engineer_name}"
+    depends_on:
+      - "docs/onboarding/${engineer_name}/day-1-checklist.md"
+
+  - template: memo.md
+    path: "docs/onboarding/${engineer_name}/week-1-handoff.md"
+    title: "Week-1 handoff: ${engineer_name} to ${manager_name}"
+    depends_on:
+      - "docs/onboarding/${engineer_name}/day-3-checkpoint.md"
+
+beads_items:
+  - type: task
+    title: "${engineer_name}: day-1 setup"
+    link_to: "docs/onboarding/${engineer_name}/day-1-checklist.md"
+
+  - type: task
+    title: "${engineer_name}: day-3 checkpoint review"
+    link_to: "docs/onboarding/${engineer_name}/day-3-checkpoint.md"
+    depends_on_prior: true
+
+  - type: task
+    title: "${engineer_name}: week-1 handoff with ${manager_name}"
+    link_to: "docs/onboarding/${engineer_name}/week-1-handoff.md"
+    depends_on_prior: true
+
+  - type: task
+    title: "${engineer_name}: onboarding complete sign-off"
+    depends_on_prior: true
+
+checks:
+  - name: brief-precedes-checklist
+    kind: file-order
+    files:
+      - "docs/onboarding/${engineer_name}/brief.md"
+      - "docs/onboarding/${engineer_name}/day-1-checklist.md"
+  - name: checklist-precedes-checkpoint
+    kind: file-order
+    files:
+      - "docs/onboarding/${engineer_name}/day-1-checklist.md"
+      - "docs/onboarding/${engineer_name}/day-3-checkpoint.md"
+  - name: checkpoint-precedes-handoff
+    kind: file-order
+    files:
+      - "docs/onboarding/${engineer_name}/day-3-checkpoint.md"
+      - "docs/onboarding/${engineer_name}/week-1-handoff.md"

package/templates/workflows/new-feature.yml

@@ -0,0 +1,53 @@
+version: 1
+id: new-feature
+title: New feature workflow
+description: PRD to ADR to tests to implementation to review chain.
+
+inputs:
+  - name: feature_name
+    prompt: "Short feature name (lowercase-hyphenated)"
+    required: true
+  - name: owner
+    prompt: "Owner specialist"
+    default: engineer
+
+artifacts:
+  - template: prd.md
+    path: "docs/prd/${feature_name}.md"
+    title: "PRD: ${feature_name}"
+
+  - template: adr.md
+    path: "docs/adr/${feature_name}.md"
+    title: "ADR: ${feature_name}"
+    depends_on:
+      - "docs/prd/${feature_name}.md"
+
+  - template: test-plan.md
+    path: "docs/test-plans/${feature_name}.md"
+    depends_on:
+      - "docs/adr/${feature_name}.md"
+
+beads_items:
+  - type: feature
+    title: "${feature_name}: spec"
+    link_to: "docs/prd/${feature_name}.md"
+
+  - type: feature
+    title: "${feature_name}: design"
+    link_to: "docs/adr/${feature_name}.md"
+    depends_on_prior: true
+
+  - type: feature
+    title: "${feature_name}: implementation"
+    depends_on_prior: true
+
+  - type: feature
+    title: "${feature_name}: review"
+    depends_on_prior: true
+
+checks:
+  - name: prd-precedes-adr
+    kind: file-order
+    files:
+      - "docs/prd/${feature_name}.md"
+      - "docs/adr/${feature_name}.md"