Skip to content

Commit 4567174

Browse files
markhazletonmarkhazleton
committed
feat: Enhance devspark commands with new scripts and validation processes
- Added scripts for creating new features in both Bash and PowerShell. - Updated user input handling to use {ARGS} for consistency across commands. - Introduced a new command for addressing PR review findings, enforcing commit isolation. - Implemented atomic prompt shims for legacy commands to ensure backward compatibility. - Enhanced validation processes for specifications and tasks, ensuring quality and completeness. - Added a PowerShell wrapper for running workflows, improving usability. - Created a new agent for addressing PR reviews, allowing for personalized command execution.
1 parent 60f0900 commit 4567174

31 files changed

Lines changed: 637 additions & 61 deletions

‎.devspark/VERSION‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
version: 2.0.0
2-
installed: 2026-04-16
1+
version: 2.1.0
2+
installed: 2026-04-18
33
method: copilot-quickstart
4-
migrated-from: fresh
4+
migrated-from: 2.0.0

‎.devspark/defaults/commands/devspark.address-pr-review.md‎

Lines changed: 174 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
1+
---
2+
description: Address open PR review findings with enforced commit isolation between code fixes and review-file updates
3+
handoffs:
4+
- label: Re-Review Updated PR
5+
agent: devspark.pr-review
6+
prompt: Run /devspark.pr-review UPDATE for this PR after fixes are committed
7+
scripts:
8+
sh: pwsh -File .devspark/scripts/powershell/address-pr-review.ps1 -PrId $ARGUMENTS -Json
9+
ps: .devspark/scripts/powershell/address-pr-review.ps1 -PrId $ARGUMENTS -Json
10+
---
11+
12+
## User Input
13+
14+
```text
15+
$ARGUMENTS
16+
```
17+
18+
You **MUST** consider the user input before proceeding (if not empty).
19+
20+
## Overview
21+
22+
This command is the **author-side companion** to `/devspark.pr-review`. It helps you address open findings in `/.documentation/specs/pr-review/pr-{PR_ID}.md` while enforcing commit isolation:
23+
24+
1. Commit code fixes first.
25+
2. Commit review-file updates second.
26+
27+
**IMPORTANT**: The staging gates are mechanical and mandatory. Do not bypass them.
28+
29+
## Prerequisites
30+
31+
- Existing PR review file at `/.documentation/specs/pr-review/pr-{PR_ID}.md`
32+
- Git repository with the PR source branch checked out
33+
- PowerShell 7+ (`pwsh`) available for the gate helper script
34+
35+
## Outline
36+
37+
### Phase 0 — Load context
38+
39+
> **Script Resolution**: Before running `{SCRIPT}`, apply the 2-tier override check for PowerShell only — if `.documentation/scripts/powershell/address-pr-review.ps1` exists on disk, run that file instead, preserving all arguments. Team override in `.documentation/scripts/powershell/` takes priority over `.devspark/scripts/powershell/`.
40+
41+
1. Run `{SCRIPT}` with `-PrId {PR_ID} -Json`.
42+
2. Fail fast if `/.documentation/specs/pr-review/pr-{PR_ID}.md` is missing.
43+
3. Parse open findings from checklist lines matching:
44+
- `- [ ] **C-##**`
45+
- `- [ ] **H-##**`
46+
- `- [ ] **M-##**`
47+
- `- [ ] **L-##**`
48+
- `- [ ] **CON-##**`
49+
4. Confirm current branch equals the PR source branch. Refuse if mismatched.
50+
5. Capture `git status --short`.
51+
6. **Refuse to proceed** if any staged path matches `.documentation/specs/pr-review/pr-*.md`.
52+
53+
If no open findings remain, print: `Nothing to address.` and stop.
54+
55+
### Phase 1 — Plan
56+
57+
1. Render open findings as a checklist with severity badges.
58+
2. Ask which findings to address this iteration (`all` allowed).
59+
3. Build an internal todo list with one item per selected finding.
60+
61+
### Phase 2 — Fix loop (per finding)
62+
63+
For each selected finding:
64+
65+
1. Read the cited file/lines and confirm the issue.
66+
2. Apply the recommended fix, or propose an alternative and show the diff.
67+
3. Stage **only** code paths touched by that fix.
68+
4. Never run `git add .`.
69+
5. Never stage `/.documentation/specs/pr-review/pr-{PR_ID}.md` during this phase.
70+
71+
### Phase 3 — Validate
72+
73+
1. Re-run the **locked pytest scope** from the review file `Stats` table (reuse the same command; do not pick a new scope).
74+
2. Re-run project-specific validators explicitly recorded in the review file.
75+
3. If any validation fails, return to Phase 2.
76+
4. Do not continue until validations pass.
77+
78+
### Phase 4 — Commit code fixes (isolation gate #1)
79+
80+
1. Run gate script with `-Gate code-only` before commit.
81+
2. If the gate fails, **abort** and print offending staged paths.
82+
3. Review staged diff and commit with:
83+
84+
```text
85+
fix(pr-{PR_ID}): address {M-02,M-04,M-05}
86+
```
87+
88+
1. Capture the resulting short hash as `{FIX_SHA}`.
89+
90+
### Phase 5 — Update the review file
91+
92+
For each fixed finding:
93+
94+
1. Flip `- [ ]` to `- [x]`.
95+
2. Append `— *Fixed in {FIX_SHA}: {one-line how}*` to the finding heading line.
96+
3. Do **not** change finding IDs, descriptions, or broken/fix code blocks.
97+
98+
Then update metadata:
99+
100+
1. Bump revision in the header table (`Rev N -> Rev N+1`).
101+
2. Update `Stats` with current churn/test counts/commit snapshot.
102+
3. Append a new row to `Revision Log` for this iteration.
103+
4. Stage only `/.documentation/specs/pr-review/pr-{PR_ID}.md`.
104+
105+
### Phase 6 — Commit review file (isolation gate #2)
106+
107+
1. Run gate script with `-Gate review-only` before commit.
108+
2. If the gate fails, **abort** and print offending staged paths.
109+
3. Commit with:
110+
111+
```text
112+
review(pr-{PR_ID}): rev {N} — {X} fixed, {Y} remaining
113+
```
114+
115+
1. Verify commit disjointness:
116+
117+
```bash
118+
git log HEAD~2..HEAD --name-only
119+
```
120+
121+
Parse the two commits and assert they share zero file paths.
122+
123+
### Phase 7 — Handoff
124+
125+
1. Print both new commit hashes (`fix` and `review`).
126+
2. Suggest focused re-review:
127+
128+
```text
129+
Run `/devspark.pr-review UPDATE {PR_URL}` to trigger a focused re-review.
130+
```
131+
132+
## Guidelines
133+
134+
### Commit Discipline (MUST)
135+
136+
- A commit touching `/.documentation/specs/pr-review/pr-{PR_ID}.md` MUST NOT include any other path.
137+
- Code fixes and review-file updates MUST be separate commits.
138+
- Do not amend/squash these two commits together.
139+
140+
### Gate Execution (MUST)
141+
142+
- Use the helper script as the source of truth for staging gates.
143+
- If a gate exits non-zero, stop and resolve staging before retrying.
144+
145+
### Edit Scope (MUST)
146+
147+
In review files, limit edits to:
148+
149+
- finding checkbox state
150+
- heading-line fixed-in suffix
151+
- revision metadata (`Revision`, `Stats`, `Revision Log`)
152+
153+
Everything else is immutable during addressing.
154+
155+
## Context
156+
157+
$ARGUMENTS
158+
159+
## Shared Review Resolution Contract Output
160+
161+
When emitting findings (review observations, issues, recommendations), structure each entry to include the shared resolution contract fields so downstream tools (/devspark.address-pr-review, telemetry, harvest) can act on them deterministically:
162+
163+
```yaml
164+
findings:
165+
- finding_id: <stable-id-unique-within-this-command-output> # e.g., analyze-001, clarify-002
166+
severity: critical | high | medium | low
167+
description: <1-3 sentence problem statement>
168+
recommended_action: <machine-actionable next step>
169+
execution_mode: auto | selective | manual
170+
status: open # set to `resolved` after remediation
171+
outcome: "" # populated post-resolution by address-pr-review
172+
```
173+
174+
inding_id MUST be stable across re-runs when the underlying issue is unchanged. xecution_mode MUST be one of: `auto` (safe to apply automatically), `selective` (apply with reviewer approval), `manual` (requires human implementation). The `status` and `outcome` fields are written by `/devspark.address-pr-review` (FR-028).

