Feature Promotion Lifecycle
Canonical variable model and MCP-only command sequence for promoting potential feature/bug entries and initializing active feature delivery.
When to Use This Skill
Use this skill when:
- A large-scope change requires feature/bug promotion workflow.
- A short-path workflow still requires promotion/folder initialization before delegated implementation.
- An orchestrator must create potential docs, promote to issue, branch, and active feature folder.
- Downstream research/spec agents depend on deterministic paths and identifiers.
MCP Tool Availability Preflight
Before any promotion step starts, verify that the required drm-copilot MCP tools are available in the current agent session.
Required MCP tool set:
- feature potential entry:
mcp__drm-copilot__new_potential_entry with short_name=${short-name}
- bug potential entry:
mcp__drm-copilot__new_potential_bug_entry with short_name=${short-name}
- potential-to-issue promotion:
mcp__drm-copilot__potential_to_issue with potential_path=${relativeFile}, promotion_type=${promotion-type}, work_mode=${work-mode}
- active feature folder creation:
mcp__drm-copilot__new_active_feature_folder with feature_name=${long-name}, type=${promotion-type}, issue_number=${issue-num}, work_mode=${work-mode}
If the required MCP tools are unavailable, stop before potential-entry creation, issue promotion, or active-folder creation begins. Restore MCP connectivity first. Agent sessions do not have an approved non-MCP execution branch for promotion work.
Agent-Session Promotion Execution Rule
Execute the lifecycle only through the MCP tool forms listed above. The MCP path is the sole authoritative execution path for agent sessions.
After each successful promotion operation, persist the raw MCP receipt payload under the matching checkpoint key in artifacts/orchestration/orchestrator-state.json:
delegation_receipts.promotion.potential_entry
delegation_receipts.promotion.issue
delegation_receipts.promotion.feature_folder
Each delegation_receipts.promotion.* field stores the raw MCP receipt payload returned by the corresponding promotion operation without lossy normalization.
Note: VS Code command-palette commands may exist for interactive extension use, but this note is non-authoritative for agent sessions.
Pre-Existing Issue Path
When the GitHub issue already exists (it was transferred, filed before orchestration, or created by epic decomposition), do not call potential_to_issue: that tool creates a new issue and would duplicate the existing one. Instead:
- Verify the issue read-only with
gh issue view, a gh api GET request, or a GitHub MCP issue read, and use its number as ${issue-num}.
- Record a top-level
issue_adoption object in the orchestrator checkpoint (issue_num, issue_url, origin, verified_via, verified_at, evidence, waived_tools, and, when a promotion-entry tool is waived, potential_record). For that waiver potential_record is required when origin is epic_decomposition, optional when origin is transferred or filed_before_orchestration, and validated whenever it is present. A valid record waives the potential_to_issue receipt requirement at completion.
delegation_receipts.promotion.issue may be omitted, because no promotion receipt exists for an adopted issue.
The field rules, the closed set of waivable tools, and the fail-closed behavior are defined in .claude/rules/orchestrator-state.md under ## Invariants (issue_adoption object).
Canonical Variables
${promotion-type}: feature or bug
${short-name}: lowercase slug, hyphen-separated
${relativeFile}: workspace-relative path to created potential entry markdown
${long-name}: ${relativeFile} filename without .md
${issue-num}: promoted GitHub issue number
${feature-folder}: active feature folder path
${plan-path}: single canonical plan file path reused across planning and preflight revisions
${work-mode}: minor-audit, full-feature, or full-bug (legacy full is accepted only as an alias for full-feature)
${short-path-flag}: --work-mode minor-audit (mandatory for short-path promotion/folder creation)
When orchestrator routing selects short path, promotion/folder initialization still occurs and MUST use minor-audit mode.
Use the same MCP tool-availability preflight described above and continue only when the required promotion tools are available.
Promote the potential document through mcp__drm-copilot__potential_to_issue with work_mode=minor-audit.
Create branch:
${promotion-type}/${short-name}-${issue-num}
- Create the active feature folder through
mcp__drm-copilot__new_active_feature_folder with work_mode=minor-audit.
4a) Verify minor-audit folder integrity before proceeding:
${feature-folder}/issue.md exists and contains - Work Mode: minor-audit
${feature-folder}/issue.md contains an explicit ## Acceptance Criteria section
${feature-folder}/spec.md does not exist
${feature-folder}/user-story.md does not exist
- the promoted record under
docs/features/potential/promoted/ is still present (see 4b)
- if any check fails, stop and remediate before planning
4b) Verify the promoted record was retained after new_active_feature_folder:
- the promoted file the earlier
potential_to_issue step reported as its destination_path must still exist under docs/features/potential/promoted/
new_active_feature_folder COPIES a promoted source into the active folder as issue.md; it MOVES a source resolved from docs/features/potential/ directly. An absent promoted record after a promoted-source run is a defect, not expected cleanup (issue #487).
- this check applies to every work mode, not only
minor-audit
- Delegate minimal-audit plan creation to
atomic_planner with directive:
DIRECTIVE: MINIMAL-AUDIT PLAN REQUIRED
5a) Resolve and persist ${plan-path} before delegation:
- reuse the earliest existing
plan*.md in ${feature-folder} when present
- otherwise create exactly one canonical plan file path and reuse it for all revisions
- Require preflight validation via
atomic_executor until:
Execute plan Phase 0 only via executor and checkpoint evidence.
Branch:
- manual bootstrap: save state and stop,
- non-bootstrap: continue with constrained small-path development.
- Validate delivery via executor against
issue.md, then run reduced audit/remediation loop until ready-to-merge.
Required Outputs for Downstream Handoffs
Before delegating research/spec/planning, provide:
${feature-folder}/issue.md
${feature-folder}/spec.md (or expected target path)
${feature-folder}/user-story.md (or explicit NONE)
- latest research artifact path(s)
- constraints/APIs/invariants to preserve
Mode-aware expectations:
- For
minor-audit, the explicit ## Acceptance Criteria section in issue.md is the primary acceptance-criteria source and spec.md/user-story.md may be intentionally absent by design.
- For
minor-audit, do not infer acceptance criteria from other issue.md sections such as verification notes, next steps, or severity checklists.
- For
minor-audit, spec.md/user-story.md must be treated as integrity failures when they appear unexpectedly in the active folder.
- For
full-feature, spec.md and user-story.md are expected alongside issue.md.
- For
full-bug, spec.md is expected alongside issue.md; user-story.md should be absent unless the requirements explicitly justify it.
Selected-mode persistence requirements:
- Producer outputs MUST persist exactly one marker in
issue.md metadata above the first ## heading:
- Work Mode: minor-audit
- Work Mode: full-feature
- Work Mode: full-bug
- Persisted marker MUST represent selected mode after eligibility checks, not requested mode.
- If a legacy requested
full path is accepted, tooling MUST normalize it to full-feature before persistence.
- If a requested
minor-audit path is rejected by eligibility checks, tooling MUST fail closed to full-feature, emit the downgrade reason, and persist - Work Mode: full-feature.
1---2name: feature-promotion-lifecycle-23description: Deterministic promotion workflow from potential feature/bug entry to issue, branch, active feature folder, and downstream spec/research handoffs. Agent sessions must use the drm-copilot MCP tool surface and record raw promotion receipts under the canonical checkpoint namespace.4metadata:5 source: https://skillmd.com/skills/drmoisan/feature-promotion-lifecycle-26---78# Feature Promotion Lifecycle910Canonical variable model and MCP-only command sequence for promoting potential feature/bug entries and initializing active feature delivery.1112## When to Use This Skill1314Use this skill when:15- A large-scope change requires feature/bug promotion workflow.16- A short-path workflow still requires promotion/folder initialization before delegated implementation.17- An orchestrator must create potential docs, promote to issue, branch, and active feature folder.18- Downstream research/spec agents depend on deterministic paths and identifiers.1920## MCP Tool Availability Preflight2122Before any promotion step starts, verify that the required `drm-copilot` MCP tools are available in the current agent session.2324Required MCP tool set:25- feature potential entry: `mcp__drm-copilot__new_potential_entry` with `short_name=${short-name}`26- bug potential entry: `mcp__drm-copilot__new_potential_bug_entry` with `short_name=${short-name}`27- potential-to-issue promotion: `mcp__drm-copilot__potential_to_issue` with `potential_path=${relativeFile}`, `promotion_type=${promotion-type}`, `work_mode=${work-mode}`28- active feature folder creation: `mcp__drm-copilot__new_active_feature_folder` with `feature_name=${long-name}`, `type=${promotion-type}`, `issue_number=${issue-num}`, `work_mode=${work-mode}`2930If the required MCP tools are unavailable, stop before potential-entry creation, issue promotion, or active-folder creation begins. Restore MCP connectivity first. Agent sessions do not have an approved non-MCP execution branch for promotion work.3132## Agent-Session Promotion Execution Rule3334Execute the lifecycle only through the MCP tool forms listed above. The MCP path is the sole authoritative execution path for agent sessions.3536After each successful promotion operation, persist the raw MCP receipt payload under the matching checkpoint key in `artifacts/orchestration/orchestrator-state.json`:37- `delegation_receipts.promotion.potential_entry`38- `delegation_receipts.promotion.issue`39- `delegation_receipts.promotion.feature_folder`4041Each `delegation_receipts.promotion.*` field stores the raw MCP receipt payload returned by the corresponding promotion operation without lossy normalization.4243Note: VS Code command-palette commands may exist for interactive extension use, but this note is non-authoritative for agent sessions.4445## Pre-Existing Issue Path4647When the GitHub issue already exists (it was transferred, filed before orchestration, or created by epic decomposition), do not call `potential_to_issue`: that tool creates a new issue and would duplicate the existing one. Instead:48491. Verify the issue read-only with `gh issue view`, a `gh api` GET request, or a GitHub MCP issue read, and use its number as `${issue-num}`.502. Record a top-level `issue_adoption` object in the orchestrator checkpoint (`issue_num`, `issue_url`, `origin`, `verified_via`, `verified_at`, `evidence`, `waived_tools`, and, when a promotion-entry tool is waived, `potential_record`). For that waiver `potential_record` is required when `origin` is `epic_decomposition`, optional when `origin` is `transferred` or `filed_before_orchestration`, and validated whenever it is present. A valid record waives the `potential_to_issue` receipt requirement at completion.513. `delegation_receipts.promotion.issue` may be omitted, because no promotion receipt exists for an adopted issue.5253The field rules, the closed set of waivable tools, and the fail-closed behavior are defined in `.claude/rules/orchestrator-state.md` under `## Invariants (issue_adoption object)`.5455## Canonical Variables5657- `${promotion-type}`: `feature` or `bug`58- `${short-name}`: lowercase slug, hyphen-separated59- `${relativeFile}`: workspace-relative path to created potential entry markdown60- `${long-name}`: `${relativeFile}` filename without `.md`61- `${issue-num}`: promoted GitHub issue number62- `${feature-folder}`: active feature folder path63- `${plan-path}`: single canonical plan file path reused across planning and preflight revisions64- `${work-mode}`: `minor-audit`, `full-feature`, or `full-bug` (legacy `full` is accepted only as an alias for `full-feature`)65- `${short-path-flag}`: `--work-mode minor-audit` (mandatory for short-path promotion/folder creation)6667When orchestrator routing selects short path, promotion/folder initialization still occurs and MUST use `minor-audit` mode.68691) Use the same MCP tool-availability preflight described above and continue only when the required promotion tools are available.70712) Promote the potential document through `mcp__drm-copilot__potential_to_issue` with `work_mode=minor-audit`.72733) Create branch:74- `${promotion-type}/${short-name}-${issue-num}`75764) Create the active feature folder through `mcp__drm-copilot__new_active_feature_folder` with `work_mode=minor-audit`.77784a) Verify minor-audit folder integrity before proceeding:79- `${feature-folder}/issue.md` exists and contains `- Work Mode: minor-audit`80- `${feature-folder}/issue.md` contains an explicit `## Acceptance Criteria` section81- `${feature-folder}/spec.md` does not exist82- `${feature-folder}/user-story.md` does not exist83- the promoted record under `docs/features/potential/promoted/` is still present (see 4b)84- if any check fails, stop and remediate before planning85864b) Verify the promoted record was retained after `new_active_feature_folder`:87- the promoted file the earlier `potential_to_issue` step reported as its `destination_path` must still exist under `docs/features/potential/promoted/`88- `new_active_feature_folder` COPIES a promoted source into the active folder as `issue.md`; it MOVES a source resolved from `docs/features/potential/` directly. An absent promoted record after a promoted-source run is a defect, not expected cleanup (issue #487).89- this check applies to every work mode, not only `minor-audit`90915) Delegate minimal-audit plan creation to `atomic_planner` with directive:92- `DIRECTIVE: MINIMAL-AUDIT PLAN REQUIRED`93945a) Resolve and persist `${plan-path}` before delegation:95- reuse the earliest existing `plan*.md` in `${feature-folder}` when present96- otherwise create exactly one canonical plan file path and reuse it for all revisions97986) Require preflight validation via `atomic_executor` until:99- `PREFLIGHT: ALL CLEAR`1001017) Execute plan Phase 0 only via executor and checkpoint evidence.1021038) Branch:104- manual bootstrap: save state and stop,105- non-bootstrap: continue with constrained small-path development.1061079) Validate delivery via executor against `issue.md`, then run reduced audit/remediation loop until ready-to-merge.108109## Required Outputs for Downstream Handoffs110111Before delegating research/spec/planning, provide:112- `${feature-folder}/issue.md`113- `${feature-folder}/spec.md` (or expected target path)114- `${feature-folder}/user-story.md` (or explicit `NONE`)115- latest research artifact path(s)116- constraints/APIs/invariants to preserve117118Mode-aware expectations:119- For `minor-audit`, the explicit `## Acceptance Criteria` section in `issue.md` is the primary acceptance-criteria source and `spec.md`/`user-story.md` may be intentionally absent by design.120- For `minor-audit`, do not infer acceptance criteria from other `issue.md` sections such as verification notes, next steps, or severity checklists.121- For `minor-audit`, `spec.md`/`user-story.md` must be treated as integrity failures when they appear unexpectedly in the active folder.122- For `full-feature`, `spec.md` and `user-story.md` are expected alongside `issue.md`.123- For `full-bug`, `spec.md` is expected alongside `issue.md`; `user-story.md` should be absent unless the requirements explicitly justify it.124125Selected-mode persistence requirements:126- Producer outputs MUST persist exactly one marker in `issue.md` metadata above the first `##` heading:127 - `- Work Mode: minor-audit`128 - `- Work Mode: full-feature`129 - `- Work Mode: full-bug`130- Persisted marker MUST represent selected mode after eligibility checks, not requested mode.131- If a legacy requested `full` path is accepted, tooling MUST normalize it to `full-feature` before persistence.132- If a requested `minor-audit` path is rejected by eligibility checks, tooling MUST fail closed to `full-feature`, emit the downgrade reason, and persist `- Work Mode: full-feature`.133