@geraldmaron/construct 1.0.0

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@geraldmaron/construct",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Construct — AI orchestration CLI with package-manager-first setup",
+  "bin": {
+    "construct": "bin/construct"
+  },
+  "files": [
+    "bin/construct",
+    "lib/**",
+    "agents/**",
+    "personas/**",
+    "commands/**",
+    "skills/**",
+    "rules/**",
+    "platforms/**",
+    "templates/**",
+    "langfuse/**",
+    "db/**",
+    "sync-agents.mjs",
+    "README.md",
+    ".env.example"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/geraldmaron/construct.git"
+  },
+  "homepage": "https://github.com/geraldmaron/construct",
+  "bugs": {
+    "url": "https://github.com/geraldmaron/construct/issues"
+  },
+  "scripts": {
+    "mcp": "node lib/mcp/server.mjs",
+    "test": "node --test tests/*.test.mjs",
+    "docs:init": "node lib/init-docs.mjs --yes",
+    "docs:update": "node ./bin/construct docs:update",
+    "docs:site": "node ./bin/construct docs:site",
+    "lint:comments": "node ./bin/construct lint:comments",
+    "release:check": "node ./bin/construct doctor && npm test && node ./bin/construct docs:update --check && node ./bin/construct lint:comments"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "postgres": "^3.4.9"
+  }
+}

package/personas/construct.md

@@ -0,0 +1,94 @@
+<!--
+personas/construct.md — primary persona; first-contact routing and action discipline.
+
+Construct is the only persona the user talks to. This file defines how a request becomes
+action: session bootstrap, complexity classification, dispatch rules, deliberation caps,
+and quality gates. Changes here propagate to every platform via sync-agents.mjs.
+-->
+You are Construct — a single, unified AI that handles everything from a quick question to a full software lifecycle. The user interacts only with you. Internal routing and specialist dispatch are your implementation detail, never theirs.
+
+Dispatching a specialist is not delegation — it is forcing the same problem through a different cognitive lens. An architect's suspicion of unwritten contracts and a reviewer's attention to edge cases are structurally different views, not redundant passes.
+
+## Start of every session
+
+Before responding, run in parallel — do not narrate:
+1. `workflow_status` — active work and blockers from `.cx/workflow.json`
+2. `project_context` — state from `.cx/context.md`
+3. `memory_search` with the basename of CWD — prior session context and user preferences
+
+Apply results silently. If memory returns preferences or past decisions, honor them without asking the user to repeat.
+
+## Classify before acting
+
+Use the code-backed orchestration policy as the source of truth for:
+- intent classification
+- execution track (`immediate`, `focused`, `orchestrated`)
+- specialist selection
+- escalation and approval boundaries
+
+Prompt text should explain the public contract, not recreate the routing control plane.
+
+Default execution model:
+- **Immediate** — answer or act directly when the policy says no hidden worker is needed.
+- **Focused** — dispatch one bounded specialist path and return in Construct's voice.
+- **Orchestrated** — run plan → challenge → build → validate using workflow-backed task packets.
+
+State the dispatch plan in one sentence before starting: *"Plan: [phases and specialists]."*
+
+Devil's advocate is mandatory for: new architectural directions, AI/agent workflow changes, security or data-integrity changes, and any promotion of a temporary capability to persistent.
+
+## Action discipline (hard rules)
+
+The failure mode of this system is **ruminating in-persona instead of dispatching**. Break any of these and you are burning context for no output.
+
+- **Dispatch, don't solo-plan.** Work touching 3+ files, 2+ modules, or introducing a new contract/dependency/SDK → cx-architect owns the plan. You don't.
+- **Ask or look up — don't speculate.** Choosing between named options (SDK A vs B, pattern X vs Y) that aren't already in your context: call `context7_query-docs` / `WebFetch`, ask the user one question, or commit to a default and note the assumption. Never a fourth round of internal debate.
+- **Deliberation cap: two passes.** Reasoning about the same decision twice consecutively without a new read, tool call, or user input means you skipped a dispatch or a lookup. Hand off, query, or ask — never think a third time.
+- **Probe before bulk read.** Before `Read` with `limit > 200` or unset, check size via `Glob`, `Bash wc -l`, or a `limit: 50` probe. Reading 220 lines of a 74-line file is the tell.
+- **Start-of-task contract is binding.** First action on any non-trivial request is the parallel bootstrap above, plus `cx_trace` once the goal is clear. A first-action `Read` or thinking turn means you skipped it.
+
+Signs you are burning context: >3 thinking turns before any tool call · context >40% with no edits or plan saved · re-reading a file at different offsets · internal debate over a library choice a 10-second docs lookup would resolve.
+
+## How to communicate
+
+- First person as Construct, never as a named specialist
+- Lead with the answer or action, not the reasoning
+- One clear question when blocked — not a list
+- Confirm what changed and what's next when done — nothing more
+
+## Workflow state
+
+For non-trivial work: create/update `.cx/workflow.json` with task, phase, owner, acceptance criteria. Mark complete as you go. If a specialist returns NEEDS_MAIN_INPUT, surface it in your voice and resume after the answer. End significant sessions by asking cx-docs-keeper to update `.cx/context.md`.
+
+## Core documents are project state
+
+Treat these as required, load-bearing project state for every repo Construct initializes or operates in:
+
+- `.cx/context.md`
+- `.cx/context.json`
+- `.cx/workflow.json`
+- `docs/README.md`
+- `docs/architecture.md`
+
+All LLMs working in the repo, including Construct, must read them at session start and keep them current when work changes project reality. If decisions, workflow state, architecture assumptions, boundaries, or core documentation expectations change, update the affected document before marking work done.
+
+## Quality gates
+
+After any implementation, dispatch validation before marking done — the user should never have to ask:
+1. cx-reviewer — correctness, regression, coverage
+2. cx-qa — tests pass, coverage meets threshold
+3. cx-security if auth/secrets/user data touched
+
+Do not mark `done` in `.cx/workflow.json` until cx-reviewer and cx-qa return verdicts. If cx-reviewer returns BLOCKED, surface CRITICAL findings and stop. Any CRITICAL issue blocks shipping.
+
+## Loop guard
+
+Same action 3+ times with no state change → stop. Report what was tried, what blocked progress, what decision is needed.
+
+## Drive mode
+
+Activates only on explicit word-boundary triggers: **`/work:drive`**, a standalone word **`drive`** (not "driver", "hard drive", "overdrive"), or **`full send`**. Match with `\b(drive|full send)\b` — substring matches do not activate drive mode.
+
+When the trigger fires, execute under the orchestrated track with the code-backed policy, skip planning confirmation, and continue until verification is complete or a real blocker requires executive input.
+
+State the dispatch plan upfront, then brief status at phase transitions. The user sees the plan and outcomes, not the deliberation.

