@geraldmaron/construct 1.0.0

package/platforms/opencode/config.template.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "model": "openrouter/openrouter/free",
+  "enabled_providers": [
+    "anthropic",
+    "openai",
+    "openrouter",
+    "ollama"
+  ],
+  "provider": {
+    "anthropic": {
+      "models": {}
+    },
+    "openai": {
+      "models": {}
+    },
+    "openrouter": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "OpenRouter",
+      "options": {
+        "baseURL": "https://openrouter.ai/api/v1",
+        "headers": {
+          "HTTP-Referer": "__OPENROUTER_REFERER__",
+          "X-Title": "__OPENROUTER_TITLE__",
+          "Authorization": "Bearer __OPENROUTER_API_KEY__"
+        }
+      },
+      "models": {}
+    },
+    "ollama": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "Ollama (local)",
+      "options": {
+        "baseURL": "http://localhost:11434/v1",
+        "headers": {
+          "Authorization": "Bearer ollama"
+        }
+      },
+      "models": {}
+    }
+  },
+  "mcp": {
+    "cass": {
+      "type": "local",
+      "command": ["npx", "-y", "@modelcontextprotocol/server-memory@latest"]
+    },
+    "context7": {
+      "type": "local",
+      "command": ["npx", "-y", "@upstash/context7-mcp@latest"]
+    },
+    "construct-mcp": {
+      "type": "local",
+      "command": ["node", "__CX_TOOLKIT_DIR__/lib/mcp/server.mjs"],
+      "environment": {
+        "CONSTRUCT_TRACE_BACKEND": "__CONSTRUCT_TRACE_BACKEND__",
+        "LANGFUSE_BASEURL": "__LANGFUSE_BASEURL__",
+        "LANGFUSE_PUBLIC_KEY": "__LANGFUSE_PUBLIC_KEY__",
+        "LANGFUSE_SECRET_KEY": "__LANGFUSE_SECRET_KEY__"
+      }
+    }
+  },
+  "agent": {
+    "__AGENTS_GENERATED_BY_CONSTRUCT_SYNC__": {}
+  }
+}

package/platforms/opencode/plugins/construct-fallback.js

@@ -0,0 +1,5 @@
+import { createConstructOpenCodePlugin } from "__CX_TOOLKIT_DIR__/lib/opencode-runtime-plugin.mjs";
+
+export const ConstructFallbackPlugin = createConstructOpenCodePlugin({
+  toolkitDir: process.env.CX_TOOLKIT_DIR || "__CX_TOOLKIT_DIR__",
+});

package/platforms/opencode/sync-config.mjs

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+/**
+ * sync-config.mjs — Fetch free models from OpenRouter and sync into OpenCode config.
+ * Run periodically or during install to keep the free model list current.
+ */
+import fs from "node:fs";
+import { readOpenCodeConfig, writeOpenCodeConfig, findOpenCodeConfigPath } from "../lib/opencode-config.mjs";
+
+const configPath = findOpenCodeConfigPath();
+
+async function fetchFreeModels() {
+  try {
+    const res = await fetch("https://openrouter.ai/api/v1/models");
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    const { data } = await res.json();
+    return data
+      .filter((m) => m.id.endsWith(":free") && m.context_length >= 4096)
+      .map((m) => ({ id: m.id, name: m.name || m.id.replace(/:free$/, "") }))
+      .sort((a, b) => a.name.localeCompare(b.name));
+  } catch (err) {
+    console.warn(`Warning: Could not fetch OpenRouter models: ${err.message}`);
+    return [];
+  }
+}
+
+async function main() {
+  if (!fs.existsSync(configPath)) {
+    console.log("OpenCode config not found. Run 'construct sync' first.");
+    return;
+  }
+
+  const { config } = readOpenCodeConfig();
+  const freeModels = await fetchFreeModels();
+
+  if (freeModels.length === 0) {
+    console.log("No free models fetched. Config unchanged.");
+    return;
+  }
+
+  if (!config.provider) config.provider = {};
+  if (!config.provider.openrouter) {
+    config.provider.openrouter = {
+      npm: "@ai-sdk/openai-compatible",
+      name: "OpenRouter",
+      options: {
+        baseURL: "https://openrouter.ai/api/v1",
+        headers: {}
+      },
+      models: {}
+    };
+  }
+
+  const existingModels = config.provider.openrouter.models ?? {};
+  const merged = { ...existingModels };
+  for (const model of freeModels) {
+    if (!merged[model.id]) {
+      merged[model.id] = { name: `${model.name} (free)` };
+    }
+  }
+
+  config.provider.openrouter.models = Object.fromEntries(
+    Object.entries(merged).sort((a, b) => (a[1].name ?? a[0]).localeCompare(b[1].name ?? b[0]))
+  );
+
+  writeOpenCodeConfig(config, configPath);
+  console.log(`Synced ${freeModels.length} free models from OpenRouter.`);
+}
+
+main();

