From 84a3aa57dea5cfa28c4e2770f1fdae13d13dcbaf Mon Sep 17 00:00:00 2001
From: Hisyam <158235363+Kavleri@users.noreply.github.com>
Date: Mon, 30 Mar 2026 12:14:20 +0700
Subject: [PATCH] docs: add pencil usage guidelines to core-tools #2162

Addresses issue #2162 by adding recommendations for introducing Pencil early in the BMad workflow.
---
 docs/reference/core-tools.md | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/docs/reference/core-tools.md b/docs/reference/core-tools.md
index dbc690826..1f91ea82e 100644
--- a/docs/reference/core-tools.md
+++ b/docs/reference/core-tools.md
@@ -291,3 +291,14 @@ Run both `bmad-review-adversarial-general` and `bmad-review-edge-case-hunter` to
 **Input:** Target folder path
 
 **Output:** `index.md` with organized file listings, relative links, and brief descriptions
+
+
+
+## 3rd Party Tools Integration: Pencil
+
+If you are using **Pencil** within BMAD workflows for creating mockups or UI designs, it is critical that the LLM is fully aware of its existence early in the process rather than treating it merely as a nice-to-have MCP (Model Context Protocol).
+
+**Important Guidelines for Pencil:**
+- **Introduce Early:** The sooner you bring Pencil into your planning process, the better. You must specify Pencil in your tooling **before** generating the `_bmad-output/planning-artifacts/architecture.md` document.
+- **Enforce Context:** Explicitly enforce the inclusion of your `.pen` (Pencil) files in the `_bmad-output/project-context.md` file. 
+- **Why this matters:** If you bring Pencil in after the PRD, UX, and Architecture docs are already drafted without establishing these guardrails, the AI will not integrate it smoothly and will cause avoidable course corrections during sprints.