@thiaq/project-skill 0.1.0

package/README.md

@@ -0,0 +1,31 @@
+# @thiaq/project-skill
+
+npm distribution for the ThiaQ project setup skill.
+
+The package installs the `thiaq-project` skill into local agent skill folders so
+Codex or Claude Code can refresh a ThiaQ project from live discovery plus static
+repo analysis.
+
+## Install From npm
+
+```bash
+npm install --save-dev @thiaq/project-skill
+npx thiaq-project-skill install --agent codex --agent claude-code
+```
+
+## Install From A Packed Tarball
+
+```bash
+npm pack ./skills/thiaq-project
+npm install --save-dev ./thiaq-project-skill-0.1.0.tgz
+npx thiaq-project-skill install --agent codex
+```
+
+## Agent Prompt
+
+```text
+Use the thiaq-project skill. Refresh the existing ThiaQ project additively:
+read existing project context, scan the repo, use live discovery evidence if
+available, and propose a reviewed product map without making the customer or
+project name the root node.
+```

package/SKILL.md

@@ -0,0 +1,263 @@
+---
+name: thiaq-project
+description: Set up or refresh a ThiaQ project using hosted ThiaQ MCP tools. Use when an agent is asked to understand a product for ThiaQ, install or connect the runner/extension, run safe discovery, summarize repo/docs/GitHub/Jira/tests, fuse live UI evidence with static code analysis, infer personas and jobs, identify product areas/features/surfaces/controls, propose product map naming, propose access and safety policy, group test ideas, create issue/repair proposals, or prepare deterministic QA coverage without making the user fill long forms.
+---
+
+# ThiaQ Project
+
+Use this skill to populate ThiaQ from both live product discovery and static
+repo evidence. Treat ThiaQ as a hosted control plane: submit summaries and
+reviewable change sets through MCP, then let the first user confirm naming,
+module boundaries, and critical paths in the UI.
+
+This is a generic ThiaQ skill. It tells the harness what ThiaQ needs to know;
+the harness decides how to collect that context from repo files, docs, GitHub,
+Jira, browser traces, tests, or other connected tools.
+
+## Core Rules
+
+- Keep ThiaQ core product-agnostic. Put product-specific mechanics in the
+  customer repo, product adapter, or repo summary.
+- Do not change customer application code unless the user explicitly asks for
+  an app-code change. Treat setup as outside-in QA/tooling work.
+- Create or update ThiaQ files only under the repo's existing QA/test/tooling
+  conventions, such as `qa/thiaq`, `tests/thiaq`, `test/thiaq`, `e2e/thiaq`,
+  `playwright/thiaq`, or `cypress/thiaq`.
+- Ensure repo-local ThiaQ runtime state is ignored by Git. At minimum,
+  `.gitignore` should contain `.thiaq/`; runner token configs such as
+  `thiaq.runner.json` should also stay uncommitted unless the team has a safe
+  secret-management pattern.
+- Never send secrets, production customer data, broad raw source, or token
+  values to ThiaQ.
+- Submit additive findings. Do not overwrite confirmed product knowledge.
+- MCP writes must create change sets, proposals, or runner job requests.
+- Approved CI still requires reviewed Git-backed flows, journeys, manifests,
+  interaction contracts, and assertions.
+- Coordinate/browser-agent actions are discovery evidence until reviewed into a
+  deterministic selector or product-driver contract.
+
+## Workflow
+
+1. Identify the ThiaQ project id and hosted MCP endpoint.
+2. Confirm the runner or browser extension is installed and connected, or help
+   the user create the smallest repo-local adapter needed to run safely.
+3. Read available static product context: repo docs, connected issues,
+   existing tests, routes, labels, fixtures, naming, product language, feature
+   folders, stories, scripts, registries, manifests, and QA tooling.
+4. Check whether the repo has a ThiaQ adapter in a repo-local tooling folder:
+   `qa/thiaq/adapter.ts`, `tests/thiaq/adapter.ts`,
+   `test/thiaq/adapter.ts`, `e2e/thiaq/adapter.ts`,
+   `playwright/thiaq/adapter.ts`, `cypress/thiaq/adapter.ts`,
+   `.thiaq/adapter.ts`, or `thiaq.adapter.ts`.
+5. If no adapter exists, propose a small repo-local adapter before discovery.
+6. Ask the user only for missing high-risk setup facts: safe URL, test role,
+   auth/session method, and destructive-action boundaries.
+7. Start safe live discovery when access and safety boundaries are clear. Use
+   discovery to capture screens, surfaces, controls, canvas affordances,
+   selector gaps, blocked paths, screenshots, and bug candidates.
+8. Fuse static repo analysis with live discovery. Prefer names that match the
+   product's own docs, routes, UI labels, tests, and issue language.
+9. Propose a reviewable product map shaped like
+   `Product Area -> Feature or Workflow -> Surface or Control`. The customer or
+   project name is context, not the root tree node.
+10. Ask the first user to review naming, split/merge areas, confirm critical
+   paths, and flag anything ThiaQ should never automate.
+11. Call ThiaQ MCP tools to submit summaries and proposed changes.
+12. After discovery, use ThiaQ test ideas and issue categories to propose
+   deterministic coverage work.
+
+## What To Inspect
+
+Prefer targeted reads over broad dumps:
+
+- product docs: `README`, `docs/`, `product/`, onboarding guides;
+- routes and navigation: router files, app shell, route manifests;
+- surface labels and naming: page titles, route names, test IDs, visible labels,
+  domain nouns, workflow names, issue labels;
+- tests: Playwright/Cypress specs, fixtures, page objects, selectors;
+- adapters: product drivers, canvas/test bridges, helper registries;
+- implementation shape: feature folders, components, stories, scripts,
+  registries, manifests, permissions, and data models that explain product
+  boundaries;
+- discovery artifacts: visited URLs, screenshots, controls, accessibility
+  snapshots, selector gaps, blocked paths, canvas object evidence, and
+  bug-candidate ideas;
+- issue context: GitHub/Jira labels, bug reports, UX notes when available;
+- existing manifests: capabilities, use cases, journeys, flow registries.
+
+Preserve evidence as short references such as `docs/product.md:12`,
+`app/routes/dashboard.tsx`, `tests/e2e/create-project.spec.ts`, or issue URLs.
+
+## Repo-Local Adapter
+
+The customer's repo should own product-specific setup, test helpers, drivers,
+naming standards, and secret references. ThiaQ Cloud owns orchestration, review
+state, findings, and artifacts; it should not bake customer adapters into the
+platform.
+
+When an adapter is missing, pick the folder that matches the repo's existing
+test/tooling style. Prefer an existing top-level `qa/`, `tests/`, `test/`,
+`e2e/`, `playwright/`, or `cypress/` folder. Fall back to `qa/thiaq`. Do not
+place ThiaQ setup under `src/`, `app/`, `pages/`, `routes/`, `components/`, or
+other application-code roots.
+
+Propose a file like `tests/thiaq/adapter.ts` or `qa/thiaq/adapter.ts`:
+
+```ts
+const defineThiaQAdapter = (adapter) => adapter;
+
+export default defineThiaQAdapter({
+  id: "example-product",
+  name: "Example Product",
+  capabilities: {
+    capabilities: ["discovery", "recipe_run", "visual_anchors"],
+    jobTypes: ["discovery", "recipe_run"],
+    labels: ["dashboard", "admin", "workflow"]
+  },
+  doctor(context) {
+    return {
+      checks: [
+        {
+          id: "base-url",
+          label: "Safe test URL is configured",
+          status: context.baseUrl ? "passed" : "failed",
+          message: context.baseUrl ?? "Set runner baseUrl"
+        }
+      ],
+      ok: Boolean(context.baseUrl)
+    };
+  }
+});
+```
+
+Use the inline helper for a zero-dependency first setup. If the repo can add
+developer dependencies, install `@thiaq/adapter-contract` and import
+`defineThiaQAdapter` for stricter TypeScript typing.
+
+Add product-specific methods only when the generic runner is insufficient:
+
+- `runDiscovery(context, job)` for custom login, seed data, app startup, or
+  product-specific screenshot/anchor capture.
+- `runRecipe(context, job)` for repo-owned deterministic recipe execution.
+- `runSuite(context, job)` for existing Playwright/Cypress suite integration.
+- `summarizeRepo(context)` for repo-local product summaries.
+
+Prefer adapter code that calls existing test helpers, page objects, fixtures,
+and product drivers. Do not duplicate working test infrastructure just to fit
+ThiaQ.
+
+The runner config may point at the adapter:
+
+```json
+{
+  "adapter": "example-product",
+  "adapterPath": "tests/thiaq/adapter.ts",
+  "baseUrl": "http://localhost:5174",
+  "repoPath": "/path/to/customer/repo"
+}
+```
+
+`thiaq runner setup` should add `.thiaq/` and `thiaq.runner.json` to
+`.gitignore` so local artifacts and runner tokens do not get committed.
+
+Run `thiaq runner doctor` before discovery. Treat failed adapter checks as
+setup blockers and warnings as explicit caveats in the ThiaQ project summary.
+
+## Required User Questions
+
+Ask only when the answer cannot be inferred safely:
+
+- What safe test URL should ThiaQ open?
+- What test role/account should discovery use?
+- What actions are safe to perform automatically?
+- What data must never be created, edited, deleted, transmitted, or persisted?
+- Which environment stores secrets, and what reference name should ThiaQ use?
+
+Do not ask the user to paste long product forms if repo evidence can answer the
+question.
+
+## MCP Tool Use
+
+Use the hosted MCP endpoint in Code Mode/search-and-execute when available. In
+that mode, first call `query` to find the typed ThiaQ operation, then call
+`execute` with the smallest useful operation and arguments.
+
+Use `get_project_context` first. Then call the smallest useful write operation:
+
+- `submit_repo_summary` for repo/docs/tests/Jira/GitHub summaries.
+- `propose_product_profile_changes` for product basics.
+- `propose_persona_changes` for additive personas.
+- `propose_job_changes` for persona-linked jobs.
+- `start_discovery_run` after runner or extension setup and safety review.
+- `propose_product_hierarchy_changes` for reviewable product maps that fuse
+  static repo analysis with live discovery evidence.
+- `propose_access_profile_changes` for test URL, role, auth, and secret refs.
+- `propose_safety_policy_changes` for safe/unsafe action boundaries.
+- `list_test_ideas` after discovery.
+- `propose_test_idea_promotion` to create reviewable promotion work.
+- `list_issue_categories` for UX confusion, selector, driver, assertion, and
+  safety gaps.
+- `create_repair_proposal` when an issue needs product, adapter, selector, or
+  assertion repair.
+
+For tool schemas and payload examples, read
+`references/mcp-tools.md` only when preparing MCP calls.
+
+## Summary Shape
+
+When submitting repo evidence, keep findings structured:
+
+```json
+{
+  "productProfile": {
+    "productName": "Example",
+    "productBrief": "Short product description"
+  },
+  "personas": [{ "name": "Workspace Admin", "evidence": ["docs/admin.md"] }],
+  "jobs": [{ "title": "Create and share a workflow", "personaName": "Analyst" }],
+  "hierarchy": {
+    "areas": [{ "areaId": "area.dashboard", "name": "Dashboard" }],
+    "features": [{ "featureId": "feature.projects", "areaId": "area.dashboard", "name": "Projects" }],
+    "surfaces": [{ "surfaceId": "surface.project-list", "featureId": "feature.projects", "name": "Project list" }]
+  },
+  "accessProfile": {
+    "loginUrl": "https://staging.example.com",
+    "testRole": "Primary test user",
+    "secretReference": "THIAQ_STAGING_SESSION"
+  },
+  "safetyPolicy": {
+    "safeActions": ["create test data"],
+    "unsafeActions": ["delete real customer data"]
+  }
+}
+```
+
+## Product Map Guidance
+
+Build a product map that a QA-oriented user can navigate immediately. The tree
+should expose product behavior, not account metadata:
+
+- Top visible level: product areas such as Dashboard, Canvas Authoring,
+  Collaboration, Admin, Billing, Reporting, or Workspace Organization.
+- Second level: features or workflows inside each area.
+- Third level: surfaces, controls, states, or canvas affordances that scenarios
+  can anchor to.
+- Scenario and issue counts should attach to the most specific useful node.
+- Never use the customer, project, tenant, or product name as the visible root
+  node. Keep that as surrounding context.
+- Carry evidence and confidence for inferred nodes so the first user can
+  rename, merge, split, or reject suggestions.
+
+Use repo structure alone only as a starting hypothesis. Prefer the fused view:
+what users can see in live discovery, what code/routes/tests call it, and what
+docs or issues say the product team calls it.
+
+## Completion Criteria
+
+Finish with a short status:
+
+- summaries submitted,
+- change sets created,
+- missing setup facts,
+- recommended next ThiaQ action,
+- any safety caveats.

