refactor(voyage): S31 — V15 trim plan-export to headless-only (decompose alias)
Drop the pr/issue/markdown variants from `/trekplan --export`. Claude Code reformats a plan into a PR body, issue comment, or stripped markdown ad-hoc on request, so a dedicated export path added maintenance without value. Keep `--export headless` as a backwards-compatible alias for `--decompose` and relabel it as the decomposition entry it actually is. - commands/trekplan.md: Phase 1 parse rejects non-headless formats and sets mode = decompose for headless; delete the Export phase; rename Phase 1.6 → Phase 1.5 (Decompose); update the mode enum, argument-hint, and usage block. - docs/command-modes.md, README.md: export row relabeled as a --decompose alias. - tests/commands/trekplan.test.mjs: +2 V15 pins (variants gone, headless kept). Non-breaking (plan D-register). Tests 731 (729 pass / 2 skip / 0 fail), bar `node --test`; `claude plugin validate` green (1 accepted warning). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LqBYc8Ltrk7LipyJmGxXiB
This commit is contained in:
parent
6c00df573b
commit
9dc50a2047
4 changed files with 40 additions and 94 deletions
|
|
@ -236,7 +236,7 @@ Output:
|
|||
| **Foreground** | `/trekplan --project <dir> --fg` | No-op alias (foreground is default since v2.4.0) |
|
||||
| **Quick** | `/trekplan --project <dir> --quick` | No agent swarm, lightweight scan only |
|
||||
| **Decompose** | `/trekplan --decompose plan.md` | Split plan into headless session specs |
|
||||
| **Export** | `/trekplan --export pr plan.md` | PR description, issue comment, or clean markdown |
|
||||
| **Export** | `/trekplan --export headless plan.md` | Legacy alias for `--decompose` (the only remaining export format) |
|
||||
| **Profile** | `/trekplan --profile <name> --project <dir>` | (v4.1.0) Pin model profile; emitted as `profile:` in plan.md frontmatter. See [Profile system](#profile-system-v410). |
|
||||
|
||||
`--brief` or `--project` is **required**. `/trekplan` with no brief exits with an error and a pointer to `/trekbrief`.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
name: trekplan
|
||||
description: Deep implementation planning from a task brief. Requires --brief or --project. Runs parallel specialized agents, optional external research, and adversarial review.
|
||||
argument-hint: "--brief <path> | --project <dir> [--fg | --quick | --research <brief> | --decompose <plan> | --export <fmt> <plan>]"
|
||||
argument-hint: "--brief <path> | --project <dir> [--fg | --quick | --research <brief> | --decompose <plan> | --export headless <plan>]"
|
||||
model: opus
|
||||
allowed-tools: Agent, Read, Glob, Grep, Write, Edit, Bash, AskUserQuestion, TaskCreate, TaskUpdate, TeamCreate, TeamDelete
|
||||
---
|
||||
|
|
@ -30,13 +30,19 @@ Pipeline position:
|
|||
|
||||
Parse `$ARGUMENTS` for mode flags. Order of precedence:
|
||||
|
||||
1. **`--export <format> <plan-path>`** — extract `{format}` (first token after
|
||||
`--export`) and `{plan-path}` (remainder). Valid formats: `pr`, `issue`,
|
||||
`markdown`, `headless`. Set **mode = export**.
|
||||
1. **`--export headless <plan-path>`** — extract `{format}` (first token after
|
||||
`--export`) and `{plan-path}` (remainder). `headless` is the only export
|
||||
format; it is a backwards-compatible **alias for `--decompose`**. Set
|
||||
**mode = decompose** and run the decomposition pipeline (Phase 1.5).
|
||||
|
||||
If format is not in the valid set:
|
||||
The PR / issue / markdown export variants were removed — Claude Code
|
||||
reformats a plan into a PR body, issue comment, or stripped markdown
|
||||
ad-hoc on request, so a dedicated export path added maintenance without
|
||||
value. If `{format}` is anything other than `headless`:
|
||||
```
|
||||
Error: unknown export format '{format}'. Valid: pr, issue, markdown, headless
|
||||
Error: export format '{format}' is not supported. The only export is
|
||||
'headless' (an alias for --decompose). For PR / issue / markdown output,
|
||||
ask Claude to reformat the plan directly.
|
||||
```
|
||||
If the plan file does not exist:
|
||||
```
|
||||
|
|
@ -140,7 +146,7 @@ Usage: /trekplan --brief <path-to-brief.md>
|
|||
/trekplan --brief <path> --research <research-brief.md>
|
||||
/trekplan --project <dir> --fg
|
||||
/trekplan --project <dir> --quick
|
||||
/trekplan --export <pr|issue|markdown|headless> <plan-path>
|
||||
/trekplan --export headless <plan-path>
|
||||
/trekplan --decompose <plan-path>
|
||||
|
||||
A brief is required. Produce one with /trekbrief first.
|
||||
|
|
@ -152,7 +158,7 @@ Modes:
|
|||
--fg No-op alias (foreground is the only mode as of v2.4.0)
|
||||
--quick Skip exploration agent swarm; plan directly
|
||||
--min-brief-version <ver> Warn (never block) if the brief is older than <ver> (e.g. 2.2)
|
||||
--export Generate shareable output from an existing plan (no new planning)
|
||||
--export headless Legacy alias for --decompose (the only remaining export format)
|
||||
--decompose Split an existing plan into self-contained headless sessions
|
||||
|
||||
Examples:
|
||||
|
|
@ -160,7 +166,7 @@ Examples:
|
|||
/trekplan --brief .claude/projects/2026-04-18-jwt-auth/brief.md
|
||||
/trekplan --project .claude/projects/2026-04-18-jwt-auth --research extra.md
|
||||
/trekplan --project .claude/projects/2026-04-18-jwt-auth --fg
|
||||
/trekplan --export pr .claude/plans/trekplan-2026-04-06-rate-limiting.md
|
||||
/trekplan --export headless .claude/plans/trekplan-2026-04-06-rate-limiting.md
|
||||
/trekplan --decompose .claude/plans/trekplan-2026-04-06-rate-limiting.md
|
||||
|
||||
Migrating from v1.x? See MIGRATION.md in this plugin. The old --spec flag
|
||||
|
|
@ -187,7 +193,7 @@ If `research_status == pending` and `research_topics > 0`:
|
|||
|
||||
Report the detected mode:
|
||||
```
|
||||
Mode: {foreground | quick | export | decompose}
|
||||
Mode: {foreground | quick | decompose}
|
||||
Brief: {brief_path}
|
||||
Project: {project_dir or "-"}
|
||||
Research: {N local briefs, M extra via --research}
|
||||
|
|
@ -233,89 +239,10 @@ If `fm.type === 'trekreview'`:
|
|||
`type: brief` input simply omit the field. No `plan_version` bump is
|
||||
required for this addition (backwards compatible).
|
||||
|
||||
## Phase 1.5 — Export (runs only when mode = export)
|
||||
## Phase 1.5 — Decompose (runs only when mode = decompose)
|
||||
|
||||
**Skip this phase entirely unless mode = export.**
|
||||
|
||||
Read the plan file. Extract these sections from the plan content:
|
||||
- Task description (from Context section)
|
||||
- Implementation steps (from Implementation Plan section)
|
||||
- Risks (from Risks and Mitigations section)
|
||||
- Test strategy (from Test Strategy section, if present)
|
||||
- Scope estimate (from Estimated Scope section)
|
||||
|
||||
### Format: `pr`
|
||||
|
||||
Output a markdown block formatted as a PR description:
|
||||
|
||||
```
|
||||
## Summary
|
||||
|
||||
{2–3 sentence summary of what this change does and why}
|
||||
|
||||
## Changes
|
||||
|
||||
{Bulleted list of implementation steps, one line each}
|
||||
|
||||
## Test plan
|
||||
|
||||
{Bulleted checklist from test strategy, formatted as - [ ] items}
|
||||
|
||||
## Risks
|
||||
|
||||
{Risks from plan, abbreviated to 1 line each}
|
||||
|
||||
---
|
||||
*Generated by trekplan from {plan filename}*
|
||||
```
|
||||
|
||||
### Format: `issue`
|
||||
|
||||
Output a markdown block formatted as an issue comment:
|
||||
|
||||
```
|
||||
## Implementation plan summary
|
||||
|
||||
**Task:** {task description}
|
||||
**Plan file:** {plan path}
|
||||
**Scope:** {N files, complexity}
|
||||
|
||||
### Proposed approach
|
||||
{3–5 bullet points from key implementation steps}
|
||||
|
||||
### Open questions / risks
|
||||
{Top 2–3 risks from plan}
|
||||
|
||||
---
|
||||
*Generated by trekplan*
|
||||
```
|
||||
|
||||
### Format: `markdown`
|
||||
|
||||
Output the plan content with internal metadata stripped:
|
||||
- Remove the "Revisions" section
|
||||
- Remove plan-critic and scope-guardian scores/verdicts
|
||||
- Remove `[ASSUMPTION]` markers (but keep the surrounding sentence)
|
||||
- Keep everything else verbatim
|
||||
|
||||
### Format: `headless`
|
||||
|
||||
This is a shortcut for `--decompose`. It runs the full session decomposition
|
||||
pipeline and is equivalent to `--decompose {plan-path}`. Proceed to
|
||||
Phase 1.6 (Decompose) below.
|
||||
|
||||
---
|
||||
|
||||
After outputting the formatted block (for pr/issue/markdown), say:
|
||||
```
|
||||
Export complete ({format}). Copy the block above.
|
||||
```
|
||||
|
||||
Then **stop**. Do not continue to any subsequent phase.
|
||||
|
||||
## Phase 1.6 — Decompose (runs only when mode = decompose or export headless)
|
||||
|
||||
**Skip this phase entirely unless mode = decompose or export format = headless.**
|
||||
**Skip this phase entirely unless mode = decompose.** (`--export headless` is a
|
||||
backwards-compatible alias that sets mode = decompose, so it lands here too.)
|
||||
|
||||
Read the plan file. Verify it contains an Implementation Plan section with
|
||||
numbered steps. If no steps are found, report and stop:
|
||||
|
|
|
|||
|
|
@ -39,7 +39,7 @@ Flags combine: `--project <dir> --local`, `--external --quick`.
|
|||
| `--fg` | No-op alias (foreground is default since v2.4.0) |
|
||||
| `--quick` | Plan directly (no agent swarm) |
|
||||
| `--min-brief-version <ver>` | (S18) Warn — never block — if the brief declares a version below `<ver>` (e.g. `2.2`), i.e. sidesteps framing enforcement |
|
||||
| `--export <pr\|issue\|markdown\|headless> <plan>` | Generate shareable output from existing plan |
|
||||
| `--export headless <plan>` | Legacy alias for `--decompose` — the only remaining export format (the `pr` / `issue` / `markdown` variants were removed; Claude reformats a plan ad-hoc on request) |
|
||||
| `--decompose <plan>` | Split plan into self-contained headless sessions |
|
||||
| `--gates {true\|false}` | (v3.4.0) Boolean autonomy-gate flag; present → gating on. Policy (`gates_mode`) detailed under `## Autonomy mode` in `docs/operations.md`. |
|
||||
| `--profile <name>` | (v4.1.0) Model profile for the plan phase (and others, since plan emits `profile:` to plan.md frontmatter). |
|
||||
|
|
|
|||
|
|
@ -71,3 +71,22 @@ test('trekplan — SC7: brief_version 2.1 + no phase_signals + no partial → BR
|
|||
`sequencing gate must fire; errors=${JSON.stringify(r.errors)}`,
|
||||
);
|
||||
});
|
||||
|
||||
// --- S31 / V15: export trim — drop pr|issue|markdown, keep headless as a --decompose alias ---
|
||||
|
||||
test('trekplan — V15: pr/issue/markdown export variants are removed', () => {
|
||||
const text = read();
|
||||
// No remaining `--export pr` usage/example anywhere in the command.
|
||||
assert.equal(/--export\s+pr\b/.test(text), false, '`--export pr` must be gone');
|
||||
// The per-format subsections of the old Export phase must be deleted.
|
||||
assert.ok(!text.includes('Format: `pr`'), 'pr export-format section must be gone');
|
||||
assert.ok(!text.includes('Format: `issue`'), 'issue export-format section must be gone');
|
||||
assert.ok(!text.includes('Format: `markdown`'), 'markdown export-format section must be gone');
|
||||
});
|
||||
|
||||
test('trekplan — V15: --export headless survives as a --decompose alias', () => {
|
||||
const text = read();
|
||||
assert.match(text, /--export\s+headless/, '`--export headless` must remain documented');
|
||||
assert.match(text, /alias for [`*]*--decompose/i,
|
||||
'`--export headless` must be labeled an alias for --decompose');
|
||||
});
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue