Skip to content

Convert generate-project-context to native skill packaging #1950

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
alexeyv merged 3 commits into from
Mar 14, 2026
Merged

Convert generate-project-context to native skill packaging #1950

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e7f87af
convert generate-project-context to native skill packaging
alexeyv Mar 12, 2026
2d64254
fix(skill): remove workflow metadata from bmad-generate-project-context
alexeyv Mar 14, 2026
1457e0b
fix(bmm): remove workflow metadata from generate-project-context work…
alexeyv Mar 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion src/bmm/module-help.csv
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
module,phase,name,code,sequence,workflow-file,command,required,agent,options,description,output-location,outputs,
bmm,anytime,Document Project,DP,,skill:bmad-document-project,bmad-bmm-document-project,false,analyst,Create Mode,"Analyze an existing project to produce useful documentation",project-knowledge,*,
bmm,anytime,Generate Project Context,GPC,,_bmad/bmm/workflows/generate-project-context/workflow.md,bmad-bmm-generate-project-context,false,analyst,Create Mode,"Scan existing codebase to generate a lean LLM-optimized project-context.md containing critical implementation rules patterns and conventions for AI agents. Essential for brownfield projects and quick-flow.",output_folder,"project context",
bmm,anytime,Generate Project Context,GPC,,skill:bmad-generate-project-context,bmad-bmm-generate-project-context,false,analyst,Create Mode,"Scan existing codebase to generate a lean LLM-optimized project-context.md containing critical implementation rules patterns and conventions for AI agents. Essential for brownfield projects and quick-flow.",output_folder,"project context",
bmm,anytime,Quick Spec,QS,,_bmad/bmm/workflows/bmad-quick-flow/quick-spec/workflow.md,bmad-bmm-quick-spec,false,quick-flow-solo-dev,Create Mode,"Do not suggest for potentially very complex things unless requested or if the user complains that they do not want to follow the extensive planning of the bmad method. Quick one-off tasks small changes simple apps brownfield additions to well established patterns utilities without extensive planning",planning_artifacts,"tech spec",
bmm,anytime,Quick Dev,QD,,skill:bmad-quick-dev,bmad-bmm-quick-dev,false,quick-flow-solo-dev,Create Mode,"Quick one-off tasks small changes simple apps utilities without extensive planning - Do not suggest for potentially very complex things unless requested or if the user complains that they do not want to follow the extensive planning of the bmad method, unless the user is already working through the implementation phase and just requests a 1 off things not already in the plan",,,
bmm,anytime,Quick Dev New Preview,QQ,,skill:bmad-quick-dev-new-preview,bmad-bmm-quick-dev-new-preview,false,quick-flow-solo-dev,Create Mode,"Unified quick flow (experimental): clarify intent plan implement review and present in a single workflow",implementation_artifacts,"tech spec implementation",
Expand Down
6 changes: 6 additions & 0 deletions src/bmm/workflows/bmad-generate-project-context/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
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"'
---

Follow the instructions in [workflow.md](workflow.md).
1 change: 1 addition & 0 deletions src/bmm/workflows/bmad-generate-project-context/bmad-skill-manifest.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
type: skill
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Mar 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Add manifest description; discovery/help metadata is currently dropped.

Line 1 omits description, which removes human-readable intent for this skill and makes manifest metadata weaker than the repo convention.

Based on learnings: "In all bmad-skill-manifest.yaml files, use a concise, action-oriented description ... Keep descriptions brief and consistent across manifests."

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@src/bmm/workflows/bmad-generate-project-context/bmad-skill-manifest.yaml` at
line 1, Add a concise, action-oriented description field to the manifest so
human-readable intent and discovery/help metadata are preserved: update the
bmad-skill-manifest.yaml by adding a top-level "description" key (alongside the
existing "type: skill") with a brief imperative sentence describing what the
skill does (e.g., "Generate project-specific context from repository files").
Keep it short, consistent with other bmad manifests, and ensure the description
accurately reflects the behavior of this skill.

0 ...oject-context/project-context-template.md → ...oject-context/project-context-template.md
View file
Open in desktop
File renamed without changes.
4 changes: 2 additions & 2 deletions ...project-context/steps/step-01-discover.md → ...project-context/steps/step-01-discover.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -123,7 +123,7 @@ Based on discovery, create or update the context document:

#### A. Fresh Document Setup (if no existing context)

Copy template from `{installed_path}/project-context-template.md` to `{output_folder}/project-context.md`
Copy template from `./project-context-template.md` to `{output_folder}/project-context.md`
Copy link
Copy Markdown

@augmentcode augmentcode bot Mar 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

step-01-discover.md lives under steps/, so ./project-context-template.md will usually resolve to steps/project-context-template.md (which doesn’t exist) rather than the template in the workflow root. Consider referencing the template via {template_path} (or otherwise making the path parent-relative) so the copy instruction can’t point at a missing file.

Severity: medium

Fix This in Augment

🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.

Copy link
Copy Markdown

@coderabbitai coderabbitai bot Mar 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Template source path is incorrect for converted-workflow step resolution.

Line 126 uses ./project-context-template.md, which resolves to steps/project-context-template.md in this workflow type; the template lives at the skill root.

Proposed fix 
-Copy template from `./project-context-template.md` to `{output_folder}/project-context.md`
+Copy template from `../project-context-template.md` to `{output_folder}/project-context.md`

Based on learnings: "In step files located inside a steps/ subdirectory of a converted-workflow skill, ./ resolves relative to the file's own directory (steps/), not relative to the skill root."

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
Copy template from `./project-context-template.md` to `{output_folder}/project-context.md`
Copy template from `../project-context-template.md` to `{output_folder}/project-context.md`
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@src/bmm/workflows/bmad-generate-project-context/steps/step-01-discover.md` at
line 126, The template source path in step-01-discover.md incorrectly uses
'./project-context-template.md' (which resolves to
steps/project-context-template.md); change that reference to the skill-root path
by using '../project-context-template.md' (so the copy from
'../project-context-template.md' to '{output_folder}/project-context.md' will
locate the template in the skill root).