‎.devspark/defaults/commands/devspark.analyze.md‎

Lines changed: 23 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,9 @@ handoffs:
77
- label: Revise Plan
88
agent: devspark.plan
99
prompt: Revise plan to address analysis findings
10+
scripts:
11+
sh: .devspark/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks
12+
ps: .devspark/scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks
1013
---
1114

1215
## User Input
@@ -35,9 +38,9 @@ Read the YAML frontmatter in `spec.md` before analyzing. Treat `classification`,
3538

3639
### 1. Initialize Analysis Context
3740

38-
> **Script Resolution**: Before running `.devspark/scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks`, apply the 2-tier override check — if `.documentation/scripts/powershell/<filename>` (PowerShell) or `.documentation/scripts/bash/<filename>` (Bash) exists on disk, run that file instead, preserving all arguments. Team overrides in `.documentation/scripts/` always take priority over `.devspark/scripts/`.
41+
> **Script Resolution**: Before running `{SCRIPT}`, apply the 2-tier override check — if `.documentation/scripts/powershell/<filename>` (PowerShell) or `.documentation/scripts/bash/<filename>` (Bash) exists on disk, run that file instead, preserving all arguments. Team overrides in `.documentation/scripts/` always take priority over `.devspark/scripts/`.
3942
40-
Run `.devspark/scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths:
43+
Run `{SCRIPT}` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths:
4144

4245
- SPEC = FEATURE_DIR/spec.md
4346
- PLAN = FEATURE_DIR/plan.md
@@ -211,4 +214,21 @@ After producing the report:
211214

212215
## Context
213216

214-
$ARGUMENTS
217+
{ARGS}
218+
219+
## Shared Review Resolution Contract Output
220+
221+
When emitting findings (review observations, issues, recommendations), structure each entry to include the shared resolution contract fields so downstream tools (/devspark.address-pr-review, telemetry, harvest) can act on them deterministically:
222+
223+
```yaml
224+
findings:
225+
- finding_id: <stable-id-unique-within-this-command-output> # e.g., analyze-001, clarify-002
226+
severity: critical | high | medium | low
227+
description: <1-3 sentence problem statement>
228+
recommended_action: <machine-actionable next step>
229+
execution_mode: auto | selective | manual
230+
status: open # set to `resolved` after remediation
231+
outcome: "" # populated post-resolution by address-pr-review
232+
```
233+
234+
inding_id MUST be stable across re-runs when the underlying issue is unchanged. xecution_mode MUST be one of: `auto` (safe to apply automatically), `selective` (apply with reviewer approval), `manual` (requires human implementation). The `status` and `outcome` fields are written by `/devspark.address-pr-review` (FR-028).

‎.devspark/defaults/commands/devspark.archive.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,9 @@ handoffs:
77
- label: Run Documentation Audit
88
agent: devspark.site-audit
99
prompt: Audit documentation quality and stale references before harvest
10+
scripts:
11+
sh: .devspark/scripts/bash/harvest.sh $ARGUMENTS --json
12+
ps: .devspark/scripts/powershell/harvest.ps1 $ARGUMENTS -Json
1013
---
1114

1215
## User Input
@@ -36,9 +39,9 @@ Treat every invocation of `/devspark.archive` as an invocation of `/devspark.har
3639

