mirror of
https://github.com/garrytan/gstack.git
synced 2026-07-09 17:38:40 +02:00
merge: integrate origin/main (v0.18.1.0) into open-agents-learnings
Main moved forward 6 commits while this branch was local. Integrated
both sides preserving all functionality:
From main (v0.16.4.0 → v0.18.1.0):
- v0.17.0.0 — UX behavioral foundations + ux-audit (generateUXPrinciples,
{{UX_PRINCIPLES}} placeholder, triggers frontmatter on skills)
- v0.18.0.0 — Confusion Protocol, Hermes + GBrain hosts, brain-first
resolver (generateBrainHealthInstruction, generateConfusionProtocol,
generateGBrainContextLoad, generateGBrainSaveResults, hosts/gbrain.ts,
hosts/hermes.ts, scripts/resolvers/gbrain.ts, GBrain bash health check)
- v0.18.0.1 — ngrok Windows build fix
- 0cc830b6 — tilde-in-assignment permission fix
- cc42f14a — gstack compact design doc (tabled)
- 822e843a — headed browser auto-shutdown + disconnect cleanup (v0.18.1.0)
Integration approach: keep this branch's preamble.ts submodule refactor
as the structure of record. Extracted main's two new generators into
their own submodules:
- scripts/resolvers/preamble/generate-brain-health-instruction.ts
- scripts/resolvers/preamble/generate-confusion-protocol.ts
Updated scripts/resolvers/preamble/generate-preamble-bash.ts to absorb
main's GBrain health check (host-conditional on gbrain/hermes).
scripts/resolvers/index.ts now imports BOTH:
- This branch's adds: MODEL_OVERLAY, TASTE_PROFILE, BIN_DIR resolvers
- Main's adds: UX_PRINCIPLES, GBRAIN_CONTEXT_LOAD, GBRAIN_SAVE_RESULTS
resolvers
scripts/resolvers/design.ts keeps both generateTasteProfile (this
branch) and generateUXPrinciples (main). Sibling exports, no overlap.
scripts/gen-skill-docs.ts keeps both this branch's --model flag wiring
and main's edits.
Templates auto-merged where possible. The 35 generated SKILL.md /
golden conflicts auto-resolved via `bun run gen:skill-docs --host all`
followed by re-snapshotting the ship goldens for claude/codex/factory.
Verification:
- bun run gen:skill-docs --host all completes cleanly
- bun test: 1 pre-existing failure (gstack-community-dashboard Supabase
network test, 235s timeout). NOT related to merge — unchanged Supabase
test infra times out without live network. Flagged in PR body.
Token-ceiling warnings on plan-ceo-review (29K), office-hours (26K),
and ship (34K). These existed on origin/main before the merge — the
preamble grew substantially from main's GBrain + UX additions plus this
branch's continuous-checkpoint, context-health, model-overlay, taste-profile,
and feature-discovery additions. Worth a follow-up reduction pass but
doesn't block this merge.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Garry Tan
@@ -19,6 +19,11 @@ allowed-tools:
|
||||
- Bash
|
||||
- AskUserQuestion
|
||||
- WebSearch
|
||||
triggers:
|
||||
- think bigger
|
||||
- expand scope
|
||||
- strategy review
|
||||
- rethink this plan
|
||||
---
|
||||
<!-- AUTO-GENERATED from SKILL.md.tmpl — do not edit directly -->
|
||||
<!-- Regenerate: bun run gen:skill-docs -->
|
||||
@@ -435,6 +440,19 @@ AI makes completeness near-free. Always recommend the complete option over short
|
||||
|
||||
Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut).
|
||||
|
||||
## Confusion Protocol
|
||||
|
||||
When you encounter high-stakes ambiguity during coding:
|
||||
- Two plausible architectures or data models for the same requirement
|
||||
- A request that contradicts existing patterns and you're unsure which to follow
|
||||
- A destructive operation where the scope is unclear
|
||||
- Missing context that would change your approach significantly
|
||||
|
||||
STOP. Name the ambiguity in one sentence. Present 2-3 options with tradeoffs.
|
||||
Ask the user. Do not guess on architectural or data model decisions.
|
||||
|
||||
This does NOT apply to routine coding, small features, or obvious changes.
|
||||
|
||||
## Continuous Checkpoint Mode
|
||||
|
||||
If `CHECKPOINT_MODE` is `"continuous"` (from preamble output): auto-commit work as
|
||||
@@ -982,6 +1000,8 @@ matches a past learning, display:
|
||||
This makes the compounding visible. The user should see that gstack is getting
|
||||
smarter on their codebase over time.
|
||||
|
||||
|
||||
|
||||
## Step 0: Nuclear Scope Challenge + Mode Selection
|
||||
|
||||
### 0A. Premise Challenge
|
||||
@@ -1204,6 +1224,7 @@ After mode is selected, confirm which implementation approach (from 0C-bis) appl
|
||||
|
||||
Once selected, commit fully. Do not silently drift.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.
|
||||
**Reminder: Do NOT make any code changes. Review only.**
|
||||
|
||||
## Review Sections (11 sections, after scope and mode are agreed)
|
||||
|
||||
@@ -1233,6 +1254,7 @@ Evaluate and diagram:
|
||||
|
||||
Required ASCII diagram: full system architecture showing new components and their relationships to existing ones.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.
|
||||
**Reminder: Do NOT make any code changes. Review only.**
|
||||
|
||||
### Section 2: Error & Rescue Map
|
||||
This is the section that catches silent failures. It is not optional.
|
||||
@@ -1262,6 +1284,7 @@ Rules for this section:
|
||||
* For each GAP (unrescued error that should be rescued): specify the rescue action and what the user should see.
|
||||
* For LLM/AI service calls specifically: what happens when the response is malformed? When it's empty? When it hallucinates invalid JSON? When the model returns a refusal? Each of these is a distinct failure mode.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.
|
||||
**Reminder: Do NOT make any code changes. Review only.**
|
||||
|
||||
### Section 3: Security & Threat Model
|
||||
Security is not a sub-bullet of architecture. It gets its own section.
|
||||
@@ -1277,6 +1300,7 @@ Evaluate:
|
||||
|
||||
For each finding: threat, likelihood (High/Med/Low), impact (High/Med/Low), and whether the plan mitigates it.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.
|
||||
**Reminder: Do NOT make any code changes. Review only.**
|
||||
|
||||
### Section 4: Data Flow & Interaction Edge Cases
|
||||
This section traces data through the system and interactions through the UI with adversarial thoroughness.
|
||||
@@ -1313,6 +1337,7 @@ For each node: what happens on each shadow path? Is it tested?
|
||||
```
|
||||
Flag any unhandled edge case as a gap. For each gap, specify the fix.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.
|
||||
**Reminder: Do NOT make any code changes. Review only.**
|
||||
|
||||
### Section 5: Code Quality Review
|
||||
Evaluate:
|
||||
@@ -1325,6 +1350,7 @@ Evaluate:
|
||||
* Under-engineering check. Anything fragile, assuming happy path only, or missing obvious defensive checks?
|
||||
* Cyclomatic complexity. Flag any new method that branches more than 5 times. Propose a refactor.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.
|
||||
**Reminder: Do NOT make any code changes. Review only.**
|
||||
|
||||
### Section 6: Test Review
|
||||
Make a complete diagram of every new thing this plan introduces:
|
||||
@@ -1365,6 +1391,7 @@ Load/stress test requirements: For any new codepath called frequently or process
|
||||
|
||||
For LLM/prompt changes: Check CLAUDE.md for the "Prompt/LLM changes" file patterns. If this plan touches ANY of those patterns, state which eval suites must be run, which cases should be added, and what baselines to compare against.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.
|
||||
**Reminder: Do NOT make any code changes. Review only.**
|
||||
|
||||
### Section 7: Performance Review
|
||||
Evaluate:
|
||||
@@ -1376,6 +1403,7 @@ Evaluate:
|
||||
* Slow paths. Top 3 slowest new codepaths and estimated p99 latency.
|
||||
* Connection pool pressure. New DB connections, Redis connections, HTTP connections?
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.
|
||||
**Reminder: Do NOT make any code changes. Review only.**
|
||||
|
||||
### Section 8: Observability & Debuggability Review
|
||||
New systems break. This section ensures you can see why.
|
||||
@@ -1392,6 +1420,7 @@ Evaluate:
|
||||
**EXPANSION and SELECTIVE EXPANSION addition:**
|
||||
* What observability would make this feature a joy to operate? (For SELECTIVE EXPANSION, include observability for any accepted cherry-picks.)
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.
|
||||
**Reminder: Do NOT make any code changes. Review only.**
|
||||
|
||||
### Section 9: Deployment & Rollout Review
|
||||
Evaluate:
|
||||
@@ -1407,6 +1436,7 @@ Evaluate:
|
||||
**EXPANSION and SELECTIVE EXPANSION addition:**
|
||||
* What deploy infrastructure would make shipping this feature routine? (For SELECTIVE EXPANSION, assess whether accepted cherry-picks change the deployment risk profile.)
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.
|
||||
**Reminder: Do NOT make any code changes. Review only.**
|
||||
|
||||
### Section 10: Long-Term Trajectory Review
|
||||
Evaluate:
|
||||
@@ -1422,6 +1452,7 @@ Evaluate:
|
||||
* Platform potential. Does this create capabilities other features can leverage?
|
||||
* (SELECTIVE EXPANSION only) Retrospective: Were the right cherry-picks accepted? Did any rejected expansions turn out to be load-bearing for the accepted ones?
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.
|
||||
**Reminder: Do NOT make any code changes. Review only.**
|
||||
|
||||
### Section 11: Design & UX Review (skip if no UI scope detected)
|
||||
The CEO calling in the designer. Not a pixel-level audit — that's /plan-design-review and /design-review. This is ensuring the plan has design intentionality.
|
||||
@@ -1444,6 +1475,7 @@ Required ASCII diagram: user flow showing screens/states and transitions.
|
||||
|
||||
If this plan has significant UI scope, recommend: "Consider running /plan-design-review for a deep design review of this plan before implementation."
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.
|
||||
**Reminder: Do NOT make any code changes. Review only.**
|
||||
|
||||
## Outside Voice — Independent Plan Challenge (optional, recommended)
|
||||
|
||||
@@ -1911,6 +1943,8 @@ staleness detection: if those files are later deleted, the learning can be flagg
|
||||
**Only log genuine discoveries.** Don't log obvious things. Don't log things the user
|
||||
already knows. A good test: would this insight save time in a future session? If yes, log it.
|
||||
|
||||
|
||||
|
||||
## Mode Quick Reference
|
||||
```
|
||||
┌────────────────────────────────────────────────────────────────────────────────┐
|
||||
|
||||
@@ -19,6 +19,11 @@ allowed-tools:
|
||||
- Bash
|
||||
- AskUserQuestion
|
||||
- WebSearch
|
||||
triggers:
|
||||
- think bigger
|
||||
- expand scope
|
||||
- strategy review
|
||||
- rethink this plan
|
||||
---
|
||||
|
||||
{{PREAMBLE}}
|
||||
@@ -190,6 +195,8 @@ Feed into the Premise Challenge (0A) and Dream State Mapping (0C). If you find a
|
||||
|
||||
{{LEARNINGS_SEARCH}}
|
||||
|
||||
{{GBRAIN_CONTEXT_LOAD}}
|
||||
|
||||
## Step 0: Nuclear Scope Challenge + Mode Selection
|
||||
|
||||
### 0A. Premise Challenge
|
||||
@@ -352,6 +359,7 @@ After mode is selected, confirm which implementation approach (from 0C-bis) appl
|
||||
|
||||
Once selected, commit fully. Do not silently drift.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.
|
||||
**Reminder: Do NOT make any code changes. Review only.**
|
||||
|
||||
## Review Sections (11 sections, after scope and mode are agreed)
|
||||
|
||||
@@ -381,6 +389,7 @@ Evaluate and diagram:
|
||||
|
||||
Required ASCII diagram: full system architecture showing new components and their relationships to existing ones.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.
|
||||
**Reminder: Do NOT make any code changes. Review only.**
|
||||
|
||||
### Section 2: Error & Rescue Map
|
||||
This is the section that catches silent failures. It is not optional.
|
||||
@@ -410,6 +419,7 @@ Rules for this section:
|
||||
* For each GAP (unrescued error that should be rescued): specify the rescue action and what the user should see.
|
||||
* For LLM/AI service calls specifically: what happens when the response is malformed? When it's empty? When it hallucinates invalid JSON? When the model returns a refusal? Each of these is a distinct failure mode.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.
|
||||
**Reminder: Do NOT make any code changes. Review only.**
|
||||
|
||||
### Section 3: Security & Threat Model
|
||||
Security is not a sub-bullet of architecture. It gets its own section.
|
||||
@@ -425,6 +435,7 @@ Evaluate:
|
||||
|
||||
For each finding: threat, likelihood (High/Med/Low), impact (High/Med/Low), and whether the plan mitigates it.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.
|
||||
**Reminder: Do NOT make any code changes. Review only.**
|
||||
|
||||
### Section 4: Data Flow & Interaction Edge Cases
|
||||
This section traces data through the system and interactions through the UI with adversarial thoroughness.
|
||||
@@ -461,6 +472,7 @@ For each node: what happens on each shadow path? Is it tested?
|
||||
```
|
||||
Flag any unhandled edge case as a gap. For each gap, specify the fix.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.
|
||||
**Reminder: Do NOT make any code changes. Review only.**
|
||||
|
||||
### Section 5: Code Quality Review
|
||||
Evaluate:
|
||||
@@ -473,6 +485,7 @@ Evaluate:
|
||||
* Under-engineering check. Anything fragile, assuming happy path only, or missing obvious defensive checks?
|
||||
* Cyclomatic complexity. Flag any new method that branches more than 5 times. Propose a refactor.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.
|
||||
**Reminder: Do NOT make any code changes. Review only.**
|
||||
|
||||
### Section 6: Test Review
|
||||
Make a complete diagram of every new thing this plan introduces:
|
||||
@@ -513,6 +526,7 @@ Load/stress test requirements: For any new codepath called frequently or process
|
||||
|
||||
For LLM/prompt changes: Check CLAUDE.md for the "Prompt/LLM changes" file patterns. If this plan touches ANY of those patterns, state which eval suites must be run, which cases should be added, and what baselines to compare against.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.
|
||||
**Reminder: Do NOT make any code changes. Review only.**
|
||||
|
||||
### Section 7: Performance Review
|
||||
Evaluate:
|
||||
@@ -524,6 +538,7 @@ Evaluate:
|
||||
* Slow paths. Top 3 slowest new codepaths and estimated p99 latency.
|
||||
* Connection pool pressure. New DB connections, Redis connections, HTTP connections?
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.
|
||||
**Reminder: Do NOT make any code changes. Review only.**
|
||||
|
||||
### Section 8: Observability & Debuggability Review
|
||||
New systems break. This section ensures you can see why.
|
||||
@@ -540,6 +555,7 @@ Evaluate:
|
||||
**EXPANSION and SELECTIVE EXPANSION addition:**
|
||||
* What observability would make this feature a joy to operate? (For SELECTIVE EXPANSION, include observability for any accepted cherry-picks.)
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.
|
||||
**Reminder: Do NOT make any code changes. Review only.**
|
||||
|
||||
### Section 9: Deployment & Rollout Review
|
||||
Evaluate:
|
||||
@@ -555,6 +571,7 @@ Evaluate:
|
||||
**EXPANSION and SELECTIVE EXPANSION addition:**
|
||||
* What deploy infrastructure would make shipping this feature routine? (For SELECTIVE EXPANSION, assess whether accepted cherry-picks change the deployment risk profile.)
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.
|
||||
**Reminder: Do NOT make any code changes. Review only.**
|
||||
|
||||
### Section 10: Long-Term Trajectory Review
|
||||
Evaluate:
|
||||
@@ -570,6 +587,7 @@ Evaluate:
|
||||
* Platform potential. Does this create capabilities other features can leverage?
|
||||
* (SELECTIVE EXPANSION only) Retrospective: Were the right cherry-picks accepted? Did any rejected expansions turn out to be load-bearing for the accepted ones?
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.
|
||||
**Reminder: Do NOT make any code changes. Review only.**
|
||||
|
||||
### Section 11: Design & UX Review (skip if no UI scope detected)
|
||||
The CEO calling in the designer. Not a pixel-level audit — that's /plan-design-review and /design-review. This is ensuring the plan has design intentionality.
|
||||
@@ -592,6 +610,7 @@ Required ASCII diagram: user flow showing screens/states and transitions.
|
||||
|
||||
If this plan has significant UI scope, recommend: "Consider running /plan-design-review for a deep design review of this plan before implementation."
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.
|
||||
**Reminder: Do NOT make any code changes. Review only.**
|
||||
|
||||
{{CODEX_PLAN_REVIEW}}
|
||||
|
||||
@@ -783,6 +802,8 @@ If promoted, copy the CEO plan content to `docs/designs/{FEATURE}.md` (create th
|
||||
|
||||
{{LEARNINGS_LOG}}
|
||||
|
||||
{{GBRAIN_SAVE_RESULTS}}
|
||||
|
||||
## Mode Quick Reference
|
||||
```
|
||||
┌────────────────────────────────────────────────────────────────────────────────┐
|
||||
|
||||
Reference in New Issue
Block a user