@tianhai/pi-workflow-kit 0.17.1 → 1.0.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.
Files changed (67) hide show
  1. package/README.md +91 -64
  2. package/agents/pwk-hazard-reviewer.md +24 -0
  3. package/agents/pwk-smell-reviewer.md +17 -0
  4. package/agents/pwk-spec-reviewer.md +14 -0
  5. package/agents/pwk-tracing-reviewer.md +14 -0
  6. package/docs/developer-usage-guide.md +49 -37
  7. package/docs/lessons.md +13 -0
  8. package/docs/oversight-model.md +19 -9
  9. package/docs/workflow-phases.md +58 -29
  10. package/extensions/workflow-guard.ts +190 -91
  11. package/package.json +19 -3
  12. package/skills/pwk-brainstorming/SKILL.md +60 -0
  13. package/skills/pwk-code-review/SKILL.md +46 -0
  14. package/skills/{diagnose → pwk-diagnose}/SKILL.md +3 -2
  15. package/skills/pwk-executing-tasks/SKILL.md +154 -0
  16. package/skills/pwk-finalizing/SKILL.md +78 -0
  17. package/skills/pwk-status/SKILL.md +28 -0
  18. package/skills/pwk-writing-plans/SKILL.md +83 -0
  19. package/docs/plans/2026-06-03-karpathy-guidelines-ab-comparison.md +0 -166
  20. package/docs/plans/completed/2026-04-11-checkpoint-review-gates-design.md +0 -50
  21. package/docs/plans/completed/2026-04-11-checkpoint-review-gates-implementation.md +0 -98
  22. package/docs/plans/completed/2026-04-11-finalizing-merge-options-design.md +0 -33
  23. package/docs/plans/completed/2026-04-11-finalizing-merge-options-implementation.md +0 -75
  24. package/docs/plans/completed/2026-04-11-workspace-setup-design.md +0 -28
  25. package/docs/plans/completed/2026-04-11-workspace-setup-implementation.md +0 -57
  26. package/docs/plans/completed/2026-04-15-bash-guard-design.md +0 -39
  27. package/docs/plans/completed/2026-04-15-bash-guard-implementation.md +0 -229
  28. package/docs/plans/completed/2026-04-21-workflow-guard-safe-commands-design.md +0 -172
  29. package/docs/plans/completed/2026-04-21-workflow-guard-safe-commands-implementation.md +0 -168
  30. package/docs/plans/completed/2026-04-22-go-readonly-safe-commands-implementation.md +0 -54
  31. package/docs/plans/completed/2026-04-28-executing-tasks-redesign-design.md +0 -171
  32. package/docs/plans/completed/2026-04-28-executing-tasks-redesign-implementation.md +0 -208
  33. package/docs/plans/completed/2026-04-28-executing-tasks-redesign-progress.md +0 -14
  34. package/docs/plans/completed/2026-05-01-incorporate-mattpocock-skills-design.md +0 -154
  35. package/docs/plans/completed/2026-05-01-incorporate-mattpocock-skills-implementation.md +0 -315
  36. package/docs/plans/completed/2026-05-01-incorporate-mattpocock-skills-progress.md +0 -15
  37. package/docs/plans/completed/2026-05-08-checkpoint-gates-design.md +0 -235
  38. package/docs/plans/completed/2026-05-08-checkpoint-gates-implementation.md +0 -83
  39. package/docs/plans/completed/2026-05-08-checkpoint-gates-progress.md +0 -11
  40. package/docs/plans/completed/2026-05-08-lessons-learned-design.md +0 -76
  41. package/docs/plans/completed/2026-05-08-lessons-learned-implementation.md +0 -219
  42. package/docs/plans/completed/2026-05-08-lessons-learned-progress.md +0 -15
  43. package/docs/plans/completed/2026-05-08-migrate-earendil-works-design.md +0 -39
  44. package/docs/plans/completed/2026-05-08-migrate-earendil-works-implementation.md +0 -45
  45. package/docs/plans/completed/2026-05-08-migrate-earendil-works-progress.md +0 -10
  46. package/docs/plans/completed/2026-05-08-worktree-handoff-design.md +0 -118
  47. package/docs/plans/completed/2026-05-08-worktree-handoff-implementation.md +0 -140
  48. package/docs/plans/completed/2026-05-08-worktree-handoff-progress.md +0 -10
  49. package/docs/plans/completed/2026-05-20-generic-lessons-design.md +0 -70
  50. package/docs/plans/completed/2026-05-20-generic-lessons-implementation.md +0 -114
  51. package/docs/plans/completed/2026-05-20-generic-lessons-progress.md +0 -11
  52. package/docs/plans/completed/2026-05-22-agentic-agile-enhancements-design.md +0 -77
  53. package/docs/plans/completed/2026-05-22-agentic-agile-enhancements-implementation.md +0 -473
  54. package/docs/plans/completed/2026-05-25-design-review-split-implementation.md +0 -622
  55. package/docs/plans/completed/2026-05-25-design-review-split-progress.md +0 -16
  56. package/docs/plans/completed/2026-05-25-pr5-improvements-implementation.md +0 -273
  57. package/docs/plans/completed/2026-05-25-pr5-improvements-progress.md +0 -17
  58. package/docs/plans/completed/2026-06-03-add-verify-skill-design.md +0 -51
  59. package/docs/plans/completed/2026-06-03-add-verify-skill-implementation.md +0 -111
  60. package/docs/plans/completed/2026-06-03-add-verify-skill-progress.md +0 -11
  61. package/docs/plans/completed/2026-06-03-verify-skill-design.md +0 -176
  62. package/skills/brainstorming/SKILL.md +0 -48
  63. package/skills/design-review/SKILL.md +0 -113
  64. package/skills/executing-tasks/SKILL.md +0 -350
  65. package/skills/finalizing/SKILL.md +0 -119
  66. package/skills/verify/SKILL.md +0 -170
  67. package/skills/writing-plans/SKILL.md +0 -343
