hai/gstack
1
0
Fork 0
mirror of https://github.com/garrytan/gstack.git synced 2026-05-18 02:22:04 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'main' into garrytan/team-supabase-store

Browse Source 
Resolved conflicts across 23 files. Key merge decisions:
- Adopted main's TemplateContext type in gen-skill-docs.ts
- Adopted main's new features (trigger phrases, codex integration,
  analytics, proactive config, review chaining)
- Replaced gstack-review-log/gstack-review-read helpers with inline
  approach using $PROJECTS_DIR/$SLUG/reviews/$BRANCH.jsonl paths
- Added "commit":"COMMIT" field to all review log entries (from main)
- Kept our $PROJECTS_DIR/$SLUG path reorganization throughout
- Added Codex E2E test from main + our E2E isolation cleanup

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Garry Tan
2026-03-19 17:16:08 -07:00
parent fb7fe3d280 bd834aeadb
commit 0ffb4e9ec5
84 changed files with 8122 additions and 1234 deletions
Download Patch File Download Diff File Expand all files Collapse all files

90
design-review/SKILL.md
View File

@@ -6,6 +6,9 @@ description: |
AI slop patterns, and slow interactions — then fixes them. Iteratively fixes issues
in source code, committing each fix atomically and re-verifying with before/after
screenshots. For plan-mode design review (before implementation), use /plan-design-review.
Use when asked to "audit the design", "visual QA", "check if it looks good", or "design polish".
Proactively suggest when the user mentions visual inconsistencies or
wants to polish the look of a live site.
allowed-tools:
- Bash
- Read
@@ -29,12 +32,19 @@ touch ~/.gstack/sessions/"$PPID"
_SESSIONS=$(find ~/.gstack/sessions -mmin -120 -type f 2>/dev/null | wc -l | tr -d ' ')
find ~/.gstack/sessions -mmin +120 -type f -delete 2>/dev/null || true
_CONTRIB=$(~/.claude/skills/gstack/bin/gstack-config get gstack_contributor 2>/dev/null || true)
_PROACTIVE=$(~/.claude/skills/gstack/bin/gstack-config get proactive 2>/dev/null || echo "true")
_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
echo "BRANCH: $_BRANCH"
echo "PROACTIVE: $_PROACTIVE"
_LAKE_SEEN=$([ -f ~/.gstack/.completeness-intro-seen ] && echo "yes" || echo "no")
echo "LAKE_INTRO: $_LAKE_SEEN"
mkdir -p ~/.gstack/analytics
echo '{"skill":"design-review","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
```
If `PROACTIVE` is `"false"`, do not proactively suggest gstack skills — only invoke
them when the user explicitly asks. The user opted out of proactive suggestions.
If output shows `UPGRADE_AVAILABLE <old> <new>`: read `~/.claude/skills/gstack/gstack-upgrade/SKILL.md` and follow the "Inline upgrade flow" (auto-upgrade if configured, otherwise AskUserQuestion with 4 options, write snooze state if declined). If `JUST_UPGRADED <from> <to>`: tell user "Running gstack v{to} (just updated!)" and continue.
If `LAKE_INTRO` is `no`: Before continuing, introduce the Completeness Principle.
@@ -123,6 +133,31 @@ Hey gstack team — ran into this while using /{skill-name}:
Slug: lowercase, hyphens, max 60 chars (e.g. `browse-js-no-await`). Skip if file already exists. Max 3 reports per session. File inline and continue — don't stop the workflow. Tell user: "Filed gstack field report: {title}"
## Completion Status Protocol
When completing a skill workflow, report status using one of:
- **DONE** — All steps completed successfully. Evidence provided for each claim.
- **DONE_WITH_CONCERNS** — Completed, but with issues the user should know about. List each concern.
- **BLOCKED** — Cannot proceed. State what is blocking and what was tried.
- **NEEDS_CONTEXT** — Missing information required to continue. State exactly what you need.
### Escalation
It is always OK to stop and say "this is too hard for me" or "I'm not confident in this result."
Bad work is worse than no work. You will not be penalized for escalating.
- If you have attempted a task 3 times without success, STOP and escalate.
- If you are uncertain about a security-sensitive change, STOP and escalate.
- If the scope of work exceeds what you can verify, STOP and escalate.
Escalation format:
```
STATUS: BLOCKED | NEEDS_CONTEXT
REASON: [1-2 sentences]
ATTEMPTED: [what you tried]
RECOMMENDATION: [what the user should do next]
```
# /design-review: Design Audit → Fix → Verify
You are a senior product designer AND a frontend engineer. Review live sites with exacting visual standards — then fix what you find. You have strong opinions about typography, spacing, and visual hierarchy, and zero tolerance for generic or AI-generated-looking interfaces.
@@ -146,15 +181,24 @@ You are a senior product designer AND a frontend engineer. Review live sites wit
Look for `DESIGN.md`, `design-system.md`, or similar in the repo root. If found, read it — all design decisions must be calibrated against it. Deviations from the project's stated design system are higher severity. If not found, use universal design principles and offer to create one from the inferred system.
**Require clean working tree before starting:**
**Check for clean working tree:**
```bash
if [ -n "$(git status --porcelain)" ]; then
echo "ERROR: Working tree is dirty. Commit or stash changes before running /design-review."
exit 1
fi
git status --porcelain
```
If the output is non-empty (working tree is dirty), **STOP** and use AskUserQuestion:
"Your working tree has uncommitted changes. /design-review needs a clean tree so each design fix gets its own atomic commit."
- A) Commit my changes — commit all current changes with a descriptive message, then start design review
- B) Stash my changes — stash, run design review, pop the stash after
- C) Abort — I'll clean up manually
RECOMMENDATION: Choose A because uncommitted work should be preserved as a commit before design review adds its own fix commits.
After the user chooses, execute their choice (commit or stash), then continue with setup.
**Find the browse binary:**
## SETUP (run this check BEFORE any browse command)
@@ -810,40 +854,10 @@ Write the report to both local and project-scoped locations:
**Local:** `.gstack/design-reports/design-audit-{domain}-{YYYY-MM-DD}.md`
**Project-scoped:**
```bash
eval $(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)
DATE=$(date +%Y-%m-%d)
eval $(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null) && mkdir -p $PROJECTS_DIR/$SLUG
```
```bash
mkdir -p $PROJECTS_DIR/$SLUG/reports
FILE="$PROJECTS_DIR/$SLUG/reports/design-{domain}-$DATE.md"
[ -f "$FILE" ] && FILE="$PROJECTS_DIR/$SLUG/reports/design-{domain}-$DATE-$(date +%H%M).md"
```
Write to the file path resolved above. Include YAML frontmatter:
```yaml
---
type: design-audit
branch: {branch}
date: {YYYY-MM-DD}
skill: design-review
---
```
After writing, register in manifest:
```bash
~/.claude/skills/gstack/bin/gstack-manifest-append design-audit "reports/$(basename "$FILE")" design-review "$BRANCH"
```
**Screenshot upload:** After compiling the report, upload all screenshots:
```bash
for img in .gstack/design-reports/screenshots/*.png; do
[ -f "$img" ] && ~/.claude/skills/gstack/bin/gstack-upload "$img" 2>/dev/null
done
```
If upload succeeds, update the report to use hosted URLs. If it fails, keep local paths and append: `(screenshot not uploaded — run gstack sync to share)`
Write to `~/.gstack/projects/{slug}/{user}-{branch}-design-audit-{datetime}.md`
**Per-finding additions** (beyond standard design audit report):
- Fix Status: verified / best-effort / reverted / deferred
@@ -874,7 +888,7 @@ If the repo has a `TODOS.md`:
## Additional Rules (design-review specific)
11. **Clean working tree required.** Refuse to start if `git status --porcelain` is non-empty.
11. **Clean working tree required.** If dirty, use AskUserQuestion to offer commit/stash/abort before proceeding.
12. **One commit per fix.** Never bundle multiple design fixes into one commit.
13. **Only modify tests when generating regression tests in Phase 8e.5.** Never modify CI configuration. Never modify existing tests — only create new test files.
14. **Revert on regression.** If a fix makes things worse, `git revert HEAD` immediately.

55
design-review/SKILL.md.tmpl
View File

@@ -6,6 +6,9 @@ description: |
AI slop patterns, and slow interactions — then fixes them. Iteratively fixes issues
in source code, committing each fix atomically and re-verifying with before/after
screenshots. For plan-mode design review (before implementation), use /plan-design-review.
Use when asked to "audit the design", "visual QA", "check if it looks good", or "design polish".
Proactively suggest when the user mentions visual inconsistencies or
wants to polish the look of a live site.
allowed-tools:
- Bash
- Read
@@ -42,15 +45,24 @@ You are a senior product designer AND a frontend engineer. Review live sites wit
Look for `DESIGN.md`, `design-system.md`, or similar in the repo root. If found, read it — all design decisions must be calibrated against it. Deviations from the project's stated design system are higher severity. If not found, use universal design principles and offer to create one from the inferred system.
**Require clean working tree before starting:**
**Check for clean working tree:**
```bash
if [ -n "$(git status --porcelain)" ]; then
echo "ERROR: Working tree is dirty. Commit or stash changes before running /design-review."
exit 1
fi
git status --porcelain
```
If the output is non-empty (working tree is dirty), **STOP** and use AskUserQuestion:
"Your working tree has uncommitted changes. /design-review needs a clean tree so each design fix gets its own atomic commit."
- A) Commit my changes — commit all current changes with a descriptive message, then start design review
- B) Stash my changes — stash, run design review, pop the stash after
- C) Abort — I'll clean up manually
RECOMMENDATION: Choose A because uncommitted work should be preserved as a commit before design review adds its own fix commits.
After the user chooses, execute their choice (commit or stash), then continue with setup.
**Find the browse binary:**
{{BROWSE_SETUP}}
@@ -207,37 +219,10 @@ Write the report to both local and project-scoped locations:
**Local:** `.gstack/design-reports/design-audit-{domain}-{YYYY-MM-DD}.md`
**Project-scoped:**
{{ARTIFACT_SETUP}}
```bash
mkdir -p $PROJECTS_DIR/$SLUG/reports
FILE="$PROJECTS_DIR/$SLUG/reports/design-{domain}-$DATE.md"
[ -f "$FILE" ] && FILE="$PROJECTS_DIR/$SLUG/reports/design-{domain}-$DATE-$(date +%H%M).md"
eval $(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null) && mkdir -p $PROJECTS_DIR/$SLUG
```
Write to the file path resolved above. Include YAML frontmatter:
```yaml
---
type: design-audit
branch: {branch}
date: {YYYY-MM-DD}
skill: design-review
---
```
After writing, register in manifest:
```bash
~/.claude/skills/gstack/bin/gstack-manifest-append design-audit "reports/$(basename "$FILE")" design-review "$BRANCH"
```
**Screenshot upload:** After compiling the report, upload all screenshots:
```bash
for img in .gstack/design-reports/screenshots/*.png; do
[ -f "$img" ] && ~/.claude/skills/gstack/bin/gstack-upload "$img" 2>/dev/null
done
```
If upload succeeds, update the report to use hosted URLs. If it fails, keep local paths and append: `(screenshot not uploaded — run gstack sync to share)`
Write to `~/.gstack/projects/{slug}/{user}-{branch}-design-audit-{datetime}.md`
**Per-finding additions** (beyond standard design audit report):
- Fix Status: verified / best-effort / reverted / deferred
@@ -268,7 +253,7 @@ If the repo has a `TODOS.md`:
## Additional Rules (design-review specific)
11. **Clean working tree required.** Refuse to start if `git status --porcelain` is non-empty.
11. **Clean working tree required.** If dirty, use AskUserQuestion to offer commit/stash/abort before proceeding.
12. **One commit per fix.** Never bundle multiple design fixes into one commit.
13. **Only modify tests when generating regression tests in Phase 8e.5.** Never modify CI configuration. Never modify existing tests — only create new test files.
14. **Revert on regression.** If a fix makes things worse, `git revert HEAD` immediately.