package/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ThiaQ Project Setup"
+  short_description: "Set up ThiaQ from live discovery plus repo analysis."
+  default_prompt: "Use this skill to connect my runner or extension, discover my app, scan my repo, and propose a reviewed ThiaQ product map through the hosted MCP tools."

package/bin/install.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+import { cp, mkdir, rm } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const args = process.argv.slice(2);
+
+function hasFlag(flag) {
+  return args.includes(flag);
+}
+
+function valuesFor(flag) {
+  const values = [];
+  for (let index = 0; index < args.length; index += 1) {
+    if (args[index] === flag && args[index + 1]) values.push(args[index + 1]);
+  }
+  return values;
+}
+
+if (hasFlag("--help") || hasFlag("-h")) {
+  console.log(`Usage:
+  thiaq-project-skill install [--agent codex] [--agent claude-code] [--target /path/to/skills]
+
+Examples:
+  thiaq-project-skill install --agent codex
+  thiaq-project-skill install --agent codex --agent claude-code
+  thiaq-project-skill install --target ./.codex/skills
+`);
+  process.exit(0);
+}
+
+const command = args[0] ?? "install";
+if (command !== "install") {
+  throw new Error(`Unsupported command: ${command}`);
+}
+
+const explicitTargets = valuesFor("--target").map((target) => resolve(target));
+const agents = valuesFor("--agent");
+const selectedAgents =
+  agents.length > 0 || explicitTargets.length === 0 ? agents : [];
+const defaultAgents =
+  agents.length > 0 || explicitTargets.length > 0 ? selectedAgents : ["codex"];
+
+const agentTargets = defaultAgents.map((agent) => {
+  if (agent === "codex") return join(homedir(), ".codex", "skills");
+  if (agent === "claude-code" || agent === "claude") {
+    return join(homedir(), ".claude", "skills");
+  }
+  throw new Error(`Unsupported agent: ${agent}`);
+});
+
+const targets = [...new Set([...explicitTargets, ...agentTargets])];
+
+for (const target of targets) {
+  const destination = join(target, "thiaq-project");
+  await mkdir(target, { recursive: true });
+  await rm(destination, { recursive: true, force: true });
+  await cp(packageRoot, destination, {
+    recursive: true,
+    filter(source) {
+      return !source.includes(`${packageRoot}/node_modules`);
+    }
+  });
+  console.log(`Installed thiaq-project skill to ${destination}`);
+}