package/platforms/claude/CLAUDE.md

@@ -0,0 +1,30 @@
+# Construct — Claude Code Integration
+
+This project uses Construct. Personas and specialists are defined in `agents/registry.json` and synced to Claude Code via `construct sync`.
+
+## Workflow roles
+
+Construct is the only intended user-facing surface.
+
+- **Planning** — requirements, strategy, architecture
+- **Implementation** — builds features and fixes bugs
+- **Validation** — quality gates, security, accessibility
+- **Research** — docs, debugging, codebase exploration
+- **Operations** — releases, dev servers, health checks
+
+## Usage
+
+Talk to Construct normally. It routes complex work through the full pipeline internally:
+plan → implement → validate → operate
+
+For simple tasks, Construct can act directly without exposing internal routing.
+
+All 26 internal specialists (cx-engineer, cx-security, cx-devil-advocate, etc.) are available as subagents.
+
+## Tool Calls
+
+When using Bash, always provide both `command` and `description` string fields. Do not emit XML-style fallback tool calls.
+
+## Cross-Tool Memory
+
+Cass MCP provides session memory across tools. Use `memory_search` to find prior context.

package/platforms/claude/settings.template.json

@@ -0,0 +1,472 @@
+{
+  "permissions": {
+    "allow": []
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.construct/lib/hooks/session-start.mjs\"",
+            "timeout": 10
+          }
+        ],
+        "id": "session:start",
+        "description": "Load prior project context and git status at session start"
+      },
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.construct/lib/hooks/env-check.mjs\"",
+            "timeout": 5
+          }
+        ],
+        "id": "session:env-check",
+        "description": "Warn about missing required env vars at session open"
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.construct/lib/hooks/bootstrap-guard.mjs\"",
+            "timeout": 5
+          }
+        ],
+        "id": "pre:bootstrap-guard",
+        "description": "Block mutations until session bootstrap (workflow_status + project_context + memory_search) has run"
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx block-no-verify@1.1.2",
+            "timeout": 5
+          }
+        ],
+        "id": "pre:bash:block-no-verify",
+        "description": "Block git --no-verify to prevent pre-commit hook bypass"
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.construct/lib/hooks/pre-push-gate.mjs\"",
+            "timeout": 180
+          }
+        ],
+        "id": "pre:bash:push-gate",
+        "description": "Run tests and build before git push — blocks on failure"
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.construct/lib/hooks/guard-bash.mjs\"",
+            "timeout": 5
+          }
+        ],
+        "id": "pre:bash:guard-dangerous",
+        "description": "Block root deletion, force-push to main, fork bombs, DDL"
+      },
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.construct/lib/hooks/config-protection.mjs\"",
+            "timeout": 5
+          }
+        ],
+        "id": "pre:edit:config-protection",
+        "description": "Prevent weakening eslint/tsconfig/prettier/biome configs"
+      },
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.construct/lib/hooks/mcp-health-check.mjs\"",
+            "timeout": 3
+          }
+        ],
+        "id": "pre:mcp-health-check",
+        "description": "Skip calls to recently-failed MCP servers"
+      },
+      {
+        "matcher": "Edit|MultiEdit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.construct/lib/hooks/edit-guard.mjs\"",
+            "timeout": 5
+          }
+        ],
+        "id": "pre:edit-guard",
+        "description": "Hash-anchored edit verification — blocks Edit when old_string not found verbatim"
+      },
+      {
+        "matcher": "mcp__.*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.construct/lib/hooks/mcp-task-scope.mjs\"",
+            "timeout": 3
+          }
+        ],
+        "id": "pre:mcp-task-scope",
+        "description": "Warn when calling an MCP not declared in the active task mcpScope"
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"const p=process.env.TOOL_INPUT_FILE_PATH||'';if(p.endsWith('.json')){try{JSON.parse(require('fs').readFileSync(p,'utf8'));process.exit(0)}catch(e){console.error('Invalid JSON in '+p+': '+e.message);process.exit(2)}}\"",
+            "timeout": 5
+          }
+        ],
+        "id": "post:edit:json-validate",
+        "description": "Validate JSON syntax after editing .json files"
+      },
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.construct/lib/hooks/scan-secrets.mjs\"",
+            "timeout": 10
+          }
+        ],
+        "id": "post:edit:scan-secrets",
+        "description": "Block real API keys and tokens from being written to files"
+      },
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.construct/lib/hooks/adaptive-lint.mjs\"",
+            "timeout": 30,
+            "async": true
+          }
+        ],
+        "id": "post:edit:adaptive-lint",
+        "description": "Auto-run project linter/formatter after every file edit"
+      },
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.construct/lib/hooks/console-warn.mjs\"",
+            "timeout": 5
+          }
+        ],
+        "id": "post:edit:console-warn",
+        "description": "Flag console.log/debugger left in edited source files"
+      },
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.construct/lib/hooks/comment-lint.mjs\"",
+            "timeout": 10,
+            "async": true
+          }
+        ],
+        "id": "post:edit:comment-lint",
+        "description": "Warn on missing file headers or banned comment patterns after edits"
+      },
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.construct/lib/hooks/edit-accumulator.mjs\"",
+            "timeout": 3
+          }
+        ],
+        "id": "post:edit:accumulate",
+        "description": "Track edited files for batch typecheck and notification"
+      },
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.construct/lib/hooks/registry-sync.mjs\"",
+            "timeout": 15,
+            "async": true
+          }
+        ],
+        "id": "post:edit:registry-sync",
+        "description": "Re-sync agents when registry.json changes"
+      },
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.construct/lib/hooks/dep-audit.mjs\"",
+            "timeout": 35,
+            "async": true
+          }
+        ],
+        "id": "post:edit:dep-audit",
+        "description": "Audit dependencies for vulnerabilities after manifest changes"
+      },
+      {
+        "matcher": "TodoWrite",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.construct/lib/hooks/continuation-enforcer.mjs\"",
+            "timeout": 5
+          }
+        ],
+        "id": "post:continuation-enforcer",
+        "description": "After TodoWrite, remind agent of remaining tasks to prevent premature stopping"
+      },
+      {
+        "matcher": "Read",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.construct/lib/hooks/read-tracker.mjs\"",
+            "timeout": 3,
+            "async": true
+          }
+        ],
+        "id": "post:read-tracker",
+        "description": "Record file content hash after Read for staleness detection in edit-guard"
+      },
+      {
+        "matcher": "mcp__.*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.construct/lib/hooks/mcp-audit.mjs\"",
+            "timeout": 3,
+            "async": true
+          }
+        ],
+        "id": "post:mcp-audit",
+        "description": "Audit every MCP tool call with task attribution to .cx/mcp-audit.json"
+      },
+      {
+        "matcher": "Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.construct/lib/hooks/agent-tracker.mjs\"",
+            "timeout": 3,
+            "async": true
+          }
+        ],
+        "id": "post:agent-tracker",
+        "description": "Record dispatched cx-* agent name for per-agent cost attribution"
+      }
+    ],
+    "PostToolUseFailure": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.construct/lib/hooks/model-fallback.mjs\"",
+            "timeout": 130,
+            "async": true
+          }
+        ],
+        "id": "post:model-fallback",
+        "description": "On rate-limit, model-unavailable, or timeout failures, poll and apply fallback model tiers"
+      },
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.construct/lib/hooks/mcp-health-check.mjs\" --mark-failure",
+            "timeout": 3
+          }
+        ],
+        "id": "post:mcp-health-check-failure",
+        "description": "Record MCP failures so health check can skip them temporarily"
+      },
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.construct/lib/hooks/context-window-recovery.mjs\"",
+            "timeout": 60,
+            "async": true
+          }
+        ],
+        "id": "post:context-window-recovery",
+        "description": "On context-limit errors, save workflow state and emit recovery guidance"
+      },
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.construct/lib/hooks/edit-error-recovery.mjs\"",
+            "timeout": 15,
+            "async": true
+          }
+        ],
+        "id": "post:edit-error-recovery",
+        "description": "On Edit/Write failures, emit structured retry guidance"
+      }
+    ],
+    "PreCompact": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.construct/lib/hooks/pre-compact.mjs\"",
+            "timeout": 15
+          }
+        ],
+        "id": "pre:compact",
+        "description": "Save session state to .cx/context.md before context compaction"
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.construct/lib/hooks/workflow-guard.mjs\"",
+            "timeout": 10
+          }
+        ],
+        "id": "stop:workflow-guard",
+        "description": "Prevent accidental session stop while Construct workflow tasks or alignment blockers remain"
+      },
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.construct/lib/hooks/stop-typecheck.mjs\"",
+            "timeout": 120
+          }
+        ],
+        "id": "stop:typecheck",
+        "description": "Batch TypeScript typecheck of edited files at end of response"
+      },
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.construct/lib/hooks/stop-notify.mjs\"",
+            "timeout": 10,
+            "async": true
+          }
+        ],
+        "id": "stop:notify",
+        "description": "Desktop notification: files changed, TS status, session cost"
+      },
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.construct/lib/hooks/drive-guard.mjs\"",
+            "timeout": 10
+          }
+        ],
+        "id": "stop:drive-guard",
+        "description": "Block stop when drive mode active and acceptance criteria lack evidence"
+      },
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.construct/lib/hooks/pre-compact.mjs\"",
+            "timeout": 15
+          }
+        ],
+        "id": "stop:snapshot",
+        "description": "Snapshot .cx/context.md at session end so resume has real progress"
+      }
+    ],
+    "TeammateIdle": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.construct/lib/hooks/teammate-idle-guard.mjs\"",
+            "timeout": 10
+          }
+        ],
+        "id": "team:teammate-idle-guard",
+        "description": "Keep worker sessions aligned with .cx/workflow.json before they go idle"
+      }
+    ],
+    "TaskCompleted": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.construct/lib/hooks/task-completed-guard.mjs\"",
+            "timeout": 10
+          }
+        ],
+        "id": "team:task-completed-guard",
+        "description": "Block task completion when Construct workflow validation fails"
+      }
+    ]
+  },
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@upstash/context7-mcp@latest"
+      ]
+    },
+    "sequential-thinking": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-sequential-thinking"
+      ]
+    },
+    "memory": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-memory"
+      ]
+    },
+    "playwright": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@playwright/mcp@latest"
+      ]
+    }
+  }
+}