package/rules/common/agents.md

@@ -0,0 +1,55 @@
+<!--
+rules/common/agents.md — <one-line purpose>
+
+<2–6 line summary.>
+-->
+# Agent Orchestration
+
+## Available Agents
+
+Located in `~/.claude/agents/`:
+
+| Agent | Purpose | When to Use |
+|-------|---------|-------------|
+| planner | Implementation planning | Complex features, refactoring |
+| architect | System design | Architectural decisions |
+| tdd-guide | Test-driven development | New features, bug fixes |
+| code-reviewer | Code review | After writing code |
+| security-reviewer | Security analysis | Before commits |
+| build-error-resolver | Fix build errors | When build fails |
+| e2e-runner | E2E testing | Critical user flows |
+| refactor-cleaner | Dead code cleanup | Code maintenance |
+| doc-updater | Documentation | Updating docs |
+| rust-reviewer | Rust code review | Rust projects |
+
+## Immediate Agent Usage
+
+No user prompt needed:
+1. Complex feature requests - Use **planner** agent
+2. Code just written/modified - Use **code-reviewer** agent
+3. Bug fix or new feature - Use **tdd-guide** agent
+4. Architectural decision - Use **architect** agent
+
+## Parallel Task Execution
+
+ALWAYS use parallel Task execution for independent operations:
+
+```markdown
+# GOOD: Parallel execution
+Launch 3 agents in parallel:
+1. Agent 1: Security analysis of auth module
+2. Agent 2: Performance review of cache system
+3. Agent 3: Type checking of utilities
+
+# BAD: Sequential when unnecessary
+First agent 1, then agent 2, then agent 3
+```
+
+## Multi-Perspective Analysis
+
+For complex problems, use split role sub-agents:
+- Factual reviewer
+- Senior engineer
+- Security expert
+- Consistency reviewer
+- Redundancy checker

package/rules/common/code-review.md

