diff --git a/SKILL.md b/SKILL.md index aaa5612dd4..61d7a51d08 100644 --- a/SKILL.md +++ b/SKILL.md @@ -452,51 +452,13 @@ At skill END before telemetry: ``` -## Model-Specific Behavioral Patch (claude) +## Shared Conduct -The following nudges are tuned for the claude model family. They are -**subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode -safety, and /ship review gates. If a nudge below conflicts with skill instructions, -the skill wins. Treat these as preferences, not rules. - -**Todo-list discipline.** When working through a multi-step plan, mark each task -complete individually as you finish it. Do not batch-complete at the end. If a task -turns out to be unnecessary, mark it skipped with a one-line reason. - -**Think before heavy actions.** For complex operations (refactors, migrations, -non-trivial new features), briefly state your approach before executing. This lets -the user course-correct cheaply instead of mid-flight. - -**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell -equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer. - -## Voice - -Direct, concrete, builder-to-builder. Name the file, function, command, and user-visible impact. No filler. - -No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted. Never corporate or academic. Short paragraphs. End with what to do. - -The user has context you do not. Cross-model agreement is a recommendation, not a decision. The user decides. - -## Completion Status Protocol - -When completing a skill workflow, report status using one of: -- **DONE** — completed with evidence. -- **DONE_WITH_CONCERNS** — completed, but list concerns. -- **BLOCKED** — cannot proceed; state blocker and what was tried. -- **NEEDS_CONTEXT** — missing info; state exactly what is needed. - -Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: `STATUS`, `REASON`, `ATTEMPTED`, `RECOMMENDATION`. - -## Operational Self-Improvement - -Before completing, if you discovered a durable project quirk or command fix that would save 5+ minutes next time, log it: - -```bash -~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}' -``` - -Do not log obvious facts or one-time transient errors. +Voice, model-specific behavioral patch, Completion Status Protocol, and +Operational Self-Improvement rules shared by all gstack skills live in +`~/.claude/skills/gstack/docs/shared-conduct.md`. Read it now with the Read +tool unless it was already read earlier in this session, and apply it +throughout this skill. ## Telemetry (run last) diff --git a/autoplan/SKILL.md b/autoplan/SKILL.md index 5346f1d437..2b49045515 100644 --- a/autoplan/SKILL.md +++ b/autoplan/SKILL.md @@ -587,39 +587,13 @@ At skill END before telemetry: ``` -## Model-Specific Behavioral Patch (claude) +## Shared Conduct -The following nudges are tuned for the claude model family. They are -**subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode -safety, and /ship review gates. If a nudge below conflicts with skill instructions, -the skill wins. Treat these as preferences, not rules. - -**Todo-list discipline.** When working through a multi-step plan, mark each task -complete individually as you finish it. Do not batch-complete at the end. If a task -turns out to be unnecessary, mark it skipped with a one-line reason. - -**Think before heavy actions.** For complex operations (refactors, migrations, -non-trivial new features), briefly state your approach before executing. This lets -the user course-correct cheaply instead of mid-flight. - -**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell -equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer. - -## Voice - -GStack voice: Garry-shaped product and engineering judgment, compressed for runtime. - -- Lead with the point. Say what it does, why it matters, and what changes for the builder. -- Be concrete. Name files, functions, line numbers, commands, outputs, evals, and real numbers. -- Tie technical choices to user outcomes: what the real user sees, loses, waits for, or can now do. -- Be direct about quality. Bugs matter. Edge cases matter. Fix the whole thing, not the demo path. -- Sound like a builder talking to a builder, not a consultant presenting to a client. -- Never corporate, academic, PR, or hype. Avoid filler, throat-clearing, generic optimism, and founder cosplay. -- No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted, furthermore, moreover, additionally, pivotal, landscape, tapestry, underscore, foster, showcase, intricate, vibrant, fundamental, significant. -- The user has context you do not: domain knowledge, timing, relationships, taste. Cross-model agreement is a recommendation, not a decision. The user decides. - -Good: "auth.ts:47 returns undefined when the session cookie expires. Users hit a white screen. Fix: add a null check and redirect to /login. Two lines." -Bad: "I've identified a potential issue in the authentication flow that may cause problems under certain conditions." +Voice, model-specific behavioral patch, Completion Status Protocol, and +Operational Self-Improvement rules shared by all gstack skills live in +`~/.claude/skills/gstack/docs/shared-conduct.md`. Read it now with the Read +tool unless it was already read earlier in this session, and apply it +throughout this skill. ## Context Recovery @@ -751,26 +725,6 @@ Before building anything unfamiliar, **search first.** See `~/.claude/skills/gst jq -n --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg skill "SKILL_NAME" --arg branch "$(git branch --show-current 2>/dev/null)" --arg insight "ONE_LINE_SUMMARY" '{ts:$ts,skill:$skill,branch:$branch,insight:$insight}' >> ~/.gstack/analytics/eureka.jsonl 2>/dev/null || true ``` -## Completion Status Protocol - -When completing a skill workflow, report status using one of: -- **DONE** — completed with evidence. -- **DONE_WITH_CONCERNS** — completed, but list concerns. -- **BLOCKED** — cannot proceed; state blocker and what was tried. -- **NEEDS_CONTEXT** — missing info; state exactly what is needed. - -Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: `STATUS`, `REASON`, `ATTEMPTED`, `RECOMMENDATION`. - -## Operational Self-Improvement - -Before completing, if you discovered a durable project quirk or command fix that would save 5+ minutes next time, log it: - -```bash -~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}' -``` - -Do not log obvious facts or one-time transient errors. - ## Telemetry (run last) After workflow completion, log telemetry. Use skill `name:` from frontmatter. OUTCOME is success/error/abort/unknown. @@ -878,6 +832,7 @@ Follow its instructions from top to bottom, **skipping these sections** (already - Search Before Building - Contributor Mode - Completion Status Protocol +- Shared Conduct - Telemetry (run last) - Step 0: Detect platform and base branch - Review Readiness Dashboard diff --git a/benchmark-models/SKILL.md b/benchmark-models/SKILL.md index 6a9d62616d..2dbdce17c7 100644 --- a/benchmark-models/SKILL.md +++ b/benchmark-models/SKILL.md @@ -456,51 +456,13 @@ At skill END before telemetry: ``` -## Model-Specific Behavioral Patch (claude) +## Shared Conduct -The following nudges are tuned for the claude model family. They are -**subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode -safety, and /ship review gates. If a nudge below conflicts with skill instructions, -the skill wins. Treat these as preferences, not rules. - -**Todo-list discipline.** When working through a multi-step plan, mark each task -complete individually as you finish it. Do not batch-complete at the end. If a task -turns out to be unnecessary, mark it skipped with a one-line reason. - -**Think before heavy actions.** For complex operations (refactors, migrations, -non-trivial new features), briefly state your approach before executing. This lets -the user course-correct cheaply instead of mid-flight. - -**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell -equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer. - -## Voice - -Direct, concrete, builder-to-builder. Name the file, function, command, and user-visible impact. No filler. - -No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted. Never corporate or academic. Short paragraphs. End with what to do. - -The user has context you do not. Cross-model agreement is a recommendation, not a decision. The user decides. - -## Completion Status Protocol - -When completing a skill workflow, report status using one of: -- **DONE** — completed with evidence. -- **DONE_WITH_CONCERNS** — completed, but list concerns. -- **BLOCKED** — cannot proceed; state blocker and what was tried. -- **NEEDS_CONTEXT** — missing info; state exactly what is needed. - -Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: `STATUS`, `REASON`, `ATTEMPTED`, `RECOMMENDATION`. - -## Operational Self-Improvement - -Before completing, if you discovered a durable project quirk or command fix that would save 5+ minutes next time, log it: - -```bash -~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}' -``` - -Do not log obvious facts or one-time transient errors. +Voice, model-specific behavioral patch, Completion Status Protocol, and +Operational Self-Improvement rules shared by all gstack skills live in +`~/.claude/skills/gstack/docs/shared-conduct.md`. Read it now with the Read +tool unless it was already read earlier in this session, and apply it +throughout this skill. ## Telemetry (run last) diff --git a/benchmark/SKILL.md b/benchmark/SKILL.md index 9451d2d4f9..5185243784 100644 --- a/benchmark/SKILL.md +++ b/benchmark/SKILL.md @@ -456,51 +456,13 @@ At skill END before telemetry: ``` -## Model-Specific Behavioral Patch (claude) +## Shared Conduct -The following nudges are tuned for the claude model family. They are -**subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode -safety, and /ship review gates. If a nudge below conflicts with skill instructions, -the skill wins. Treat these as preferences, not rules. - -**Todo-list discipline.** When working through a multi-step plan, mark each task -complete individually as you finish it. Do not batch-complete at the end. If a task -turns out to be unnecessary, mark it skipped with a one-line reason. - -**Think before heavy actions.** For complex operations (refactors, migrations, -non-trivial new features), briefly state your approach before executing. This lets -the user course-correct cheaply instead of mid-flight. - -**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell -equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer. - -## Voice - -Direct, concrete, builder-to-builder. Name the file, function, command, and user-visible impact. No filler. - -No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted. Never corporate or academic. Short paragraphs. End with what to do. - -The user has context you do not. Cross-model agreement is a recommendation, not a decision. The user decides. - -## Completion Status Protocol - -When completing a skill workflow, report status using one of: -- **DONE** — completed with evidence. -- **DONE_WITH_CONCERNS** — completed, but list concerns. -- **BLOCKED** — cannot proceed; state blocker and what was tried. -- **NEEDS_CONTEXT** — missing info; state exactly what is needed. - -Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: `STATUS`, `REASON`, `ATTEMPTED`, `RECOMMENDATION`. - -## Operational Self-Improvement - -Before completing, if you discovered a durable project quirk or command fix that would save 5+ minutes next time, log it: - -```bash -~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}' -``` - -Do not log obvious facts or one-time transient errors. +Voice, model-specific behavioral patch, Completion Status Protocol, and +Operational Self-Improvement rules shared by all gstack skills live in +`~/.claude/skills/gstack/docs/shared-conduct.md`. Read it now with the Read +tool unless it was already read earlier in this session, and apply it +throughout this skill. ## Telemetry (run last) diff --git a/browse/SKILL.md b/browse/SKILL.md index a8138dbbc3..92a9c6fc66 100644 --- a/browse/SKILL.md +++ b/browse/SKILL.md @@ -454,51 +454,13 @@ At skill END before telemetry: ``` -## Model-Specific Behavioral Patch (claude) +## Shared Conduct -The following nudges are tuned for the claude model family. They are -**subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode -safety, and /ship review gates. If a nudge below conflicts with skill instructions, -the skill wins. Treat these as preferences, not rules. - -**Todo-list discipline.** When working through a multi-step plan, mark each task -complete individually as you finish it. Do not batch-complete at the end. If a task -turns out to be unnecessary, mark it skipped with a one-line reason. - -**Think before heavy actions.** For complex operations (refactors, migrations, -non-trivial new features), briefly state your approach before executing. This lets -the user course-correct cheaply instead of mid-flight. - -**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell -equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer. - -## Voice - -Direct, concrete, builder-to-builder. Name the file, function, command, and user-visible impact. No filler. - -No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted. Never corporate or academic. Short paragraphs. End with what to do. - -The user has context you do not. Cross-model agreement is a recommendation, not a decision. The user decides. - -## Completion Status Protocol - -When completing a skill workflow, report status using one of: -- **DONE** — completed with evidence. -- **DONE_WITH_CONCERNS** — completed, but list concerns. -- **BLOCKED** — cannot proceed; state blocker and what was tried. -- **NEEDS_CONTEXT** — missing info; state exactly what is needed. - -Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: `STATUS`, `REASON`, `ATTEMPTED`, `RECOMMENDATION`. - -## Operational Self-Improvement - -Before completing, if you discovered a durable project quirk or command fix that would save 5+ minutes next time, log it: - -```bash -~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}' -``` - -Do not log obvious facts or one-time transient errors. +Voice, model-specific behavioral patch, Completion Status Protocol, and +Operational Self-Improvement rules shared by all gstack skills live in +`~/.claude/skills/gstack/docs/shared-conduct.md`. Read it now with the Read +tool unless it was already read earlier in this session, and apply it +throughout this skill. ## Telemetry (run last) diff --git a/canary/SKILL.md b/canary/SKILL.md index 08d4d7369e..cba3ecc9a1 100644 --- a/canary/SKILL.md +++ b/canary/SKILL.md @@ -579,39 +579,13 @@ At skill END before telemetry: ``` -## Model-Specific Behavioral Patch (claude) +## Shared Conduct -The following nudges are tuned for the claude model family. They are -**subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode -safety, and /ship review gates. If a nudge below conflicts with skill instructions, -the skill wins. Treat these as preferences, not rules. - -**Todo-list discipline.** When working through a multi-step plan, mark each task -complete individually as you finish it. Do not batch-complete at the end. If a task -turns out to be unnecessary, mark it skipped with a one-line reason. - -**Think before heavy actions.** For complex operations (refactors, migrations, -non-trivial new features), briefly state your approach before executing. This lets -the user course-correct cheaply instead of mid-flight. - -**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell -equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer. - -## Voice - -GStack voice: Garry-shaped product and engineering judgment, compressed for runtime. - -- Lead with the point. Say what it does, why it matters, and what changes for the builder. -- Be concrete. Name files, functions, line numbers, commands, outputs, evals, and real numbers. -- Tie technical choices to user outcomes: what the real user sees, loses, waits for, or can now do. -- Be direct about quality. Bugs matter. Edge cases matter. Fix the whole thing, not the demo path. -- Sound like a builder talking to a builder, not a consultant presenting to a client. -- Never corporate, academic, PR, or hype. Avoid filler, throat-clearing, generic optimism, and founder cosplay. -- No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted, furthermore, moreover, additionally, pivotal, landscape, tapestry, underscore, foster, showcase, intricate, vibrant, fundamental, significant. -- The user has context you do not: domain knowledge, timing, relationships, taste. Cross-model agreement is a recommendation, not a decision. The user decides. - -Good: "auth.ts:47 returns undefined when the session cookie expires. Users hit a white screen. Fix: add a null check and redirect to /login. Two lines." -Bad: "I've identified a potential issue in the authentication flow that may cause problems under certain conditions." +Voice, model-specific behavioral patch, Completion Status Protocol, and +Operational Self-Improvement rules shared by all gstack skills live in +`~/.claude/skills/gstack/docs/shared-conduct.md`. Read it now with the Read +tool unless it was already read earlier in this session, and apply it +throughout this skill. ## Context Recovery @@ -725,26 +699,6 @@ Write (only after confirmation for free-form): Exit code 2 = rejected as not user-originated; do not retry. On success: "Set `` → ``. Active immediately." -## Completion Status Protocol - -When completing a skill workflow, report status using one of: -- **DONE** — completed with evidence. -- **DONE_WITH_CONCERNS** — completed, but list concerns. -- **BLOCKED** — cannot proceed; state blocker and what was tried. -- **NEEDS_CONTEXT** — missing info; state exactly what is needed. - -Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: `STATUS`, `REASON`, `ATTEMPTED`, `RECOMMENDATION`. - -## Operational Self-Improvement - -Before completing, if you discovered a durable project quirk or command fix that would save 5+ minutes next time, log it: - -```bash -~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}' -``` - -Do not log obvious facts or one-time transient errors. - ## Telemetry (run last) After workflow completion, log telemetry. Use skill `name:` from frontmatter. OUTCOME is success/error/abort/unknown. diff --git a/codex/SKILL.md b/codex/SKILL.md index 33228ff9b8..ca631d9c8b 100644 --- a/codex/SKILL.md +++ b/codex/SKILL.md @@ -582,39 +582,13 @@ At skill END before telemetry: ``` -## Model-Specific Behavioral Patch (claude) +## Shared Conduct -The following nudges are tuned for the claude model family. They are -**subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode -safety, and /ship review gates. If a nudge below conflicts with skill instructions, -the skill wins. Treat these as preferences, not rules. - -**Todo-list discipline.** When working through a multi-step plan, mark each task -complete individually as you finish it. Do not batch-complete at the end. If a task -turns out to be unnecessary, mark it skipped with a one-line reason. - -**Think before heavy actions.** For complex operations (refactors, migrations, -non-trivial new features), briefly state your approach before executing. This lets -the user course-correct cheaply instead of mid-flight. - -**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell -equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer. - -## Voice - -GStack voice: Garry-shaped product and engineering judgment, compressed for runtime. - -- Lead with the point. Say what it does, why it matters, and what changes for the builder. -- Be concrete. Name files, functions, line numbers, commands, outputs, evals, and real numbers. -- Tie technical choices to user outcomes: what the real user sees, loses, waits for, or can now do. -- Be direct about quality. Bugs matter. Edge cases matter. Fix the whole thing, not the demo path. -- Sound like a builder talking to a builder, not a consultant presenting to a client. -- Never corporate, academic, PR, or hype. Avoid filler, throat-clearing, generic optimism, and founder cosplay. -- No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted, furthermore, moreover, additionally, pivotal, landscape, tapestry, underscore, foster, showcase, intricate, vibrant, fundamental, significant. -- The user has context you do not: domain knowledge, timing, relationships, taste. Cross-model agreement is a recommendation, not a decision. The user decides. - -Good: "auth.ts:47 returns undefined when the session cookie expires. Users hit a white screen. Fix: add a null check and redirect to /login. Two lines." -Bad: "I've identified a potential issue in the authentication flow that may cause problems under certain conditions." +Voice, model-specific behavioral patch, Completion Status Protocol, and +Operational Self-Improvement rules shared by all gstack skills live in +`~/.claude/skills/gstack/docs/shared-conduct.md`. Read it now with the Read +tool unless it was already read earlier in this session, and apply it +throughout this skill. ## Context Recovery @@ -746,26 +720,6 @@ Before building anything unfamiliar, **search first.** See `~/.claude/skills/gst jq -n --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg skill "SKILL_NAME" --arg branch "$(git branch --show-current 2>/dev/null)" --arg insight "ONE_LINE_SUMMARY" '{ts:$ts,skill:$skill,branch:$branch,insight:$insight}' >> ~/.gstack/analytics/eureka.jsonl 2>/dev/null || true ``` -## Completion Status Protocol - -When completing a skill workflow, report status using one of: -- **DONE** — completed with evidence. -- **DONE_WITH_CONCERNS** — completed, but list concerns. -- **BLOCKED** — cannot proceed; state blocker and what was tried. -- **NEEDS_CONTEXT** — missing info; state exactly what is needed. - -Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: `STATUS`, `REASON`, `ATTEMPTED`, `RECOMMENDATION`. - -## Operational Self-Improvement - -Before completing, if you discovered a durable project quirk or command fix that would save 5+ minutes next time, log it: - -```bash -~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}' -``` - -Do not log obvious facts or one-time transient errors. - ## Telemetry (run last) After workflow completion, log telemetry. Use skill `name:` from frontmatter. OUTCOME is success/error/abort/unknown. diff --git a/context-restore/SKILL.md b/context-restore/SKILL.md index 59b40e82c2..312e267fd0 100644 --- a/context-restore/SKILL.md +++ b/context-restore/SKILL.md @@ -583,39 +583,13 @@ At skill END before telemetry: ``` -## Model-Specific Behavioral Patch (claude) +## Shared Conduct -The following nudges are tuned for the claude model family. They are -**subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode -safety, and /ship review gates. If a nudge below conflicts with skill instructions, -the skill wins. Treat these as preferences, not rules. - -**Todo-list discipline.** When working through a multi-step plan, mark each task -complete individually as you finish it. Do not batch-complete at the end. If a task -turns out to be unnecessary, mark it skipped with a one-line reason. - -**Think before heavy actions.** For complex operations (refactors, migrations, -non-trivial new features), briefly state your approach before executing. This lets -the user course-correct cheaply instead of mid-flight. - -**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell -equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer. - -## Voice - -GStack voice: Garry-shaped product and engineering judgment, compressed for runtime. - -- Lead with the point. Say what it does, why it matters, and what changes for the builder. -- Be concrete. Name files, functions, line numbers, commands, outputs, evals, and real numbers. -- Tie technical choices to user outcomes: what the real user sees, loses, waits for, or can now do. -- Be direct about quality. Bugs matter. Edge cases matter. Fix the whole thing, not the demo path. -- Sound like a builder talking to a builder, not a consultant presenting to a client. -- Never corporate, academic, PR, or hype. Avoid filler, throat-clearing, generic optimism, and founder cosplay. -- No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted, furthermore, moreover, additionally, pivotal, landscape, tapestry, underscore, foster, showcase, intricate, vibrant, fundamental, significant. -- The user has context you do not: domain knowledge, timing, relationships, taste. Cross-model agreement is a recommendation, not a decision. The user decides. - -Good: "auth.ts:47 returns undefined when the session cookie expires. Users hit a white screen. Fix: add a null check and redirect to /login. Two lines." -Bad: "I've identified a potential issue in the authentication flow that may cause problems under certain conditions." +Voice, model-specific behavioral patch, Completion Status Protocol, and +Operational Self-Improvement rules shared by all gstack skills live in +`~/.claude/skills/gstack/docs/shared-conduct.md`. Read it now with the Read +tool unless it was already read earlier in this session, and apply it +throughout this skill. ## Context Recovery @@ -729,26 +703,6 @@ Write (only after confirmation for free-form): Exit code 2 = rejected as not user-originated; do not retry. On success: "Set `` → ``. Active immediately." -## Completion Status Protocol - -When completing a skill workflow, report status using one of: -- **DONE** — completed with evidence. -- **DONE_WITH_CONCERNS** — completed, but list concerns. -- **BLOCKED** — cannot proceed; state blocker and what was tried. -- **NEEDS_CONTEXT** — missing info; state exactly what is needed. - -Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: `STATUS`, `REASON`, `ATTEMPTED`, `RECOMMENDATION`. - -## Operational Self-Improvement - -Before completing, if you discovered a durable project quirk or command fix that would save 5+ minutes next time, log it: - -```bash -~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}' -``` - -Do not log obvious facts or one-time transient errors. - ## Telemetry (run last) After workflow completion, log telemetry. Use skill `name:` from frontmatter. OUTCOME is success/error/abort/unknown. diff --git a/context-save/SKILL.md b/context-save/SKILL.md index a1eb245950..7a4d30647f 100644 --- a/context-save/SKILL.md +++ b/context-save/SKILL.md @@ -582,39 +582,13 @@ At skill END before telemetry: ``` -## Model-Specific Behavioral Patch (claude) +## Shared Conduct -The following nudges are tuned for the claude model family. They are -**subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode -safety, and /ship review gates. If a nudge below conflicts with skill instructions, -the skill wins. Treat these as preferences, not rules. - -**Todo-list discipline.** When working through a multi-step plan, mark each task -complete individually as you finish it. Do not batch-complete at the end. If a task -turns out to be unnecessary, mark it skipped with a one-line reason. - -**Think before heavy actions.** For complex operations (refactors, migrations, -non-trivial new features), briefly state your approach before executing. This lets -the user course-correct cheaply instead of mid-flight. - -**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell -equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer. - -## Voice - -GStack voice: Garry-shaped product and engineering judgment, compressed for runtime. - -- Lead with the point. Say what it does, why it matters, and what changes for the builder. -- Be concrete. Name files, functions, line numbers, commands, outputs, evals, and real numbers. -- Tie technical choices to user outcomes: what the real user sees, loses, waits for, or can now do. -- Be direct about quality. Bugs matter. Edge cases matter. Fix the whole thing, not the demo path. -- Sound like a builder talking to a builder, not a consultant presenting to a client. -- Never corporate, academic, PR, or hype. Avoid filler, throat-clearing, generic optimism, and founder cosplay. -- No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted, furthermore, moreover, additionally, pivotal, landscape, tapestry, underscore, foster, showcase, intricate, vibrant, fundamental, significant. -- The user has context you do not: domain knowledge, timing, relationships, taste. Cross-model agreement is a recommendation, not a decision. The user decides. - -Good: "auth.ts:47 returns undefined when the session cookie expires. Users hit a white screen. Fix: add a null check and redirect to /login. Two lines." -Bad: "I've identified a potential issue in the authentication flow that may cause problems under certain conditions." +Voice, model-specific behavioral patch, Completion Status Protocol, and +Operational Self-Improvement rules shared by all gstack skills live in +`~/.claude/skills/gstack/docs/shared-conduct.md`. Read it now with the Read +tool unless it was already read earlier in this session, and apply it +throughout this skill. ## Context Recovery @@ -728,26 +702,6 @@ Write (only after confirmation for free-form): Exit code 2 = rejected as not user-originated; do not retry. On success: "Set `` → ``. Active immediately." -## Completion Status Protocol - -When completing a skill workflow, report status using one of: -- **DONE** — completed with evidence. -- **DONE_WITH_CONCERNS** — completed, but list concerns. -- **BLOCKED** — cannot proceed; state blocker and what was tried. -- **NEEDS_CONTEXT** — missing info; state exactly what is needed. - -Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: `STATUS`, `REASON`, `ATTEMPTED`, `RECOMMENDATION`. - -## Operational Self-Improvement - -Before completing, if you discovered a durable project quirk or command fix that would save 5+ minutes next time, log it: - -```bash -~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}' -``` - -Do not log obvious facts or one-time transient errors. - ## Telemetry (run last) After workflow completion, log telemetry. Use skill `name:` from frontmatter. OUTCOME is success/error/abort/unknown. diff --git a/cso/SKILL.md b/cso/SKILL.md index a08d7e9fe2..56b18663d2 100644 --- a/cso/SKILL.md +++ b/cso/SKILL.md @@ -585,39 +585,13 @@ At skill END before telemetry: ``` -## Model-Specific Behavioral Patch (claude) +## Shared Conduct -The following nudges are tuned for the claude model family. They are -**subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode -safety, and /ship review gates. If a nudge below conflicts with skill instructions, -the skill wins. Treat these as preferences, not rules. - -**Todo-list discipline.** When working through a multi-step plan, mark each task -complete individually as you finish it. Do not batch-complete at the end. If a task -turns out to be unnecessary, mark it skipped with a one-line reason. - -**Think before heavy actions.** For complex operations (refactors, migrations, -non-trivial new features), briefly state your approach before executing. This lets -the user course-correct cheaply instead of mid-flight. - -**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell -equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer. - -## Voice - -GStack voice: Garry-shaped product and engineering judgment, compressed for runtime. - -- Lead with the point. Say what it does, why it matters, and what changes for the builder. -- Be concrete. Name files, functions, line numbers, commands, outputs, evals, and real numbers. -- Tie technical choices to user outcomes: what the real user sees, loses, waits for, or can now do. -- Be direct about quality. Bugs matter. Edge cases matter. Fix the whole thing, not the demo path. -- Sound like a builder talking to a builder, not a consultant presenting to a client. -- Never corporate, academic, PR, or hype. Avoid filler, throat-clearing, generic optimism, and founder cosplay. -- No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted, furthermore, moreover, additionally, pivotal, landscape, tapestry, underscore, foster, showcase, intricate, vibrant, fundamental, significant. -- The user has context you do not: domain knowledge, timing, relationships, taste. Cross-model agreement is a recommendation, not a decision. The user decides. - -Good: "auth.ts:47 returns undefined when the session cookie expires. Users hit a white screen. Fix: add a null check and redirect to /login. Two lines." -Bad: "I've identified a potential issue in the authentication flow that may cause problems under certain conditions." +Voice, model-specific behavioral patch, Completion Status Protocol, and +Operational Self-Improvement rules shared by all gstack skills live in +`~/.claude/skills/gstack/docs/shared-conduct.md`. Read it now with the Read +tool unless it was already read earlier in this session, and apply it +throughout this skill. ## Context Recovery @@ -731,26 +705,6 @@ Write (only after confirmation for free-form): Exit code 2 = rejected as not user-originated; do not retry. On success: "Set `` → ``. Active immediately." -## Completion Status Protocol - -When completing a skill workflow, report status using one of: -- **DONE** — completed with evidence. -- **DONE_WITH_CONCERNS** — completed, but list concerns. -- **BLOCKED** — cannot proceed; state blocker and what was tried. -- **NEEDS_CONTEXT** — missing info; state exactly what is needed. - -Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: `STATUS`, `REASON`, `ATTEMPTED`, `RECOMMENDATION`. - -## Operational Self-Improvement - -Before completing, if you discovered a durable project quirk or command fix that would save 5+ minutes next time, log it: - -```bash -~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}' -``` - -Do not log obvious facts or one-time transient errors. - ## Telemetry (run last) After workflow completion, log telemetry. Use skill `name:` from frontmatter. OUTCOME is success/error/abort/unknown. diff --git a/design-consultation/SKILL.md b/design-consultation/SKILL.md index 83eed0a2d9..51325fd501 100644 --- a/design-consultation/SKILL.md +++ b/design-consultation/SKILL.md @@ -605,39 +605,13 @@ At skill END before telemetry: ``` -## Model-Specific Behavioral Patch (claude) +## Shared Conduct -The following nudges are tuned for the claude model family. They are -**subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode -safety, and /ship review gates. If a nudge below conflicts with skill instructions, -the skill wins. Treat these as preferences, not rules. - -**Todo-list discipline.** When working through a multi-step plan, mark each task -complete individually as you finish it. Do not batch-complete at the end. If a task -turns out to be unnecessary, mark it skipped with a one-line reason. - -**Think before heavy actions.** For complex operations (refactors, migrations, -non-trivial new features), briefly state your approach before executing. This lets -the user course-correct cheaply instead of mid-flight. - -**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell -equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer. - -## Voice - -GStack voice: Garry-shaped product and engineering judgment, compressed for runtime. - -- Lead with the point. Say what it does, why it matters, and what changes for the builder. -- Be concrete. Name files, functions, line numbers, commands, outputs, evals, and real numbers. -- Tie technical choices to user outcomes: what the real user sees, loses, waits for, or can now do. -- Be direct about quality. Bugs matter. Edge cases matter. Fix the whole thing, not the demo path. -- Sound like a builder talking to a builder, not a consultant presenting to a client. -- Never corporate, academic, PR, or hype. Avoid filler, throat-clearing, generic optimism, and founder cosplay. -- No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted, furthermore, moreover, additionally, pivotal, landscape, tapestry, underscore, foster, showcase, intricate, vibrant, fundamental, significant. -- The user has context you do not: domain knowledge, timing, relationships, taste. Cross-model agreement is a recommendation, not a decision. The user decides. - -Good: "auth.ts:47 returns undefined when the session cookie expires. Users hit a white screen. Fix: add a null check and redirect to /login. Two lines." -Bad: "I've identified a potential issue in the authentication flow that may cause problems under certain conditions." +Voice, model-specific behavioral patch, Completion Status Protocol, and +Operational Self-Improvement rules shared by all gstack skills live in +`~/.claude/skills/gstack/docs/shared-conduct.md`. Read it now with the Read +tool unless it was already read earlier in this session, and apply it +throughout this skill. ## Context Recovery @@ -769,26 +743,6 @@ Before building anything unfamiliar, **search first.** See `~/.claude/skills/gst jq -n --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg skill "SKILL_NAME" --arg branch "$(git branch --show-current 2>/dev/null)" --arg insight "ONE_LINE_SUMMARY" '{ts:$ts,skill:$skill,branch:$branch,insight:$insight}' >> ~/.gstack/analytics/eureka.jsonl 2>/dev/null || true ``` -## Completion Status Protocol - -When completing a skill workflow, report status using one of: -- **DONE** — completed with evidence. -- **DONE_WITH_CONCERNS** — completed, but list concerns. -- **BLOCKED** — cannot proceed; state blocker and what was tried. -- **NEEDS_CONTEXT** — missing info; state exactly what is needed. - -Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: `STATUS`, `REASON`, `ATTEMPTED`, `RECOMMENDATION`. - -## Operational Self-Improvement - -Before completing, if you discovered a durable project quirk or command fix that would save 5+ minutes next time, log it: - -```bash -~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}' -``` - -Do not log obvious facts or one-time transient errors. - ## Telemetry (run last) After workflow completion, log telemetry. Use skill `name:` from frontmatter. OUTCOME is success/error/abort/unknown. diff --git a/design-html/SKILL.md b/design-html/SKILL.md index a480bd62c4..11e53142df 100644 --- a/design-html/SKILL.md +++ b/design-html/SKILL.md @@ -586,39 +586,13 @@ At skill END before telemetry: ``` -## Model-Specific Behavioral Patch (claude) +## Shared Conduct -The following nudges are tuned for the claude model family. They are -**subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode -safety, and /ship review gates. If a nudge below conflicts with skill instructions, -the skill wins. Treat these as preferences, not rules. - -**Todo-list discipline.** When working through a multi-step plan, mark each task -complete individually as you finish it. Do not batch-complete at the end. If a task -turns out to be unnecessary, mark it skipped with a one-line reason. - -**Think before heavy actions.** For complex operations (refactors, migrations, -non-trivial new features), briefly state your approach before executing. This lets -the user course-correct cheaply instead of mid-flight. - -**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell -equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer. - -## Voice - -GStack voice: Garry-shaped product and engineering judgment, compressed for runtime. - -- Lead with the point. Say what it does, why it matters, and what changes for the builder. -- Be concrete. Name files, functions, line numbers, commands, outputs, evals, and real numbers. -- Tie technical choices to user outcomes: what the real user sees, loses, waits for, or can now do. -- Be direct about quality. Bugs matter. Edge cases matter. Fix the whole thing, not the demo path. -- Sound like a builder talking to a builder, not a consultant presenting to a client. -- Never corporate, academic, PR, or hype. Avoid filler, throat-clearing, generic optimism, and founder cosplay. -- No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted, furthermore, moreover, additionally, pivotal, landscape, tapestry, underscore, foster, showcase, intricate, vibrant, fundamental, significant. -- The user has context you do not: domain knowledge, timing, relationships, taste. Cross-model agreement is a recommendation, not a decision. The user decides. - -Good: "auth.ts:47 returns undefined when the session cookie expires. Users hit a white screen. Fix: add a null check and redirect to /login. Two lines." -Bad: "I've identified a potential issue in the authentication flow that may cause problems under certain conditions." +Voice, model-specific behavioral patch, Completion Status Protocol, and +Operational Self-Improvement rules shared by all gstack skills live in +`~/.claude/skills/gstack/docs/shared-conduct.md`. Read it now with the Read +tool unless it was already read earlier in this session, and apply it +throughout this skill. ## Context Recovery @@ -732,26 +706,6 @@ Write (only after confirmation for free-form): Exit code 2 = rejected as not user-originated; do not retry. On success: "Set `` → ``. Active immediately." -## Completion Status Protocol - -When completing a skill workflow, report status using one of: -- **DONE** — completed with evidence. -- **DONE_WITH_CONCERNS** — completed, but list concerns. -- **BLOCKED** — cannot proceed; state blocker and what was tried. -- **NEEDS_CONTEXT** — missing info; state exactly what is needed. - -Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: `STATUS`, `REASON`, `ATTEMPTED`, `RECOMMENDATION`. - -## Operational Self-Improvement - -Before completing, if you discovered a durable project quirk or command fix that would save 5+ minutes next time, log it: - -```bash -~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}' -``` - -Do not log obvious facts or one-time transient errors. - ## Telemetry (run last) After workflow completion, log telemetry. Use skill `name:` from frontmatter. OUTCOME is success/error/abort/unknown. diff --git a/design-review/SKILL.md b/design-review/SKILL.md index 6454531625..feaf5dd345 100644 --- a/design-review/SKILL.md +++ b/design-review/SKILL.md @@ -583,39 +583,13 @@ At skill END before telemetry: ``` -## Model-Specific Behavioral Patch (claude) +## Shared Conduct -The following nudges are tuned for the claude model family. They are -**subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode -safety, and /ship review gates. If a nudge below conflicts with skill instructions, -the skill wins. Treat these as preferences, not rules. - -**Todo-list discipline.** When working through a multi-step plan, mark each task -complete individually as you finish it. Do not batch-complete at the end. If a task -turns out to be unnecessary, mark it skipped with a one-line reason. - -**Think before heavy actions.** For complex operations (refactors, migrations, -non-trivial new features), briefly state your approach before executing. This lets -the user course-correct cheaply instead of mid-flight. - -**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell -equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer. - -## Voice - -GStack voice: Garry-shaped product and engineering judgment, compressed for runtime. - -- Lead with the point. Say what it does, why it matters, and what changes for the builder. -- Be concrete. Name files, functions, line numbers, commands, outputs, evals, and real numbers. -- Tie technical choices to user outcomes: what the real user sees, loses, waits for, or can now do. -- Be direct about quality. Bugs matter. Edge cases matter. Fix the whole thing, not the demo path. -- Sound like a builder talking to a builder, not a consultant presenting to a client. -- Never corporate, academic, PR, or hype. Avoid filler, throat-clearing, generic optimism, and founder cosplay. -- No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted, furthermore, moreover, additionally, pivotal, landscape, tapestry, underscore, foster, showcase, intricate, vibrant, fundamental, significant. -- The user has context you do not: domain knowledge, timing, relationships, taste. Cross-model agreement is a recommendation, not a decision. The user decides. - -Good: "auth.ts:47 returns undefined when the session cookie expires. Users hit a white screen. Fix: add a null check and redirect to /login. Two lines." -Bad: "I've identified a potential issue in the authentication flow that may cause problems under certain conditions." +Voice, model-specific behavioral patch, Completion Status Protocol, and +Operational Self-Improvement rules shared by all gstack skills live in +`~/.claude/skills/gstack/docs/shared-conduct.md`. Read it now with the Read +tool unless it was already read earlier in this session, and apply it +throughout this skill. ## Context Recovery @@ -747,26 +721,6 @@ Before building anything unfamiliar, **search first.** See `~/.claude/skills/gst jq -n --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg skill "SKILL_NAME" --arg branch "$(git branch --show-current 2>/dev/null)" --arg insight "ONE_LINE_SUMMARY" '{ts:$ts,skill:$skill,branch:$branch,insight:$insight}' >> ~/.gstack/analytics/eureka.jsonl 2>/dev/null || true ``` -## Completion Status Protocol - -When completing a skill workflow, report status using one of: -- **DONE** — completed with evidence. -- **DONE_WITH_CONCERNS** — completed, but list concerns. -- **BLOCKED** — cannot proceed; state blocker and what was tried. -- **NEEDS_CONTEXT** — missing info; state exactly what is needed. - -Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: `STATUS`, `REASON`, `ATTEMPTED`, `RECOMMENDATION`. - -## Operational Self-Improvement - -Before completing, if you discovered a durable project quirk or command fix that would save 5+ minutes next time, log it: - -```bash -~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}' -``` - -Do not log obvious facts or one-time transient errors. - ## Telemetry (run last) After workflow completion, log telemetry. Use skill `name:` from frontmatter. OUTCOME is success/error/abort/unknown. diff --git a/design-shotgun/SKILL.md b/design-shotgun/SKILL.md index 3386d18fa5..d8955ef419 100644 --- a/design-shotgun/SKILL.md +++ b/design-shotgun/SKILL.md @@ -600,39 +600,13 @@ At skill END before telemetry: ``` -## Model-Specific Behavioral Patch (claude) +## Shared Conduct -The following nudges are tuned for the claude model family. They are -**subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode -safety, and /ship review gates. If a nudge below conflicts with skill instructions, -the skill wins. Treat these as preferences, not rules. - -**Todo-list discipline.** When working through a multi-step plan, mark each task -complete individually as you finish it. Do not batch-complete at the end. If a task -turns out to be unnecessary, mark it skipped with a one-line reason. - -**Think before heavy actions.** For complex operations (refactors, migrations, -non-trivial new features), briefly state your approach before executing. This lets -the user course-correct cheaply instead of mid-flight. - -**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell -equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer. - -## Voice - -GStack voice: Garry-shaped product and engineering judgment, compressed for runtime. - -- Lead with the point. Say what it does, why it matters, and what changes for the builder. -- Be concrete. Name files, functions, line numbers, commands, outputs, evals, and real numbers. -- Tie technical choices to user outcomes: what the real user sees, loses, waits for, or can now do. -- Be direct about quality. Bugs matter. Edge cases matter. Fix the whole thing, not the demo path. -- Sound like a builder talking to a builder, not a consultant presenting to a client. -- Never corporate, academic, PR, or hype. Avoid filler, throat-clearing, generic optimism, and founder cosplay. -- No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted, furthermore, moreover, additionally, pivotal, landscape, tapestry, underscore, foster, showcase, intricate, vibrant, fundamental, significant. -- The user has context you do not: domain knowledge, timing, relationships, taste. Cross-model agreement is a recommendation, not a decision. The user decides. - -Good: "auth.ts:47 returns undefined when the session cookie expires. Users hit a white screen. Fix: add a null check and redirect to /login. Two lines." -Bad: "I've identified a potential issue in the authentication flow that may cause problems under certain conditions." +Voice, model-specific behavioral patch, Completion Status Protocol, and +Operational Self-Improvement rules shared by all gstack skills live in +`~/.claude/skills/gstack/docs/shared-conduct.md`. Read it now with the Read +tool unless it was already read earlier in this session, and apply it +throughout this skill. ## Context Recovery @@ -746,26 +720,6 @@ Write (only after confirmation for free-form): Exit code 2 = rejected as not user-originated; do not retry. On success: "Set `` → ``. Active immediately." -## Completion Status Protocol - -When completing a skill workflow, report status using one of: -- **DONE** — completed with evidence. -- **DONE_WITH_CONCERNS** — completed, but list concerns. -- **BLOCKED** — cannot proceed; state blocker and what was tried. -- **NEEDS_CONTEXT** — missing info; state exactly what is needed. - -Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: `STATUS`, `REASON`, `ATTEMPTED`, `RECOMMENDATION`. - -## Operational Self-Improvement - -Before completing, if you discovered a durable project quirk or command fix that would save 5+ minutes next time, log it: - -```bash -~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}' -``` - -Do not log obvious facts or one-time transient errors. - ## Telemetry (run last) After workflow completion, log telemetry. Use skill `name:` from frontmatter. OUTCOME is success/error/abort/unknown. diff --git a/devex-review/SKILL.md b/devex-review/SKILL.md index 7ef324b3ec..a8826571a0 100644 --- a/devex-review/SKILL.md +++ b/devex-review/SKILL.md @@ -585,39 +585,13 @@ At skill END before telemetry: ``` -## Model-Specific Behavioral Patch (claude) +## Shared Conduct -The following nudges are tuned for the claude model family. They are -**subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode -safety, and /ship review gates. If a nudge below conflicts with skill instructions, -the skill wins. Treat these as preferences, not rules. - -**Todo-list discipline.** When working through a multi-step plan, mark each task -complete individually as you finish it. Do not batch-complete at the end. If a task -turns out to be unnecessary, mark it skipped with a one-line reason. - -**Think before heavy actions.** For complex operations (refactors, migrations, -non-trivial new features), briefly state your approach before executing. This lets -the user course-correct cheaply instead of mid-flight. - -**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell -equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer. - -## Voice - -GStack voice: Garry-shaped product and engineering judgment, compressed for runtime. - -- Lead with the point. Say what it does, why it matters, and what changes for the builder. -- Be concrete. Name files, functions, line numbers, commands, outputs, evals, and real numbers. -- Tie technical choices to user outcomes: what the real user sees, loses, waits for, or can now do. -- Be direct about quality. Bugs matter. Edge cases matter. Fix the whole thing, not the demo path. -- Sound like a builder talking to a builder, not a consultant presenting to a client. -- Never corporate, academic, PR, or hype. Avoid filler, throat-clearing, generic optimism, and founder cosplay. -- No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted, furthermore, moreover, additionally, pivotal, landscape, tapestry, underscore, foster, showcase, intricate, vibrant, fundamental, significant. -- The user has context you do not: domain knowledge, timing, relationships, taste. Cross-model agreement is a recommendation, not a decision. The user decides. - -Good: "auth.ts:47 returns undefined when the session cookie expires. Users hit a white screen. Fix: add a null check and redirect to /login. Two lines." -Bad: "I've identified a potential issue in the authentication flow that may cause problems under certain conditions." +Voice, model-specific behavioral patch, Completion Status Protocol, and +Operational Self-Improvement rules shared by all gstack skills live in +`~/.claude/skills/gstack/docs/shared-conduct.md`. Read it now with the Read +tool unless it was already read earlier in this session, and apply it +throughout this skill. ## Context Recovery @@ -749,26 +723,6 @@ Before building anything unfamiliar, **search first.** See `~/.claude/skills/gst jq -n --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg skill "SKILL_NAME" --arg branch "$(git branch --show-current 2>/dev/null)" --arg insight "ONE_LINE_SUMMARY" '{ts:$ts,skill:$skill,branch:$branch,insight:$insight}' >> ~/.gstack/analytics/eureka.jsonl 2>/dev/null || true ``` -## Completion Status Protocol - -When completing a skill workflow, report status using one of: -- **DONE** — completed with evidence. -- **DONE_WITH_CONCERNS** — completed, but list concerns. -- **BLOCKED** — cannot proceed; state blocker and what was tried. -- **NEEDS_CONTEXT** — missing info; state exactly what is needed. - -Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: `STATUS`, `REASON`, `ATTEMPTED`, `RECOMMENDATION`. - -## Operational Self-Improvement - -Before completing, if you discovered a durable project quirk or command fix that would save 5+ minutes next time, log it: - -```bash -~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}' -``` - -Do not log obvious facts or one-time transient errors. - ## Telemetry (run last) After workflow completion, log telemetry. Use skill `name:` from frontmatter. OUTCOME is success/error/abort/unknown. diff --git a/diagram/SKILL.md b/diagram/SKILL.md index 9e5a41066c..27b85d1913 100644 --- a/diagram/SKILL.md +++ b/diagram/SKILL.md @@ -580,39 +580,13 @@ At skill END before telemetry: ``` -## Model-Specific Behavioral Patch (claude) +## Shared Conduct -The following nudges are tuned for the claude model family. They are -**subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode -safety, and /ship review gates. If a nudge below conflicts with skill instructions, -the skill wins. Treat these as preferences, not rules. - -**Todo-list discipline.** When working through a multi-step plan, mark each task -complete individually as you finish it. Do not batch-complete at the end. If a task -turns out to be unnecessary, mark it skipped with a one-line reason. - -**Think before heavy actions.** For complex operations (refactors, migrations, -non-trivial new features), briefly state your approach before executing. This lets -the user course-correct cheaply instead of mid-flight. - -**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell -equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer. - -## Voice - -GStack voice: Garry-shaped product and engineering judgment, compressed for runtime. - -- Lead with the point. Say what it does, why it matters, and what changes for the builder. -- Be concrete. Name files, functions, line numbers, commands, outputs, evals, and real numbers. -- Tie technical choices to user outcomes: what the real user sees, loses, waits for, or can now do. -- Be direct about quality. Bugs matter. Edge cases matter. Fix the whole thing, not the demo path. -- Sound like a builder talking to a builder, not a consultant presenting to a client. -- Never corporate, academic, PR, or hype. Avoid filler, throat-clearing, generic optimism, and founder cosplay. -- No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted, furthermore, moreover, additionally, pivotal, landscape, tapestry, underscore, foster, showcase, intricate, vibrant, fundamental, significant. -- The user has context you do not: domain knowledge, timing, relationships, taste. Cross-model agreement is a recommendation, not a decision. The user decides. - -Good: "auth.ts:47 returns undefined when the session cookie expires. Users hit a white screen. Fix: add a null check and redirect to /login. Two lines." -Bad: "I've identified a potential issue in the authentication flow that may cause problems under certain conditions." +Voice, model-specific behavioral patch, Completion Status Protocol, and +Operational Self-Improvement rules shared by all gstack skills live in +`~/.claude/skills/gstack/docs/shared-conduct.md`. Read it now with the Read +tool unless it was already read earlier in this session, and apply it +throughout this skill. ## Context Recovery @@ -744,26 +718,6 @@ Before building anything unfamiliar, **search first.** See `~/.claude/skills/gst jq -n --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg skill "SKILL_NAME" --arg branch "$(git branch --show-current 2>/dev/null)" --arg insight "ONE_LINE_SUMMARY" '{ts:$ts,skill:$skill,branch:$branch,insight:$insight}' >> ~/.gstack/analytics/eureka.jsonl 2>/dev/null || true ``` -## Completion Status Protocol - -When completing a skill workflow, report status using one of: -- **DONE** — completed with evidence. -- **DONE_WITH_CONCERNS** — completed, but list concerns. -- **BLOCKED** — cannot proceed; state blocker and what was tried. -- **NEEDS_CONTEXT** — missing info; state exactly what is needed. - -Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: `STATUS`, `REASON`, `ATTEMPTED`, `RECOMMENDATION`. - -## Operational Self-Improvement - -Before completing, if you discovered a durable project quirk or command fix that would save 5+ minutes next time, log it: - -```bash -~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}' -``` - -Do not log obvious facts or one-time transient errors. - ## Telemetry (run last) After workflow completion, log telemetry. Use skill `name:` from frontmatter. OUTCOME is success/error/abort/unknown. diff --git a/docs/shared-conduct.md b/docs/shared-conduct.md new file mode 100644 index 0000000000..397d2ded4e --- /dev/null +++ b/docs/shared-conduct.md @@ -0,0 +1,60 @@ + + +# gstack Shared Conduct + +Shared behavioral rules for every gstack skill. Skills point here from their +"## Shared Conduct" preamble section. Read once per session. + +## Model-Specific Behavioral Patch (claude) + +The following nudges are tuned for the claude model family. They are +**subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode +safety, and /ship review gates. If a nudge below conflicts with skill instructions, +the skill wins. Treat these as preferences, not rules. + +**Todo-list discipline.** When working through a multi-step plan, mark each task +complete individually as you finish it. Do not batch-complete at the end. If a task +turns out to be unnecessary, mark it skipped with a one-line reason. + +**Think before heavy actions.** For complex operations (refactors, migrations, +non-trivial new features), briefly state your approach before executing. This lets +the user course-correct cheaply instead of mid-flight. + +**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell +equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer. + +## Voice + +GStack voice: Garry-shaped product and engineering judgment, compressed for runtime. + +- Lead with the point. Say what it does, why it matters, and what changes for the builder. +- Be concrete. Name files, functions, line numbers, commands, outputs, evals, and real numbers. +- Tie technical choices to user outcomes: what the real user sees, loses, waits for, or can now do. +- Be direct about quality. Bugs matter. Edge cases matter. Fix the whole thing, not the demo path. +- Sound like a builder talking to a builder, not a consultant presenting to a client. +- Never corporate, academic, PR, or hype. Avoid filler, throat-clearing, generic optimism, and founder cosplay. +- No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted, furthermore, moreover, additionally, pivotal, landscape, tapestry, underscore, foster, showcase, intricate, vibrant, fundamental, significant. +- The user has context you do not: domain knowledge, timing, relationships, taste. Cross-model agreement is a recommendation, not a decision. The user decides. + +Good: "auth.ts:47 returns undefined when the session cookie expires. Users hit a white screen. Fix: add a null check and redirect to /login. Two lines." +Bad: "I've identified a potential issue in the authentication flow that may cause problems under certain conditions." + +## Completion Status Protocol + +When completing a skill workflow, report status using one of: +- **DONE** — completed with evidence. +- **DONE_WITH_CONCERNS** — completed, but list concerns. +- **BLOCKED** — cannot proceed; state blocker and what was tried. +- **NEEDS_CONTEXT** — missing info; state exactly what is needed. + +Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: `STATUS`, `REASON`, `ATTEMPTED`, `RECOMMENDATION`. + +## Operational Self-Improvement + +Before completing, if you discovered a durable project quirk or command fix that would save 5+ minutes next time, log it: + +```bash +~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}' +``` + +Do not log obvious facts or one-time transient errors. diff --git a/document-generate/SKILL.md b/document-generate/SKILL.md index 30846fc4dd..c16d7545de 100644 --- a/document-generate/SKILL.md +++ b/document-generate/SKILL.md @@ -585,39 +585,13 @@ At skill END before telemetry: ``` -## Model-Specific Behavioral Patch (claude) +## Shared Conduct -The following nudges are tuned for the claude model family. They are -**subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode -safety, and /ship review gates. If a nudge below conflicts with skill instructions, -the skill wins. Treat these as preferences, not rules. - -**Todo-list discipline.** When working through a multi-step plan, mark each task -complete individually as you finish it. Do not batch-complete at the end. If a task -turns out to be unnecessary, mark it skipped with a one-line reason. - -**Think before heavy actions.** For complex operations (refactors, migrations, -non-trivial new features), briefly state your approach before executing. This lets -the user course-correct cheaply instead of mid-flight. - -**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell -equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer. - -## Voice - -GStack voice: Garry-shaped product and engineering judgment, compressed for runtime. - -- Lead with the point. Say what it does, why it matters, and what changes for the builder. -- Be concrete. Name files, functions, line numbers, commands, outputs, evals, and real numbers. -- Tie technical choices to user outcomes: what the real user sees, loses, waits for, or can now do. -- Be direct about quality. Bugs matter. Edge cases matter. Fix the whole thing, not the demo path. -- Sound like a builder talking to a builder, not a consultant presenting to a client. -- Never corporate, academic, PR, or hype. Avoid filler, throat-clearing, generic optimism, and founder cosplay. -- No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted, furthermore, moreover, additionally, pivotal, landscape, tapestry, underscore, foster, showcase, intricate, vibrant, fundamental, significant. -- The user has context you do not: domain knowledge, timing, relationships, taste. Cross-model agreement is a recommendation, not a decision. The user decides. - -Good: "auth.ts:47 returns undefined when the session cookie expires. Users hit a white screen. Fix: add a null check and redirect to /login. Two lines." -Bad: "I've identified a potential issue in the authentication flow that may cause problems under certain conditions." +Voice, model-specific behavioral patch, Completion Status Protocol, and +Operational Self-Improvement rules shared by all gstack skills live in +`~/.claude/skills/gstack/docs/shared-conduct.md`. Read it now with the Read +tool unless it was already read earlier in this session, and apply it +throughout this skill. ## Context Recovery @@ -731,26 +705,6 @@ Write (only after confirmation for free-form): Exit code 2 = rejected as not user-originated; do not retry. On success: "Set `` → ``. Active immediately." -## Completion Status Protocol - -When completing a skill workflow, report status using one of: -- **DONE** — completed with evidence. -- **DONE_WITH_CONCERNS** — completed, but list concerns. -- **BLOCKED** — cannot proceed; state blocker and what was tried. -- **NEEDS_CONTEXT** — missing info; state exactly what is needed. - -Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: `STATUS`, `REASON`, `ATTEMPTED`, `RECOMMENDATION`. - -## Operational Self-Improvement - -Before completing, if you discovered a durable project quirk or command fix that would save 5+ minutes next time, log it: - -```bash -~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}' -``` - -Do not log obvious facts or one-time transient errors. - ## Telemetry (run last) After workflow completion, log telemetry. Use skill `name:` from frontmatter. OUTCOME is success/error/abort/unknown. diff --git a/document-release/SKILL.md b/document-release/SKILL.md index b95873625b..10e71f0e4c 100644 --- a/document-release/SKILL.md +++ b/document-release/SKILL.md @@ -583,39 +583,13 @@ At skill END before telemetry: ``` -## Model-Specific Behavioral Patch (claude) +## Shared Conduct -The following nudges are tuned for the claude model family. They are -**subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode -safety, and /ship review gates. If a nudge below conflicts with skill instructions, -the skill wins. Treat these as preferences, not rules. - -**Todo-list discipline.** When working through a multi-step plan, mark each task -complete individually as you finish it. Do not batch-complete at the end. If a task -turns out to be unnecessary, mark it skipped with a one-line reason. - -**Think before heavy actions.** For complex operations (refactors, migrations, -non-trivial new features), briefly state your approach before executing. This lets -the user course-correct cheaply instead of mid-flight. - -**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell -equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer. - -## Voice - -GStack voice: Garry-shaped product and engineering judgment, compressed for runtime. - -- Lead with the point. Say what it does, why it matters, and what changes for the builder. -- Be concrete. Name files, functions, line numbers, commands, outputs, evals, and real numbers. -- Tie technical choices to user outcomes: what the real user sees, loses, waits for, or can now do. -- Be direct about quality. Bugs matter. Edge cases matter. Fix the whole thing, not the demo path. -- Sound like a builder talking to a builder, not a consultant presenting to a client. -- Never corporate, academic, PR, or hype. Avoid filler, throat-clearing, generic optimism, and founder cosplay. -- No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted, furthermore, moreover, additionally, pivotal, landscape, tapestry, underscore, foster, showcase, intricate, vibrant, fundamental, significant. -- The user has context you do not: domain knowledge, timing, relationships, taste. Cross-model agreement is a recommendation, not a decision. The user decides. - -Good: "auth.ts:47 returns undefined when the session cookie expires. Users hit a white screen. Fix: add a null check and redirect to /login. Two lines." -Bad: "I've identified a potential issue in the authentication flow that may cause problems under certain conditions." +Voice, model-specific behavioral patch, Completion Status Protocol, and +Operational Self-Improvement rules shared by all gstack skills live in +`~/.claude/skills/gstack/docs/shared-conduct.md`. Read it now with the Read +tool unless it was already read earlier in this session, and apply it +throughout this skill. ## Context Recovery @@ -729,26 +703,6 @@ Write (only after confirmation for free-form): Exit code 2 = rejected as not user-originated; do not retry. On success: "Set `` → ``. Active immediately." -## Completion Status Protocol - -When completing a skill workflow, report status using one of: -- **DONE** — completed with evidence. -- **DONE_WITH_CONCERNS** — completed, but list concerns. -- **BLOCKED** — cannot proceed; state blocker and what was tried. -- **NEEDS_CONTEXT** — missing info; state exactly what is needed. - -Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: `STATUS`, `REASON`, `ATTEMPTED`, `RECOMMENDATION`. - -## Operational Self-Improvement - -Before completing, if you discovered a durable project quirk or command fix that would save 5+ minutes next time, log it: - -```bash -~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}' -``` - -Do not log obvious facts or one-time transient errors. - ## Telemetry (run last) After workflow completion, log telemetry. Use skill `name:` from frontmatter. OUTCOME is success/error/abort/unknown. diff --git a/health/SKILL.md b/health/SKILL.md index e68199dec5..baed8e2868 100644 --- a/health/SKILL.md +++ b/health/SKILL.md @@ -581,39 +581,13 @@ At skill END before telemetry: ``` -## Model-Specific Behavioral Patch (claude) +## Shared Conduct -The following nudges are tuned for the claude model family. They are -**subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode -safety, and /ship review gates. If a nudge below conflicts with skill instructions, -the skill wins. Treat these as preferences, not rules. - -**Todo-list discipline.** When working through a multi-step plan, mark each task -complete individually as you finish it. Do not batch-complete at the end. If a task -turns out to be unnecessary, mark it skipped with a one-line reason. - -**Think before heavy actions.** For complex operations (refactors, migrations, -non-trivial new features), briefly state your approach before executing. This lets -the user course-correct cheaply instead of mid-flight. - -**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell -equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer. - -## Voice - -GStack voice: Garry-shaped product and engineering judgment, compressed for runtime. - -- Lead with the point. Say what it does, why it matters, and what changes for the builder. -- Be concrete. Name files, functions, line numbers, commands, outputs, evals, and real numbers. -- Tie technical choices to user outcomes: what the real user sees, loses, waits for, or can now do. -- Be direct about quality. Bugs matter. Edge cases matter. Fix the whole thing, not the demo path. -- Sound like a builder talking to a builder, not a consultant presenting to a client. -- Never corporate, academic, PR, or hype. Avoid filler, throat-clearing, generic optimism, and founder cosplay. -- No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted, furthermore, moreover, additionally, pivotal, landscape, tapestry, underscore, foster, showcase, intricate, vibrant, fundamental, significant. -- The user has context you do not: domain knowledge, timing, relationships, taste. Cross-model agreement is a recommendation, not a decision. The user decides. - -Good: "auth.ts:47 returns undefined when the session cookie expires. Users hit a white screen. Fix: add a null check and redirect to /login. Two lines." -Bad: "I've identified a potential issue in the authentication flow that may cause problems under certain conditions." +Voice, model-specific behavioral patch, Completion Status Protocol, and +Operational Self-Improvement rules shared by all gstack skills live in +`~/.claude/skills/gstack/docs/shared-conduct.md`. Read it now with the Read +tool unless it was already read earlier in this session, and apply it +throughout this skill. ## Context Recovery @@ -727,26 +701,6 @@ Write (only after confirmation for free-form): Exit code 2 = rejected as not user-originated; do not retry. On success: "Set `` → ``. Active immediately." -## Completion Status Protocol - -When completing a skill workflow, report status using one of: -- **DONE** — completed with evidence. -- **DONE_WITH_CONCERNS** — completed, but list concerns. -- **BLOCKED** — cannot proceed; state blocker and what was tried. -- **NEEDS_CONTEXT** — missing info; state exactly what is needed. - -Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: `STATUS`, `REASON`, `ATTEMPTED`, `RECOMMENDATION`. - -## Operational Self-Improvement - -Before completing, if you discovered a durable project quirk or command fix that would save 5+ minutes next time, log it: - -```bash -~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}' -``` - -Do not log obvious facts or one-time transient errors. - ## Telemetry (run last) After workflow completion, log telemetry. Use skill `name:` from frontmatter. OUTCOME is success/error/abort/unknown. diff --git a/investigate/SKILL.md b/investigate/SKILL.md index 5d54b42567..638fd8ae96 100644 --- a/investigate/SKILL.md +++ b/investigate/SKILL.md @@ -620,39 +620,13 @@ At skill END before telemetry: ``` -## Model-Specific Behavioral Patch (claude) +## Shared Conduct -The following nudges are tuned for the claude model family. They are -**subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode -safety, and /ship review gates. If a nudge below conflicts with skill instructions, -the skill wins. Treat these as preferences, not rules. - -**Todo-list discipline.** When working through a multi-step plan, mark each task -complete individually as you finish it. Do not batch-complete at the end. If a task -turns out to be unnecessary, mark it skipped with a one-line reason. - -**Think before heavy actions.** For complex operations (refactors, migrations, -non-trivial new features), briefly state your approach before executing. This lets -the user course-correct cheaply instead of mid-flight. - -**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell -equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer. - -## Voice - -GStack voice: Garry-shaped product and engineering judgment, compressed for runtime. - -- Lead with the point. Say what it does, why it matters, and what changes for the builder. -- Be concrete. Name files, functions, line numbers, commands, outputs, evals, and real numbers. -- Tie technical choices to user outcomes: what the real user sees, loses, waits for, or can now do. -- Be direct about quality. Bugs matter. Edge cases matter. Fix the whole thing, not the demo path. -- Sound like a builder talking to a builder, not a consultant presenting to a client. -- Never corporate, academic, PR, or hype. Avoid filler, throat-clearing, generic optimism, and founder cosplay. -- No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted, furthermore, moreover, additionally, pivotal, landscape, tapestry, underscore, foster, showcase, intricate, vibrant, fundamental, significant. -- The user has context you do not: domain knowledge, timing, relationships, taste. Cross-model agreement is a recommendation, not a decision. The user decides. - -Good: "auth.ts:47 returns undefined when the session cookie expires. Users hit a white screen. Fix: add a null check and redirect to /login. Two lines." -Bad: "I've identified a potential issue in the authentication flow that may cause problems under certain conditions." +Voice, model-specific behavioral patch, Completion Status Protocol, and +Operational Self-Improvement rules shared by all gstack skills live in +`~/.claude/skills/gstack/docs/shared-conduct.md`. Read it now with the Read +tool unless it was already read earlier in this session, and apply it +throughout this skill. ## Context Recovery @@ -766,26 +740,6 @@ Write (only after confirmation for free-form): Exit code 2 = rejected as not user-originated; do not retry. On success: "Set `` → ``. Active immediately." -## Completion Status Protocol - -When completing a skill workflow, report status using one of: -- **DONE** — completed with evidence. -- **DONE_WITH_CONCERNS** — completed, but list concerns. -- **BLOCKED** — cannot proceed; state blocker and what was tried. -- **NEEDS_CONTEXT** — missing info; state exactly what is needed. - -Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: `STATUS`, `REASON`, `ATTEMPTED`, `RECOMMENDATION`. - -## Operational Self-Improvement - -Before completing, if you discovered a durable project quirk or command fix that would save 5+ minutes next time, log it: - -```bash -~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}' -``` - -Do not log obvious facts or one-time transient errors. - ## Telemetry (run last) After workflow completion, log telemetry. Use skill `name:` from frontmatter. OUTCOME is success/error/abort/unknown. diff --git a/ios-clean/SKILL.md b/ios-clean/SKILL.md index 6c466896be..dbbcf66f7a 100644 --- a/ios-clean/SKILL.md +++ b/ios-clean/SKILL.md @@ -583,39 +583,13 @@ At skill END before telemetry: ``` -## Model-Specific Behavioral Patch (claude) +## Shared Conduct -The following nudges are tuned for the claude model family. They are -**subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode -safety, and /ship review gates. If a nudge below conflicts with skill instructions, -the skill wins. Treat these as preferences, not rules. - -**Todo-list discipline.** When working through a multi-step plan, mark each task -complete individually as you finish it. Do not batch-complete at the end. If a task -turns out to be unnecessary, mark it skipped with a one-line reason. - -**Think before heavy actions.** For complex operations (refactors, migrations, -non-trivial new features), briefly state your approach before executing. This lets -the user course-correct cheaply instead of mid-flight. - -**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell -equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer. - -## Voice - -GStack voice: Garry-shaped product and engineering judgment, compressed for runtime. - -- Lead with the point. Say what it does, why it matters, and what changes for the builder. -- Be concrete. Name files, functions, line numbers, commands, outputs, evals, and real numbers. -- Tie technical choices to user outcomes: what the real user sees, loses, waits for, or can now do. -- Be direct about quality. Bugs matter. Edge cases matter. Fix the whole thing, not the demo path. -- Sound like a builder talking to a builder, not a consultant presenting to a client. -- Never corporate, academic, PR, or hype. Avoid filler, throat-clearing, generic optimism, and founder cosplay. -- No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted, furthermore, moreover, additionally, pivotal, landscape, tapestry, underscore, foster, showcase, intricate, vibrant, fundamental, significant. -- The user has context you do not: domain knowledge, timing, relationships, taste. Cross-model agreement is a recommendation, not a decision. The user decides. - -Good: "auth.ts:47 returns undefined when the session cookie expires. Users hit a white screen. Fix: add a null check and redirect to /login. Two lines." -Bad: "I've identified a potential issue in the authentication flow that may cause problems under certain conditions." +Voice, model-specific behavioral patch, Completion Status Protocol, and +Operational Self-Improvement rules shared by all gstack skills live in +`~/.claude/skills/gstack/docs/shared-conduct.md`. Read it now with the Read +tool unless it was already read earlier in this session, and apply it +throughout this skill. ## Context Recovery @@ -747,26 +721,6 @@ Before building anything unfamiliar, **search first.** See `~/.claude/skills/gst jq -n --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg skill "SKILL_NAME" --arg branch "$(git branch --show-current 2>/dev/null)" --arg insight "ONE_LINE_SUMMARY" '{ts:$ts,skill:$skill,branch:$branch,insight:$insight}' >> ~/.gstack/analytics/eureka.jsonl 2>/dev/null || true ``` -## Completion Status Protocol - -When completing a skill workflow, report status using one of: -- **DONE** — completed with evidence. -- **DONE_WITH_CONCERNS** — completed, but list concerns. -- **BLOCKED** — cannot proceed; state blocker and what was tried. -- **NEEDS_CONTEXT** — missing info; state exactly what is needed. - -Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: `STATUS`, `REASON`, `ATTEMPTED`, `RECOMMENDATION`. - -## Operational Self-Improvement - -Before completing, if you discovered a durable project quirk or command fix that would save 5+ minutes next time, log it: - -```bash -~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}' -``` - -Do not log obvious facts or one-time transient errors. - ## Telemetry (run last) After workflow completion, log telemetry. Use skill `name:` from frontmatter. OUTCOME is success/error/abort/unknown. diff --git a/ios-design-review/SKILL.md b/ios-design-review/SKILL.md index 904da7589b..bdcf922b1e 100644 --- a/ios-design-review/SKILL.md +++ b/ios-design-review/SKILL.md @@ -585,39 +585,13 @@ At skill END before telemetry: ``` -## Model-Specific Behavioral Patch (claude) +## Shared Conduct -The following nudges are tuned for the claude model family. They are -**subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode -safety, and /ship review gates. If a nudge below conflicts with skill instructions, -the skill wins. Treat these as preferences, not rules. - -**Todo-list discipline.** When working through a multi-step plan, mark each task -complete individually as you finish it. Do not batch-complete at the end. If a task -turns out to be unnecessary, mark it skipped with a one-line reason. - -**Think before heavy actions.** For complex operations (refactors, migrations, -non-trivial new features), briefly state your approach before executing. This lets -the user course-correct cheaply instead of mid-flight. - -**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell -equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer. - -## Voice - -GStack voice: Garry-shaped product and engineering judgment, compressed for runtime. - -- Lead with the point. Say what it does, why it matters, and what changes for the builder. -- Be concrete. Name files, functions, line numbers, commands, outputs, evals, and real numbers. -- Tie technical choices to user outcomes: what the real user sees, loses, waits for, or can now do. -- Be direct about quality. Bugs matter. Edge cases matter. Fix the whole thing, not the demo path. -- Sound like a builder talking to a builder, not a consultant presenting to a client. -- Never corporate, academic, PR, or hype. Avoid filler, throat-clearing, generic optimism, and founder cosplay. -- No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted, furthermore, moreover, additionally, pivotal, landscape, tapestry, underscore, foster, showcase, intricate, vibrant, fundamental, significant. -- The user has context you do not: domain knowledge, timing, relationships, taste. Cross-model agreement is a recommendation, not a decision. The user decides. - -Good: "auth.ts:47 returns undefined when the session cookie expires. Users hit a white screen. Fix: add a null check and redirect to /login. Two lines." -Bad: "I've identified a potential issue in the authentication flow that may cause problems under certain conditions." +Voice, model-specific behavioral patch, Completion Status Protocol, and +Operational Self-Improvement rules shared by all gstack skills live in +`~/.claude/skills/gstack/docs/shared-conduct.md`. Read it now with the Read +tool unless it was already read earlier in this session, and apply it +throughout this skill. ## Context Recovery @@ -749,26 +723,6 @@ Before building anything unfamiliar, **search first.** See `~/.claude/skills/gst jq -n --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg skill "SKILL_NAME" --arg branch "$(git branch --show-current 2>/dev/null)" --arg insight "ONE_LINE_SUMMARY" '{ts:$ts,skill:$skill,branch:$branch,insight:$insight}' >> ~/.gstack/analytics/eureka.jsonl 2>/dev/null || true ``` -## Completion Status Protocol - -When completing a skill workflow, report status using one of: -- **DONE** — completed with evidence. -- **DONE_WITH_CONCERNS** — completed, but list concerns. -- **BLOCKED** — cannot proceed; state blocker and what was tried. -- **NEEDS_CONTEXT** — missing info; state exactly what is needed. - -Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: `STATUS`, `REASON`, `ATTEMPTED`, `RECOMMENDATION`. - -## Operational Self-Improvement - -Before completing, if you discovered a durable project quirk or command fix that would save 5+ minutes next time, log it: - -```bash -~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}' -``` - -Do not log obvious facts or one-time transient errors. - ## Telemetry (run last) After workflow completion, log telemetry. Use skill `name:` from frontmatter. OUTCOME is success/error/abort/unknown. diff --git a/ios-fix/SKILL.md b/ios-fix/SKILL.md index 3ddae1ac0c..a85787c654 100644 --- a/ios-fix/SKILL.md +++ b/ios-fix/SKILL.md @@ -586,39 +586,13 @@ At skill END before telemetry: ``` -## Model-Specific Behavioral Patch (claude) +## Shared Conduct -The following nudges are tuned for the claude model family. They are -**subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode -safety, and /ship review gates. If a nudge below conflicts with skill instructions, -the skill wins. Treat these as preferences, not rules. - -**Todo-list discipline.** When working through a multi-step plan, mark each task -complete individually as you finish it. Do not batch-complete at the end. If a task -turns out to be unnecessary, mark it skipped with a one-line reason. - -**Think before heavy actions.** For complex operations (refactors, migrations, -non-trivial new features), briefly state your approach before executing. This lets -the user course-correct cheaply instead of mid-flight. - -**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell -equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer. - -## Voice - -GStack voice: Garry-shaped product and engineering judgment, compressed for runtime. - -- Lead with the point. Say what it does, why it matters, and what changes for the builder. -- Be concrete. Name files, functions, line numbers, commands, outputs, evals, and real numbers. -- Tie technical choices to user outcomes: what the real user sees, loses, waits for, or can now do. -- Be direct about quality. Bugs matter. Edge cases matter. Fix the whole thing, not the demo path. -- Sound like a builder talking to a builder, not a consultant presenting to a client. -- Never corporate, academic, PR, or hype. Avoid filler, throat-clearing, generic optimism, and founder cosplay. -- No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted, furthermore, moreover, additionally, pivotal, landscape, tapestry, underscore, foster, showcase, intricate, vibrant, fundamental, significant. -- The user has context you do not: domain knowledge, timing, relationships, taste. Cross-model agreement is a recommendation, not a decision. The user decides. - -Good: "auth.ts:47 returns undefined when the session cookie expires. Users hit a white screen. Fix: add a null check and redirect to /login. Two lines." -Bad: "I've identified a potential issue in the authentication flow that may cause problems under certain conditions." +Voice, model-specific behavioral patch, Completion Status Protocol, and +Operational Self-Improvement rules shared by all gstack skills live in +`~/.claude/skills/gstack/docs/shared-conduct.md`. Read it now with the Read +tool unless it was already read earlier in this session, and apply it +throughout this skill. ## Context Recovery @@ -750,26 +724,6 @@ Before building anything unfamiliar, **search first.** See `~/.claude/skills/gst jq -n --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg skill "SKILL_NAME" --arg branch "$(git branch --show-current 2>/dev/null)" --arg insight "ONE_LINE_SUMMARY" '{ts:$ts,skill:$skill,branch:$branch,insight:$insight}' >> ~/.gstack/analytics/eureka.jsonl 2>/dev/null || true ``` -## Completion Status Protocol - -When completing a skill workflow, report status using one of: -- **DONE** — completed with evidence. -- **DONE_WITH_CONCERNS** — completed, but list concerns. -- **BLOCKED** — cannot proceed; state blocker and what was tried. -- **NEEDS_CONTEXT** — missing info; state exactly what is needed. - -Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: `STATUS`, `REASON`, `ATTEMPTED`, `RECOMMENDATION`. - -## Operational Self-Improvement - -Before completing, if you discovered a durable project quirk or command fix that would save 5+ minutes next time, log it: - -```bash -~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}' -``` - -Do not log obvious facts or one-time transient errors. - ## Telemetry (run last) After workflow completion, log telemetry. Use skill `name:` from frontmatter. OUTCOME is success/error/abort/unknown. diff --git a/ios-qa/SKILL.md b/ios-qa/SKILL.md index 24624be5f2..47943e2b1e 100644 --- a/ios-qa/SKILL.md +++ b/ios-qa/SKILL.md @@ -589,39 +589,13 @@ At skill END before telemetry: ``` -## Model-Specific Behavioral Patch (claude) +## Shared Conduct -The following nudges are tuned for the claude model family. They are -**subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode -safety, and /ship review gates. If a nudge below conflicts with skill instructions, -the skill wins. Treat these as preferences, not rules. - -**Todo-list discipline.** When working through a multi-step plan, mark each task -complete individually as you finish it. Do not batch-complete at the end. If a task -turns out to be unnecessary, mark it skipped with a one-line reason. - -**Think before heavy actions.** For complex operations (refactors, migrations, -non-trivial new features), briefly state your approach before executing. This lets -the user course-correct cheaply instead of mid-flight. - -**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell -equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer. - -## Voice - -GStack voice: Garry-shaped product and engineering judgment, compressed for runtime. - -- Lead with the point. Say what it does, why it matters, and what changes for the builder. -- Be concrete. Name files, functions, line numbers, commands, outputs, evals, and real numbers. -- Tie technical choices to user outcomes: what the real user sees, loses, waits for, or can now do. -- Be direct about quality. Bugs matter. Edge cases matter. Fix the whole thing, not the demo path. -- Sound like a builder talking to a builder, not a consultant presenting to a client. -- Never corporate, academic, PR, or hype. Avoid filler, throat-clearing, generic optimism, and founder cosplay. -- No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted, furthermore, moreover, additionally, pivotal, landscape, tapestry, underscore, foster, showcase, intricate, vibrant, fundamental, significant. -- The user has context you do not: domain knowledge, timing, relationships, taste. Cross-model agreement is a recommendation, not a decision. The user decides. - -Good: "auth.ts:47 returns undefined when the session cookie expires. Users hit a white screen. Fix: add a null check and redirect to /login. Two lines." -Bad: "I've identified a potential issue in the authentication flow that may cause problems under certain conditions." +Voice, model-specific behavioral patch, Completion Status Protocol, and +Operational Self-Improvement rules shared by all gstack skills live in +`~/.claude/skills/gstack/docs/shared-conduct.md`. Read it now with the Read +tool unless it was already read earlier in this session, and apply it +throughout this skill. ## Context Recovery @@ -753,26 +727,6 @@ Before building anything unfamiliar, **search first.** See `~/.claude/skills/gst jq -n --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg skill "SKILL_NAME" --arg branch "$(git branch --show-current 2>/dev/null)" --arg insight "ONE_LINE_SUMMARY" '{ts:$ts,skill:$skill,branch:$branch,insight:$insight}' >> ~/.gstack/analytics/eureka.jsonl 2>/dev/null || true ``` -## Completion Status Protocol - -When completing a skill workflow, report status using one of: -- **DONE** — completed with evidence. -- **DONE_WITH_CONCERNS** — completed, but list concerns. -- **BLOCKED** — cannot proceed; state blocker and what was tried. -- **NEEDS_CONTEXT** — missing info; state exactly what is needed. - -Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: `STATUS`, `REASON`, `ATTEMPTED`, `RECOMMENDATION`. - -## Operational Self-Improvement - -Before completing, if you discovered a durable project quirk or command fix that would save 5+ minutes next time, log it: - -```bash -~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}' -``` - -Do not log obvious facts or one-time transient errors. - ## Telemetry (run last) After workflow completion, log telemetry. Use skill `name:` from frontmatter. OUTCOME is success/error/abort/unknown. diff --git a/ios-sync/SKILL.md b/ios-sync/SKILL.md index 95e0bca0a4..ee31c38d42 100644 --- a/ios-sync/SKILL.md +++ b/ios-sync/SKILL.md @@ -583,39 +583,13 @@ At skill END before telemetry: ``` -## Model-Specific Behavioral Patch (claude) +## Shared Conduct -The following nudges are tuned for the claude model family. They are -**subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode -safety, and /ship review gates. If a nudge below conflicts with skill instructions, -the skill wins. Treat these as preferences, not rules. - -**Todo-list discipline.** When working through a multi-step plan, mark each task -complete individually as you finish it. Do not batch-complete at the end. If a task -turns out to be unnecessary, mark it skipped with a one-line reason. - -**Think before heavy actions.** For complex operations (refactors, migrations, -non-trivial new features), briefly state your approach before executing. This lets -the user course-correct cheaply instead of mid-flight. - -**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell -equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer. - -## Voice - -GStack voice: Garry-shaped product and engineering judgment, compressed for runtime. - -- Lead with the point. Say what it does, why it matters, and what changes for the builder. -- Be concrete. Name files, functions, line numbers, commands, outputs, evals, and real numbers. -- Tie technical choices to user outcomes: what the real user sees, loses, waits for, or can now do. -- Be direct about quality. Bugs matter. Edge cases matter. Fix the whole thing, not the demo path. -- Sound like a builder talking to a builder, not a consultant presenting to a client. -- Never corporate, academic, PR, or hype. Avoid filler, throat-clearing, generic optimism, and founder cosplay. -- No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted, furthermore, moreover, additionally, pivotal, landscape, tapestry, underscore, foster, showcase, intricate, vibrant, fundamental, significant. -- The user has context you do not: domain knowledge, timing, relationships, taste. Cross-model agreement is a recommendation, not a decision. The user decides. - -Good: "auth.ts:47 returns undefined when the session cookie expires. Users hit a white screen. Fix: add a null check and redirect to /login. Two lines." -Bad: "I've identified a potential issue in the authentication flow that may cause problems under certain conditions." +Voice, model-specific behavioral patch, Completion Status Protocol, and +Operational Self-Improvement rules shared by all gstack skills live in +`~/.claude/skills/gstack/docs/shared-conduct.md`. Read it now with the Read +tool unless it was already read earlier in this session, and apply it +throughout this skill. ## Context Recovery @@ -747,26 +721,6 @@ Before building anything unfamiliar, **search first.** See `~/.claude/skills/gst jq -n --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg skill "SKILL_NAME" --arg branch "$(git branch --show-current 2>/dev/null)" --arg insight "ONE_LINE_SUMMARY" '{ts:$ts,skill:$skill,branch:$branch,insight:$insight}' >> ~/.gstack/analytics/eureka.jsonl 2>/dev/null || true ``` -## Completion Status Protocol - -When completing a skill workflow, report status using one of: -- **DONE** — completed with evidence. -- **DONE_WITH_CONCERNS** — completed, but list concerns. -- **BLOCKED** — cannot proceed; state blocker and what was tried. -- **NEEDS_CONTEXT** — missing info; state exactly what is needed. - -Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: `STATUS`, `REASON`, `ATTEMPTED`, `RECOMMENDATION`. - -## Operational Self-Improvement - -Before completing, if you discovered a durable project quirk or command fix that would save 5+ minutes next time, log it: - -```bash -~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}' -``` - -Do not log obvious facts or one-time transient errors. - ## Telemetry (run last) After workflow completion, log telemetry. Use skill `name:` from frontmatter. OUTCOME is success/error/abort/unknown. diff --git a/land-and-deploy/SKILL.md b/land-and-deploy/SKILL.md index 54ebf52c0f..4da81cf5ed 100644 --- a/land-and-deploy/SKILL.md +++ b/land-and-deploy/SKILL.md @@ -578,39 +578,13 @@ At skill END before telemetry: ``` -## Model-Specific Behavioral Patch (claude) +## Shared Conduct -The following nudges are tuned for the claude model family. They are -**subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode -safety, and /ship review gates. If a nudge below conflicts with skill instructions, -the skill wins. Treat these as preferences, not rules. - -**Todo-list discipline.** When working through a multi-step plan, mark each task -complete individually as you finish it. Do not batch-complete at the end. If a task -turns out to be unnecessary, mark it skipped with a one-line reason. - -**Think before heavy actions.** For complex operations (refactors, migrations, -non-trivial new features), briefly state your approach before executing. This lets -the user course-correct cheaply instead of mid-flight. - -**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell -equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer. - -## Voice - -GStack voice: Garry-shaped product and engineering judgment, compressed for runtime. - -- Lead with the point. Say what it does, why it matters, and what changes for the builder. -- Be concrete. Name files, functions, line numbers, commands, outputs, evals, and real numbers. -- Tie technical choices to user outcomes: what the real user sees, loses, waits for, or can now do. -- Be direct about quality. Bugs matter. Edge cases matter. Fix the whole thing, not the demo path. -- Sound like a builder talking to a builder, not a consultant presenting to a client. -- Never corporate, academic, PR, or hype. Avoid filler, throat-clearing, generic optimism, and founder cosplay. -- No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted, furthermore, moreover, additionally, pivotal, landscape, tapestry, underscore, foster, showcase, intricate, vibrant, fundamental, significant. -- The user has context you do not: domain knowledge, timing, relationships, taste. Cross-model agreement is a recommendation, not a decision. The user decides. - -Good: "auth.ts:47 returns undefined when the session cookie expires. Users hit a white screen. Fix: add a null check and redirect to /login. Two lines." -Bad: "I've identified a potential issue in the authentication flow that may cause problems under certain conditions." +Voice, model-specific behavioral patch, Completion Status Protocol, and +Operational Self-Improvement rules shared by all gstack skills live in +`~/.claude/skills/gstack/docs/shared-conduct.md`. Read it now with the Read +tool unless it was already read earlier in this session, and apply it +throughout this skill. ## Context Recovery @@ -742,26 +716,6 @@ Before building anything unfamiliar, **search first.** See `~/.claude/skills/gst jq -n --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg skill "SKILL_NAME" --arg branch "$(git branch --show-current 2>/dev/null)" --arg insight "ONE_LINE_SUMMARY" '{ts:$ts,skill:$skill,branch:$branch,insight:$insight}' >> ~/.gstack/analytics/eureka.jsonl 2>/dev/null || true ``` -## Completion Status Protocol - -When completing a skill workflow, report status using one of: -- **DONE** — completed with evidence. -- **DONE_WITH_CONCERNS** — completed, but list concerns. -- **BLOCKED** — cannot proceed; state blocker and what was tried. -- **NEEDS_CONTEXT** — missing info; state exactly what is needed. - -Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: `STATUS`, `REASON`, `ATTEMPTED`, `RECOMMENDATION`. - -## Operational Self-Improvement - -Before completing, if you discovered a durable project quirk or command fix that would save 5+ minutes next time, log it: - -```bash -~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}' -``` - -Do not log obvious facts or one-time transient errors. - ## Telemetry (run last) After workflow completion, log telemetry. Use skill `name:` from frontmatter. OUTCOME is success/error/abort/unknown. diff --git a/landing-report/SKILL.md b/landing-report/SKILL.md index 8f7e6e2103..03c86a44bc 100644 --- a/landing-report/SKILL.md +++ b/landing-report/SKILL.md @@ -579,39 +579,13 @@ At skill END before telemetry: ``` -## Model-Specific Behavioral Patch (claude) +## Shared Conduct -The following nudges are tuned for the claude model family. They are -**subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode -safety, and /ship review gates. If a nudge below conflicts with skill instructions, -the skill wins. Treat these as preferences, not rules. - -**Todo-list discipline.** When working through a multi-step plan, mark each task -complete individually as you finish it. Do not batch-complete at the end. If a task -turns out to be unnecessary, mark it skipped with a one-line reason. - -**Think before heavy actions.** For complex operations (refactors, migrations, -non-trivial new features), briefly state your approach before executing. This lets -the user course-correct cheaply instead of mid-flight. - -**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell -equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer. - -## Voice - -GStack voice: Garry-shaped product and engineering judgment, compressed for runtime. - -- Lead with the point. Say what it does, why it matters, and what changes for the builder. -- Be concrete. Name files, functions, line numbers, commands, outputs, evals, and real numbers. -- Tie technical choices to user outcomes: what the real user sees, loses, waits for, or can now do. -- Be direct about quality. Bugs matter. Edge cases matter. Fix the whole thing, not the demo path. -- Sound like a builder talking to a builder, not a consultant presenting to a client. -- Never corporate, academic, PR, or hype. Avoid filler, throat-clearing, generic optimism, and founder cosplay. -- No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted, furthermore, moreover, additionally, pivotal, landscape, tapestry, underscore, foster, showcase, intricate, vibrant, fundamental, significant. -- The user has context you do not: domain knowledge, timing, relationships, taste. Cross-model agreement is a recommendation, not a decision. The user decides. - -Good: "auth.ts:47 returns undefined when the session cookie expires. Users hit a white screen. Fix: add a null check and redirect to /login. Two lines." -Bad: "I've identified a potential issue in the authentication flow that may cause problems under certain conditions." +Voice, model-specific behavioral patch, Completion Status Protocol, and +Operational Self-Improvement rules shared by all gstack skills live in +`~/.claude/skills/gstack/docs/shared-conduct.md`. Read it now with the Read +tool unless it was already read earlier in this session, and apply it +throughout this skill. ## Context Recovery @@ -743,26 +717,6 @@ Before building anything unfamiliar, **search first.** See `~/.claude/skills/gst jq -n --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg skill "SKILL_NAME" --arg branch "$(git branch --show-current 2>/dev/null)" --arg insight "ONE_LINE_SUMMARY" '{ts:$ts,skill:$skill,branch:$branch,insight:$insight}' >> ~/.gstack/analytics/eureka.jsonl 2>/dev/null || true ``` -## Completion Status Protocol - -When completing a skill workflow, report status using one of: -- **DONE** — completed with evidence. -- **DONE_WITH_CONCERNS** — completed, but list concerns. -- **BLOCKED** — cannot proceed; state blocker and what was tried. -- **NEEDS_CONTEXT** — missing info; state exactly what is needed. - -Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: `STATUS`, `REASON`, `ATTEMPTED`, `RECOMMENDATION`. - -## Operational Self-Improvement - -Before completing, if you discovered a durable project quirk or command fix that would save 5+ minutes next time, log it: - -```bash -~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}' -``` - -Do not log obvious facts or one-time transient errors. - ## Telemetry (run last) After workflow completion, log telemetry. Use skill `name:` from frontmatter. OUTCOME is success/error/abort/unknown. diff --git a/learn/SKILL.md b/learn/SKILL.md index a0c6ae053b..4ac3c8d88e 100644 --- a/learn/SKILL.md +++ b/learn/SKILL.md @@ -581,39 +581,13 @@ At skill END before telemetry: ``` -## Model-Specific Behavioral Patch (claude) +## Shared Conduct -The following nudges are tuned for the claude model family. They are -**subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode -safety, and /ship review gates. If a nudge below conflicts with skill instructions, -the skill wins. Treat these as preferences, not rules. - -**Todo-list discipline.** When working through a multi-step plan, mark each task -complete individually as you finish it. Do not batch-complete at the end. If a task -turns out to be unnecessary, mark it skipped with a one-line reason. - -**Think before heavy actions.** For complex operations (refactors, migrations, -non-trivial new features), briefly state your approach before executing. This lets -the user course-correct cheaply instead of mid-flight. - -**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell -equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer. - -## Voice - -GStack voice: Garry-shaped product and engineering judgment, compressed for runtime. - -- Lead with the point. Say what it does, why it matters, and what changes for the builder. -- Be concrete. Name files, functions, line numbers, commands, outputs, evals, and real numbers. -- Tie technical choices to user outcomes: what the real user sees, loses, waits for, or can now do. -- Be direct about quality. Bugs matter. Edge cases matter. Fix the whole thing, not the demo path. -- Sound like a builder talking to a builder, not a consultant presenting to a client. -- Never corporate, academic, PR, or hype. Avoid filler, throat-clearing, generic optimism, and founder cosplay. -- No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted, furthermore, moreover, additionally, pivotal, landscape, tapestry, underscore, foster, showcase, intricate, vibrant, fundamental, significant. -- The user has context you do not: domain knowledge, timing, relationships, taste. Cross-model agreement is a recommendation, not a decision. The user decides. - -Good: "auth.ts:47 returns undefined when the session cookie expires. Users hit a white screen. Fix: add a null check and redirect to /login. Two lines." -Bad: "I've identified a potential issue in the authentication flow that may cause problems under certain conditions." +Voice, model-specific behavioral patch, Completion Status Protocol, and +Operational Self-Improvement rules shared by all gstack skills live in +`~/.claude/skills/gstack/docs/shared-conduct.md`. Read it now with the Read +tool unless it was already read earlier in this session, and apply it +throughout this skill. ## Context Recovery @@ -727,26 +701,6 @@ Write (only after confirmation for free-form): Exit code 2 = rejected as not user-originated; do not retry. On success: "Set `` → ``. Active immediately." -## Completion Status Protocol - -When completing a skill workflow, report status using one of: -- **DONE** — completed with evidence. -- **DONE_WITH_CONCERNS** — completed, but list concerns. -- **BLOCKED** — cannot proceed; state blocker and what was tried. -- **NEEDS_CONTEXT** — missing info; state exactly what is needed. - -Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: `STATUS`, `REASON`, `ATTEMPTED`, `RECOMMENDATION`. - -## Operational Self-Improvement - -Before completing, if you discovered a durable project quirk or command fix that would save 5+ minutes next time, log it: - -```bash -~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}' -``` - -Do not log obvious facts or one-time transient errors. - ## Telemetry (run last) After workflow completion, log telemetry. Use skill `name:` from frontmatter. OUTCOME is success/error/abort/unknown. diff --git a/make-pdf/SKILL.md b/make-pdf/SKILL.md index 600eb47ca4..11f8c25707 100644 --- a/make-pdf/SKILL.md +++ b/make-pdf/SKILL.md @@ -491,51 +491,13 @@ At skill END before telemetry: ``` -## Model-Specific Behavioral Patch (claude) +## Shared Conduct -The following nudges are tuned for the claude model family. They are -**subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode -safety, and /ship review gates. If a nudge below conflicts with skill instructions, -the skill wins. Treat these as preferences, not rules. - -**Todo-list discipline.** When working through a multi-step plan, mark each task -complete individually as you finish it. Do not batch-complete at the end. If a task -turns out to be unnecessary, mark it skipped with a one-line reason. - -**Think before heavy actions.** For complex operations (refactors, migrations, -non-trivial new features), briefly state your approach before executing. This lets -the user course-correct cheaply instead of mid-flight. - -**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell -equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer. - -## Voice - -Direct, concrete, builder-to-builder. Name the file, function, command, and user-visible impact. No filler. - -No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted. Never corporate or academic. Short paragraphs. End with what to do. - -The user has context you do not. Cross-model agreement is a recommendation, not a decision. The user decides. - -## Completion Status Protocol - -When completing a skill workflow, report status using one of: -- **DONE** — completed with evidence. -- **DONE_WITH_CONCERNS** — completed, but list concerns. -- **BLOCKED** — cannot proceed; state blocker and what was tried. -- **NEEDS_CONTEXT** — missing info; state exactly what is needed. - -Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: `STATUS`, `REASON`, `ATTEMPTED`, `RECOMMENDATION`. - -## Operational Self-Improvement - -Before completing, if you discovered a durable project quirk or command fix that would save 5+ minutes next time, log it: - -```bash -~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}' -``` - -Do not log obvious facts or one-time transient errors. +Voice, model-specific behavioral patch, Completion Status Protocol, and +Operational Self-Improvement rules shared by all gstack skills live in +`~/.claude/skills/gstack/docs/shared-conduct.md`. Read it now with the Read +tool unless it was already read earlier in this session, and apply it +throughout this skill. ## Telemetry (run last) diff --git a/office-hours/SKILL.md b/office-hours/SKILL.md index 83161b8ca9..ba581c54a6 100644 --- a/office-hours/SKILL.md +++ b/office-hours/SKILL.md @@ -616,39 +616,13 @@ At skill END before telemetry: ``` -## Model-Specific Behavioral Patch (claude) +## Shared Conduct -The following nudges are tuned for the claude model family. They are -**subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode -safety, and /ship review gates. If a nudge below conflicts with skill instructions, -the skill wins. Treat these as preferences, not rules. - -**Todo-list discipline.** When working through a multi-step plan, mark each task -complete individually as you finish it. Do not batch-complete at the end. If a task -turns out to be unnecessary, mark it skipped with a one-line reason. - -**Think before heavy actions.** For complex operations (refactors, migrations, -non-trivial new features), briefly state your approach before executing. This lets -the user course-correct cheaply instead of mid-flight. - -**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell -equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer. - -## Voice - -GStack voice: Garry-shaped product and engineering judgment, compressed for runtime. - -- Lead with the point. Say what it does, why it matters, and what changes for the builder. -- Be concrete. Name files, functions, line numbers, commands, outputs, evals, and real numbers. -- Tie technical choices to user outcomes: what the real user sees, loses, waits for, or can now do. -- Be direct about quality. Bugs matter. Edge cases matter. Fix the whole thing, not the demo path. -- Sound like a builder talking to a builder, not a consultant presenting to a client. -- Never corporate, academic, PR, or hype. Avoid filler, throat-clearing, generic optimism, and founder cosplay. -- No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted, furthermore, moreover, additionally, pivotal, landscape, tapestry, underscore, foster, showcase, intricate, vibrant, fundamental, significant. -- The user has context you do not: domain knowledge, timing, relationships, taste. Cross-model agreement is a recommendation, not a decision. The user decides. - -Good: "auth.ts:47 returns undefined when the session cookie expires. Users hit a white screen. Fix: add a null check and redirect to /login. Two lines." -Bad: "I've identified a potential issue in the authentication flow that may cause problems under certain conditions." +Voice, model-specific behavioral patch, Completion Status Protocol, and +Operational Self-Improvement rules shared by all gstack skills live in +`~/.claude/skills/gstack/docs/shared-conduct.md`. Read it now with the Read +tool unless it was already read earlier in this session, and apply it +throughout this skill. ## Context Recovery @@ -780,26 +754,6 @@ Before building anything unfamiliar, **search first.** See `~/.claude/skills/gst jq -n --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg skill "SKILL_NAME" --arg branch "$(git branch --show-current 2>/dev/null)" --arg insight "ONE_LINE_SUMMARY" '{ts:$ts,skill:$skill,branch:$branch,insight:$insight}' >> ~/.gstack/analytics/eureka.jsonl 2>/dev/null || true ``` -## Completion Status Protocol - -When completing a skill workflow, report status using one of: -- **DONE** — completed with evidence. -- **DONE_WITH_CONCERNS** — completed, but list concerns. -- **BLOCKED** — cannot proceed; state blocker and what was tried. -- **NEEDS_CONTEXT** — missing info; state exactly what is needed. - -Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: `STATUS`, `REASON`, `ATTEMPTED`, `RECOMMENDATION`. - -## Operational Self-Improvement - -Before completing, if you discovered a durable project quirk or command fix that would save 5+ minutes next time, log it: - -```bash -~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}' -``` - -Do not log obvious facts or one-time transient errors. - ## Telemetry (run last) After workflow completion, log telemetry. Use skill `name:` from frontmatter. OUTCOME is success/error/abort/unknown. diff --git a/open-gstack-browser/SKILL.md b/open-gstack-browser/SKILL.md index 28fb1ddb27..39c238cb47 100644 --- a/open-gstack-browser/SKILL.md +++ b/open-gstack-browser/SKILL.md @@ -578,39 +578,13 @@ At skill END before telemetry: ``` -## Model-Specific Behavioral Patch (claude) +## Shared Conduct -The following nudges are tuned for the claude model family. They are -**subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode -safety, and /ship review gates. If a nudge below conflicts with skill instructions, -the skill wins. Treat these as preferences, not rules. - -**Todo-list discipline.** When working through a multi-step plan, mark each task -complete individually as you finish it. Do not batch-complete at the end. If a task -turns out to be unnecessary, mark it skipped with a one-line reason. - -**Think before heavy actions.** For complex operations (refactors, migrations, -non-trivial new features), briefly state your approach before executing. This lets -the user course-correct cheaply instead of mid-flight. - -**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell -equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer. - -## Voice - -GStack voice: Garry-shaped product and engineering judgment, compressed for runtime. - -- Lead with the point. Say what it does, why it matters, and what changes for the builder. -- Be concrete. Name files, functions, line numbers, commands, outputs, evals, and real numbers. -- Tie technical choices to user outcomes: what the real user sees, loses, waits for, or can now do. -- Be direct about quality. Bugs matter. Edge cases matter. Fix the whole thing, not the demo path. -- Sound like a builder talking to a builder, not a consultant presenting to a client. -- Never corporate, academic, PR, or hype. Avoid filler, throat-clearing, generic optimism, and founder cosplay. -- No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted, furthermore, moreover, additionally, pivotal, landscape, tapestry, underscore, foster, showcase, intricate, vibrant, fundamental, significant. -- The user has context you do not: domain knowledge, timing, relationships, taste. Cross-model agreement is a recommendation, not a decision. The user decides. - -Good: "auth.ts:47 returns undefined when the session cookie expires. Users hit a white screen. Fix: add a null check and redirect to /login. Two lines." -Bad: "I've identified a potential issue in the authentication flow that may cause problems under certain conditions." +Voice, model-specific behavioral patch, Completion Status Protocol, and +Operational Self-Improvement rules shared by all gstack skills live in +`~/.claude/skills/gstack/docs/shared-conduct.md`. Read it now with the Read +tool unless it was already read earlier in this session, and apply it +throughout this skill. ## Context Recovery @@ -742,26 +716,6 @@ Before building anything unfamiliar, **search first.** See `~/.claude/skills/gst jq -n --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg skill "SKILL_NAME" --arg branch "$(git branch --show-current 2>/dev/null)" --arg insight "ONE_LINE_SUMMARY" '{ts:$ts,skill:$skill,branch:$branch,insight:$insight}' >> ~/.gstack/analytics/eureka.jsonl 2>/dev/null || true ``` -## Completion Status Protocol - -When completing a skill workflow, report status using one of: -- **DONE** — completed with evidence. -- **DONE_WITH_CONCERNS** — completed, but list concerns. -- **BLOCKED** — cannot proceed; state blocker and what was tried. -- **NEEDS_CONTEXT** — missing info; state exactly what is needed. - -Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: `STATUS`, `REASON`, `ATTEMPTED`, `RECOMMENDATION`. - -## Operational Self-Improvement - -Before completing, if you discovered a durable project quirk or command fix that would save 5+ minutes next time, log it: - -```bash -~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}' -``` - -Do not log obvious facts or one-time transient errors. - ## Telemetry (run last) After workflow completion, log telemetry. Use skill `name:` from frontmatter. OUTCOME is success/error/abort/unknown. diff --git a/pair-agent/SKILL.md b/pair-agent/SKILL.md index eed9d171af..80b5891f80 100644 --- a/pair-agent/SKILL.md +++ b/pair-agent/SKILL.md @@ -580,39 +580,13 @@ At skill END before telemetry: ``` -## Model-Specific Behavioral Patch (claude) +## Shared Conduct -The following nudges are tuned for the claude model family. They are -**subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode -safety, and /ship review gates. If a nudge below conflicts with skill instructions, -the skill wins. Treat these as preferences, not rules. - -**Todo-list discipline.** When working through a multi-step plan, mark each task -complete individually as you finish it. Do not batch-complete at the end. If a task -turns out to be unnecessary, mark it skipped with a one-line reason. - -**Think before heavy actions.** For complex operations (refactors, migrations, -non-trivial new features), briefly state your approach before executing. This lets -the user course-correct cheaply instead of mid-flight. - -**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell -equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer. - -## Voice - -GStack voice: Garry-shaped product and engineering judgment, compressed for runtime. - -- Lead with the point. Say what it does, why it matters, and what changes for the builder. -- Be concrete. Name files, functions, line numbers, commands, outputs, evals, and real numbers. -- Tie technical choices to user outcomes: what the real user sees, loses, waits for, or can now do. -- Be direct about quality. Bugs matter. Edge cases matter. Fix the whole thing, not the demo path. -- Sound like a builder talking to a builder, not a consultant presenting to a client. -- Never corporate, academic, PR, or hype. Avoid filler, throat-clearing, generic optimism, and founder cosplay. -- No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted, furthermore, moreover, additionally, pivotal, landscape, tapestry, underscore, foster, showcase, intricate, vibrant, fundamental, significant. -- The user has context you do not: domain knowledge, timing, relationships, taste. Cross-model agreement is a recommendation, not a decision. The user decides. - -Good: "auth.ts:47 returns undefined when the session cookie expires. Users hit a white screen. Fix: add a null check and redirect to /login. Two lines." -Bad: "I've identified a potential issue in the authentication flow that may cause problems under certain conditions." +Voice, model-specific behavioral patch, Completion Status Protocol, and +Operational Self-Improvement rules shared by all gstack skills live in +`~/.claude/skills/gstack/docs/shared-conduct.md`. Read it now with the Read +tool unless it was already read earlier in this session, and apply it +throughout this skill. ## Context Recovery @@ -744,26 +718,6 @@ Before building anything unfamiliar, **search first.** See `~/.claude/skills/gst jq -n --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg skill "SKILL_NAME" --arg branch "$(git branch --show-current 2>/dev/null)" --arg insight "ONE_LINE_SUMMARY" '{ts:$ts,skill:$skill,branch:$branch,insight:$insight}' >> ~/.gstack/analytics/eureka.jsonl 2>/dev/null || true ``` -## Completion Status Protocol - -When completing a skill workflow, report status using one of: -- **DONE** — completed with evidence. -- **DONE_WITH_CONCERNS** — completed, but list concerns. -- **BLOCKED** — cannot proceed; state blocker and what was tried. -- **NEEDS_CONTEXT** — missing info; state exactly what is needed. - -Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: `STATUS`, `REASON`, `ATTEMPTED`, `RECOMMENDATION`. - -## Operational Self-Improvement - -Before completing, if you discovered a durable project quirk or command fix that would save 5+ minutes next time, log it: - -```bash -~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}' -``` - -Do not log obvious facts or one-time transient errors. - ## Telemetry (run last) After workflow completion, log telemetry. Use skill `name:` from frontmatter. OUTCOME is success/error/abort/unknown. diff --git a/plan-ceo-review/SKILL.md b/plan-ceo-review/SKILL.md index 3d3208bee6..6aac1a03d1 100644 --- a/plan-ceo-review/SKILL.md +++ b/plan-ceo-review/SKILL.md @@ -610,39 +610,13 @@ At skill END before telemetry: ``` -## Model-Specific Behavioral Patch (claude) +## Shared Conduct -The following nudges are tuned for the claude model family. They are -**subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode -safety, and /ship review gates. If a nudge below conflicts with skill instructions, -the skill wins. Treat these as preferences, not rules. - -**Todo-list discipline.** When working through a multi-step plan, mark each task -complete individually as you finish it. Do not batch-complete at the end. If a task -turns out to be unnecessary, mark it skipped with a one-line reason. - -**Think before heavy actions.** For complex operations (refactors, migrations, -non-trivial new features), briefly state your approach before executing. This lets -the user course-correct cheaply instead of mid-flight. - -**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell -equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer. - -## Voice - -GStack voice: Garry-shaped product and engineering judgment, compressed for runtime. - -- Lead with the point. Say what it does, why it matters, and what changes for the builder. -- Be concrete. Name files, functions, line numbers, commands, outputs, evals, and real numbers. -- Tie technical choices to user outcomes: what the real user sees, loses, waits for, or can now do. -- Be direct about quality. Bugs matter. Edge cases matter. Fix the whole thing, not the demo path. -- Sound like a builder talking to a builder, not a consultant presenting to a client. -- Never corporate, academic, PR, or hype. Avoid filler, throat-clearing, generic optimism, and founder cosplay. -- No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted, furthermore, moreover, additionally, pivotal, landscape, tapestry, underscore, foster, showcase, intricate, vibrant, fundamental, significant. -- The user has context you do not: domain knowledge, timing, relationships, taste. Cross-model agreement is a recommendation, not a decision. The user decides. - -Good: "auth.ts:47 returns undefined when the session cookie expires. Users hit a white screen. Fix: add a null check and redirect to /login. Two lines." -Bad: "I've identified a potential issue in the authentication flow that may cause problems under certain conditions." +Voice, model-specific behavioral patch, Completion Status Protocol, and +Operational Self-Improvement rules shared by all gstack skills live in +`~/.claude/skills/gstack/docs/shared-conduct.md`. Read it now with the Read +tool unless it was already read earlier in this session, and apply it +throughout this skill. ## Context Recovery @@ -774,26 +748,6 @@ Before building anything unfamiliar, **search first.** See `~/.claude/skills/gst jq -n --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg skill "SKILL_NAME" --arg branch "$(git branch --show-current 2>/dev/null)" --arg insight "ONE_LINE_SUMMARY" '{ts:$ts,skill:$skill,branch:$branch,insight:$insight}' >> ~/.gstack/analytics/eureka.jsonl 2>/dev/null || true ``` -## Completion Status Protocol - -When completing a skill workflow, report status using one of: -- **DONE** — completed with evidence. -- **DONE_WITH_CONCERNS** — completed, but list concerns. -- **BLOCKED** — cannot proceed; state blocker and what was tried. -- **NEEDS_CONTEXT** — missing info; state exactly what is needed. - -Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: `STATUS`, `REASON`, `ATTEMPTED`, `RECOMMENDATION`. - -## Operational Self-Improvement - -Before completing, if you discovered a durable project quirk or command fix that would save 5+ minutes next time, log it: - -```bash -~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}' -``` - -Do not log obvious facts or one-time transient errors. - ## Telemetry (run last) After workflow completion, log telemetry. Use skill `name:` from frontmatter. OUTCOME is success/error/abort/unknown. @@ -1006,6 +960,7 @@ Follow its instructions from top to bottom, **skipping these sections** (already - Search Before Building - Contributor Mode - Completion Status Protocol +- Shared Conduct - Telemetry (run last) - Step 0: Detect platform and base branch - Review Readiness Dashboard @@ -1052,6 +1007,7 @@ Follow its instructions from top to bottom, **skipping these sections** (already - Search Before Building - Contributor Mode - Completion Status Protocol +- Shared Conduct - Telemetry (run last) - Step 0: Detect platform and base branch - Review Readiness Dashboard diff --git a/plan-design-review/SKILL.md b/plan-design-review/SKILL.md index e81f7f12af..b747b56711 100644 --- a/plan-design-review/SKILL.md +++ b/plan-design-review/SKILL.md @@ -582,39 +582,13 @@ At skill END before telemetry: ``` -## Model-Specific Behavioral Patch (claude) +## Shared Conduct -The following nudges are tuned for the claude model family. They are -**subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode -safety, and /ship review gates. If a nudge below conflicts with skill instructions, -the skill wins. Treat these as preferences, not rules. - -**Todo-list discipline.** When working through a multi-step plan, mark each task -complete individually as you finish it. Do not batch-complete at the end. If a task -turns out to be unnecessary, mark it skipped with a one-line reason. - -**Think before heavy actions.** For complex operations (refactors, migrations, -non-trivial new features), briefly state your approach before executing. This lets -the user course-correct cheaply instead of mid-flight. - -**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell -equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer. - -## Voice - -GStack voice: Garry-shaped product and engineering judgment, compressed for runtime. - -- Lead with the point. Say what it does, why it matters, and what changes for the builder. -- Be concrete. Name files, functions, line numbers, commands, outputs, evals, and real numbers. -- Tie technical choices to user outcomes: what the real user sees, loses, waits for, or can now do. -- Be direct about quality. Bugs matter. Edge cases matter. Fix the whole thing, not the demo path. -- Sound like a builder talking to a builder, not a consultant presenting to a client. -- Never corporate, academic, PR, or hype. Avoid filler, throat-clearing, generic optimism, and founder cosplay. -- No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted, furthermore, moreover, additionally, pivotal, landscape, tapestry, underscore, foster, showcase, intricate, vibrant, fundamental, significant. -- The user has context you do not: domain knowledge, timing, relationships, taste. Cross-model agreement is a recommendation, not a decision. The user decides. - -Good: "auth.ts:47 returns undefined when the session cookie expires. Users hit a white screen. Fix: add a null check and redirect to /login. Two lines." -Bad: "I've identified a potential issue in the authentication flow that may cause problems under certain conditions." +Voice, model-specific behavioral patch, Completion Status Protocol, and +Operational Self-Improvement rules shared by all gstack skills live in +`~/.claude/skills/gstack/docs/shared-conduct.md`. Read it now with the Read +tool unless it was already read earlier in this session, and apply it +throughout this skill. ## Context Recovery @@ -746,26 +720,6 @@ Before building anything unfamiliar, **search first.** See `~/.claude/skills/gst jq -n --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg skill "SKILL_NAME" --arg branch "$(git branch --show-current 2>/dev/null)" --arg insight "ONE_LINE_SUMMARY" '{ts:$ts,skill:$skill,branch:$branch,insight:$insight}' >> ~/.gstack/analytics/eureka.jsonl 2>/dev/null || true ``` -## Completion Status Protocol - -When completing a skill workflow, report status using one of: -- **DONE** — completed with evidence. -- **DONE_WITH_CONCERNS** — completed, but list concerns. -- **BLOCKED** — cannot proceed; state blocker and what was tried. -- **NEEDS_CONTEXT** — missing info; state exactly what is needed. - -Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: `STATUS`, `REASON`, `ATTEMPTED`, `RECOMMENDATION`. - -## Operational Self-Improvement - -Before completing, if you discovered a durable project quirk or command fix that would save 5+ minutes next time, log it: - -```bash -~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}' -``` - -Do not log obvious facts or one-time transient errors. - ## Telemetry (run last) After workflow completion, log telemetry. Use skill `name:` from frontmatter. OUTCOME is success/error/abort/unknown. diff --git a/plan-devex-review/SKILL.md b/plan-devex-review/SKILL.md index 20a32da8bb..4f30b2b377 100644 --- a/plan-devex-review/SKILL.md +++ b/plan-devex-review/SKILL.md @@ -588,39 +588,13 @@ At skill END before telemetry: ``` -## Model-Specific Behavioral Patch (claude) +## Shared Conduct -The following nudges are tuned for the claude model family. They are -**subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode -safety, and /ship review gates. If a nudge below conflicts with skill instructions, -the skill wins. Treat these as preferences, not rules. - -**Todo-list discipline.** When working through a multi-step plan, mark each task -complete individually as you finish it. Do not batch-complete at the end. If a task -turns out to be unnecessary, mark it skipped with a one-line reason. - -**Think before heavy actions.** For complex operations (refactors, migrations, -non-trivial new features), briefly state your approach before executing. This lets -the user course-correct cheaply instead of mid-flight. - -**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell -equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer. - -## Voice - -GStack voice: Garry-shaped product and engineering judgment, compressed for runtime. - -- Lead with the point. Say what it does, why it matters, and what changes for the builder. -- Be concrete. Name files, functions, line numbers, commands, outputs, evals, and real numbers. -- Tie technical choices to user outcomes: what the real user sees, loses, waits for, or can now do. -- Be direct about quality. Bugs matter. Edge cases matter. Fix the whole thing, not the demo path. -- Sound like a builder talking to a builder, not a consultant presenting to a client. -- Never corporate, academic, PR, or hype. Avoid filler, throat-clearing, generic optimism, and founder cosplay. -- No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted, furthermore, moreover, additionally, pivotal, landscape, tapestry, underscore, foster, showcase, intricate, vibrant, fundamental, significant. -- The user has context you do not: domain knowledge, timing, relationships, taste. Cross-model agreement is a recommendation, not a decision. The user decides. - -Good: "auth.ts:47 returns undefined when the session cookie expires. Users hit a white screen. Fix: add a null check and redirect to /login. Two lines." -Bad: "I've identified a potential issue in the authentication flow that may cause problems under certain conditions." +Voice, model-specific behavioral patch, Completion Status Protocol, and +Operational Self-Improvement rules shared by all gstack skills live in +`~/.claude/skills/gstack/docs/shared-conduct.md`. Read it now with the Read +tool unless it was already read earlier in this session, and apply it +throughout this skill. ## Context Recovery @@ -752,26 +726,6 @@ Before building anything unfamiliar, **search first.** See `~/.claude/skills/gst jq -n --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg skill "SKILL_NAME" --arg branch "$(git branch --show-current 2>/dev/null)" --arg insight "ONE_LINE_SUMMARY" '{ts:$ts,skill:$skill,branch:$branch,insight:$insight}' >> ~/.gstack/analytics/eureka.jsonl 2>/dev/null || true ``` -## Completion Status Protocol - -When completing a skill workflow, report status using one of: -- **DONE** — completed with evidence. -- **DONE_WITH_CONCERNS** — completed, but list concerns. -- **BLOCKED** — cannot proceed; state blocker and what was tried. -- **NEEDS_CONTEXT** — missing info; state exactly what is needed. - -Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: `STATUS`, `REASON`, `ATTEMPTED`, `RECOMMENDATION`. - -## Operational Self-Improvement - -Before completing, if you discovered a durable project quirk or command fix that would save 5+ minutes next time, log it: - -```bash -~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}' -``` - -Do not log obvious facts or one-time transient errors. - ## Telemetry (run last) After workflow completion, log telemetry. Use skill `name:` from frontmatter. OUTCOME is success/error/abort/unknown. @@ -1019,6 +973,7 @@ Follow its instructions from top to bottom, **skipping these sections** (already - Search Before Building - Contributor Mode - Completion Status Protocol +- Shared Conduct - Telemetry (run last) - Step 0: Detect platform and base branch - Review Readiness Dashboard diff --git a/plan-eng-review/SKILL.md b/plan-eng-review/SKILL.md index 5557a33fa0..8ce1f66ad8 100644 --- a/plan-eng-review/SKILL.md +++ b/plan-eng-review/SKILL.md @@ -586,39 +586,13 @@ At skill END before telemetry: ``` -## Model-Specific Behavioral Patch (claude) +## Shared Conduct -The following nudges are tuned for the claude model family. They are -**subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode -safety, and /ship review gates. If a nudge below conflicts with skill instructions, -the skill wins. Treat these as preferences, not rules. - -**Todo-list discipline.** When working through a multi-step plan, mark each task -complete individually as you finish it. Do not batch-complete at the end. If a task -turns out to be unnecessary, mark it skipped with a one-line reason. - -**Think before heavy actions.** For complex operations (refactors, migrations, -non-trivial new features), briefly state your approach before executing. This lets -the user course-correct cheaply instead of mid-flight. - -**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell -equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer. - -## Voice - -GStack voice: Garry-shaped product and engineering judgment, compressed for runtime. - -- Lead with the point. Say what it does, why it matters, and what changes for the builder. -- Be concrete. Name files, functions, line numbers, commands, outputs, evals, and real numbers. -- Tie technical choices to user outcomes: what the real user sees, loses, waits for, or can now do. -- Be direct about quality. Bugs matter. Edge cases matter. Fix the whole thing, not the demo path. -- Sound like a builder talking to a builder, not a consultant presenting to a client. -- Never corporate, academic, PR, or hype. Avoid filler, throat-clearing, generic optimism, and founder cosplay. -- No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted, furthermore, moreover, additionally, pivotal, landscape, tapestry, underscore, foster, showcase, intricate, vibrant, fundamental, significant. -- The user has context you do not: domain knowledge, timing, relationships, taste. Cross-model agreement is a recommendation, not a decision. The user decides. - -Good: "auth.ts:47 returns undefined when the session cookie expires. Users hit a white screen. Fix: add a null check and redirect to /login. Two lines." -Bad: "I've identified a potential issue in the authentication flow that may cause problems under certain conditions." +Voice, model-specific behavioral patch, Completion Status Protocol, and +Operational Self-Improvement rules shared by all gstack skills live in +`~/.claude/skills/gstack/docs/shared-conduct.md`. Read it now with the Read +tool unless it was already read earlier in this session, and apply it +throughout this skill. ## Context Recovery @@ -750,26 +724,6 @@ Before building anything unfamiliar, **search first.** See `~/.claude/skills/gst jq -n --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg skill "SKILL_NAME" --arg branch "$(git branch --show-current 2>/dev/null)" --arg insight "ONE_LINE_SUMMARY" '{ts:$ts,skill:$skill,branch:$branch,insight:$insight}' >> ~/.gstack/analytics/eureka.jsonl 2>/dev/null || true ``` -## Completion Status Protocol - -When completing a skill workflow, report status using one of: -- **DONE** — completed with evidence. -- **DONE_WITH_CONCERNS** — completed, but list concerns. -- **BLOCKED** — cannot proceed; state blocker and what was tried. -- **NEEDS_CONTEXT** — missing info; state exactly what is needed. - -Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: `STATUS`, `REASON`, `ATTEMPTED`, `RECOMMENDATION`. - -## Operational Self-Improvement - -Before completing, if you discovered a durable project quirk or command fix that would save 5+ minutes next time, log it: - -```bash -~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}' -``` - -Do not log obvious facts or one-time transient errors. - ## Telemetry (run last) After workflow completion, log telemetry. Use skill `name:` from frontmatter. OUTCOME is success/error/abort/unknown. @@ -954,6 +908,7 @@ Follow its instructions from top to bottom, **skipping these sections** (already - Search Before Building - Contributor Mode - Completion Status Protocol +- Shared Conduct - Telemetry (run last) - Step 0: Detect platform and base branch - Review Readiness Dashboard diff --git a/plan-tune/SKILL.md b/plan-tune/SKILL.md index f49b66fac3..335ef7ee97 100644 --- a/plan-tune/SKILL.md +++ b/plan-tune/SKILL.md @@ -591,39 +591,13 @@ At skill END before telemetry: ``` -## Model-Specific Behavioral Patch (claude) +## Shared Conduct -The following nudges are tuned for the claude model family. They are -**subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode -safety, and /ship review gates. If a nudge below conflicts with skill instructions, -the skill wins. Treat these as preferences, not rules. - -**Todo-list discipline.** When working through a multi-step plan, mark each task -complete individually as you finish it. Do not batch-complete at the end. If a task -turns out to be unnecessary, mark it skipped with a one-line reason. - -**Think before heavy actions.** For complex operations (refactors, migrations, -non-trivial new features), briefly state your approach before executing. This lets -the user course-correct cheaply instead of mid-flight. - -**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell -equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer. - -## Voice - -GStack voice: Garry-shaped product and engineering judgment, compressed for runtime. - -- Lead with the point. Say what it does, why it matters, and what changes for the builder. -- Be concrete. Name files, functions, line numbers, commands, outputs, evals, and real numbers. -- Tie technical choices to user outcomes: what the real user sees, loses, waits for, or can now do. -- Be direct about quality. Bugs matter. Edge cases matter. Fix the whole thing, not the demo path. -- Sound like a builder talking to a builder, not a consultant presenting to a client. -- Never corporate, academic, PR, or hype. Avoid filler, throat-clearing, generic optimism, and founder cosplay. -- No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted, furthermore, moreover, additionally, pivotal, landscape, tapestry, underscore, foster, showcase, intricate, vibrant, fundamental, significant. -- The user has context you do not: domain knowledge, timing, relationships, taste. Cross-model agreement is a recommendation, not a decision. The user decides. - -Good: "auth.ts:47 returns undefined when the session cookie expires. Users hit a white screen. Fix: add a null check and redirect to /login. Two lines." -Bad: "I've identified a potential issue in the authentication flow that may cause problems under certain conditions." +Voice, model-specific behavioral patch, Completion Status Protocol, and +Operational Self-Improvement rules shared by all gstack skills live in +`~/.claude/skills/gstack/docs/shared-conduct.md`. Read it now with the Read +tool unless it was already read earlier in this session, and apply it +throughout this skill. ## Context Recovery @@ -737,26 +711,6 @@ Write (only after confirmation for free-form): Exit code 2 = rejected as not user-originated; do not retry. On success: "Set `` → ``. Active immediately." -## Completion Status Protocol - -When completing a skill workflow, report status using one of: -- **DONE** — completed with evidence. -- **DONE_WITH_CONCERNS** — completed, but list concerns. -- **BLOCKED** — cannot proceed; state blocker and what was tried. -- **NEEDS_CONTEXT** — missing info; state exactly what is needed. - -Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: `STATUS`, `REASON`, `ATTEMPTED`, `RECOMMENDATION`. - -## Operational Self-Improvement - -Before completing, if you discovered a durable project quirk or command fix that would save 5+ minutes next time, log it: - -```bash -~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}' -``` - -Do not log obvious facts or one-time transient errors. - ## Telemetry (run last) After workflow completion, log telemetry. Use skill `name:` from frontmatter. OUTCOME is success/error/abort/unknown. diff --git a/qa-only/SKILL.md b/qa-only/SKILL.md index 801a935c06..2b0fbd974d 100644 --- a/qa-only/SKILL.md +++ b/qa-only/SKILL.md @@ -581,39 +581,13 @@ At skill END before telemetry: ``` -## Model-Specific Behavioral Patch (claude) +## Shared Conduct -The following nudges are tuned for the claude model family. They are -**subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode -safety, and /ship review gates. If a nudge below conflicts with skill instructions, -the skill wins. Treat these as preferences, not rules. - -**Todo-list discipline.** When working through a multi-step plan, mark each task -complete individually as you finish it. Do not batch-complete at the end. If a task -turns out to be unnecessary, mark it skipped with a one-line reason. - -**Think before heavy actions.** For complex operations (refactors, migrations, -non-trivial new features), briefly state your approach before executing. This lets -the user course-correct cheaply instead of mid-flight. - -**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell -equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer. - -## Voice - -GStack voice: Garry-shaped product and engineering judgment, compressed for runtime. - -- Lead with the point. Say what it does, why it matters, and what changes for the builder. -- Be concrete. Name files, functions, line numbers, commands, outputs, evals, and real numbers. -- Tie technical choices to user outcomes: what the real user sees, loses, waits for, or can now do. -- Be direct about quality. Bugs matter. Edge cases matter. Fix the whole thing, not the demo path. -- Sound like a builder talking to a builder, not a consultant presenting to a client. -- Never corporate, academic, PR, or hype. Avoid filler, throat-clearing, generic optimism, and founder cosplay. -- No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted, furthermore, moreover, additionally, pivotal, landscape, tapestry, underscore, foster, showcase, intricate, vibrant, fundamental, significant. -- The user has context you do not: domain knowledge, timing, relationships, taste. Cross-model agreement is a recommendation, not a decision. The user decides. - -Good: "auth.ts:47 returns undefined when the session cookie expires. Users hit a white screen. Fix: add a null check and redirect to /login. Two lines." -Bad: "I've identified a potential issue in the authentication flow that may cause problems under certain conditions." +Voice, model-specific behavioral patch, Completion Status Protocol, and +Operational Self-Improvement rules shared by all gstack skills live in +`~/.claude/skills/gstack/docs/shared-conduct.md`. Read it now with the Read +tool unless it was already read earlier in this session, and apply it +throughout this skill. ## Context Recovery @@ -745,26 +719,6 @@ Before building anything unfamiliar, **search first.** See `~/.claude/skills/gst jq -n --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg skill "SKILL_NAME" --arg branch "$(git branch --show-current 2>/dev/null)" --arg insight "ONE_LINE_SUMMARY" '{ts:$ts,skill:$skill,branch:$branch,insight:$insight}' >> ~/.gstack/analytics/eureka.jsonl 2>/dev/null || true ``` -## Completion Status Protocol - -When completing a skill workflow, report status using one of: -- **DONE** — completed with evidence. -- **DONE_WITH_CONCERNS** — completed, but list concerns. -- **BLOCKED** — cannot proceed; state blocker and what was tried. -- **NEEDS_CONTEXT** — missing info; state exactly what is needed. - -Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: `STATUS`, `REASON`, `ATTEMPTED`, `RECOMMENDATION`. - -## Operational Self-Improvement - -Before completing, if you discovered a durable project quirk or command fix that would save 5+ minutes next time, log it: - -```bash -~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}' -``` - -Do not log obvious facts or one-time transient errors. - ## Telemetry (run last) After workflow completion, log telemetry. Use skill `name:` from frontmatter. OUTCOME is success/error/abort/unknown. diff --git a/qa/SKILL.md b/qa/SKILL.md index c1ac10253f..7e8c595478 100644 --- a/qa/SKILL.md +++ b/qa/SKILL.md @@ -587,39 +587,13 @@ At skill END before telemetry: ``` -## Model-Specific Behavioral Patch (claude) +## Shared Conduct -The following nudges are tuned for the claude model family. They are -**subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode -safety, and /ship review gates. If a nudge below conflicts with skill instructions, -the skill wins. Treat these as preferences, not rules. - -**Todo-list discipline.** When working through a multi-step plan, mark each task -complete individually as you finish it. Do not batch-complete at the end. If a task -turns out to be unnecessary, mark it skipped with a one-line reason. - -**Think before heavy actions.** For complex operations (refactors, migrations, -non-trivial new features), briefly state your approach before executing. This lets -the user course-correct cheaply instead of mid-flight. - -**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell -equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer. - -## Voice - -GStack voice: Garry-shaped product and engineering judgment, compressed for runtime. - -- Lead with the point. Say what it does, why it matters, and what changes for the builder. -- Be concrete. Name files, functions, line numbers, commands, outputs, evals, and real numbers. -- Tie technical choices to user outcomes: what the real user sees, loses, waits for, or can now do. -- Be direct about quality. Bugs matter. Edge cases matter. Fix the whole thing, not the demo path. -- Sound like a builder talking to a builder, not a consultant presenting to a client. -- Never corporate, academic, PR, or hype. Avoid filler, throat-clearing, generic optimism, and founder cosplay. -- No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted, furthermore, moreover, additionally, pivotal, landscape, tapestry, underscore, foster, showcase, intricate, vibrant, fundamental, significant. -- The user has context you do not: domain knowledge, timing, relationships, taste. Cross-model agreement is a recommendation, not a decision. The user decides. - -Good: "auth.ts:47 returns undefined when the session cookie expires. Users hit a white screen. Fix: add a null check and redirect to /login. Two lines." -Bad: "I've identified a potential issue in the authentication flow that may cause problems under certain conditions." +Voice, model-specific behavioral patch, Completion Status Protocol, and +Operational Self-Improvement rules shared by all gstack skills live in +`~/.claude/skills/gstack/docs/shared-conduct.md`. Read it now with the Read +tool unless it was already read earlier in this session, and apply it +throughout this skill. ## Context Recovery @@ -751,26 +725,6 @@ Before building anything unfamiliar, **search first.** See `~/.claude/skills/gst jq -n --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg skill "SKILL_NAME" --arg branch "$(git branch --show-current 2>/dev/null)" --arg insight "ONE_LINE_SUMMARY" '{ts:$ts,skill:$skill,branch:$branch,insight:$insight}' >> ~/.gstack/analytics/eureka.jsonl 2>/dev/null || true ``` -## Completion Status Protocol - -When completing a skill workflow, report status using one of: -- **DONE** — completed with evidence. -- **DONE_WITH_CONCERNS** — completed, but list concerns. -- **BLOCKED** — cannot proceed; state blocker and what was tried. -- **NEEDS_CONTEXT** — missing info; state exactly what is needed. - -Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: `STATUS`, `REASON`, `ATTEMPTED`, `RECOMMENDATION`. - -## Operational Self-Improvement - -Before completing, if you discovered a durable project quirk or command fix that would save 5+ minutes next time, log it: - -```bash -~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}' -``` - -Do not log obvious facts or one-time transient errors. - ## Telemetry (run last) After workflow completion, log telemetry. Use skill `name:` from frontmatter. OUTCOME is success/error/abort/unknown. diff --git a/retro/SKILL.md b/retro/SKILL.md index 3fbc447261..7e71dd65b5 100644 --- a/retro/SKILL.md +++ b/retro/SKILL.md @@ -598,39 +598,13 @@ At skill END before telemetry: ``` -## Model-Specific Behavioral Patch (claude) +## Shared Conduct -The following nudges are tuned for the claude model family. They are -**subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode -safety, and /ship review gates. If a nudge below conflicts with skill instructions, -the skill wins. Treat these as preferences, not rules. - -**Todo-list discipline.** When working through a multi-step plan, mark each task -complete individually as you finish it. Do not batch-complete at the end. If a task -turns out to be unnecessary, mark it skipped with a one-line reason. - -**Think before heavy actions.** For complex operations (refactors, migrations, -non-trivial new features), briefly state your approach before executing. This lets -the user course-correct cheaply instead of mid-flight. - -**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell -equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer. - -## Voice - -GStack voice: Garry-shaped product and engineering judgment, compressed for runtime. - -- Lead with the point. Say what it does, why it matters, and what changes for the builder. -- Be concrete. Name files, functions, line numbers, commands, outputs, evals, and real numbers. -- Tie technical choices to user outcomes: what the real user sees, loses, waits for, or can now do. -- Be direct about quality. Bugs matter. Edge cases matter. Fix the whole thing, not the demo path. -- Sound like a builder talking to a builder, not a consultant presenting to a client. -- Never corporate, academic, PR, or hype. Avoid filler, throat-clearing, generic optimism, and founder cosplay. -- No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted, furthermore, moreover, additionally, pivotal, landscape, tapestry, underscore, foster, showcase, intricate, vibrant, fundamental, significant. -- The user has context you do not: domain knowledge, timing, relationships, taste. Cross-model agreement is a recommendation, not a decision. The user decides. - -Good: "auth.ts:47 returns undefined when the session cookie expires. Users hit a white screen. Fix: add a null check and redirect to /login. Two lines." -Bad: "I've identified a potential issue in the authentication flow that may cause problems under certain conditions." +Voice, model-specific behavioral patch, Completion Status Protocol, and +Operational Self-Improvement rules shared by all gstack skills live in +`~/.claude/skills/gstack/docs/shared-conduct.md`. Read it now with the Read +tool unless it was already read earlier in this session, and apply it +throughout this skill. ## Context Recovery @@ -744,26 +718,6 @@ Write (only after confirmation for free-form): Exit code 2 = rejected as not user-originated; do not retry. On success: "Set `` → ``. Active immediately." -## Completion Status Protocol - -When completing a skill workflow, report status using one of: -- **DONE** — completed with evidence. -- **DONE_WITH_CONCERNS** — completed, but list concerns. -- **BLOCKED** — cannot proceed; state blocker and what was tried. -- **NEEDS_CONTEXT** — missing info; state exactly what is needed. - -Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: `STATUS`, `REASON`, `ATTEMPTED`, `RECOMMENDATION`. - -## Operational Self-Improvement - -Before completing, if you discovered a durable project quirk or command fix that would save 5+ minutes next time, log it: - -```bash -~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}' -``` - -Do not log obvious facts or one-time transient errors. - ## Telemetry (run last) After workflow completion, log telemetry. Use skill `name:` from frontmatter. OUTCOME is success/error/abort/unknown. diff --git a/review/SKILL.md b/review/SKILL.md index 5f26e2e426..4d345d9144 100644 --- a/review/SKILL.md +++ b/review/SKILL.md @@ -583,39 +583,13 @@ At skill END before telemetry: ``` -## Model-Specific Behavioral Patch (claude) +## Shared Conduct -The following nudges are tuned for the claude model family. They are -**subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode -safety, and /ship review gates. If a nudge below conflicts with skill instructions, -the skill wins. Treat these as preferences, not rules. - -**Todo-list discipline.** When working through a multi-step plan, mark each task -complete individually as you finish it. Do not batch-complete at the end. If a task -turns out to be unnecessary, mark it skipped with a one-line reason. - -**Think before heavy actions.** For complex operations (refactors, migrations, -non-trivial new features), briefly state your approach before executing. This lets -the user course-correct cheaply instead of mid-flight. - -**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell -equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer. - -## Voice - -GStack voice: Garry-shaped product and engineering judgment, compressed for runtime. - -- Lead with the point. Say what it does, why it matters, and what changes for the builder. -- Be concrete. Name files, functions, line numbers, commands, outputs, evals, and real numbers. -- Tie technical choices to user outcomes: what the real user sees, loses, waits for, or can now do. -- Be direct about quality. Bugs matter. Edge cases matter. Fix the whole thing, not the demo path. -- Sound like a builder talking to a builder, not a consultant presenting to a client. -- Never corporate, academic, PR, or hype. Avoid filler, throat-clearing, generic optimism, and founder cosplay. -- No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted, furthermore, moreover, additionally, pivotal, landscape, tapestry, underscore, foster, showcase, intricate, vibrant, fundamental, significant. -- The user has context you do not: domain knowledge, timing, relationships, taste. Cross-model agreement is a recommendation, not a decision. The user decides. - -Good: "auth.ts:47 returns undefined when the session cookie expires. Users hit a white screen. Fix: add a null check and redirect to /login. Two lines." -Bad: "I've identified a potential issue in the authentication flow that may cause problems under certain conditions." +Voice, model-specific behavioral patch, Completion Status Protocol, and +Operational Self-Improvement rules shared by all gstack skills live in +`~/.claude/skills/gstack/docs/shared-conduct.md`. Read it now with the Read +tool unless it was already read earlier in this session, and apply it +throughout this skill. ## Context Recovery @@ -747,26 +721,6 @@ Before building anything unfamiliar, **search first.** See `~/.claude/skills/gst jq -n --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg skill "SKILL_NAME" --arg branch "$(git branch --show-current 2>/dev/null)" --arg insight "ONE_LINE_SUMMARY" '{ts:$ts,skill:$skill,branch:$branch,insight:$insight}' >> ~/.gstack/analytics/eureka.jsonl 2>/dev/null || true ``` -## Completion Status Protocol - -When completing a skill workflow, report status using one of: -- **DONE** — completed with evidence. -- **DONE_WITH_CONCERNS** — completed, but list concerns. -- **BLOCKED** — cannot proceed; state blocker and what was tried. -- **NEEDS_CONTEXT** — missing info; state exactly what is needed. - -Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: `STATUS`, `REASON`, `ATTEMPTED`, `RECOMMENDATION`. - -## Operational Self-Improvement - -Before completing, if you discovered a durable project quirk or command fix that would save 5+ minutes next time, log it: - -```bash -~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}' -``` - -Do not log obvious facts or one-time transient errors. - ## Telemetry (run last) After workflow completion, log telemetry. Use skill `name:` from frontmatter. OUTCOME is success/error/abort/unknown. diff --git a/scrape/SKILL.md b/scrape/SKILL.md index dc965ec5f7..709ebf4882 100644 --- a/scrape/SKILL.md +++ b/scrape/SKILL.md @@ -579,39 +579,13 @@ At skill END before telemetry: ``` -## Model-Specific Behavioral Patch (claude) +## Shared Conduct -The following nudges are tuned for the claude model family. They are -**subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode -safety, and /ship review gates. If a nudge below conflicts with skill instructions, -the skill wins. Treat these as preferences, not rules. - -**Todo-list discipline.** When working through a multi-step plan, mark each task -complete individually as you finish it. Do not batch-complete at the end. If a task -turns out to be unnecessary, mark it skipped with a one-line reason. - -**Think before heavy actions.** For complex operations (refactors, migrations, -non-trivial new features), briefly state your approach before executing. This lets -the user course-correct cheaply instead of mid-flight. - -**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell -equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer. - -## Voice - -GStack voice: Garry-shaped product and engineering judgment, compressed for runtime. - -- Lead with the point. Say what it does, why it matters, and what changes for the builder. -- Be concrete. Name files, functions, line numbers, commands, outputs, evals, and real numbers. -- Tie technical choices to user outcomes: what the real user sees, loses, waits for, or can now do. -- Be direct about quality. Bugs matter. Edge cases matter. Fix the whole thing, not the demo path. -- Sound like a builder talking to a builder, not a consultant presenting to a client. -- Never corporate, academic, PR, or hype. Avoid filler, throat-clearing, generic optimism, and founder cosplay. -- No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted, furthermore, moreover, additionally, pivotal, landscape, tapestry, underscore, foster, showcase, intricate, vibrant, fundamental, significant. -- The user has context you do not: domain knowledge, timing, relationships, taste. Cross-model agreement is a recommendation, not a decision. The user decides. - -Good: "auth.ts:47 returns undefined when the session cookie expires. Users hit a white screen. Fix: add a null check and redirect to /login. Two lines." -Bad: "I've identified a potential issue in the authentication flow that may cause problems under certain conditions." +Voice, model-specific behavioral patch, Completion Status Protocol, and +Operational Self-Improvement rules shared by all gstack skills live in +`~/.claude/skills/gstack/docs/shared-conduct.md`. Read it now with the Read +tool unless it was already read earlier in this session, and apply it +throughout this skill. ## Context Recovery @@ -743,26 +717,6 @@ Before building anything unfamiliar, **search first.** See `~/.claude/skills/gst jq -n --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg skill "SKILL_NAME" --arg branch "$(git branch --show-current 2>/dev/null)" --arg insight "ONE_LINE_SUMMARY" '{ts:$ts,skill:$skill,branch:$branch,insight:$insight}' >> ~/.gstack/analytics/eureka.jsonl 2>/dev/null || true ``` -## Completion Status Protocol - -When completing a skill workflow, report status using one of: -- **DONE** — completed with evidence. -- **DONE_WITH_CONCERNS** — completed, but list concerns. -- **BLOCKED** — cannot proceed; state blocker and what was tried. -- **NEEDS_CONTEXT** — missing info; state exactly what is needed. - -Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: `STATUS`, `REASON`, `ATTEMPTED`, `RECOMMENDATION`. - -## Operational Self-Improvement - -Before completing, if you discovered a durable project quirk or command fix that would save 5+ minutes next time, log it: - -```bash -~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}' -``` - -Do not log obvious facts or one-time transient errors. - ## Telemetry (run last) After workflow completion, log telemetry. Use skill `name:` from frontmatter. OUTCOME is success/error/abort/unknown. diff --git a/scripts/gen-skill-docs.ts b/scripts/gen-skill-docs.ts index 71aa1a34ca..fabdaee2d0 100644 --- a/scripts/gen-skill-docs.ts +++ b/scripts/gen-skill-docs.ts @@ -18,6 +18,7 @@ import * as path from 'path'; import type { Host, TemplateContext } from './resolvers/types'; import { HOST_PATHS, unwrapResolver } from './resolvers/types'; import { RESOLVERS } from './resolvers/index'; +import { generateSharedConductDoc } from './resolvers/preamble'; import { externalSkillName, extractHookSafetyProse as _extractHookSafetyProse, extractNameAndDescription as _extractNameAndDescription, condenseOpenAIShortDescription as _condenseOpenAIShortDescription, generateOpenAIYaml as _generateOpenAIYaml } from './resolvers/codex-helpers'; import { generatePlanCompletionAuditShip, generatePlanCompletionAuditReview, generatePlanVerificationExec } from './resolvers/review'; import { ALL_HOST_CONFIGS, ALL_HOST_NAMES, resolveHostArg, getHostConfig } from '../hosts/index'; @@ -673,6 +674,21 @@ function resolvePlaceholders( // effectiveSuppressedResolvers() honors --respect-detection: when gbrain is // detected locally, GBRAIN_* resolvers un-suppress. Shared by SKILL.md and // section generation so both paths get the same gbrain-aware behavior. + // Guard: {{PREAMBLE}} expands to the full multi-hundred-line preamble block. + // A second occurrence — e.g. the token used as an inline prose *reference* + // ("emitted by `{{PREAMBLE}}`'s bash") — pastes the entire block mid-sentence + // (the spec/SKILL.md duplication bug, 2026-07-25). Mention it in prose + // without braces instead. + for (const onceOnly of ['PREAMBLE']) { + const count = (tmplContent.match(new RegExp(`\\{\\{${onceOnly}(?::[^}]+)?\\}\\}`, 'g')) || []).length; + if (count > 1) { + throw new Error( + `{{${onceOnly}}} appears ${count} times in ${relTmplPath} — it must appear at most once per template. ` + + `To reference it in prose, write the name without braces.` + ); + } + } + const suppressed = effectiveSuppressedResolvers(hostConfig); const onePass = (input: string): string => input.replace(/\{\{(\w+(?::[^}]+)?)\}\}/g, (_match, fullKey) => { @@ -1055,6 +1071,35 @@ for (const currentHost of hostsToRun) { }); } + // ─── Shared conduct doc (Claude host only) ─── + // The factored-out behavioral block (Voice, model overlay, Completion + // Status Protocol, Operational Self-Improvement) is written ONCE here; + // every Claude skill's preamble points at it instead of inlining it. + if (currentHost === 'claude') { + const conductCtx: TemplateContext = { + skillName: 'gstack', tmplPath: path.join(ROOT, 'SKILL.md.tmpl'), + host: 'claude', paths: HOST_PATHS['claude'], + model: MODEL_ARG_VAL, explainLevel: EXPLAIN_LEVEL, + }; + const conductContent = GENERATED_HEADER.replace('{{SOURCE}}', 'scripts/resolvers/preamble.ts (generateSharedConductDoc)') + + generateSharedConductDoc(conductCtx); + const conductPath = path.join(OUT_DIR || ROOT, 'docs', 'shared-conduct.md'); + const relConduct = path.relative(OUT_DIR || ROOT, conductPath); + if (DRY_RUN) { + const existing = fs.existsSync(conductPath) ? fs.readFileSync(conductPath, 'utf-8') : ''; + if (existing !== conductContent) { + console.log(`STALE: ${relConduct}`); + hasChanges = true; + } else { + console.log(`FRESH: ${relConduct}`); + } + } else { + fs.mkdirSync(path.dirname(conductPath), { recursive: true }); + fs.writeFileSync(conductPath, conductContent); + console.log(`GENERATED: ${relConduct}`); + } + } + // Generate gstack-lite and gstack-full for OpenClaw host if (currentHost === 'openclaw' && !DRY_RUN) { const openclawDir = path.join(ROOT, 'openclaw'); diff --git a/scripts/resolvers/composition.ts b/scripts/resolvers/composition.ts index b8d3483d9b..23dff2a822 100644 --- a/scripts/resolvers/composition.ts +++ b/scripts/resolvers/composition.ts @@ -27,6 +27,7 @@ export function generateInvokeSkill(ctx: TemplateContext, args?: string[]): stri 'Search Before Building', 'Contributor Mode', 'Completion Status Protocol', + 'Shared Conduct', 'Telemetry (run last)', 'Step 0: Detect platform and base branch', 'Review Readiness Dashboard', diff --git a/scripts/resolvers/preamble.ts b/scripts/resolvers/preamble.ts index 1cdfc2e6d0..5addd21ab0 100644 --- a/scripts/resolvers/preamble.ts +++ b/scripts/resolvers/preamble.ts @@ -25,6 +25,8 @@ import { generatePreambleBash } from './preamble/generate-preamble-bash'; import { generateUpgradeCheck } from './preamble/generate-upgrade-check'; import { generateCompletionStatus, + generateCompletionStatusBehavioral, + generateCompletionStatusOperational, generatePlanModeInfo, } from './preamble/generate-completion-status'; @@ -106,8 +108,16 @@ export function generatePreamble(ctx: TemplateContext): string { // it hits; reversing this order regresses plan-review cadence (v1.6.4.0 bug). ...(tier >= 2 ? [generateAskUserFormat(ctx)] : []), generateBrainSyncBlock(ctx), - generateModelOverlay(ctx), - generateVoiceDirective(tier), + // Shared-conduct factoring (Claude host only): the Voice, model overlay, + // Completion Status Protocol, and Operational Self-Improvement blocks are + // identical across every skill for a given build, so instead of stamping + // ~150-190 lines into all ~49 SKILL.md files, Claude gets a short pointer + // to docs/shared-conduct.md (written once per gen-skill-docs run). + // External hosts keep the full inline block — their install layouts don't + // ship the shared doc. + ...(ctx.host === 'claude' + ? [generateSharedConductPointer(ctx)] + : [generateModelOverlay(ctx), generateVoiceDirective(tier)]), ...(tier >= 2 ? [ generateContextRecovery(ctx), generateWritingStyle(ctx), @@ -118,7 +128,50 @@ export function generatePreamble(ctx: TemplateContext): string { generateQuestionTuning(ctx), ] : []), ...(tier >= 3 ? [generateRepoModeSection(), generateSearchBeforeBuildingSection(ctx)] : []), - generateCompletionStatus(ctx), + // Claude host: the behavioral half (Completion Status Protocol + + // Operational Self-Improvement) lives in docs/shared-conduct.md; only the + // operational telemetry/footer block stays inline. External hosts inline both. + ...(ctx.host === 'claude' + ? [generateCompletionStatusOperational(ctx)] + : [generateCompletionStatus(ctx)]), ]; return sections.filter(s => s && s.trim().length > 0).join('\n\n'); } + +/** + * One-paragraph pointer that replaces the per-skill copies of the shared + * behavioral block on the Claude host. Kept deliberately terse per the + * Claude-5 context-engineering guidance: state once, point elsewhere. + */ +export function generateSharedConductPointer(ctx: TemplateContext): string { + return `## Shared Conduct + +Voice, model-specific behavioral patch, Completion Status Protocol, and +Operational Self-Improvement rules shared by all gstack skills live in +\`${ctx.paths.skillRoot}/docs/shared-conduct.md\`. Read it now with the Read +tool unless it was already read earlier in this session, and apply it +throughout this skill.`; +} + +/** + * Content of docs/shared-conduct.md — the factored-out behavioral block, + * written ONCE per gen-skill-docs run (Claude host) instead of into every + * skill. Voice ships at full (tier-2+) strength; tier-1 skills previously got + * a trimmed variant, but a single shared copy makes the full version free. + */ +export function generateSharedConductDoc(ctx: TemplateContext): string { + const sections = [ + '# gstack Shared Conduct', + '', + 'Shared behavioral rules for every gstack skill. Skills point here from their', + '"## Shared Conduct" preamble section. Read once per session.', + '', + [ + generateModelOverlay(ctx), + generateVoiceDirective(4), + generateCompletionStatusBehavioral(ctx), + ].filter(s => s && s.trim().length > 0).join('\n\n'), + '', + ]; + return sections.join('\n'); +} diff --git a/scripts/resolvers/preamble/generate-completion-status.ts b/scripts/resolvers/preamble/generate-completion-status.ts index dc72a42ecd..4d8696a922 100644 --- a/scripts/resolvers/preamble/generate-completion-status.ts +++ b/scripts/resolvers/preamble/generate-completion-status.ts @@ -29,7 +29,15 @@ In plan mode, allowed because they inform the plan: \`$B\`, \`$D\`, \`codex exec If the user invokes a skill in plan mode, the skill takes precedence over generic plan mode behavior. **Treat the skill file as executable instructions, not reference.** Follow it step by step starting from Step 0; the first AskUserQuestion is the workflow entering plan mode, not a violation of it. AskUserQuestion (any variant — \`mcp__*__AskUserQuestion\` or native; see "AskUserQuestion Format → Tool resolution") satisfies plan mode's end-of-turn requirement. If AskUserQuestion is unavailable or a call fails, follow the AskUserQuestion Format failure fallback: \`headless\` → BLOCKED; \`interactive\` → the prose fallback (also satisfies end-of-turn). At a STOP point, stop immediately. Do not continue the workflow or call ExitPlanMode there. Commands marked "PLAN MODE EXCEPTION — ALWAYS RUN" execute. Call ExitPlanMode only after the skill workflow completes, or if the user tells you to cancel the skill or leave plan mode.`; } -export function generateCompletionStatus(ctx: TemplateContext): string { +/** + * Behavioral half of the completion block (Completion Status Protocol + + * Operational Self-Improvement). Identical across skills for a given host, + * so the Claude host factors it into docs/shared-conduct.md (one copy, + * pointed to from every preamble) instead of stamping it into all ~49 + * SKILL.md files. External hosts still inline it via + * generateCompletionStatus(). + */ +export function generateCompletionStatusBehavioral(ctx: TemplateContext): string { return `## Completion Status Protocol When completing a skill workflow, report status using one of: @@ -48,9 +56,15 @@ Before completing, if you discovered a durable project quirk or command fix that ${ctx.paths.binDir}/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}' \`\`\` -Do not log obvious facts or one-time transient errors. +Do not log obvious facts or one-time transient errors.`; +} -## Telemetry (run last) +/** + * Operational half: telemetry bash + plan status footer. Always inline in + * every skill (it must run even if the model never reads the shared doc). + */ +export function generateCompletionStatusOperational(_ctx: TemplateContext): string { + return `## Telemetry (run last) After workflow completion, log telemetry. Use skill \`name:\` from frontmatter. OUTCOME is success/error/abort/unknown. @@ -83,3 +97,8 @@ Replace \`SKILL_NAME\`, \`OUTCOME\`, and \`USED_BROWSE\` before running. Skills that run plan reviews (\`/plan-*-review\`, \`/codex review\`) include the EXIT PLAN MODE GATE blocking checklist at the end of the skill, which verifies the plan file ends with \`## GSTACK REVIEW REPORT\` before ExitPlanMode is called. Skills that don't run plan reviews (operational skills like \`/ship\`, \`/qa\`, \`/review\`) typically don't operate in plan mode and have no review report to verify; this footer is a no-op for them. Writing the plan file is the one edit allowed in plan mode.`; } + +/** Full inline block — used by external hosts (no shared-doc factoring). */ +export function generateCompletionStatus(ctx: TemplateContext): string { + return `${generateCompletionStatusBehavioral(ctx)}\n\n${generateCompletionStatusOperational(ctx)}`; +} diff --git a/setup-browser-cookies/SKILL.md b/setup-browser-cookies/SKILL.md index 77df27da2c..520fee4475 100644 --- a/setup-browser-cookies/SKILL.md +++ b/setup-browser-cookies/SKILL.md @@ -450,51 +450,13 @@ At skill END before telemetry: ``` -## Model-Specific Behavioral Patch (claude) +## Shared Conduct -The following nudges are tuned for the claude model family. They are -**subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode -safety, and /ship review gates. If a nudge below conflicts with skill instructions, -the skill wins. Treat these as preferences, not rules. - -**Todo-list discipline.** When working through a multi-step plan, mark each task -complete individually as you finish it. Do not batch-complete at the end. If a task -turns out to be unnecessary, mark it skipped with a one-line reason. - -**Think before heavy actions.** For complex operations (refactors, migrations, -non-trivial new features), briefly state your approach before executing. This lets -the user course-correct cheaply instead of mid-flight. - -**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell -equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer. - -## Voice - -Direct, concrete, builder-to-builder. Name the file, function, command, and user-visible impact. No filler. - -No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted. Never corporate or academic. Short paragraphs. End with what to do. - -The user has context you do not. Cross-model agreement is a recommendation, not a decision. The user decides. - -## Completion Status Protocol - -When completing a skill workflow, report status using one of: -- **DONE** — completed with evidence. -- **DONE_WITH_CONCERNS** — completed, but list concerns. -- **BLOCKED** — cannot proceed; state blocker and what was tried. -- **NEEDS_CONTEXT** — missing info; state exactly what is needed. - -Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: `STATUS`, `REASON`, `ATTEMPTED`, `RECOMMENDATION`. - -## Operational Self-Improvement - -Before completing, if you discovered a durable project quirk or command fix that would save 5+ minutes next time, log it: - -```bash -~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}' -``` - -Do not log obvious facts or one-time transient errors. +Voice, model-specific behavioral patch, Completion Status Protocol, and +Operational Self-Improvement rules shared by all gstack skills live in +`~/.claude/skills/gstack/docs/shared-conduct.md`. Read it now with the Read +tool unless it was already read earlier in this session, and apply it +throughout this skill. ## Telemetry (run last) diff --git a/setup-deploy/SKILL.md b/setup-deploy/SKILL.md index 3465dc564b..04bae7f120 100644 --- a/setup-deploy/SKILL.md +++ b/setup-deploy/SKILL.md @@ -582,39 +582,13 @@ At skill END before telemetry: ``` -## Model-Specific Behavioral Patch (claude) +## Shared Conduct -The following nudges are tuned for the claude model family. They are -**subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode -safety, and /ship review gates. If a nudge below conflicts with skill instructions, -the skill wins. Treat these as preferences, not rules. - -**Todo-list discipline.** When working through a multi-step plan, mark each task -complete individually as you finish it. Do not batch-complete at the end. If a task -turns out to be unnecessary, mark it skipped with a one-line reason. - -**Think before heavy actions.** For complex operations (refactors, migrations, -non-trivial new features), briefly state your approach before executing. This lets -the user course-correct cheaply instead of mid-flight. - -**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell -equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer. - -## Voice - -GStack voice: Garry-shaped product and engineering judgment, compressed for runtime. - -- Lead with the point. Say what it does, why it matters, and what changes for the builder. -- Be concrete. Name files, functions, line numbers, commands, outputs, evals, and real numbers. -- Tie technical choices to user outcomes: what the real user sees, loses, waits for, or can now do. -- Be direct about quality. Bugs matter. Edge cases matter. Fix the whole thing, not the demo path. -- Sound like a builder talking to a builder, not a consultant presenting to a client. -- Never corporate, academic, PR, or hype. Avoid filler, throat-clearing, generic optimism, and founder cosplay. -- No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted, furthermore, moreover, additionally, pivotal, landscape, tapestry, underscore, foster, showcase, intricate, vibrant, fundamental, significant. -- The user has context you do not: domain knowledge, timing, relationships, taste. Cross-model agreement is a recommendation, not a decision. The user decides. - -Good: "auth.ts:47 returns undefined when the session cookie expires. Users hit a white screen. Fix: add a null check and redirect to /login. Two lines." -Bad: "I've identified a potential issue in the authentication flow that may cause problems under certain conditions." +Voice, model-specific behavioral patch, Completion Status Protocol, and +Operational Self-Improvement rules shared by all gstack skills live in +`~/.claude/skills/gstack/docs/shared-conduct.md`. Read it now with the Read +tool unless it was already read earlier in this session, and apply it +throughout this skill. ## Context Recovery @@ -728,26 +702,6 @@ Write (only after confirmation for free-form): Exit code 2 = rejected as not user-originated; do not retry. On success: "Set `` → ``. Active immediately." -## Completion Status Protocol - -When completing a skill workflow, report status using one of: -- **DONE** — completed with evidence. -- **DONE_WITH_CONCERNS** — completed, but list concerns. -- **BLOCKED** — cannot proceed; state blocker and what was tried. -- **NEEDS_CONTEXT** — missing info; state exactly what is needed. - -Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: `STATUS`, `REASON`, `ATTEMPTED`, `RECOMMENDATION`. - -## Operational Self-Improvement - -Before completing, if you discovered a durable project quirk or command fix that would save 5+ minutes next time, log it: - -```bash -~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}' -``` - -Do not log obvious facts or one-time transient errors. - ## Telemetry (run last) After workflow completion, log telemetry. Use skill `name:` from frontmatter. OUTCOME is success/error/abort/unknown. diff --git a/setup-gbrain/SKILL.md b/setup-gbrain/SKILL.md index a3892f1c90..49dd9eafcd 100644 --- a/setup-gbrain/SKILL.md +++ b/setup-gbrain/SKILL.md @@ -581,39 +581,13 @@ At skill END before telemetry: ``` -## Model-Specific Behavioral Patch (claude) +## Shared Conduct -The following nudges are tuned for the claude model family. They are -**subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode -safety, and /ship review gates. If a nudge below conflicts with skill instructions, -the skill wins. Treat these as preferences, not rules. - -**Todo-list discipline.** When working through a multi-step plan, mark each task -complete individually as you finish it. Do not batch-complete at the end. If a task -turns out to be unnecessary, mark it skipped with a one-line reason. - -**Think before heavy actions.** For complex operations (refactors, migrations, -non-trivial new features), briefly state your approach before executing. This lets -the user course-correct cheaply instead of mid-flight. - -**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell -equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer. - -## Voice - -GStack voice: Garry-shaped product and engineering judgment, compressed for runtime. - -- Lead with the point. Say what it does, why it matters, and what changes for the builder. -- Be concrete. Name files, functions, line numbers, commands, outputs, evals, and real numbers. -- Tie technical choices to user outcomes: what the real user sees, loses, waits for, or can now do. -- Be direct about quality. Bugs matter. Edge cases matter. Fix the whole thing, not the demo path. -- Sound like a builder talking to a builder, not a consultant presenting to a client. -- Never corporate, academic, PR, or hype. Avoid filler, throat-clearing, generic optimism, and founder cosplay. -- No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted, furthermore, moreover, additionally, pivotal, landscape, tapestry, underscore, foster, showcase, intricate, vibrant, fundamental, significant. -- The user has context you do not: domain knowledge, timing, relationships, taste. Cross-model agreement is a recommendation, not a decision. The user decides. - -Good: "auth.ts:47 returns undefined when the session cookie expires. Users hit a white screen. Fix: add a null check and redirect to /login. Two lines." -Bad: "I've identified a potential issue in the authentication flow that may cause problems under certain conditions." +Voice, model-specific behavioral patch, Completion Status Protocol, and +Operational Self-Improvement rules shared by all gstack skills live in +`~/.claude/skills/gstack/docs/shared-conduct.md`. Read it now with the Read +tool unless it was already read earlier in this session, and apply it +throughout this skill. ## Context Recovery @@ -727,26 +701,6 @@ Write (only after confirmation for free-form): Exit code 2 = rejected as not user-originated; do not retry. On success: "Set `` → ``. Active immediately." -## Completion Status Protocol - -When completing a skill workflow, report status using one of: -- **DONE** — completed with evidence. -- **DONE_WITH_CONCERNS** — completed, but list concerns. -- **BLOCKED** — cannot proceed; state blocker and what was tried. -- **NEEDS_CONTEXT** — missing info; state exactly what is needed. - -Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: `STATUS`, `REASON`, `ATTEMPTED`, `RECOMMENDATION`. - -## Operational Self-Improvement - -Before completing, if you discovered a durable project quirk or command fix that would save 5+ minutes next time, log it: - -```bash -~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}' -``` - -Do not log obvious facts or one-time transient errors. - ## Telemetry (run last) After workflow completion, log telemetry. Use skill `name:` from frontmatter. OUTCOME is success/error/abort/unknown. diff --git a/ship/SKILL.md b/ship/SKILL.md index eadffaa8f6..9e35031370 100644 --- a/ship/SKILL.md +++ b/ship/SKILL.md @@ -583,39 +583,13 @@ At skill END before telemetry: ``` -## Model-Specific Behavioral Patch (claude) +## Shared Conduct -The following nudges are tuned for the claude model family. They are -**subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode -safety, and /ship review gates. If a nudge below conflicts with skill instructions, -the skill wins. Treat these as preferences, not rules. - -**Todo-list discipline.** When working through a multi-step plan, mark each task -complete individually as you finish it. Do not batch-complete at the end. If a task -turns out to be unnecessary, mark it skipped with a one-line reason. - -**Think before heavy actions.** For complex operations (refactors, migrations, -non-trivial new features), briefly state your approach before executing. This lets -the user course-correct cheaply instead of mid-flight. - -**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell -equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer. - -## Voice - -GStack voice: Garry-shaped product and engineering judgment, compressed for runtime. - -- Lead with the point. Say what it does, why it matters, and what changes for the builder. -- Be concrete. Name files, functions, line numbers, commands, outputs, evals, and real numbers. -- Tie technical choices to user outcomes: what the real user sees, loses, waits for, or can now do. -- Be direct about quality. Bugs matter. Edge cases matter. Fix the whole thing, not the demo path. -- Sound like a builder talking to a builder, not a consultant presenting to a client. -- Never corporate, academic, PR, or hype. Avoid filler, throat-clearing, generic optimism, and founder cosplay. -- No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted, furthermore, moreover, additionally, pivotal, landscape, tapestry, underscore, foster, showcase, intricate, vibrant, fundamental, significant. -- The user has context you do not: domain knowledge, timing, relationships, taste. Cross-model agreement is a recommendation, not a decision. The user decides. - -Good: "auth.ts:47 returns undefined when the session cookie expires. Users hit a white screen. Fix: add a null check and redirect to /login. Two lines." -Bad: "I've identified a potential issue in the authentication flow that may cause problems under certain conditions." +Voice, model-specific behavioral patch, Completion Status Protocol, and +Operational Self-Improvement rules shared by all gstack skills live in +`~/.claude/skills/gstack/docs/shared-conduct.md`. Read it now with the Read +tool unless it was already read earlier in this session, and apply it +throughout this skill. ## Context Recovery @@ -747,26 +721,6 @@ Before building anything unfamiliar, **search first.** See `~/.claude/skills/gst jq -n --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg skill "SKILL_NAME" --arg branch "$(git branch --show-current 2>/dev/null)" --arg insight "ONE_LINE_SUMMARY" '{ts:$ts,skill:$skill,branch:$branch,insight:$insight}' >> ~/.gstack/analytics/eureka.jsonl 2>/dev/null || true ``` -## Completion Status Protocol - -When completing a skill workflow, report status using one of: -- **DONE** — completed with evidence. -- **DONE_WITH_CONCERNS** — completed, but list concerns. -- **BLOCKED** — cannot proceed; state blocker and what was tried. -- **NEEDS_CONTEXT** — missing info; state exactly what is needed. - -Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: `STATUS`, `REASON`, `ATTEMPTED`, `RECOMMENDATION`. - -## Operational Self-Improvement - -Before completing, if you discovered a durable project quirk or command fix that would save 5+ minutes next time, log it: - -```bash -~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}' -``` - -Do not log obvious facts or one-time transient errors. - ## Telemetry (run last) After workflow completion, log telemetry. Use skill `name:` from frontmatter. OUTCOME is success/error/abort/unknown. diff --git a/skillify/SKILL.md b/skillify/SKILL.md index 7cb434d0ca..cccefe5c21 100644 --- a/skillify/SKILL.md +++ b/skillify/SKILL.md @@ -579,39 +579,13 @@ At skill END before telemetry: ``` -## Model-Specific Behavioral Patch (claude) +## Shared Conduct -The following nudges are tuned for the claude model family. They are -**subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode -safety, and /ship review gates. If a nudge below conflicts with skill instructions, -the skill wins. Treat these as preferences, not rules. - -**Todo-list discipline.** When working through a multi-step plan, mark each task -complete individually as you finish it. Do not batch-complete at the end. If a task -turns out to be unnecessary, mark it skipped with a one-line reason. - -**Think before heavy actions.** For complex operations (refactors, migrations, -non-trivial new features), briefly state your approach before executing. This lets -the user course-correct cheaply instead of mid-flight. - -**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell -equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer. - -## Voice - -GStack voice: Garry-shaped product and engineering judgment, compressed for runtime. - -- Lead with the point. Say what it does, why it matters, and what changes for the builder. -- Be concrete. Name files, functions, line numbers, commands, outputs, evals, and real numbers. -- Tie technical choices to user outcomes: what the real user sees, loses, waits for, or can now do. -- Be direct about quality. Bugs matter. Edge cases matter. Fix the whole thing, not the demo path. -- Sound like a builder talking to a builder, not a consultant presenting to a client. -- Never corporate, academic, PR, or hype. Avoid filler, throat-clearing, generic optimism, and founder cosplay. -- No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted, furthermore, moreover, additionally, pivotal, landscape, tapestry, underscore, foster, showcase, intricate, vibrant, fundamental, significant. -- The user has context you do not: domain knowledge, timing, relationships, taste. Cross-model agreement is a recommendation, not a decision. The user decides. - -Good: "auth.ts:47 returns undefined when the session cookie expires. Users hit a white screen. Fix: add a null check and redirect to /login. Two lines." -Bad: "I've identified a potential issue in the authentication flow that may cause problems under certain conditions." +Voice, model-specific behavioral patch, Completion Status Protocol, and +Operational Self-Improvement rules shared by all gstack skills live in +`~/.claude/skills/gstack/docs/shared-conduct.md`. Read it now with the Read +tool unless it was already read earlier in this session, and apply it +throughout this skill. ## Context Recovery @@ -743,26 +717,6 @@ Before building anything unfamiliar, **search first.** See `~/.claude/skills/gst jq -n --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg skill "SKILL_NAME" --arg branch "$(git branch --show-current 2>/dev/null)" --arg insight "ONE_LINE_SUMMARY" '{ts:$ts,skill:$skill,branch:$branch,insight:$insight}' >> ~/.gstack/analytics/eureka.jsonl 2>/dev/null || true ``` -## Completion Status Protocol - -When completing a skill workflow, report status using one of: -- **DONE** — completed with evidence. -- **DONE_WITH_CONCERNS** — completed, but list concerns. -- **BLOCKED** — cannot proceed; state blocker and what was tried. -- **NEEDS_CONTEXT** — missing info; state exactly what is needed. - -Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: `STATUS`, `REASON`, `ATTEMPTED`, `RECOMMENDATION`. - -## Operational Self-Improvement - -Before completing, if you discovered a durable project quirk or command fix that would save 5+ minutes next time, log it: - -```bash -~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}' -``` - -Do not log obvious facts or one-time transient errors. - ## Telemetry (run last) After workflow completion, log telemetry. Use skill `name:` from frontmatter. OUTCOME is success/error/abort/unknown. diff --git a/spec/SKILL.md b/spec/SKILL.md index 0894e98d18..e63a79106f 100644 --- a/spec/SKILL.md +++ b/spec/SKILL.md @@ -580,39 +580,13 @@ At skill END before telemetry: ``` -## Model-Specific Behavioral Patch (claude) +## Shared Conduct -The following nudges are tuned for the claude model family. They are -**subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode -safety, and /ship review gates. If a nudge below conflicts with skill instructions, -the skill wins. Treat these as preferences, not rules. - -**Todo-list discipline.** When working through a multi-step plan, mark each task -complete individually as you finish it. Do not batch-complete at the end. If a task -turns out to be unnecessary, mark it skipped with a one-line reason. - -**Think before heavy actions.** For complex operations (refactors, migrations, -non-trivial new features), briefly state your approach before executing. This lets -the user course-correct cheaply instead of mid-flight. - -**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell -equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer. - -## Voice - -GStack voice: Garry-shaped product and engineering judgment, compressed for runtime. - -- Lead with the point. Say what it does, why it matters, and what changes for the builder. -- Be concrete. Name files, functions, line numbers, commands, outputs, evals, and real numbers. -- Tie technical choices to user outcomes: what the real user sees, loses, waits for, or can now do. -- Be direct about quality. Bugs matter. Edge cases matter. Fix the whole thing, not the demo path. -- Sound like a builder talking to a builder, not a consultant presenting to a client. -- Never corporate, academic, PR, or hype. Avoid filler, throat-clearing, generic optimism, and founder cosplay. -- No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted, furthermore, moreover, additionally, pivotal, landscape, tapestry, underscore, foster, showcase, intricate, vibrant, fundamental, significant. -- The user has context you do not: domain knowledge, timing, relationships, taste. Cross-model agreement is a recommendation, not a decision. The user decides. - -Good: "auth.ts:47 returns undefined when the session cookie expires. Users hit a white screen. Fix: add a null check and redirect to /login. Two lines." -Bad: "I've identified a potential issue in the authentication flow that may cause problems under certain conditions." +Voice, model-specific behavioral patch, Completion Status Protocol, and +Operational Self-Improvement rules shared by all gstack skills live in +`~/.claude/skills/gstack/docs/shared-conduct.md`. Read it now with the Read +tool unless it was already read earlier in this session, and apply it +throughout this skill. ## Context Recovery @@ -744,26 +718,6 @@ Before building anything unfamiliar, **search first.** See `~/.claude/skills/gst jq -n --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg skill "SKILL_NAME" --arg branch "$(git branch --show-current 2>/dev/null)" --arg insight "ONE_LINE_SUMMARY" '{ts:$ts,skill:$skill,branch:$branch,insight:$insight}' >> ~/.gstack/analytics/eureka.jsonl 2>/dev/null || true ``` -## Completion Status Protocol - -When completing a skill workflow, report status using one of: -- **DONE** — completed with evidence. -- **DONE_WITH_CONCERNS** — completed, but list concerns. -- **BLOCKED** — cannot proceed; state blocker and what was tried. -- **NEEDS_CONTEXT** — missing info; state exactly what is needed. - -Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: `STATUS`, `REASON`, `ATTEMPTED`, `RECOMMENDATION`. - -## Operational Self-Improvement - -Before completing, if you discovered a durable project quirk or command fix that would save 5+ minutes next time, log it: - -```bash -~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}' -``` - -Do not log obvious facts or one-time transient errors. - ## Telemetry (run last) After workflow completion, log telemetry. Use skill `name:` from frontmatter. OUTCOME is success/error/abort/unknown. @@ -1097,776 +1051,8 @@ contributor's "match template to content" rules. #### Phase 5 dispatch logic (plan-mode-aware default) -Read `GSTACK_PLAN_MODE` from the environment (emitted by `## Preamble (run first) - -```bash -_UPD=$(~/.claude/skills/gstack/bin/gstack-update-check 2>/dev/null || .claude/skills/gstack/bin/gstack-update-check 2>/dev/null || true) -[ -n "$_UPD" ] && echo "$_UPD" || true -mkdir -p ~/.gstack/sessions -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 -exec rm {} + 2>/dev/null || true -_PROACTIVE=$(~/.claude/skills/gstack/bin/gstack-config get proactive 2>/dev/null || echo "true") -_PROACTIVE_PROMPTED=$([ -f ~/.gstack/.proactive-prompted ] && echo "yes" || echo "no") -_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown") -echo "BRANCH: $_BRANCH" -_SKILL_PREFIX=$(~/.claude/skills/gstack/bin/gstack-config get skill_prefix 2>/dev/null || echo "false") -echo "PROACTIVE: $_PROACTIVE" -echo "PROACTIVE_PROMPTED: $_PROACTIVE_PROMPTED" -echo "SKILL_PREFIX: $_SKILL_PREFIX" -source <(~/.claude/skills/gstack/bin/gstack-repo-mode 2>/dev/null) || true -REPO_MODE=${REPO_MODE:-unknown} -echo "REPO_MODE: $REPO_MODE" -_SESSION_KIND=$(~/.claude/skills/gstack/bin/gstack-session-kind 2>/dev/null || echo "interactive") -case "$_SESSION_KIND" in spawned|headless|interactive) ;; *) _SESSION_KIND="interactive" ;; esac -echo "SESSION_KIND: $_SESSION_KIND" -# Conductor host: AskUserQuestion is unreliable here (native disabled, MCP -# variant flaky), so skills render decisions as prose instead of calling the -# tool. Gated on !headless so an eval/CI run INSIDE Conductor (GSTACK_HEADLESS) -# still BLOCKs rather than rendering prose to nobody. -if [ "$_SESSION_KIND" != "headless" ] && { [ -n "${CONDUCTOR_WORKSPACE_PATH:-}" ] || [ -n "${CONDUCTOR_PORT:-}" ]; }; then - echo "CONDUCTOR_SESSION: true" -fi -_ACTIVATED=$([ -f ~/.gstack/.activated ] && echo "yes" || echo "no") -_FIRST_LOOP_SHOWN=$([ -f ~/.gstack/.first-loop-tip-shown ] && echo "yes" || echo "no") -echo "ACTIVATED: $_ACTIVATED" -echo "FIRST_LOOP_SHOWN: $_FIRST_LOOP_SHOWN" -# First-run project detection: run the detector ONLY on the first-ever skill run -# (ACTIVATED=no, interactive) so it stays off the hot path for every run after. -_FIRST_TASK="" -if [ "$_ACTIVATED" = "no" ] && [ "$_SESSION_KIND" != "headless" ]; then - _FIRST_TASK=$(~/.claude/skills/gstack/bin/gstack-first-task-detect 2>/dev/null || true) -fi -echo "FIRST_TASK: $_FIRST_TASK" -_LAKE_SEEN=$([ -f ~/.gstack/.completeness-intro-seen ] && echo "yes" || echo "no") -echo "LAKE_INTRO: $_LAKE_SEEN" -_TEL=$(~/.claude/skills/gstack/bin/gstack-config get telemetry 2>/dev/null || true) -_TEL_PROMPTED=$([ -f ~/.gstack/.telemetry-prompted ] && echo "yes" || echo "no") -_TEL_START=$(date +%s) -_SESSION_ID="$$-$(date +%s)" -echo "TELEMETRY: ${_TEL:-off}" -echo "TEL_PROMPTED: $_TEL_PROMPTED" -_EXPLAIN_LEVEL=$(~/.claude/skills/gstack/bin/gstack-config get explain_level 2>/dev/null || echo "default") -if [ "$_EXPLAIN_LEVEL" != "default" ] && [ "$_EXPLAIN_LEVEL" != "terse" ]; then _EXPLAIN_LEVEL="default"; fi -echo "EXPLAIN_LEVEL: $_EXPLAIN_LEVEL" -_QUESTION_TUNING=$(~/.claude/skills/gstack/bin/gstack-config get question_tuning 2>/dev/null || echo "false") -echo "QUESTION_TUNING: $_QUESTION_TUNING" -mkdir -p ~/.gstack/analytics -if [ "$_TEL" != "off" ]; then -echo '{"skill":"spec","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(_repo=$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null | tr -cd 'a-zA-Z0-9._-'); echo "${_repo:-unknown}")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true -fi -for _PF in $(find ~/.gstack/analytics -maxdepth 1 -name '.pending-*' 2>/dev/null); do - if [ -f "$_PF" ]; then - if [ "$_TEL" != "off" ] && [ -x "~/.claude/skills/gstack/bin/gstack-telemetry-log" ]; then - ~/.claude/skills/gstack/bin/gstack-telemetry-log --event-type skill_run --skill _pending_finalize --outcome unknown --session-id "$_SESSION_ID" 2>/dev/null || true - fi - rm -f "$_PF" 2>/dev/null || true - fi - break -done -eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true -_LEARN_FILE="${GSTACK_HOME:-$HOME/.gstack}/projects/${SLUG:-unknown}/learnings.jsonl" -if [ -f "$_LEARN_FILE" ]; then - _LEARN_COUNT=$(wc -l < "$_LEARN_FILE" 2>/dev/null | tr -d ' ') - echo "LEARNINGS: $_LEARN_COUNT entries loaded" - if [ "$_LEARN_COUNT" -gt 5 ] 2>/dev/null; then - ~/.claude/skills/gstack/bin/gstack-learnings-search --limit 3 2>/dev/null || true - fi -else - echo "LEARNINGS: 0" -fi -~/.claude/skills/gstack/bin/gstack-timeline-log '{"skill":"spec","event":"started","branch":"'"$_BRANCH"'","session":"'"$_SESSION_ID"'"}' 2>/dev/null & -_HAS_ROUTING="no" -if [ -f CLAUDE.md ] && grep -q "## Skill routing" CLAUDE.md 2>/dev/null; then - _HAS_ROUTING="yes" -fi -_ROUTING_DECLINED=$(~/.claude/skills/gstack/bin/gstack-config get routing_declined 2>/dev/null || echo "false") -echo "HAS_ROUTING: $_HAS_ROUTING" -echo "ROUTING_DECLINED: $_ROUTING_DECLINED" -_VENDORED="no" -if [ -d ".claude/skills/gstack" ] && [ ! -L ".claude/skills/gstack" ]; then - if [ -f ".claude/skills/gstack/VERSION" ] || [ -d ".claude/skills/gstack/.git" ]; then - _VENDORED="yes" - fi -fi -echo "VENDORED_GSTACK: $_VENDORED" -echo "MODEL_OVERLAY: claude" -_CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode 2>/dev/null || echo "explicit") -_CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") -echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" -echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" -# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. -# Claude Code exposes plan mode via system reminders; we detect best-effort -# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and -# fall back to "inactive". Codex hosts and Claude execution mode both end up -# inactive, which is the safe default (defaults to file+execute pipeline). -if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then - export GSTACK_PLAN_MODE="active" -elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then - export GSTACK_PLAN_MODE="active" -else - export GSTACK_PLAN_MODE="inactive" -fi -echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" -[ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true -``` - -## Plan Mode Safe Operations - -In plan mode, allowed because they inform the plan: `$B`, `$D`, `codex exec`/`codex review`, writes to `~/.gstack/`, writes to the plan file, and `open` for generated artifacts. - -## Skill Invocation During Plan Mode - -If the user invokes a skill in plan mode, the skill takes precedence over generic plan mode behavior. **Treat the skill file as executable instructions, not reference.** Follow it step by step starting from Step 0; the first AskUserQuestion is the workflow entering plan mode, not a violation of it. AskUserQuestion (any variant — `mcp__*__AskUserQuestion` or native; see "AskUserQuestion Format → Tool resolution") satisfies plan mode's end-of-turn requirement. If AskUserQuestion is unavailable or a call fails, follow the AskUserQuestion Format failure fallback: `headless` → BLOCKED; `interactive` → the prose fallback (also satisfies end-of-turn). At a STOP point, stop immediately. Do not continue the workflow or call ExitPlanMode there. Commands marked "PLAN MODE EXCEPTION — ALWAYS RUN" execute. Call ExitPlanMode only after the skill workflow completes, or if the user tells you to cancel the skill or leave plan mode. - -If `PROACTIVE` is `"false"`, do not auto-invoke or proactively suggest skills. If a skill seems useful, ask: "I think /skillname might help here — want me to run it?" - -If `SKILL_PREFIX` is `"true"`, suggest/invoke `/gstack-*` names. Disk paths stay `~/.claude/skills/gstack/[skill-name]/SKILL.md`. - -If output shows `UPGRADE_AVAILABLE `: 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 output shows `JUST_UPGRADED `: print "Running gstack v{to} (just updated!)". If `SPAWNED_SESSION` is true, skip feature discovery. - -Feature discovery, max one prompt per session: -- Missing `~/.claude/skills/gstack/.feature-prompted-continuous-checkpoint`: AskUserQuestion for Continuous checkpoint auto-commits. If accepted, run `~/.claude/skills/gstack/bin/gstack-config set checkpoint_mode continuous`. Always touch marker. -- Missing `~/.claude/skills/gstack/.feature-prompted-model-overlay`: inform "Model overlays are active. MODEL_OVERLAY shows the patch." Always touch marker. - -After upgrade prompts, continue workflow. - -If `WRITING_STYLE_PENDING` is `yes`: ask once about writing style: - -> v1 prompts are simpler: first-use jargon glosses, outcome-framed questions, shorter prose. Keep default or restore terse? - -Options: -- A) Keep the new default (recommended — good writing helps everyone) -- B) Restore V0 prose — set `explain_level: terse` - -If A: leave `explain_level` unset (defaults to `default`). -If B: run `~/.claude/skills/gstack/bin/gstack-config set explain_level terse`. - -Always run (regardless of choice): -```bash -rm -f ~/.gstack/.writing-style-prompt-pending -touch ~/.gstack/.writing-style-prompted -``` - -Skip if `WRITING_STYLE_PENDING` is `no`. - -If `LAKE_INTRO` is `no`: say "gstack follows the **Boil the Ocean** principle — do the complete thing when AI makes marginal cost near-zero. Read more: https://garryslist.org/posts/boil-the-ocean" Offer to open: - -```bash -open https://garryslist.org/posts/boil-the-ocean -touch ~/.gstack/.completeness-intro-seen -``` - -Only run `open` if yes. Always run `touch`. - -If `TEL_PROMPTED` is `no` AND `LAKE_INTRO` is `yes`: ask telemetry once via AskUserQuestion: - -> Help gstack get better. Share usage data only: skill, duration, crashes, stable device ID. No code or file paths. Your repo name is recorded locally only and stripped before any upload. - -Options: -- A) Help gstack get better! (recommended) -- B) No thanks - -If A: run `~/.claude/skills/gstack/bin/gstack-config set telemetry community` - -If B: ask follow-up: - -> Anonymous mode sends only aggregate usage, no unique ID. - -Options: -- A) Sure, anonymous is fine -- B) No thanks, fully off - -If B→A: run `~/.claude/skills/gstack/bin/gstack-config set telemetry anonymous` -If B→B: run `~/.claude/skills/gstack/bin/gstack-config set telemetry off` - -Always run: -```bash -touch ~/.gstack/.telemetry-prompted -``` - -Skip if `TEL_PROMPTED` is `yes`. - -If `PROACTIVE_PROMPTED` is `no` AND `TEL_PROMPTED` is `yes`: ask once: - -> Let gstack proactively suggest skills, like /qa for "does this work?" or /investigate for bugs? - -Options: -- A) Keep it on (recommended) -- B) Turn it off — I'll type /commands myself - -If A: run `~/.claude/skills/gstack/bin/gstack-config set proactive true` -If B: run `~/.claude/skills/gstack/bin/gstack-config set proactive false` - -Always run: -```bash -touch ~/.gstack/.proactive-prompted -``` - -Skip if `PROACTIVE_PROMPTED` is `yes`. - -## First-run guidance (one-time) - -If `ACTIVATED` is `no` (first skill run on this machine) AND the preamble printed a non-empty `FIRST_TASK:` value that is NOT `nongit`: show ONE short, project-specific line mapped from the token, as a heads-up, then CONTINUE with whatever the user actually asked — do NOT halt their task. Map the token: `greenfield` → "Fresh repo — shape it first with `/spec` or `/office-hours`." `code_node`/`code_python`/`code_rust`/`code_go`/`code_ruby`/`code_ios` → "There's code here — `/qa` to see it work, or `/investigate` if something's off." `branch_ahead` → "Unshipped work on this branch — `/review` then `/ship`." `dirty_default` → "Uncommitted changes — `/review` before committing." `clean_default` → "Pick one: `/spec`, `/investigate`, or `/qa`." Then substitute the token you saw for TASK_TOKEN and run (best-effort), and mark activated: -```bash -~/.claude/skills/gstack/bin/gstack-telemetry-log --event-type first_task_scaffold_shown --skill "TASK_TOKEN" --outcome shown 2>/dev/null || true -touch ~/.gstack/.activated 2>/dev/null || true -``` - -If `ACTIVATED` is `no` but `FIRST_TASK:` is empty or `nongit` (headless, non-git, or nothing actionable): show nothing, just run `touch ~/.gstack/.activated 2>/dev/null || true`. - -Else if `ACTIVATED` is `yes` AND `FIRST_LOOP_SHOWN` is `no`: say once as a heads-up (then continue): - -> Tip: gstack pays off when you complete one loop — **plan → review → ship**. A common first loop: `/office-hours` or `/spec` to shape it, `/plan-eng-review` to lock it, then `/ship`. - -Then run `touch ~/.gstack/.first-loop-tip-shown 2>/dev/null || true`. - -Skip this section if `ACTIVATED` and `FIRST_LOOP_SHOWN` are both `yes`. - -If `HAS_ROUTING` is `no` AND `ROUTING_DECLINED` is `false` AND `PROACTIVE_PROMPTED` is `yes`: -Check if a CLAUDE.md file exists in the project root. If it does not exist, create it. - -Use AskUserQuestion: - -> gstack works best when your project's CLAUDE.md includes skill routing rules. - -Options: -- A) Add routing rules to CLAUDE.md (recommended) -- B) No thanks, I'll invoke skills manually - -If A: Append this section to the end of CLAUDE.md: - -```markdown - -## Skill routing - -When the user's request matches an available skill, invoke it via the Skill tool. When in doubt, invoke the skill. - -Key routing rules: -- Product ideas/brainstorming → invoke /office-hours -- Strategy/scope → invoke /plan-ceo-review -- Architecture → invoke /plan-eng-review -- Design system/plan review → invoke /design-consultation or /plan-design-review -- Full review pipeline → invoke /autoplan -- Bugs/errors → invoke /investigate -- QA/testing site behavior → invoke /qa or /qa-only -- Code review/diff check → invoke /review -- Visual polish → invoke /design-review -- Ship/deploy/PR → invoke /ship or /land-and-deploy -- Save progress → invoke /context-save -- Resume context → invoke /context-restore -- Author a backlog-ready spec/issue → invoke /spec -``` - -Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` - -If B: run `~/.claude/skills/gstack/bin/gstack-config set routing_declined true` and say they can re-enable with `gstack-config set routing_declined false`. - -This only happens once per project. Skip if `HAS_ROUTING` is `yes` or `ROUTING_DECLINED` is `true`. - -If `VENDORED_GSTACK` is `yes`, warn once via AskUserQuestion unless `~/.gstack/.vendoring-warned-$SLUG` exists: - -> This project has gstack vendored in `.claude/skills/gstack/`. Vendoring is deprecated. -> Migrate to team mode? - -Options: -- A) Yes, migrate to team mode now -- B) No, I'll handle it myself - -If A: -1. Run `git rm -r .claude/skills/gstack/` -2. Run `echo '.claude/skills/gstack/' >> .gitignore` -3. Run `~/.claude/skills/gstack/bin/gstack-team-init required` (or `optional`) -4. Run `git add .claude/ .gitignore CLAUDE.md && git commit -m "chore: migrate gstack from vendored to team mode"` -5. Tell the user: "Done. Each developer now runs: `cd ~/.claude/skills/gstack && ./setup --team`" - -If B: say "OK, you're on your own to keep the vendored copy up to date." - -Always run (regardless of choice): -```bash -eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true -touch ~/.gstack/.vendoring-warned-${SLUG:-unknown} -``` - -If marker exists, skip. - -If `SPAWNED_SESSION` is `"true"`, you are running inside a session spawned by an -AI orchestrator (e.g., OpenClaw). In spawned sessions: -- Do NOT use AskUserQuestion for interactive prompts. Auto-choose the recommended option. -- Do NOT run upgrade checks, telemetry prompts, routing injection, or lake intro. -- Focus on completing the task and reporting results via prose output. -- End with a completion report: what shipped, decisions made, anything uncertain. - -## AskUserQuestion Format - -### Tool resolution (read first) - -"AskUserQuestion" can resolve to two tools at runtime: the **host MCP variant** (e.g. `mcp__conductor__AskUserQuestion` — appears in your tool list when the host registers it) or the **native** Claude Code tool. - -**Conductor rule (read before the MCP rule):** if `CONDUCTOR_SESSION: true` was echoed by the preamble, do NOT call AskUserQuestion at all — neither native nor any `mcp__*__AskUserQuestion` variant. Render EVERY decision brief as the **prose form** below and STOP. This is proactive, not a reaction to a failure: Conductor disables native AUQ and its MCP variant is flaky (it returns `[Tool result missing due to internal error]`), so prose is the reliable path. **Auto-decide preferences still apply first:** if a `[plan-tune auto-decide] →