@nurix/etna 0.20.36 → 0.20.38

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (212) hide show
  1. package/data/catalog/rules/frontend.md +5 -5
  2. package/data/catalog/rules/pnpm.md +2 -2
  3. package/data/catalog/skills/nustack/SKILL.md +2 -2
  4. package/data/catalog/skills/nustack/references/cli-design.md +35 -35
  5. package/data/catalog/skills/nustack/references/monorepo-master-list.md +6 -6
  6. package/data/catalog/skills/nustack/references/monorepo-setup.md +13 -13
  7. package/data/catalog/skills/nustack/references/publishing.md +40 -39
  8. package/data/harness-index.json +1 -1
  9. package/data/harnesses/code/harness.json +2 -2
  10. package/data/harnesses/code/hooks/approved-packages.md +1 -2
  11. package/data/harnesses/code/rules/frontend.md +5 -5
  12. package/data/harnesses/code/rules/pnpm.md +2 -2
  13. package/data/harnesses/code/skills/boundary/SKILL.md +33 -22
  14. package/data/harnesses/code/skills/boundary/references/index.md +2 -4
  15. package/data/harnesses/code/skills/boundary/references/mechanisms.md +3 -10
  16. package/data/harnesses/code/skills/boundary/references/packs/build-config-runtime.md +1 -1
  17. package/data/harnesses/code/skills/boundary/references/packs/frontend.md +17 -17
  18. package/data/harnesses/code/skills/boundary/references/packs/generic-tail.md +1 -1
  19. package/data/harnesses/code/skills/brainstorm/README.md +11 -13
  20. package/data/harnesses/code/skills/brainstorm/SKILL.md +150 -132
  21. package/data/harnesses/code/skills/brainstorm/references/doctrine.md +48 -51
  22. package/data/harnesses/code/skills/brainstorm/references/harvest.md +51 -56
  23. package/data/harnesses/code/skills/brainstorm/references/session-schema.md +48 -42
  24. package/data/harnesses/code/skills/design/SKILL.md +31 -35
  25. package/data/harnesses/code/skills/design/components/charts.md +121 -43
  26. package/data/harnesses/code/skills/design/components/collections.md +209 -41
  27. package/data/harnesses/code/skills/design/components/feedback.md +86 -25
  28. package/data/harnesses/code/skills/design/components/hooks.md +198 -12
  29. package/data/harnesses/code/skills/design/components/index.md +93 -71
  30. package/data/harnesses/code/skills/design/components/inputs.md +249 -157
  31. package/data/harnesses/code/skills/design/components/layout.md +98 -38
  32. package/data/harnesses/code/skills/design/components/media.md +46 -25
  33. package/data/harnesses/code/skills/design/components/motion.md +56 -46
  34. package/data/harnesses/code/skills/design/components/navigation.md +54 -15
  35. package/data/harnesses/code/skills/design/components/overlays.md +51 -41
  36. package/data/harnesses/code/skills/design/components/setup.md +84 -5
  37. package/data/harnesses/code/skills/design/components/typography.md +72 -22
  38. package/data/harnesses/code/skills/design/components/utils.md +47 -13
  39. package/data/harnesses/code/skills/design/data/chrome/board-column.md +12 -12
  40. package/data/harnesses/code/skills/design/data/chrome/data-table.md +6 -6
  41. package/data/harnesses/code/skills/design/data/chrome/side-panel.md +15 -15
  42. package/data/harnesses/code/skills/design/data/chrome/sidebar.md +25 -25
  43. package/data/harnesses/code/skills/design/data/chrome/stat-cards.md +22 -22
  44. package/data/harnesses/code/skills/design/data/chrome/topbar.md +12 -12
  45. package/data/harnesses/code/skills/design/data/iconography.md +2 -2
  46. package/data/harnesses/code/skills/design/references/compose.md +14 -16
  47. package/data/harnesses/code/skills/design/references/emission.md +6 -6
  48. package/data/harnesses/code/skills/design/references/foundations.md +5 -5
  49. package/data/harnesses/code/skills/design/references/intake.md +6 -6
  50. package/data/harnesses/code/skills/design/references/object-pass.md +1 -1
  51. package/data/harnesses/code/skills/design/references/ship-gate.md +5 -5
  52. package/data/harnesses/code/skills/design/references/ux-patterns/Readme.md +4 -4
  53. package/data/harnesses/code/skills/design/references/ux-patterns/ai-layer.md +1 -1
  54. package/data/harnesses/code/skills/design/references/ux-patterns/container-choice.md +1 -1
  55. package/data/harnesses/code/skills/design/references/ux-patterns/dashboards.md +1 -1
  56. package/data/harnesses/code/skills/design/references/ux-patterns/modes.md +1 -1
  57. package/data/harnesses/code/skills/design/references/ux-patterns/object-model.md +2 -2
  58. package/data/harnesses/code/skills/design/references/ux-patterns/promotion-demotion.md +1 -1
  59. package/data/harnesses/code/skills/design/references/ux-patterns/settings.md +1 -1
  60. package/data/harnesses/code/skills/design/references/ux-patterns/standard-pages.md +1 -1
  61. package/data/harnesses/code/skills/design/scripts/README-validator.md +20 -8
  62. package/data/harnesses/code/skills/design/scripts/validate-design-md.mjs +15 -10
  63. package/data/harnesses/code/skills/documentation/SKILL.md +5 -5
  64. package/data/harnesses/code/skills/documentation/references/examples.md +22 -22
  65. package/data/harnesses/code/skills/documentation/references/frontmatter.md +3 -3
  66. package/data/harnesses/code/skills/documentation/references/instruction-style.md +3 -3
  67. package/data/harnesses/code/skills/documentation/references/source-comments.md +3 -3
  68. package/data/harnesses/code/skills/documentation/references/style-guide.md +5 -5
  69. package/data/harnesses/code/skills/documentation/references/untemplated.md +8 -8
  70. package/data/harnesses/code/skills/documentation/scripts/doc-lint.mjs +3 -2
  71. package/data/harnesses/code/skills/documentation/templates/Readme.md +1 -1
  72. package/data/harnesses/code/skills/documentation/templates/acceptance-criteria.md +1 -1
  73. package/data/harnesses/code/skills/documentation/templates/api-reference.md +1 -1
  74. package/data/harnesses/code/skills/documentation/templates/architecture-decision.md +3 -7
  75. package/data/harnesses/code/skills/documentation/templates/behavioral-checklist.md +1 -1
  76. package/data/harnesses/code/skills/documentation/templates/changelog-entry.md +1 -1
  77. package/data/harnesses/code/skills/documentation/templates/changelog-index.md +1 -1
  78. package/data/harnesses/code/skills/documentation/templates/docs-readme.md +3 -3
  79. package/data/harnesses/code/skills/documentation/templates/doctrine.md +1 -1
  80. package/data/harnesses/code/skills/documentation/templates/domain-model.md +1 -1
  81. package/data/harnesses/code/skills/documentation/templates/environment-registry.md +1 -1
  82. package/data/harnesses/code/skills/documentation/templates/feature.md +3 -3
  83. package/data/harnesses/code/skills/documentation/templates/handover.md +2 -2
  84. package/data/harnesses/code/skills/documentation/templates/implementation-map.md +1 -1
  85. package/data/harnesses/code/skills/documentation/templates/migration-runbook.md +1 -1
  86. package/data/harnesses/code/skills/documentation/templates/non-goals.md +1 -1
  87. package/data/harnesses/code/skills/documentation/templates/operations-procedure.md +2 -2
  88. package/data/harnesses/code/skills/documentation/templates/package.md +1 -1
  89. package/data/harnesses/code/skills/documentation/templates/protected-files.md +1 -1
  90. package/data/harnesses/code/skills/documentation/templates/root-readme.md +1 -1
  91. package/data/harnesses/code/skills/documentation/templates/security-overview.md +1 -1
  92. package/data/harnesses/code/skills/documentation/templates/system-overview.md +1 -1
  93. package/data/harnesses/code/skills/documentation/templates/system.md +1 -1
  94. package/data/harnesses/code/skills/documentation/templates/testing-strategy.md +1 -1
  95. package/data/harnesses/code/skills/documentation/templates/ux-behavior.md +3 -5
  96. package/data/harnesses/code/skills/issue-bridge/SKILL.md +51 -16
  97. package/data/harnesses/code/skills/issue-bridge/references/trackers/github.md +5 -5
  98. package/data/harnesses/code/skills/issue-bridge/references/trackers/jira.md +11 -8
  99. package/data/harnesses/code/skills/issue-bridge/references/trackers/linear.md +16 -11
  100. package/data/harnesses/code/skills/nustack-graph/SKILL.md +38 -29
  101. package/data/harnesses/code/skills/polygraph/references/dispatch.md +31 -18
  102. package/data/harnesses/code/skills/polygraph/references/rows.md +11 -6
  103. package/data/harnesses/code/skills/schema-design/SKILL.md +39 -41
  104. package/data/harnesses/code/skills/test/SKILL.md +38 -42
  105. package/data/harnesses/code/skills/testing/SKILL.md +83 -73
  106. package/data/harnesses/code/skills/workflow-mapper/SKILL.md +156 -193
  107. package/data/harnesses/code/skills/workflow-mapper/references/patterns.md +15 -15
  108. package/data/harnesses/delivery/harness.json +2 -2
  109. package/data/harnesses/delivery/skills/brainstorm/README.md +11 -13
  110. package/data/harnesses/delivery/skills/brainstorm/SKILL.md +150 -132
  111. package/data/harnesses/delivery/skills/brainstorm/references/doctrine.md +48 -51
  112. package/data/harnesses/delivery/skills/brainstorm/references/harvest.md +51 -56
  113. package/data/harnesses/delivery/skills/brainstorm/references/session-schema.md +48 -42
  114. package/data/harnesses/delivery/skills/cost-report/SKILL.md +10 -10
  115. package/data/harnesses/delivery/skills/documentation/SKILL.md +5 -5
  116. package/data/harnesses/delivery/skills/documentation/references/examples.md +22 -22
  117. package/data/harnesses/delivery/skills/documentation/references/frontmatter.md +3 -3
  118. package/data/harnesses/delivery/skills/documentation/references/instruction-style.md +3 -3
  119. package/data/harnesses/delivery/skills/documentation/references/source-comments.md +3 -3
  120. package/data/harnesses/delivery/skills/documentation/references/style-guide.md +5 -5
  121. package/data/harnesses/delivery/skills/documentation/references/untemplated.md +8 -8
  122. package/data/harnesses/delivery/skills/documentation/scripts/doc-lint.mjs +3 -2
  123. package/data/harnesses/delivery/skills/documentation/templates/Readme.md +1 -1
  124. package/data/harnesses/delivery/skills/documentation/templates/acceptance-criteria.md +1 -1
  125. package/data/harnesses/delivery/skills/documentation/templates/api-reference.md +1 -1
  126. package/data/harnesses/delivery/skills/documentation/templates/architecture-decision.md +3 -7
  127. package/data/harnesses/delivery/skills/documentation/templates/behavioral-checklist.md +1 -1
  128. package/data/harnesses/delivery/skills/documentation/templates/changelog-entry.md +1 -1
  129. package/data/harnesses/delivery/skills/documentation/templates/changelog-index.md +1 -1
  130. package/data/harnesses/delivery/skills/documentation/templates/docs-readme.md +3 -3
  131. package/data/harnesses/delivery/skills/documentation/templates/doctrine.md +1 -1
  132. package/data/harnesses/delivery/skills/documentation/templates/domain-model.md +1 -1
  133. package/data/harnesses/delivery/skills/documentation/templates/environment-registry.md +1 -1
  134. package/data/harnesses/delivery/skills/documentation/templates/feature.md +3 -3
  135. package/data/harnesses/delivery/skills/documentation/templates/handover.md +2 -2
  136. package/data/harnesses/delivery/skills/documentation/templates/implementation-map.md +1 -1
  137. package/data/harnesses/delivery/skills/documentation/templates/migration-runbook.md +1 -1
  138. package/data/harnesses/delivery/skills/documentation/templates/non-goals.md +1 -1
  139. package/data/harnesses/delivery/skills/documentation/templates/operations-procedure.md +2 -2
  140. package/data/harnesses/delivery/skills/documentation/templates/package.md +1 -1
  141. package/data/harnesses/delivery/skills/documentation/templates/protected-files.md +1 -1
  142. package/data/harnesses/delivery/skills/documentation/templates/root-readme.md +1 -1
  143. package/data/harnesses/delivery/skills/documentation/templates/security-overview.md +1 -1
  144. package/data/harnesses/delivery/skills/documentation/templates/system-overview.md +1 -1
  145. package/data/harnesses/delivery/skills/documentation/templates/system.md +1 -1
  146. package/data/harnesses/delivery/skills/documentation/templates/testing-strategy.md +1 -1
  147. package/data/harnesses/delivery/skills/documentation/templates/ux-behavior.md +3 -5
  148. package/data/harnesses/delivery/skills/escalate/SKILL.md +11 -11
  149. package/data/harnesses/delivery/skills/prompt-eval/SKILL.md +8 -8
  150. package/data/harnesses/delivery/skills/prompt-library/SKILL.md +30 -9
  151. package/data/harnesses/delivery/skills/route/SKILL.md +8 -8
  152. package/data/harnesses/etna/harness.json +2 -2
  153. package/data/harnesses/etna/skills/boundary/SKILL.md +33 -22
  154. package/data/harnesses/etna/skills/boundary/references/index.md +2 -4
  155. package/data/harnesses/etna/skills/boundary/references/mechanisms.md +3 -10
  156. package/data/harnesses/etna/skills/boundary/references/packs/build-config-runtime.md +1 -1
  157. package/data/harnesses/etna/skills/boundary/references/packs/frontend.md +17 -17
  158. package/data/harnesses/etna/skills/boundary/references/packs/generic-tail.md +1 -1
  159. package/data/harnesses/etna/skills/brainstorm/README.md +11 -13
  160. package/data/harnesses/etna/skills/brainstorm/SKILL.md +150 -132
  161. package/data/harnesses/etna/skills/brainstorm/references/doctrine.md +48 -51
  162. package/data/harnesses/etna/skills/brainstorm/references/harvest.md +51 -56
  163. package/data/harnesses/etna/skills/brainstorm/references/session-schema.md +48 -42
  164. package/data/harnesses/etna/skills/documentation/SKILL.md +5 -5
  165. package/data/harnesses/etna/skills/documentation/references/examples.md +22 -22
  166. package/data/harnesses/etna/skills/documentation/references/frontmatter.md +3 -3
  167. package/data/harnesses/etna/skills/documentation/references/instruction-style.md +3 -3
  168. package/data/harnesses/etna/skills/documentation/references/source-comments.md +3 -3
  169. package/data/harnesses/etna/skills/documentation/references/style-guide.md +5 -5
  170. package/data/harnesses/etna/skills/documentation/references/untemplated.md +8 -8
  171. package/data/harnesses/etna/skills/documentation/scripts/doc-lint.mjs +3 -2
  172. package/data/harnesses/etna/skills/documentation/templates/Readme.md +1 -1
  173. package/data/harnesses/etna/skills/documentation/templates/acceptance-criteria.md +1 -1
  174. package/data/harnesses/etna/skills/documentation/templates/api-reference.md +1 -1
  175. package/data/harnesses/etna/skills/documentation/templates/architecture-decision.md +3 -7
  176. package/data/harnesses/etna/skills/documentation/templates/behavioral-checklist.md +1 -1
  177. package/data/harnesses/etna/skills/documentation/templates/changelog-entry.md +1 -1
  178. package/data/harnesses/etna/skills/documentation/templates/changelog-index.md +1 -1
  179. package/data/harnesses/etna/skills/documentation/templates/docs-readme.md +3 -3
  180. package/data/harnesses/etna/skills/documentation/templates/doctrine.md +1 -1
  181. package/data/harnesses/etna/skills/documentation/templates/domain-model.md +1 -1
  182. package/data/harnesses/etna/skills/documentation/templates/environment-registry.md +1 -1
  183. package/data/harnesses/etna/skills/documentation/templates/feature.md +3 -3
  184. package/data/harnesses/etna/skills/documentation/templates/handover.md +2 -2
  185. package/data/harnesses/etna/skills/documentation/templates/implementation-map.md +1 -1
  186. package/data/harnesses/etna/skills/documentation/templates/migration-runbook.md +1 -1
  187. package/data/harnesses/etna/skills/documentation/templates/non-goals.md +1 -1
  188. package/data/harnesses/etna/skills/documentation/templates/operations-procedure.md +2 -2
  189. package/data/harnesses/etna/skills/documentation/templates/package.md +1 -1
  190. package/data/harnesses/etna/skills/documentation/templates/protected-files.md +1 -1
  191. package/data/harnesses/etna/skills/documentation/templates/root-readme.md +1 -1
  192. package/data/harnesses/etna/skills/documentation/templates/security-overview.md +1 -1
  193. package/data/harnesses/etna/skills/documentation/templates/system-overview.md +1 -1
  194. package/data/harnesses/etna/skills/documentation/templates/system.md +1 -1
  195. package/data/harnesses/etna/skills/documentation/templates/testing-strategy.md +1 -1
  196. package/data/harnesses/etna/skills/documentation/templates/ux-behavior.md +3 -5
  197. package/data/harnesses/etna/skills/workflow-mapper/SKILL.md +156 -193
  198. package/data/harnesses/etna/skills/workflow-mapper/references/patterns.md +15 -15
  199. package/data/harnesses/hr/harness.json +2 -2
  200. package/data/harnesses/hr/skills/evaluator/SKILL.md +71 -73
  201. package/data/harnesses/hr/skills/evaluator/criteria/code-quality.md +28 -47
  202. package/data/harnesses/hr/skills/evaluator/criteria/deployment-readiness.md +33 -43
  203. package/data/harnesses/hr/skills/evaluator/criteria/maintainability.md +34 -46
  204. package/data/harnesses/hr/skills/evaluator/criteria/mechanical-ambition.md +13 -13
  205. package/data/harnesses/hr/skills/evaluator/criteria/problem-substantiveness.md +7 -7
  206. package/data/harnesses/hr/skills/evaluator/criteria/testing.md +36 -41
  207. package/data/harnesses/hr/skills/evaluator/criteria/ux-mechanics.md +25 -11
  208. package/data/harnesses/hr/skills/evaluator/criteria/value-articulation.md +7 -7
  209. package/data/harnesses/hr/skills/evaluator/preflight.md +27 -46
  210. package/data/harnesses/hr/skills/interview-eval/SKILL.md +37 -42
  211. package/data/harnesses/hr/skills/interview-eval/rubric.md +21 -23
  212. package/package.json +2 -2
@@ -3,144 +3,120 @@ name: workflow-mapper
3
3
  description: "Use when mapping a codebase's major workflows — traces call chains from user action to database or external system and produces mermaid sequence diagrams + markdown. Triggers on 'map workflows', 'trace flows', 'sequence diagram', 'how does X work end-to-end'."
4
4
  ---
5
5
 
6
- # Workflow Mapper Skill
6
+ # Workflow mapper
7
7
 
8
- Identify and document every major workflow in a codebase by tracing execution paths from trigger to terminal effect. Output is a single markdown file with mermaid sequence diagrams.
8
+ Trace every major workflow in a codebase from trigger to terminal effect, and write one markdown file of mermaid sequence diagrams.
9
9
 
10
- ---
11
-
12
- ## Decision Tree
10
+ ## Modes
13
11
 
14
- ```
15
- User request
16
- │
17
- ├─ "Map all workflows" ────────────▶ Full Discovery (all phases)
18
- │
19
- ├─ "Map workflow for {feature}" ───▶ Targeted Discovery (skip Phase 1 broad scan)
20
- │
21
- ├─ "Update workflow map" ──────────▶ Incremental (diff against existing map)
22
- │
23
- └─ "How does X work end-to-end" ──▶ Single Workflow Trace (Phase 2-4 only)
24
- ```
12
+ | Request | Mode | Runs |
13
+ | --- | --- | --- |
14
+ | "Map all workflows" | Full discovery (default) | Phases 1–5 |
15
+ | "Map workflow for {feature}" | Targeted discovery | Phases 2–5, from the feature's own entry points instead of the Phase 1 broad scan |
16
+ | "Update workflow map" | Incremental | Re-traces only workflows whose files changed against the existing map |
17
+ | "How does X work end-to-end" | Single workflow trace | Phases 2–4 only |
25
18
 
