Convert generate-project-context to native skill packaging#1950
Merged
Convert generate-project-context to native skill packaging#1950
Conversation
🤖 Augment PR SummarySummary: Converts the “generate project context” workflow to native skill packaging. 🤖 Was this summary useful? React with 👍 or 👎 |
![augmentcode[bot]](https://avatars.githubusercontent.com/in/1027498?s=60&v=4){kind=small}
| #### 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` |
There was a problem hiding this comment.
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
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
alexeyv
force-pushed
the
convert-generate-project-context-skill
branch
from
622ad78 to
7f6eb40
Compare
📝 WalkthroughWalkthroughThis change migrates the Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~15 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
📝 Coding Plan
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🧹 Nitpick comments (4)
src/bmm/workflows/bmad-generate-project-context/SKILL.md (1)
3-3: Broaden SKILL description to include update flow, not only creation.Line 3 says “Create project-context.md,” but the workflow also supports updating an existing context. This mismatch can mislead invocation/routing intent text.
Based on learnings: "SKILL.md frontmatter is the canonical source of truth for skill descriptions."
🤖 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/SKILL.md` at line 3, Update the SKILL.md frontmatter description so it accurately reflects both creation and update flows: change the description string in SKILL.md from "Create project-context.md with AI rules. Use when the user says 'generate project context' or 'create project context'" to mention creating or updating (e.g., "Create or update project-context.md with AI rules") and expand invocation examples to include update phrases like "update project context" or "modify project context" so the canonical skill description matches the workflow's supported operations.src/bmm/workflows/bmad-generate-project-context/workflow.md (2)
35-35:installed_pathis now effectively a placeholder with no clear value.Line 35 sets
installed_path = .; this no longer conveys a concrete install location and weakens traceability/debuggability for downstream references.🤖 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` at line 35, The `installed_path` variable (currently set to `.`) is a placeholder and should be replaced with a concrete install location or computed dynamically; update the workflow to set `installed_path` to the real install directory (e.g., an explicit path, an environment variable like INSTALL_DIR, or derive it from runtime context such as GITHUB_WORKSPACE or a resolved package install path) and ensure any references that consume `installed_path` (search for usages of `installed_path` in templates or steps) are updated to use this concrete value so downstream tracing and debugging work correctly.
36-43: Path contract is split across files without a single enforced source of truth.Line 36 defines
template_path, while step files directly embed template/step paths. This makes path changes error-prone during future conversions and renames.🤖 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 36 - 43, The workflow splits path configuration between the top-level variables `template_path` and `output_file` and hard-coded paths inside step files like `./steps/step-01-discover.md`, which risks drift; centralize all path values by moving step and template locations into a single source-of-truth (e.g., a `paths` map or variables in the workflow header) and update each step file reference to use those variables (for example replace embedded `./steps/step-01-discover.md` with the centralized variable for that step and have `template_path`/`output_file` referenced consistently), ensuring all uses of `template_path`, `output_file`, and step filenames read from that single config so future renames only require one change.src/bmm/workflows/bmad-generate-project-context/steps/step-01-discover.md (1)
126-126: Use{template_path}here to avoid path drift between workflow and step docs.Line 126 hardcodes the template location while
workflow.mdalready declarestemplate_path. If one changes and the other doesn’t, the flow silently drifts.🤖 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, Replace the hardcoded template path in the step text with the workflow variable so the step uses `{template_path}` instead of `./project-context-template.md`; update the instruction that currently reads "Copy template from `./project-context-template.md` to `{output_folder}/project-context.md`" to read "Copy template from `{template_path}` to `{output_folder}/project-context.md`" so the step-01-discover.md content stays in sync with the workflow's `template_path` declaration.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@src/bmm/workflows/bmad-generate-project-context/bmad-skill-manifest.yaml`:
- 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.
In `@src/bmm/workflows/bmad-generate-project-context/steps/step-01-discover.md`:
- 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).
- Around line 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.
In `@src/bmm/workflows/bmad-generate-project-context/workflow.md`:
- Around line 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.
---
Nitpick comments:
In `@src/bmm/workflows/bmad-generate-project-context/SKILL.md`:
- Line 3: Update the SKILL.md frontmatter description so it accurately reflects
both creation and update flows: change the description string in SKILL.md from
"Create project-context.md with AI rules. Use when the user says 'generate
project context' or 'create project context'" to mention creating or updating
(e.g., "Create or update project-context.md with AI rules") and expand
invocation examples to include update phrases like "update project context" or
"modify project context" so the canonical skill description matches the
workflow's supported operations.
In `@src/bmm/workflows/bmad-generate-project-context/steps/step-01-discover.md`:
- Line 126: Replace the hardcoded template path in the step text with the
workflow variable so the step uses `{template_path}` instead of
`./project-context-template.md`; update the instruction that currently reads
"Copy template from `./project-context-template.md` to
`{output_folder}/project-context.md`" to read "Copy template from
`{template_path}` to `{output_folder}/project-context.md`" so the
step-01-discover.md content stays in sync with the workflow's `template_path`
declaration.
In `@src/bmm/workflows/bmad-generate-project-context/workflow.md`:
- Line 35: The `installed_path` variable (currently set to `.`) is a placeholder
and should be replaced with a concrete install location or computed dynamically;
update the workflow to set `installed_path` to the real install directory (e.g.,
an explicit path, an environment variable like INSTALL_DIR, or derive it from
runtime context such as GITHUB_WORKSPACE or a resolved package install path) and
ensure any references that consume `installed_path` (search for usages of
`installed_path` in templates or steps) are updated to use this concrete value
so downstream tracing and debugging work correctly.
- Around line 36-43: The workflow splits path configuration between the
top-level variables `template_path` and `output_file` and hard-coded paths
inside step files like `./steps/step-01-discover.md`, which risks drift;
centralize all path values by moving step and template locations into a single
source-of-truth (e.g., a `paths` map or variables in the workflow header) and
update each step file reference to use those variables (for example replace
embedded `./steps/step-01-discover.md` with the centralized variable for that
step and have `template_path`/`output_file` referenced consistently), ensuring
all uses of `template_path`, `output_file`, and step filenames read from that
single config so future renames only require one change.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 2cd960b8-d728-422a-b514-76b34c2b6f70
⛔ Files ignored due to path filters (1)
src/bmm/module-help.csvis excluded by!**/*.csv
📒 Files selected for processing (8)
src/bmm/workflows/bmad-generate-project-context/SKILL.mdsrc/bmm/workflows/bmad-generate-project-context/bmad-skill-manifest.yamlsrc/bmm/workflows/bmad-generate-project-context/project-context-template.mdsrc/bmm/workflows/bmad-generate-project-context/steps/step-01-discover.mdsrc/bmm/workflows/bmad-generate-project-context/steps/step-02-generate.mdsrc/bmm/workflows/bmad-generate-project-context/steps/step-03-complete.mdsrc/bmm/workflows/bmad-generate-project-context/workflow.mdsrc/bmm/workflows/generate-project-context/bmad-skill-manifest.yaml
💤 Files with no reviewable changes (1)
- src/bmm/workflows/generate-project-context/bmad-skill-manifest.yaml
| @@ -0,0 +1 @@ | |||
| type: skill | |||
There was a problem hiding this comment.
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.
| #### 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` |
There was a problem hiding this comment.
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).
Comment on lines
+126
to
127
| Copy template from `./project-context-template.md` to `{output_folder}/project-context.md` | ||
| Initialize frontmatter fields. |
There was a problem hiding this comment.
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.
Comment on lines
+35
to
+36
| - `installed_path` = `.` | ||
| - `template_path` = `./project-context-template.md` |
There was a problem hiding this comment.
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.
7f6eb40 to
8a56b77
Compare
Remove name/description frontmatter from workflow.md (belongs in SKILL.md). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…flow Move name/description to SKILL.md; workflow.md carries only execution content. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
alexeyv
force-pushed
the
convert-generate-project-context-skill
branch
from
8a56b77 to
1457e0b
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
generate-project-contextto nativetype: skillpackagingsrc/bmm/workflows/bmad-generate-project-context/SKILL.md, switch manifest totype: skill, and keep workflow/steps/template content unchanged except required path/name normalizationsrc/bmm/module-help.csvworkflow-file reference toskill:bmad-generate-project-contextValidation
node tools/cli/bmad-cli.js install --directory /Users/alex/src/bmad --modules bmm --tools claude-code --yes.claude/skills/bmad-generate-project-context/contains workflow + steps + template + SKILL_bmad/_config/skill-manifest.csvcontainsbmad-generate-project-context_bmad/_config/workflow-manifest.csvhas nogenerate-project-contextentrynpm testEquivalence Protocol
workflow.mdsteps/step-01-discover.mdsteps/step-02-generate.mdsteps/step-03-complete.mdproject-context-template.md