@zhuk/spego 0.6.2 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## [0.8.0] - 2026-05-22
+
+### Added
+- Combined OpenSpec + spego workflow skills: `change-brainstorm`, `change-review`, `change-verify-report`, and `change-retro`.
+- README guidance for before/during/after OpenSpec change lanes with spego persistence checkpoints.
+
+## [0.7.0] - 2026-05-14
+
+### Changed
+- **CLI output modes**: every command now emits pretty human-friendly output by default and JSON when the global `--json` flag is supplied. Human output uses bordered boxes (`╭─ ─╮`), aligned tables, single-emoji section headers (`📦 📄 🛠️ 🧭 📚 ✅`), and `────` dividers. Errors render as `⚠️  [CODE] message` in human mode and as the existing `{ error: { code, message, details } }` envelope in JSON mode.
+- **`spego commands` and `spego workflows` default-mode flip**: these commands used to print JSON unconditionally; they now print human output by default. Agents and scripts that pipe their stdout MUST pass `--json` to keep getting JSON.
+- **`spego regenerate` → `spego skills`**: renamed for clarity. `spego regenerate` remains as a hidden alias for one minor release with a deprecation warning. Running `spego skills` also cleans up any legacy `spego-regenerate` generated paths.
+
+### Deprecated
+- **`spego view --format <fmt>`**: superseded by the global `--json` flag. Continues to work for one minor release; emits a single `deprecated:` warning line to stderr in human mode. Will be removed in the next minor release.
+- **`spego regenerate`**: renamed to `spego skills`. The hidden alias continues to work for one minor release and emits a deprecation warning in human mode. Will be removed in the next minor release.
+
 ## [0.6.2] - 2026-05-14
 
 ### Fixed

package/README.md

@@ -22,14 +22,25 @@ spego init --agents claude --demo false
 | `spego delete --id <uuid>` | Soft-delete (preserves history) |
 | `spego list` | List artifacts |
 | `spego view` | Export bundle as markdown or JSON |
-| `spego commands` | List command metadata (JSON) |
-| `spego workflows` | List workflow skills metadata (JSON) |
-| `spego regenerate` | Regenerate agent skill files |
+| `spego commands` | List command metadata |
+| `spego workflows` | List workflow skills metadata |
+| `spego skills` | Regenerate agent skill files |
 | `spego epics` | List delivery epics |
 | `spego tasks --change <name>` | List tasks for a change |
 | `spego index rebuild` | Rebuild SQLite index from files |
 
-All commands accept `--json` for structured output and `--cwd <dir>` to set the project root.
+All commands accept `--cwd <dir>` to set the project root.
+
+### Output modes
+
+Every spego command speaks two output modes:
+
+- **Human (default)** — pretty, scannable output for terminals. Section headers use a single emoji prefix (`📦 📄 🛠️ 🧭 📚 ✅`), summaries render as bordered boxes (`╭─ … ─╮`), lists render as aligned tables, and `view` separates artifacts with `────` dividers. Errors print as `⚠️  [CODE] message` to stderr.
+- **JSON (opt-in)** — pass the global `--json` flag to get deterministic, decoration-free JSON on stdout. Errors come back as `{ "error": { "code", "message", "details" } }` on stderr.
+
+Agents calling spego MUST pass `--json` so they get parseable output. Humans normally do not.
+
+The legacy `spego view --format markdown|json` flag is **deprecated** and will be removed in the next minor release. Use the global `--json` flag instead. The old flag still works during the deprecation window and prints a single `deprecated:` warning line to stderr.
 
 ## Architecture
 