26
- ---
19
+ Dispatch and per-mode procedure are § Execution strategy. Load [`references/patterns.md`](references/patterns.md) at the start of Phase 1 (or of a targeted search) — it carries framework detection and the full grep/glob patterns per stack; the patterns below are the summary.
27
20
 
28
- ## Phase 1: Entry Point Discovery
21
+ ## Phase 1: Entry point discovery
29
22
 
30
- Find all places where a multi-step process begins. Use parallel sub-agents — one per technique.
23
+ Find every place a multi-step process begins, one sub-agent per technique. Adapt each pattern to the framework detected.
31
24
 
32
- ### Technique 1: Route Harvesting
25
+ ### Technique 1: Route harvesting
33
26
 
34
- Scan all API route definitions. These are the primary entry points for backend workflows.
27
+ API route definitions are the primary backend entry points.
35
28
 
36
29
  ```
37
- Search patterns (adapt to framework):
38
- Express: router.(get|post|put|patch|delete)\(
39
- Fastify: fastify.(get|post|put|patch|delete)\(
40
- Next.js: export (async )?function (GET|POST|PUT|PATCH|DELETE)
41
- Hono: app.(get|post|put|patch|delete)\(
42
- tRPC: .query\(|.mutation\(
30
+ Express: router.(get|post|put|patch|delete)\(
31
+ Fastify: fastify.(get|post|put|patch|delete)\(
32
+ Next.js: export (async )?function (GET|POST|PUT|PATCH|DELETE)
33
+ Hono: app.(get|post|put|patch|delete)\(
34
+ tRPC: .query\(|.mutation\(
43
35
  ```
44
36
 
45
- For each route, record: `{ method, path, handler_function, file }`.
37
+ Record each route as `{ method, path, handler_function, file }`. Drop trivial CRUD (one DB call plus a response); keep a route that:
46
38
 
47
- Filter out trivial CRUD (single DB call + response). Keep routes that:
39
+ - calls `startWorkflow`, `addJob`, `enqueue`, `emit` or `publish` (async dispatch)
40
+ - calls two or more service functions in sequence
41
+ - opens a transaction (`$transaction`, `BEGIN`, `withTransaction`)
42
+ - returns a job or workflow ID for polling
43
+ - triggers WebSocket or SSE events
48
44
 
49
- - Call `startWorkflow`, `addJob`, `enqueue`, `emit`, `publish` (async dispatch)
50
- - Call 2+ service functions sequentially
51
- - Have transaction blocks (`$transaction`, `BEGIN`, `withTransaction`)
52
- - Return a job/workflow ID for polling
53
- - Trigger WebSocket/SSE events
45
+ ### Technique 2: Background job discovery
54
46
 
55
- ### Technique 2: Background Job Discovery
56
-
57
- Find all registered background jobs, workflows, and queues.
47
+ Find every registered background job, workflow and queue.
58
48
 
59
49
  ```
60
- Search patterns:
61
- Temporal: export async function .*Workflow|workflowModules|startChild\(
62
- BullMQ: new Queue\(|new Worker\(|.add\(|.process\(
63
- Celery: @app.task|@shared_task
64
- Inngest: createFunction\(|inngest.send\(
65
- Cron: cron.schedule\(|@Cron\(|node-cron
66
- EventEmitter: .on\(|.emit\(|EventEmitter
50
+ Temporal: export async function .*Workflow|workflowModules|startChild\(
51
+ BullMQ: new Queue\(|new Worker\(|.add\(|.process\(
52
+ Celery: @app.task|@shared_task
53
+ Inngest: createFunction\(|inngest.send\(
54
+ Cron: cron.schedule\(|@Cron\(|node-cron
55
+ EventEmitter: .on\(|.emit\(|EventEmitter
67
56
  ```
68
57
 
69
- For Temporal specifically, also check:
70
-
71
- - `temporal/config/workflowModules.js` — workflow registry with queues and dependencies
72
- - `temporal/config/activityModules.js` — activity aggregation
58
+ For Temporal, also read `temporal/config/workflowModules.js` (the workflow registry, with queues and dependencies) and `temporal/config/activityModules.js` (activity aggregation).
73
59
 
74
- ### Technique 3: Frontend Action Tracing
60
+ ### Technique 3: Frontend action tracing
75
61
 
76
62
  Find UI-initiated multi-step flows.
77
63
 
78
64
  ```
79
- Search patterns:
80
- Redux thunks: createAsyncThunk\(|dispatch\(
81
- API calls: api\.(post|put|patch|delete)\(|axios\.(post|put|patch|delete)\(|fetch\(
82
- Form submits: onSubmit|handleSubmit
83
- Custom hooks: use[A-Z].*\(\) that contain API calls
65
+ Redux thunks: createAsyncThunk\(|dispatch\(
66
+ API calls: api\.(post|put|patch|delete)\(|axios\.(post|put|patch|delete)\(|fetch\(
67
+ Form submits: onSubmit|handleSubmit
68
+ Custom hooks: use[A-Z].*\(\) that contain API calls
84
69
  ```
85
70
 
86
- Focus on actions that:
71
+ Keep actions that:
87
72
 
88
- - POST/PUT/PATCH/DELETE to backend (not just GETs)
89
- - Dispatch multiple Redux actions in sequence
90
- - Start polling loops (`setInterval`, recursive `setTimeout`, retry patterns)
91
- - Open WebSocket connections or listen for server-sent events
73
+ - POST, PUT, PATCH or DELETE to the backend — **never** a GET alone
74
+ - dispatch several Redux actions in sequence
75
+ - start a polling loop (`setInterval`, recursive `setTimeout`, retry patterns)
76
+ - open a WebSocket connection or listen for server-sent events
92
77
 
93
- ### Technique 4: Event & Message Tracing
78
+ ### Technique 4: Event and message tracing
94
79
 
95
80
  Find event-driven workflows (WebSocket, pub/sub, SSE).
96
81
 
97
82
  ```
98
- Search patterns:
99
- WebSocket: socket.on\(|io.on\(|ws.on\(
100
- SSE: EventSource|text/event-stream
101
- Redis pub: .publish\(|.subscribe\(
102
- Message: .sendMessage\(|.postMessage\(
83
+ WebSocket: socket.on\(|io.on\(|ws.on\(
84
+ SSE: EventSource|text/event-stream
85
+ Redis pub: .publish\(|.subscribe\(
86
+ Message: .sendMessage\(|.postMessage\(
103
87
  ```
104
88
 
105
- ### Technique 5: Scheduled & Lifecycle Workflows
89
+ ### Technique 5: Scheduled and lifecycle workflows
106
90
 
107
91
  ```
108
- Search patterns:
109
- App startup: app.listen|bootstrap|onModuleInit|main\(\)
110
- Shutdown: SIGTERM|SIGINT|gracefulShutdown|onModuleDestroy
111
- Migrations: migrate|seed|up\(\)|down\(\)
112
- Health checks: /health|/ping|/ready|/live
92
+ App startup: app.listen|bootstrap|onModuleInit|main\(\)
93
+ Shutdown: SIGTERM|SIGINT|gracefulShutdown|onModuleDestroy
94
+ Migrations: migrate|seed|up\(\)|down\(\)
95
+ Health checks: /health|/ping|/ready|/live
113
96
  ```
114
97
 
115
- ---
116
-
117
- ## Phase 2: Call Chain Tracing
98
+ ## Phase 2: Call chain tracing
118
99
 
119
- For each discovered entry point, trace the full execution path. Use one sub-agent per workflow for parallelism.
100
+ Trace each entry point's full execution path, one sub-agent per workflow.
120
101
 
121
- ### Tracing Algorithm
102
+ ### Tracing algorithm
122
103
 
123
- ```
124
- 1. Start at the entry point function
125
- 2. Read the function body
126
- 3. For each function call or await:
127
- a. Is it a DB operation? → Record as "Database" participant action
128
- b. Is it an external API call? → Record as "{ServiceName}" participant action
129
- c. Is it a queue/workflow dispatch? → Record as "{QueueSystem}" participant, then recurse into the dispatched handler
130
- d. Is it a Redux dispatch? → Record as "Redux" participant action
131
- e. Is it an internal function in the same service? → Recurse (but cap depth at 4)
132
- f. Is it a WebSocket emit? → Record as "WebSocket" participant action
133
- 4. Record branching (if/else, try/catch, switch) as alt/opt blocks
134
- 5. Record loops (polling, retry, pagination) as loop blocks
135
- 6. Stop when you hit: a return to the caller, a terminal DB write, or an external system response
136
- 7. If a workflow trace exceeds the configured depth cap, stop tracing and note the overflow point with a comment like "→ [continues deeper, capped at depth N]". Do not silently truncate.
137
- ```
104
+ 1. Start at the entry point function and read its body.
105
+ 2. Classify each function call or `await`:
106
+ 1. DB operation → a `Database` action.
107
+ 2. External API call → a `{ServiceName}` action.
108
+ 3. Queue or workflow dispatch → a `{QueueSystem}` action, then recurse into the dispatched handler.
109
+ 4. Redux dispatch → a `Redux` action.
110
+ 5. Internal function in the same service → recurse, up to depth 4 unless the user sets another cap.
111
+ 6. WebSocket emit → a `WebSocket` action.
112
+ 3. Record branching (`if`/`else`, `try`/`catch`, `switch`) as `alt` or `opt` blocks.
113
+ 4. Record loops (polling, retry, pagination) as `loop` blocks.
114
+ 5. Stop at a return to the caller, a terminal DB write, or an external system's response.
115
+ 6. When a trace hits the depth cap, stop and mark the overflow point — `→ [continues deeper, capped at depth N]`. **Never** truncate silently.
138
116
 
139
- ### Participant Identification
117
+ ### Participant identification
140
118
 
141
- Map code actors to diagram participants using this hierarchy:
142
-
143
- | Code Pattern | Participant Name |
119
+ | Code pattern | Participant |
144
120
  | --- | --- |
