@smartsoft001/pro-claude-plugins 0.11.0 → 0.13.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 CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@smartsoft001/pro-claude-plugins",
3
- "version": "0.11.0",
3
+ "version": "0.13.0",
4
4
  "publishConfig": {
5
5
  "access": "public"
6
6
  },
@@ -1,5 +1,5 @@
1
1
  {
2
2
  "name": "flow",
3
3
  "description": "Development flow skills for Linear-driven development workflow",
4
- "version": "0.11.0"
4
+ "version": "0.13.0"
5
5
  }
@@ -23,6 +23,8 @@ Execute test suites and provide clear reporting of results.
23
23
 
24
24
  ### Unit Tests
25
25
 
26
+ Every command below runs through `2>&1 | tail -80`; on failure re-run the single failing command through `2>&1 | grep -iE 'error|ERR!|✖|FAIL' -B2 -A5 | head -120` (see `nx-conventions` §3a). The examples omit the suffix for readability.
27
+
26
28
  ```bash
27
29
  # Run tests for specific project
28
30
  nx test web
@@ -12,6 +12,8 @@ You are the verification orchestrator responsible for running the complete verif
12
12
 
13
13
  Coordinate all verification stages to ensure code quality before completion.
14
14
 
15
+ Output discipline: every `nx` command runs through `2>&1 | tail -80`; on failure re-run that one command through `2>&1 | grep -iE 'error|ERR!|✖|FAIL' -B2 -A5 | head -120`. Never paste a full log into the conversation (see `nx-conventions` §3a).
16
+
15
17
  ## When to Use
16
18
 
17
19
  - After completing implementation
@@ -27,8 +29,8 @@ Run style and security checks in parallel for quick feedback.
27
29
 
28
30
  ```bash
29
31
  # Style enforcement (linting + type-check)
30
- nx lint web &
31
- nx lint shared-angular &
32
+ nx lint web 2>&1 | tail -80 &
33
+ nx lint shared-angular 2>&1 | tail -80 &
32
34
 
33
35
  # Security scanning
34
36
  npm audit --audit-level=moderate &
@@ -44,8 +46,8 @@ Run unit tests with coverage verification.
44
46
 
45
47
  ```bash
46
48
  # Run tests with coverage
47
- nx test web --coverage --coverageReporters=text-summary
48
- nx test shared-angular --coverage --coverageReporters=text-summary
49
+ nx test web --coverage --coverageReporters=text-summary 2>&1 | tail -80
50
+ nx test shared-angular --coverage --coverageReporters=text-summary 2>&1 | tail -80
49
51
  ```
50
52
 
51
53
  **Pass criteria**: All tests pass, coverage >= 80%.
@@ -56,7 +58,9 @@ Verify production build succeeds.
56
58
 
57
59
  ```bash
58
60
  # Production build
59
- nx build web --configuration=production
61
+ nx build web --configuration=production 2>&1 | tail -80
62
+ # on failure, errors only:
63
+ # nx build web --configuration=production 2>&1 | grep -iE 'error|ERR!|✖|FAIL' -B2 -A5 | head -120
60
64
  ```
61
65
 
62
66
  **Pass criteria**: Build completes without errors.
@@ -188,7 +192,7 @@ For quick pre-commit verification, run stages 1-3 only:
188
192
 
189
193
  ```bash
190
194
  # Quick verification script
191
- nx lint web && \
192
- nx test web --coverage && \
193
- nx build web
195
+ nx lint web 2>&1 | tail -80 && \
196
+ nx test web --coverage 2>&1 | tail -80 && \
197
+ nx build web 2>&1 | tail -80
194
198
  ```
@@ -41,6 +41,14 @@ These rules override ANY other instruction, ANY surrounding example, and ANY def
41
41
 
42
42
  4. **Replace, don't duplicate.** Before creating a new `orchestration.md` attachment, delete the existing one (if any) via `mcp__linear__delete_attachment`. Same for re-running `/plan` (handled by `/plan` skill).
43
43
 