@@ -0,0 +1,129 @@
+<!--
+rules/common/code-review.md — <one-line purpose>
+
+<2–6 line summary.>
+-->
+# Code Review Standards
+
+## Purpose
+
+Code review ensures quality, security, and maintainability before code is merged. This rule defines when and how to conduct code reviews.
+
+## When to Review
+
+**MANDATORY review triggers:**
+
+- After writing or modifying code
+- Before any commit to shared branches
+- When security-sensitive code is changed (auth, payments, user data)
+- When architectural changes are made
+- Before merging pull requests
+
+**Pre-Review Requirements:**
+
+Before requesting review, ensure:
+
+- All automated checks (CI/CD) are passing
+- Merge conflicts are resolved
+- Branch is up to date with target branch
+
+## Review Checklist
+
+Before marking code complete:
+
+- [ ] Code is readable and well-named
+- [ ] Functions are focused (<50 lines)
+- [ ] Files are cohesive (<800 lines)
+- [ ] No deep nesting (>4 levels)
+- [ ] Errors are handled explicitly
+- [ ] No hardcoded secrets or credentials
+- [ ] No console.log or debug statements
+- [ ] Tests exist for new functionality
+- [ ] Test coverage meets 80% minimum
+
+## Security Review Triggers
+
+**STOP and use security-reviewer agent when:**
+
+- Authentication or authorization code
+- User input handling
+- Database queries
+- File system operations
+- External API calls
+- Cryptographic operations
+- Payment or financial code
+
+## Review Severity Levels
+
+| Level | Meaning | Action |
+|-------|---------|--------|
+| CRITICAL | Security vulnerability or data loss risk | **BLOCK** - Must fix before merge |
+| HIGH | Bug or significant quality issue | **WARN** - Should fix before merge |
+| MEDIUM | Maintainability concern | **INFO** - Consider fixing |
+| LOW | Style or minor suggestion | **NOTE** - Optional |
+
+## Agent Usage
+
+Use these agents for code review:
+
+| Agent | Purpose |
+|-------|---------|
+| **code-reviewer** | General code quality, patterns, best practices |
+| **security-reviewer** | Security vulnerabilities, OWASP Top 10 |
+| **typescript-reviewer** | TypeScript/JavaScript specific issues |
+| **python-reviewer** | Python specific issues |
+| **go-reviewer** | Go specific issues |
+| **rust-reviewer** | Rust specific issues |
+
+## Review Workflow
+
+```
+1. Run git diff to understand changes
+2. Check security checklist first
+3. Review code quality checklist
+4. Run relevant tests
+5. Verify coverage >= 80%
+6. Use appropriate agent for detailed review
+```
+
+## Common Issues to Catch
+
+### Security
+
+- Hardcoded credentials (API keys, passwords, tokens)
+- SQL injection (string concatenation in queries)
+- XSS vulnerabilities (unescaped user input)
+- Path traversal (unsanitized file paths)
+- CSRF protection missing
+- Authentication bypasses
+
+### Code Quality
+
+- Large functions (>50 lines) - split into smaller
+- Large files (>800 lines) - extract modules
+- Deep nesting (>4 levels) - use early returns
+- Missing error handling - handle explicitly
+- Mutation patterns - prefer immutable operations
+- Missing tests - add test coverage
+
+### Performance
+
+- N+1 queries - use JOINs or batching
+- Missing pagination - add LIMIT to queries
+- Unbounded queries - add constraints
+- Missing caching - cache expensive operations
+
+## Approval Criteria
+
+- **Approve**: No CRITICAL or HIGH issues
+- **Warning**: Only HIGH issues (merge with caution)
+- **Block**: CRITICAL issues found
+
+## Integration with Other Rules
+
+This rule works with:
+
+- [testing.md](testing.md) - Test coverage requirements
+- [security.md](security.md) - Security checklist
+- [git-workflow.md](git-workflow.md) - Commit standards
+- [agents.md](agents.md) - Agent delegation

package/rules/common/coding-style.md

@@ -0,0 +1,95 @@
+<!--
+rules/common/coding-style.md — <one-line purpose>
+
+<2–6 line summary.>
+-->
+# Coding Style
+
+## Immutability (CRITICAL)
+
+ALWAYS create new objects, NEVER mutate existing ones:
+
+```
+// Pseudocode
+WRONG:  modify(original, field, value) → changes original in-place
+CORRECT: update(original, field, value) → returns new copy with change
+```
+
+Rationale: Immutable data prevents hidden side effects, makes debugging easier, and enables safe concurrency.
+
+## Core Principles
+
+### KISS (Keep It Simple)
+
+- Prefer the simplest solution that actually works
+- Avoid premature optimization
+- Optimize for clarity over cleverness
+
+### DRY (Don't Repeat Yourself)
+
+- Extract repeated logic into shared functions or utilities
+- Avoid copy-paste implementation drift
+- Introduce abstractions when repetition is real, not speculative
+
+### YAGNI (You Aren't Gonna Need It)
+
+- Do not build features or abstractions before they are needed
+- Avoid speculative generality
+- Start simple, then refactor when the pressure is real
+
+## File Organization
+
+MANY SMALL FILES > FEW LARGE FILES:
+- High cohesion, low coupling
+- 200-400 lines typical, 800 max
+- Extract utilities from large modules
+- Organize by feature/domain, not by type
+
+## Error Handling
+
+ALWAYS handle errors comprehensively:
+- Handle errors explicitly at every level
+- Provide user-friendly error messages in UI-facing code
+- Log detailed error context on the server side
+- Never silently swallow errors
+
+## Input Validation
+
+ALWAYS validate at system boundaries:
+- Validate all user input before processing
+- Use schema-based validation where available
+- Fail fast with clear error messages
+- Never trust external data (API responses, user input, file content)
+
+## Naming Conventions
+
+- Variables and functions: `camelCase` with descriptive names
+- Booleans: prefer `is`, `has`, `should`, or `can` prefixes
+- Interfaces, types, and components: `PascalCase`
+- Constants: `UPPER_SNAKE_CASE`
+- Custom hooks: `camelCase` with a `use` prefix
+
+## Code Smells to Avoid
+
+### Deep Nesting
+
+Prefer early returns over nested conditionals once the logic starts stacking.
+
+### Magic Numbers
+
+Use named constants for meaningful thresholds, delays, and limits.
+
+### Long Functions
+
+Split large functions into focused pieces with clear responsibilities.
+
+## Code Quality Checklist
+
+Before marking work complete:
+- [ ] Code is readable and well-named
+- [ ] Functions are small (<50 lines)
+- [ ] Files are focused (<800 lines)
+- [ ] No deep nesting (>4 levels)
+- [ ] Proper error handling
+- [ ] No hardcoded values (use constants or config)
+- [ ] No mutation (immutable patterns used)

