@thiaq/project-skill 0.1.0 → 0.1.1

package/README.md

@@ -26,6 +26,7 @@ npx thiaq-project-skill install --agent codex
 ```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.
+available, show me a draft three-level product tree for review, and only then
+propose a reviewed product map without making the customer or project name the
+root node.
 ```

package/SKILL.md

@@ -57,12 +57,15 @@ Jira, browser traces, tests, or other connected tools.
    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.
+9. Draft an explicit tree before any hierarchy write. It must have at least
+   three levels: `Product Area -> Feature or Workflow -> Surface`. Controls may
+   be fourth-level leaves. The customer or project name is context, not the
+   root tree node.
+10. Show the proposed tree to the first user in the chat, using indentation or
+   bullets so the structure is visible. Ask what should be renamed, merged,
+   split, moved, marked uncertain, or treated as release-critical.
+11. Only after the first user reviews or explicitly asks you to proceed, 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.
 
@@ -216,9 +219,11 @@ When submitting repo evidence, keep findings structured:
   "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" }]
+    "nodes": [
+      { "nodeId": "area.dashboard", "parentId": null, "level": 1, "kind": "product_area", "name": "Dashboard" },
+      { "nodeId": "feature.projects", "parentId": "area.dashboard", "level": 2, "kind": "feature", "name": "Projects" },
+      { "nodeId": "surface.project-list", "parentId": "feature.projects", "level": 3, "kind": "surface", "name": "Project list" }
+    ]
   },
   "accessProfile": {
     "loginUrl": "https://staging.example.com",
@@ -240,13 +245,20 @@ 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.
+- Third level: surfaces, states, or canvas affordances that scenarios can
+  anchor to.
+- Optional fourth level: controls only when the control is stable, named, and
+  useful as a scenario anchor.
 - 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.
+- Do not submit a flat list of sections as a hierarchy. The hierarchy proposal
+  must contain explicit tree nodes with stable `nodeId`, `parentId`, `level`,
+  `kind`, `name`, evidence, confidence, and review questions.
+- Do not submit the hierarchy before showing the draft tree to the user unless
+  the user explicitly tells you to proceed without review.
 
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thiaq/project-skill",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "private": false,
   "description": "ThiaQ project setup skill for Codex and Claude Code agents.",

package/references/mcp-tools.md

@@ -111,12 +111,18 @@ but mark them as proposals that should be fused with live discovery.
 ## 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.
+with static repo analysis. Before calling it, show the proposed tree to the
+first user and ask what should be renamed, merged, split, moved, marked
+uncertain, or treated as release-critical. 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.
 
+The proposal must include an explicit tree with at least three levels:
+`Product Area -> Feature or Workflow -> Surface`. Controls may be fourth-level
+leaves when they are stable scenario anchors. Flat sections or areas with nested
+free-form metadata are not enough.
+
 ```json
 {
   "name": "propose_product_hierarchy_changes",
@@ -126,26 +132,29 @@ tenant, project, or product name the root node.
     "summary": "Combines live UI discovery with repo routes, tests, and docs.",
     "source": "discovery:job-id + repo-summary:main",
     "payload": {
-      "areas": [
+      "nodes": [
         {
-          "areaId": "area.canvas-authoring",
+          "nodeId": "area.canvas-authoring",
+          "parentId": null,
+          "level": 1,
+          "kind": "product_area",
           "name": "Canvas Authoring",
           "evidenceRefs": ["discovery:screen.canvas", "app/routes/canvas.tsx"],
           "confidence": 0.82
-        }
-      ],
-      "features": [
+        },
         {
-          "featureId": "feature.canvas-shapes",
-          "areaId": "area.canvas-authoring",
+          "nodeId": "feature.canvas-shapes",
+          "parentId": "area.canvas-authoring",
+          "level": 2,
+          "kind": "feature",
           "name": "Shapes",
           "evidenceRefs": ["discovery:control.shape-toolbar", "tests/e2e/shapes.spec.ts"]
-        }
-      ],
-      "surfaces": [
+        },
         {
-          "surfaceId": "surface.shape-toolbar",
-          "featureId": "feature.canvas-shapes",
+          "nodeId": "surface.shape-toolbar",
+          "parentId": "feature.canvas-shapes",
+          "level": 3,
+          "kind": "surface",
           "name": "Shape toolbar",
           "evidenceRefs": ["discovery:control.shape-toolbar"]
         }