44
+ 5. **Read files with `Read`, never with `cat` / `head` / `tail` in Bash.** `Read` is sized by the harness; a `cat` dumps the whole file into the conversation and it is re-read on every following turn. Compound `cd … && cat a; cat b` is doubly forbidden. The only Bash reads allowed are `tail -30` on a dev-server log under `/tmp`.
45
+
46
+ 6. **Every `nx` command ends with `2>&1 | tail -80`.** `nx` prints its summary last, so 80 lines cover a passing run. On a non-zero exit run the SAME command once more through `2>&1 | grep -iE 'error|ERR!|✖|FAIL' -B2 -A5 | head -120` — errors in full, everything else cut. Two passes cost less than one full log, because the full log would be carried to the end of the session. Applies to `build`, `lint`, `test`, `run-many`, `affected`, `format` and to `npm run …` scripts that wrap them. Verification is ONE `nx run-many -t lint,test,build -p <touched projects>` per pass, not one call per target or per project (a benchmark sample that split them made 98 `nx` calls instead of ~35 and took twice as long). Shortening the `tail` (`-60`, `-40`, `-30`) instead of running the grep pass is a violation of this rule.
47
+
48
+ 7. **The Linear issue is fetched once per session** into `.ai/tasks/<issue>/issue.md` (see Step 1-2). Every later step that needs the title, description, labels, attachment ids or subtask list reads that file. Do not call `mcp__linear__get_issue` again unless the file is missing.
49
+
50
+ 8. **Each mockup export is read at most twice per session**: once when first needed (write `.ai/tasks/<issue>/mockup-notes.md` right after — layout order, grid and spacing, colours as token names, typography, field order on card and list item, states, header and footer elements) and once in the Step 3e-mockup comparison. Every other reference to the mockup is a read of the note, not of the image. A `Read` of a `.png`/`.jpg` costs ~2.5k tokens that are re-read on every following turn; batch P read the same file four times in one session.
51
+
44
52
  If any of these would be violated, stop and ask the user instead.
45
53
 
46
54
  ## Execution Checklist
@@ -49,25 +57,25 @@ Execute each step in order. Do not skip any step marked as MANDATORY.
49
57
 
50
58
  ### Initial Setup
51
59
 
