@geraldmaron/construct 1.0.0 → 1.0.2

package/bin/construct-postinstall.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+/**
+ * bin/construct-postinstall.mjs — npm postinstall hook for consumer projects.
+ *
+ * When a downstream project pins `@geraldmaron/construct` as a (dev)Dependency
+ * and runs `npm install`, npm fetches Construct into the project's
+ * `node_modules/` and then runs this script. Its job: regenerate the project's
+ * `.claude/agents/` and `.claude/settings.json` from the bundled registry so
+ * the project clone is fully runnable without a manual `construct setup`.
+ *
+ * The script is a no-op in three cases:
+ *
+ *   1. The install is happening inside the Construct repo itself.
+ *   2. CONSTRUCT_SKIP_POSTINSTALL=1 is set.
+ *   3. The install target has no package.json (monorepo nested installs).
+ *
+ * Staging itself lives in `lib/install/stage-project.mjs` so `construct init`
+ * can call the same code path for opt-in adoption after a clone.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, statSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { stageProjectAdapters } from '../lib/install/stage-project.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = path.resolve(HERE, '..');
+const PKG_VERSION = (() => {
+  try { return JSON.parse(readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf8')).version || ''; }
+  catch { return ''; }
+})();
+
+const log = (msg) => process.stdout.write(`[construct-postinstall] ${msg}\n`);
+
+if (process.env.CONSTRUCT_SKIP_POSTINSTALL === '1') {
+  log('skipping (CONSTRUCT_SKIP_POSTINSTALL=1)');
+  process.exit(0);
+}
+
+const initCwd = process.env.INIT_CWD || process.cwd();
+
+// Skip when installing inside the Construct repo itself, but still wire up
+// the local commit template so contributors get the right editor scaffolding.
+try {
+  const pkgRealRoot = statSync(PKG_ROOT).isDirectory() ? PKG_ROOT : null;
+  if (pkgRealRoot && pkgRealRoot.startsWith(initCwd) && initCwd === PKG_ROOT) {
+    log('install is inside the Construct repo itself; skipping sync');
+    if (existsSync(path.join(PKG_ROOT, '.gitmessage')) && existsSync(path.join(PKG_ROOT, '.git'))) {
+      const cfg = spawnSync('git', ['config', 'commit.template', '.gitmessage'], {
+        cwd: PKG_ROOT,
+        stdio: 'ignore',
+      });
+      if (cfg.status === 0) log('configured git commit.template -> .gitmessage');
+    }
+    process.exit(0);
+  }
+} catch { /* fall through */ }
+
+// Require a package.json at the install target so monorepo nested installs
+// don't accidentally trigger staging in the wrong directory.
+
+const consumerPkgPath = path.join(initCwd, 'package.json');
+if (!existsSync(consumerPkgPath)) {
+  log(`no package.json at ${initCwd}; skipping`);
+  process.exit(0);
+}
+
+let consumerPkg = {};
+try { consumerPkg = JSON.parse(readFileSync(consumerPkgPath, 'utf8')); } catch { /* empty */ }
+if (consumerPkg.name === '@geraldmaron/construct') {
+  log('install target is the Construct package itself; skipping');
+  process.exit(0);
+}
+
+try {
+  stageProjectAdapters({
+    projectRoot: initCwd,
+    packageRoot: PKG_ROOT,
+    pkgVersion: PKG_VERSION,
+    log,
+  });
+} catch (err) {
+  log(`staging failed: ${err.message}; leaving project in a clean state`);
+  process.exit(0);
+}

package/commands/build/feature.md

@@ -13,9 +13,9 @@ Before writing a line:
 1. Read every file you will touch. Understand the existing pattern before deviating.
 2. If the approach is uncertain, consult cx-architect first.
 
-Verification before done:
-- [ ] Changed files compile without errors
-- [ ] Existing tests still pass
-- [ ] New behavior has test coverage
-- [ ] No hardcoded secrets or debug statements
-- [ ] No file over 800 lines
+When dispatching subagents: set an implicit timeout expectation. If a dispatched agent
+produces no output or tool activity within two minutes, surface it to the user with the
+agent description and elapsed time rather than waiting silently. Do not re-dispatch until
+the user confirms the prior invocation is not still running.
+
+Verification protocol is owned by `cx-engineer` — apply its checklist before declaring done.

