fix(code-review): address review findings in step-01 intent cascade

- Set {spec_file} immediately in Tier 1 when spec provided
- Add staged/uncommitted handlers to instruction 3 dispatch table
- Replace undefined {branch}/{sha} placeholders with angle brackets
- Fix {story_key} vs {{story-id}} placeholder mismatch
- Correct "wants reviewed" grammar to "wants to be reviewed"

CONTRIBUTING.md

@@ -6,6 +6,12 @@ Thank you for considering contributing! We believe in **Human Amplification, Not
 
 ---
 
+> **Before you write code: talk to us on [Discord](https://discord.gg/gk8jAdXWmj).**
+>
+> If your change adds features, restructures code, or touches more than a couple of files, **confirm with a maintainer that it fits**. A large PR out of the blue has a high chance of being closed — regardless of effort invested. A five-minute conversation can save you hours.
+
+---
+
 ## Our Philosophy
 
 BMad strengthens human-AI collaboration through specialized agents and guided workflows. Every contribution should answer: **"Does this make humans and AI better together?"**
@@ -57,15 +63,10 @@ After searching, use the [feature request template](https://github.com/bmad-code
 
 ## Before Starting Work
 
-⚠️ **Required before submitting PRs:**
-
 | Work Type               | Requirement                                              |
-| ------------- | ---------------------------------------------- |
+| ----------------------- | -------------------------------------------------------- |
-| Bug fix       | An open issue (create one if it doesn't exist) |
+| Typo / small bug fix    | Just open the PR                                         |
-| Feature       | An open feature request issue                  |
+| Feature or large change | Confirm with a maintainer on Discord **before** you start |
-| Large changes | Discussion via issue first                     |
-
-**Why?** This prevents wasted effort on work that may not align with project direction.
 
 ---
 
@@ -83,6 +84,12 @@ Submit PRs to the `main` branch. We use trunk-based development. Every push to `
 
 If your change exceeds 800 lines, break it into smaller PRs that can be reviewed independently.
 
+### AI-Generated Code
+
+Given the nature of this project, we expect most contributions involve AI assistance — that's fine. What we require is **heavy human curation**. You must understand every line you're submitting, have made deliberate choices about what to include, and be able to explain your reasoning.
+
+We will reject PRs that read like raw LLM output: bulk refactors nobody asked for, unsolicited "improvements" across many files, or changes where the submitter clearly hasn't read the existing code. Using AI to write code is normal here; using AI as a substitute for thinking is not.
+
 ### New to Pull Requests?
 
 1. **Fork** the repository

src/bmm-skills/4-implementation/bmad-code-review/steps/step-01-gather-context.md

@@ -15,18 +15,37 @@ story_key: '' # set at runtime when discovered from sprint status
 
 ## INSTRUCTIONS
 
-1. **Detect review intent from invocation text.** Check the triggering prompt for phrases that map to a review mode:
+1. **Find the review target.** The conversation context before this skill was triggered IS your starting point — not a blank slate. Check in this order — stop as soon as the review target is identified:
+
+   **Tier 1 — Explicit argument.**
+   Did the user pass a PR, commit SHA, branch, spec file, or diff source this message?
+   - PR reference → resolve to branch/commit via `gh pr view`. If resolution fails, ask for a SHA or branch.
+   - Commit or branch → use directly.
+   - Spec file → set `{spec_file}` to the provided path. Check its frontmatter for `baseline_commit`. If found, use as diff baseline. If not found, continue the cascade (a spec alone does not identify a diff source).
+   - Also scan the argument for diff-mode keywords that narrow the scope:
      - "staged" / "staged changes" → Staged changes only
      - "uncommitted" / "working tree" / "all changes" → Uncommitted changes (staged + unstaged)
-   - "branch diff" / "vs main" / "against main" / "compared to {branch}" → Branch diff (extract base branch if mentioned)
+     - "branch diff" / "vs main" / "against main" / "compared to <branch>" → Branch diff (extract base branch if mentioned)
-   - "commit range" / "last N commits" / "{sha}..{sha}" → Specific commit range
+     - "commit range" / "last N commits" / "<from-sha>..<to-sha>" → Specific commit range
      - "this diff" / "provided diff" / "paste" → User-provided diff (do not match bare "diff" — it appears in other modes)
-   - When multiple phrases match, prefer the most specific match (e.g., "branch diff" over bare "diff").
+   - When multiple keywords match, prefer the most specific (e.g., "branch diff" over bare "diff").
-   - **If a clear match is found:** Announce the detected mode (e.g., "Detected intent: review staged changes only") and proceed directly to constructing `{diff_output}` using the corresponding sub-case from instruction 3. Skip to instruction 4 (spec question).
+
-   - **If no match from invocation text, check sprint tracking.** Look for a sprint status file (`*sprint-status*`) in `{implementation_artifacts}` or `{planning_artifacts}`. If found, scan for any story with status `review`. Handle as follows:
+   **Tier 2 — Recent conversation.**
-     - **Exactly one `review` story:** Set `{story_key}` to the story's key (e.g., `1-2-user-auth`). Suggest it: "I found story {{story-id}} in `review` status. Would you like to review its changes? [Y] Yes / [N] No, let me choose". If confirmed, use the story context to determine the diff source (branch name derived from story slug, or uncommitted changes). If declined, clear `{story_key}` and fall through to instruction 2.
+   Do the last few messages reveal what the user wants to be reviewed? Look for spec paths, commit refs, branches, PRs, or descriptions of a change. Apply the same diff-mode keyword scan and routing as Tier 1.
-     - **Multiple `review` stories:** Present them as numbered options alongside a manual choice option. Wait for user selection. If the user selects a story, set `{story_key}` to the selected story's key and use the selected story's context to determine the diff source as in the single-story case above, and proceed to instruction 3. If the user selects the manual choice, clear `{story_key}` and fall through to instruction 2.
+
-   - **If no match and no sprint tracking:** Fall through to instruction 2.
+   **Tier 3 — Sprint tracking.**
+   Look for a sprint status file (`*sprint-status*`) in `{implementation_artifacts}` or `{planning_artifacts}`. If found, scan for stories with status `review`:
+   - **Exactly one `review` story:** Set `{story_key}` to the story's key (e.g., `1-2-user-auth`). Suggest it: "I found story <story-id> in `review` status. Would you like to review its changes? [Y] Yes / [N] No, let me choose". If confirmed, use the story context to determine the diff source (branch name derived from story slug, or uncommitted changes). If declined, clear `{story_key}` and fall through.
+   - **Multiple `review` stories:** Present them as numbered options alongside a manual choice option. Wait for user selection. If a story is selected, set `{story_key}` and use its context to determine the diff source. If manual choice is selected, clear `{story_key}` and fall through.
+   - **None:** Fall through.
+
+   **Tier 4 — Current git state.**
+   If version control is unavailable, skip to Tier 5. Otherwise, check the current branch and HEAD. If the branch is not `main` (or the default branch), confirm: "I see HEAD is `<short-sha>` on `<branch>` — do you want to review this branch's changes?" If confirmed, treat as a branch diff against `main`. If declined, fall through.
+
+   **Tier 5 — Ask.**
+   Fall through to instruction 2.
+
+   Never ask extra questions beyond what the cascade prescribes. If a tier above already identified the target, skip the remaining tiers and proceed to instruction 3 (construct diff).
 
 2. HALT. Ask the user: **What do you want to review?** Present these options:
    - **Uncommitted changes** (staged + unstaged)
@@ -36,13 +55,17 @@ story_key: '' # set at runtime when discovered from sprint status
    - **Provided diff or file list** (user pastes or provides a path)
 
 3. Construct `{diff_output}` from the chosen source.
+   - For **staged changes only**: run `git diff --cached`.
+   - For **uncommitted changes** (staged + unstaged): run `git diff HEAD`.
    - For **branch diff**: verify the base branch exists before running `git diff`. If it does not exist, HALT and ask the user for a valid branch.
    - For **commit range**: verify the range resolves. If it does not, HALT and ask the user for a valid range.
    - For **provided diff**: validate the content is non-empty and parseable as a unified diff. If it is not parseable, HALT and ask the user to provide a valid diff.
    - For **file list**: validate each path exists in the working tree. Construct `{diff_output}` by running `git diff HEAD -- <path1> <path2> ...`. If any paths are untracked (new files not yet staged), use `git diff --no-index /dev/null <path>` to include them. If the diff is empty (files have no uncommitted changes and are not untracked), ask the user whether to review the full file contents or to specify a different baseline.
    - After constructing `{diff_output}`, verify it is non-empty regardless of source type. If empty, HALT and tell the user there is nothing to review.
 
-4. Ask the user: **Is there a spec or story file that provides context for these changes?**
+4. **Set the spec context.**
+   - If `{spec_file}` is already set (from Tier 1 or Tier 2): verify the file exists and is readable, then set `{review_mode}` = `"full"`.
+   - Otherwise, ask the user: **Is there a spec or story file that provides context for these changes?**
      - If yes: set `{spec_file}` to the path provided, verify the file exists and is readable, then set `{review_mode}` = `"full"`.
      - If no: set `{review_mode}` = `"no-spec"`.
 

website/astro.config.mjs

@@ -119,6 +119,20 @@ export default defineConfig({
           autogenerate: { directory: 'reference' },
         },
         // TEA docs moved to standalone module site; keep BMM sidebar focused.
+        {
+          label: 'BMad Ecosystem',
+          collapsed: false,
+          items: [
+            { label: 'BMad Builder', link: 'https://bmad-builder-docs.bmad-method.org/', attrs: { target: '_blank' } },
+            { label: 'Creative Intelligence Suite', link: 'https://cis-docs.bmad-method.org/', attrs: { target: '_blank' } },
+            { label: 'Game Dev Studio', link: 'https://game-dev-studio-docs.bmad-method.org/', attrs: { target: '_blank' } },
+            {
+              label: 'Test Architect (TEA)',
+              link: 'https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/',
+              attrs: { target: '_blank' },
+            },
+          ],
+        },
       ],
 
       // Credits in footer

website/src/components/Banner.astro

@@ -7,9 +7,13 @@ const llmsFullUrl = `${getSiteUrl()}/llms-full.txt`;
 <div class="ai-banner" role="note" aria-label="AI documentation notice">
   <span>🤖 Consolidated, AI-optimized BMAD docs: <a href={llmsFullUrl}>llms-full.txt</a>. Fetch this plain text file for complete context.</span>
 </div>
+<div class="announce-banner" role="note" aria-label="BMad Builder announcement">
+  <span>🚀 Build your own BMad modules and share them with the community! <a href="https://bmad-builder-docs.bmad-method.org/tutorials/build-your-first-module/">Get started</a> or <a href="https://bmad-builder-docs.bmad-method.org/how-to/distribute-your-module/">submit to the marketplace</a>.</span>
+</div>
 
 <style>
-  .ai-banner {
+  .ai-banner,
+  .announce-banner {
     width: 100%;
     height: var(--ai-banner-height, 2.75rem);
     background: #1a1a1a;
@@ -25,37 +29,48 @@ const llmsFullUrl = `${getSiteUrl()}/llms-full.txt`;
   }
 
   /* Truncate text on narrow screens */
-  .ai-banner span {
+  .ai-banner span,
+  .announce-banner span {
     white-space: nowrap;
     overflow: hidden;
     text-overflow: ellipsis;
     max-width: 100%;
   }
-  .ai-banner a {
+  .ai-banner a,
+  .announce-banner a {
     color: #3b82f6;
     text-decoration: none;
     font-weight: 600;
   }
-  .ai-banner a:hover {
+  .ai-banner a:hover,
+  .announce-banner a:hover {
     color: #fafafa;
     text-decoration: underline;
   }
-  .ai-banner a:focus-visible {
+  .ai-banner a:focus-visible,
+  .announce-banner a:focus-visible {
     outline: 2px solid #3b82f6;
     outline-offset: 2px;
     border-radius: 2px;
   }
 
+  .announce-banner {
+    background: #1a2332;
+    border-bottom: 1px solid #1e3a5f;
+  }
+
   /* Match navbar padding at breakpoints */
   @media (min-width: 50rem) {
-    .ai-banner {
+    .ai-banner,
+    .announce-banner {
       padding-left: 2.5rem;
       padding-right: 2.5rem;
     }
   }
 
   @media (min-width: 72rem) {
-    .ai-banner {
+    .ai-banner,
+    .announce-banner {
       padding-left: 3rem;
       padding-right: 3rem;
     }