@nurix/etna 0.20.36 → 0.20.37
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.
- package/data/catalog/skills/nustack/SKILL.md +2 -2
- package/data/catalog/skills/nustack/references/cli-design.md +35 -35
- package/data/catalog/skills/nustack/references/monorepo-master-list.md +6 -6
- package/data/catalog/skills/nustack/references/monorepo-setup.md +13 -13
- package/data/catalog/skills/nustack/references/publishing.md +40 -39
- package/data/harness-index.json +1 -1
- package/data/harnesses/code/harness.json +1 -1
- package/data/harnesses/code/skills/boundary/SKILL.md +33 -22
- package/data/harnesses/code/skills/boundary/references/index.md +2 -4
- package/data/harnesses/code/skills/boundary/references/mechanisms.md +3 -10
- package/data/harnesses/code/skills/boundary/references/packs/frontend.md +17 -17
- package/data/harnesses/code/skills/boundary/references/packs/generic-tail.md +1 -1
- package/data/harnesses/code/skills/brainstorm/README.md +11 -13
- package/data/harnesses/code/skills/brainstorm/SKILL.md +150 -132
- package/data/harnesses/code/skills/brainstorm/references/doctrine.md +48 -51
- package/data/harnesses/code/skills/brainstorm/references/harvest.md +51 -56
- package/data/harnesses/code/skills/brainstorm/references/session-schema.md +48 -42
- package/data/harnesses/code/skills/design/SKILL.md +31 -35
- package/data/harnesses/code/skills/design/data/iconography.md +2 -2
- package/data/harnesses/code/skills/design/references/compose.md +14 -16
- package/data/harnesses/code/skills/design/references/foundations.md +5 -5
- package/data/harnesses/code/skills/design/references/intake.md +6 -6
- package/data/harnesses/code/skills/design/references/object-pass.md +1 -1
- package/data/harnesses/code/skills/design/references/ship-gate.md +5 -5
- package/data/harnesses/code/skills/design/references/ux-patterns/Readme.md +4 -4
- package/data/harnesses/code/skills/design/references/ux-patterns/ai-layer.md +1 -1
- package/data/harnesses/code/skills/design/references/ux-patterns/container-choice.md +1 -1
- package/data/harnesses/code/skills/design/references/ux-patterns/dashboards.md +1 -1
- package/data/harnesses/code/skills/design/references/ux-patterns/modes.md +1 -1
- package/data/harnesses/code/skills/design/references/ux-patterns/object-model.md +2 -2
- package/data/harnesses/code/skills/design/references/ux-patterns/promotion-demotion.md +1 -1
- package/data/harnesses/code/skills/design/references/ux-patterns/settings.md +1 -1
- package/data/harnesses/code/skills/design/references/ux-patterns/standard-pages.md +1 -1
- package/data/harnesses/code/skills/documentation/SKILL.md +5 -5
- package/data/harnesses/code/skills/documentation/references/examples.md +22 -22
- package/data/harnesses/code/skills/documentation/references/frontmatter.md +3 -3
- package/data/harnesses/code/skills/documentation/references/instruction-style.md +3 -3
- package/data/harnesses/code/skills/documentation/references/source-comments.md +3 -3
- package/data/harnesses/code/skills/documentation/references/style-guide.md +5 -5
- package/data/harnesses/code/skills/documentation/references/untemplated.md +8 -8
- package/data/harnesses/code/skills/documentation/scripts/doc-lint.mjs +3 -2
- package/data/harnesses/code/skills/documentation/templates/Readme.md +1 -1
- package/data/harnesses/code/skills/documentation/templates/acceptance-criteria.md +1 -1
- package/data/harnesses/code/skills/documentation/templates/api-reference.md +1 -1
- package/data/harnesses/code/skills/documentation/templates/architecture-decision.md +3 -7
- package/data/harnesses/code/skills/documentation/templates/behavioral-checklist.md +1 -1
- package/data/harnesses/code/skills/documentation/templates/changelog-entry.md +1 -1
- package/data/harnesses/code/skills/documentation/templates/changelog-index.md +1 -1
- package/data/harnesses/code/skills/documentation/templates/docs-readme.md +3 -3
- package/data/harnesses/code/skills/documentation/templates/doctrine.md +1 -1
- package/data/harnesses/code/skills/documentation/templates/domain-model.md +1 -1
- package/data/harnesses/code/skills/documentation/templates/environment-registry.md +1 -1
- package/data/harnesses/code/skills/documentation/templates/feature.md +3 -3
- package/data/harnesses/code/skills/documentation/templates/handover.md +2 -2
- package/data/harnesses/code/skills/documentation/templates/implementation-map.md +1 -1
- package/data/harnesses/code/skills/documentation/templates/migration-runbook.md +1 -1
- package/data/harnesses/code/skills/documentation/templates/non-goals.md +1 -1
- package/data/harnesses/code/skills/documentation/templates/operations-procedure.md +2 -2
- package/data/harnesses/code/skills/documentation/templates/package.md +1 -1
- package/data/harnesses/code/skills/documentation/templates/protected-files.md +1 -1
- package/data/harnesses/code/skills/documentation/templates/root-readme.md +1 -1
- package/data/harnesses/code/skills/documentation/templates/security-overview.md +1 -1
- package/data/harnesses/code/skills/documentation/templates/system-overview.md +1 -1
- package/data/harnesses/code/skills/documentation/templates/system.md +1 -1
- package/data/harnesses/code/skills/documentation/templates/testing-strategy.md +1 -1
- package/data/harnesses/code/skills/documentation/templates/ux-behavior.md +3 -5
- package/data/harnesses/code/skills/issue-bridge/SKILL.md +51 -16
- package/data/harnesses/code/skills/issue-bridge/references/trackers/github.md +5 -5
- package/data/harnesses/code/skills/issue-bridge/references/trackers/jira.md +11 -8
- package/data/harnesses/code/skills/issue-bridge/references/trackers/linear.md +16 -11
- package/data/harnesses/code/skills/nustack-graph/SKILL.md +38 -29
- package/data/harnesses/code/skills/polygraph/references/dispatch.md +31 -18
- package/data/harnesses/code/skills/polygraph/references/rows.md +11 -6
- package/data/harnesses/code/skills/schema-design/SKILL.md +39 -41
- package/data/harnesses/code/skills/test/SKILL.md +38 -42
- package/data/harnesses/code/skills/testing/SKILL.md +83 -73
- package/data/harnesses/code/skills/workflow-mapper/SKILL.md +156 -193
- package/data/harnesses/code/skills/workflow-mapper/references/patterns.md +15 -15
- package/data/harnesses/delivery/harness.json +1 -1
- package/data/harnesses/delivery/skills/brainstorm/README.md +11 -13
- package/data/harnesses/delivery/skills/brainstorm/SKILL.md +150 -132
- package/data/harnesses/delivery/skills/brainstorm/references/doctrine.md +48 -51
- package/data/harnesses/delivery/skills/brainstorm/references/harvest.md +51 -56
- package/data/harnesses/delivery/skills/brainstorm/references/session-schema.md +48 -42
- package/data/harnesses/delivery/skills/cost-report/SKILL.md +10 -10
- package/data/harnesses/delivery/skills/documentation/SKILL.md +5 -5
- package/data/harnesses/delivery/skills/documentation/references/examples.md +22 -22
- package/data/harnesses/delivery/skills/documentation/references/frontmatter.md +3 -3
- package/data/harnesses/delivery/skills/documentation/references/instruction-style.md +3 -3
- package/data/harnesses/delivery/skills/documentation/references/source-comments.md +3 -3
- package/data/harnesses/delivery/skills/documentation/references/style-guide.md +5 -5
- package/data/harnesses/delivery/skills/documentation/references/untemplated.md +8 -8
- package/data/harnesses/delivery/skills/documentation/scripts/doc-lint.mjs +3 -2
- package/data/harnesses/delivery/skills/documentation/templates/Readme.md +1 -1
- package/data/harnesses/delivery/skills/documentation/templates/acceptance-criteria.md +1 -1
- package/data/harnesses/delivery/skills/documentation/templates/api-reference.md +1 -1
- package/data/harnesses/delivery/skills/documentation/templates/architecture-decision.md +3 -7
- package/data/harnesses/delivery/skills/documentation/templates/behavioral-checklist.md +1 -1
- package/data/harnesses/delivery/skills/documentation/templates/changelog-entry.md +1 -1
- package/data/harnesses/delivery/skills/documentation/templates/changelog-index.md +1 -1
- package/data/harnesses/delivery/skills/documentation/templates/docs-readme.md +3 -3
- package/data/harnesses/delivery/skills/documentation/templates/doctrine.md +1 -1
- package/data/harnesses/delivery/skills/documentation/templates/domain-model.md +1 -1
- package/data/harnesses/delivery/skills/documentation/templates/environment-registry.md +1 -1
- package/data/harnesses/delivery/skills/documentation/templates/feature.md +3 -3
- package/data/harnesses/delivery/skills/documentation/templates/handover.md +2 -2
- package/data/harnesses/delivery/skills/documentation/templates/implementation-map.md +1 -1
- package/data/harnesses/delivery/skills/documentation/templates/migration-runbook.md +1 -1
- package/data/harnesses/delivery/skills/documentation/templates/non-goals.md +1 -1
- package/data/harnesses/delivery/skills/documentation/templates/operations-procedure.md +2 -2
- package/data/harnesses/delivery/skills/documentation/templates/package.md +1 -1
- package/data/harnesses/delivery/skills/documentation/templates/protected-files.md +1 -1
- package/data/harnesses/delivery/skills/documentation/templates/root-readme.md +1 -1
- package/data/harnesses/delivery/skills/documentation/templates/security-overview.md +1 -1
- package/data/harnesses/delivery/skills/documentation/templates/system-overview.md +1 -1
- package/data/harnesses/delivery/skills/documentation/templates/system.md +1 -1
- package/data/harnesses/delivery/skills/documentation/templates/testing-strategy.md +1 -1
- package/data/harnesses/delivery/skills/documentation/templates/ux-behavior.md +3 -5
- package/data/harnesses/delivery/skills/escalate/SKILL.md +11 -11
- package/data/harnesses/delivery/skills/prompt-eval/SKILL.md +8 -8
- package/data/harnesses/delivery/skills/prompt-library/SKILL.md +30 -9
- package/data/harnesses/delivery/skills/route/SKILL.md +8 -8
- package/data/harnesses/etna/harness.json +1 -1
- package/data/harnesses/etna/skills/boundary/SKILL.md +33 -22
- package/data/harnesses/etna/skills/boundary/references/index.md +2 -4
- package/data/harnesses/etna/skills/boundary/references/mechanisms.md +3 -10
- package/data/harnesses/etna/skills/boundary/references/packs/frontend.md +17 -17
- package/data/harnesses/etna/skills/boundary/references/packs/generic-tail.md +1 -1
- package/data/harnesses/etna/skills/brainstorm/README.md +11 -13
- package/data/harnesses/etna/skills/brainstorm/SKILL.md +150 -132
- package/data/harnesses/etna/skills/brainstorm/references/doctrine.md +48 -51
- package/data/harnesses/etna/skills/brainstorm/references/harvest.md +51 -56
- package/data/harnesses/etna/skills/brainstorm/references/session-schema.md +48 -42
- package/data/harnesses/etna/skills/documentation/SKILL.md +5 -5
- package/data/harnesses/etna/skills/documentation/references/examples.md +22 -22
- package/data/harnesses/etna/skills/documentation/references/frontmatter.md +3 -3
- package/data/harnesses/etna/skills/documentation/references/instruction-style.md +3 -3
- package/data/harnesses/etna/skills/documentation/references/source-comments.md +3 -3
- package/data/harnesses/etna/skills/documentation/references/style-guide.md +5 -5
- package/data/harnesses/etna/skills/documentation/references/untemplated.md +8 -8
- package/data/harnesses/etna/skills/documentation/scripts/doc-lint.mjs +3 -2
- package/data/harnesses/etna/skills/documentation/templates/Readme.md +1 -1
- package/data/harnesses/etna/skills/documentation/templates/acceptance-criteria.md +1 -1
- package/data/harnesses/etna/skills/documentation/templates/api-reference.md +1 -1
- package/data/harnesses/etna/skills/documentation/templates/architecture-decision.md +3 -7
- package/data/harnesses/etna/skills/documentation/templates/behavioral-checklist.md +1 -1
- package/data/harnesses/etna/skills/documentation/templates/changelog-entry.md +1 -1
- package/data/harnesses/etna/skills/documentation/templates/changelog-index.md +1 -1
- package/data/harnesses/etna/skills/documentation/templates/docs-readme.md +3 -3
- package/data/harnesses/etna/skills/documentation/templates/doctrine.md +1 -1
- package/data/harnesses/etna/skills/documentation/templates/domain-model.md +1 -1
- package/data/harnesses/etna/skills/documentation/templates/environment-registry.md +1 -1
- package/data/harnesses/etna/skills/documentation/templates/feature.md +3 -3
- package/data/harnesses/etna/skills/documentation/templates/handover.md +2 -2
- package/data/harnesses/etna/skills/documentation/templates/implementation-map.md +1 -1
- package/data/harnesses/etna/skills/documentation/templates/migration-runbook.md +1 -1
- package/data/harnesses/etna/skills/documentation/templates/non-goals.md +1 -1
- package/data/harnesses/etna/skills/documentation/templates/operations-procedure.md +2 -2
- package/data/harnesses/etna/skills/documentation/templates/package.md +1 -1
- package/data/harnesses/etna/skills/documentation/templates/protected-files.md +1 -1
- package/data/harnesses/etna/skills/documentation/templates/root-readme.md +1 -1
- package/data/harnesses/etna/skills/documentation/templates/security-overview.md +1 -1
- package/data/harnesses/etna/skills/documentation/templates/system-overview.md +1 -1
- package/data/harnesses/etna/skills/documentation/templates/system.md +1 -1
- package/data/harnesses/etna/skills/documentation/templates/testing-strategy.md +1 -1
- package/data/harnesses/etna/skills/documentation/templates/ux-behavior.md +3 -5
- package/data/harnesses/etna/skills/workflow-mapper/SKILL.md +156 -193
- package/data/harnesses/etna/skills/workflow-mapper/references/patterns.md +15 -15
- package/data/harnesses/hr/harness.json +1 -1
- package/data/harnesses/hr/skills/evaluator/SKILL.md +71 -73
- package/data/harnesses/hr/skills/evaluator/criteria/code-quality.md +28 -47
- package/data/harnesses/hr/skills/evaluator/criteria/deployment-readiness.md +33 -43
- package/data/harnesses/hr/skills/evaluator/criteria/maintainability.md +34 -46
- package/data/harnesses/hr/skills/evaluator/criteria/mechanical-ambition.md +13 -13
- package/data/harnesses/hr/skills/evaluator/criteria/problem-substantiveness.md +7 -7
- package/data/harnesses/hr/skills/evaluator/criteria/testing.md +36 -41
- package/data/harnesses/hr/skills/evaluator/criteria/ux-mechanics.md +25 -11
- package/data/harnesses/hr/skills/evaluator/criteria/value-articulation.md +7 -7
- package/data/harnesses/hr/skills/evaluator/preflight.md +27 -46
- package/data/harnesses/hr/skills/interview-eval/SKILL.md +37 -42
- package/data/harnesses/hr/skills/interview-eval/rubric.md +21 -23
- 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
|
|
6
|
+
# Workflow mapper
|
|
7
7
|
|
|
8
|
-
|
|
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
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
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
|
|
21
|
+
## Phase 1: Entry point discovery
|
|
29
22
|
|
|
30
|
-
Find
|
|
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
|
|
25
|
+
### Technique 1: Route harvesting
|
|
33
26
|
|
|
34
|
-
|
|
27
|
+
API route definitions are the primary backend entry points.
|
|
35
28
|
|
|
36
29
|
```
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
56
|
-
|
|
57
|
-
Find all registered background jobs, workflows, and queues.
|
|
47
|
+
Find every registered background job, workflow and queue.
|
|
58
48
|
|
|
59
49
|
```
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
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
|
|
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
|
|
60
|
+
### Technique 3: Frontend action tracing
|
|
75
61
|
|
|
76
62
|
Find UI-initiated multi-step flows.
|
|
77
63
|
|
|
78
64
|
```
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
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
|
-
|
|
71
|
+
Keep actions that:
|
|
87
72
|
|
|
88
|
-
- POST
|
|
89
|
-
-
|
|
90
|
-
-
|
|
91
|
-
-
|
|
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
|
|
78
|
+
### Technique 4: Event and message tracing
|
|
94
79
|
|
|
95
80
|
Find event-driven workflows (WebSocket, pub/sub, SSE).
|
|
96
81
|
|
|
97
82
|
```
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
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
|
|
89
|
+
### Technique 5: Scheduled and lifecycle workflows
|
|
106
90
|
|
|
107
91
|
```
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
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
|
-
|
|
100
|
+
Trace each entry point's full execution path, one sub-agent per workflow.
|
|
120
101
|
|
|
121
|
-
### Tracing
|
|
102
|
+
### Tracing algorithm
|
|
122
103
|
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
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
|
|
117
|
+
### Participant identification
|
|
140
118
|
|
|
141
|
-
|
|
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
|
|
134
|
+
### Branching detection
|
|
159
135
|
|
|
160
|
-
|
|
136
|
+
Draw a block only for conditional logic that forks the workflow:
|
|
161
137
|
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
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
|
|
148
|
+
## Phase 3: Classification and filtering
|
|
175
149
|
|
|
176
|
-
Not every
|
|
150
|
+
Not every route is a workflow.
|
|
177
151
|
|
|
178
|
-
### Workflow
|
|
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
|
|
166
|
+
### Complexity scoring
|
|
193
167
|
|
|
194
|
-
|
|
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
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
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
|
-
|
|
176
|
+
Async behaviour — polling, callbacks, child workflows — raises the score one level.
|
|
202
177
|
|
|
203
|
-
|
|
178
|
+
## Phase 4: Mermaid diagram generation
|
|
204
179
|
|
|
205
|
-
|
|
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
|
|
209
|
+
### Diagram rules
|
|
237
210
|
|
|
238
|
-
1. **Arrow types
|
|
239
|
-
2. **Activation bars
|
|
240
|
-
3. **Alt blocks
|
|
241
|
-
4. **Loop blocks
|
|
242
|
-
5. **Opt blocks
|
|
243
|
-
6. **Notes
|
|
244
|
-
7. **Participant order
|
|
245
|
-
8. **Label brevity
|
|
246
|
-
9. **Max participants
|
|
247
|
-
10. **Max steps
|
|
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
|
|
222
|
+
### Grouping related steps
|
|
250
223
|
|
|
251
|
-
|
|
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
|
|
237
|
+
### Output file structure
|
|
267
238
|
|
|
268
|
-
Write to the user-specified path,
|
|
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
|
|
307
|
+
### Section ordering
|
|
337
308
|
|
|
338
|
-
|
|
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
|
-
|
|
311
|
+
## Execution strategy
|
|
346
312
|
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
## Execution Strategy
|
|
313
|
+
### Full discovery (default)
|
|
350
314
|
|
|
351
|
-
|
|
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
|
-
|
|
320
|
+
### Targeted discovery
|
|
354
321
|
|
|
355
|
-
|
|
322
|
+
The user names a feature; skip the Phase 1 broad scan.
|
|
356
323
|
|
|
357
|
-
|
|
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
|
-
|
|
360
|
-
2. Trace from those entry points only
|
|
361
|
-
3. Output a single-feature workflow document
|
|
328
|
+
### Incremental update
|
|
362
329
|
|
|
363
|
-
|
|
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
|
-
|
|
366
|
-
|
|
367
|
-
---
|
|
334
|
+
## Advanced techniques
|
|
368
335
|
|
|
369
|
-
|
|
336
|
+
### Payload storage detection
|
|
370
337
|
|
|
371
|
-
|
|
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
|
-
|
|
345
|
+
Mark it in the diagram as a "Store payload → reference by ID" pattern.
|
|
381
346
|
|
|
382
|
-
### Optimistic
|
|
347
|
+
### Optimistic locking detection
|
|
383
348
|
|
|
384
|
-
|
|
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
|
-
|
|
356
|
+
Each is a conflict branch — an `alt` block.
|
|
392
357
|
|
|
393
|
-
### Polling
|
|
358
|
+
### Polling loop detection
|
|
394
359
|
|
|
395
|
-
|
|
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
|
-
|
|
367
|
+
Put the polling interval and timeout in the diagram.
|
|
403
368
|
|
|
404
|
-
### Child
|
|
369
|
+
### Child workflow / sub-job detection
|
|
405
370
|
|
|
406
|
-
|
|
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
|
-
|
|
378
|
+
Draw them as nested sequences or separate linked diagrams.
|
|
414
379
|
|
|
415
|
-
### Transaction
|
|
380
|
+
### Transaction boundary detection
|
|
416
381
|
|
|
417
|
-
|
|
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
|
|
389
|
+
Group the operations inside a transaction in a `rect` block.
|
|
425
390
|
|
|
426
|
-
### Rate
|
|
391
|
+
### Rate limiting and middleware detection
|
|
427
392
|
|
|
428
|
-
|
|
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
|
-
|
|
437
|
-
|
|
438
|
-
---
|
|
401
|
+
Show each as a guard — an `opt` block or a note.
|
|
439
402
|
|
|
440
|
-
## Quality
|
|
403
|
+
## Quality checks
|
|
441
404
|
|
|
442
|
-
Before
|
|
405
|
+
Before writing the output, verify:
|
|
443
406
|
|
|
444
|
-
- [ ] Every diagram has
|
|
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
|
|
447
|
-
- [ ]
|
|
448
|
-
- [ ]
|
|
449
|
-
- [ ] No workflow
|
|
450
|
-
- [ ] Mermaid syntax is valid (no unclosed blocks, balanced activate
|
|
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
|
|
1
|
+
# Search patterns
|
|
2
2
|
|
|
3
|
-
|
|
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
|
-
|
|
7
|
+
---
|
|
8
8
|
|
|
9
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
186
|
+
## Workflow complexity indicators
|
|
187
187
|
|
|
188
|
-
Patterns
|
|
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
|
|
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
|