package/commands/plan/feature.md

@@ -1,11 +1,11 @@
 <!--
-commands/plan/feature.md — Plan a feature and import it as workflow task packets
+commands/plan/feature.md — Plan a feature and turn it into a tracker-linked implementation plan
 
 Produces a structured spec using the canonical Construct plan format, saves it
-to .cx/plans/, and calls workflow_import_plan to create full bead packets.
+to .cx/plans/ as a durable planning artifact linked to the active tracker slice.
 -->
 ---
-description: Plan a feature — produce a structured spec and import it as workflow task packets
+description: Plan a feature — produce a structured spec and link it to the active tracker-backed plan
 ---
 
 You are Construct. Plan the following: $ARGUMENTS
@@ -45,5 +45,6 @@ Rules:
 
 ## Step 3 — Save and import
 1. Save this full plan to `.cx/plans/{slug}-plan.md`
-2. Call `workflow_import_plan` with the Tasks section markdown and `spec_ref` = the saved plan path
-3. Report: tasks created, plan path, workflow summary
+2. If the project uses Beads or another external tracker, include the issue id in the plan and keep the current `plan.md` aligned with it
+3. Declare file ownership explicitly so parallel work still follows the single-writer rule
+4. Report: tracker links, plan path, and ownership boundaries

package/commands/plan/requirements.md

@@ -21,4 +21,4 @@ Do not proceed to implementation until these are clear.
 
 ## Next step
 
-Once requirements are agreed, run `/plan feature {topic}` to produce a structured implementation plan and import it as workflow task packets (beads) into `.cx/workflow.json`.
+Once requirements are agreed, run `/plan feature {topic}` to produce a structured implementation plan tied to the tracker and `plan.md`.

package/commands/ship/status.md

@@ -10,7 +10,7 @@ description: Status — current project state, workflow, uncommitted changes, re
 You are Construct. Report status for: $ARGUMENTS
 
 Check and report:
-1. Workflow state from `.cx/workflow.json` (if it exists) — phase, active tasks, blockers
+1. Tracker and `plan.md` state — active slices, blockers, and ownership boundaries
 2. Uncommitted changes via `git status`
 3. Recent commits via `git log --oneline -10`
 4. Active branch and relationship to main

package/commands/work/drive.md

@@ -11,7 +11,7 @@ You are Construct in drive mode. Execute $ARGUMENTS fully and autonomously witho
 
 ## Execution contract
 
-Use the code-backed orchestration policy and workflow task packets as the control plane.
+Use the code-backed orchestration policy, tracker state, and `plan.md` as the control plane.
 This command turns off planning confirmation, but it does not override validation, acceptance criteria, or approval boundaries.
 
 ## Execution Loop
@@ -20,7 +20,7 @@ This command turns off planning confirmation, but it does not override validatio
 Map the codebase areas relevant to the task. Identify entry points, dependencies, and affected modules.
 
 **Step 2 — Plan** (cx-architect)