3740
### 1. Gather Context
3841

39-
> **Script Resolution**: Before running `.devspark/scripts/powershell/harvest.ps1 $ARGUMENTS -Json`, apply the 2-tier override check — if `.documentation/scripts/powershell/<filename>` (PowerShell) or `.documentation/scripts/bash/<filename>` (Bash) exists on disk, run that file instead, preserving all arguments. Team overrides in `.documentation/scripts/` always take priority over `.devspark/scripts/`.
42+
> **Script Resolution**: Before running `{SCRIPT}`, apply the 2-tier override check — if `.documentation/scripts/powershell/<filename>` (PowerShell) or `.documentation/scripts/bash/<filename>` (Bash) exists on disk, run that file instead, preserving all arguments. Team overrides in `.documentation/scripts/` always take priority over `.devspark/scripts/`.
4043
41-
Run `.devspark/scripts/powershell/harvest.ps1 $ARGUMENTS -Json` from the repo root. Parse the JSON output:
44+
Run `{SCRIPT}` from the repo root. Parse the JSON output:
4245

4346
- `REPO_ROOT` — absolute path to the repository root
4447
- `ARCHIVE_DIR` — target folder for today's archive (e.g., `.archive/2026-03-07`)

‎.devspark/defaults/commands/devspark.checklist.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,9 @@ handoffs:
77
- label: Run Analysis
88
agent: devspark.analyze
99
prompt: Analyze spec consistency after checklist review
10+
scripts:
11+
sh: .devspark/scripts/bash/check-prerequisites.sh --json
12+
ps: .devspark/scripts/powershell/check-prerequisites.ps1 -Json
1013
---
1114

