@codyswann/lisa 1.91.1 → 1.93.0
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/package.json +1 -1
- package/plugins/lisa/.claude-plugin/plugin.json +1 -1
- package/plugins/lisa/skills/jira-create/SKILL.md +28 -0
- package/plugins/lisa/skills/jira-write-ticket/SKILL.md +22 -0
- package/plugins/lisa/skills/notion-to-jira/SKILL.md +105 -0
- package/plugins/lisa-cdk/.claude-plugin/plugin.json +1 -1
- package/plugins/lisa-expo/.claude-plugin/plugin.json +1 -1
- package/plugins/lisa-expo/skills/jira-create/SKILL.md +28 -0
- package/plugins/lisa-nestjs/.claude-plugin/plugin.json +1 -1
- package/plugins/lisa-rails/.claude-plugin/plugin.json +1 -1
- package/plugins/lisa-rails/skills/jira-create/SKILL.md +28 -0
- package/plugins/lisa-typescript/.claude-plugin/plugin.json +1 -1
- package/plugins/src/base/skills/jira-create/SKILL.md +28 -0
- package/plugins/src/base/skills/jira-write-ticket/SKILL.md +22 -0
- package/plugins/src/base/skills/notion-to-jira/SKILL.md +105 -0
- package/plugins/src/expo/skills/jira-create/SKILL.md +28 -0
- package/plugins/src/rails/skills/jira-create/SKILL.md +28 -0
- package/typescript/copy-contents/.husky/pre-push +14 -0
- package/typescript/copy-overwrite/audit.ignore.config.json +20 -0
- package/typescript/create-only/.husky/pre-push.local +17 -0
package/package.json
CHANGED
|
@@ -78,7 +78,7 @@
|
|
|
78
78
|
"lodash": ">=4.18.1"
|
|
79
79
|
},
|
|
80
80
|
"name": "@codyswann/lisa",
|
|
81
|
-
"version": "1.
|
|
81
|
+
"version": "1.93.0",
|
|
82
82
|
"description": "Claude Code governance framework that applies guardrails, guidance, and automated enforcement to projects",
|
|
83
83
|
"main": "dist/index.js",
|
|
84
84
|
"exports": {
|
|
@@ -81,6 +81,34 @@ h3. Assertions
|
|
|
81
81
|
4. **Assertions are testable statements** — "Health check returns 200 with status ok" not "API works"
|
|
82
82
|
5. **Prerequisites include environment setup** — Database connection, env vars, running services
|
|
83
83
|
|
|
84
|
+
## Source Artifact Preservation
|
|
85
|
+
|
|
86
|
+
If $ARGUMENTS includes a PRD, design doc, Figma URL, Lovable prototype, or similar external artifact — or if a referenced file links out to one — those references MUST be preserved as remote links on the created tickets. Dropping source artifacts during ticket creation is the single most common quality failure in this pipeline, because developers picking up a ticket then lose the design/UX source of truth.
|
|
87
|
+
|
|
88
|
+
Rules:
|
|
89
|
+
|
|
90
|
+
1. **Extract before creating**: enumerate every external URL, embed, attachment, or example payload in the input. Classify by domain (`ui-design`, `ux-flow`, `data`, `ops`, `reference`) — see `notion-to-jira` Phase 1.5 for the canonical taxonomy.
|
|
91
|
+
2. **Epic gets everything**: attach all extracted artifacts as remote links on the epic, regardless of domain.
|
|
92
|
+
3. **Stories inherit by domain**: frontend stories get `ui-design` + `ux-flow` + `reference`; backend gets `data` + `reference`; infra gets `ops` + `reference`. When ambiguous, err on the side of inclusion.
|
|
93
|
+
4. **Sub-tasks inherit via parent**: do not re-attach on every sub-task unless a specific artifact applies only to that sub-task.
|
|
94
|
+
5. **Verify before reporting**: before declaring done, confirm every extracted artifact is reachable from the tickets. If any are missing, fail loudly and surface the dropped list to the human — do not silently drop.
|
|
95
|
+
|
|
96
|
+
When delegating actual writes to `jira-write-ticket`, pass the extracted artifact list so its Phase 4c (Remote Links) step can attach them.
|
|
97
|
+
|
|
98
|
+
**Classification disambiguation** (applied during extraction):
|
|
99
|
+
- Figma URL with `/proto/` or `starting-point-node-id=` → `ux-flow`; plain design frame URL → `ui-design`.
|
|
100
|
+
- Lovable output → always `ux-flow` (its code/styling/logic is NOT authoritative).
|
|
101
|
+
- Loom / annotated screenshot with flow arrows → `ux-flow`; bare screenshot → `ui-design`.
|
|
102
|
+
|
|
103
|
+
**Source precedence** (must be recorded on every ticket carrying design artifacts):
|
|
104
|
+
- Business rules (fields, validation, permissions, constraints) come from the **description / PRD body**.
|
|
105
|
+
- Visual treatment (layout, spacing, typography, color) comes from **mocks** (`ui-design`).
|
|
106
|
+
- Flow and interaction (navigation, transitions, state changes) come from **prototypes** (`ux-flow`).
|
|
107
|
+
- API / data shape comes from **`data` artifacts**.
|
|
108
|
+
- Cross-axis conflicts are surfaced as `## Open Questions` BLOCKERs, never silently reconciled.
|
|
109
|
+
|
|
110
|
+
**Existing-component reuse** (applies to every UI-touching ticket): the story description must instruct the implementer to locate the closest existing component in the codebase and prefer reuse over pixel-matching a mock. Design-vs-code divergence is raised on the ticket, not resolved by the implementer alone.
|
|
111
|
+
|
|
84
112
|
## Issue Requirements
|
|
85
113
|
|
|
86
114
|
Each issue must clearly communicate to:
|
|
@@ -124,6 +124,28 @@ Identify and attach:
|
|
|
124
124
|
- Confluence pages (design docs, RFCs, runbooks)
|
|
125
125
|
- Dashboards (Grafana, Datadog, Sentry issue)
|
|
126
126
|
- Incident tickets (PagerDuty, Statuspage)
|
|
127
|
+
- **Source artifacts from the originating PRD / parent epic**: Figma files, Lovable prototypes, Loom walkthroughs, design mockups, example payloads, Google Docs/Slides, collaborative whiteboards. If this ticket has a parent epic, enumerate the epic's remote links and inherit the ones whose domain matches this ticket's scope (UI → `ui-design` + `ux-flow`; backend → `data`; infra → `ops`; always inherit generic `reference` links). Never assume a developer will walk up to the epic to find design context — attach it here.
|
|
128
|
+
|
|
129
|
+
Domain disambiguation (applied on inheritance):
|
|
130
|
+
- Figma URL with `/proto/` in path or `starting-point-node-id=` in query → `ux-flow`; otherwise `ui-design`.
|
|
131
|
+
- Lovable output → always `ux-flow`; its code/styling is not authoritative.
|
|
132
|
+
- Loom / annotated screenshot → `ux-flow`.
|
|
133
|
+
- Bare screenshot → `ui-design`.
|
|
134
|
+
|
|
135
|
+
If the ticket was generated from a PRD (by `notion-to-jira` or similar) and the parent epic has no source artifacts, surface that as a smell and ask whether artifacts were missed during extraction before proceeding.
|
|
136
|
+
|
|
137
|
+
### 4d. Source Precedence (must appear on the ticket)
|
|
138
|
+
|
|
139
|
+
When a ticket carries both design artifacts and a description, different sources are authoritative for different questions. Record this precedence explicitly in the ticket description (under Technical Approach or a dedicated `## Source Precedence` subsection) so the implementer doesn't silently reconcile conflicts:
|
|
140
|
+
|
|
141
|
+
- **Business rules** (required fields, validation, permissions, data constraints, edge cases) → the **description / PRD body** wins.
|
|
142
|
+
- **Visual treatment** (layout, spacing, typography, color, iconography) → **mocks (`ui-design`)** win.
|
|
143
|
+
- **Flow and interaction** (navigation, transitions, state changes, timing, empty/error/loading states) → **prototypes (`ux-flow`)** win.
|
|
144
|
+
- **API / data shape** → **`data` artifacts** win.
|
|
145
|
+
|
|
146
|
+
Cross-axis conflicts (mock shows a field the PRD doesn't mention; prototype shows a flow the PRD contradicts; two Figma links disagree) must be raised as BLOCKER items in an `## Open Questions` section on the ticket — never silently reconciled.
|
|
147
|
+
|
|
148
|
+
For UI-touching tickets, additionally include the reuse expectation: "Before implementing, identify the closest existing component in the codebase. Prefer reuse even if the mock specifies different styling; raise design-vs-code divergence as a discussion item here rather than pixel-matching from scratch."
|
|
127
149
|
|
|
128
150
|
Use Jira's web UI or `mcp__atlassian__editJiraIssue` to set the `Development` field / remote links where supported.
|
|
129
151
|
|
|
@@ -53,6 +53,76 @@ Do not retrieve credentials from repository files or local agent settings.
|
|
|
53
53
|
- Engineering comments (prefixed with "Engineering:" or wrench emoji) that identify technical constraints
|
|
54
54
|
- Cross-PRD dependencies (references to other features or shared infrastructure)
|
|
55
55
|
|
|
56
|
+
### Phase 1.5: Extract Source Artifacts
|
|
57
|
+
|
|
58
|
+
PRDs typically reference external design, UX, and data artifacts (Figma files, Lovable prototypes, Loom walkthroughs, screenshots, example payloads, Confluence pages). These MUST be preserved onto the resulting tickets — otherwise developers picking up a ticket lose the source of truth. This is the failure mode this step exists to prevent.
|
|
59
|
+
|
|
60
|
+
1. **Scan the PRD main page, all Epic sub-pages, and every fetched comment thread** for:
|
|
61
|
+
- URLs to design/prototype tools (Figma, FigJam, Figma Make, Lovable, Framer, Penpot)
|
|
62
|
+
- URLs to recording/walkthrough tools (Loom, YouTube, Vimeo, Descript)
|
|
63
|
+
- URLs to collaborative docs (Google Docs/Slides/Sheets, Confluence, Notion peer pages)
|
|
64
|
+
- URLs to code sandboxes (CodeSandbox, StackBlitz, Replit, GitHub permalinks/gists)
|
|
65
|
+
- URLs to diagramming tools (Miro, Mural, Excalidraw, Mermaid Live, draw.io, Lucid)
|
|
66
|
+
- URLs to data/observability tools (Grafana, Datadog, Sentry, Metabase, Looker)
|
|
67
|
+
- Embedded images and file attachments on the page itself
|
|
68
|
+
- Fenced code blocks with example data (JSON, SQL, GraphQL, cURL request/response)
|
|
69
|
+
|
|
70
|
+
2. **Classify each artifact by domain**. The split matters — each domain is the source of truth for different implementation decisions:
|
|
71
|
+
|
|
72
|
+
| Domain | What it defines | Examples |
|
|
73
|
+
|--------|-----------------|----------|
|
|
74
|
+
| `ui-design` (mocks) | **Visual treatment only** — layout, spacing, typography, color, iconography | Figma design frames, Framer static frames, bare screenshots, mockup PNGs |
|
|
75
|
+
| `ux-flow` (prototypes) | **Interaction and flow only** — navigation, transitions, state changes, timing, empty/error/loading states | Lovable output, Loom walkthroughs, Figma prototype links, annotated screenshots, Miro/Mural flow diagrams, user journey maps |
|
|
76
|
+
| `data` | Request/response shape, schema constraints | Example JSON, SQL schemas, GraphQL snippets, API contracts |
|
|
77
|
+
| `ops` | Deployment/runtime context | Runbooks, dashboards, Terraform refs, deployment diagrams |
|
|
78
|
+
| `reference` | Cross-cutting context | Confluence, Notion peer pages, Google Docs, related PRDs |
|
|
79
|
+
|
|
80
|
+
3. **Apply disambiguation rules** when an artifact could fit multiple domains. These rules exist because agents consistently misclassify Figma and Lovable artifacts, which are the two most common sources of dropped context.
|
|
81
|
+
|
|
82
|
+
- **Figma URL**: classify as `ux-flow` if the URL is a prototype share link — it contains `/proto/`, or has `starting-point-node-id=` in the query, or the sharing context labels it "prototype" / "play mode". Otherwise classify as `ui-design`. Never assume.
|
|
83
|
+
- **Lovable output**: always `ux-flow`. Lovable ships working code, but its code, styling, and any embedded business rules are NOT authoritative. Treat Lovable strictly as a UX/flow reference. Implementation uses existing project components; business rules come from the PRD description, not from Lovable.
|
|
84
|
+
- **Screenshot with annotations** (arrows between frames, flow labels, numbered steps): `ux-flow`. A bare unannotated screenshot: `ui-design`. A side-by-side gallery of state variants (empty/error/loading): `ui-design` with state variants noted.
|
|
85
|
+
- **Loom / video walkthrough**: `ux-flow` in the vast majority of cases. The rare exception — a video that's only a static-frame design review with no interaction — is still `ux-flow` for routing purposes (both UX and UI stories benefit from it).
|
|
86
|
+
- **Figma file with both design frames and a prototype**: emit two entries — one `ui-design` for the file, one `ux-flow` for the prototype URL — so both propagate correctly.
|
|
87
|
+
|
|
88
|
+
4. **Build an `artifacts` map** keyed by domain. Each entry: `{ url, title, domain, source_page, source_page_url, classification_reason }`. The `classification_reason` makes disambiguation auditable ("Figma URL contains `/proto/` → ux-flow"). The `source_page` lets you trace each reference back to where it appeared in the PRD.
|
|
89
|
+
|
|
90
|
+
5. **Surface coverage smells** — incomplete artifact sets are a common root cause of implementation drift:
|
|
91
|
+
- **Zero artifacts** on a non-trivial PRD: almost always an extraction bug, not a design decision. Say so explicitly.
|
|
92
|
+
- **Prototype but no mock** (`ux-flow` present, `ui-design` absent): flag "missing UI mocks". UI will have to be inferred from prototype frames — note that prototype styling is typically placeholder and must NOT be treated as visual source of truth. Record the smell on the epic.
|
|
93
|
+
- **Mocks but no prototype** (`ui-design` present, `ux-flow` absent): flag "missing UX prototype". UX will have to be inferred from static mock states (empty/error/loading/hover) — any flow that isn't explicitly depicted in the mocks must be raised as a BLOCKER with recommendation + alternatives, not silently invented.
|
|
94
|
+
- **Lovable output without a description covering business rules**: flag "business rules missing". Lovable's embedded logic is not authoritative; the PRD description must explicitly state required fields, validation, permissions, and edge cases.
|
|
95
|
+
|
|
96
|
+
### Phase 1.6: Source Precedence & Conflict Resolution
|
|
97
|
+
|
|
98
|
+
Different artifact domains answer different questions. When they disagree, silent reconciliation is a known failure mode — these rules must be encoded on the tickets and respected during implementation.
|
|
99
|
+
|
|
100
|
+
**Authoritative source by question**:
|
|
101
|
+
|
|
102
|
+
| Question | Authoritative source |
|
|
103
|
+
|----------|---------------------|
|
|
104
|
+
| Does this field exist? Is it required? Who can see/edit it? What validation applies? What are the edge cases, permission rules, data constraints? | **Description / PRD body** (business rules) |
|
|
105
|
+
| What does it look like — layout, spacing, typography, color, iconography? | **Mocks (`ui-design`)** |
|
|
106
|
+
| How does it flow — navigation, transitions, state changes, timing, empty/error/loading states? | **Prototypes (`ux-flow`)** |
|
|
107
|
+
| Where does the data come from, what shape is it, what are the API contracts? | **`data` artifacts** |
|
|
108
|
+
|
|
109
|
+
**Cross-axis conflicts must be surfaced, not reconciled silently**:
|
|
110
|
+
|
|
111
|
+
- Mock shows a field the description doesn't mention → BLOCKER on the story: "Figma shows field `X` not in PRD; confirm it exists, and if so add business rules (required/optional, validation)."
|
|
112
|
+
- Description mandates behavior the prototype contradicts → BLOCKER: "PRD says Y, prototype shows Z; which is correct?"
|
|
113
|
+
- Prototype shows a flow the mocks don't cover (e.g., an error state) → Note on the story: "Error state flow from prototype; no mock exists for the error UI. Use existing error component or request mock."
|
|
114
|
+
- Multiple artifacts of the same domain disagree (e.g., two Figma links showing different layouts) → BLOCKER: list both, ask which is current.
|
|
115
|
+
|
|
116
|
+
Record every conflict on the ticket description under a `## Open Questions` subsection so the developer picking up the ticket sees it before writing code.
|
|
117
|
+
|
|
118
|
+
**Existing-component reuse (applies to `ui-design` consumers)**:
|
|
119
|
+
|
|
120
|
+
Mocks define *visual intent*, not *implementation shortcut*. Before a developer builds UI from a mock, they must search the codebase for the closest-matching existing component. Encode this expectation on every UI-touching story:
|
|
121
|
+
|
|
122
|
+
- Story description includes: "Before implementing, identify the closest existing component in the codebase. Prefer reuse even if the Figma mock specifies different styling — flag the design-vs-code divergence as a discussion point on this ticket rather than pixel-matching Figma from scratch."
|
|
123
|
+
- If no existing component fits, building a new one is an explicit decision that must be recorded in the ticket (with rationale) before implementation.
|
|
124
|
+
- Lovable-generated components are never the reuse target — always use the project's own components.
|
|
125
|
+
|
|
56
126
|
### Phase 2: Codebase Research (if needed)
|
|
57
127
|
|
|
58
128
|
If the session doesn't already have codebase context, explore the repos to understand what exists.
|
|
@@ -72,9 +142,12 @@ Create one Epic per PRD epic using the JIRA project key from config. Each Epic d
|
|
|
72
142
|
- Key decisions from comments (with attribution)
|
|
73
143
|
- Blockers and open questions
|
|
74
144
|
- Dependencies on other epics or PRDs
|
|
145
|
+
- A **Source Artifacts** section listing every artifact extracted in Phase 1.5 (grouped by domain)
|
|
75
146
|
|
|
76
147
|
Use `contentFormat: "markdown"` for all descriptions.
|
|
77
148
|
|
|
149
|
+
**Attach every artifact from Phase 1.5 as an Epic remote link** — regardless of domain. The epic is the canonical hub, and anyone working on the epic or its descendants must be able to reach the full set from one place. No filtering at the epic level.
|
|
150
|
+
|
|
78
151
|
### Phase 4: Create Stories
|
|
79
152
|
|
|
80
153
|
For each Epic, create Stories:
|
|
@@ -91,9 +164,21 @@ Each story description should include:
|
|
|
91
164
|
- Acceptance criteria (from functional requirements)
|
|
92
165
|
- Technical notes from engineering comments
|
|
93
166
|
- Blockers with recommendation + alternatives (if any)
|
|
167
|
+
- A **Source Artifacts** section listing the artifacts inherited from the epic that match this story's scope (see propagation rules below)
|
|
94
168
|
|
|
95
169
|
Set `parent` to the Epic key to link stories to their epic.
|
|
96
170
|
|
|
171
|
+
**Inherit domain-matching artifacts as story remote links**. For each story, attach the Phase 1.5 artifacts whose domain matches the story's scope:
|
|
172
|
+
|
|
173
|
+
| Story type | Inherits domains |
|
|
174
|
+
|------------|------------------|
|
|
175
|
+
| Frontend / UI | `ui-design`, `ux-flow`, `reference` |
|
|
176
|
+
| Backend / API / data model | `data`, `reference` |
|
|
177
|
+
| Infrastructure | `ops`, `reference` |
|
|
178
|
+
| Mixed / setup ("X.0") | All domains |
|
|
179
|
+
|
|
180
|
+
When classification is ambiguous, err on the side of inclusion — a developer can ignore a link, but they can't inherit one that wasn't attached. Classification mistakes are caught by the preservation gate in Phase 5.5 and by the human reviewing the final report.
|
|
181
|
+
|
|
97
182
|
### Phase 5: Create Sub-tasks
|
|
98
183
|
|
|
99
184
|
Delegate sub-task creation to **parallel agents** (one per epic or batch of stories) for efficiency.
|
|
@@ -111,6 +196,25 @@ Use the test user credentials from config for all verification plans.
|
|
|
111
196
|
|
|
112
197
|
Set `parent` to the Story key. Use `issueTypeName: "Sub-task"`.
|
|
113
198
|
|
|
199
|
+
Sub-tasks inherit their parent story's artifacts by reference (the parent link). Do not re-attach the same remote links on every sub-task — that creates noise. The only exception is when a sub-task depends on an artifact that the parent story doesn't (e.g., a sub-task spec'd from a specific Figma frame that the broader story doesn't cite) — in that case, attach the specific artifact directly.
|
|
200
|
+
|
|
201
|
+
### Phase 5.5: Artifact Preservation Gate
|
|
202
|
+
|
|
203
|
+
Before reporting, verify that every artifact extracted in Phase 1.5 is reachable from the created tickets. This gate exists because silent artifact loss is the failure mode this skill is designed to prevent.
|
|
204
|
+
|
|
205
|
+
1. Pull the remote links of every epic and story created in this run (via the JIRA API).
|
|
206
|
+
2. Build a preservation matrix: `artifact URL → [ticket keys that reference it]`.
|
|
207
|
+
3. For every artifact from Phase 1.5:
|
|
208
|
+
- It MUST appear on the epic it belongs to (no exceptions).
|
|
209
|
+
- It SHOULD appear on at least one story whose scope matches its domain (except `reference`-domain artifacts, which may be epic-only if no story is domain-matched).
|
|
210
|
+
4. If any artifact has zero references anywhere, or is missing from its epic, FAIL LOUDLY:
|
|
211
|
+
- List each dropped artifact with its domain, title, and source page.
|
|
212
|
+
- State why it was dropped (domain classification error, propagation skipped, attach failure).
|
|
213
|
+
- Ask the human to confirm the drop or point at the right epic/story, then re-attach before continuing.
|
|
214
|
+
5. If classification seems misrouted (e.g., a Figma link ended up on a backend story and nowhere else), surface the misroute and offer to re-propagate.
|
|
215
|
+
|
|
216
|
+
Do NOT skip this gate. If every artifact is preserved, print the matrix compactly and proceed to Phase 6.
|
|
217
|
+
|
|
114
218
|
### Phase 6: Report Results
|
|
115
219
|
|
|
116
220
|
After all tickets are created, present a summary table to the user:
|
|
@@ -118,6 +222,7 @@ After all tickets are created, present a summary table to the user:
|
|
|
118
222
|
- All Stories grouped by Epic
|
|
119
223
|
- All Sub-tasks grouped by Story with repo tags
|
|
120
224
|
- Repo distribution (how many tasks per repo)
|
|
225
|
+
- **Artifact Preservation Matrix** — one row per artifact showing which epic/stories reference it
|
|
121
226
|
- Blockers list with recommendations and alternatives
|
|
122
227
|
- Cross-PRD dependencies
|
|
123
228
|
|
|
@@ -87,6 +87,34 @@ h3. Assertions
|
|
|
87
87
|
6. **Prerequisites include feature flags** — If the feature is behind a PostHog flag, name it explicitly
|
|
88
88
|
7. **Auth steps included when needed** — If the journey requires login, include the test credentials in Prerequisites
|
|
89
89
|
|
|
90
|
+
## Source Artifact Preservation
|
|
91
|
+
|
|
92
|
+
If $ARGUMENTS includes a PRD, design doc, Figma URL, Lovable prototype, or similar external artifact — or if a referenced file links out to one — those references MUST be preserved as remote links on the created tickets. Dropping source artifacts during ticket creation is the single most common quality failure in this pipeline, because developers picking up a ticket then lose the design/UX source of truth.
|
|
93
|
+
|
|
94
|
+
Rules:
|
|
95
|
+
|
|
96
|
+
1. **Extract before creating**: enumerate every external URL, embed, attachment, or example payload in the input. Classify by domain (`ui-design`, `ux-flow`, `data`, `ops`, `reference`) — see `notion-to-jira` Phase 1.5 for the canonical taxonomy.
|
|
97
|
+
2. **Epic gets everything**: attach all extracted artifacts as remote links on the epic, regardless of domain.
|
|
98
|
+
3. **Stories inherit by domain**: frontend/Expo stories get `ui-design` + `ux-flow` + `reference`; backend gets `data` + `reference`; infra gets `ops` + `reference`. When ambiguous, err on the side of inclusion.
|
|
99
|
+
4. **Sub-tasks inherit via parent**: do not re-attach on every sub-task unless a specific artifact applies only to that sub-task.
|
|
100
|
+
5. **Verify before reporting**: before declaring done, confirm every extracted artifact is reachable from the tickets. If any are missing, fail loudly and surface the dropped list to the human — do not silently drop.
|
|
101
|
+
|
|
102
|
+
When delegating actual writes to `jira-write-ticket`, pass the extracted artifact list so its Phase 4c (Remote Links) step can attach them.
|
|
103
|
+
|
|
104
|
+
**Classification disambiguation** (applied during extraction):
|
|
105
|
+
- Figma URL with `/proto/` or `starting-point-node-id=` → `ux-flow`; plain design frame URL → `ui-design`.
|
|
106
|
+
- Lovable output → always `ux-flow` (its code/styling/logic is NOT authoritative).
|
|
107
|
+
- Loom / annotated screenshot with flow arrows → `ux-flow`; bare screenshot → `ui-design`.
|
|
108
|
+
|
|
109
|
+
**Source precedence** (must be recorded on every ticket carrying design artifacts):
|
|
110
|
+
- Business rules (fields, validation, permissions, constraints) come from the **description / PRD body**.
|
|
111
|
+
- Visual treatment (layout, spacing, typography, color) comes from **mocks** (`ui-design`).
|
|
112
|
+
- Flow and interaction (navigation, transitions, state changes, empty/error/loading states) come from **prototypes** (`ux-flow`).
|
|
113
|
+
- API / data shape comes from **`data` artifacts**.
|
|
114
|
+
- Cross-axis conflicts are surfaced as `## Open Questions` BLOCKERs, never silently reconciled.
|
|
115
|
+
|
|
116
|
+
**Existing-component reuse** (applies to every UI-touching ticket — especially relevant for Expo/React Native with its established component library): the story description must instruct the implementer to locate the closest existing component in the codebase and prefer reuse over pixel-matching a mock. Design-vs-code divergence is raised on the ticket, not resolved by the implementer alone.
|
|
117
|
+
|
|
90
118
|
## Issue Requirements
|
|
91
119
|
|
|
92
120
|
Each issue must clearly communicate to:
|
|
@@ -27,6 +27,34 @@ Analyze the provided file(s) and create a comprehensive JIRA hierarchy with all
|
|
|
27
27
|
**Feature Flags**: All features behind flags with lifecycle plan
|
|
28
28
|
**Cleanup**: Remove temporary code, scripts, dev configs
|
|
29
29
|
|
|
30
|
+
## Source Artifact Preservation
|
|
31
|
+
|
|
32
|
+
If $ARGUMENTS includes a PRD, design doc, Figma URL, Lovable prototype, or similar external artifact — or if a referenced file links out to one — those references MUST be preserved as remote links on the created tickets. Dropping source artifacts during ticket creation is the single most common quality failure in this pipeline, because developers picking up a ticket then lose the design/UX source of truth.
|
|
33
|
+
|
|
34
|
+
Rules:
|
|
35
|
+
|
|
36
|
+
1. **Extract before creating**: enumerate every external URL, embed, attachment, or example payload in the input. Classify by domain (`ui-design`, `ux-flow`, `data`, `ops`, `reference`) — see `notion-to-jira` Phase 1.5 for the canonical taxonomy.
|
|
37
|
+
2. **Epic gets everything**: attach all extracted artifacts as remote links on the epic, regardless of domain.
|
|
38
|
+
3. **Stories inherit by domain**: frontend/view stories get `ui-design` + `ux-flow` + `reference`; backend/model/controller stories get `data` + `reference`; infra stories get `ops` + `reference`. When ambiguous, err on the side of inclusion.
|
|
39
|
+
4. **Sub-tasks inherit via parent**: do not re-attach on every sub-task unless a specific artifact applies only to that sub-task.
|
|
40
|
+
5. **Verify before reporting**: before declaring done, confirm every extracted artifact is reachable from the tickets. If any are missing, fail loudly and surface the dropped list to the human — do not silently drop.
|
|
41
|
+
|
|
42
|
+
When delegating actual writes to `jira-write-ticket`, pass the extracted artifact list so its Phase 4c (Remote Links) step can attach them.
|
|
43
|
+
|
|
44
|
+
**Classification disambiguation** (applied during extraction):
|
|
45
|
+
- Figma URL with `/proto/` or `starting-point-node-id=` → `ux-flow`; plain design frame URL → `ui-design`.
|
|
46
|
+
- Lovable output → always `ux-flow` (its code/styling/logic is NOT authoritative).
|
|
47
|
+
- Loom / annotated screenshot with flow arrows → `ux-flow`; bare screenshot → `ui-design`.
|
|
48
|
+
|
|
49
|
+
**Source precedence** (must be recorded on every ticket carrying design artifacts):
|
|
50
|
+
- Business rules (fields, validation, permissions, constraints) come from the **description / PRD body**.
|
|
51
|
+
- Visual treatment (layout, spacing, typography, color) comes from **mocks** (`ui-design`).
|
|
52
|
+
- Flow and interaction (navigation, transitions, state changes, empty/error/loading states) come from **prototypes** (`ux-flow`).
|
|
53
|
+
- API / data shape comes from **`data` artifacts**.
|
|
54
|
+
- Cross-axis conflicts are surfaced as `## Open Questions` BLOCKERs, never silently reconciled.
|
|
55
|
+
|
|
56
|
+
**Existing-component reuse** (applies to every view/partial-touching ticket): the story description must instruct the implementer to locate the closest existing view partial or ViewComponent in the codebase and prefer reuse over pixel-matching a mock. Design-vs-code divergence is raised on the ticket, not resolved by the implementer alone.
|
|
57
|
+
|
|
30
58
|
## Issue Requirements
|
|
31
59
|
|
|
32
60
|
Each issue must clearly communicate to:
|
|
@@ -81,6 +81,34 @@ h3. Assertions
|
|
|
81
81
|
4. **Assertions are testable statements** — "Health check returns 200 with status ok" not "API works"
|
|
82
82
|
5. **Prerequisites include environment setup** — Database connection, env vars, running services
|
|
83
83
|
|
|
84
|
+
## Source Artifact Preservation
|
|
85
|
+
|
|
86
|
+
If $ARGUMENTS includes a PRD, design doc, Figma URL, Lovable prototype, or similar external artifact — or if a referenced file links out to one — those references MUST be preserved as remote links on the created tickets. Dropping source artifacts during ticket creation is the single most common quality failure in this pipeline, because developers picking up a ticket then lose the design/UX source of truth.
|
|
87
|
+
|
|
88
|
+
Rules:
|
|
89
|
+
|
|
90
|
+
1. **Extract before creating**: enumerate every external URL, embed, attachment, or example payload in the input. Classify by domain (`ui-design`, `ux-flow`, `data`, `ops`, `reference`) — see `notion-to-jira` Phase 1.5 for the canonical taxonomy.
|
|
91
|
+
2. **Epic gets everything**: attach all extracted artifacts as remote links on the epic, regardless of domain.
|
|
92
|
+
3. **Stories inherit by domain**: frontend stories get `ui-design` + `ux-flow` + `reference`; backend gets `data` + `reference`; infra gets `ops` + `reference`. When ambiguous, err on the side of inclusion.
|
|
93
|
+
4. **Sub-tasks inherit via parent**: do not re-attach on every sub-task unless a specific artifact applies only to that sub-task.
|
|
94
|
+
5. **Verify before reporting**: before declaring done, confirm every extracted artifact is reachable from the tickets. If any are missing, fail loudly and surface the dropped list to the human — do not silently drop.
|
|
95
|
+
|
|
96
|
+
When delegating actual writes to `jira-write-ticket`, pass the extracted artifact list so its Phase 4c (Remote Links) step can attach them.
|
|
97
|
+
|
|
98
|
+
**Classification disambiguation** (applied during extraction):
|
|
99
|
+
- Figma URL with `/proto/` or `starting-point-node-id=` → `ux-flow`; plain design frame URL → `ui-design`.
|
|
100
|
+
- Lovable output → always `ux-flow` (its code/styling/logic is NOT authoritative).
|
|
101
|
+
- Loom / annotated screenshot with flow arrows → `ux-flow`; bare screenshot → `ui-design`.
|
|
102
|
+
|
|
103
|
+
**Source precedence** (must be recorded on every ticket carrying design artifacts):
|
|
104
|
+
- Business rules (fields, validation, permissions, constraints) come from the **description / PRD body**.
|
|
105
|
+
- Visual treatment (layout, spacing, typography, color) comes from **mocks** (`ui-design`).
|
|
106
|
+
- Flow and interaction (navigation, transitions, state changes) come from **prototypes** (`ux-flow`).
|
|
107
|
+
- API / data shape comes from **`data` artifacts**.
|
|
108
|
+
- Cross-axis conflicts are surfaced as `## Open Questions` BLOCKERs, never silently reconciled.
|
|
109
|
+
|
|
110
|
+
**Existing-component reuse** (applies to every UI-touching ticket): the story description must instruct the implementer to locate the closest existing component in the codebase and prefer reuse over pixel-matching a mock. Design-vs-code divergence is raised on the ticket, not resolved by the implementer alone.
|
|
111
|
+
|
|
84
112
|
## Issue Requirements
|
|
85
113
|
|
|
86
114
|
Each issue must clearly communicate to:
|
|
@@ -124,6 +124,28 @@ Identify and attach:
|
|
|
124
124
|
- Confluence pages (design docs, RFCs, runbooks)
|
|
125
125
|
- Dashboards (Grafana, Datadog, Sentry issue)
|
|
126
126
|
- Incident tickets (PagerDuty, Statuspage)
|
|
127
|
+
- **Source artifacts from the originating PRD / parent epic**: Figma files, Lovable prototypes, Loom walkthroughs, design mockups, example payloads, Google Docs/Slides, collaborative whiteboards. If this ticket has a parent epic, enumerate the epic's remote links and inherit the ones whose domain matches this ticket's scope (UI → `ui-design` + `ux-flow`; backend → `data`; infra → `ops`; always inherit generic `reference` links). Never assume a developer will walk up to the epic to find design context — attach it here.
|
|
128
|
+
|
|
129
|
+
Domain disambiguation (applied on inheritance):
|
|
130
|
+
- Figma URL with `/proto/` in path or `starting-point-node-id=` in query → `ux-flow`; otherwise `ui-design`.
|
|
131
|
+
- Lovable output → always `ux-flow`; its code/styling is not authoritative.
|
|
132
|
+
- Loom / annotated screenshot → `ux-flow`.
|
|
133
|
+
- Bare screenshot → `ui-design`.
|
|
134
|
+
|
|
135
|
+
If the ticket was generated from a PRD (by `notion-to-jira` or similar) and the parent epic has no source artifacts, surface that as a smell and ask whether artifacts were missed during extraction before proceeding.
|
|
136
|
+
|
|
137
|
+
### 4d. Source Precedence (must appear on the ticket)
|
|
138
|
+
|
|
139
|
+
When a ticket carries both design artifacts and a description, different sources are authoritative for different questions. Record this precedence explicitly in the ticket description (under Technical Approach or a dedicated `## Source Precedence` subsection) so the implementer doesn't silently reconcile conflicts:
|
|
140
|
+
|
|
141
|
+
- **Business rules** (required fields, validation, permissions, data constraints, edge cases) → the **description / PRD body** wins.
|
|
142
|
+
- **Visual treatment** (layout, spacing, typography, color, iconography) → **mocks (`ui-design`)** win.
|
|
143
|
+
- **Flow and interaction** (navigation, transitions, state changes, timing, empty/error/loading states) → **prototypes (`ux-flow`)** win.
|
|
144
|
+
- **API / data shape** → **`data` artifacts** win.
|
|
145
|
+
|
|
146
|
+
Cross-axis conflicts (mock shows a field the PRD doesn't mention; prototype shows a flow the PRD contradicts; two Figma links disagree) must be raised as BLOCKER items in an `## Open Questions` section on the ticket — never silently reconciled.
|
|
147
|
+
|
|
148
|
+
For UI-touching tickets, additionally include the reuse expectation: "Before implementing, identify the closest existing component in the codebase. Prefer reuse even if the mock specifies different styling; raise design-vs-code divergence as a discussion item here rather than pixel-matching from scratch."
|
|
127
149
|
|
|
128
150
|
Use Jira's web UI or `mcp__atlassian__editJiraIssue` to set the `Development` field / remote links where supported.
|
|
129
151
|
|
|
@@ -53,6 +53,76 @@ Do not retrieve credentials from repository files or local agent settings.
|
|
|
53
53
|
- Engineering comments (prefixed with "Engineering:" or wrench emoji) that identify technical constraints
|
|
54
54
|
- Cross-PRD dependencies (references to other features or shared infrastructure)
|
|
55
55
|
|
|
56
|
+
### Phase 1.5: Extract Source Artifacts
|
|
57
|
+
|
|
58
|
+
PRDs typically reference external design, UX, and data artifacts (Figma files, Lovable prototypes, Loom walkthroughs, screenshots, example payloads, Confluence pages). These MUST be preserved onto the resulting tickets — otherwise developers picking up a ticket lose the source of truth. This is the failure mode this step exists to prevent.
|
|
59
|
+
|
|
60
|
+
1. **Scan the PRD main page, all Epic sub-pages, and every fetched comment thread** for:
|
|
61
|
+
- URLs to design/prototype tools (Figma, FigJam, Figma Make, Lovable, Framer, Penpot)
|
|
62
|
+
- URLs to recording/walkthrough tools (Loom, YouTube, Vimeo, Descript)
|
|
63
|
+
- URLs to collaborative docs (Google Docs/Slides/Sheets, Confluence, Notion peer pages)
|
|
64
|
+
- URLs to code sandboxes (CodeSandbox, StackBlitz, Replit, GitHub permalinks/gists)
|
|
65
|
+
- URLs to diagramming tools (Miro, Mural, Excalidraw, Mermaid Live, draw.io, Lucid)
|
|
66
|
+
- URLs to data/observability tools (Grafana, Datadog, Sentry, Metabase, Looker)
|
|
67
|
+
- Embedded images and file attachments on the page itself
|
|
68
|
+
- Fenced code blocks with example data (JSON, SQL, GraphQL, cURL request/response)
|
|
69
|
+
|
|
70
|
+
2. **Classify each artifact by domain**. The split matters — each domain is the source of truth for different implementation decisions:
|
|
71
|
+
|
|
72
|
+
| Domain | What it defines | Examples |
|
|
73
|
+
|--------|-----------------|----------|
|
|
74
|
+
| `ui-design` (mocks) | **Visual treatment only** — layout, spacing, typography, color, iconography | Figma design frames, Framer static frames, bare screenshots, mockup PNGs |
|
|
75
|
+
| `ux-flow` (prototypes) | **Interaction and flow only** — navigation, transitions, state changes, timing, empty/error/loading states | Lovable output, Loom walkthroughs, Figma prototype links, annotated screenshots, Miro/Mural flow diagrams, user journey maps |
|
|
76
|
+
| `data` | Request/response shape, schema constraints | Example JSON, SQL schemas, GraphQL snippets, API contracts |
|
|
77
|
+
| `ops` | Deployment/runtime context | Runbooks, dashboards, Terraform refs, deployment diagrams |
|
|
78
|
+
| `reference` | Cross-cutting context | Confluence, Notion peer pages, Google Docs, related PRDs |
|
|
79
|
+
|
|
80
|
+
3. **Apply disambiguation rules** when an artifact could fit multiple domains. These rules exist because agents consistently misclassify Figma and Lovable artifacts, which are the two most common sources of dropped context.
|
|
81
|
+
|
|
82
|
+
- **Figma URL**: classify as `ux-flow` if the URL is a prototype share link — it contains `/proto/`, or has `starting-point-node-id=` in the query, or the sharing context labels it "prototype" / "play mode". Otherwise classify as `ui-design`. Never assume.
|
|
83
|
+
- **Lovable output**: always `ux-flow`. Lovable ships working code, but its code, styling, and any embedded business rules are NOT authoritative. Treat Lovable strictly as a UX/flow reference. Implementation uses existing project components; business rules come from the PRD description, not from Lovable.
|
|
84
|
+
- **Screenshot with annotations** (arrows between frames, flow labels, numbered steps): `ux-flow`. A bare unannotated screenshot: `ui-design`. A side-by-side gallery of state variants (empty/error/loading): `ui-design` with state variants noted.
|
|
85
|
+
- **Loom / video walkthrough**: `ux-flow` in the vast majority of cases. The rare exception — a video that's only a static-frame design review with no interaction — is still `ux-flow` for routing purposes (both UX and UI stories benefit from it).
|
|
86
|
+
- **Figma file with both design frames and a prototype**: emit two entries — one `ui-design` for the file, one `ux-flow` for the prototype URL — so both propagate correctly.
|
|
87
|
+
|
|
88
|
+
4. **Build an `artifacts` map** keyed by domain. Each entry: `{ url, title, domain, source_page, source_page_url, classification_reason }`. The `classification_reason` makes disambiguation auditable ("Figma URL contains `/proto/` → ux-flow"). The `source_page` lets you trace each reference back to where it appeared in the PRD.
|
|
89
|
+
|
|
90
|
+
5. **Surface coverage smells** — incomplete artifact sets are a common root cause of implementation drift:
|
|
91
|
+
- **Zero artifacts** on a non-trivial PRD: almost always an extraction bug, not a design decision. Say so explicitly.
|
|
92
|
+
- **Prototype but no mock** (`ux-flow` present, `ui-design` absent): flag "missing UI mocks". UI will have to be inferred from prototype frames — note that prototype styling is typically placeholder and must NOT be treated as visual source of truth. Record the smell on the epic.
|
|
93
|
+
- **Mocks but no prototype** (`ui-design` present, `ux-flow` absent): flag "missing UX prototype". UX will have to be inferred from static mock states (empty/error/loading/hover) — any flow that isn't explicitly depicted in the mocks must be raised as a BLOCKER with recommendation + alternatives, not silently invented.
|
|
94
|
+
- **Lovable output without a description covering business rules**: flag "business rules missing". Lovable's embedded logic is not authoritative; the PRD description must explicitly state required fields, validation, permissions, and edge cases.
|
|
95
|
+
|
|
96
|
+
### Phase 1.6: Source Precedence & Conflict Resolution
|
|
97
|
+
|
|
98
|
+
Different artifact domains answer different questions. When they disagree, silent reconciliation is a known failure mode — these rules must be encoded on the tickets and respected during implementation.
|
|
99
|
+
|
|
100
|
+
**Authoritative source by question**:
|
|
101
|
+
|
|
102
|
+
| Question | Authoritative source |
|
|
103
|
+
|----------|---------------------|
|
|
104
|
+
| Does this field exist? Is it required? Who can see/edit it? What validation applies? What are the edge cases, permission rules, data constraints? | **Description / PRD body** (business rules) |
|
|
105
|
+
| What does it look like — layout, spacing, typography, color, iconography? | **Mocks (`ui-design`)** |
|
|
106
|
+
| How does it flow — navigation, transitions, state changes, timing, empty/error/loading states? | **Prototypes (`ux-flow`)** |
|
|
107
|
+
| Where does the data come from, what shape is it, what are the API contracts? | **`data` artifacts** |
|
|
108
|
+
|
|
109
|
+
**Cross-axis conflicts must be surfaced, not reconciled silently**:
|
|
110
|
+
|
|
111
|
+
- Mock shows a field the description doesn't mention → BLOCKER on the story: "Figma shows field `X` not in PRD; confirm it exists, and if so add business rules (required/optional, validation)."
|
|
112
|
+
- Description mandates behavior the prototype contradicts → BLOCKER: "PRD says Y, prototype shows Z; which is correct?"
|
|
113
|
+
- Prototype shows a flow the mocks don't cover (e.g., an error state) → Note on the story: "Error state flow from prototype; no mock exists for the error UI. Use existing error component or request mock."
|
|
114
|
+
- Multiple artifacts of the same domain disagree (e.g., two Figma links showing different layouts) → BLOCKER: list both, ask which is current.
|
|
115
|
+
|
|
116
|
+
Record every conflict on the ticket description under a `## Open Questions` subsection so the developer picking up the ticket sees it before writing code.
|
|
117
|
+
|
|
118
|
+
**Existing-component reuse (applies to `ui-design` consumers)**:
|
|
119
|
+
|
|
120
|
+
Mocks define *visual intent*, not *implementation shortcut*. Before a developer builds UI from a mock, they must search the codebase for the closest-matching existing component. Encode this expectation on every UI-touching story:
|
|
121
|
+
|
|
122
|
+
- Story description includes: "Before implementing, identify the closest existing component in the codebase. Prefer reuse even if the Figma mock specifies different styling — flag the design-vs-code divergence as a discussion point on this ticket rather than pixel-matching Figma from scratch."
|
|
123
|
+
- If no existing component fits, building a new one is an explicit decision that must be recorded in the ticket (with rationale) before implementation.
|
|
124
|
+
- Lovable-generated components are never the reuse target — always use the project's own components.
|
|
125
|
+
|
|
56
126
|
### Phase 2: Codebase Research (if needed)
|
|
57
127
|
|
|
58
128
|
If the session doesn't already have codebase context, explore the repos to understand what exists.
|
|
@@ -72,9 +142,12 @@ Create one Epic per PRD epic using the JIRA project key from config. Each Epic d
|
|
|
72
142
|
- Key decisions from comments (with attribution)
|
|
73
143
|
- Blockers and open questions
|
|
74
144
|
- Dependencies on other epics or PRDs
|
|
145
|
+
- A **Source Artifacts** section listing every artifact extracted in Phase 1.5 (grouped by domain)
|
|
75
146
|
|
|
76
147
|
Use `contentFormat: "markdown"` for all descriptions.
|
|
77
148
|
|
|
149
|
+
**Attach every artifact from Phase 1.5 as an Epic remote link** — regardless of domain. The epic is the canonical hub, and anyone working on the epic or its descendants must be able to reach the full set from one place. No filtering at the epic level.
|
|
150
|
+
|
|
78
151
|
### Phase 4: Create Stories
|
|
79
152
|
|
|
80
153
|
For each Epic, create Stories:
|
|
@@ -91,9 +164,21 @@ Each story description should include:
|
|
|
91
164
|
- Acceptance criteria (from functional requirements)
|
|
92
165
|
- Technical notes from engineering comments
|
|
93
166
|
- Blockers with recommendation + alternatives (if any)
|
|
167
|
+
- A **Source Artifacts** section listing the artifacts inherited from the epic that match this story's scope (see propagation rules below)
|
|
94
168
|
|
|
95
169
|
Set `parent` to the Epic key to link stories to their epic.
|
|
96
170
|
|
|
171
|
+
**Inherit domain-matching artifacts as story remote links**. For each story, attach the Phase 1.5 artifacts whose domain matches the story's scope:
|
|
172
|
+
|
|
173
|
+
| Story type | Inherits domains |
|
|
174
|
+
|------------|------------------|
|
|
175
|
+
| Frontend / UI | `ui-design`, `ux-flow`, `reference` |
|
|
176
|
+
| Backend / API / data model | `data`, `reference` |
|
|
177
|
+
| Infrastructure | `ops`, `reference` |
|
|
178
|
+
| Mixed / setup ("X.0") | All domains |
|
|
179
|
+
|
|
180
|
+
When classification is ambiguous, err on the side of inclusion — a developer can ignore a link, but they can't inherit one that wasn't attached. Classification mistakes are caught by the preservation gate in Phase 5.5 and by the human reviewing the final report.
|
|
181
|
+
|
|
97
182
|
### Phase 5: Create Sub-tasks
|
|
98
183
|
|
|
99
184
|
Delegate sub-task creation to **parallel agents** (one per epic or batch of stories) for efficiency.
|
|
@@ -111,6 +196,25 @@ Use the test user credentials from config for all verification plans.
|
|
|
111
196
|
|
|
112
197
|
Set `parent` to the Story key. Use `issueTypeName: "Sub-task"`.
|
|
113
198
|
|
|
199
|
+
Sub-tasks inherit their parent story's artifacts by reference (the parent link). Do not re-attach the same remote links on every sub-task — that creates noise. The only exception is when a sub-task depends on an artifact that the parent story doesn't (e.g., a sub-task spec'd from a specific Figma frame that the broader story doesn't cite) — in that case, attach the specific artifact directly.
|
|
200
|
+
|
|
201
|
+
### Phase 5.5: Artifact Preservation Gate
|
|
202
|
+
|
|
203
|
+
Before reporting, verify that every artifact extracted in Phase 1.5 is reachable from the created tickets. This gate exists because silent artifact loss is the failure mode this skill is designed to prevent.
|
|
204
|
+
|
|
205
|
+
1. Pull the remote links of every epic and story created in this run (via the JIRA API).
|
|
206
|
+
2. Build a preservation matrix: `artifact URL → [ticket keys that reference it]`.
|
|
207
|
+
3. For every artifact from Phase 1.5:
|
|
208
|
+
- It MUST appear on the epic it belongs to (no exceptions).
|
|
209
|
+
- It SHOULD appear on at least one story whose scope matches its domain (except `reference`-domain artifacts, which may be epic-only if no story is domain-matched).
|
|
210
|
+
4. If any artifact has zero references anywhere, or is missing from its epic, FAIL LOUDLY:
|
|
211
|
+
- List each dropped artifact with its domain, title, and source page.
|
|
212
|
+
- State why it was dropped (domain classification error, propagation skipped, attach failure).
|
|
213
|
+
- Ask the human to confirm the drop or point at the right epic/story, then re-attach before continuing.
|
|
214
|
+
5. If classification seems misrouted (e.g., a Figma link ended up on a backend story and nowhere else), surface the misroute and offer to re-propagate.
|
|
215
|
+
|
|
216
|
+
Do NOT skip this gate. If every artifact is preserved, print the matrix compactly and proceed to Phase 6.
|
|
217
|
+
|
|
114
218
|
### Phase 6: Report Results
|
|
115
219
|
|
|
116
220
|
After all tickets are created, present a summary table to the user:
|
|
@@ -118,6 +222,7 @@ After all tickets are created, present a summary table to the user:
|
|
|
118
222
|
- All Stories grouped by Epic
|
|
119
223
|
- All Sub-tasks grouped by Story with repo tags
|
|
120
224
|
- Repo distribution (how many tasks per repo)
|
|
225
|
+
- **Artifact Preservation Matrix** — one row per artifact showing which epic/stories reference it
|
|
121
226
|
- Blockers list with recommendations and alternatives
|
|
122
227
|
- Cross-PRD dependencies
|
|
123
228
|
|
|
@@ -87,6 +87,34 @@ h3. Assertions
|
|
|
87
87
|
6. **Prerequisites include feature flags** — If the feature is behind a PostHog flag, name it explicitly
|
|
88
88
|
7. **Auth steps included when needed** — If the journey requires login, include the test credentials in Prerequisites
|
|
89
89
|
|
|
90
|
+
## Source Artifact Preservation
|
|
91
|
+
|
|
92
|
+
If $ARGUMENTS includes a PRD, design doc, Figma URL, Lovable prototype, or similar external artifact — or if a referenced file links out to one — those references MUST be preserved as remote links on the created tickets. Dropping source artifacts during ticket creation is the single most common quality failure in this pipeline, because developers picking up a ticket then lose the design/UX source of truth.
|
|
93
|
+
|
|
94
|
+
Rules:
|
|
95
|
+
|
|
96
|
+
1. **Extract before creating**: enumerate every external URL, embed, attachment, or example payload in the input. Classify by domain (`ui-design`, `ux-flow`, `data`, `ops`, `reference`) — see `notion-to-jira` Phase 1.5 for the canonical taxonomy.
|
|
97
|
+
2. **Epic gets everything**: attach all extracted artifacts as remote links on the epic, regardless of domain.
|
|
98
|
+
3. **Stories inherit by domain**: frontend/Expo stories get `ui-design` + `ux-flow` + `reference`; backend gets `data` + `reference`; infra gets `ops` + `reference`. When ambiguous, err on the side of inclusion.
|
|
99
|
+
4. **Sub-tasks inherit via parent**: do not re-attach on every sub-task unless a specific artifact applies only to that sub-task.
|
|
100
|
+
5. **Verify before reporting**: before declaring done, confirm every extracted artifact is reachable from the tickets. If any are missing, fail loudly and surface the dropped list to the human — do not silently drop.
|
|
101
|
+
|
|
102
|
+
When delegating actual writes to `jira-write-ticket`, pass the extracted artifact list so its Phase 4c (Remote Links) step can attach them.
|
|
103
|
+
|
|
104
|
+
**Classification disambiguation** (applied during extraction):
|
|
105
|
+
- Figma URL with `/proto/` or `starting-point-node-id=` → `ux-flow`; plain design frame URL → `ui-design`.
|
|
106
|
+
- Lovable output → always `ux-flow` (its code/styling/logic is NOT authoritative).
|
|
107
|
+
- Loom / annotated screenshot with flow arrows → `ux-flow`; bare screenshot → `ui-design`.
|
|
108
|
+
|
|
109
|
+
**Source precedence** (must be recorded on every ticket carrying design artifacts):
|
|
110
|
+
- Business rules (fields, validation, permissions, constraints) come from the **description / PRD body**.
|
|
111
|
+
- Visual treatment (layout, spacing, typography, color) comes from **mocks** (`ui-design`).
|
|
112
|
+
- Flow and interaction (navigation, transitions, state changes, empty/error/loading states) come from **prototypes** (`ux-flow`).
|
|
113
|
+
- API / data shape comes from **`data` artifacts**.
|
|
114
|
+
- Cross-axis conflicts are surfaced as `## Open Questions` BLOCKERs, never silently reconciled.
|
|
115
|
+
|
|
116
|
+
**Existing-component reuse** (applies to every UI-touching ticket — especially relevant for Expo/React Native with its established component library): the story description must instruct the implementer to locate the closest existing component in the codebase and prefer reuse over pixel-matching a mock. Design-vs-code divergence is raised on the ticket, not resolved by the implementer alone.
|
|
117
|
+
|
|
90
118
|
## Issue Requirements
|
|
91
119
|
|
|
92
120
|
Each issue must clearly communicate to:
|
|
@@ -27,6 +27,34 @@ Analyze the provided file(s) and create a comprehensive JIRA hierarchy with all
|
|
|
27
27
|
**Feature Flags**: All features behind flags with lifecycle plan
|
|
28
28
|
**Cleanup**: Remove temporary code, scripts, dev configs
|
|
29
29
|
|
|
30
|
+
## Source Artifact Preservation
|
|
31
|
+
|
|
32
|
+
If $ARGUMENTS includes a PRD, design doc, Figma URL, Lovable prototype, or similar external artifact — or if a referenced file links out to one — those references MUST be preserved as remote links on the created tickets. Dropping source artifacts during ticket creation is the single most common quality failure in this pipeline, because developers picking up a ticket then lose the design/UX source of truth.
|
|
33
|
+
|
|
34
|
+
Rules:
|
|
35
|
+
|
|
36
|
+
1. **Extract before creating**: enumerate every external URL, embed, attachment, or example payload in the input. Classify by domain (`ui-design`, `ux-flow`, `data`, `ops`, `reference`) — see `notion-to-jira` Phase 1.5 for the canonical taxonomy.
|
|
37
|
+
2. **Epic gets everything**: attach all extracted artifacts as remote links on the epic, regardless of domain.
|
|
38
|
+
3. **Stories inherit by domain**: frontend/view stories get `ui-design` + `ux-flow` + `reference`; backend/model/controller stories get `data` + `reference`; infra stories get `ops` + `reference`. When ambiguous, err on the side of inclusion.
|
|
39
|
+
4. **Sub-tasks inherit via parent**: do not re-attach on every sub-task unless a specific artifact applies only to that sub-task.
|
|
40
|
+
5. **Verify before reporting**: before declaring done, confirm every extracted artifact is reachable from the tickets. If any are missing, fail loudly and surface the dropped list to the human — do not silently drop.
|
|
41
|
+
|
|
42
|
+
When delegating actual writes to `jira-write-ticket`, pass the extracted artifact list so its Phase 4c (Remote Links) step can attach them.
|
|
43
|
+
|
|
44
|
+
**Classification disambiguation** (applied during extraction):
|
|
45
|
+
- Figma URL with `/proto/` or `starting-point-node-id=` → `ux-flow`; plain design frame URL → `ui-design`.
|
|
46
|
+
- Lovable output → always `ux-flow` (its code/styling/logic is NOT authoritative).
|
|
47
|
+
- Loom / annotated screenshot with flow arrows → `ux-flow`; bare screenshot → `ui-design`.
|
|
48
|
+
|
|
49
|
+
**Source precedence** (must be recorded on every ticket carrying design artifacts):
|
|
50
|
+
- Business rules (fields, validation, permissions, constraints) come from the **description / PRD body**.
|
|
51
|
+
- Visual treatment (layout, spacing, typography, color) comes from **mocks** (`ui-design`).
|
|
52
|
+
- Flow and interaction (navigation, transitions, state changes, empty/error/loading states) come from **prototypes** (`ux-flow`).
|
|
53
|
+
- API / data shape comes from **`data` artifacts**.
|
|
54
|
+
- Cross-axis conflicts are surfaced as `## Open Questions` BLOCKERs, never silently reconciled.
|
|
55
|
+
|
|
56
|
+
**Existing-component reuse** (applies to every view/partial-touching ticket): the story description must instruct the implementer to locate the closest existing view partial or ViewComponent in the codebase and prefer reuse over pixel-matching a mock. Design-vs-code divergence is raised on the ticket, not resolved by the implementer alone.
|
|
57
|
+
|
|
30
58
|
## Issue Requirements
|
|
31
59
|
|
|
32
60
|
Each issue must clearly communicate to:
|
|
@@ -272,6 +272,20 @@ fi
|
|
|
272
272
|
# fi
|
|
273
273
|
# fi
|
|
274
274
|
|
|
275
|
+
# Project-specific extension slot (see .husky/pre-push.local).
|
|
276
|
+
# This hook sources pre-push.local if present so per-project checks
|
|
277
|
+
# (e.g., app-boot verification, schema validation) survive Lisa template
|
|
278
|
+
# updates without editing the governance block above.
|
|
279
|
+
if [ -f .husky/pre-push.local ]; then
|
|
280
|
+
echo "🔌 Running project-specific pre-push checks (.husky/pre-push.local)..."
|
|
281
|
+
# shellcheck source=/dev/null
|
|
282
|
+
. .husky/pre-push.local
|
|
283
|
+
if [ $? -ne 0 ]; then
|
|
284
|
+
echo "❌ Project-specific pre-push checks failed."
|
|
285
|
+
exit 1
|
|
286
|
+
fi
|
|
287
|
+
fi
|
|
288
|
+
|
|
275
289
|
exit 0
|
|
276
290
|
|
|
277
291
|
# END: AI GUARDRAILS
|
|
@@ -117,6 +117,26 @@
|
|
|
117
117
|
"id": "GHSA-fvcv-3m26-pcqx",
|
|
118
118
|
"package": "axios",
|
|
119
119
|
"reason": "Cloud metadata exfiltration requires attacker-controlled outbound request header values. Keep this exclusion only if axios request headers are never sourced from untrusted input."
|
|
120
|
+
},
|
|
121
|
+
{
|
|
122
|
+
"id": "GHSA-2v35-w6hq-6mfw",
|
|
123
|
+
"package": "@xmldom/xmldom",
|
|
124
|
+
"reason": "Uncontrolled recursion in XML serialization leading to DoS. Transitive via expo > @expo/config-plugins > @expo/plist; only serializes developer-authored plist files at build/prebuild time, no runtime code path parses or serializes attacker-controlled XML."
|
|
125
|
+
},
|
|
126
|
+
{
|
|
127
|
+
"id": "GHSA-f6ww-3ggp-fr8h",
|
|
128
|
+
"package": "@xmldom/xmldom",
|
|
129
|
+
"reason": "XML injection via unvalidated DocumentType serialization. Transitive via expo > @expo/config-plugins > @expo/plist; only serializes developer-authored plist files at build/prebuild time, no runtime code path serializes attacker-controlled XML."
|
|
130
|
+
},
|
|
131
|
+
{
|
|
132
|
+
"id": "GHSA-x6wf-f3px-wcqx",
|
|
133
|
+
"package": "@xmldom/xmldom",
|
|
134
|
+
"reason": "XML node injection via unvalidated processing instruction serialization. Transitive via expo > @expo/config-plugins > @expo/plist; only serializes developer-authored plist files at build/prebuild time, no runtime code path serializes attacker-controlled XML."
|
|
135
|
+
},
|
|
136
|
+
{
|
|
137
|
+
"id": "GHSA-j759-j44w-7fr8",
|
|
138
|
+
"package": "@xmldom/xmldom",
|
|
139
|
+
"reason": "XML node injection via unvalidated comment serialization. Transitive via expo > @expo/config-plugins > @expo/plist; only serializes developer-authored plist files at build/prebuild time, no runtime code path serializes attacker-controlled XML."
|
|
120
140
|
}
|
|
121
141
|
]
|
|
122
142
|
}
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
# Project-specific pre-push checks
|
|
2
|
+
#
|
|
3
|
+
# This file is sourced by .husky/pre-push after Lisa's governance block.
|
|
4
|
+
# Add commands here that are unique to this project — Lisa will never
|
|
5
|
+
# overwrite or delete this file on future template updates.
|
|
6
|
+
#
|
|
7
|
+
# The file runs as a sourced POSIX script. Any non-zero exit aborts the push.
|
|
8
|
+
#
|
|
9
|
+
# Examples:
|
|
10
|
+
# # NestJS AppModule + GraphQL schema boot verification
|
|
11
|
+
# $RUNNER verify:boot || exit 1
|
|
12
|
+
#
|
|
13
|
+
# # Project-specific migration lint
|
|
14
|
+
# $RUNNER migrations:check || exit 1
|
|
15
|
+
#
|
|
16
|
+
# $RUNNER is set by the parent hook based on the detected package manager
|
|
17
|
+
# (bun run / yarn run / npm run).
|