package/bin/validate.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { access, readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)));
+const requiredFiles = [
+  "SKILL.md",
+  "README.md",
+  "agents/openai.yaml",
+  "references/mcp-tools.md"
+];
+
+for (const file of requiredFiles) {
+  await access(join(root, file));
+}
+
+const skill = await readFile(join(root, "SKILL.md"), "utf8");
+if (!skill.startsWith("---\n")) {
+  throw new Error("SKILL.md must start with YAML frontmatter");
+}
+
+for (const required of ["name: thiaq-project", "description:"]) {
+  if (!skill.includes(required)) {
+    throw new Error(`SKILL.md missing required frontmatter: ${required}`);
+  }
+}
+
+console.log("thiaq-project skill package is valid");

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@thiaq/project-skill",
+  "version": "0.1.0",
+  "type": "module",
+  "private": false,
+  "description": "ThiaQ project setup skill for Codex and Claude Code agents.",
+  "license": "UNLICENSED",
+  "bin": {
+    "thiaq-project-skill": "./bin/install.mjs"
+  },
+  "files": [
+    "SKILL.md",
+    "README.md",
+    "agents",
+    "references",
+    "bin",
+    "package.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node ./bin/validate.mjs",
+    "prepack": "node ./bin/validate.mjs"
+  }
+}