145
121
  | React component, hook, event handler | `User` + `Frontend` |
146
122
  | Express/API route handler | `API` |
@@ -155,27 +131,25 @@ Map code actors to diagram participants using this hierarchy:
155
131
  | Email/SMS send | `Notifications` |
156
132
  | Auth provider (Keycloak, Better Auth, Auth0) | `Auth` |
157
133
 
158
- ### Branching Detection
134
+ ### Branching detection
159
135
 
160
- Look for conditional logic that represents meaningful workflow forks:
136
+ Draw a block only for conditional logic that forks the workflow:
161
137
 
162
- ```
163
- - Version conflicts (optimistic locking) → alt block
164
- - Permission/auth checks → opt block
165
- - Feature flags → opt block
166
- - Error handling with different outcomes → alt block
167
- - Retry with backoff → loop block
168
- - Polling for completion → loop block
169
- - Batch processing → loop block
170
- ```
171
-
172
- ---
138
+ | Condition | Block |
139
+ | --- | --- |
140
+ | Version conflict (optimistic locking) | `alt` |
141
+ | Error handling whose outcomes differ | `alt` |
142
+ | Permission or auth check | `opt` |
143
+ | Feature flag | `opt` |
144
+ | Retry with backoff | `loop` |
145
+ | Polling for completion | `loop` |
146
+ | Batch processing | `loop` |
173
147
 
174
- ## Phase 3: Classification & Filtering
148
+ ## Phase 3: Classification and filtering
175
149
 
176
- Not every API route is a "workflow". Classify and filter.
150
+ Not every route is a workflow.
177
151
 
178
- ### Workflow Categories
152
+ ### Workflow categories
179
153
 
180
154
  | Category | Criteria | Include? |
181
155
  | --- | --- | --- |
@@ -189,22 +163,21 @@ Not every API route is a "workflow". Classify and filter.
189
163
  | **Static Serving** | File serving, asset delivery | Skip |
190
164
  | **Health/Config** | Health checks, config endpoints | Skip |
191
165
 
192
- ### Complexity Scoring
166
+ ### Complexity scoring
193
167
 
194
- Score each workflow to determine diagram detail level:
168
+ The score sets the diagram's detail: a simple workflow gets a compact diagram, a complex one full detail with `alt`/`opt`/`loop` blocks.
195
169
 
196
- - **Steps**: Count distinct operations (DB calls, API calls, dispatches). 1-2 = simple, 3-5 = moderate, 6+ = complex
197
- - **Participants**: Count distinct systems involved. 2 = simple, 3-4 = moderate, 5+ = complex
198
- - **Branching**: Count alt/opt blocks. 0 = linear, 1-2 = moderate, 3+ = complex
199
- - **Async**: Has polling, callbacks, child workflows? +1 complexity level
170
+ | Axis | Simple | Moderate | Complex |
171
+ | --- | --- | --- | --- |
172
+ | Steps — distinct operations (DB calls, API calls, dispatches) | 1–2 | 3–5 | 6+ |
173
+ | Participants — distinct systems | 2 | 3–4 | 5+ |
174
+ | Branching — `alt`/`opt` blocks | 0 (linear) | 1–2 | 3+ |
200
175
 
201
- Simple workflows get a compact diagram. Complex workflows get full detail with alt/opt/loop blocks.
176
+ Async behaviour — polling, callbacks, child workflows — raises the score one level.
202
177
 
203
- ---
178
+ ## Phase 4: Mermaid diagram generation
204
179
 
205
- ## Phase 4: Mermaid Diagram Generation
206
-
207
- ### Diagram Template
180
+ ### Diagram template
208
181
 
209
182
  ````markdown
210
183
  ### {Workflow Name}
@@ -233,22 +206,22 @@ sequenceDiagram
233
206
  - {Known edge cases or failure modes}
234
207
  ````
235
208
 
236
- ### Diagram Rules
209
+ ### Diagram rules
237
210
 
238
- 1. **Arrow types**: Solid (`->>`) for calls/requests, dashed (`-->>`) for returns/responses
239
- 2. **Activation bars**: Use `activate`/`deactivate` only for long-running operations (Temporal workflows, polling loops)
240
- 3. **Alt blocks**: Use for real workflow branching (conflict vs success), not for error handling
241
- 4. **Loop blocks**: Use for polling, retry, batch processing — include the condition
242
- 5. **Opt blocks**: Use for conditional steps (feature flags, optional integrations)
243
- 6. **Notes**: Use `Note over` for context that doesn't fit in arrow labels
244
- 7. **Participant order**: Left-to-right follows the data flow direction (User → Frontend → API → Backend → Database)
245
- 8. **Label brevity**: Arrow labels should be ≤8 words. Use the action, not the implementation detail
246
- 9. **Max participants**: 7 per diagram. If more, split into sub-diagrams or collapse internal services
247
- 10. **Max steps**: 15 visible interactions per diagram. For longer workflows, group related steps or use `rect` blocks
211
+ 1. **Arrow types:** solid (`->>`) for calls and requests, dashed (`-->>`) for returns and responses.
212
+ 2. **Activation bars:** `activate`/`deactivate` **only** for long-running operations (Temporal workflows, polling loops).
213
+ 3. **Alt blocks:** for a real workflow branch whose outcomes differ (conflict vs success) — **never** for generic error handling such as a catch that rethrows.
214
+ 4. **Loop blocks:** for polling, retry and batch processing, with the condition in the label.
215
+ 5. **Opt blocks:** for conditional steps (feature flags, optional integrations).
216
+ 6. **Notes:** `Note over` for context that does not fit an arrow label.
217
+ 7. **Participant order:** left to right along the data flow — `User`, `Frontend`, `API`, backend, `Database`.
218
+ 8. **Label brevity:** arrow labels of 8 words or fewer, naming the action rather than the implementation detail.
219
+ 9. **Max participants:** 7 per diagram. Past that, split into sub-diagrams or collapse internal services.
220
+ 10. **Max steps:** 15 visible interactions per diagram. Past that, group related steps or use `rect` blocks.
248
221
 
249
- ### Grouping Related Steps
222
+ ### Grouping related steps
250
223
 