-Produce a structured plan using the canonical Construct plan format (see `commands/plan/feature.md` — `### T{N} — Title` sections with fielded sub-bullets). Save it to `.cx/plans/{slug}-plan.md`, then call `workflow_import_plan` with the Tasks section markdown and `spec_ref` = saved plan path. That populates `.cx/workflow.json` with full bead packets (files, readFirst, doNotChange, acceptanceCriteria, dependsOn). Identify tasks that can run in parallel by inspecting `dependsOn`.
+Produce a structured plan using the canonical Construct plan format (see `commands/plan/feature.md` — `### T{N} — Title` sections with fielded sub-bullets). Save it to `.cx/plans/{slug}-plan.md`, align `plan.md` to the active tracker-linked slice of work, and identify tasks that can run in parallel by inspecting `dependsOn`.
 
 Initialize `.cx/drive-state.json`:
 ```json
@@ -66,4 +66,4 @@ Only stop when ALL of the following are true:
 - Do not stop to ask for confirmation. If blocked by genuine ambiguity, surface the specific blocker and propose a resolution before stopping.
 - Prefer parallel execution for independent tasks.
 - Write verification evidence into each workflow task before marking it `done`.
-- If context is running low, save state to `.cx/workflow.json` and summarize the handoff point.
+- If context is running low, summarize the current handoff point in `plan.md` or the tracker and preserve the single-writer boundary for each file.

package/commands/work/optimize-prompts.md

@@ -1,10 +1,10 @@
 <!--
 commands/work/optimize-prompts.md — Prompt optimization command.
 
-Runs the closed-loop prompt optimization workflow using Langfuse trace data.
+Runs the closed-loop prompt optimization workflow using telemetry trace data.
 -->
 ---
-description: Closed-loop prompt optimization — read Langfuse traces, diagnose failures, push improved version to staging
+description: Closed-loop prompt optimization — read telemetry traces, diagnose failures, push improved version to staging
 ---
 
 You are cx-trace-reviewer running a prompt optimization cycle for: $ARGUMENTS
@@ -19,7 +19,7 @@ Optimize prompt fragments and overlays, not the runtime orchestration policy. If
 ## Required steps
 
 1. **Read current prompt** — read the agent's prompt from `agents/registry.json` (or its `promptFile`)
-2. **Fetch recent scores** — GET `{LANGFUSE_BASEURL}/api/public/scores?name=quality&limit=200`
+2. **Fetch recent scores** — GET `{CONSTRUCT_TELEMETRY_URL}/api/public/scores?name=quality&limit=200`
 3. **Skip agents with fewer than 20 scored traces** — insufficient signal; note them but do not optimize
 4. **Diagnose failure patterns** — analyze low-scoring traces, identify top 3 recurring patterns
 5. **Generate improved prompt** — targeted edits that address failures without breaking high-scoring behaviors

package/db/{migrations → schema}/001_init.sql

@@ -1,3 +1,5 @@
+create extension if not exists vector;
+
 create table if not exists construct_documents (
   id text primary key,
   project text not null,

package/db/schema/002_pgvector.sql

@@ -0,0 +1,182 @@
+-- db/schema/002_pgvector.sql
+-- Enable pgvector extension and add vector-typed columns for semantic search.
+-- This migration is idempotent — safe to run multiple times.
+
+-- Enable pgvector extension
+CREATE EXTENSION IF NOT EXISTS vector;
+
+-- Add vector column to construct_embeddings if it doesn't exist yet
+-- (The original 001_init.sql used double precision[], which we keep for backward compat)
+DO $$
+BEGIN
+  -- Check if embedding column is still array type and needs migration
+  IF EXISTS (
+    SELECT 1 FROM information_schema.columns
+    WHERE table_name = 'construct_embeddings'
+      AND column_name = 'embedding'
+      AND data_type = 'ARRAY'
+  ) THEN
+    -- Add new vector column
+    ALTER TABLE construct_embeddings ADD COLUMN embedding_vec vector(384);
+
+    -- Copy data from old array column to new vector column
+    UPDATE construct_embeddings
+      SET embedding_vec = embedding::vector(384);
+
+    -- Drop old column and rename
+    ALTER TABLE construct_embeddings DROP COLUMN embedding;
+    ALTER TABLE construct_embeddings RENAME COLUMN embedding_vec TO embedding;
+  END IF;
+END $$;
+
+-- Ensure embedding column exists as vector type (for fresh installs)
+ALTER TABLE construct_embeddings
+  ALTER COLUMN embedding TYPE vector(384) USING embedding::vector(384);
+
+-- Create HNSW index for fast approximate nearest neighbor search
+CREATE INDEX IF NOT EXISTS idx_embeddings_hnsw
+  ON construct_embeddings
+  USING hnsw (embedding vector_cosine_ops)
+  WITH (m = 16, ef_construction = 64);
+
+-- Create observations table with vector support
+CREATE TABLE IF NOT EXISTS construct_observations (
+  id text PRIMARY KEY,
+  project text NOT NULL,
+  role text NOT NULL,
+  category text NOT NULL,
+  summary text NOT NULL,
+  content text NOT NULL,
+  tags jsonb NOT NULL DEFAULT '[]'::jsonb,
+  confidence float NOT NULL DEFAULT 0.8,
+  source text,
+  git_sha text,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  embedding vector(384)
+);
+
+-- Indexes for observations
+CREATE INDEX IF NOT EXISTS idx_observations_project ON construct_observations(project);
+CREATE INDEX IF NOT EXISTS idx_observations_category ON construct_observations(project, category);
+CREATE INDEX IF NOT EXISTS idx_observations_created_at ON construct_observations(project, created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_observations_vector ON construct_observations USING hnsw (embedding vector_cosine_ops);
+
+-- Create sessions table with vector support
+CREATE TABLE IF NOT EXISTS construct_sessions (
+  id text PRIMARY KEY,
+  project text NOT NULL,
+  platform text,
+  summary text,
+  decisions jsonb DEFAULT '[]'::jsonb,
+  files_changed jsonb DEFAULT '[]'::jsonb,
+  open_questions jsonb DEFAULT '[]'::jsonb,
+  task_snapshot jsonb DEFAULT '[]'::jsonb,
+  status text DEFAULT 'active',
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  embedding vector(384)
+);
+
+CREATE INDEX IF NOT EXISTS idx_sessions_project ON construct_sessions(project);
+CREATE INDEX IF NOT EXISTS idx_sessions_status ON construct_sessions(project, status);
+CREATE INDEX IF NOT EXISTS idx_sessions_vector ON construct_sessions USING hnsw (embedding vector_cosine_ops);
+
+-- Create entities table with vector support
+CREATE TABLE IF NOT EXISTS construct_entities (
+  name text PRIMARY KEY,
+  type text NOT NULL,
+  summary text,
+  project text,
+  observation_ids jsonb DEFAULT '[]'::jsonb,
+  related_entities jsonb DEFAULT '[]'::jsonb,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  last_seen timestamptz,
+  embedding vector(384)
+);
+
+CREATE INDEX IF NOT EXISTS idx_entities_type ON construct_entities(type);
+CREATE INDEX IF NOT EXISTS idx_entities_project ON construct_entities(project);
+CREATE INDEX IF NOT EXISTS idx_entities_vector ON construct_entities USING hnsw (embedding vector_cosine_ops);
+
+-- Function for searching documents by embedding
+CREATE OR REPLACE FUNCTION search_documents(
+  project_name text,
+  query_embedding vector(384),
+  match_limit int DEFAULT 10,
+  min_similarity float DEFAULT 0.3
+)
+RETURNS TABLE(
+  id text,
+  title text,
+  summary text,
+  body text,
+  source_path text,
+  tags jsonb,
+  kind text,
+  similarity float
+) AS $$
+BEGIN
+  RETURN QUERY
+  SELECT
+    d.id,
+    d.title,
+    d.summary,
+    d.body,
+    d.source_path,
+    d.tags,
+    d.kind,
+    1 - (e.embedding <=> query_embedding) AS similarity
+  FROM construct_documents d
+  JOIN construct_embeddings e ON d.id = e.document_id
+  WHERE d.project = project_name
+    AND 1 - (e.embedding <=> query_embedding) > min_similarity
+  ORDER BY e.embedding <=> query_embedding
+  LIMIT match_limit;
+END;
+$$ LANGUAGE plpgsql;
+
+-- Function for searching observations by embedding
+CREATE OR REPLACE FUNCTION search_observations(
+  project_name text,
+  query_embedding vector(384),
+  match_limit int DEFAULT 10,
+  min_similarity float DEFAULT 0.3,
+  filter_role text DEFAULT NULL,
+  filter_category text DEFAULT NULL
+)
+RETURNS TABLE(
+  id text,
+  role text,
+  category text,
+  summary text,
+  content text,
+  tags jsonb,
+  confidence float,
+  source text,
+  created_at timestamptz,
+  similarity float
+) AS $$
+BEGIN
+  RETURN QUERY
+  SELECT
+    o.id,
+    o.role,
+    o.category,
+    o.summary,
+    o.content,
+    o.tags,
+    o.confidence,
+    o.source,
+    o.created_at,
+    1 - (o.embedding <=> query_embedding) AS similarity
+  FROM construct_observations o
+  WHERE o.project = project_name
+    AND 1 - (o.embedding <=> query_embedding) > min_similarity
+    AND (filter_role IS NULL OR o.role = filter_role)
+    AND (filter_category IS NULL OR o.category = filter_category)
+  ORDER BY o.embedding <=> query_embedding
+  LIMIT match_limit;
+END;
+$$ LANGUAGE plpgsql;

package/db/schema/003_intake.sql

@@ -0,0 +1,47 @@
+-- 003_intake.sql — R&D intake queue backing table for team and enterprise mode.
+-- Solo mode uses the filesystem under .cx/intake/ instead.
+--
+-- Worker claim algorithm: SELECT ... FROM construct_intake_items
+--   WHERE status = 'pending' ORDER BY created_at ASC FOR UPDATE SKIP LOCKED LIMIT 1;
+-- then set status = 'claimed', claimed_by, claimed_at in the same transaction.
+--
+-- payload jsonb carries the rest of the intake packet (intake, triage,
+-- suggestion, related, excerpt, query) so the on-disk shape and the
+-- in-table shape stay aligned.
+
+create table if not exists construct_intake_items (
+  id text primary key,
+  project text not null,
+  tenant_id text,
+  status text not null default 'pending',
+  intake_type text,
+  rd_stage text,
+  primary_owner text,
+  recommended_action text,
+  risk text,
+  requires_approval boolean not null default false,
+  confidence double precision,
+  payload jsonb not null,
+  created_at timestamptz not null default now(),
+  updated_at timestamptz not null default now(),
+  claimed_by text,
+  claimed_at timestamptz,
+  processed_at timestamptz,
+  processed_by text,
+  notes text,
+  skipped_at timestamptz,
+  skipped_by text,
+  skip_reason text
+);
+
+create index if not exists construct_intake_items_status_idx
+  on construct_intake_items(status, created_at);
+
+create index if not exists construct_intake_items_owner_idx
+  on construct_intake_items(primary_owner, status, created_at);
+
+create index if not exists construct_intake_items_payload_gin_idx
+  on construct_intake_items using gin(payload);
+
+create index if not exists construct_intake_items_project_tenant_idx
+  on construct_intake_items(project, tenant_id, status);

package/examples/README.md

@@ -0,0 +1,85 @@
+# Prompt Example Fixtures
+
+This directory holds shipped example fixtures for Construct's public persona and internal role layers.
+
+Use it for three things:
+
+- golden examples: canonical strong behavior worth preserving
+- bad examples: labeled failure modes that should fail review/eval
+- boundary and adversarial examples: ambiguity, escalation, stale context, and injection pressure
+
+Best practice in this repo:
+
+- keep the public persona and internal specialist prompts lean and rule-based
+- keep most examples here as regression fixtures, not embedded into prompt bodies
+- use bad examples as critique and eval assets, not as raw few-shot prompt content
+- add in-prompt examples only when behavior is hard to specify precisely in rules
+
+## Layout
+
+```text
+examples/
+├── personas/
+│   └── construct/
+│       ├── golden/
+│       ├── bad/
+│       ├── boundary/
+│       └── adversarial/
+└── internal/
+    └── roles/
+        ├── architect/
+        ├── engineer/
+        ├── orchestrator/
+        ├── qa/
+        └── reviewer/
+```
+
+## Fixture format
+
+Each fixture is markdown with YAML frontmatter.
+
+Required frontmatter:
+
+- `id`: stable fixture id
+- `surface`: `persona` or `internal-role`
+- `name`: fixture target name, such as `construct` or `engineer`
+- `category`: `golden`, `bad`, `boundary`, or `adversarial`
+- `verdict`: `pass` or `fail`
+- `summary`: one-line purpose
+
+Recommended frontmatter:
+
+- `references`: prompt or role files this fixture exercises
+- `tags`: stable labels for filtering and future eval harnesses
+
+Required body sections:
+
+- `## User`
+- `## Expected`
+
+Bad fixtures should also include:
+
+- `## Why This Fails`
+
+## Coverage policy
+
+Required public coverage:
+
+- `construct`: at least one `golden`, `bad`, `boundary`, and `adversarial`
+
+Required internal coverage:
+
+- `architect`, `engineer`, `reviewer`, `qa`, and `orchestrator`: at least one `golden` and one `bad`
+
+## Authoring rules
+
+- Keep fixtures short and behaviorally specific.
+- Prefer one core contract per fixture.
+- Name the expected behavior in repo terms: branch confirmation, approval boundary, routing, verification, blocker surfacing, anti-pattern avoidance.
+- For bad examples, show the failure plainly and explain why it violates the surface contract.
+
+See `docs/concepts/prompt-surfaces.md` for the canonical public-vs-internal taxonomy.
+
+## Scope
+
+These fixtures are shipped examples and regression assets. They are not yet executed by a model harness, but the structure is designed so a future evaluator can consume them without reshaping the corpus.