1215
## Overview: "Unit Tests for English"
@@ -42,9 +45,9 @@ You **MUST** consider the user input before proceeding (if not empty).
4245

4346
**Multi-app support**: If this repository uses multi-app mode (`.documentation/devspark.json` exists with `mode: "multi-app"`), check for `--app <id>` in the user input to scope this workflow to a specific application. When app context is provided, resolve artifacts from `{app.path}/.documentation/` instead of the repository root `.documentation/`. Print the resolved scope (app name, doc root) at the start of output.
4447

45-
> **Script Resolution**: Before running `.devspark/scripts/powershell/check-prerequisites.ps1 -Json`, apply the 2-tier override check — if `.documentation/scripts/powershell/<filename>` (PowerShell) or `.documentation/scripts/bash/<filename>` (Bash) exists on disk, run that file instead, preserving all arguments. Team overrides in `.documentation/scripts/` always take priority over `.devspark/scripts/`.
48+
> **Script Resolution**: Before running `{SCRIPT}`, apply the 2-tier override check — if `.documentation/scripts/powershell/<filename>` (PowerShell) or `.documentation/scripts/bash/<filename>` (Bash) exists on disk, run that file instead, preserving all arguments. Team overrides in `.documentation/scripts/` always take priority over `.devspark/scripts/`.
4649
47-
1. **Setup**: Run `.devspark/scripts/powershell/check-prerequisites.ps1 -Json` from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS list.
50+
1. **Setup**: Run `{SCRIPT}` from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS list.
4851
- All file paths must be absolute.
4952
- For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
5053
- If `/.documentation/memory/constitution.md` exists, load it. Use constitution principles to inform checklist categories (e.g., if the constitution mandates accessibility, include accessibility items).

‎.devspark/defaults/commands/devspark.clarify.md‎

Lines changed: 23 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,9 @@ handoffs:
44
- label: Build Technical Plan
55
agent: devspark.plan
66
prompt: Create a plan for the spec. I am building with...
7+
scripts:
8+
sh: .devspark/scripts/bash/check-prerequisites.sh --json --paths-only
9+
ps: .devspark/scripts/powershell/check-prerequisites.ps1 -Json -PathsOnly
710
---
811

912
## User Input
@@ -24,9 +27,9 @@ Note: This clarification workflow is expected to run (and be completed) BEFORE i
2427

2528
Execution steps:
2629

27-
> **Script Resolution**: Before running `.devspark/scripts/powershell/check-prerequisites.ps1 -Json -PathsOnly`, apply the 2-tier override check — if `.documentation/scripts/powershell/<filename>` (PowerShell) or `.documentation/scripts/bash/<filename>` (Bash) exists on disk, run that file instead, preserving all arguments. Team overrides in `.documentation/scripts/` always take priority over `.devspark/scripts/`.
30+
> **Script Resolution**: Before running `{SCRIPT}`, apply the 2-tier override check — if `.documentation/scripts/powershell/<filename>` (PowerShell) or `.documentation/scripts/bash/<filename>` (Bash) exists on disk, run that file instead, preserving all arguments. Team overrides in `.documentation/scripts/` always take priority over `.devspark/scripts/`.
2831
29-
1. Run `.devspark/scripts/powershell/check-prerequisites.ps1 -Json -PathsOnly` from repo root **once** (combined `--json --paths-only` mode / `-Json -PathsOnly`). Parse minimal JSON payload fields:
32+
1. Run `{SCRIPT}` from repo root **once** (combined `--json --paths-only` mode / `-Json -PathsOnly`). Parse minimal JSON payload fields:
3033
- `FEATURE_DIR`
3134
- `FEATURE_SPEC`
3235
- (Optionally capture `IMPL_PLAN`, `TASKS` for future chained flows.)
@@ -188,4 +191,21 @@ Behavior rules:
188191
- If no questions asked due to full coverage, output a compact coverage summary (all categories Clear) then suggest advancing.
189192
- If quota reached with unresolved high-impact categories remaining, explicitly flag them under Deferred with rationale.
190193