@@ -1,172 +0,0 @@
1
- # Workflow Guard: Safe Commands Expansion
2
-
3
- **Date:** 2026-04-21
4
- **Status:** Draft
5
-
6
- ## Problem
7
-
8
- The workflow guard blocks several read-only bash commands that are genuinely needed during brainstorm and plan phases. Two specific user reports:
9
-
10
- 1. `cd /path && git remote -v 2>/dev/null; echo "---"; ls` — blocked due to `cd` not being allowlisted and `2>/dev/null` caught by the stdout-redirect pattern.
11
- 2. `gh pr view 1564 --json ... 2>/dev/null || echo "gh failed"` — blocked because `gh` is not allowlisted at all.
12
-
13
- Additionally, `git status --short` is blocked because the safe regex only allows `git status` without flags.
14
-
15
- ## Design
16
-
17
- ### 1. Harmless redirect stripping
18
-
19
- Add a `stripHarmlessRedirects(cmd)` helper that removes `2>/dev/null` and `2>&1` before pattern matching. These are purely cosmetic (suppress stderr noise) and have no side effects.
20
-
21
- ```ts
22
- function stripHarmlessRedirects(cmd: string): string {
23
- return cmd.replace(/\s*2\s*>\s*(\/dev\/null|&1)\b/g, "");
24
- }
25
- ```
26
-
27
- Apply it inside `isSafeCommand` on each sub-command before checking DESTRUCTIVE and SAFE patterns. This fixes `2>/dev/null` without loosening the redirect catch (which still blocks real writes).
28
-
29
- ### 2. New SAFE_PATTERNS entries
30
-
31
- | Pattern | Rationale |
32
- |---------|-----------|
33
- | `/^\s*cd\b/` | Directory navigation — zero side effects |
34
- | `/^\s*gh\s+pr\s+(view\|list\|diff\|checks\|status)\b/i` | Read-only PR inspection |
35
- | `/^\s*gh\s+issue\s+(view\|list)\b/i` | Read-only issue inspection |
36
- | `/^\s*gh\s+repo\s+(view\|fork\|list)\b/i` | Read-only repo metadata |
37
- | `/^\s*gh\s+release\s+(view\|list\|download)\b/i` | Read-only release inspection |
38
- | `/^\s*gh\s+run\s+(view\|list)\b/i` | Read-only CI run inspection |
39
- | `/^\s*git\s+blame\b/` | Read-only file annotation |
40
- | `/^\s*git\s+shortlog\b/` | Read-only commit summary |
41
- | `/^\s*git\s+stash\s+list\b/i` | Read-only stash listing |
42
- | `/^\s*git\s+tag\s+(-l\|--list)\b/i` | Read-only tag listing |
43
- | `/^\s*git\s+describe\b/` | Read-only version info |
44
-
45
- ### 3. Fix: `git status` flag handling
46
-
47
- Current regex `/^\s*git\s+(status|log|...)/i` doesn't allow common flags like `--short`, `--oneline`, `--format=...`. Refine all git safe patterns to optionally accept trailing flags and args:
48
-
49
- ```ts
50
- /^\s*git\s+status\b/i,
51
- /^\s*git\s+log\b/i,
52
- /^\s*git\s+diff\b/i,
53
- /^\s*git\s+show\b/i,
54
- /^\s*git\s+blame\b/i,
55
- // etc.
56
- ```
57
-
58
- The existing patterns already anchor to `^\s*git\s+<subcommand>` — the issue was that `git status --short` didn't match because some patterns had more restrictive anchoring. Reviewing the code: the patterns use `\b` word boundaries which should allow flags. The actual issue with `git status --short && git log --oneline -5` is that the `git log --oneline -5` part is safe, but `git status --short` — let me verify: `/^\s*git\s+(status|log|diff|show|branch|remote|config\s+--get)/i` — `git status` has a `\b` after the group? No, there's no trailing `\b`. So `git status --short` **should** match since the pattern doesn't require end-of-string. The real blocker for that compound command was the `&&` splitting — `git log --oneline -5` — `-5` shouldn't be an issue either.
59
-
60
- **Conclusion on item 3:** The `git status --short` case was a false alarm caused by compound command parsing combined with the `2>/dev/null` redirect in the user's actual commands, not a pattern bug. No change needed here beyond the redirect fix.
61
-
62
- ### 4. What we're NOT adding (YAGNI)
63
-
64
- - `sed -i` (in-place editing) — correctly destructive
65
- - `gh pr create/merge/close` — write operations
66
- - `curl -o file` (output to file) — the redirect catch blocks this
67
- - `cut`, `tr`, `column`, `base64` — rarely needed; can add later on demand
68
- - `gh api` — too broad; can be used for mutations. Require specific subcommands.
69
-
70
- ## Data flow
71
-
72
- No new data flow. The changes are purely additive to the pattern-matching logic in `isSafeCommand`.
73
-
74
- ## Error handling
75
-
76
- No new error paths. The existing block-and-warn behavior remains unchanged.
77
-
78
- ## Testing
79
-
80
- Manual verification with the exact commands that were blocked:
81
-
82
- 1. `cd /some/path && git remote -v 2>/dev/null; echo "---"; ls` → allowed
83
- 2. `gh pr view 1564 --repo owner/repo --json title,body,files 2>/dev/null || echo "gh failed"` → allowed
84
- 3. `git stash list` → allowed
85
- 4. `git tag -l` → allowed
86
- 5. `rm -rf /` → still blocked ✓
87
- 6. `git push origin main` → still blocked ✓
88
-
89
- ## Tests
90
-
91
- Add the following test cases to the existing `tests/workflow-guard.test.ts` `isSafeCommand` describe block:
92
-
93
- ### New: `cd` navigation
94
- ```ts
95
- it("allows cd", () => {
96
- expect(isSafeCommand("cd /some/path")).toBe(true);
97
- expect(isSafeCommand("cd src && ls")).toBe(true);
98
- });
99
- ```
100
-
101
- ### New: GitHub CLI read-only subcommands
102
- ```ts
103
- it("allows gh read-only subcommands", () => {
104
- expect(isSafeCommand("gh pr view 1564 --json title,body")).toBe(true);
105
- expect(isSafeCommand("gh pr list --repo owner/repo")).toBe(true);
106
- expect(isSafeCommand("gh pr diff 1564")).toBe(true);
107
- expect(isSafeCommand("gh issue view 42")).toBe(true);
108
- expect(isSafeCommand("gh issue list --label bug")).toBe(true);
109
- expect(isSafeCommand("gh repo view owner/repo")).toBe(true);
110
- expect(isSafeCommand("gh run view 12345")).toBe(true);
111
- });
112
-
113
- it("blocks gh write subcommands", () => {
114
- expect(isSafeCommand("gh pr create --title 'fix'")).toBe(false);
115
- expect(isSafeCommand("gh pr merge 1564")).toBe(false);
116
- expect(isSafeCommand("gh issue close 42")).toBe(false);
117
- expect(isSafeCommand("gh release create v1.0")).toBe(false);
118
- });
119
- ```
120
-
121
- ### New: Git read-only subcommands
122
- ```ts
123
- it("allows git read-only subcommands (new additions)", () => {
124
- expect(isSafeCommand("git blame src/index.ts")).toBe(true);
125
- expect(isSafeCommand("git shortlog -sn")).toBe(true);
126
- expect(isSafeCommand("git stash list")).toBe(true);
127
- expect(isSafeCommand("git tag -l")).toBe(true);
128
- expect(isSafeCommand("git tag --list 'v*'")).toBe(true);
129
- expect(isSafeCommand("git describe --tags")).toBe(true);
130
- });
131
-
132
- it("still blocks git stash mutations", () => {
133
- expect(isSafeCommand("git stash push -m 'wip'")).toBe(false);
134
- expect(isSafeCommand("git stash pop")).toBe(false);
135
- });
136
- ```
137
-
138
- ### New: Harmless stderr redirect stripping
139
- ```ts
140
- it("allows 2>/dev/null on safe commands", () => {
141
- expect(isSafeCommand("git remote -v 2>/dev/null")).toBe(true);
142
- expect(isSafeCommand("gh pr view 1564 2>/dev/null")).toBe(true);
143
- expect(isSafeCommand("npm list 2>/dev/null")).toBe(true);
144
- });
145
-
146
- it("allows 2>&1 on safe commands", () => {
147
- expect(isSafeCommand("git log 2>&1")).toBe(true);
148
- });
149
-
150
- it("still blocks stdout redirects even with stderr redirect present", () => {
151
- expect(isSafeCommand("echo 'hello' > file.ts 2>/dev/null")).toBe(false);
152
- expect(isSafeCommand("cat config > backup.txt 2>/dev/null")).toBe(false);
153
- });
154
- ```
155
-
156
- ### New: Compound commands from real user scenarios
157
- ```ts
158
- it("allows the exact user-reported blocked commands", () => {
159
- // Scenario 1: directory navigation + git remote + ls
160
- expect(isSafeCommand("cd /Users/u/partying/pt-room && git remote -v 2>/dev/null; echo '---'; ls")).toBe(true);
161
- // Scenario 2: gh pr view with fallback
162
- expect(isSafeCommand("gh pr view 1564 --repo olachat/pt-partying --json title,body,files,additions,deletions 2>/dev/null || echo 'gh failed'")).toBe(true);
163
- });
164
- ```
165
-
166
- ## Summary
167
-
168
- | Change | Location | Size |
169
- |--------|----------|------|
170
- | Add `stripHarmlessRedirects()` | Above `isSafeCommand` | ~3 lines |
171
- | Call it in `isSafeCommand` loop body | Inside `isSafeCommand` | 1 line changed |
172
- | Add 10 new SAFE_PATTERNS entries | `SAFE_PATTERNS` array | ~10 lines |
@@ -1,168 +0,0 @@
1
- # Workflow Guard: Safe Commands Expansion — Implementation Plan
2
-
3
- **Design:** `docs/plans/2026-04-21-workflow-guard-safe-commands-design.md`
4
- **Date:** 2026-04-21
5
-
6
- ---
7
-
8
- ## Task 1: Add `stripHarmlessRedirects` helper and wire it into `isSafeCommand`
9
-
10
- **Scenario:** Modifying tested code
11
- **File:** `extensions/workflow-guard.ts`
12
-
13
- 1. Run existing tests to confirm baseline:
14
- ```bash
15
- npx vitest run tests/workflow-guard.test.ts
16
- ```
17
- Expected: all pass.
18
-
19
- 2. Add `stripHarmlessRedirects` function above `isSafeCommand`:
20
- ```ts
21
- /** Strip stderr redirects that are purely cosmetic (no side effects). */
22
- function stripHarmlessRedirects(cmd: string): string {
23
- return cmd.replace(/\s*2\s*>\s*(\/dev\/null|&1)\b/g, "");
24
- }
25
- ```
26
-
27
- 3. Wire it into `isSafeCommand` — apply `stripHarmlessRedirects` to each part before pattern matching:
28
- ```ts
29
- export function isSafeCommand(command: string): boolean {
30
- const parts = splitCompoundCommand(command);
31
- return parts.every((part) => {
32
- const cleaned = stripHarmlessRedirects(part);
33
- const isDestructive = DESTRUCTIVE_PATTERNS.some((p) => p.test(cleaned));
34
- const isSafe = SAFE_PATTERNS.some((p) => p.test(cleaned));
35
- return !isDestructive && isSafe;
36
- });
37
- }
38
- ```
39
-
40
- 4. Run tests:
41
- ```bash
42
- npx vitest run tests/workflow-guard.test.ts
43
- ```
44
- Expected: all existing tests still pass (no behavior change yet since no new SAFE_PATTERNS).
45
-
46
- 5. Commit:
47
- ```bash
48
- git add extensions/workflow-guard.ts
49
- git commit -m "feat(workflow-guard): add stripHarmlessRedirects helper"
50
- ```
51
-
52
- ---
53
-
54
- ## Task 2: Add new SAFE_PATTERNS entries
55
-
56
- **Scenario:** Modifying tested code
57
- **File:** `extensions/workflow-guard.ts`
58
-
59
- 1. Add the following entries to the `SAFE_PATTERNS` array (after the existing `gh`-related area or at end):
60
-
61
- ```ts
62
- /^\s*cd\b/,
63
- /^\s*gh\s+pr\s+(view|list|diff|checks|status)\b/i,
64
- /^\s*gh\s+issue\s+(view|list)\b/i,
65
- /^\s*gh\s+repo\s+(view|fork|list)\b/i,
66
- /^\s*gh\s+release\s+(view|list|download)\b/i,
67
- /^\s*gh\s+run\s+(view|list)\b/i,
68
- /^\s*git\s+blame\b/,
69
- /^\s*git\s+shortlog\b/,
70
- /^\s*git\s+stash\s+list\b/i,
71
- /^\s*git\s+tag\s+(-l|--list)\b/i,
72
- /^\s*git\s+describe\b/,
73
- ```
74
-
75
- 2. Run tests:
76
- ```bash
77
- npx vitest run tests/workflow-guard.test.ts
78
- ```
79
- Expected: all existing tests pass.
80
-
81
- 3. Commit:
82
- ```bash
83
- git add extensions/workflow-guard.ts
84
- git commit -m "feat(workflow-guard): add safe patterns for cd, gh, and git read-only subcommands"
85
- ```
86
-
87
- ---
88
-
89
- ## Task 3: Add tests for `cd`, `gh`, git new subcommands, and redirect stripping
90
-
91
- **Scenario:** New feature (test-first)
92
- **File:** `tests/workflow-guard.test.ts`
93
-
94
- **checkpoint: test** — pause after writing failing tests, before implementation.
95
-
96
- > Note: Implementation was already done in Tasks 1–2. These tests should all pass immediately. The checkpoint label is kept for review purposes in case the user wants to verify test design.
97
-
98
- 1. Add the following test blocks inside the `describe("isSafeCommand", ...)` block, after the existing tests:
99
-
100
- ```ts
101
- it("allows cd", () => {
102
- expect(isSafeCommand("cd /some/path")).toBe(true);
103
- expect(isSafeCommand("cd src && ls")).toBe(true);
104
- });
105
-
106
- it("allows gh read-only subcommands", () => {
107
- expect(isSafeCommand("gh pr view 1564 --json title,body")).toBe(true);
108
- expect(isSafeCommand("gh pr list --repo owner/repo")).toBe(true);
109
- expect(isSafeCommand("gh pr diff 1564")).toBe(true);
110
- expect(isSafeCommand("gh issue view 42")).toBe(true);
111
- expect(isSafeCommand("gh issue list --label bug")).toBe(true);
112
- expect(isSafeCommand("gh repo view owner/repo")).toBe(true);
113
- expect(isSafeCommand("gh run view 12345")).toBe(true);
114
- });
115
-
116
- it("blocks gh write subcommands", () => {
117
- expect(isSafeCommand("gh pr create --title 'fix'")).toBe(false);
118
- expect(isSafeCommand("gh pr merge 1564")).toBe(false);
119
- expect(isSafeCommand("gh issue close 42")).toBe(false);
120
- expect(isSafeCommand("gh release create v1.0")).toBe(false);
121
- });
122
-
123
- it("allows git read-only subcommands (new additions)", () => {
124
- expect(isSafeCommand("git blame src/index.ts")).toBe(true);
125
- expect(isSafeCommand("git shortlog -sn")).toBe(true);
126
- expect(isSafeCommand("git stash list")).toBe(true);
127
- expect(isSafeCommand("git tag -l")).toBe(true);
128
- expect(isSafeCommand("git tag --list 'v*'")).toBe(true);
129
- expect(isSafeCommand("git describe --tags")).toBe(true);
130
- });
131
-
132
- it("still blocks git stash mutations", () => {
133
- expect(isSafeCommand("git stash push -m 'wip'")).toBe(false);
134
- expect(isSafeCommand("git stash pop")).toBe(false);
135
- });
136
-
137
- it("allows 2>/dev/null on safe commands", () => {
138
- expect(isSafeCommand("git remote -v 2>/dev/null")).toBe(true);
139
- expect(isSafeCommand("gh pr view 1564 2>/dev/null")).toBe(true);
140
- expect(isSafeCommand("npm list 2>/dev/null")).toBe(true);
141
- });
142
-
143
- it("allows 2>&1 on safe commands", () => {
144
- expect(isSafeCommand("git log 2>&1")).toBe(true);
145
- });
146
-
147
- it("still blocks stdout redirects even with stderr redirect present", () => {
148
- expect(isSafeCommand("echo 'hello' > file.ts 2>/dev/null")).toBe(false);
149
- expect(isSafeCommand("cat config > backup.txt 2>/dev/null")).toBe(false);
150
- });
151
-
152
- it("allows the exact user-reported blocked commands", () => {
153
- expect(isSafeCommand("cd /Users/u/partying/pt-room && git remote -v 2>/dev/null; echo '---'; ls")).toBe(true);
154
- expect(isSafeCommand("gh pr view 1564 --repo olachat/pt-partying --json title,body,files,additions,deletions 2>/dev/null || echo 'gh failed'")).toBe(true);
155
- });
156
- ```
157
-
158
- 2. Run tests:
159
- ```bash
160
- npx vitest run tests/workflow-guard.test.ts
161
- ```
162
- Expected: all tests pass (including new ones).
163
-
164
- 3. Commit:
165
- ```bash
166
- git add tests/workflow-guard.test.ts
167
- git commit -m "test(workflow-guard): add tests for cd, gh, git read-only subcommands, and redirect stripping"
168
- ```
@@ -1,54 +0,0 @@
1
- # Add Go read-only commands to workflow-guard safe list
2
-
3
- ## Context
4
-
5
- Go toolchain read-only commands (`go doc`, `go list`, `go version`, `go env`) are blocked during brainstorm/plan phases because they're not in `SAFE_PATTERNS`. These are purely read-only with no side effects and are commonly needed during code exploration.
6
-
7
- ## Tasks
8
-
9
- ### 1 — Add Go safe patterns [Modifying tested code]
10
-
11
- **File:** `extensions/workflow-guard.ts`
12
-
13
- Add four entries to `SAFE_PATTERNS`, after the `git describe` entry:
14
-
15
- ```ts
16
- /^\s*go\s+doc\b/,
17
- /^\s*go\s+list\b/,
18
- /^\s*go\s+version\b/,
19
- /^\s*go\s+env\b/,
20
- ```
21
-
22
- **Verify:** run `npx vitest run tests/workflow-guard.test.ts` — all existing tests should pass.
23
-
24
- **Commit:** `feat(workflow-guard): add Go read-only commands to safe list`
25
-
26
- ### 2 — Add tests for Go safe commands [New feature]
27
-
28
- **File:** `tests/workflow-guard.test.ts`
29
-
30
- Add a new `it` block inside the `describe("isSafeCommand", ...)` suite:
31
-
32
- ```ts
33
- it("allows go read-only subcommands", () => {
34
- expect(isSafeCommand("go doc go.opentelemetry.io/otel/label")).toBe(true);
35
- expect(isSafeCommand("go doc go.opentelemetry.io/otel/codes 2>&1 | head -20")).toBe(true);
36
- expect(isSafeCommand("go list -m -versions go.opentelemetry.io/otel 2>&1 | tr ' ' '\\n' | grep -E '^v1\\\\.(2[89]|[3-9][0-9])' | head -20")).toBe(true);
37
- expect(isSafeCommand("go version")).toBe(true);
38
- expect(isSafeCommand("go env GOOS GOARCH")).toBe(true);
39
- });
40
- ```
41
-
42
- Also add a `go build` block test to ensure write-oriented Go commands stay blocked:
43
-
44
- ```ts
45
- it("blocks go write subcommands", () => {
46
- expect(isSafeCommand("go build ./...")).toBe(false);
47
- expect(isSafeCommand("go install golang.org/x/tools/gopls@latest")).toBe(false);
48
- expect(isSafeCommand("go mod tidy")).toBe(false);
49
- });
50
- ```
51
-
52
- **Verify:** run `npx vitest run tests/workflow-guard.test.ts` — all tests pass.
53
-
54
- **Commit:** `test(workflow-guard): add tests for Go read-only safe commands`
@@ -1,171 +0,0 @@
1
- # Design: Executing Tasks Redesign
2
-
3
- **Date:** 2026-04-28
4
- **Status:** Approved
5
-
6
- ## Problem
7
-
8
- The current `executing-tasks` skill has three issues:
9
-
10
- 1. **No progress tracking** — tasks are iterated in-memory with no file-based state. If the session crashes or the user starts a new session, all progress is lost.
11
- 2. **High token consumption** — the entire plan, all implementation work, and accumulated tool outputs stay in a single session. Even with auto-compaction, the LLM re-reads the full plan repeatedly.
12
- 3. **No context separation** — one monolithic thread handles everything. Early tasks' tool outputs bleed into later tasks' context.
13
-
14
- ## Solution Overview
15
-
16
- Introduce a **progress file** as the single source of truth for task state, and design the skill to work naturally across **multiple sessions** with fresh context.
17
-
18
- ### Core Principles
19
-
20
- - The progress file is the state — not the session, not git history
21
- - Each task is an isolated unit of work — the agent reads only what it needs
22
- - The agent suggests `/new` (fresh session) at natural break points
23
- - Resume is trivial — re-invoke the skill, it reads the progress file and picks up
24
-
25
- ## Progress File
26
-
27
- **Path:** `docs/plans/YYYY-MM-DD-<topic>-progress.md`
28
-
29
- Created by `executing-tasks` on first run by parsing the implementation plan.
30
-
31
- **Format:**
32
-
33
- ```markdown
34
- # Progress: auth
35
-
36
- Plan: docs/plans/2026-04-28-auth-implementation.md
37
- Branch: auth
38
- Started: 2026-04-28T10:00:00Z
39
- Last updated: 2026-04-28T10:45:00Z
40
-
41
- | # | Status | Task | Commit |
42
- |---|--------|------|--------|
43
- | 1 | ✅ done | Create User model | a1b2c3d |
44
- | 2 | ✅ done | Write User model tests | e4f5g6h |
45
- | 3 | 🔄 in-progress | Add login endpoint | — |
46
- | 4 | ⬜ pending | Write login tests | — |
47
- | 5 | ⏭ skipped | checkpoint: test — Add auth middleware | — |
48
- ```
49
-
50
- **Status values:**
51
-
52
- | Status | Meaning |
53
- |--------|---------|
54
- | `⬜ pending` | Not started |
55
- | `🔄 in-progress` | Currently being worked on |
56
- | `✅ done` | Committed successfully |
57
- | `❌ failed` | Could not complete (with reason appended) |
58
- | `⏭ skipped` | User chose to skip |
59
-
60
- **Rules:**
61
-
62
- - Mark `🔄 in-progress` immediately when starting a task
63
- - Mark `✅ done` + record commit hash only after successful `git commit`
64
- - Mark `❌ failed` + append `Failed: <reason>` when the agent can't proceed after retrying
65
- - Mark `⏭ skipped` when the user says "skip"
66
- - Update `Last updated` timestamp on every change
67
- - Preserve checkpoint labels from the plan in the task description
68
-
69
- ## Implementation Plan Format
70
-
71
- No file splitting. Keep one `implementation.md` but enforce a strict heading format:
72
-
73
- ```markdown
74
- ## Task 1: Create User model
75
-
76
- <!-- tdd: new-feature -->
77
- <!-- checkpoint: none -->
78
-
79
- - Create `src/models/user.ts`...
80
- ```
81
-
82
- The agent reads the progress file to find the current task number, then reads only that task's section from the implementation plan (via grep/jump to heading).
83
-
84
- ## Session Lifecycle
85
-
86
- ### First Run
87
-
88
- 1. Read progress file → doesn't exist
89
- 2. Parse implementation.md, create progress file with all tasks as `⬜ pending`
90
- 3. Ensure on correct branch / worktree (same as current skill)
91
- 4. Read task 1 section, begin work
92
-
93
- ### Continuing in Same Session
94
-
95
- After completing a non-checkpoint task:
96
- 1. Update progress file: current task → `✅ done`
97
- 2. Peek at next task:
98
- - **Has checkpoint** → pause for review (stay in session)
99
- - **No checkpoint** → continue working on next task
100
- 3. After ~3-5 non-checkpoint tasks, suggest `/new`:
101
-
102
- ```
103
- ✅ Tasks 3-5 done (commits: a1b2, e4f5, i7j8)
104
-
105
- Progress: 5/10 tasks done
106
-
107
- ⏭ Next: Task 6 — Add auth middleware (no checkpoint)
108
-
109
- 💡 Context is building up. For clean context on remaining tasks:
110
- /new then /skill:executing-tasks
111
- (or just say "continue" to keep going here)
112
- ```
113
-
114
- ### Resuming in a New Session
115
-
116
- 1. Read progress file → find first `⬜ pending` or `❌ failed` task
117
- 2. Read that task's section from implementation.md
118
- 3. Continue work — no re-reading of earlier tasks
119
-
120
- ### Checkpoint Review
121
-
122
- Same as current skill — show what was done, show the diff, wait for user approval:
123
-
124
- ```
125
- ⏸ Paused at checkpoint: test for task 4
126
-
127
- **What was done:** [brief summary]
128
- **Diff:** [show relevant diff]
129
-
130
- Review and let me know how to proceed.
131
- ```
132
-
133
- ## Resume & Failure Recovery
134
-
135
- | Scenario | What the agent sees | What it does |
136
- |----------|-------------------|--------------|
137
- | **Clean resume** | Next task is `⬜ pending` | Read task section, start working |
138
- | **Mid-task crash** | A task is `🔄 in-progress` | Check git log since last done task. If commits exist → ask user to verify. If no commits → restart the task |
139
- | **Failed task** | A task is `❌ failed` | Show failure reason, ask: retry, skip, or abort? |
140
- | **All done** | No `⬜ pending` or `❌ failed` | Show summary, suggest `/skill:finalizing` |
141
- | **No progress file** | File doesn't exist | Parse implementation.md, create progress file, start from task 1 |
142
- | **Skipped tasks remain** | `⏭ skipped` tasks exist | Noted in finalizing, no action during execution |
143
-
144
- ## User Override Commands
145
-
146
- Available at any time during execution:
147
-
148
- | User says | Agent does |
149
- |-----------|-----------|
150
- | `skip` | Mark current task `⏭ skipped`, move to next |
151
- | `status` | Show the progress table |
152
- | `stop` | Mark current task back to `⬜ pending`, suggest `/new` |
153
- | `retry` | Re-read current task section, start over |
154
-
155
- ## Changes to Other Skills
156
-
157
- ### writing-plans (minor)
158
-
159
- - Enforce `## Task N: <description>` heading format
160
- - Optional metadata comments: `<!-- tdd: ... -->` and `<!-- checkpoint: ... -->`
161
- - Everything else stays the same
162
-
163
- ### finalizing (minor)
164
-
165
- - Warn on skipped tasks before archiving: "Tasks 4 and 7 were skipped. Continue with finalizing, or go back?"
166
- - Archive the progress file to `docs/plans/completed/`
167
- - Use progress file for PR/commit summaries instead of re-reading the full plan
168
-
169
- ### brainstorming
170
-
171
- - No changes