251
- For workflows with many sequential same-type operations, collapse them:
224
+ Collapse a run of same-type sequential operations into one `rect`:
252
225
 
253
226
  ```mermaid
254
227
  sequenceDiagram
@@ -259,13 +232,11 @@ sequenceDiagram
259
232
  end
260
233
  ```
261
234
 
262
- ---
263
-
264
- ## Phase 5: Output Assembly
235
+ ## Phase 5: Output assembly
265
236
 
266
- ### Output File Structure
237
+ ### Output file structure
267
238
 
268
- Write to the user-specified path, or default to `docs/architecture/workflows.md`. Before writing output files, ensure the target directory exists. Create it with `mkdir -p` if needed.
239
+ Write to the user-specified path, defaulting to `docs/architecture/workflows.md`; create the target directory if it is missing.
269
240
 
270
241
  ```markdown
271
242
  ---
@@ -333,99 +304,93 @@ Auto-generated workflow map. Traces execution paths from user action to terminal
333
304
  {...}
334
305
  ```
335
306
 
336
- ### Section Ordering
307
+ ### Section ordering
337
308
 
338
- 1. Orchestration (the core business logic — save, publish, deploy)
339
- 2. Authentication & Session
340
- 3. Real-time (WebSocket, SSE)
341
- 4. Event-driven (pub/sub, webhooks)
342
- 5. Scheduled (cron, recurring)
343
- 6. Data Pipeline (import/export, sync, migration)
309
+ Sections follow the template's order — Orchestration, Authentication & Session, Real-time, Event-driven, Scheduled, Data Pipeline. Skip an empty section.
344
310
 
345
- Skip empty sections.
311
+ ## Execution strategy
346
312
 
347
- ---
348
-
349
- ## Execution Strategy
313
+ ### Full discovery (default)
350
314
 
351
- ### Full Discovery (default)
315
+ 1. Launch 5 parallel sub-agents for Phase 1, one per technique.
316
+ 2. Collect their results and deduplicate the entry points.
317
+ 3. Launch parallel sub-agents for Phase 2, one per workflow, at most 8 concurrent.
318
+ 4. Run Phases 3–5 sequentially in the main agent.
352
319
 
353
- Launch 5 parallel sub-agents for Phase 1 (one per technique). Collect results, deduplicate entry points, then launch parallel sub-agents for Phase 2 (one per workflow, max 8 concurrent). Run Phase 3-5 sequentially in the main agent.
320
+ ### Targeted discovery
354
321
 
355
- ### Targeted Discovery
322
+ The user names a feature; skip the Phase 1 broad scan.
356
323
 
357
- User specifies a feature name. Skip broad Phase 1 scan. Instead:
324
+ 1. Find the feature's directories and files — grep for the feature name in routes, components and workflows.
325
+ 2. Trace from those entry points only.
326
+ 3. Write a single-feature workflow document.
358
327
 
359
- 1. Find the feature's directory/files (grep for feature name in routes, components, workflows)
360
- 2. Trace from those entry points only
361
- 3. Output a single-feature workflow document
328
+ ### Incremental update
362
329
 
363
- ### Incremental Update
330
+ 1. Read the existing workflow map.
331
+ 2. For each workflow it lists, check whether its key files changed (`git diff`).
332
+ 3. Re-trace only the changed workflows; keep unchanged sections as they are.
364
333
 
365
- Read the existing workflow map file. For each workflow listed, check if the key files have changed (git diff). Re-trace only changed workflows. Preserve unchanged sections.
366
-
367
- ---
334
+ ## Advanced techniques
368
335
 
369
- ## Advanced Techniques
336
+ ### Payload storage detection
370
337
 
371
- ### Payload Storage Detection
372
-
373
- Look for patterns where large payloads are stored separately and referenced by ID:
338
+ A large payload stored separately and referenced by ID:
374
339
 
375
340
  ```
376
341
  storePayload|savePayload|workflow_payload|jobData
377
342
  → then: retrievePayload|fetchPayload|getPayload (in the worker/activity)
378
343
  ```
379
344
 
380
- Note this in the diagram as a "Store payload → reference by ID" pattern.
345
+ Mark it in the diagram as a "Store payload → reference by ID" pattern.
381
346
 
382
- ### Optimistic Locking Detection
347
+ ### Optimistic locking detection
383
348
 
384
- Look for version comparison patterns:
349
+ Version comparisons:
385
350
 
386
351
  ```
387
352
  version.*!==|version.*conflict|StaleObjectError|OptimisticLock
388
353
  if.*serverVersion.*localVersion|if.*version.*mismatch
389
354
  ```
390
355
 
391
- These indicate conflict branching that should appear as `alt` blocks.
356
+ Each is a conflict branch — an `alt` block.
392
357
 
393
- ### Polling Loop Detection
358
+ ### Polling loop detection
394
359
 
395
- Look for patterns where the frontend waits for async completion:
360
+ The frontend waiting on async completion:
396
361
 
397
362
  ```
398
363
  setInterval|setTimeout.*recursive|poll|retry.*status
399
364
  GET.*status\?.*workflowId|GET.*status\?.*jobId
400
365
  ```
401
366
 
402
- Note the polling interval and timeout in the diagram.
367
+ Put the polling interval and timeout in the diagram.
403
368
 
404
- ### Child Workflow / Sub-job Detection
369
+ ### Child workflow / sub-job detection
405
370
 
406
- Look for spawned sub-processes:
371
+ Spawned sub-processes:
407
372
 
408
373
  ```
409
374
  startChild\(|spawnChild|fork\(|.add\(.*queue
410
375
  Promise\.all.*map.*startWorkflow
411
376
  ```
412
377
 
413
- These should appear as nested sequences or separate linked diagrams.
378
+ Draw them as nested sequences or separate linked diagrams.
414
379
 
415
- ### Transaction Boundary Detection
380
+ ### Transaction boundary detection
416
381
 
417
- Look for explicit transaction markers:
382
+ Explicit transaction markers:
418
383
 
419
384
  ```
420
385
  \$transaction|\$executeRaw|BEGIN|COMMIT|ROLLBACK
421
386
  withTransaction|runInTransaction|atomic
422
387
  ```
423
388
 
424
- Group operations within a transaction using `rect` blocks in the diagram.
389
+ Group the operations inside a transaction in a `rect` block.
425
390
 