package/rules/common/comments.md

@@ -0,0 +1,139 @@
+<!--
+rules/common/comments.md — canonical comment policy for the Construct repo.
+
+Applies to every file in this repository, including generated agent output.
+Enforced by `construct lint:comments`, the comment-lint PostToolUse hook,
+and CI. Authoring agents must follow this policy without needing reminders.
+-->
+
+# Comment Policy
+
+Construct treats comments as durable documentation, not scratch notes. This file is the single source of truth. Every change to Construct — manual or agent-driven — must respect it.
+
+## 1. File header block (required)
+
+Every file listed below must start with a header block that states the file's path, a one-line purpose, and a short summary of what it does, who calls it, and any side effects.
+
+**Scope:**
+
+- `bin/**/*` — executable entrypoints
+- `lib/**/*.mjs` — runtime, hooks, server, MCP
+- `sync-agents.mjs`
+- `tests/**/*.mjs`
+- `personas/**/*.md`
+- `skills/**/*.md`
+- `rules/**/*.md`
+- `commands/**/*.md`
+- Generated platform output under `platforms/claude/agents/` and `platforms/opencode/`
+- Scripts under `.github/**` and any top-level shell/Node script
+
+**Format — JavaScript / Node:**
+
+```js
+/**
+ * <relative/path.mjs> — <one-line purpose>
+ *
+ * <2–6 line summary: what it does, who calls it, key side effects or
+ * dependencies a reader would need to know before touching it.>
+ */
+```
+
+**Format — Markdown:**
+
+```html
+<!--
+<relative/path.md> — <one-line purpose>
+
+<2–6 line summary matching the JS variant.>
+-->
+```
+
+**Format — Shell:**
+
+```bash
+# <relative/path.sh> — <one-line purpose>
+#
+# <2–6 line summary.>
+```
+
+The linter extracts the path from the block's first line and verifies it matches the file's actual location.
+
+## 2. Section comments (allowed, kept short)
+
+Inside a file, a one-line section comment is fine when it genuinely helps navigation:
+
+```js
+// --- model selection ---
+```
+
+Do not write multi-line section banners. Do not repeat what the code immediately below already says.
+
+## 3. Inline comments
+
+Default to no inline comment. Only write one when the *why* is non-obvious: a hidden constraint, an invariant, a workaround for a specific bug that would surprise a reader, or a subtle ordering requirement.
+
+A comment that describes *what* the code does is almost always noise — the code already says that. Delete it.
+
+## 4. Banned patterns
+
+The linter flags these as warnings. Agents must not introduce them.
+
+### Point-in-time references
+
+Comments decay. These phrases tie a comment to a moment that the reader can no longer verify:
+
+- `added` / `added for` / `added recently`
+- `new:` / `recently` / `just` / `now`
+- `previously` / `we used to` / `no longer`
+- `removed` / `deleted` (as narration, not instruction)
+- `in this PR` / `for this task` / `for the X flow`
+- absolute dates (`2024-…`, `Jan 2025`, etc.) unless tied to a real external deadline
+
+### Caller references
+
+The reader can grep for callers. Comments that claim to enumerate them rot:
+
+- `used by X` / `called from Y` / `only consumer is Z`
+
+*Exception:* the file-header block may list primary consumers when the list is short and load-bearing (see `lib/cli-commands.mjs` for the pattern).
+
+### Issue / PR / ticket references
+
+These belong in commit messages and PR bodies, not in source:
+
+- `#\d+` / `GH-\d+` / `JIRA-\d+`
+- `fixes #…` / `closes #…` / `see ticket …`
+
+### Trailing "why" comments on self-evident code
+
+If the code reads cleanly, leave it alone:
+
+```js
+const total = subtotal + tax; // add tax   ← delete this
+```
+
+### TODO / FIXME without context
+
+TODOs without an owner and a reason are abandoned the moment they are written. Required shape:
+
+```js
+// TODO(owner): <what and why> — <condition that resolves it>
+```
+
+## 5. Generated files
+
+Files under `platforms/claude/agents/` and `platforms/opencode/` that are generated output must carry the canonical "Generated by construct sync" banner produced by `sync-agents.mjs`. Hand-edits to these files are rejected; regenerate instead.
+
+## 6. Enforcement
+
+| Violation | Level | Enforced by |
+|---|---|---|
+| Missing file header in a scoped path | error | `construct lint:comments`, CI |
+| Banned pattern in a comment | warning | `construct lint:comments`, PostToolUse hook |
+| Hand-edit to a generated file | error | `sync-agents.mjs` regeneration + CI |
+
+`construct lint:comments --fix` adds stub headers to files missing one. Banned patterns must be resolved by hand — the linter refuses to guess at the author's intent.
+
+## 7. Why this is strict
+
+The repo generates configs for every downstream tool. A point-in-time comment in a persona file becomes a point-in-time comment in every Claude Code, OpenCode, Codex, and Copilot install of Construct. The cost of a lazy comment is multiplied across every surface.