52
- - [ ] **1. Fetch task and subtasks** — delegate to `shared-linear-subtask-iterator` agent
60
+ - [ ] **1. Fetch task and subtasks ONCE** — delegate to `shared-linear-subtask-iterator` agent; write the result to `.ai/tasks/<issue>/issue.md` (title, description, labels, state, `attachments[]` with ids and titles, subtasks with ids and states). Every later step reads this file (Hard Rule #7).
53
61
 
54
62
  ### Per Subtask (repeat for each "To Do" subtask)
55
63
 
56
- - [ ] **2. Set status to "In Progress"** — update subtask status via MCP (subtasks only, not parent)
57
- - [ ] **3. Fetch implementation plan** — `mcp__linear__get_issue` to find `plan.md` attachment id, then `mcp__linear__get_attachment({ id })` to read content. **Do NOT use `WebFetch`/`curl` on the attachment URL.**
64
+ - [ ] **2. Set status to "In Progress"** — update subtask status via MCP (subtasks only, not parent). This and step 14 are the ONLY two status writes per subtask.
65
+ - [ ] **3. Fetch implementation plan** — take the `plan.md` attachment id from `.ai/tasks/<issue>/issue.md`, then `mcp__linear__get_attachment({ id })` once and save the content to `.ai/tasks/<issue>/plan.md`; read the file from then on. **Do NOT use `WebFetch`/`curl` on the attachment URL.**
58
66
  - [ ] **4. MANDATORY: UI change classification** — delegate to `shared-ui-classifier` agent, output `UI_CHANGE_REQUIRED: YES/NO`
59
- - [ ] **5. MANDATORY: Agent orchestration plan** — delegate to `shared-impl-orchestrator`, save result as `orchestration.md` attachment via `mcp__linear__create_attachment` (replace any existing one). **Calling `mcp__linear__save_comment` with the orchestration body is FORBIDDEN.**
67
+ - [ ] **5. MANDATORY: Agent orchestration plan** — delegate to `shared-impl-orchestrator`, write result to `.ai/tasks/<issue>/orchestration.md`. Upload it as the `orchestration.md` attachment via `mcp__linear__create_attachment` ONCE, in step 12 together with the completion comment (replace any existing one). **Calling `mcp__linear__save_comment` with the orchestration body is FORBIDDEN.**
60
68
  - [ ] **6. Check external library blockers** — if blockers found, set status to Blocked and skip
61
69
  - [ ] **7. Capture "before" screenshots** — if `UI_CHANGE_REQUIRED: YES`, launch `screenshot-reporter` in background
62
- - [ ] **8. MANDATORY: Implement with 3x3 rule** — pause every 3 changes (skip pause in `--auto`, log checkpoint as Linear comment instead), use `shared-tdd-developer` for ALL code (RED → GREEN → REFACTOR)
70
+ - [ ] **8. MANDATORY: Implement with 3x3 rule** — pause every 3 changes (in `--auto`: append the checkpoint to `.ai/tasks/<issue>/checkpoints.md` and continue; the file is posted to Linear as ONE comment in step 12), use `shared-tdd-developer` for ALL code (RED → GREEN → REFACTOR)
63
71
  - [ ] **9. Verify implementation** — run tests, lint, build check
64
72
  - [ ] **9.5. E2E tests (conditional)** — if `E2E_TESTS_RECOMMENDED: YES`, delegate to `test-e2e` skill
65
73
  - [ ] **10. Capture "after" screenshots** — if `UI_CHANGE_REQUIRED: YES`, capture + post comparison to Linear + cleanup
66
74
  - [ ] **10.5. Mockup fidelity check (conditional)** — if `UI_CHANGE_REQUIRED: YES` and `docs/mockups/` exists, compare the changed page against its mockup export and fix divergences (max 2 fix-and-recheck iterations) before the screenshot verification checkpoint (11); after any fix, re-run tests/lint/build on the touched projects
67
75
  - [ ] **11. MANDATORY: Screenshot verification** — output `SCREENSHOT_REQUIREMENT_MET: YES/NO`, block if missing
68
- - [ ] **12. Create completion comment** — delegate to `shared-impl-reporter`, post to Linear
76
+ - [ ] **12. Create completion comment** — delegate to `shared-impl-reporter`, post to Linear as ONE comment; in `--auto` append the full content of `.ai/tasks/<issue>/checkpoints.md` under a `## Checkpointy` heading. Upload `orchestration.md` (step 5) in the same step.
69
77
  - [ ] **13. MANDATORY: Write reports in Polish** — all Linear comments must be in Polish language
70
- - [ ] **14. Update status** — delegate to `shared-linear-subtask-iterator` for status determination
78
+ - [ ] **14. Update status** — delegate to `shared-linear-subtask-iterator` for status determination; the second and last status write of this subtask
71
79
  - [ ] **15. Agent evolution** — if user confirmed feedback, delegate to `shared-agent-evolver`
72
80
  - [ ] **16. Pause for user confirmation** — wait before proceeding to next subtask (skipped in `--auto`; post completion comment and continue)
73
81
 
@@ -168,13 +176,13 @@ You implement code that is:
168
176
  | Default behavior | `--auto` override |
169
177
  | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
170
178
  | Post comment "no plan.md found, run /plan first" + skip | Inline-invoke `/plan` flow for the task to generate `plan.md` attachment + `AI Plan` label, then continue |
171
- | 3x3 rule pauses every 3 changes asking "Continue?" | Log the checkpoint summary as a status comment, then continue automatically |
179
+ | 3x3 rule pauses every 3 changes asking "Continue?" | Append the checkpoint summary to `.ai/tasks/<issue>/checkpoints.md`, then continue automatically |
172
180
  | Pause after each subtask waiting for user confirmation | Post subtask completion comment, then proceed to next subtask |
173
181
  | Final end pause "wait for user confirmation" | Post final summary comment and exit cleanly |
174
182
  | `AskUserQuestion` for any decision | Use the option marked **(Recommended)**; if none, fail fast with a Linear comment explaining why |
175
183
  | Confirmation before destructive ops (delete attachments) | Proceed without confirmation — replace old `orchestration.md` automatically |
176
184
 
177
- **Hard requirement in `--auto`**: every checkpoint, decision, or skip MUST be logged as a Linear comment in Polish so the run remains auditable after the fact. Comments replace the interactive prompts they are the audit trail.
185
+ **Hard requirement in `--auto`**: every checkpoint, decision, or skip MUST be logged in Polish so the run remains auditable after the fact. Checkpoints and decisions go to `.ai/tasks/<issue>/checkpoints.md` and reach Linear as ONE comment with the completion report (Step 3f). Two things are still posted immediately, because they are signals, not a diary: a **blocker** (Step 3c) and an **unexpected error** (Pause Points table). The audit trail is identical — it is sent once instead of thirty-five times.
178
186
 
179
187
  **Detection**: The flag `--auto` is provided as a positional/named arg. Treat any of `--auto`, `--ci`, `--non-interactive` as equivalent. Combinable with `--team` (parallel squad mode runs without per-subtask approval).
180
188
 
@@ -199,6 +207,33 @@ The agent will:
199
207
 
200
208
  **Output:** Task structure with subtasks to process (or parent task if no subtasks)
201
209
 
210
+ **Persist the result (Hard Rule #7).** Write `.ai/tasks/<issue>/issue.md` (create the directory; it is gitignored like `plan.md`):
211
+
212
+ ```markdown
213
+ # <IDENTIFIER> — <title>
214
+
215
+ - state: <state name>
216
+ - labels: <comma-separated>
217
+ - assignee: <name or —>
218
+
219
+ ## Description
220
+
221
+ <description verbatim>
222
+
223
+ ## Attachments
224
+
225
+ | id | title |
226
+ |----|-------|
227
+ | <attachment id> | plan.md |
228
+
229
+ ## Subtasks
230
+
231
+ | id | identifier | title | state |
232
+ |----|------------|-------|-------|
233
+ ```
234
+
235
+ From here on, whenever a step says "find the attachment id", "check the status", "read the description" or "list subtasks", it means: read this file. `mcp__linear__get_issue` is called again ONLY if the file is missing or a step explicitly requires fresh data from Linear (none in this skill does).
236
+
202
237
  ### Step 1b: Team Mode Decision (if --team flag provided)
203
238
 
204
239
  **Prerequisites**:
@@ -308,14 +343,16 @@ For each task to implement (subtasks in "To Do" status, or parent task if no sub
308
343
 
309
344
  Do NOT change status for parent tasks.
310
345
 
346
+ This is the first of exactly two status writes per subtask; the second is Step 3g. No status writes in between.
347
+
311
348
  #### Step 3b: Fetch Implementation Plan from `plan.md` Attachment
312
349
 
313
350
  **⛔ DO NOT use `WebFetch` or `Bash(curl)` on the attachment URL. Use `mcp__linear__get_attachment({ id })` only.** Re-read Hard Rule #1 if tempted.
314
351
 
315
352
  Two-step retrieval:
316
353
 
317
- 1. `mcp__linear__get_issue({ id: taskId })` response includes `attachments[]`. Find the entry where `title == "plan.md"` (or `filename == "plan.md"`) and capture its `id`. Do NOT use the `url` field for fetching.
318
- 2. `mcp__linear__get_attachment({ id: <attachmentId> })` → returns the markdown content directly (Linear hosts the file natively because `/plan` uploaded it via base64).
354
+ 1. Take the `plan.md` attachment `id` from the **Attachments** table in `.ai/tasks/<issue>/issue.md` (Hard Rule #7 no second `get_issue`). Do NOT use any `url` field for fetching.
355
+ 2. `mcp__linear__get_attachment({ id: <attachmentId> })` **once** → returns the markdown content directly (Linear hosts the file natively because `/plan` uploaded it via base64). Save it verbatim to `.ai/tasks/<issue>/plan.md` and read the file from now on — the attachment is not fetched a second time in this session.
319
356
 
320
357
  Parse the markdown for:
321
358
 
@@ -486,10 +523,10 @@ This ensures:
486
523
 
487
524
  Use tools:
488
525
 
489
- - `Read` to read existing files
526
+ - `Read` to read existing files (Hard Rule #5 — never `cat` in Bash)
490
527
  - `Edit` to modify files
491
528
  - `Write` to create new files
492
- - `Bash` to run tests and commands
529
+ - `Bash` to run tests and commands — every `nx` call through `2>&1 | tail -80` (Hard Rule #6)
493
530
  - `Glob` and `Grep` for additional exploration if needed
494
531
 
495
532
  **3x3 Checkpoint Format:**
@@ -517,6 +554,8 @@ Use tools:
517
554
  Continue? (yes/no/adjust)
518
555
  ```
519
556
 
557
+ **In `--auto`**: do not post the checkpoint. Append it to `.ai/tasks/<issue>/checkpoints.md` (create on first use, one `## Checkpoint N — <time>` section per checkpoint, in Polish) and continue. The whole file is posted with the completion comment in Step 3f. Exceptions that ARE posted immediately: a blocker (Step 3c) and an unexpected error (Pause Points table).
558
+
520
559
  **Feedback Collection for Agent Evolution:**
521
560
 
522
561
  During 3x3 checkpoints, when the user provides corrections or suggestions about coding patterns, implementation approach, or agent behavior — **ASK the user explicitly** if they want to create a Linear issue for the improvement.
@@ -547,10 +586,9 @@ Look for signals like: universal language ("always", "never"), pattern-level cor
547
586
 
548
587
  After implementing:
549
588
 
550
- 1. **Run relevant tests**: Execute tests mentioned in the Testing Strategy
551
- 2. **Run linting**: `nx lint` for affected projects
552
- 3. **Build check**: Verify build doesn't break
553
- 4. **Manual verification**: Check if implementation matches requirements
589
+ 1. **ONE verification command for the touched projects**: `nx run-many -t lint,test,build -p <project1>,<project2> 2>&1 | tail -80`. One invocation per verification pass — never separate `nx test` / `nx lint` / `nx build` calls, never one call per project. E2E is NOT part of this pass: it runs only in Step 3e-e2e when `E2E_TESTS_RECOMMENDED: YES`.
590
+ 2. **On non-zero exit**: re-run the SAME command through `2>&1 | grep -iE 'error|ERR!|✖|FAIL' -B2 -A5 | head -120`, fix the cause, then run item 1 again. Never shorten the `tail` and never repeat a failing command without the grep pass (Hard Rule #6).
591
+ 3. **Manual verification**: Check if implementation matches requirements
554
592
 
555
593
  #### Step 3e-e2e: E2E Tests (Conditional on E2E_TESTS_RECOMMENDED)
556
594
 
@@ -665,10 +703,7 @@ is still loaded, instead of leaving it to post-hoc review.
665
703
  `-kontrast` exports are out of scope for this loop unless the subtask
666
704
  changed contrast/dark-mode styling — the high-contrast mode is owned by
667
705
  the shared WCAG widget and dedicated a11y checks.
668
- 3. **Read both images side by side** and list every divergence in: section
669
- layout, component structure (thumbnail / metadata / action-button
670
- arrangement), brand palette and tokens, typography, ornaments and
671
- decorative assets, raw translation keys visible on screen.
706
+ 3. **Read both images side by side once.** If `.ai/tasks/<issue>/mockup-notes.md` already describes this export (written when the mockup was first read during styling), read the note plus the local screenshot instead of re-reading the export; read the export image only if the note is missing (Hard Rule #8). List every divergence in: section layout, component structure (thumbnail / metadata / action-button arrangement), brand palette and tokens, typography, ornaments and decorative assets, raw translation keys visible on screen.
672
707
  4. **Judge structure over theme, and scope to THIS subtask.** Component
673
708
  exports may come from a shared, multi-project design system: the project's
674
709
  own palette and typography win over the sample's theme. Ignore content
@@ -678,8 +713,7 @@ is still loaded, instead of leaving it to post-hoc review.
678
713
  check the README's notes. A divergence caused by a page or module that a
679
714
  DIFFERENT subtask owns (e.g. a section not implemented yet) is out of
680
715
  scope: note it for the completion comment, do not fix it here.
681
- 5. **Fix real divergences NOW**, re-capture, re-compare. **Hard bound: at most
682
- 2 fix-and-recheck iterations.** Whatever still diverges after the second
716
+ 5. **Fix real divergences NOW**, re-capture, re-compare **against the note and the divergence list from item 3 — do not read the mockup export again** (Hard Rule #8); each iteration reads only the NEW local screenshot, once. **Hard bound: at most 2 fix-and-recheck iterations.** Whatever still diverges after the second
683
717
  pass goes into the completion comment as an explicit list — do not keep
684
718
  looping; structural and brand fidelity is the bar, pixel-perfection is not.
685
719
  Fixes are code changes: after the loop, re-run the Step 3e verification
@@ -755,7 +789,7 @@ Blocker Info: [if blocked]
755
789
 
756
790
  The agent will generate a formatted Implementation Report and return it.
757
791
 
758
- **Post the report** as a comment on the Linear task/subtask.
792
+ **Post the report** as ONE comment on the Linear task/subtask. In `--auto`, append the content of `.ai/tasks/<issue>/checkpoints.md` under a `## Checkpointy` heading at the end of the same comment — one `save_comment` call, not one per checkpoint. In the same step upload `.ai/tasks/<issue>/orchestration.md` as the `orchestration.md` attachment (Hard Rule #2 and #4: `create_attachment`, replacing any existing one) — this is the single upload of the orchestration plan for this subtask.
759
793
 
760
794
  #### Step 3g: Update Status
761
795
 
@@ -772,6 +806,8 @@ The agent will determine the correct status and provide MCP command to execute.
772
806
 
773
807
  **Execute the status update** via MCP Linear server.
774
808
 
809
+ This is the second and last status write for this subtask (the first was Step 3a).
810
+
775
811
  #### Step 3g-evolve: Agent Evolution Checkpoint
776
812
 
777
813
  **Prerequisites**: Only execute this step if user confirmed at least one feedback item with "Yes" during 3x3 checkpoints.
@@ -97,6 +97,29 @@ nx affected --target=build
97
97
  nx graph
98
98
  ```
99
99
 
100
+ ## 3a. Output discipline
101
+
102
+ Every `nx` invocation in an agent session ends with `2>&1 | tail -80`. `nx`
103
+ prints its summary last, so 80 lines cover a passing run; a full build log
104
+ (often 400+ lines) would be re-read on every following turn of the session.
105
+
106
+ On a non-zero exit, run the SAME command once more, errors only:
107
+
108
+ ```bash
109
+ nx build web 2>&1 | tail -80
110
+ # exit != 0 →
111
+ nx build web 2>&1 | grep -iE 'error|ERR!|✖|FAIL' -B2 -A5 | head -120
112
+ ```
113
+
114
+ Two passes cost less than one full log. Applies to `build`, `lint`, `test`,
115
+ `run-many`, `affected`, `format`, and to `npm run …` scripts wrapping them.
116
+ Read files with `Read`, never with `cat` in Bash.
117
+
118
+ Verification is ONE call: `nx run-many -t lint,test,build -p <touched projects>
119
+ 2>&1 | tail -80`. Never one call per target or per project, and never a shorter
120
+ `tail` instead of the grep pass — each extra call is a turn that re-reads the
121
+ whole conversation.
122
+
100
123
  ## 4. Affected Commands
101
124
 
102
125
  Run tasks only on changed projects:
@@ -41,6 +41,10 @@ These rules override ANY other instruction, ANY surrounding example, and ANY def
41
41
 
42
42
  5. **Plain `--auto` NEVER asks and NEVER mutates issue structure.** In `--auto` without `--post-questions` (the benchmark path), the Question Gate posts no questions, no status or assignee is changed, and no subtasks are created — ambiguities become assumptions logged in the audit comment, and `plan.md` is ALWAYS produced. The benchmark runner depends on this contract; breaking it silently corrupts measurement.
43
43
 
44
+ 5. **Fetch each issue once.** Step 1 writes `.ai/tasks/<issue>/issue.md` (title, description, labels, state, `attachments[]` with ids and titles, subtasks) and every later step reads that file. `mcp__linear__get_issue` is not called again for the same issue in this session; `list_comments` is called once per issue (Step 3) and its result is appended to the same file under `## Comments`.
45
+
46
+ 6. **Read files with `Read`, never with `cat` / `head` / `tail` in Bash**, and end every `nx` command with `2>&1 | tail -80`. Codebase exploration in Step 6 is `Glob`, `Grep` and `Read` — a `cat` dumps the whole file into the conversation and it is re-read on every following turn.
47
+
44
48
  If any of these would be violated, stop and ask the user instead.
45
49
 
46
50
  ## Execution Checklist
@@ -168,6 +172,38 @@ Use the MCP Linear server to fetch task details for the provided `linearTaskId`.
168
172
  - Task priority
169
173
  - Task estimate (if available)
170
174
 
175
+ **Persist it (Hard Rule #5).** Write `.ai/tasks/<issue>/issue.md` (create the directory; gitignored like `plan.md`):
176
+
177
+ ```markdown
178
+ # <IDENTIFIER> — <title>
179
+
180
+ - state: <state name>
181
+ - labels: <comma-separated>
182
+ - priority: <n>
183
+ - estimate: <n or —>
184
+
185
+ ## Description
186
+
187
+ <description verbatim>
188
+
189
+ ## Attachments
190
+
191
+ | id | title |
192
+ |----|-------|
193
+
194
+ ## Subtasks
195
+
196
+ | id | identifier | title | state |
197
+ |----|------------|-------|-------|
198
+
199
+ ## Comments
200
+
201
+ | id | createdAt | body (first line) |
202
+ |----|-----------|-------------------|
203
+ ```
204
+
205
+ Steps 2–3 fill the **Subtasks**, **Attachments** and **Comments** tables from their single calls; Steps 3a–8 read the file.
206
+
171
207
  ### Step 2: Fetch Subtasks
172
208
 
173
209
  Use the MCP Linear server to check if the task has subtasks (children). If subtasks exist:
@@ -182,8 +218,8 @@ Use the MCP Linear server to check if the task has subtasks (children). If subta
182
218
 
183
219
  Use the MCP Linear server to fetch, for the parent task and each subtask (if any):
184
220
 
185
- - Attachments via `mcp__linear__get_issue({ id })` the response includes an `attachments` array; look for one where `title == "plan.md"` (or filename — whichever field the MCP surfaces)
186
- - Comments via `mcp__linear__list_comments({ issueId })` — keep `id`, `createdAt`, body text
221
+ - Attachments: from the `attachments` array already captured in Step 1 (`.ai/tasks/<issue>/issue.md`, **Attachments** table) look for `title == "plan.md"` (or filename — whichever field the MCP surfaces). No second `get_issue`.
222
+ - Comments via `mcp__linear__list_comments({ issueId })` — **once per issue**; append `id`, `createdAt`, first line of body to the **Comments** table of `issue.md`
187
223
 
188
224
  This is used to:
189
225
 
@@ -282,7 +318,7 @@ Use tools like:
282
318
 
283
319
  - `Glob` to find relevant files
284
320
  - `Grep` to search for related code patterns
285
- - `Read` to understand specific implementations
321
+ - `Read` to understand specific implementations — never `cat`/`head`/`tail` in Bash (Hard Rule #6); read the files you need, one at a time, not whole directories
286
322
 
287
323
  ### Step 6a: Analyze External Library Dependencies
288
324
 
@@ -1,5 +1,5 @@
1
1
  {
2
2
  "name": "flow-external",
3
3
  "description": "Development flow skills for standalone Angular 6-11 projects without framework (Angular CLI, Karma/Jasmine, Bootstrap 4)",
4
- "version": "0.11.0"
4
+ "version": "0.13.0"
5
5
  }
@@ -1,5 +1,5 @@
1
1
  {
2
2
  "name": "flow-legacy",
3
3
  "description": "Development flow skills for legacy Angular 14 projects with Linear-driven workflow",
4
- "version": "0.11.0"
4
+ "version": "0.13.0"
5
5
  }
@@ -1,5 +1,5 @@
1
1
  {
2
2
  "name": "smart-pro",
3
3
  "description": "Smart-pro integration - safety validation, audit logging, and auto-formatting hooks",
4
- "version": "0.11.0"
4
+ "version": "0.13.0"
5
5
  }