191-
Context for prioritization: $ARGUMENTS
194+
Context for prioritization: {ARGS}
195+
196+
## Shared Review Resolution Contract Output
197+
198+
When emitting findings (review observations, issues, recommendations), structure each entry to include the shared resolution contract fields so downstream tools (/devspark.address-pr-review, telemetry, harvest) can act on them deterministically:
199+
200+
```yaml
201+
findings:
202+
- finding_id: <stable-id-unique-within-this-command-output> # e.g., analyze-001, clarify-002
203+
severity: critical | high | medium | low
204+
description: <1-3 sentence problem statement>
205+
recommended_action: <machine-actionable next step>
206+
execution_mode: auto | selective | manual
207+
status: open # set to `resolved` after remediation
208+
outcome: "" # populated post-resolution by address-pr-review
209+
```
210+
211+
inding_id MUST be stable across re-runs when the underlying issue is unchanged. xecution_mode MUST be one of: `auto` (safe to apply automatically), `selective` (apply with reviewer approval), `manual` (requires human implementation). The `status` and `outcome` fields are written by `/devspark.address-pr-review` (FR-028).

‎.devspark/defaults/commands/devspark.commit-audit.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,9 @@ handoffs:
77
- label: View Harvest Report
88
agent: devspark.harvest
99
prompt: Review completed specs and stale documentation before archiving
10+
scripts:
11+
sh: .devspark/scripts/bash/commit-audit.sh $ARGUMENTS --json
12+
ps: .devspark/scripts/powershell/commit-audit.ps1 $ARGUMENTS -Json
1013
---
1114

1215
## User Input
@@ -48,9 +51,9 @@ Multiple scope flags may be combined: `--scope=velocity,hygiene`
4851

4952
### 1. Initialize Audit Context
5053

51-
> **Script Resolution**: Before running `.devspark/scripts/powershell/commit-audit.ps1 $ARGUMENTS -Json`, apply the 2-tier override check — if `.documentation/scripts/powershell/<filename>` (PowerShell) or `.documentation/scripts/bash/<filename>` (Bash) exists on disk, run that file instead, preserving all arguments. Team overrides in `.documentation/scripts/` always take priority over `.devspark/scripts/`.
54+
> **Script Resolution**: Before running `{SCRIPT}`, apply the 2-tier override check — if `.documentation/scripts/powershell/<filename>` (PowerShell) or `.documentation/scripts/bash/<filename>` (Bash) exists on disk, run that file instead, preserving all arguments. Team overrides in `.documentation/scripts/` always take priority over `.devspark/scripts/`.
5255
53-
Run `.devspark/scripts/powershell/commit-audit.ps1 $ARGUMENTS -Json` and parse its JSON output.
56+
Run `{SCRIPT}` and parse its JSON output.
5457

5558
Expected fields include:
5659

‎.devspark/defaults/commands/devspark.create-pr.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,9 @@ handoffs:
44
- label: Review Pull Request
55
agent: devspark.pr-review
66
prompt: Review the pull request for constitution compliance
7+
scripts:
8+
sh: .devspark/scripts/bash/create-pr.sh --mode preflight --json $ARGUMENTS
9+
ps: .devspark/scripts/powershell/create-pr.ps1 -Mode Preflight -Json $ARGUMENTS
710
---
811

912
## User Input
@@ -34,9 +37,9 @@ This command is advisory. Dirty trees, missing specs, incomplete tasks, unresolv
3437

3538
### 1. Run Preflight Context
3639

37-
> **Script Resolution**: Before running `.devspark/scripts/powershell/create-pr.ps1 -Mode Preflight -Json $ARGUMENTS`, apply the 2-tier override check — if `.documentation/scripts/powershell/<filename>` (PowerShell) or `.documentation/scripts/bash/<filename>` (Bash) exists on disk, run that file instead, preserving all arguments. Team overrides in `.documentation/scripts/` always take priority over `.devspark/scripts/`.
40+
> **Script Resolution**: Before running `{SCRIPT}`, apply the 2-tier override check — if `.documentation/scripts/powershell/<filename>` (PowerShell) or `.documentation/scripts/bash/<filename>` (Bash) exists on disk, run that file instead, preserving all arguments. Team overrides in `.documentation/scripts/` always take priority over `.devspark/scripts/`.
3841
39-
Run `.devspark/scripts/powershell/create-pr.ps1 -Mode Preflight -Json $ARGUMENTS` once from the repository root and parse the returned JSON.
42+
Run `{SCRIPT}` once from the repository root and parse the returned JSON.
4043

4144
Use the script output as the source of truth for:
4245

0 commit comments

Comments
 (0)