package/references/mcp-tools.md

@@ -0,0 +1,233 @@
+# ThiaQ MCP Tool Reference
+
+Endpoint shape:
+
+```http
+POST /api/mcp?optimize_context=search_and_execute
+Authorization: Bearer <thiaq api token>
+Content-Type: application/json
+```
+
+Prefer Code Mode/search-and-execute for hosted commercial use. Search first:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "search-1",
+  "method": "tools/call",
+  "params": {
+    "name": "query",
+    "arguments": {
+      "projectId": "project-id",
+      "query": "personas jobs product hierarchy"
+    }
+  }
+}
+```
+
+Then execute typed calls:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "execute-1",
+  "method": "tools/call",
+  "params": {
+    "name": "execute",
+    "arguments": {
+      "projectId": "project-id",
+      "calls": [
+        {
+          "name": "get_project_context",
+          "arguments": { "projectId": "project-id" }
+        }
+      ]
+    }
+  }
+}
+```
+
+Native JSON-RPC tools are also available for development and small tool catalogs:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "call-1",
+  "method": "tools/call",
+  "params": {
+    "name": "get_project_context",
+    "arguments": { "projectId": "project-id" }
+  }
+}
+```
+
+## Read Context
+
+```json
+{
+  "name": "get_project_context",
+  "arguments": { "projectId": "project-id" }
+}
+```
+
+## Submit Repo Summary
+
+Use this for structured static analysis from docs, routes, tests, feature
+folders, stories, fixtures, registries, manifests, issue trackers, and existing
+QA tooling. Include product-map suggestions when the repo provides evidence,
+but mark them as proposals that should be fused with live discovery.
+
+```json
+{
+  "name": "submit_repo_summary",
+  "arguments": {
+    "projectId": "project-id",
+    "source": {
+      "sourceId": "repo.main",
+      "sourceType": "repo",
+      "label": "Main product repo",
+      "uri": "https://github.com/org/repo"
+    },
+    "title": "Repo product summary",
+    "summaryMarkdown": "Concise static findings with evidence refs.",
+    "evidenceRefs": ["README.md", "app/routes/dashboard.tsx", "tests/e2e/create.spec.ts"],
+    "findings": {
+      "productProfile": {},
+      "personas": [],
+      "jobs": [],
+      "hierarchy": {
+        "areas": [],
+        "features": [],
+        "surfaces": [],
+        "namingAssumptions": []
+      },
+      "accessProfile": {},
+      "safetyPolicy": {}
+    }
+  }
+}
+```
+
+## Product Hierarchy Proposal
+
+Use `propose_product_hierarchy_changes` after fusing live discovery evidence
+with static repo analysis. The proposal should be reviewable by the first user;
+do not treat inferred names as final.
+
+The visible tree should start with product areas. Do not make the customer,
+tenant, project, or product name the root node.
+
+```json
+{
+  "name": "propose_product_hierarchy_changes",
+  "arguments": {
+    "projectId": "project-id",
+    "title": "Review discovered product map",
+    "summary": "Combines live UI discovery with repo routes, tests, and docs.",
+    "source": "discovery:job-id + repo-summary:main",
+    "payload": {
+      "areas": [
+        {
+          "areaId": "area.canvas-authoring",
+          "name": "Canvas Authoring",
+          "evidenceRefs": ["discovery:screen.canvas", "app/routes/canvas.tsx"],
+          "confidence": 0.82
+        }
+      ],
+      "features": [
+        {
+          "featureId": "feature.canvas-shapes",
+          "areaId": "area.canvas-authoring",
+          "name": "Shapes",
+          "evidenceRefs": ["discovery:control.shape-toolbar", "tests/e2e/shapes.spec.ts"]
+        }
+      ],
+      "surfaces": [
+        {
+          "surfaceId": "surface.shape-toolbar",
+          "featureId": "feature.canvas-shapes",
+          "name": "Shape toolbar",
+          "evidenceRefs": ["discovery:control.shape-toolbar"]
+        }
+      ],
+      "reviewQuestions": [
+        "Should Shapes and Connectors stay separate, or merge under Canvas Editing?"
+      ]
+    }
+  }
+}
+```
+
+## Propose Changes
+
+Use the same shape for:
+
+- `propose_product_profile_changes`
+- `propose_persona_changes`
+- `propose_job_changes`
+- `propose_product_hierarchy_changes`
+- `propose_access_profile_changes`
+- `propose_safety_policy_changes`
+
+```json
+{
+  "name": "propose_job_changes",
+  "arguments": {
+    "projectId": "project-id",
+    "title": "Review persona jobs from repo",
+    "summary": "Adds jobs inferred from docs and E2E specs.",
+    "source": "repo-summary:main",
+    "payload": {
+      "jobs": [
+        {
+          "jobId": "job.create.workflow",
+          "personaName": "Process Analyst",
+          "title": "Create a workflow from the dashboard",
+          "description": "Open the dashboard, create a process map, and reach an editable canvas."
+        }
+      ]
+    }
+  }
+}
+```
+
+## Start Discovery Request
+
+This creates a runner job request. It does not execute approved CI.
+Run it after the runner or extension is connected, auth/session handling is
+available, and safe/unsafe action boundaries are known. Discovery should
+capture live UI evidence: screens, surfaces, controls, selector gaps, blocked
+paths, screenshots, canvas affordances, and bug candidates.
+
+```json
+{
+  "name": "start_discovery_run",
+  "arguments": {
+    "projectId": "project-id",
+    "targetUrl": "https://staging.example.com/dashboard",
+    "safetyPolicyId": "change-set-or-policy-id",
+    "budget": {
+      "maxStates": 8,
+      "maxActionsPerState": 12,
+      "timeLimitMinutes": 20
+    }
+  }
+}
+```
+
+## Promote Test Ideas
+
+This creates a reviewable promotion change set. It does not write approved
+flow code.
+
+```json
+{
+  "name": "propose_test_idea_promotion",
+  "arguments": {
+    "projectId": "project-id",
+    "ideaIds": ["idea.dashboard.create"],
+    "tier": "release_gate",
+    "summary": "Promote the dashboard create path into a draft recipe."
+  }
+}
+```