Initialize frontmatter fields.
Comment on lines +126 to 127
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Mar 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Define overwrite behavior explicitly before copying template.

Lines 126-127 initialize output but don’t specify overwrite/merge behavior when the file already exists. That creates nondeterministic behavior in the existing-context branch.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@src/bmm/workflows/bmad-generate-project-context/steps/step-01-discover.md`
around lines 126 - 127, The copy step for project-context-template.md to
{output_folder}/project-context.md currently doesn't state whether to overwrite
or merge, causing nondeterminism in the existing-context branch; update the step
to explicitly handle existing files by either (a) always overwriting (document
and use an overwrite flag), or (b) performing a deterministic merge: detect if
{output_folder}/project-context.md exists, read its frontmatter, merge/retain
existing keys with initialized defaults, and then write the merged frontmatter
plus template body back; reference the template filename
project-context-template.md, the target {output_folder}/project-context.md, and
the "existing-context" branch logic when implementing the explicit
overwrite-or-merge behavior.


#### B. Existing Document Update
Expand Down Expand Up @@ -179,6 +179,6 @@ Ready to create/update your project context. This will help AI agents implement

## NEXT STEP:

After user selects [C] to continue, load `{project-root}/_bmad/bmm/workflows/generate-project-context/steps/step-02-generate.md` to collaboratively generate the specific project context rules.
After user selects [C] to continue, load `./step-02-generate.md` to collaboratively generate the specific project context rules.

Remember: Do NOT proceed to step-02 until user explicitly selects [C] from the menu and discovery is confirmed and the initial file has been written as directed in this discovery step!
2 changes: 1 addition & 1 deletion ...project-context/steps/step-02-generate.md → ...project-context/steps/step-02-generate.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -314,6 +314,6 @@ When user selects 'C' for a category, append the content directly to `{output_fo

## NEXT STEP:

After completing all rule categories and user selects 'C' for the final category, load `{project-root}/_bmad/bmm/workflows/generate-project-context/steps/step-03-complete.md` to finalize the project context file.
After completing all rule categories and user selects 'C' for the final category, load `./step-03-complete.md` to finalize the project context file.

Remember: Do NOT proceed to step-03 until all categories are complete and user explicitly selects 'C' for each!
0 ...project-context/steps/step-03-complete.md → ...project-context/steps/step-03-complete.md
View file
Open in desktop
File renamed without changes.
11 changes: 3 additions & 8 deletions ...lows/generate-project-context/workflow.md → ...bmad-generate-project-context/workflow.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,3 @@
---
name: generate-project-context
description: 'Create project-context.md with AI rules. Use when the user says "generate project context" or "create project context"'
---

# 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.
Expand Down Expand Up @@ -37,14 +32,14 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:

### Paths

- `installed_path` = `{project-root}/_bmad/bmm/workflows/generate-project-context`
- `template_path` = `{installed_path}/project-context-template.md`
- `installed_path` = `.`
- `template_path` = `./project-context-template.md`
Comment on lines +35 to +36
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Mar 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Relative path normalization now relies on implicit runtime cwd semantics.

Lines 35-36 switched from absolute/project-root-derived values to . and ./.... Installer-side resolver logic shown in tools/cli/lib/agent/installer.js:44-46 does not normalize these, so behavior depends on agent execution context rather than deterministic substitution.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@src/bmm/workflows/bmad-generate-project-context/workflow.md` around lines 35
- 36, The change replaced deterministic project-root-derived values with
relative paths (`installed_path` = `.` and `template_path` =
`./project-context-template.md`), making resolution depend on the agent's cwd;
restore deterministic resolution by using project-root anchored paths (e.g., the
original project-root-derived values) or ensure the installer normalizes these
entries before use. Update the workflow metadata entries `installed_path` and
`template_path` to be absolute or project-root relative tokens (so the installer
can substitute reliably), or modify the installer resolver (the resolver used
around the agent installer logic) to call path normalization (e.g., path.resolve
against the known project root) for these keys before consumption. Ensure
`installed_path` and `template_path` are consistently normalized to avoid
runtime cwd dependence.

- `output_file` = `{output_folder}/project-context.md`

---

## EXECUTION

Load and execute `{project-root}/_bmad/bmm/workflows/generate-project-context/steps/step-01-discover.md` to begin the workflow.
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.
3 changes: 0 additions & 3 deletions src/bmm/workflows/generate-project-context/bmad-skill-manifest.yaml
View file
Open in desktop

This file was deleted.

Loading