@@ -61,6 +72,21 @@ deliveryAdapter:
   options: {}
 ```
 
+## OpenSpec Delivery View
+
+The default delivery adapter is OpenSpec. `spego epics` exposes active OpenSpec changes as delivery epics, and `spego tasks --change <name>` exposes checklist items from the change's `tasks.md`.
+
+The adapter is read-only. It observes OpenSpec state but does not create, continue, apply, verify, sync, or archive OpenSpec changes.
+
+| Source | spego view |
+|--------|------------|
+| `openspec/changes/<name>/proposal.md` | Epic title |
+| `openspec/changes/<name>/tasks.md` | Task summaries |
+| `openspec status --change <name> --json` | Preferred status source |
+| Filesystem parsing | Fallback when the OpenSpec CLI is unavailable |
+
+Archived changes under `openspec/changes/archive/` are excluded. A change with no `tasks.md` is reported as `planning-incomplete`.
+
 ## Generated Files
 
 For Claude agent targets, `spego init` generates:
@@ -68,7 +94,7 @@ For Claude agent targets, `spego init` generates:
 - `.claude/skills/spego-<command>/SKILL.md` — skill definitions following Claude Code conventions
 - `.claude/commands/spego/` — slash command wrappers
 
-Run `spego regenerate` to update generated files without reinitializing the workspace.
+Run `spego skills` to update generated files without reinitializing the workspace.
 
 ## Workflow Skills
 
@@ -125,6 +151,42 @@ Use when you have a focused problem and want maximum idea throughput without per
 | One voice, fast iteration | `brainstorm-deep` |
 | Multiple viewpoints, stress-test ideas | `brainstorm-party` |
 
+### Combined OpenSpec + spego workflows
+
+OpenSpec prompts and spego workflow skills are separate surfaces:
+
+- OPSX/OpenSpec prompts live under `.claude/commands/opsx/` and `.claude/skills/openspec-*/`.
+- spego-generated commands and workflow skills live under `.claude/commands/spego/` and `.claude/skills/spego-*/`.
+
+OpenSpec owns change execution and lifecycle state: proposal, design, specs, tasks, apply, verify, sync, and archive. spego owns durable product-thinking artifacts: `brainstorm`, `qa`, `risk`, and `retro`. The OpenSpec delivery adapter exposed through `spego epics` and `spego tasks` is read-only.
+
+Use combined workflows when an OpenSpec change needs durable thinking around it:
+
+| Lane | OpenSpec action | spego action |
+|------|-----------------|--------------|
+| Before implementation | Create or continue a change with OPSX/OpenSpec, then read `proposal.md`, `design.md`, specs, and `tasks.md` | `spego-change-brainstorm` creates a `brainstorm` artifact |
+| During implementation | Keep task state and artifact mutations in OPSX/OpenSpec | `spego-change-review` creates `qa` or `risk` findings |
+| Before archive | Run OPSX/OpenSpec verification | `spego-change-verify-report` creates a `qa` verification report |
+| After completion | Archive or complete the OpenSpec change | `spego-change-retro` creates a `retro` artifact |
+
+Example read-only context commands:
+
+```sh
+spego epics --json
+spego tasks --change <change-name> --json
+```
+
+Example spego persistence checkpoints:
+
+```sh
+spego --json create --type brainstorm --title "<change-name> brainstorm" --body "<brainstorm output>"
+spego --json create --type qa --title "<change-name> review" --body "<quality findings>"
+spego --json create --type risk --title "<change-name> risks" --body "<risk findings>"
+spego --json create --type retro --title "<change-name> retro" --body "<retrospective>"
+```
+
+If a combined workflow discovers that OpenSpec artifacts need to change, use the matching OPSX/OpenSpec command. Do not mutate OpenSpec lifecycle state through spego.
+
 ### elicit
 
 Iterative refinement of an existing artifact using named methods (clarify, sharpen, generalize, specialize, stress-test, contextualize, simplify, formalize). A single Refiner persona proposes changes, confirms with the user, and applies via `spego update --expected-revision`. Maximum 5 cycles per session. Outputs a `qa` summary and in-place updates of the source artifact.

package/dist/cli/render.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Pretty-rendering primitives for the spego CLI human output mode.
+ *
+ * All functions are pure: string in, string out. They MUST NOT read
+ * `process.env`, MUST NOT detect TTY, and MUST NOT emit ANSI color codes.
+ * Output is plain text plus a small fixed set of Unicode box-drawing and
+ * arrow characters so it stays scannable, copy-pasteable, and stable across
+ * terminals.
+ */
+/** Truncate `value` to fit within `width` characters, appending `…` when cut. */
+export declare function truncate(value: string, width: number): string;
+/** Right-pad `value` with spaces to `width` characters. Strings longer than `width` are returned unchanged. */
+export declare function padRight(value: string, width: number): string;
+/**
+ * Render a bordered key/value summary box using rounded box-drawing characters.
+ *
+ * ```
+ * ╭─ Workspace ─────────────────────────╮
+ * │ root    /tmp/proj                   │
+ * │ agents  claude                      │
+ * ╰─────────────────────────────────────╯
+ * ```
+ */
+export declare function renderBox(title: string, rows: Array<[string, string]>): string;
+/**
+ * Render an aligned table with a header row separated from data rows by `─`.
+ *
+ * ```
+ * type/slug      rev  title
+ * ─────────────  ───  ──────────────
+ * prd/test-prd   1    Test PRD
+ * ```
+ *
+ * `opts.maxWidth` caps each column width and truncates longer cells with `…`
+ * (default 60). An empty `rows` array still renders the header and divider
+ * so callers can prepend a "no rows" hint above if they choose.
+ */
+export declare function renderTable(columns: string[], rows: string[][], opts?: {
+    maxWidth?: number;
+}): string;
+/** Render a single-line section header prefixed by an emoji. */
+export declare function renderHeader(emoji: string, label: string): string;
+/** Render a `─` divider of the given width (default 60). */
+export declare function renderDivider(width?: number): string;

package/dist/cli/render.js

@@ -0,0 +1,90 @@
+/**
+ * Pretty-rendering primitives for the spego CLI human output mode.
+ *
+ * All functions are pure: string in, string out. They MUST NOT read
+ * `process.env`, MUST NOT detect TTY, and MUST NOT emit ANSI color codes.
+ * Output is plain text plus a small fixed set of Unicode box-drawing and
+ * arrow characters so it stays scannable, copy-pasteable, and stable across
+ * terminals.
+ */
+const DEFAULT_TABLE_MAX_WIDTH = 60;
+/** Truncate `value` to fit within `width` characters, appending `…` when cut. */
+export function truncate(value, width) {
+    if (width <= 0)
+        return '';
+    if (value.length <= width)
+        return value;
+    if (width === 1)
+        return '…';
+    return value.slice(0, width - 1) + '…';
+}
+/** Right-pad `value` with spaces to `width` characters. Strings longer than `width` are returned unchanged. */
+export function padRight(value, width) {
+    if (value.length >= width)
+        return value;
+    return value + ' '.repeat(width - value.length);
+}
+/**
+ * Render a bordered key/value summary box using rounded box-drawing characters.
+ *
+ * ```
+ * ╭─ Workspace ─────────────────────────╮
+ * │ root    /tmp/proj                   │
+ * │ agents  claude                      │
+ * ╰─────────────────────────────────────╯
+ * ```
+ */
+export function renderBox(title, rows) {
+    const keyWidth = rows.reduce((m, [k]) => Math.max(m, k.length), 0);
+    const valueWidth = rows.reduce((m, [, v]) => Math.max(m, v.length), 0);
+    // Inner content width: key + 2 spaces + value
+    const contentWidth = Math.max(keyWidth + 2 + valueWidth, title.length + 4);
+    const innerWidth = contentWidth + 2; // 1 space padding on each side
+    // Title row: `╭─ <title> <N×─>╮`. Body row width is `contentWidth + 4`
+    // (`│ ` + content + ` │`); title row width is `5 + title.length + N`,
+    // so N = contentWidth - title.length - 1 to keep both rows equal.
+    const titleLine = `╭─ ${title} ${'─'.repeat(Math.max(0, contentWidth - title.length - 1))}╮`;
+    const bottom = `╰${'─'.repeat(innerWidth)}╯`;
+    const body = rows
+        .map(([k, v]) => {
+        const line = `${padRight(k, keyWidth)}  ${v}`;
+        return `│ ${padRight(line, contentWidth)} │`;
+    })
+        .join('\n');
+    return rows.length === 0 ? `${titleLine}\n${bottom}` : `${titleLine}\n${body}\n${bottom}`;
+}
+/**
+ * Render an aligned table with a header row separated from data rows by `─`.
+ *
+ * ```
+ * type/slug      rev  title
+ * ─────────────  ───  ──────────────
+ * prd/test-prd   1    Test PRD
+ * ```
+ *
+ * `opts.maxWidth` caps each column width and truncates longer cells with `…`
+ * (default 60). An empty `rows` array still renders the header and divider
+ * so callers can prepend a "no rows" hint above if they choose.
+ */
+export function renderTable(columns, rows, opts = {}) {
+    const maxWidth = opts.maxWidth ?? DEFAULT_TABLE_MAX_WIDTH;
+    const widths = columns.map((col, i) => {
+        const dataMax = rows.reduce((m, r) => Math.max(m, (r[i] ?? '').length), 0);
+        const target = Math.max(col.length, dataMax);
+        return Math.min(target, maxWidth);
+    });
+    const formatRow = (cells) => widths.map((w, i) => padRight(truncate(cells[i] ?? '', w), w)).join('  ').trimEnd();
+    const header = formatRow(columns);
+    const divider = widths.map((w) => '─'.repeat(w)).join('  ').trimEnd();
+    const body = rows.map(formatRow).join('\n');
+    return rows.length === 0 ? `${header}\n${divider}` : `${header}\n${divider}\n${body}`;
+}
+/** Render a single-line section header prefixed by an emoji. */
+export function renderHeader(emoji, label) {
+    return `${emoji} ${label}`;
+}
+/** Render a `─` divider of the given width (default 60). */
+export function renderDivider(width = 60) {
+    return '─'.repeat(Math.max(1, width));
+}
+//# sourceMappingURL=render.js.map

package/dist/cli/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../../src/cli/render.ts"],"names":[],"mappings":"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"}