426
- ### Rate Limiting & Middleware Detection
391
+ ### Rate limiting and middleware detection
427
392
 
428
- Look for middleware applied to route groups:
393
+ Middleware applied to route groups:
429
394
 
430
395
  ```
431
396
  rateLimit|rateLimiter|throttle
@@ -433,19 +398,17 @@ authenticate|authorize|requireAuth|requireRole
433
398
  validate|validateBody|validateParams
434
399
  ```
435
400
 
436
- Note these as guards in the diagram using `opt` blocks or notes.
437
-
438
- ---
401
+ Show each as a guard — an `opt` block or a note.
439
402
 
440
- ## Quality Checks
403
+ ## Quality checks
441
404
 
442
- Before outputting, verify:
405
+ Before writing the output, verify:
443
406
 
444
- - [ ] Every diagram has ≥3 participants (otherwise it's probably too simple to document)
407
+ - [ ] Every diagram has at least 3 participants — fewer is too simple to document
445
408
  - [ ] Every diagram has both request and response arrows (no dangling calls)
446
- - [ ] Participant names are consistent across all diagrams (same DB = same name everywhere)
447
- - [ ] Alt/opt/loop blocks have clear conditions written in the block label
448
- - [ ] Key files listed actually exist in the codebase (verify with glob)
449
- - [ ] No workflow is documented twice under different names
450
- - [ ] Mermaid syntax is valid (no unclosed blocks, balanced activate/deactivate)
451
- - [ ] Table of contents anchors match actual heading anchors
409
+ - [ ] Participant names match across all diagrams (the same DB carries the same name everywhere)
410
+ - [ ] Every `alt`/`opt`/`loop` block states its condition in the block label
411
+ - [ ] Every listed key file exists in the codebase (verify with glob)
412
+ - [ ] No workflow appears twice under different names
413
+ - [ ] Mermaid syntax is valid (no unclosed blocks, balanced `activate`/`deactivate`)
414
+ - [ ] Table of contents anchors match the actual heading anchors
@@ -1,12 +1,12 @@
1
- # Search Pattern Reference
1
+ # Search patterns
2
2
 
3
- Concrete grep/glob patterns for each discovery technique. Agents should adapt these to the actual framework detected in the codebase.
3
+ Load when: Phase 1 starts, or a targeted discovery searches for its feature's entry points.
4
4
 
5
- ---
5
+ Grep and glob patterns per discovery technique. Run framework detection first, then adapt each pattern to the stack it finds.
6
6
 
7
- ## Framework Detection (run first)
7
+ ---
8
8
 
9
- Identify the tech stack to select the right patterns:
9
+ ## Framework detection (run first)
10
10
 
11
11
  | Check | Pattern | Means |
12
12
  | --- | --- | --- |
@@ -22,7 +22,7 @@ Identify the tech stack to select the right patterns:
22
22
 
23
23
  ---
24
24
 
25
- ## Route Harvesting Patterns
25
+ ## Route harvesting
26
26
 
27
27
  ### Express
28
28
 
@@ -58,7 +58,7 @@ grep: (register|plugin).*routes
58
58
 
59
59
  ---
60
60
 
61
- ## Temporal Workflow Patterns
61
+ ## Temporal workflows
62
62
 
63
63
  ```
64
64
  # Workflow definitions
@@ -92,7 +92,7 @@ grep: continueAsNew\(
92
92
 
93
93
  ---
94
94
 
95
- ## BullMQ Patterns
95
+ ## BullMQ
96
96
 
97
97
  ```
98
98
  # Queue definitions
@@ -112,7 +112,7 @@ grep: \.process\(|processor:
112
112
 
113
113
  ---
114
114
 
115
- ## Redux / Frontend Action Patterns
115
+ ## Redux and frontend actions
116
116
 
117
117
  ```
118
118
  # Async thunks (dispatched actions that call APIs)
@@ -129,7 +129,7 @@ grep: dispatch\(.*Actions?\.|dispatch\(.*thunk
129
129
 
130
130
  ---
131
131
 
132
- ## WebSocket Patterns
132
+ ## WebSocket
133
133
 
134
134
  ```
135
135
  # Socket.IO server
@@ -146,7 +146,7 @@ grep: new WebSocket\(|ws\.on\(
146
146
 
147
147
  ---
148
148
 
149
- ## Database Patterns
149
+ ## Database
150
150
 
151
151
  ```
152
152
  # Prisma
@@ -163,7 +163,7 @@ grep: \.query\(|\.execute\(|BEGIN|COMMIT|ROLLBACK
163
163
 
164
164
  ---
165
165
 
166
- ## External Service Patterns
166
+ ## External services
167
167
 
168
168
  ```
169
169
  # Outbound HTTP (to other services)
@@ -183,16 +183,16 @@ grep: s3\.upload|s3\.putObject|uploadToS3|writeFile.*storage
183
183
 
184
184
  ---
185
185
 
186
- ## Workflow Complexity Indicators
186
+ ## Workflow complexity indicators
187
187
 
188
- Patterns that suggest a route is a real workflow (not simple CRUD):
188
+ Patterns marking a route as a real workflow rather than simple CRUD:
189
189
 
190
190
  ```
191
191
  # Async dispatch (work happens later)
192
192
  grep: startWorkflow\(|\.add\(.*queue|emit\(|publish\(
193
193
 
194
194
  # Multi-step (sequential calls)
195
- # Look for functions with 3+ await statements to different services
195
+ # Look for functions with 2+ sequential awaits to different services
196
196
 
197
197
  # Transaction blocks
198
198
  grep: \$transaction|\$executeRaw|BEGIN.*COMMIT|withTransaction
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "harness": "hr",
3
3
  "name": "hr",
4
- "version": "0.1.15",
4
+ "version": "0.1.16",
5
5
  "files": [
6
6
  ".prettierignore",
7
7
  ".prettierrc.json",
@@ -14,5 +14,5 @@
14
14
  "origin": "https://cdn.nustack.io",
15
15
  "track": "latest"
16
16
  },
17
- "digest": "fe37b9cbe966"
17
+ "digest": "1e97c1e90de1"
18
18
  }