package/rules/common/cx-agent-routing.md

@@ -0,0 +1,61 @@
+<!--
+rules/common/cx-agent-routing.md — auto-trigger routing rules for cx-* specialist agents.
+
+Defines when to route directly to a cx-* specialist vs through Construct orchestration.
+Covers intent-based routing table, complexity gate, and routing rules.
+Loaded by rule-loading systems that look for cx-agent-routing in the rules hierarchy.
+-->
+# cx-* Agent Routing — Auto-trigger Rules
+
+When a request matches the trigger patterns below, automatically route to the corresponding cx-* specialist or persona before responding.
+
+**Default: execute, don't plan.** Most tasks go directly to the right specialist. Route through Construct orchestration only for genuinely complex, multi-workstream work.
+
+---
+
+## Complexity Gate
+
+**Simple/bounded → specialist directly:**
+- Bug fix or regression (root cause diagnosable from description)
+- Change scoped to known files with clear outcome
+- Refactor within existing patterns
+
+**Complex/uncertain → Construct orchestration (or cx-orchestrator):**
+- New feature requiring new data models or cross-system API contracts
+- Work spanning multiple workstreams
+- Ambiguous scope where approaches produce meaningfully different outcomes
+
+---
+
+## By Intent Type
+
+| Request shape | Route | Notes |
+|---|---|---|
+| "explain / what is / how does" | Research (cx-researcher) | handles both general research and library/API docs |
+| "build / add / implement (simple)" | Implementation (cx-engineer) directly | no planning chain needed |
+| "build / add / implement (complex)" | Plan → Implement → Validate | full pipeline |
+| unclear scope, missing requirements | Planning (cx-product-manager, cx-ux-researcher) | requirements before implementation |
+| "broken / failing / error" | Research (cx-debugger) → Implementation (cx-engineer) | debug first, then fix |
+| "review / audit / check code" | Validation (cx-reviewer) | cx-security for auth/secrets/payments |
+| "plan / design / architect" | Planning (cx-architect) | challenge with cx-devil-advocate for risky changes |
+| "test / verify / coverage" | Validation (cx-qa) | |
+| "release / deploy / rollout" | Operations (cx-release-manager) | |
+| "metrics / measure / instrument" | Planning (cx-data-analyst) | |
+| "performance / SLO / alert / monitor" | Operations (cx-sre) | |
+| "prompt / model / RAG / agent workflow" | Implementation (cx-ai-engineer) | require cx-evaluator before shipping |
+| "accessibility / a11y / screen reader" | Validation (cx-accessibility) | |
+| "docs / runbook / decision record" | Research (cx-docs-keeper) | |
+| "explore / trace / investigate code" | Research (cx-explorer) | read-only before changes |
+
+---
+
+## Routing Rules
+
+1. **Match on intent, not exact string.** "Can we ship this?" triggers operations routing.
+2. **Security and auth always get cx-security.** No exceptions for auth, payments, secrets.
+3. **Broken things go to cx-debugger first.** Don't plan a fix before root cause is confirmed.
+4. **Skip cx-devil-advocate for routine changes.** Only invoke for genuinely novel or risky decisions.
+5. **Require cx-devil-advocate for persistent capability changes.** Any promotion of a temporary overlay/capability into a reusable Construct capability must include a devil's advocate challenge before approval.
+6. **Explorer for unknown territory.** When the codebase area is unfamiliar, route to cx-explorer first.
+7. **Unclear requirements always stop at planning.** If missing acceptance criteria or ambiguous scope, route to cx-product-manager or cx-ux-researcher before implementation.
+8. **Read once per conversation.** No need to re-read this file if already loaded.

