@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.
- package/README.md +91 -64
- package/agents/pwk-hazard-reviewer.md +24 -0
- package/agents/pwk-smell-reviewer.md +17 -0
- package/agents/pwk-spec-reviewer.md +14 -0
- package/agents/pwk-tracing-reviewer.md +14 -0
- package/docs/developer-usage-guide.md +49 -37
- package/docs/lessons.md +13 -0
- package/docs/oversight-model.md +19 -9
- package/docs/workflow-phases.md +58 -29
- package/extensions/workflow-guard.ts +190 -91
- package/package.json +19 -3
- package/skills/pwk-brainstorming/SKILL.md +60 -0
- package/skills/pwk-code-review/SKILL.md +46 -0
- package/skills/{diagnose → pwk-diagnose}/SKILL.md +3 -2
- package/skills/pwk-executing-tasks/SKILL.md +154 -0
- package/skills/pwk-finalizing/SKILL.md +78 -0
- package/skills/pwk-status/SKILL.md +28 -0
- package/skills/pwk-writing-plans/SKILL.md +83 -0
- package/docs/plans/2026-06-03-karpathy-guidelines-ab-comparison.md +0 -166
- package/docs/plans/completed/2026-04-11-checkpoint-review-gates-design.md +0 -50
- package/docs/plans/completed/2026-04-11-checkpoint-review-gates-implementation.md +0 -98
- package/docs/plans/completed/2026-04-11-finalizing-merge-options-design.md +0 -33
- package/docs/plans/completed/2026-04-11-finalizing-merge-options-implementation.md +0 -75
- package/docs/plans/completed/2026-04-11-workspace-setup-design.md +0 -28
- package/docs/plans/completed/2026-04-11-workspace-setup-implementation.md +0 -57
- package/docs/plans/completed/2026-04-15-bash-guard-design.md +0 -39
- package/docs/plans/completed/2026-04-15-bash-guard-implementation.md +0 -229
- package/docs/plans/completed/2026-04-21-workflow-guard-safe-commands-design.md +0 -172
- package/docs/plans/completed/2026-04-21-workflow-guard-safe-commands-implementation.md +0 -168
- package/docs/plans/completed/2026-04-22-go-readonly-safe-commands-implementation.md +0 -54
- package/docs/plans/completed/2026-04-28-executing-tasks-redesign-design.md +0 -171
- package/docs/plans/completed/2026-04-28-executing-tasks-redesign-implementation.md +0 -208
- package/docs/plans/completed/2026-04-28-executing-tasks-redesign-progress.md +0 -14
- package/docs/plans/completed/2026-05-01-incorporate-mattpocock-skills-design.md +0 -154
- package/docs/plans/completed/2026-05-01-incorporate-mattpocock-skills-implementation.md +0 -315
- package/docs/plans/completed/2026-05-01-incorporate-mattpocock-skills-progress.md +0 -15
- package/docs/plans/completed/2026-05-08-checkpoint-gates-design.md +0 -235
- package/docs/plans/completed/2026-05-08-checkpoint-gates-implementation.md +0 -83
- package/docs/plans/completed/2026-05-08-checkpoint-gates-progress.md +0 -11
- package/docs/plans/completed/2026-05-08-lessons-learned-design.md +0 -76
- package/docs/plans/completed/2026-05-08-lessons-learned-implementation.md +0 -219
- package/docs/plans/completed/2026-05-08-lessons-learned-progress.md +0 -15
- package/docs/plans/completed/2026-05-08-migrate-earendil-works-design.md +0 -39
- package/docs/plans/completed/2026-05-08-migrate-earendil-works-implementation.md +0 -45
- package/docs/plans/completed/2026-05-08-migrate-earendil-works-progress.md +0 -10
- package/docs/plans/completed/2026-05-08-worktree-handoff-design.md +0 -118
- package/docs/plans/completed/2026-05-08-worktree-handoff-implementation.md +0 -140
- package/docs/plans/completed/2026-05-08-worktree-handoff-progress.md +0 -10
- package/docs/plans/completed/2026-05-20-generic-lessons-design.md +0 -70
- package/docs/plans/completed/2026-05-20-generic-lessons-implementation.md +0 -114
- package/docs/plans/completed/2026-05-20-generic-lessons-progress.md +0 -11
- package/docs/plans/completed/2026-05-22-agentic-agile-enhancements-design.md +0 -77
- package/docs/plans/completed/2026-05-22-agentic-agile-enhancements-implementation.md +0 -473
- package/docs/plans/completed/2026-05-25-design-review-split-implementation.md +0 -622
- package/docs/plans/completed/2026-05-25-design-review-split-progress.md +0 -16
- package/docs/plans/completed/2026-05-25-pr5-improvements-implementation.md +0 -273
- package/docs/plans/completed/2026-05-25-pr5-improvements-progress.md +0 -17
- package/docs/plans/completed/2026-06-03-add-verify-skill-design.md +0 -51
- package/docs/plans/completed/2026-06-03-add-verify-skill-implementation.md +0 -111
- package/docs/plans/completed/2026-06-03-add-verify-skill-progress.md +0 -11
- package/docs/plans/completed/2026-06-03-verify-skill-design.md +0 -176
- package/skills/brainstorming/SKILL.md +0 -48
- package/skills/design-review/SKILL.md +0 -113
- package/skills/executing-tasks/SKILL.md +0 -350
- package/skills/finalizing/SKILL.md +0 -119
- package/skills/verify/SKILL.md +0 -170
- 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
|