bmad-plus 0.13.0 → 0.14.0

package/src/bmad-plus/packs/pack-dev-studio/categories/architecture/generate-project-context.md

@@ -1,81 +1,59 @@
----
+---
 name: bmad-generate-project-context
-description: 'Create project-context.md with AI rules. Use when the user says "generate project context" or "create project context"'
+description: Capture concise project conventions and constraints from inspected sources.
 ---
 
-# Generate Project Context Workflow
-
-**Goal:** Create a concise, optimized `project-context.md` file containing critical rules, patterns, and guidelines that AI agents must follow when implementing code. This file focuses on unobvious details that LLMs need to be reminded of.
-
-**Your Role:** You are a technical facilitator working with a peer to capture the essential implementation rules that will ensure consistent, high-quality code generation across all AI agents working on the project.
-
-## Conventions
-
-- Bare paths (e.g. `steps/step-01-discover.md`) resolve from the skill root.
-- `this skill directory` resolves to this skill's installed directory (where `agent configuration` lives).
-- `{project-root}`-prefixed paths resolve from the project working directory.
-- `{skill-name}` resolves to the skill directory's basename.
-
-## WORKFLOW ARCHITECTURE
-
-This uses **micro-file architecture** for disciplined execution:
-
-- Each step is a self-contained file with embedded rules
-- Sequential progression with user control at each step
-- Document state tracked in frontmatter
-- Focus on lean, LLM-optimized content generation
-- You NEVER proceed to a step file if the current step file indicates the user must approve and indicate continuation.
-
-## On Activation
-
-### Step 1: Resolve the Workflow Block
-
-<!-- Adapted for BMAD+: original script dependency removed -->
-
-**If the script fails**, resolve the `workflow` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
-
-1. `this skill file` — defaults
-2. `{project-root}/custom/{skill-name}.toml` — team overrides
-3. `{project-root}/custom/{skill-name}.user.toml` — personal overrides
-
-Any missing file is skipped. Scalars override, tables deep-merge, arrays of tables keyed by `code` or `id` replace matching entries and append new entries, and all other arrays append.
-
-### Step 2: Execute Prepend Steps
-
-Execute each entry in `{workflow.activation_steps_prepend}` in order before proceeding.
-
-### Step 3: Load Persistent Facts
-
-Treat every entry in `{workflow.persistent_facts}` as foundational context you carry for the rest of the workflow run. Entries prefixed `file:` are paths or globs under `{project-root}` — load the referenced contents as facts. All other entries are facts verbatim.
-
-### Step 4: Load Config
-
-Load config from `{project-root}/project config` and resolve:
-- Use `{user_name}` for greeting
-- Use `{communication_language}` for all communications
-- Use `{document_output_language}` for output documents
-- Use `{planning_artifacts}` for output location and artifact scanning
-- Use `{project_knowledge}` for additional context scanning
-
-### Step 5: Greet the User
-
-Greet `{user_name}`, speaking in `{communication_language}`.
-
-### Step 6: Execute Append Steps
-
-Execute each entry in `{workflow.activation_steps_append}` in order.
-
-Activation is complete. Begin the workflow below.
-
-## Paths
-
-- `output_file` = `{output_folder}/project-context.md`
-
-## Execution
-
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
-- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
-
-Load and execute `./steps/step-01-discover.md` to begin the workflow.
-
-**Note:** Input document discovery and initialization protocols are handled in step-01-discover.md.
+# Generate project context
+
+Read the [execution guide](../../shared/execution.md) and
+[Bezalel's role](architect-agent.md).
+
+## Inputs
+
+A request naming what project or area to summarize, or an explicit project
+artifact. Inspect the selected directory with host tools; a prepared context
+bundle is not a repository inspection. Read current instructions and existing
+context before generating another file.
+
+## Procedure
+
+1. Identify the repository boundary and relevant source areas. Read project
+   instructions, manifests, build or test entry points and representative code.
+   Record the inspected revision or input hashes and any inaccessible areas.
+2. Extract facts that affect future work: runtime and package manager, directory
+   responsibilities, established extension patterns, actual verification commands
+   and deployment boundaries. Cite each consequential fact to its source.
+3. Capture invariants and recurring conventions using concrete examples. Separate
+   project requirements from an observed local pattern and from a recommendation.
+   Do not promote one unusual file into a universal rule.
+4. Check existing context and documentation for duplication or contradictions.
+   Resolve claims by inspecting the authoritative source; keep unresolved
+   disagreements visible. Summarize useful rules rather than copying large files
+   or storing sensitive values.
+5. Organize a compact context document around the decisions a future implementer
+   must make. Include where to look next and what has not been inspected. Label
+   commands as discovered or executed, with actual results only for executed
+   checks.
+6. Review each statement for evidence and ongoing relevance. Write the report,
+   or the user's requested project-context destination. Never overwrite generated
+   AGENTS.md or tool adapters; changes to their rules belong in their source
+   configuration and generation workflow.
+
+## Output and acceptance
+
+The report for generate-project-context contains scope and freshness, source
+ledger, project map, working conventions, acceptance/verification commands,
+invariants and unresolved questions. State the inspected area prominently when
+coverage is partial.
+
+A future assistant should be able to find the implementation area and the
+appropriate checks from this document. Unsupported prescriptions, duplicated
+manuals and hidden assumptions should be removed or labeled as proposals.
+The context is reference material and does not override project or user instructions.
+
+## Continue
+
+Read and preserve the existing document's human additions. Compare referenced
+sources and hashes, refresh affected facts and remove stale statements only with
+their replacement evidence recorded. An unchanged report date is not proof that
+the project stayed unchanged.

package/src/bmad-plus/packs/pack-dev-studio/categories/architecture/implementation-readiness.md

@@ -1,91 +1,58 @@
----
+---
 name: bmad-check-implementation-readiness
-description: 'Validate PRD, UX, Architecture and Epics specs are complete. Use when the user says "check implementation readiness".'
+description: Check whether a selected scope has enough consistent evidence to begin implementation.
 ---
 
-# Implementation Readiness
-
-**Goal:** Validate that PRD, UX, Architecture, Epics and Stories are complete and aligned before Phase 4 implementation starts, with a focus on ensuring epics and stories are logical and have accounted for all requirements and planning.
-
-**Your Role:** You are an expert Product Manager, renowned and respected in the field of requirements traceability and spotting gaps in planning. Your success is measured in spotting the failures others have made in planning or preparation of epics and stories to produce the user's product vision.
-
-## Conventions
-
-- Bare paths (e.g. `steps/step-01-document-discovery.md`) resolve from the skill root.
-- `this skill directory` resolves to this skill's installed directory (where `agent configuration` lives).
-- `{project-root}`-prefixed paths resolve from the project working directory.
-- `{skill-name}` resolves to the skill directory's basename.
-
-## WORKFLOW ARCHITECTURE
-
-### Core Principles
-
-- **Micro-file Design**: Each step toward the overall goal is a self-contained instruction file; adhere to one file at a time, as directed
-- **Just-In-Time Loading**: Only 1 current step file will be loaded and followed to completion - never load future step files until told to do so
-- **Sequential Enforcement**: Sequence within the step files must be completed in order, no skipping or optimization allowed
-- **State Tracking**: Document progress in output file frontmatter using `stepsCompleted` array when a workflow produces a document
-- **Append-Only Building**: Build documents by appending content as directed to the output file
-
-### Step Processing Rules
-
-1. **READ COMPLETELY**: Always read the entire step file before taking any action
-2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate
-3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection
-4. **CHECK CONTINUATION**: If the step has a menu with Continue as an option, only proceed to next step when user selects 'C' (Continue)
-5. **SAVE STATE**: Update `stepsCompleted` in frontmatter before loading next step
-6. **LOAD NEXT**: When directed, read fully and follow the next step file
-
-### Critical Rules (NO EXCEPTIONS)
-
-- 🛑 **NEVER** load multiple step files simultaneously
-- 📖 **ALWAYS** read entire step file before execution
-- 🚫 **NEVER** skip steps or optimize the sequence
-- 💾 **ALWAYS** update frontmatter of output files when writing the final output for a specific step
-- 🎯 **ALWAYS** follow the exact instructions in the step file
-- ⏸️ **ALWAYS** halt at menus and wait for user input
-- 📋 **NEVER** create mental todo lists from future steps
-
-## On Activation
-
-### Step 1: Resolve the Workflow Block
-
-<!-- Adapted for BMAD+: original script dependency removed -->
-
-**If the script fails**, resolve the `workflow` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
-
-1. `this skill file` — defaults
-2. `{project-root}/custom/{skill-name}.toml` — team overrides
-3. `{project-root}/custom/{skill-name}.user.toml` — personal overrides
-
-Any missing file is skipped. Scalars override, tables deep-merge, arrays of tables keyed by `code` or `id` replace matching entries and append new entries, and all other arrays append.
-
-### Step 2: Execute Prepend Steps
-
-Execute each entry in `{workflow.activation_steps_prepend}` in order before proceeding.
-
-### Step 3: Load Persistent Facts
-
-Treat every entry in `{workflow.persistent_facts}` as foundational context you carry for the rest of the workflow run. Entries prefixed `file:` are paths or globs under `{project-root}` — load the referenced contents as facts. All other entries are facts verbatim.
-
-### Step 4: Load Config
-
-Load config from `{project-root}/project config` and resolve:
-- Use `{user_name}` for greeting
-- Use `{communication_language}` for all communications
-- Use `{document_output_language}` for output documents
-- Use `{planning_artifacts}` for output location and artifact scanning
-- Use `{project_knowledge}` for additional context scanning
-
-### Step 5: Greet the User
-
-Greet `{user_name}`, speaking in `{communication_language}`.
-
-### Step 6: Execute Append Steps
-
-Execute each entry in `{workflow.activation_steps_append}` in order.
-
-Activation is complete. Begin the workflow below.
-
-## Execution
-
-Read fully and follow: `./steps/step-01-document-discovery.md` to begin the workflow.
+# Implementation readiness
+
+Read the [execution guide](../../shared/execution.md) and
+[Bezalel's role](architect-agent.md).
+
+## Inputs
+
+At least one explicit planning or story artifact and the scope to assess. Use
+supplied requirements, architecture, UX, backlog and project constraints as
+applicable. A small maintenance task need not acquire unrelated planning documents.
+
+## Procedure
+
+1. Name the slice being assessed and inventory the artifacts actually read.
+   Record versions or hashes and whether each artifact describes the current
+   project. Separate absent documents from missing information.
+2. Extract the slice's intended behavior, acceptance criteria and invariants.
+   Check that essential terms, boundaries and failure behavior have a consistent
+   meaning across inputs. Cite conflicting passages precisely.
+3. Trace requirements through relevant UX or interface contracts, architecture
+   decisions and implementation tasks. Identify missing handoffs, contradictory
+   interfaces, uncovered constraints and acceptance checks with no observable
+   result.
+4. Inspect readiness dependencies: repository and runtime access, required data,
+   decision owners, migrations, credentials supplied through approved channels,
+   and test capabilities. Do not request or reproduce secret values in the report.
+   A promise that access exists is not a successful access check.
+5. Rank issues by their effect on the next implementation slice. Separate
+   prerequisites that stop it, decisions safely deferred, and improvements that
+   do not affect its acceptance. Give each blocking issue a source, consequence
+   and the smallest resolution action.
+6. Produce a disposition of ready, needs-resolution, or insufficient-evidence.
+   Ready requires the scoped prerequisites and acceptance path to be evidenced.
+   Missing information prevents a readiness claim for the affected scope;
+   unrelated missing documents do not block useful independent work.
+
+## Output and acceptance
+
+Write the report for implementation-readiness with assessed scope, input ledger,
+traceability table, issues, disposition and next actions. Use one row per relevant
+requirement or invariant with columns for source, implementing story or task,
+acceptance check and evidence status.
+
+Every blocking conclusion must cite a concrete contradiction or missing
+prerequisite. Zero issues is valid after completing the scoped assessment.
+Readiness means work can begin under the recorded assumptions; it does not mean
+the implementation is correct or that tests have passed.
+
+## Continue
+
+On new evidence, compare inputs and reassess only affected rows and dependencies.
+Keep prior issues and record their resolution evidence. A document revision or
+someone saying an issue is fixed is not itself proof of the relevant change.

package/src/bmad-plus/packs/pack-dev-studio/categories/architecture/steps/step-01-init.md

@@ -1,153 +1,20 @@
-# Step 1: Architecture Workflow Initialization
-
-## MANDATORY EXECUTION RULES (READ FIRST):
-
-- 🛑 NEVER generate content without user input
-- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
-- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
-- ✅ ALWAYS treat this as collaborative discovery between architectural peers
-- 📋 YOU ARE A FACILITATOR, not a content generator
-- 💬 FOCUS on initialization and setup only - don't look ahead to future steps
-- 🚪 DETECT existing workflow state and handle continuation properly
-- ⚠️ ABSOLUTELY NO TIME ESTIMATES - AI development speed has fundamentally changed
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
-
-## EXECUTION PROTOCOLS:
-
-- 🎯 Show your analysis before taking any action
-- 💾 Initialize document and update frontmatter
-- 📖 Set up frontmatter `stepsCompleted: [1]` before loading next step
-- 🚫 FORBIDDEN to load next step until setup is complete
-
-## CONTEXT BOUNDARIES:
-
-- Variables from workflow.md are available in memory
-- Previous context = what's in output document + frontmatter
-- Don't assume knowledge from other steps
-- Input document discovery happens in this step
-
-## YOUR TASK:
-
-Initialize the Architecture workflow by detecting continuation state, discovering input documents, and setting up the document for collaborative architectural decision making.
-
-## INITIALIZATION SEQUENCE:
-
-### 1. Check for Existing Workflow
-
-First, check if the output document already exists:
-
-- Look for existing {planning_artifacts}/`*architecture*.md`
-- If exists, read the complete file(s) including frontmatter
-- If not exists, this is a fresh workflow
-
-### 2. Handle Continuation (If Document Exists)
-
-If the document exists and has frontmatter with `stepsCompleted`:
-
-- **STOP here** and load `./step-01b-continue.md` immediately
-- Do not proceed with any initialization tasks
-- Let step-01b handle the continuation logic
-
-### 3. Fresh Workflow Setup (If No Document)
-
-If no document exists or no `stepsCompleted` in frontmatter:
-
-#### A. Input Document Discovery
-
-Discover and load context documents using smart discovery. Documents can be in the following locations:
-- {planning_artifacts}/**
-- {output_folder}/**
-- {project_knowledge}/**
-- {project-root}/docs/**
-
-Also - when searching - documents can be a single markdown file, or a folder with an index and multiple files. For Example, if searching for `*foo*.md` and not found, also search for a folder called *foo*/index.md (which indicates sharded content)
-
-Try to discover the following:
-- Product Brief (`*brief*.md`)
-- Product Requirements Document (`*prd*.md`)
-- UX Design (`*ux-design*.md`) and other
-- Research Documents (`*research*.md`)
-- Project Documentation (generally multiple documents might be found for this in the `{project_knowledge}` or `{project-root}/docs` folder.)
-- Project Context (`**/project-context.md`)
-
-<critical>Confirm what you have found with the user, along with asking if the user wants to provide anything else. Only after this confirmation will you proceed to follow the loading rules</critical>
-
-**Loading Rules:**
-
-- Load ALL discovered files completely that the user confirmed or provided (no offset/limit)
-- If there is a project context, whatever is relevant should try to be biased in the remainder of this whole workflow process
-- For sharded folders, load ALL files to get complete picture, using the index first to potentially know the potential of each document
-- index.md is a guide to what's relevant whenever available
-- Track all successfully loaded files in frontmatter `inputDocuments` array
-
-#### B. Validate Required Inputs
-
-Before proceeding, verify we have the essential inputs:
-
-**PRD Validation:**
-
-- If no PRD found: "Architecture requires a PRD to work from. Please run the PRD workflow first or provide the PRD file path."
-- Do NOT proceed without PRD
-
-**Other Input that might exist:**
-
-- UX Spec: "Provides UI/UX architectural requirements"
-
-#### C. Create Initial Document
-
-Copy the template from `../architecture-decision-template.md` to `{planning_artifacts}/architecture.md`
-
-#### D. Complete Initialization and Report
-
-Complete setup and report to user:
-
-**Document Setup:**
-
-- Created: `{planning_artifacts}/architecture.md` from template
-- Initialized frontmatter with workflow state
-
-**Input Documents Discovered:**
-Report what was found:
-"Welcome {{user_name}}! I've set up your Architecture workspace for {{project_name}}.
-
-**Documents Found:**
-
-- PRD: {number of PRD files loaded or "None found - REQUIRED"}
-- UX Design: {number of UX files loaded or "None found"}
-- Research: {number of research files loaded or "None found"}
-- Project docs: {number of project files loaded or "None found"}
-- Project context: {project_context_rules count of rules for AI agents found}
-
-**Files loaded:** {list of specific file names or "No additional documents found"}
-
-Ready to begin architectural decision making. Do you have any other documents you'd like me to include?
-
-[C] Continue to project context analysis
-
-## SUCCESS METRICS:
-
-✅ Existing workflow detected and handed off to step-01b correctly
-✅ Fresh workflow initialized with template and frontmatter
-✅ Input documents discovered and loaded using sharded-first logic
-✅ All discovered files tracked in frontmatter `inputDocuments`
-✅ PRD requirement validated and communicated
-✅ User confirmed document setup and can proceed
-
-## FAILURE MODES:
-
-❌ Proceeding with fresh initialization when existing workflow exists
-❌ Not updating frontmatter with discovered input documents
-❌ Creating document without proper template
-❌ Not checking sharded folders first before whole files
-❌ Not reporting what documents were found to user
-❌ Proceeding without validating PRD requirement
-
-❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
-❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
-❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
-
-## NEXT STEP:
-
-After user selects [C] to continue, only after ensuring all the template output has been created, then load `./step-02-context.md` to analyze the project context and begin architectural decision making.
-
-Remember: Do NOT proceed to step-02 until user explicitly selects [C] from the menu and setup is confirmed!
+# Architecture compatibility guide — establish the baseline
+
+This retained path corresponds to procedure step 1 of
+[create-architecture](../create-architecture.md). The main workflow is complete;
+these guides do not form an execution chain. Follow the common
+[execution guide](../../../shared/execution.md).
+
+Read the actual request, project instructions and relevant prior decisions.
+Inventory the input artifacts, their hashes when available and the current
+implementation state. Check whether an architecture report already exists before
+writing one, and preserve its human additions.
+
+Record the requested outcome, system boundary, exclusions and available evidence.
+An absent PRD does not automatically prevent a bounded architecture task; identify
+the missing information that actually matters.
+
+This part is complete when the baseline and intended deliverable are explicit.
+If resuming, compare the old ledger with current inputs before trusting prior
+decisions. Continue at the earliest incomplete part of the main procedure;
+do not overwrite a report merely because this legacy entry was invoked.