feat(product): add /ensemble:feature pipeline orchestration command

[ldangelo]

Summary

• Adds new /ensemble:feature command (packages/product/commands/feature.yaml) that orchestrates the full idea-to-plan pipeline as a single invocation
• Adds --plan and --execute flags to /ensemble:implement-trd-beads for split scaffold/execute workflows
• Bumps ensemble-development → 5.7.0, ensemble-product → 5.5.0, ensemble-full → 5.7.0, marketplace → 5.7.0

New command: /ensemble:feature

Runs five commands in strict sequence:

1. /ensemble:create-prd <description> — creates PRD, captures PRD_PATH
2. /ensemble:refine-prd — user interview (skipped with --skip-refine)
3. /ensemble:create-trd <PRD_PATH> — creates TRD, captures TRD_PATH
4. /ensemble:refine-trd — user interview (skipped with --skip-refine)
5. /ensemble:implement-trd-beads <TRD_PATH> --plan — scaffold only, never executes code

Ends with a handoff message showing PRD_PATH, TRD_PATH, and how to proceed:

• /ensemble:implement-trd-beads --execute in current window
• ntm in a new window

Flags:

• --skip-refine — bypasses steps 2 and 4 for an uninterrupted run
• Step failures halt the pipeline with a diagnostic message and retry command

Changes to /ensemble:implement-trd-beads

• --plan — runs Scaffold phase only (creates bead hierarchy), then exits; use when you want to review the plan before executing
• --execute — skips Scaffold, runs Execute phase against existing beads; errors if no scaffold exists
• Mutual exclusion enforced: using both flags together prints an error and exits
• implement-trd-beads.yaml bumped to 2.6.0

Test plan

• Run /ensemble:feature "Add dark mode to settings panel" — verify 5-step progress indicators and handoff message
• Run /ensemble:feature "Add search" --skip-refine — verify steps 2 and 4 show (skipped)
• Run /ensemble:feature with no args — verify usage message, no pipeline steps execute
• Run /ensemble:feature "test" --unknown-flag — verify unknown flag error
• Run /ensemble:implement-trd-beads <trd> --plan — verify scaffold creates beads then exits without executing
• Run /ensemble:implement-trd-beads <trd> --execute — verify skips scaffold, runs against existing beads
• Run /ensemble:implement-trd-beads <trd> --plan --execute — verify mutual exclusion error
• Run npm run validate — verify all plugins pass

🤖 Generated with Claude Code

[claude]

PR Review: feat(product): add /ensemble:feature pipeline orchestration command

Summary

This PR introduces a new /ensemble:feature command that chains five existing commands (create-prd → refine-prd → create-trd → refine-trd → implement-trd-beads --plan) into a single invocation, and adds --plan / --execute split-mode flags to implement-trd-beads. Version bumps are consistent across packages and marketplace.

⚠️ CI status: all 4 checks failing. This is the primary blocker.

---

🔴 Critical Issues

1. All CI checks are failing

validate, generate, and both test (20) and test (22) are failing. Most likely causes:

• Schema validation (validate): feature.yaml is missing the allowed_tools field, which is likely required by schemas/command-yaml-schema.json (see feat: Rename ai-mesh to ensemble (v5.0.0) #2 below).
• Generate mismatch (generate): If the generator produces slightly different output than the committed feature.md, the check fails. Re-run npm run generate locally and recommit.
• Test failures: Likely snapshot or manifest tests that validate command structure or marketplace entries.

Action required: Run npm run validate, npm run generate, and npm test locally; fix all errors before merge.

2. feature.yaml missing allowed_tools

feature.yaml has no allowed_tools field — other commands like implement-trd-beads.yaml declare this explicitly. The command uses Glob to detect PRD/TRD files, so at minimum:

allowed_tools:
  - Glob

This omission is likely the direct cause of the validate CI failure.

---

🟡 Bugs / Logic Issues

3. PRD/TRD path detection via glob-by-mtime is fragile (Phase 2, Steps 1 & 3)

Detecting the output file by finding "the most recently modified .md" in docs/PRD/ and docs/TRD/ is a race-condition-prone heuristic. If refine-prd touches an existing file more recently than the newly created one, PRD_PATH could resolve incorrectly. Since create-prd and create-trd return the output path directly, capturing that return value would be more reliable.

4. Step 5 retry hint omits TRD_PATH

When implement-trd-beads --plan fails, the retry message shown is:

/ensemble:implement-trd-beads --plan

This omits the required TRD_PATH argument. Steps 1 and 3 correctly include the file path in their retry hints — Step 5 should follow the same pattern:

/ensemble:implement-trd-beads <TRD_PATH> --plan

5. "wheel instructions" comment is stale in implement-trd-beads.yaml

The action description at the top of the Handle Special Arguments section says "print wheel instructions and exit after scaffold completes" but the actual exit message says "Plan complete…". This leftover text should be updated to avoid confusing future maintainers.

6. --execute with no TRD_PATH gives a misleading error

When --execute is used without a trd-path, TRD_SLUG will be undefined and the scaffold lookup silently fails with "no existing scaffold found" rather than "no TRD path provided". A guard at the top of argument parsing ("if --execute and no trd-path, print usage and exit") would give a much clearer error.

---

✅ What's Done Well

• Dual-source-of-truth pattern is correctly followed: feature.yaml is the source, feature.md is generated and carries the <!-- DO NOT EDIT --> header. Consistent with the rest of the codebase.
• Version bumps are internally consistent: ensemble-development, ensemble-product, ensemble-full, and marketplace.json all bump together correctly.
• constraints block is well-designed: Explicitly hardcodes --plan, forbids forwarding $ARGUMENTS to sub-commands, and forbids code execution. Clean separation of planning vs. implementation.
• --plan/--execute mutual exclusion check ordering is correct: Error check comes before individual flag checks.
• PRD and TRD are thorough: The supporting docs are well-structured and detailed.

---

🔵 Minor / Improvements

• No automated tests added: The PR's test plan is entirely manual. Given the repo has a Jest convention per package, regression tests for --plan/--execute argument parsing and mutual exclusion would improve confidence and prevent regressions.
• CLAUDE.md Quick Reference not updated: The slash commands table doesn't include /ensemble:feature — a minor omission for discoverability.

---

Summary Table

Category	Finding	Severity
CI	All 4 checks failing	🔴 Blocker
Bug	feature.yaml missing allowed_tools (likely schema failure cause)	🔴 High
Bug	PRD/TRD path detection via glob-by-mtime is fragile	🟡 Medium
Bug	Step 5 retry hint omits TRD_PATH argument	🟡 Medium
Bug	--execute without trd-path gives misleading error	🟡 Medium
Inconsistency	Stale "wheel instructions" text in --plan action description	🔵 Low
Coverage	No automated tests for new argument-parsing logic	🔵 Low
Docs	CLAUDE.md Quick Reference not updated for new command	🔵 Low

The core concept is solid and the architecture is consistent with the existing plugin conventions. Resolve the CI blockers (especially the missing allowed_tools field and the generate mismatch) and address the medium-severity path detection bugs before merging.

---

Reviewed by Claude Sonnet 4.6

[claude]

PR Review: feat(product) pipeline orchestration - see inline comments for details

[claude]

test2

[claude]

PR Review: feat(product): add /ensemble:feature pipeline orchestration command

This PR introduces the /ensemble:feature command (a five-step idea-to-plan pipeline orchestrator) and adds --plan/--execute split-workflow flags to /ensemble:implement-trd-beads. The implementation is well-structured, ships with thorough PRD and TRD documentation, and follows existing YAML command conventions correctly.

---

Bugs / Logic Issues

1. feature.yaml Step 5 retry command omits TRD_PATH

In packages/product/commands/feature.yaml around the Step 5 retry instructions:

To retry from this step, run:
  /ensemble:implement-trd-beads --plan

Step 3's retry template correctly includes <PRD_PATH>, but Step 5 drops <TRD_PATH>. Without it, the retry falls back to the ambient TRD selection heuristic (most recent, or prompt user), which may pick the wrong file when multiple TRDs are present. The same omission appears in the generated packages/product/commands/ensemble/feature.md.

Fix: Update to /ensemble:implement-trd-beads <TRD_PATH> --plan

---

2. --execute flag documentation missing dirty-working-directory warning

When EXECUTE_ONLY=true, Preflight Step 3 still runs git status --porcelain and halts on a dirty working directory. This is pre-existing behavior, but the new --execute flag's argument_hint doesn't mention it. Users picking up a prior scaffold (--execute) will be surprised when uncommitted WIP blocks execution.

Fix: Add a note to the argument_hint for --execute that the working directory must be clean.

---

3. Prose -- in feature descriptions triggers "Unknown flag" error

Phase 1 Step 3 scans for -- tokens after removing --skip-refine. A feature description like /ensemble:feature "Support legacy -- deprecated API modes" will hit the "Unknown flag" error path. This is a known LLM argument-parsing limitation but should be documented.

Fix: Add a constraints: entry noting that -- is reserved as a flag prefix and cannot appear in prose arguments.

---

Design Observations

4. PRD/TRD path capture via "most recently modified" Glob is fragile

Steps 1 and 3 use Glob to find the most recently modified .md file in docs/PRD/ (and docs/TRD/) to capture PRD_PATH/TRD_PATH. This is a timing-dependent heuristic — coarse mtime resolution or concurrent writes (CI, parallel sessions) could capture the wrong file. Risk R1 in the TRD covers constituent-command changes but not concurrent writes.

Suggestion for v1.1.0: Contract with create-prd/create-trd to emit the output path as their last line, captured directly rather than inferred from filesystem state.

---

5. Handoff message inconsistency between feature.yaml and PRD Appendix 11.2

feature.yaml emits:

In this window:    /ensemble:implement-trd-beads <TRD_PATH> --execute

PRD Section 4.8 (REQ-010) and Appendix 11.2 show:

In this window:    /ensemble:implement-trd-beads --execute

The YAML form (with TRD_PATH) is more correct, but this means AC-010-2 ("message includes the exact command /ensemble:implement-trd-beads --execute") fails against the actual output. Minor, but the PRD's acceptance criterion should be updated to match.

---

Test Coverage

6. No automated regression guard for pipeline sequencing

All verification methods in the sprint plan are manual. This is an inherent limitation of the YAML-as-agentic-instructions pattern across the ensemble codebase, not specific to this PR. However, if implement-trd-beads or constituent commands change in ways that conflict with feature.yaml's invocation assumptions (e.g., the --plan passthrough, the PLAN_ONLY/EXECUTE_ONLY gate positions), no test will catch it. Worth tracking as a known gap in the test suite.

---

Positive Highlights

• The fail-fast pipeline design (halt on constituent command failure, expose checkpoint commands for retry) is well thought out and clearly documented in TRD sections 3.1–3.3.
• The --skip-refine flag is a good ergonomic addition for experienced users who want to bypass the interactive refinement step.
• Version bumps are consistent across all four locations (package.json files + marketplace.json).
• The self-referential nature of the PR ("dog-fooding" the feature pipeline to build the feature pipeline) is acknowledged and appropriate.

---

Summary

The main actionable items before merge:

1. Fix the Step 5 retry command to include TRD_PATH (feature.yaml, feature.md)
2. Document the --execute dirty-working-directory behavior in the argument hint
3. Document the prose -- character limitation in argument constraints
4. Align PRD AC-010-2 with the actual TRD_PATH-inclusive handoff command

Items 4 and the design observations are lower-priority and can be addressed in follow-up issues if preferred.

🤖 Generated with Claude Code

[claude]

PR Review: feat(product) - /ensemble:feature pipeline orchestration

Overall: Good concept and well-structured orchestration design. The pipeline sequencing is clear and the --plan/--execute split in implement-trd-beads is a useful addition. However, there are CI failures to address and a few correctness issues worth fixing before merge.

CI Failures (all checks failing: generate, test, validate)

All three required CI checks are failing. The most likely causes based on code inspection:

1. feature.yaml is missing allowed_tools - The command uses Glob internally to find PRD/TRD paths, but allowed_tools is not declared in metadata. Compare with implement-trd-beads.yaml which declares allowed_tools. Add:

allowed_tools:
  - Glob

2. feature.md was hand-authored, not generated - The DO NOT EDIT header is present, but npm run generate must be run to produce the canonical output. If the generated output differs from the checked-in .md, the generate CI check will fail. Run npm run generate and commit the result.

Correctness Issues

Fragile PRD/TRD path capture (Steps 1 and 3)

Using Glob on the most recently modified .md file in docs/PRD/ is brittle. If a prior run left a stale file with a newer mtime, or if create-prd fails partway and leaves a partial file, the wrong path gets captured silently.

Step 5 retry hint is incomplete

When Step 5 fails, the retry message shown to the user is missing TRD_PATH. Current message: /ensemble:implement-trd-beads --plan. Should be: /ensemble:implement-trd-beads <TRD_PATH> --plan. Same issue in implement-trd-beads for the PLAN_ONLY exit message - it says 'Run /ensemble:implement-trd-beads --execute to begin implementation' without including the TRD path.

'print wheel instructions' placeholder in implement-trd-beads

The action 'print wheel instructions' reads as an unresolved internal note. The actual exit message is defined correctly later in the file, but this parenthetical is confusing. Clarify or remove it.

Minor Issues

• Date inconsistency in feature.md: Has last-updated: 2026-03-15 while all other changes in this PR use 2026-03-16. Non-issue if regenerated; otherwise update.
• No tests for new command: packages/product/tests/ only has .gitkeep. The feature.yaml flag-parsing logic (empty args, unknown flags, --skip-refine stripping) is a good candidate for unit tests.
• --execute without TRD path - undocumented behavior: The handoff message instructs users to run /ensemble:implement-trd-beads --execute without a TRD path. How does the command determine which TRD to use? If the bead scaffold encodes this implicitly, document it in the argument-hint.

What's Working Well

• The constraints block in feature.yaml is excellent - explicitly preventing --execute from being forwarded and prohibiting implementation work are the right guardrails.
• Sequential pipeline with fail-fast semantics and per-step retry hints is user-friendly.
• Mutual exclusion check for --plan --execute at the top of argument handling is the correct placement.
• Version bumps are consistent across package.json, marketplace.json, and command YAML.

Summary

Priority	Issue
Blocking (CI)	Add allowed_tools: [Glob] to feature.yaml
Blocking (CI)	Run npm run generate and commit result
Correctness	Fix Step 5 retry hint to include TRD_PATH
Correctness	Fix PLAN_ONLY handoff message to include TRD path
Minor	Clarify 'print wheel instructions' placeholder

Reviewed by Claude Code