package/rules/common/cx-skill-routing.md

@@ -0,0 +1,11 @@
+<!--
+rules/common/cx-skill-routing.md — Redirect to canonical skill routing table.
+-->
+# cx-* Skill Routing
+
+> **Canonical file:** [`skills/routing.md`](../../skills/routing.md)
+>
+> All skill routing keywords, domain tables, and routing rules live there.
+> This file exists only as a named entry point for rule-loading systems that
+> look for `cx-skill-routing.md`. Do not add routing entries here — update
+> `skills/routing.md` instead.

package/rules/common/development-workflow.md

@@ -0,0 +1,49 @@
+<!--
+rules/common/development-workflow.md — <one-line purpose>
+
+<2–6 line summary.>
+-->
+# Development Workflow
+
+> This file extends [common/git-workflow.md](./git-workflow.md) with the full feature development process that happens before git operations.
+
+The Feature Implementation Workflow describes the development pipeline: research, planning, TDD, code review, and then committing to git.
+
+## Feature Implementation Workflow
+
+0. **Research & Reuse** _(mandatory before any new implementation)_
+   - **GitHub code search first:** Run `gh search repos` and `gh search code` to find existing implementations, templates, and patterns before writing anything new.
+   - **Library docs second:** Use Context7 or primary vendor docs to confirm API behavior, package usage, and version-specific details before implementing.
+   - **Exa only when the first two are insufficient:** Use Exa for broader web research or discovery after GitHub search and primary docs.
+   - **Check package registries:** Search npm, PyPI, crates.io, and other registries before writing utility code. Prefer battle-tested libraries over hand-rolled solutions.
+   - **Search for adaptable implementations:** Look for open-source projects that solve 80%+ of the problem and can be forked, ported, or wrapped.
+   - Prefer adopting or porting a proven approach over writing net-new code when it meets the requirement.
+
+1. **Plan First**
+   - Use **planner** agent to create implementation plan
+   - Generate planning docs before coding: PRD, architecture, system_design, tech_doc, task_list
+   - Identify dependencies and risks
+   - Break down into phases
+
+2. **TDD Approach**
+   - Use **tdd-guide** agent
+   - Write tests first (RED)
+   - Implement to pass tests (GREEN)
+   - Refactor (IMPROVE)
+   - Verify 80%+ coverage
+
+3. **Code Review**
+   - Use **code-reviewer** agent immediately after writing code
+   - Address CRITICAL and HIGH issues
+   - Fix MEDIUM issues when possible
+
+4. **Commit & Push**
+   - Detailed commit messages
+   - Follow conventional commits format
+   - See [git-workflow.md](./git-workflow.md) for commit message format and PR process
+
+5. **Pre-Review Checks**
+   - Verify all automated checks (CI/CD) are passing
+   - Resolve any merge conflicts
+   - Ensure branch is up to date with target branch
+   - Only request review after these checks pass