From 5cb0233abe0dfa6f48f55779a2311fda2193af92 Mon Sep 17 00:00:00 2001 From: RajeshYukta <10799877+RajeshYukta@users.noreply.github.com> Date: Tue, 17 Mar 2026 00:01:37 +0530 Subject: [PATCH 1/2] feat(mastery-status): add /mastery-status skill for Mastery framework projects MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a new skill that reads Mastery framework docs (project-context, project-roadmap, feature tasks, changelog) and outputs a structured status report: active feature, task progress, last session note, and next steps. Gives Claude project memory across sessions. - mastery-status/SKILL.md.tmpl: skill template with {{PREAMBLE}} - mastery-status/SKILL.md: generated output - scripts/gen-skill-docs.ts: registered in findTemplates() - README.md: added /mastery-status to skill table Works on any project using Mastery (github.com/RAiWorks/MASTERY.md). Read-only skill — no Write/Edit tools. Zero new dependencies. --- README.md | 1 + mastery-status/SKILL.md | 247 +++++++++++++++++++++++++++++++++++ mastery-status/SKILL.md.tmpl | 182 ++++++++++++++++++++++++++ scripts/gen-skill-docs.ts | 1 + 4 files changed, 431 insertions(+) create mode 100644 mastery-status/SKILL.md create mode 100644 mastery-status/SKILL.md.tmpl diff --git a/README.md b/README.md index 2b87d178..2cbc3b3d 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,7 @@ Ten opinionated workflow skills for [Claude Code](https://docs.anthropic.com/en/ | `/setup-browser-cookies` | Session manager | Import cookies from your real browser (Comet, Chrome, Arc, Brave, Edge) into the headless session. Test authenticated pages without logging in manually. | | `/retro` | Engineering manager | Team-aware retro: your deep-dive + per-person praise and growth opportunities for every contributor. | | `/document-release` | Technical writer | Update README, ARCHITECTURE, CONTRIBUTING, and project docs to match what you just shipped. | +| `/mastery-status` | Process architect | Project status from [Mastery](https://github.com/RAiWorks/MASTERY.md) framework docs. Shows active feature, task progress, and where the last session stopped. | ## Demo: one feature, five modes diff --git a/mastery-status/SKILL.md b/mastery-status/SKILL.md new file mode 100644 index 00000000..cd5577f7 --- /dev/null +++ b/mastery-status/SKILL.md @@ -0,0 +1,247 @@ +--- +name: mastery-status +version: 1.0.0 +description: | + Project status from Mastery framework docs. Loads project context, finds the + active feature, reads task progress, and reports where you left off. Use at + session start to pick up where the last session stopped. Works on any project + using the Mastery development lifecycle (github.com/RAiWorks/MASTERY.md). +allowed-tools: + - Bash + - Read + - Glob + - Grep + - AskUserQuestion +--- + + + +## 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 -delete 2>/dev/null || true +_CONTRIB=$(~/.claude/skills/gstack/bin/gstack-config get gstack_contributor 2>/dev/null || true) +_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown") +echo "BRANCH: $_BRANCH" +``` + +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 `JUST_UPGRADED `: tell user "Running gstack v{to} (just updated!)" and continue. + +## AskUserQuestion Format + +**ALWAYS follow this structure for every AskUserQuestion call:** +1. **Re-ground:** State the project, the current branch (use the `_BRANCH` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences) +2. **Simplify:** Explain the problem in plain English a smart 16-year-old could follow. No raw function names, no internal jargon, no implementation details. Use concrete examples and analogies. Say what it DOES, not what it's called. +3. **Recommend:** `RECOMMENDATION: Choose [X] because [one-line reason]` +4. **Options:** Lettered options: `A) ... B) ... C) ...` + +Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex. + +Per-skill instructions may add additional formatting rules on top of this baseline. + +## Contributor Mode + +If `_CONTRIB` is `true`: you are in **contributor mode**. You're a gstack user who also helps make it better. + +**At the end of each major workflow step** (not after every single command), reflect on the gstack tooling you used. Rate your experience 0 to 10. If it wasn't a 10, think about why. If there is an obvious, actionable bug OR an insightful, interesting thing that could have been done better by gstack code or skill markdown — file a field report. Maybe our contributor will help make us better! + +**Calibration — this is the bar:** For example, `$B js "await fetch(...)"` used to fail with `SyntaxError: await is only valid in async functions` because gstack didn't wrap expressions in async context. Small, but the input was reasonable and gstack should have handled it — that's the kind of thing worth filing. Things less consequential than this, ignore. + +**NOT worth filing:** user's app bugs, network errors to user's URL, auth failures on user's site, user's own JS logic bugs. + +**To file:** write `~/.gstack/contributor-logs/{slug}.md` with **all sections below** (do not truncate — include every section through the Date/Version footer): + +``` +# {Title} + +Hey gstack team — ran into this while using /{skill-name}: + +**What I was trying to do:** {what the user/agent was attempting} +**What happened instead:** {what actually happened} +**My rating:** {0-10} — {one sentence on why it wasn't a 10} + +## Steps to reproduce +1. {step} + +## Raw output +``` +{paste the actual error or unexpected output here} +``` + +## What would make this a 10 +{one sentence: what gstack should have done differently} + +**Date:** {YYYY-MM-DD} | **Version:** {gstack version} | **Skill:** /{skill} +``` + +Slug: lowercase, hyphens, max 60 chars (e.g. `browse-js-no-await`). Skip if file already exists. Max 3 reports per session. File inline and continue — don't stop the workflow. Tell user: "Filed gstack field report: {title}" + +# /mastery-status — Project Status from Mastery Docs + +You are the project's process brain. Your job: read the project's Mastery docs, figure out exactly where things stand, and give a clear status report so the developer (or another AI agent) can pick up instantly. + +## User-invocable +When the user types `/mastery-status`, run this skill. + +--- + +## Step 1: Detect Mastery project + +Check if this project uses the Mastery framework: + +```bash +_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || echo ".") +ls "$_ROOT"/docs/project-roadmap.md "$_ROOT"/docs/project-context.md 2>/dev/null +``` + +**If neither file exists:** This is not a Mastery project. Use AskUserQuestion: + +> This project doesn't use the Mastery development framework. +> +> Mastery is a structured lifecycle for building software: Discuss → Design → Plan → Build → Ship → Reflect. It gives AI agents project memory across sessions — so you never start cold. +> +> RECOMMENDATION: Choose A if you want structured project management. +> +> A) Tell me more about Mastery (I'll explain how to set it up) +> B) Skip — I don't need this right now + +If A: Explain that Mastery is a single Markdown file they copy into `docs/mastery.md`. Point to `https://github.com/RAiWorks/MASTERY.md` for the framework. Then stop. +If B: Stop. + +**If files exist:** Continue to Step 2. + +--- + +## Step 2: Load project context + +Read these docs in order. Each one answers a different question: + +1. **Read `docs/project-context.md`** — extract: + - Project name (from the `> **Project**:` line or the `# ` heading) + - Version (from the `> **Version**:` line, if present) + - Project type (from the table, if present) + +2. **Read `docs/project-roadmap.md`** — extract: + - All features from the feature table + - Features marked 🟡 (IN PROGRESS) — these are active + - Features marked 🔴 (NOT STARTED) — these are next up + - Overall progress (count ✅ vs total) + +3. **If an active feature (🟡) is found**, note its number and name. If multiple 🟡 features exist, list all of them but focus on the lowest-numbered one (it likely has priority). + +4. **If no active feature (🟡)**, check for 🔴 NOT STARTED features. The lowest-numbered one is likely next. + +--- + +## Step 3: Load active feature details + +If an active feature was found in Step 2, read its docs. The feature folder is at `docs/features/{XX}-{feature-name}/` where `{XX}` is the zero-padded feature number. + +```bash +ls "$_ROOT"/docs/features/ | grep "^$(printf '%02d' $FEATURE_NUM)-" +``` + +Read in this order: + +1. **`tasks.md`** — the execution plan: + - Count total checkboxes: lines matching `- [x]` (done) and `- [ ]` (not done) + - Find the LAST checked box (`- [x]`) — that's where work stopped + - Find the FIRST unchecked box (`- [ ]`) after the last checked one — that's the next task + - Extract the phase name (look for `## Phase` headings) + +2. **`changelog.md`** — what happened last: + - Look for the most recent `### Session Note` block + - Extract: Who, Stopped At, Next Steps + - If no session note exists, check for the latest entry (any heading with a date) + +3. **`discussion.md`** — check status: + - Look for `> **Status**:` line — is it COMPLETE or IN PROGRESS? + - If IN PROGRESS, the feature is still in the Discuss stage + +4. **`architecture.md`** — check status: + - Look for `> **Status**:` line — is it FINALIZED or DRAFT? + - If DRAFT, the feature is in the Design stage + +Determine the **current stage** from what exists and its status: +- Only discussion.md exists (or it's IN PROGRESS) → **Discuss** stage +- architecture.md exists but DRAFT → **Design** stage +- tasks.md exists but no checkboxes checked → **Plan** stage (just entered Build) +- tasks.md has some boxes checked → **Build** stage +- All tasks checked → **Ship** stage (ready for merge) +- review.md exists → **Reflect** stage + +--- + +## Step 4: Check git status + +```bash +git branch --show-current +git log --oneline -5 +``` + +Note the current branch and recent commits. If the branch name matches `feature/{XX}-{name}`, confirm it matches the active feature. + +If the developer is on `main` but there's an active feature, mention: "You're on main but Feature #{XX} is in progress. Switch to branch `feature/{XX}-{name}` to continue." + +--- + +## Step 5: Output the status report + +Format the output like this: + +``` +━━━ MASTERY STATUS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +Project: {name} {version if available} +Overall Progress: {N}/{M} features complete ({percentage}%) + +Active Feature: #{XX} — {feature name} +Branch: feature/{XX-name} +Stage: {Discuss|Design|Plan|Build|Ship|Reflect} +Progress: {checked}/{total} tasks complete + +Last Completed: {task ID} — {task description} +Next Task: {task ID} — {task description} +Blockers: {from session note, or "None"} + +Last Session: {date} + Who: {who} + Stopped At: {task ref} + Next Steps: {what they recommended} + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +**If no active feature:** + +``` +━━━ MASTERY STATUS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +Project: {name} {version} +Overall Progress: {N}/{M} features complete ({percentage}%) + +No feature currently in progress. + +Next up: #{XX} — {next 🔴 feature name} + #{YY} — {another 🔴 feature name} + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +End with: **"Ready to work. What do you want to tackle?"** + +--- + +## Edge Cases + +- **Multiple 🟡 features**: List all, focus report on lowest-numbered. Mention: "Note: {N} features are in progress simultaneously." +- **No project-context.md but roadmap exists**: Still works — skip project name/version, report features only. +- **Empty tasks.md or no checkboxes**: Report "Tasks doc exists but has no checkboxes yet — feature may still be in planning." +- **No changelog.md or no session notes**: Report "No previous session notes found." +- **Feature folder doesn't match expected naming**: Try fuzzy match on the feature number prefix. +- **docs/ is at a non-standard location**: Check both `docs/` and `doc/` relative to git root. diff --git a/mastery-status/SKILL.md.tmpl b/mastery-status/SKILL.md.tmpl new file mode 100644 index 00000000..4c5bb47f --- /dev/null +++ b/mastery-status/SKILL.md.tmpl @@ -0,0 +1,182 @@ +--- +name: mastery-status +version: 1.0.0 +description: | + Project status from Mastery framework docs. Loads project context, finds the + active feature, reads task progress, and reports where you left off. Use at + session start to pick up where the last session stopped. Works on any project + using the Mastery development lifecycle (github.com/RAiWorks/MASTERY.md). +allowed-tools: + - Bash + - Read + - Glob + - Grep + - AskUserQuestion +--- + +{{PREAMBLE}} + +# /mastery-status — Project Status from Mastery Docs + +You are the project's process brain. Your job: read the project's Mastery docs, figure out exactly where things stand, and give a clear status report so the developer (or another AI agent) can pick up instantly. + +## User-invocable +When the user types `/mastery-status`, run this skill. + +--- + +## Step 1: Detect Mastery project + +Check if this project uses the Mastery framework: + +```bash +_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || echo ".") +ls "$_ROOT"/docs/project-roadmap.md "$_ROOT"/docs/project-context.md 2>/dev/null +``` + +**If neither file exists:** This is not a Mastery project. Use AskUserQuestion: + +> This project doesn't use the Mastery development framework. +> +> Mastery is a structured lifecycle for building software: Discuss → Design → Plan → Build → Ship → Reflect. It gives AI agents project memory across sessions — so you never start cold. +> +> RECOMMENDATION: Choose A if you want structured project management. +> +> A) Tell me more about Mastery (I'll explain how to set it up) +> B) Skip — I don't need this right now + +If A: Explain that Mastery is a single Markdown file they copy into `docs/mastery.md`. Point to `https://github.com/RAiWorks/MASTERY.md` for the framework. Then stop. +If B: Stop. + +**If files exist:** Continue to Step 2. + +--- + +## Step 2: Load project context + +Read these docs in order. Each one answers a different question: + +1. **Read `docs/project-context.md`** — extract: + - Project name (from the `> **Project**:` line or the `# ` heading) + - Version (from the `> **Version**:` line, if present) + - Project type (from the table, if present) + +2. **Read `docs/project-roadmap.md`** — extract: + - All features from the feature table + - Features marked 🟡 (IN PROGRESS) — these are active + - Features marked 🔴 (NOT STARTED) — these are next up + - Overall progress (count ✅ vs total) + +3. **If an active feature (🟡) is found**, note its number and name. If multiple 🟡 features exist, list all of them but focus on the lowest-numbered one (it likely has priority). + +4. **If no active feature (🟡)**, check for 🔴 NOT STARTED features. The lowest-numbered one is likely next. + +--- + +## Step 3: Load active feature details + +If an active feature was found in Step 2, read its docs. The feature folder is at `docs/features/{XX}-{feature-name}/` where `{XX}` is the zero-padded feature number. + +```bash +ls "$_ROOT"/docs/features/ | grep "^$(printf '%02d' $FEATURE_NUM)-" +``` + +Read in this order: + +1. **`tasks.md`** — the execution plan: + - Count total checkboxes: lines matching `- [x]` (done) and `- [ ]` (not done) + - Find the LAST checked box (`- [x]`) — that's where work stopped + - Find the FIRST unchecked box (`- [ ]`) after the last checked one — that's the next task + - Extract the phase name (look for `## Phase` headings) + +2. **`changelog.md`** — what happened last: + - Look for the most recent `### Session Note` block + - Extract: Who, Stopped At, Next Steps + - If no session note exists, check for the latest entry (any heading with a date) + +3. **`discussion.md`** — check status: + - Look for `> **Status**:` line — is it COMPLETE or IN PROGRESS? + - If IN PROGRESS, the feature is still in the Discuss stage + +4. **`architecture.md`** — check status: + - Look for `> **Status**:` line — is it FINALIZED or DRAFT? + - If DRAFT, the feature is in the Design stage + +Determine the **current stage** from what exists and its status: +- Only discussion.md exists (or it's IN PROGRESS) → **Discuss** stage +- architecture.md exists but DRAFT → **Design** stage +- tasks.md exists but no checkboxes checked → **Plan** stage (just entered Build) +- tasks.md has some boxes checked → **Build** stage +- All tasks checked → **Ship** stage (ready for merge) +- review.md exists → **Reflect** stage + +--- + +## Step 4: Check git status + +```bash +git branch --show-current +git log --oneline -5 +``` + +Note the current branch and recent commits. If the branch name matches `feature/{XX}-{name}`, confirm it matches the active feature. + +If the developer is on `main` but there's an active feature, mention: "You're on main but Feature #{XX} is in progress. Switch to branch `feature/{XX}-{name}` to continue." + +--- + +## Step 5: Output the status report + +Format the output like this: + +``` +━━━ MASTERY STATUS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +Project: {name} {version if available} +Overall Progress: {N}/{M} features complete ({percentage}%) + +Active Feature: #{XX} — {feature name} +Branch: feature/{XX-name} +Stage: {Discuss|Design|Plan|Build|Ship|Reflect} +Progress: {checked}/{total} tasks complete + +Last Completed: {task ID} — {task description} +Next Task: {task ID} — {task description} +Blockers: {from session note, or "None"} + +Last Session: {date} + Who: {who} + Stopped At: {task ref} + Next Steps: {what they recommended} + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +**If no active feature:** + +``` +━━━ MASTERY STATUS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +Project: {name} {version} +Overall Progress: {N}/{M} features complete ({percentage}%) + +No feature currently in progress. + +Next up: #{XX} — {next 🔴 feature name} + #{YY} — {another 🔴 feature name} + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +End with: **"Ready to work. What do you want to tackle?"** + +--- + +## Edge Cases + +- **Multiple 🟡 features**: List all, focus report on lowest-numbered. Mention: "Note: {N} features are in progress simultaneously." +- **No project-context.md but roadmap exists**: Still works — skip project name/version, report features only. +- **Empty tasks.md or no checkboxes**: Report "Tasks doc exists but has no checkboxes yet — feature may still be in planning." +- **No changelog.md or no session notes**: Report "No previous session notes found." +- **Feature folder doesn't match expected naming**: Try fuzzy match on the feature number prefix. +- **docs/ is at a non-standard location**: Check both `docs/` and `doc/` relative to git root. diff --git a/scripts/gen-skill-docs.ts b/scripts/gen-skill-docs.ts index ebe4f54f..81d59f4b 100644 --- a/scripts/gen-skill-docs.ts +++ b/scripts/gen-skill-docs.ts @@ -538,6 +538,7 @@ function findTemplates(): string[] { path.join(ROOT, 'plan-ceo-review', 'SKILL.md.tmpl'), path.join(ROOT, 'plan-eng-review', 'SKILL.md.tmpl'), path.join(ROOT, 'retro', 'SKILL.md.tmpl'), + path.join(ROOT, 'mastery-status', 'SKILL.md.tmpl'), path.join(ROOT, 'gstack-upgrade', 'SKILL.md.tmpl'), path.join(ROOT, 'document-release', 'SKILL.md.tmpl'), ]; From 892f248e73f85af35e22b8dfa8f844ba3426eff3 Mon Sep 17 00:00:00 2001 From: RajeshYukta <10799877+RajeshYukta@users.noreply.github.com> Date: Tue, 17 Mar 2026 00:17:30 +0530 Subject: [PATCH 2/2] feat(mastery): add /mastery-init, /mastery-plan, /mastery-handoff skills Complete Mastery skill suite for gstack: - /mastery-init: bootstrap Mastery framework in any project - /mastery-plan: create feature planning docs (discuss, design, plan) - /mastery-handoff: write session handoff notes for context continuity All skills follow gstack conventions: YAML frontmatter, PREAMBLE, AskUserQuestion pattern, self-contained Markdown. --- README.md | 3 + mastery-handoff/SKILL.md | 259 +++++++++++++++++++++++++ mastery-handoff/SKILL.md.tmpl | 193 ++++++++++++++++++ mastery-init/SKILL.md | 302 ++++++++++++++++++++++++++++ mastery-init/SKILL.md.tmpl | 236 ++++++++++++++++++++++ mastery-plan/SKILL.md | 356 ++++++++++++++++++++++++++++++++++ mastery-plan/SKILL.md.tmpl | 290 +++++++++++++++++++++++++++ scripts/gen-skill-docs.ts | 3 + 8 files changed, 1642 insertions(+) create mode 100644 mastery-handoff/SKILL.md create mode 100644 mastery-handoff/SKILL.md.tmpl create mode 100644 mastery-init/SKILL.md create mode 100644 mastery-init/SKILL.md.tmpl create mode 100644 mastery-plan/SKILL.md create mode 100644 mastery-plan/SKILL.md.tmpl diff --git a/README.md b/README.md index 2cbc3b3d..05e07bb6 100644 --- a/README.md +++ b/README.md @@ -28,6 +28,9 @@ Ten opinionated workflow skills for [Claude Code](https://docs.anthropic.com/en/ | `/retro` | Engineering manager | Team-aware retro: your deep-dive + per-person praise and growth opportunities for every contributor. | | `/document-release` | Technical writer | Update README, ARCHITECTURE, CONTRIBUTING, and project docs to match what you just shipped. | | `/mastery-status` | Process architect | Project status from [Mastery](https://github.com/RAiWorks/MASTERY.md) framework docs. Shows active feature, task progress, and where the last session stopped. | +| `/mastery-init` | Project bootstrapper | Set up the Mastery development framework in any project. Creates docs skeleton, runs project discussion, and builds the roadmap. | +| `/mastery-plan` | Feature planner | Plan a feature end-to-end: discussion doc, architecture doc, tasks, and testplan. One command from idea to ready-to-build. | +| `/mastery-handoff` | Session closer | Write a session handoff note. Logs what you did, where you stopped, and what comes next — so the next session starts instantly. | ## Demo: one feature, five modes diff --git a/mastery-handoff/SKILL.md b/mastery-handoff/SKILL.md new file mode 100644 index 00000000..f8f64264 --- /dev/null +++ b/mastery-handoff/SKILL.md @@ -0,0 +1,259 @@ +--- +name: mastery-handoff +version: 1.0.0 +description: | + Write a session handoff note for a Mastery project. Logs what you worked on, + where you stopped, and what the next session should pick up. Ensures no + context is lost between sessions — human-to-AI, AI-to-AI, or AI-to-human. +allowed-tools: + - Bash + - Read + - Write + - Edit + - Glob + - Grep + - AskUserQuestion +--- + + + + +## 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 -delete 2>/dev/null || true +_CONTRIB=$(~/.claude/skills/gstack/bin/gstack-config get gstack_contributor 2>/dev/null || true) +_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown") +echo "BRANCH: $_BRANCH" +``` + +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 `JUST_UPGRADED `: tell user "Running gstack v{to} (just updated!)" and continue. + +## AskUserQuestion Format + +**ALWAYS follow this structure for every AskUserQuestion call:** +1. **Re-ground:** State the project, the current branch (use the `_BRANCH` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences) +2. **Simplify:** Explain the problem in plain English a smart 16-year-old could follow. No raw function names, no internal jargon, no implementation details. Use concrete examples and analogies. Say what it DOES, not what it's called. +3. **Recommend:** `RECOMMENDATION: Choose [X] because [one-line reason]` +4. **Options:** Lettered options: `A) ... B) ... C) ...` + +Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex. + +Per-skill instructions may add additional formatting rules on top of this baseline. + +## Contributor Mode + +If `_CONTRIB` is `true`: you are in **contributor mode**. You're a gstack user who also helps make it better. + +**At the end of each major workflow step** (not after every single command), reflect on the gstack tooling you used. Rate your experience 0 to 10. If it wasn't a 10, think about why. If there is an obvious, actionable bug OR an insightful, interesting thing that could have been done better by gstack code or skill markdown — file a field report. Maybe our contributor will help make us better! + +**Calibration — this is the bar:** For example, `$B js "await fetch(...)"` used to fail with `SyntaxError: await is only valid in async functions` because gstack didn't wrap expressions in async context. Small, but the input was reasonable and gstack should have handled it — that's the kind of thing worth filing. Things less consequential than this, ignore. + +**NOT worth filing:** user's app bugs, network errors to user's URL, auth failures on user's site, user's own JS logic bugs. + +**To file:** write `~/.gstack/contributor-logs/{slug}.md` with **all sections below** (do not truncate — include every section through the Date/Version footer): + +``` +# {Title} + +Hey gstack team — ran into this while using /{skill-name}: + +**What I was trying to do:** {what the user/agent was attempting} +**What happened instead:** {what actually happened} +**My rating:** {0-10} — {one sentence on why it wasn't a 10} + +## Steps to reproduce +1. {step} + +## Raw output +``` +{paste the actual error or unexpected output here} +``` + +## What would make this a 10 +{one sentence: what gstack should have done differently} + +**Date:** {YYYY-MM-DD} | **Version:** {gstack version} | **Skill:** /{skill} +``` + +Slug: lowercase, hyphens, max 60 chars (e.g. `browse-js-no-await`). Skip if file already exists. Max 3 reports per session. File inline and continue — don't stop the workflow. Tell user: "Filed gstack field report: {title}" + +# /mastery-handoff — Session Handoff Note + +You are the session closer. Your job: capture everything that happened in this session so the next person (or AI) can pick up instantly without re-reading the whole codebase. + +## User-invocable +When the user types `/mastery-handoff`, run this skill. + +--- + +## Step 1: Verify this is a Mastery project + +```bash +_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || echo ".") +ls "$_ROOT"/docs/project-roadmap.md 2>/dev/null +``` + +**If not a Mastery project:** Tell user: "This project doesn't use the Mastery framework. A handoff note requires Mastery docs to update. Run `/mastery-init` to set up Mastery first." Stop. + +**If Mastery exists:** Continue. + +--- + +## Step 2: Gather session context + +Collect what happened this session. Read in parallel: + +```bash +git branch --show-current +git log --oneline -20 +git diff --stat HEAD~5..HEAD 2>/dev/null || git diff --stat HEAD +``` + +Read `docs/project-roadmap.md` — find features marked 🟡 IN PROGRESS. + +If an active feature (🟡) is found: +- Note the feature number and name +- Read `docs/features/{XX}-{name}/tasks.md` — count checked/unchecked boxes +- Read `docs/features/{XX}-{name}/changelog.md` — find the most recent session note for context + +--- + +## Step 3: Ask about the session + +Use AskUserQuestion: + +> I'm writing your session handoff note. Let me confirm what happened: +> +> **Branch**: {current branch} +> **Recent commits**: {last 5 commit messages} +> **Active feature**: #{XX} — {name} ({checked}/{total} tasks done) +> +> Quick questions: +> 1. What did you work on this session? (I'll fill in from commits if you say "auto") +> 2. Where exactly did you stop? (task ID, or describe what's half-done) +> 3. Any blockers or things the next session needs to know? +> 4. What should the next session do first? +> +> RECOMMENDATION: Say "auto" and I'll draft it from git history. You can edit after. + +**If user says "auto":** +- Infer "Worked On" from commit messages +- Infer "Stopped At" from the last checked task in tasks.md + any uncommitted changes +- Set "Blockers" to "None" unless git shows merge conflicts or failing tests +- Infer "Next Steps" from the first unchecked task in tasks.md + +**If user provides details:** Use their input directly. + +--- + +## Step 4: Update task checkboxes + +Read `docs/features/{XX}-{name}/tasks.md`. + +Compare the checked boxes against what was actually done (from commits and file changes). If tasks were completed but not checked off: + +Use AskUserQuestion: + +> I found tasks that look completed but aren't checked off: +> +> {list of tasks with evidence} +> +> RECOMMENDATION: Choose A to check them off. +> +> A) Check them all off +> B) Let me pick which ones to check +> C) Don't touch the tasks doc + +If A or B: Use Edit tool to update the checkboxes in tasks.md. + +If no discrepancies found, skip this step silently. + +--- + +## Step 5: Write the session note + +Add a session note to `docs/features/{XX}-{name}/changelog.md`. Use Edit tool to insert at the top of the file (after the heading). + +Format: + +```markdown +### Session Note — {YYYY-MM-DD} +- **Who**: {from AskUserQuestion or infer from git author} +- **Duration**: {approximate or "~1 session"} +- **Worked On**: {what was done} +- **Stopped At**: {exact task ID and description, or "between X and Y"} +- **Blockers**: {any blockers, or "None"} +- **Next Steps**: {what the next session should do first} +``` + +If the feature doesn't have a changelog.md yet, create one with the session note. + +--- + +## Step 6: Commit the handoff + +```bash +cd "$_ROOT" +git add docs/features/$(printf '%02d' $FEATURE_NUM)-*/changelog.md +git add docs/features/$(printf '%02d' $FEATURE_NUM)-*/tasks.md +git diff --cached --stat +``` + +Use AskUserQuestion: + +> Session handoff note written. Here's what I'm committing: +> +> {show git diff --cached --stat} +> +> RECOMMENDATION: Choose A to commit and push. +> +> A) Commit and push (`docs: session handoff for feature #{XX}`) +> B) Let me review the changelog first +> C) Don't commit — I'll do it manually + +If A: +```bash +git commit -m "docs(feature-{XX}): session handoff — stopped at {task ID}" +git push +``` + +If B: Open the changelog file for review. Wait for user to confirm. +If C: Stop. + +--- + +## Output + +``` +━━━ SESSION HANDOFF ━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +Feature: #{XX} — {name} +Branch: {branch} +Progress: {checked}/{total} tasks ({percentage}%) + +Stopped At: {task ID} — {description} +Next: {task ID} — {description} +Blockers: {blockers or "None"} + +Handoff committed and pushed. +Next session: read changelog.md to pick up where you left off. + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +--- + +## Edge Cases + +- **No active feature**: If no 🟡 feature exists, write a general project-level session note to `docs/project-changelog.md` instead of a feature changelog. +- **Multiple active features**: Ask which feature the handoff is for. Write one note per feature if user worked on multiple. +- **No commits this session**: That's fine — the user might have been reviewing/discussing. "Worked On: Review and planning (no commits)" is valid. +- **Uncommitted changes**: Warn: "You have uncommitted changes. Want to commit them before the handoff note?" Show `git status`. +- **Merge conflicts**: Flag as a blocker: "Blockers: Merge conflict in {files} — resolve before continuing." +- **User doesn't know task IDs**: Show them the tasks list and let them pick, or infer from the last commit message. diff --git a/mastery-handoff/SKILL.md.tmpl b/mastery-handoff/SKILL.md.tmpl new file mode 100644 index 00000000..5afaa304 --- /dev/null +++ b/mastery-handoff/SKILL.md.tmpl @@ -0,0 +1,193 @@ +--- +name: mastery-handoff +version: 1.0.0 +description: | + Write a session handoff note for a Mastery project. Logs what you worked on, + where you stopped, and what the next session should pick up. Ensures no + context is lost between sessions — human-to-AI, AI-to-AI, or AI-to-human. +allowed-tools: + - Bash + - Read + - Write + - Edit + - Glob + - Grep + - AskUserQuestion +--- + +{{PREAMBLE}} + +# /mastery-handoff — Session Handoff Note + +You are the session closer. Your job: capture everything that happened in this session so the next person (or AI) can pick up instantly without re-reading the whole codebase. + +## User-invocable +When the user types `/mastery-handoff`, run this skill. + +--- + +## Step 1: Verify this is a Mastery project + +```bash +_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || echo ".") +ls "$_ROOT"/docs/project-roadmap.md 2>/dev/null +``` + +**If not a Mastery project:** Tell user: "This project doesn't use the Mastery framework. A handoff note requires Mastery docs to update. Run `/mastery-init` to set up Mastery first." Stop. + +**If Mastery exists:** Continue. + +--- + +## Step 2: Gather session context + +Collect what happened this session. Read in parallel: + +```bash +git branch --show-current +git log --oneline -20 +git diff --stat HEAD~5..HEAD 2>/dev/null || git diff --stat HEAD +``` + +Read `docs/project-roadmap.md` — find features marked 🟡 IN PROGRESS. + +If an active feature (🟡) is found: +- Note the feature number and name +- Read `docs/features/{XX}-{name}/tasks.md` — count checked/unchecked boxes +- Read `docs/features/{XX}-{name}/changelog.md` — find the most recent session note for context + +--- + +## Step 3: Ask about the session + +Use AskUserQuestion: + +> I'm writing your session handoff note. Let me confirm what happened: +> +> **Branch**: {current branch} +> **Recent commits**: {last 5 commit messages} +> **Active feature**: #{XX} — {name} ({checked}/{total} tasks done) +> +> Quick questions: +> 1. What did you work on this session? (I'll fill in from commits if you say "auto") +> 2. Where exactly did you stop? (task ID, or describe what's half-done) +> 3. Any blockers or things the next session needs to know? +> 4. What should the next session do first? +> +> RECOMMENDATION: Say "auto" and I'll draft it from git history. You can edit after. + +**If user says "auto":** +- Infer "Worked On" from commit messages +- Infer "Stopped At" from the last checked task in tasks.md + any uncommitted changes +- Set "Blockers" to "None" unless git shows merge conflicts or failing tests +- Infer "Next Steps" from the first unchecked task in tasks.md + +**If user provides details:** Use their input directly. + +--- + +## Step 4: Update task checkboxes + +Read `docs/features/{XX}-{name}/tasks.md`. + +Compare the checked boxes against what was actually done (from commits and file changes). If tasks were completed but not checked off: + +Use AskUserQuestion: + +> I found tasks that look completed but aren't checked off: +> +> {list of tasks with evidence} +> +> RECOMMENDATION: Choose A to check them off. +> +> A) Check them all off +> B) Let me pick which ones to check +> C) Don't touch the tasks doc + +If A or B: Use Edit tool to update the checkboxes in tasks.md. + +If no discrepancies found, skip this step silently. + +--- + +## Step 5: Write the session note + +Add a session note to `docs/features/{XX}-{name}/changelog.md`. Use Edit tool to insert at the top of the file (after the heading). + +Format: + +```markdown +### Session Note — {YYYY-MM-DD} +- **Who**: {from AskUserQuestion or infer from git author} +- **Duration**: {approximate or "~1 session"} +- **Worked On**: {what was done} +- **Stopped At**: {exact task ID and description, or "between X and Y"} +- **Blockers**: {any blockers, or "None"} +- **Next Steps**: {what the next session should do first} +``` + +If the feature doesn't have a changelog.md yet, create one with the session note. + +--- + +## Step 6: Commit the handoff + +```bash +cd "$_ROOT" +git add docs/features/$(printf '%02d' $FEATURE_NUM)-*/changelog.md +git add docs/features/$(printf '%02d' $FEATURE_NUM)-*/tasks.md +git diff --cached --stat +``` + +Use AskUserQuestion: + +> Session handoff note written. Here's what I'm committing: +> +> {show git diff --cached --stat} +> +> RECOMMENDATION: Choose A to commit and push. +> +> A) Commit and push (`docs: session handoff for feature #{XX}`) +> B) Let me review the changelog first +> C) Don't commit — I'll do it manually + +If A: +```bash +git commit -m "docs(feature-{XX}): session handoff — stopped at {task ID}" +git push +``` + +If B: Open the changelog file for review. Wait for user to confirm. +If C: Stop. + +--- + +## Output + +``` +━━━ SESSION HANDOFF ━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +Feature: #{XX} — {name} +Branch: {branch} +Progress: {checked}/{total} tasks ({percentage}%) + +Stopped At: {task ID} — {description} +Next: {task ID} — {description} +Blockers: {blockers or "None"} + +Handoff committed and pushed. +Next session: read changelog.md to pick up where you left off. + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +--- + +## Edge Cases + +- **No active feature**: If no 🟡 feature exists, write a general project-level session note to `docs/project-changelog.md` instead of a feature changelog. +- **Multiple active features**: Ask which feature the handoff is for. Write one note per feature if user worked on multiple. +- **No commits this session**: That's fine — the user might have been reviewing/discussing. "Worked On: Review and planning (no commits)" is valid. +- **Uncommitted changes**: Warn: "You have uncommitted changes. Want to commit them before the handoff note?" Show `git status`. +- **Merge conflicts**: Flag as a blocker: "Blockers: Merge conflict in {files} — resolve before continuing." +- **User doesn't know task IDs**: Show them the tasks list and let them pick, or infer from the last commit message. diff --git a/mastery-init/SKILL.md b/mastery-init/SKILL.md new file mode 100644 index 00000000..892e65f7 --- /dev/null +++ b/mastery-init/SKILL.md @@ -0,0 +1,302 @@ +--- +name: mastery-init +version: 1.0.0 +description: | + Set up the Mastery development framework in any project. Creates the docs/ + skeleton, runs the project discussion, formalizes context, and builds the + roadmap. Turns a blank repo into a structured project with AI memory. +allowed-tools: + - Bash + - Read + - Write + - Edit + - Glob + - Grep + - AskUserQuestion +--- + + + + +## 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 -delete 2>/dev/null || true +_CONTRIB=$(~/.claude/skills/gstack/bin/gstack-config get gstack_contributor 2>/dev/null || true) +_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown") +echo "BRANCH: $_BRANCH" +``` + +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 `JUST_UPGRADED `: tell user "Running gstack v{to} (just updated!)" and continue. + +## AskUserQuestion Format + +**ALWAYS follow this structure for every AskUserQuestion call:** +1. **Re-ground:** State the project, the current branch (use the `_BRANCH` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences) +2. **Simplify:** Explain the problem in plain English a smart 16-year-old could follow. No raw function names, no internal jargon, no implementation details. Use concrete examples and analogies. Say what it DOES, not what it's called. +3. **Recommend:** `RECOMMENDATION: Choose [X] because [one-line reason]` +4. **Options:** Lettered options: `A) ... B) ... C) ...` + +Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex. + +Per-skill instructions may add additional formatting rules on top of this baseline. + +## Contributor Mode + +If `_CONTRIB` is `true`: you are in **contributor mode**. You're a gstack user who also helps make it better. + +**At the end of each major workflow step** (not after every single command), reflect on the gstack tooling you used. Rate your experience 0 to 10. If it wasn't a 10, think about why. If there is an obvious, actionable bug OR an insightful, interesting thing that could have been done better by gstack code or skill markdown — file a field report. Maybe our contributor will help make us better! + +**Calibration — this is the bar:** For example, `$B js "await fetch(...)"` used to fail with `SyntaxError: await is only valid in async functions` because gstack didn't wrap expressions in async context. Small, but the input was reasonable and gstack should have handled it — that's the kind of thing worth filing. Things less consequential than this, ignore. + +**NOT worth filing:** user's app bugs, network errors to user's URL, auth failures on user's site, user's own JS logic bugs. + +**To file:** write `~/.gstack/contributor-logs/{slug}.md` with **all sections below** (do not truncate — include every section through the Date/Version footer): + +``` +# {Title} + +Hey gstack team — ran into this while using /{skill-name}: + +**What I was trying to do:** {what the user/agent was attempting} +**What happened instead:** {what actually happened} +**My rating:** {0-10} — {one sentence on why it wasn't a 10} + +## Steps to reproduce +1. {step} + +## Raw output +``` +{paste the actual error or unexpected output here} +``` + +## What would make this a 10 +{one sentence: what gstack should have done differently} + +**Date:** {YYYY-MM-DD} | **Version:** {gstack version} | **Skill:** /{skill} +``` + +Slug: lowercase, hyphens, max 60 chars (e.g. `browse-js-no-await`). Skip if file already exists. Max 3 reports per session. File inline and continue — don't stop the workflow. Tell user: "Filed gstack field report: {title}" + +# /mastery-init — Bootstrap Mastery in a Project + +You are the project architect. Your job: set up the Mastery development framework so this project has structured documentation, a clear lifecycle, and AI memory across sessions. + +## User-invocable +When the user types `/mastery-init`, run this skill. + +--- + +## Step 1: Check if Mastery already exists + +```bash +_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || echo ".") +ls "$_ROOT"/docs/mastery.md "$_ROOT"/docs/mastery-compact.md "$_ROOT"/docs/project-context.md 2>/dev/null +``` + +**If `docs/mastery.md` already exists:** Use AskUserQuestion: + +> This project already has the Mastery framework installed at `docs/mastery.md`. +> +> RECOMMENDATION: Choose A to check your project status instead. +> +> A) Run /mastery-status instead (check where things stand) +> B) Re-initialize anyway (will overwrite existing docs — destructive) +> C) Cancel + +If A: Tell user to run `/mastery-status`. Stop. +If B: Warn "This will overwrite existing Mastery docs. Proceeding..." and continue. +If C: Stop. + +**If no Mastery docs exist:** Continue to Step 2. + +--- + +## Step 2: Get the framework files + +The Mastery framework consists of two files that go into `docs/`: +- `mastery.md` — Full framework with all 16 templates (~25k tokens) +- `mastery-compact.md` — AI-optimized rules only (~6k tokens) + +```bash +mkdir -p "$_ROOT/docs/features" "$_ROOT/docs/references" +``` + +Use AskUserQuestion: + +> I need to set up the Mastery framework files. The framework is two Markdown files that define your project's development lifecycle. +> +> RECOMMENDATION: Choose A — it's the fastest way to get started. +> +> A) Download from GitHub (fetches latest from github.com/RAiWorks/MASTERY.md) +> B) I already have the files — just tell me where to put them +> C) I'll paste the content manually + +If A: Run: +```bash +curl -sL "https://raw.githubusercontent.com/RAiWorks/MASTERY.md/main/mastery.md" -o "$_ROOT/docs/mastery.md" +curl -sL "https://raw.githubusercontent.com/RAiWorks/MASTERY.md/main/mastery-compact.md" -o "$_ROOT/docs/mastery-compact.md" +echo "Downloaded mastery.md and mastery-compact.md to docs/" +``` +Verify the downloads aren't empty. If curl fails, tell the user to download manually from `https://github.com/RAiWorks/MASTERY.md` and place files in `docs/`. + +If B: Tell user to place `mastery.md` and `mastery-compact.md` in the project's `docs/` folder. Wait for confirmation, then verify the files exist. + +If C: Create placeholder files and tell user to paste content into them. + +--- + +## Step 3: Run the project discussion + +Read `docs/mastery-compact.md` to understand the framework rules (context loading order). + +Now start the project discussion. Use AskUserQuestion: + +> Let's discuss your project. I need to understand what you're building so I can set up the right documentation structure. +> +> RECOMMENDATION: Answer all questions — this becomes your project's permanent memory. +> +> Tell me about your project: +> 1. What is it? (one sentence) +> 2. Why does it exist? (problem it solves) +> 3. Who is it for? (target users) +> 4. What tech stack? (language, framework, database, etc.) +> 5. What are the first 3-5 features you want to build? + +After the user responds, create `docs/project-discussion.md` with the full discussion content. Use the template structure from mastery.md — search for "### 4. Discussion Document" in `docs/mastery.md` to get the template. + +Mark the discussion status as `> **Status**: ✅ COMPLETE` at the top. + +--- + +## Step 4: Create project-context.md + +Distill the discussion into `docs/project-context.md`. Search for "### 5. Project Context" in `docs/mastery.md` for the template. + +Key fields to fill: +- Project name, version (start at 0.1.0), description +- Project type, tech stack, architecture style +- Key decisions table (from the discussion) + +Use AskUserQuestion to confirm: + +> Here's a summary of your project identity. Does this look right? +> +> **{Project Name}** — {one-line description} +> **Stack**: {tech stack} +> **Type**: {project type} +> +> RECOMMENDATION: Choose A if the summary is accurate. +> +> A) Looks good — save it +> B) I want to change something (tell me what) + +--- + +## Step 5: Build the roadmap + +Create `docs/project-roadmap.md`. Search for "### 6. Project Roadmap" in `docs/mastery.md` for the template. + +Use the features from the discussion (Step 3) to build the feature table. Number features starting at 01. All start as 🔴 Not Started except Feature #01 which should be 🟡 In Progress. + +Show the roadmap and confirm with AskUserQuestion: + +> Here's your feature roadmap. I've ordered features by what seems like natural dependency order. +> +> {show the feature table} +> +> RECOMMENDATION: Choose A if the order makes sense. +> +> A) Looks good — save it +> B) I want to reorder or rename features (tell me what) +> C) Add more features first + +--- + +## Step 6: Create AGENTS.md + +Create an `AGENTS.md` file at the project root. This orients AI agents working on the project. Search for "### 12. AGENTS.md" in `docs/mastery.md` for the template. + +Must include: +- Project overview (from context) +- Getting started order (docs to read) +- Key rules (from the framework) +- Conventions (branches, commits, file naming) + +--- + +## Step 7: Create project changelog + +Create `docs/project-changelog.md` with an empty `## [Unreleased]` section. Search for "### 16. Project Changelog" in `docs/mastery.md` for the template. + +--- + +## Step 8: Initial commit + +```bash +cd "$_ROOT" +git add docs/mastery.md docs/mastery-compact.md docs/project-discussion.md docs/project-context.md docs/project-roadmap.md docs/project-changelog.md AGENTS.md +git status +``` + +Use AskUserQuestion: + +> Mastery is set up! Here's what was created: +> +> - `docs/mastery.md` — Framework (full) +> - `docs/mastery-compact.md` — Framework (compact, for AI) +> - `docs/project-discussion.md` — Project discussion +> - `docs/project-context.md` — Project identity +> - `docs/project-roadmap.md` — Feature roadmap +> - `docs/project-changelog.md` — Changelog +> - `AGENTS.md` — AI agent orientation +> +> RECOMMENDATION: Choose A to commit this setup. +> +> A) Commit all files (`docs: initialize Mastery framework`) +> B) Let me review first — don't commit yet +> C) Start Feature #01 immediately (commit + begin first feature) + +If A: `git commit -m "docs: initialize Mastery framework"` +If B: Stop — tell user to review and commit when ready. +If C: Commit, then tell user to run `/mastery-plan` to start planning Feature #01. + +--- + +## Output + +``` +━━━ MASTERY INITIALIZED ━━━━━━━━━━━━━━━━━━━━━━━ + +Project: {name} +Version: 0.1.0 +Features: {N} planned +Next: Feature #01 — {name} + +Files created: + docs/mastery.md + docs/mastery-compact.md + docs/project-discussion.md + docs/project-context.md + docs/project-roadmap.md + docs/project-changelog.md + AGENTS.md + +Run /mastery-plan to start your first feature. + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +--- + +## Edge Cases + +- **Not a git repo**: Run `git init` first, then proceed. Warn user: "Initialized git repo." +- **docs/ already exists with other files**: Don't touch existing files. Only create Mastery docs. +- **User wants minimal setup**: If they say "skip discussion" or "just the skeleton", create the folder structure and empty template files. Mark discussion as IN PROGRESS. +- **Monorepo**: Ask which subdirectory to initialize. Create docs/ there, not at repo root. diff --git a/mastery-init/SKILL.md.tmpl b/mastery-init/SKILL.md.tmpl new file mode 100644 index 00000000..ef08984c --- /dev/null +++ b/mastery-init/SKILL.md.tmpl @@ -0,0 +1,236 @@ +--- +name: mastery-init +version: 1.0.0 +description: | + Set up the Mastery development framework in any project. Creates the docs/ + skeleton, runs the project discussion, formalizes context, and builds the + roadmap. Turns a blank repo into a structured project with AI memory. +allowed-tools: + - Bash + - Read + - Write + - Edit + - Glob + - Grep + - AskUserQuestion +--- + +{{PREAMBLE}} + +# /mastery-init — Bootstrap Mastery in a Project + +You are the project architect. Your job: set up the Mastery development framework so this project has structured documentation, a clear lifecycle, and AI memory across sessions. + +## User-invocable +When the user types `/mastery-init`, run this skill. + +--- + +## Step 1: Check if Mastery already exists + +```bash +_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || echo ".") +ls "$_ROOT"/docs/mastery.md "$_ROOT"/docs/mastery-compact.md "$_ROOT"/docs/project-context.md 2>/dev/null +``` + +**If `docs/mastery.md` already exists:** Use AskUserQuestion: + +> This project already has the Mastery framework installed at `docs/mastery.md`. +> +> RECOMMENDATION: Choose A to check your project status instead. +> +> A) Run /mastery-status instead (check where things stand) +> B) Re-initialize anyway (will overwrite existing docs — destructive) +> C) Cancel + +If A: Tell user to run `/mastery-status`. Stop. +If B: Warn "This will overwrite existing Mastery docs. Proceeding..." and continue. +If C: Stop. + +**If no Mastery docs exist:** Continue to Step 2. + +--- + +## Step 2: Get the framework files + +The Mastery framework consists of two files that go into `docs/`: +- `mastery.md` — Full framework with all 16 templates (~25k tokens) +- `mastery-compact.md` — AI-optimized rules only (~6k tokens) + +```bash +mkdir -p "$_ROOT/docs/features" "$_ROOT/docs/references" +``` + +Use AskUserQuestion: + +> I need to set up the Mastery framework files. The framework is two Markdown files that define your project's development lifecycle. +> +> RECOMMENDATION: Choose A — it's the fastest way to get started. +> +> A) Download from GitHub (fetches latest from github.com/RAiWorks/MASTERY.md) +> B) I already have the files — just tell me where to put them +> C) I'll paste the content manually + +If A: Run: +```bash +curl -sL "https://raw.githubusercontent.com/RAiWorks/MASTERY.md/main/mastery.md" -o "$_ROOT/docs/mastery.md" +curl -sL "https://raw.githubusercontent.com/RAiWorks/MASTERY.md/main/mastery-compact.md" -o "$_ROOT/docs/mastery-compact.md" +echo "Downloaded mastery.md and mastery-compact.md to docs/" +``` +Verify the downloads aren't empty. If curl fails, tell the user to download manually from `https://github.com/RAiWorks/MASTERY.md` and place files in `docs/`. + +If B: Tell user to place `mastery.md` and `mastery-compact.md` in the project's `docs/` folder. Wait for confirmation, then verify the files exist. + +If C: Create placeholder files and tell user to paste content into them. + +--- + +## Step 3: Run the project discussion + +Read `docs/mastery-compact.md` to understand the framework rules (context loading order). + +Now start the project discussion. Use AskUserQuestion: + +> Let's discuss your project. I need to understand what you're building so I can set up the right documentation structure. +> +> RECOMMENDATION: Answer all questions — this becomes your project's permanent memory. +> +> Tell me about your project: +> 1. What is it? (one sentence) +> 2. Why does it exist? (problem it solves) +> 3. Who is it for? (target users) +> 4. What tech stack? (language, framework, database, etc.) +> 5. What are the first 3-5 features you want to build? + +After the user responds, create `docs/project-discussion.md` with the full discussion content. Use the template structure from mastery.md — search for "### 4. Discussion Document" in `docs/mastery.md` to get the template. + +Mark the discussion status as `> **Status**: ✅ COMPLETE` at the top. + +--- + +## Step 4: Create project-context.md + +Distill the discussion into `docs/project-context.md`. Search for "### 5. Project Context" in `docs/mastery.md` for the template. + +Key fields to fill: +- Project name, version (start at 0.1.0), description +- Project type, tech stack, architecture style +- Key decisions table (from the discussion) + +Use AskUserQuestion to confirm: + +> Here's a summary of your project identity. Does this look right? +> +> **{Project Name}** — {one-line description} +> **Stack**: {tech stack} +> **Type**: {project type} +> +> RECOMMENDATION: Choose A if the summary is accurate. +> +> A) Looks good — save it +> B) I want to change something (tell me what) + +--- + +## Step 5: Build the roadmap + +Create `docs/project-roadmap.md`. Search for "### 6. Project Roadmap" in `docs/mastery.md` for the template. + +Use the features from the discussion (Step 3) to build the feature table. Number features starting at 01. All start as 🔴 Not Started except Feature #01 which should be 🟡 In Progress. + +Show the roadmap and confirm with AskUserQuestion: + +> Here's your feature roadmap. I've ordered features by what seems like natural dependency order. +> +> {show the feature table} +> +> RECOMMENDATION: Choose A if the order makes sense. +> +> A) Looks good — save it +> B) I want to reorder or rename features (tell me what) +> C) Add more features first + +--- + +## Step 6: Create AGENTS.md + +Create an `AGENTS.md` file at the project root. This orients AI agents working on the project. Search for "### 12. AGENTS.md" in `docs/mastery.md` for the template. + +Must include: +- Project overview (from context) +- Getting started order (docs to read) +- Key rules (from the framework) +- Conventions (branches, commits, file naming) + +--- + +## Step 7: Create project changelog + +Create `docs/project-changelog.md` with an empty `## [Unreleased]` section. Search for "### 16. Project Changelog" in `docs/mastery.md` for the template. + +--- + +## Step 8: Initial commit + +```bash +cd "$_ROOT" +git add docs/mastery.md docs/mastery-compact.md docs/project-discussion.md docs/project-context.md docs/project-roadmap.md docs/project-changelog.md AGENTS.md +git status +``` + +Use AskUserQuestion: + +> Mastery is set up! Here's what was created: +> +> - `docs/mastery.md` — Framework (full) +> - `docs/mastery-compact.md` — Framework (compact, for AI) +> - `docs/project-discussion.md` — Project discussion +> - `docs/project-context.md` — Project identity +> - `docs/project-roadmap.md` — Feature roadmap +> - `docs/project-changelog.md` — Changelog +> - `AGENTS.md` — AI agent orientation +> +> RECOMMENDATION: Choose A to commit this setup. +> +> A) Commit all files (`docs: initialize Mastery framework`) +> B) Let me review first — don't commit yet +> C) Start Feature #01 immediately (commit + begin first feature) + +If A: `git commit -m "docs: initialize Mastery framework"` +If B: Stop — tell user to review and commit when ready. +If C: Commit, then tell user to run `/mastery-plan` to start planning Feature #01. + +--- + +## Output + +``` +━━━ MASTERY INITIALIZED ━━━━━━━━━━━━━━━━━━━━━━━ + +Project: {name} +Version: 0.1.0 +Features: {N} planned +Next: Feature #01 — {name} + +Files created: + docs/mastery.md + docs/mastery-compact.md + docs/project-discussion.md + docs/project-context.md + docs/project-roadmap.md + docs/project-changelog.md + AGENTS.md + +Run /mastery-plan to start your first feature. + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +--- + +## Edge Cases + +- **Not a git repo**: Run `git init` first, then proceed. Warn user: "Initialized git repo." +- **docs/ already exists with other files**: Don't touch existing files. Only create Mastery docs. +- **User wants minimal setup**: If they say "skip discussion" or "just the skeleton", create the folder structure and empty template files. Mark discussion as IN PROGRESS. +- **Monorepo**: Ask which subdirectory to initialize. Create docs/ there, not at repo root. diff --git a/mastery-plan/SKILL.md b/mastery-plan/SKILL.md new file mode 100644 index 00000000..ffa53ffe --- /dev/null +++ b/mastery-plan/SKILL.md @@ -0,0 +1,356 @@ +--- +name: mastery-plan +version: 1.0.0 +description: | + Create feature planning docs for a Mastery project. Walks through the full + Discuss → Design → Plan flow: writes the discussion doc, architecture doc, + tasks, and testplan. One command to go from idea to ready-to-build. +allowed-tools: + - Bash + - Read + - Write + - Edit + - Glob + - Grep + - AskUserQuestion +--- + + + + +## 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 -delete 2>/dev/null || true +_CONTRIB=$(~/.claude/skills/gstack/bin/gstack-config get gstack_contributor 2>/dev/null || true) +_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown") +echo "BRANCH: $_BRANCH" +``` + +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 `JUST_UPGRADED `: tell user "Running gstack v{to} (just updated!)" and continue. + +## AskUserQuestion Format + +**ALWAYS follow this structure for every AskUserQuestion call:** +1. **Re-ground:** State the project, the current branch (use the `_BRANCH` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences) +2. **Simplify:** Explain the problem in plain English a smart 16-year-old could follow. No raw function names, no internal jargon, no implementation details. Use concrete examples and analogies. Say what it DOES, not what it's called. +3. **Recommend:** `RECOMMENDATION: Choose [X] because [one-line reason]` +4. **Options:** Lettered options: `A) ... B) ... C) ...` + +Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex. + +Per-skill instructions may add additional formatting rules on top of this baseline. + +## Contributor Mode + +If `_CONTRIB` is `true`: you are in **contributor mode**. You're a gstack user who also helps make it better. + +**At the end of each major workflow step** (not after every single command), reflect on the gstack tooling you used. Rate your experience 0 to 10. If it wasn't a 10, think about why. If there is an obvious, actionable bug OR an insightful, interesting thing that could have been done better by gstack code or skill markdown — file a field report. Maybe our contributor will help make us better! + +**Calibration — this is the bar:** For example, `$B js "await fetch(...)"` used to fail with `SyntaxError: await is only valid in async functions` because gstack didn't wrap expressions in async context. Small, but the input was reasonable and gstack should have handled it — that's the kind of thing worth filing. Things less consequential than this, ignore. + +**NOT worth filing:** user's app bugs, network errors to user's URL, auth failures on user's site, user's own JS logic bugs. + +**To file:** write `~/.gstack/contributor-logs/{slug}.md` with **all sections below** (do not truncate — include every section through the Date/Version footer): + +``` +# {Title} + +Hey gstack team — ran into this while using /{skill-name}: + +**What I was trying to do:** {what the user/agent was attempting} +**What happened instead:** {what actually happened} +**My rating:** {0-10} — {one sentence on why it wasn't a 10} + +## Steps to reproduce +1. {step} + +## Raw output +``` +{paste the actual error or unexpected output here} +``` + +## What would make this a 10 +{one sentence: what gstack should have done differently} + +**Date:** {YYYY-MM-DD} | **Version:** {gstack version} | **Skill:** /{skill} +``` + +Slug: lowercase, hyphens, max 60 chars (e.g. `browse-js-no-await`). Skip if file already exists. Max 3 reports per session. File inline and continue — don't stop the workflow. Tell user: "Filed gstack field report: {title}" + +# /mastery-plan — Plan a Feature from Scratch + +You are the feature planner. Your job: take a feature idea and produce a complete set of planning docs — discussion, architecture, tasks, testplan — so someone (human or AI) can build it without guessing. + +## User-invocable +When the user types `/mastery-plan`, run this skill. + +--- + +## Step 1: Verify this is a Mastery project + +```bash +_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || echo ".") +ls "$_ROOT"/docs/project-roadmap.md "$_ROOT"/docs/mastery-compact.md 2>/dev/null +``` + +**If not a Mastery project:** Use AskUserQuestion: + +> This project doesn't have the Mastery framework set up yet. You need that before planning features. +> +> RECOMMENDATION: Choose A to set it up first. +> +> A) Set up Mastery first (I'll walk you through it) +> B) Cancel + +If A: Tell user to run `/mastery-init`. Stop. +If B: Stop. + +**If Mastery exists:** Read `docs/mastery-compact.md` for framework rules, then continue. + +--- + +## Step 2: Pick the feature + +Read `docs/project-roadmap.md` and extract the feature table. + +Use AskUserQuestion: + +> Here are your planned features: +> +> {list features from roadmap with status emoji} +> +> RECOMMENDATION: Choose the next 🔴 Not Started feature, or describe a new one. +> +> A) Start planning Feature #{next 🔴 number} — {name} +> B) I want to plan a different feature (tell me which number) +> C) New feature not on the roadmap yet (describe it) + +If C: Ask user to describe the feature. Assign the next available number. Add it to `docs/project-roadmap.md` as 🟡 In Progress using Edit tool. + +For A or B: Update the chosen feature to 🟡 In Progress in the roadmap using Edit tool. + +Note the feature number (XX) and name for folder creation. + +--- + +## Step 3: Create the feature branch + +```bash +FEATURE_NUM={XX} +FEATURE_SLUG={kebab-case-name} +BRANCH="feature/${FEATURE_NUM}-${FEATURE_SLUG}" +git checkout -b "$BRANCH" +echo "Created branch: $BRANCH" +``` + +Create the feature folder: + +```bash +mkdir -p "$_ROOT/docs/features/$(printf '%02d' $FEATURE_NUM)-${FEATURE_SLUG}" +``` + +--- + +## Step 4: Write the discussion doc + +This is a structured conversation about the feature. Use AskUserQuestion: + +> Let's discuss Feature #{XX} — {name}. +> +> Tell me everything about this feature: +> 1. What does it do? (user-facing behavior) +> 2. Why do we need it? (problem it solves) +> 3. Any technical constraints? (must use X, can't touch Y) +> 4. How will we know it's done? (acceptance criteria) +> 5. Any open questions? (things you're not sure about) +> +> RECOMMENDATION: Be thorough — this becomes the permanent record of WHY this feature exists. + +After the user responds, create `docs/features/{XX}-{name}/discussion.md`. Load the template from `docs/mastery.md` — search for "### 4. Discussion Document". + +Fill in: +- Feature name and number +- The conversation content organized into sections +- Open questions (if any) +- Decision log (capture any decisions made during the discussion) + +If the user has open questions, work through them one at a time with AskUserQuestion. Each question gets its own ask — never batch. + +Mark status: `> **Status**: ✅ COMPLETE` when all questions are resolved. + +--- + +## Step 5: Write the architecture doc + +Read the discussion doc for context. Create `docs/features/{XX}-{name}/architecture.md`. Load the template from `docs/mastery.md` — search for "### 7. Architecture Document". + +Fill in: +- Overview (what and why, from discussion) +- File structure (what files will be created or modified) +- Component design (key components and their responsibilities) +- Data flow (how data moves through the system) +- Trade-offs table (alternatives considered, pros/cons, verdict) + +Use AskUserQuestion to present the architecture: + +> Here's the proposed architecture for Feature #{XX}: +> +> **Approach**: {one-sentence summary} +> **Files touched**: {list} +> **Key trade-off**: {main decision and why} +> +> RECOMMENDATION: Choose A if the design makes sense. +> +> A) Looks good — finalize this architecture +> B) I want to change the approach (tell me what) +> C) I have concerns about {specific aspect} + +Mark status: `> **Status**: 🟢 FINALIZED` when approved. + +--- + +## Step 6: Write the tasks doc + +Read the architecture doc for context. Create `docs/features/{XX}-{name}/tasks.md`. Load the template from `docs/mastery.md` — search for "### 8. Tasks Document". + +Break the architecture into implementation phases with checkboxed tasks: + +```markdown +## Phase A — {name} +- [ ] **A.1** — {specific, implementable task} +- [ ] **A.2** — {next task} + +## Phase B — {name} +- [ ] **B.1** — {task} +``` + +Rules: +- Every task must be specific enough to implement without asking questions +- Tasks are ordered by dependency (later tasks can depend on earlier ones) +- Each phase groups related work +- Include a prerequisites section at the top + +Show the task list to the user with AskUserQuestion: + +> Here's the implementation plan — {N} tasks across {M} phases: +> +> {show phases and tasks} +> +> RECOMMENDATION: Choose A if the breakdown is actionable. +> +> A) Looks good — save it +> B) Too granular — combine some tasks +> C) Not detailed enough — break down {specific task} +> D) Missing something — I need to add {what} + +--- + +## Step 7: Write the testplan doc + +Create `docs/features/{XX}-{name}/testplan.md`. Load the template from `docs/mastery.md` — search for "### 9. Test Plan Document". + +Generate test cases that cover: +- Happy path for each major task +- Edge cases from the architecture's trade-offs +- Error/failure scenarios +- Integration points (if any) + +Format: + +```markdown +| TC ID | Description | Steps | Expected | Status | +|-------|-------------|-------|----------|--------| +| TC-01 | {test name} | {steps} | {expected result} | ⬜ | +``` + +--- + +## Step 8: Create the changelog doc + +Create `docs/features/{XX}-{name}/changelog.md`. Load the template from `docs/mastery.md` — search for "### 11. Feature Changelog". + +Add a session note: + +```markdown +### Session Note — {today's date} +- **Who**: AI Agent + Developer +- **Duration**: ~1 session +- **Worked On**: Created all planning docs (discussion, architecture, tasks, testplan) +- **Stopped At**: Planning complete — ready for Build stage +- **Blockers**: None +- **Next Steps**: Start Phase A implementation +``` + +--- + +## Step 9: Commit and push + +```bash +cd "$_ROOT" +git add docs/features/$(printf '%02d' $FEATURE_NUM)-*/ +git add docs/project-roadmap.md +git status +``` + +Use AskUserQuestion: + +> Feature #{XX} planning is complete! All docs created: +> +> - `discussion.md` — ✅ COMPLETE +> - `architecture.md` — 🟢 FINALIZED +> - `tasks.md` — {N} tasks across {M} phases +> - `testplan.md` — {N} test cases +> - `changelog.md` — Session note logged +> +> RECOMMENDATION: Choose A to commit and push. +> +> A) Commit and push to feature branch +> B) Let me review first — don't commit +> C) Start building immediately (commit + begin Phase A) + +If A: +```bash +git commit -m "docs(feature-{XX}): complete planning docs for {feature-name}" +git push -u origin "$BRANCH" +``` + +If C: Commit, push, then tell user: "Start implementing Phase A, Task A.1." + +--- + +## Output + +``` +━━━ FEATURE PLANNED ━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +Feature: #{XX} — {name} +Branch: feature/{XX}-{slug} +Stage: Plan → Build (ready) + +Documents: + discussion.md ✅ COMPLETE + architecture.md 🟢 FINALIZED + tasks.md {N} tasks, {M} phases + testplan.md {N} test cases + changelog.md Session note logged + +Next: Start Phase A — {first task description} + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +--- + +## Edge Cases + +- **Feature already has some docs**: Read existing docs and skip those steps. Only create what's missing. +- **User wants lightweight feature**: If the feature is trivial (docs-only, config change, < 1 hour), suggest using `lightweight.md` instead. Create a single combined doc per Mastery's lightweight variant rules. +- **Multiple features in progress**: Warn user: "You already have {N} features in progress. Consider finishing one first." But don't block — they may have good reasons. +- **No git**: Warn but continue. Skip branch creation and commit steps. +- **Architecture debate**: If user goes back and forth on the architecture, keep the discussion doc updated with the decision log. Don't finalize architecture until user explicitly approves. diff --git a/mastery-plan/SKILL.md.tmpl b/mastery-plan/SKILL.md.tmpl new file mode 100644 index 00000000..73a7fcb4 --- /dev/null +++ b/mastery-plan/SKILL.md.tmpl @@ -0,0 +1,290 @@ +--- +name: mastery-plan +version: 1.0.0 +description: | + Create feature planning docs for a Mastery project. Walks through the full + Discuss → Design → Plan flow: writes the discussion doc, architecture doc, + tasks, and testplan. One command to go from idea to ready-to-build. +allowed-tools: + - Bash + - Read + - Write + - Edit + - Glob + - Grep + - AskUserQuestion +--- + +{{PREAMBLE}} + +# /mastery-plan — Plan a Feature from Scratch + +You are the feature planner. Your job: take a feature idea and produce a complete set of planning docs — discussion, architecture, tasks, testplan — so someone (human or AI) can build it without guessing. + +## User-invocable +When the user types `/mastery-plan`, run this skill. + +--- + +## Step 1: Verify this is a Mastery project + +```bash +_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || echo ".") +ls "$_ROOT"/docs/project-roadmap.md "$_ROOT"/docs/mastery-compact.md 2>/dev/null +``` + +**If not a Mastery project:** Use AskUserQuestion: + +> This project doesn't have the Mastery framework set up yet. You need that before planning features. +> +> RECOMMENDATION: Choose A to set it up first. +> +> A) Set up Mastery first (I'll walk you through it) +> B) Cancel + +If A: Tell user to run `/mastery-init`. Stop. +If B: Stop. + +**If Mastery exists:** Read `docs/mastery-compact.md` for framework rules, then continue. + +--- + +## Step 2: Pick the feature + +Read `docs/project-roadmap.md` and extract the feature table. + +Use AskUserQuestion: + +> Here are your planned features: +> +> {list features from roadmap with status emoji} +> +> RECOMMENDATION: Choose the next 🔴 Not Started feature, or describe a new one. +> +> A) Start planning Feature #{next 🔴 number} — {name} +> B) I want to plan a different feature (tell me which number) +> C) New feature not on the roadmap yet (describe it) + +If C: Ask user to describe the feature. Assign the next available number. Add it to `docs/project-roadmap.md` as 🟡 In Progress using Edit tool. + +For A or B: Update the chosen feature to 🟡 In Progress in the roadmap using Edit tool. + +Note the feature number (XX) and name for folder creation. + +--- + +## Step 3: Create the feature branch + +```bash +FEATURE_NUM={XX} +FEATURE_SLUG={kebab-case-name} +BRANCH="feature/${FEATURE_NUM}-${FEATURE_SLUG}" +git checkout -b "$BRANCH" +echo "Created branch: $BRANCH" +``` + +Create the feature folder: + +```bash +mkdir -p "$_ROOT/docs/features/$(printf '%02d' $FEATURE_NUM)-${FEATURE_SLUG}" +``` + +--- + +## Step 4: Write the discussion doc + +This is a structured conversation about the feature. Use AskUserQuestion: + +> Let's discuss Feature #{XX} — {name}. +> +> Tell me everything about this feature: +> 1. What does it do? (user-facing behavior) +> 2. Why do we need it? (problem it solves) +> 3. Any technical constraints? (must use X, can't touch Y) +> 4. How will we know it's done? (acceptance criteria) +> 5. Any open questions? (things you're not sure about) +> +> RECOMMENDATION: Be thorough — this becomes the permanent record of WHY this feature exists. + +After the user responds, create `docs/features/{XX}-{name}/discussion.md`. Load the template from `docs/mastery.md` — search for "### 4. Discussion Document". + +Fill in: +- Feature name and number +- The conversation content organized into sections +- Open questions (if any) +- Decision log (capture any decisions made during the discussion) + +If the user has open questions, work through them one at a time with AskUserQuestion. Each question gets its own ask — never batch. + +Mark status: `> **Status**: ✅ COMPLETE` when all questions are resolved. + +--- + +## Step 5: Write the architecture doc + +Read the discussion doc for context. Create `docs/features/{XX}-{name}/architecture.md`. Load the template from `docs/mastery.md` — search for "### 7. Architecture Document". + +Fill in: +- Overview (what and why, from discussion) +- File structure (what files will be created or modified) +- Component design (key components and their responsibilities) +- Data flow (how data moves through the system) +- Trade-offs table (alternatives considered, pros/cons, verdict) + +Use AskUserQuestion to present the architecture: + +> Here's the proposed architecture for Feature #{XX}: +> +> **Approach**: {one-sentence summary} +> **Files touched**: {list} +> **Key trade-off**: {main decision and why} +> +> RECOMMENDATION: Choose A if the design makes sense. +> +> A) Looks good — finalize this architecture +> B) I want to change the approach (tell me what) +> C) I have concerns about {specific aspect} + +Mark status: `> **Status**: 🟢 FINALIZED` when approved. + +--- + +## Step 6: Write the tasks doc + +Read the architecture doc for context. Create `docs/features/{XX}-{name}/tasks.md`. Load the template from `docs/mastery.md` — search for "### 8. Tasks Document". + +Break the architecture into implementation phases with checkboxed tasks: + +```markdown +## Phase A — {name} +- [ ] **A.1** — {specific, implementable task} +- [ ] **A.2** — {next task} + +## Phase B — {name} +- [ ] **B.1** — {task} +``` + +Rules: +- Every task must be specific enough to implement without asking questions +- Tasks are ordered by dependency (later tasks can depend on earlier ones) +- Each phase groups related work +- Include a prerequisites section at the top + +Show the task list to the user with AskUserQuestion: + +> Here's the implementation plan — {N} tasks across {M} phases: +> +> {show phases and tasks} +> +> RECOMMENDATION: Choose A if the breakdown is actionable. +> +> A) Looks good — save it +> B) Too granular — combine some tasks +> C) Not detailed enough — break down {specific task} +> D) Missing something — I need to add {what} + +--- + +## Step 7: Write the testplan doc + +Create `docs/features/{XX}-{name}/testplan.md`. Load the template from `docs/mastery.md` — search for "### 9. Test Plan Document". + +Generate test cases that cover: +- Happy path for each major task +- Edge cases from the architecture's trade-offs +- Error/failure scenarios +- Integration points (if any) + +Format: + +```markdown +| TC ID | Description | Steps | Expected | Status | +|-------|-------------|-------|----------|--------| +| TC-01 | {test name} | {steps} | {expected result} | ⬜ | +``` + +--- + +## Step 8: Create the changelog doc + +Create `docs/features/{XX}-{name}/changelog.md`. Load the template from `docs/mastery.md` — search for "### 11. Feature Changelog". + +Add a session note: + +```markdown +### Session Note — {today's date} +- **Who**: AI Agent + Developer +- **Duration**: ~1 session +- **Worked On**: Created all planning docs (discussion, architecture, tasks, testplan) +- **Stopped At**: Planning complete — ready for Build stage +- **Blockers**: None +- **Next Steps**: Start Phase A implementation +``` + +--- + +## Step 9: Commit and push + +```bash +cd "$_ROOT" +git add docs/features/$(printf '%02d' $FEATURE_NUM)-*/ +git add docs/project-roadmap.md +git status +``` + +Use AskUserQuestion: + +> Feature #{XX} planning is complete! All docs created: +> +> - `discussion.md` — ✅ COMPLETE +> - `architecture.md` — 🟢 FINALIZED +> - `tasks.md` — {N} tasks across {M} phases +> - `testplan.md` — {N} test cases +> - `changelog.md` — Session note logged +> +> RECOMMENDATION: Choose A to commit and push. +> +> A) Commit and push to feature branch +> B) Let me review first — don't commit +> C) Start building immediately (commit + begin Phase A) + +If A: +```bash +git commit -m "docs(feature-{XX}): complete planning docs for {feature-name}" +git push -u origin "$BRANCH" +``` + +If C: Commit, push, then tell user: "Start implementing Phase A, Task A.1." + +--- + +## Output + +``` +━━━ FEATURE PLANNED ━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +Feature: #{XX} — {name} +Branch: feature/{XX}-{slug} +Stage: Plan → Build (ready) + +Documents: + discussion.md ✅ COMPLETE + architecture.md 🟢 FINALIZED + tasks.md {N} tasks, {M} phases + testplan.md {N} test cases + changelog.md Session note logged + +Next: Start Phase A — {first task description} + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +--- + +## Edge Cases + +- **Feature already has some docs**: Read existing docs and skip those steps. Only create what's missing. +- **User wants lightweight feature**: If the feature is trivial (docs-only, config change, < 1 hour), suggest using `lightweight.md` instead. Create a single combined doc per Mastery's lightweight variant rules. +- **Multiple features in progress**: Warn user: "You already have {N} features in progress. Consider finishing one first." But don't block — they may have good reasons. +- **No git**: Warn but continue. Skip branch creation and commit steps. +- **Architecture debate**: If user goes back and forth on the architecture, keep the discussion doc updated with the decision log. Don't finalize architecture until user explicitly approves. diff --git a/scripts/gen-skill-docs.ts b/scripts/gen-skill-docs.ts index 81d59f4b..331e0556 100644 --- a/scripts/gen-skill-docs.ts +++ b/scripts/gen-skill-docs.ts @@ -539,6 +539,9 @@ function findTemplates(): string[] { path.join(ROOT, 'plan-eng-review', 'SKILL.md.tmpl'), path.join(ROOT, 'retro', 'SKILL.md.tmpl'), path.join(ROOT, 'mastery-status', 'SKILL.md.tmpl'), + path.join(ROOT, 'mastery-init', 'SKILL.md.tmpl'), + path.join(ROOT, 'mastery-plan', 'SKILL.md.tmpl'), + path.join(ROOT, 'mastery-handoff', 'SKILL.md.tmpl'), path.join(ROOT, 'gstack-upgrade', 'SKILL.md.tmpl'), path.join(ROOT, 'document-release', 'SKILL.md.tmpl'), ];