From 4564cb18ed26c6638fcf684ef4c438c801ac51ae Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Wed, 18 Mar 2026 23:48:28 -0700 Subject: [PATCH] refactor: reorganize template write paths + add frontmatter + manifest All skill templates now write artifacts to subdirectories under $PROJECTS_DIR/$SLUG/ (reviews/, plans/, reports/). Adds YAML frontmatter to markdown artifacts and manifest-append calls. Templates updated: - plan-eng-review: plans/ + reviews/ - plan-ceo-review: plans/ceo/ + reviews/ - plan-design-review: reviews/ - ship: reviews/ - design-review: reports/ - qa: reports/ - qa-only: reports/ - review/greptile-triage: uses gstack-slug instead of remote-slug Co-Authored-By: Claude Opus 4.6 (1M context) --- design-review/SKILL.md.tmpl | 24 +++++++++++++++++++--- plan-ceo-review/SKILL.md.tmpl | 34 +++++++++++++++++++++----------- plan-design-review/SKILL.md.tmpl | 4 ++-- plan-eng-review/SKILL.md.tmpl | 26 +++++++++++++++++------- qa-only/SKILL.md.tmpl | 24 +++++++++++++++++++--- qa/SKILL.md.tmpl | 24 +++++++++++++++++++--- review/greptile-triage.md | 10 +++++----- ship/SKILL.md.tmpl | 4 ++-- 8 files changed, 113 insertions(+), 37 deletions(-) diff --git a/design-review/SKILL.md.tmpl b/design-review/SKILL.md.tmpl index eb8dd6b8..6d503e1a 100644 --- a/design-review/SKILL.md.tmpl +++ b/design-review/SKILL.md.tmpl @@ -207,11 +207,29 @@ 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 -eval $(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null) -mkdir -p ~/.gstack/projects/$SLUG +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" ``` -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 diff --git a/plan-ceo-review/SKILL.md.tmpl b/plan-ceo-review/SKILL.md.tmpl index 1a8b0658..1414d7f9 100644 --- a/plan-ceo-review/SKILL.md.tmpl +++ b/plan-ceo-review/SKILL.md.tmpl @@ -162,22 +162,27 @@ Describe the ideal end state of this system 12 months from now. Does this plan m After the opt-in/cherry-pick ceremony, write the plan to disk so the vision and decisions survive beyond this conversation. Only run this step for EXPANSION and SELECTIVE EXPANSION modes. -```bash -eval $(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null) -mkdir -p ~/.gstack/projects/$SLUG/ceo-plans -``` - -Before writing, check for existing CEO plans in the ceo-plans/ directory. If any are >30 days old or their branch has been merged/deleted, offer to archive them: +{{ARTIFACT_SETUP}} ```bash -mkdir -p ~/.gstack/projects/$SLUG/ceo-plans/archive -# For each stale plan: mv ~/.gstack/projects/$SLUG/ceo-plans/{old-plan}.md ~/.gstack/projects/$SLUG/ceo-plans/archive/ +mkdir -p $PROJECTS_DIR/$SLUG/plans/ceo ``` -Write to `~/.gstack/projects/$SLUG/ceo-plans/{date}-{feature-slug}.md` using this format: +Before writing, check for existing CEO plans in the plans/ceo/ directory. If any are >30 days old or their branch has been merged/deleted, offer to archive them: + +```bash +mkdir -p $PROJECTS_DIR/$SLUG/plans/ceo/archive +# For each stale plan: mv $PROJECTS_DIR/$SLUG/plans/ceo/{old-plan}.md $PROJECTS_DIR/$SLUG/plans/ceo/archive/ +``` + +Write to `$PROJECTS_DIR/$SLUG/plans/ceo/$DATE-{feature-slug}.md` using this format: ```markdown --- +type: ceo-plan +branch: {branch} +date: {YYYY-MM-DD} +skill: plan-ceo-review status: ACTIVE --- # CEO Plan: {Feature Name} @@ -208,6 +213,11 @@ Repo: {owner/repo} Derive the feature slug from the plan being reviewed (e.g., "user-dashboard", "auth-refactor"). Use the date in YYYY-MM-DD format. +After writing the CEO plan, register it in the manifest: +```bash +~/.claude/skills/gstack/bin/gstack-manifest-append ceo-plan "plans/ceo/$DATE-{feature-slug}.md" plan-ceo-review "$BRANCH" +``` + ### 0E. Temporal Interrogation (EXPANSION, SELECTIVE EXPANSION, and HOLD modes) Think ahead to implementation: What decisions will need to be made during implementation that should be resolved NOW in the plan? ``` @@ -592,8 +602,8 @@ After producing the Completion Summary above, persist the review result: ```bash eval $(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null) -mkdir -p ~/.gstack/projects/$SLUG -echo '{"skill":"plan-ceo-review","timestamp":"TIMESTAMP","status":"STATUS","unresolved":N,"critical_gaps":N,"mode":"MODE"}' >> ~/.gstack/projects/$SLUG/$BRANCH-reviews.jsonl +mkdir -p $PROJECTS_DIR/$SLUG/reviews +echo '{"skill":"plan-ceo-review","timestamp":"TIMESTAMP","status":"STATUS","unresolved":N,"critical_gaps":N,"mode":"MODE"}' >> $PROJECTS_DIR/$SLUG/reviews/$BRANCH.jsonl ``` Before running this command, substitute the placeholder values from the Completion Summary you just produced: @@ -611,7 +621,7 @@ At the end of the review, if the vision produced a compelling feature direction, "The vision from this review produced {N} accepted scope expansions. Want to promote it to a design doc in the repo?" - **A)** Promote to `docs/designs/{FEATURE}.md` (committed to repo, visible to the team) -- **B)** Keep in `~/.gstack/projects/` only (local, personal reference) +- **B)** Keep in `$PROJECTS_DIR/$SLUG/plans/ceo/` only (local, personal reference) - **C)** Skip If promoted, copy the CEO plan content to `docs/designs/{FEATURE}.md` (create the directory if needed) and update the `status` field in the original CEO plan from `ACTIVE` to `PROMOTED`. diff --git a/plan-design-review/SKILL.md.tmpl b/plan-design-review/SKILL.md.tmpl index f8f5221a..94b2b6e4 100644 --- a/plan-design-review/SKILL.md.tmpl +++ b/plan-design-review/SKILL.md.tmpl @@ -267,8 +267,8 @@ After producing the Completion Summary above, persist the review result: ```bash eval $(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null) -mkdir -p ~/.gstack/projects/$SLUG -echo '{"skill":"plan-design-review","timestamp":"TIMESTAMP","status":"STATUS","overall_score":N,"unresolved":N,"decisions_made":N}' >> ~/.gstack/projects/$SLUG/$BRANCH-reviews.jsonl +mkdir -p $PROJECTS_DIR/$SLUG/reviews +echo '{"skill":"plan-design-review","timestamp":"TIMESTAMP","status":"STATUS","overall_score":N,"unresolved":N,"decisions_made":N}' >> $PROJECTS_DIR/$SLUG/reviews/$BRANCH.jsonl ``` Substitute values from the Completion Summary: diff --git a/plan-eng-review/SKILL.md.tmpl b/plan-eng-review/SKILL.md.tmpl index 91f24719..0fe1d2ba 100644 --- a/plan-eng-review/SKILL.md.tmpl +++ b/plan-eng-review/SKILL.md.tmpl @@ -111,16 +111,23 @@ For LLM/prompt changes: check the "Prompt/LLM changes" file patterns listed in C After producing the test diagram, write a test plan artifact to the project directory so `/qa` and `/qa-only` can consume it as primary test input (replacing the lossy git-diff heuristic): +{{ARTIFACT_SETUP}} + ```bash -eval $(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null) -USER=$(whoami) -DATETIME=$(date +%Y%m%d-%H%M%S) -mkdir -p ~/.gstack/projects/$SLUG +mkdir -p $PROJECTS_DIR/$SLUG/plans +FILE="$PROJECTS_DIR/$SLUG/plans/$DATE-$BRANCH-test-plan.md" +[ -f "$FILE" ] && FILE="$PROJECTS_DIR/$SLUG/plans/$DATE-$(date +%H%M)-$BRANCH-test-plan.md" ``` -Write to `~/.gstack/projects/{slug}/{user}-{branch}-test-plan-{datetime}.md`: +Write to the file path resolved above with this content (include the YAML frontmatter): ```markdown +--- +type: test-plan +branch: {branch} +date: {YYYY-MM-DD} +skill: plan-eng-review +--- # Test Plan Generated by /plan-eng-review on {date} Branch: {branch} @@ -141,6 +148,11 @@ Repo: {owner/repo} This file is consumed by `/qa` and `/qa-only` as primary test input. Include only the information that helps a QA tester know **what to test and where** — not implementation details. +After writing the test plan, register it in the manifest: +```bash +~/.claude/skills/gstack/bin/gstack-manifest-append test-plan "plans/$(basename "$FILE")" plan-eng-review "$BRANCH" +``` + ### 4. Performance review Evaluate: * N+1 queries and database access patterns. @@ -222,8 +234,8 @@ After producing the Completion Summary above, persist the review result: ```bash eval $(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null) -mkdir -p ~/.gstack/projects/$SLUG -echo '{"skill":"plan-eng-review","timestamp":"TIMESTAMP","status":"STATUS","unresolved":N,"critical_gaps":N,"mode":"MODE"}' >> ~/.gstack/projects/$SLUG/$BRANCH-reviews.jsonl +mkdir -p $PROJECTS_DIR/$SLUG/reviews +echo '{"skill":"plan-eng-review","timestamp":"TIMESTAMP","status":"STATUS","unresolved":N,"critical_gaps":N,"mode":"MODE"}' >> $PROJECTS_DIR/$SLUG/reviews/$BRANCH.jsonl ``` Substitute values from the Completion Summary: diff --git a/qa-only/SKILL.md.tmpl b/qa-only/SKILL.md.tmpl index 831e71ed..892e9479 100644 --- a/qa-only/SKILL.md.tmpl +++ b/qa-only/SKILL.md.tmpl @@ -71,11 +71,29 @@ Write the report to both local and project-scoped locations: **Local:** `.gstack/qa-reports/qa-report-{domain}-{YYYY-MM-DD}.md` **Project-scoped:** Write test outcome artifact for cross-session context: + +{{ARTIFACT_SETUP}} + ```bash -eval $(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null) -mkdir -p ~/.gstack/projects/$SLUG +mkdir -p $PROJECTS_DIR/$SLUG/reports +FILE="$PROJECTS_DIR/$SLUG/reports/$BRANCH-test-outcome-$DATE.md" +[ -f "$FILE" ] && FILE="$PROJECTS_DIR/$SLUG/reports/$BRANCH-test-outcome-$DATE-$(date +%H%M).md" +``` + +Write to the file path resolved above. Include YAML frontmatter: +```yaml +--- +type: test-outcome +branch: {branch} +date: {YYYY-MM-DD} +skill: qa-only +--- +``` + +After writing, register in manifest: +```bash +~/.claude/skills/gstack/bin/gstack-manifest-append test-outcome "reports/$(basename "$FILE")" qa-only "$BRANCH" ``` -Write to `~/.gstack/projects/{slug}/{user}-{branch}-test-outcome-{datetime}.md` ### Output Structure diff --git a/qa/SKILL.md.tmpl b/qa/SKILL.md.tmpl index 10aa8e0f..51bdbc25 100644 --- a/qa/SKILL.md.tmpl +++ b/qa/SKILL.md.tmpl @@ -493,11 +493,29 @@ Write the report to both local and project-scoped locations: **Local:** `.gstack/qa-reports/qa-report-{domain}-{YYYY-MM-DD}.md` **Project-scoped:** Write test outcome artifact for cross-session context: + +{{ARTIFACT_SETUP}} + ```bash -eval $(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null) -mkdir -p ~/.gstack/projects/$SLUG +mkdir -p $PROJECTS_DIR/$SLUG/reports +FILE="$PROJECTS_DIR/$SLUG/reports/$BRANCH-test-outcome-$DATE.md" +[ -f "$FILE" ] && FILE="$PROJECTS_DIR/$SLUG/reports/$BRANCH-test-outcome-$DATE-$(date +%H%M).md" +``` + +Write to the file path resolved above. Include YAML frontmatter: +```yaml +--- +type: test-outcome +branch: {branch} +date: {YYYY-MM-DD} +skill: qa +--- +``` + +After writing, register in manifest: +```bash +~/.claude/skills/gstack/bin/gstack-manifest-append test-outcome "reports/$(basename "$FILE")" qa "$BRANCH" ``` -Write to `~/.gstack/projects/{slug}/{user}-{branch}-test-outcome-{datetime}.md` **Per-issue additions** (beyond standard report template): - Fix Status: verified / best-effort / reverted / deferred diff --git a/review/greptile-triage.md b/review/greptile-triage.md index 407fe768..f8028dff 100644 --- a/review/greptile-triage.md +++ b/review/greptile-triage.md @@ -34,8 +34,8 @@ The `position != null` filter on line-level comments automatically skips outdate Derive the project-specific history path: ```bash -REMOTE_SLUG=$(browse/bin/remote-slug 2>/dev/null || ~/.claude/skills/gstack/browse/bin/remote-slug 2>/dev/null || basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)") -PROJECT_HISTORY="$HOME/.gstack/projects/$REMOTE_SLUG/greptile-history.md" +eval $(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null) +PROJECT_HISTORY="$PROJECTS_DIR/$SLUG/greptile-history.md" ``` Read `$PROJECT_HISTORY` if it exists (per-project suppressions). Each line records a previous triage outcome: @@ -183,13 +183,13 @@ When classifying comments, also assess whether Greptile's implied severity match Before writing, ensure both directories exist: ```bash -REMOTE_SLUG=$(browse/bin/remote-slug 2>/dev/null || ~/.claude/skills/gstack/browse/bin/remote-slug 2>/dev/null || basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)") -mkdir -p "$HOME/.gstack/projects/$REMOTE_SLUG" +eval $(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null) +mkdir -p "$PROJECTS_DIR/$SLUG" mkdir -p ~/.gstack ``` Append one line per triage outcome to **both** files (per-project for suppressions, global for retro): -- `~/.gstack/projects/$REMOTE_SLUG/greptile-history.md` (per-project) +- `$PROJECTS_DIR/$SLUG/greptile-history.md` (per-project) - `~/.gstack/greptile-history.md` (global aggregate) Format: diff --git a/ship/SKILL.md.tmpl b/ship/SKILL.md.tmpl index a6083792..5009a53c 100644 --- a/ship/SKILL.md.tmpl +++ b/ship/SKILL.md.tmpl @@ -61,7 +61,7 @@ If the Eng Review is NOT "CLEAR": 1. **Check for a prior override on this branch:** ```bash eval $(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null) - grep '"skill":"ship-review-override"' ~/.gstack/projects/$SLUG/$BRANCH-reviews.jsonl 2>/dev/null || echo "NO_OVERRIDE" + grep '"skill":"ship-review-override"' $PROJECTS_DIR/$SLUG/reviews/$BRANCH.jsonl 2>/dev/null || echo "NO_OVERRIDE" ``` If an override exists, display the dashboard and note "Review gate previously accepted — continuing." Do NOT ask again. @@ -75,7 +75,7 @@ If the Eng Review is NOT "CLEAR": 3. **If the user chooses A or C,** persist the decision so future `/ship` runs on this branch skip the gate: ```bash eval $(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null) - echo '{"skill":"ship-review-override","timestamp":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'","decision":"USER_CHOICE"}' >> ~/.gstack/projects/$SLUG/$BRANCH-reviews.jsonl + echo '{"skill":"ship-review-override","timestamp":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'","decision":"USER_CHOICE"}' >> $PROJECTS_DIR/$SLUG/reviews/$BRANCH.jsonl ``` Substitute USER_CHOICE with "ship_anyway" or "not_relevant".