diff --git a/README.md b/README.md index 87bc9d2..3c31d96 100644 --- a/README.md +++ b/README.md @@ -236,7 +236,7 @@ Output: | **Foreground** | `/trekplan --project --fg` | No-op alias (foreground is default since v2.4.0) | | **Quick** | `/trekplan --project --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 --project ` | (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`. diff --git a/commands/trekplan.md b/commands/trekplan.md index f6f2b1f..8f98662 100644 --- a/commands/trekplan.md +++ b/commands/trekplan.md @@ -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 | --project [--fg | --quick | --research | --decompose | --export ]" +argument-hint: "--brief | --project [--fg | --quick | --research | --decompose | --export headless ]" 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 `** — extract `{format}` (first token after - `--export`) and `{plan-path}` (remainder). Valid formats: `pr`, `issue`, - `markdown`, `headless`. Set **mode = export**. +1. **`--export headless `** — 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 /trekplan --brief --research /trekplan --project --fg /trekplan --project --quick - /trekplan --export + /trekplan --export headless /trekplan --decompose 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 Warn (never block) if the brief is older than (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: diff --git a/docs/command-modes.md b/docs/command-modes.md index 01c28e9..e68cf0a 100644 --- a/docs/command-modes.md +++ b/docs/command-modes.md @@ -39,7 +39,7 @@ Flags combine: `--project --local`, `--external --quick`. | `--fg` | No-op alias (foreground is default since v2.4.0) | | `--quick` | Plan directly (no agent swarm) | | `--min-brief-version ` | (S18) Warn — never block — if the brief declares a version below `` (e.g. `2.2`), i.e. sidesteps framing enforcement | -| `--export ` | Generate shareable output from existing plan | +| `--export headless ` | 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 ` | 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 ` | (v4.1.0) Model profile for the plan phase (and others, since plan emits `profile:` to plan.md frontmatter). | diff --git a/tests/commands/trekplan.test.mjs b/tests/commands/trekplan.test.mjs index 1ab3ee0..f9f996f 100644 --- a/tests/commands/trekplan.test.mjs +++ b/tests/commands/trekplan.test.mjs @@ -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'); +});