package/examples/internal/roles/architect/bad/clever-plan-without-contracts.md

@@ -0,0 +1,30 @@
+---
+id: architect-bad-clever-plan-without-contracts
+surface: internal-role
+name: architect
+category: bad
+verdict: fail
+summary: Recommends a clever architecture without exposing contracts or rejected alternatives.
+references:
+  - skills/roles/architect.md
+  - agents/prompts/cx-architect.md
+tags:
+  - missing-contracts
+  - hidden-dependencies
+---
+
+## User
+
+Design the runtime coordination layer.
+
+## Expected
+
+This is a bad outcome:
+
+```text
+We should add a shared coordinator and let each module figure it out dynamically.
+```
+
+## Why This Fails
+
+It hides the interface contract, does not expose tradeoffs, and gives no basis for downstream engineering or review.

package/examples/internal/roles/architect/golden/explicit-tradeoff-before-plan.md

@@ -0,0 +1,23 @@
+---
+id: architect-golden-explicit-tradeoff-before-plan
+surface: internal-role
+name: architect
+category: golden
+verdict: pass
+summary: Makes interface and dependency tradeoffs explicit before locking in a plan.
+references:
+  - skills/roles/architect.md
+  - agents/prompts/cx-architect.md
+tags:
+  - tradeoffs
+  - contracts
+  - architecture
+---
+
+## User
+
+Plan the auth/session split across modules.
+
+## Expected
+
+Strong architect behavior names the relevant module boundaries, interface contracts, and tradeoffs before recommending a plan. It does not skip directly to file changes or implementation detail.

package/examples/internal/roles/engineer/bad/speculative-abstraction.md

@@ -0,0 +1,30 @@
+---
+id: engineer-bad-speculative-abstraction
+surface: internal-role
+name: engineer
+category: bad
+verdict: fail
+summary: Introduces an abstraction for future cases without evidence from the code.
+references:
+  - skills/roles/engineer.md
+  - agents/prompts/cx-engineer.md
+tags:
+  - speculative-abstraction
+  - unnecessary-surface-area
+---
+
+## User
+
+Add support for this one new storage backend.
+
+## Expected
+
+This is a bad outcome:
+
+```text
+I introduced a generic provider factory, backend registry, pluggable resolver, and four config flags so future backends are easy.
+```
+
+## Why This Fails
+
+It violates the engineer anti-pattern against speculative abstraction. The current case asks for one concrete backend, not a framework for hypothetical future ones.

package/examples/internal/roles/engineer/golden/read-before-write.md

@@ -0,0 +1,28 @@
+---
+id: engineer-golden-read-before-write
+surface: internal-role
+name: engineer
+category: golden
+verdict: pass
+summary: Reads the touched files and surrounding pattern before proposing code changes.
+references:
+  - skills/roles/engineer.md
+  - agents/prompts/cx-engineer.md
+tags:
+  - read-before-write
+  - local-conventions
+---
+
+## User
+
+Rename the auth token helper and update its callers.
+
+## Expected
+
+Strong engineer behavior reads the helper and at least one caller before drafting the change. It does not jump straight to abstraction or a blind rename.
+
+The contract is:
+
+- surrounding file is read first
+- at least one caller or call site is examined
+- edits follow existing local conventions

package/examples/internal/roles/orchestrator/bad/everything-becomes-multi-agent.md

@@ -0,0 +1,29 @@
+---
+id: orchestrator-bad-everything-becomes-multi-agent
+surface: internal-role
+name: orchestrator
+category: bad
+verdict: fail
+summary: Treats a simple ask as a full orchestrated workflow.
+references:
+  - skills/roles/orchestrator.md
+tags:
+  - over-orchestration
+  - ceremony
+---
+
+## User
+
+What file defines the main persona?
+
+## Expected
+
+This is a bad outcome:
+
+```text
+Plan: cx-architect for discovery, cx-explorer for repo mapping, cx-reviewer for quality, then cx-docs-keeper for synthesis.
+```
+
+## Why This Fails
+
+It violates the orchestrator contract to classify first and choose the smallest adequate path.