@zhuk/spego 0.3.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Changelog
 
+## [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
+- Replaced hardcoded local path in authoring workflow test with repo-relative root so tests pass on CI.
+- Use lightweight git tag for npm trusted publishing (OIDC) compatibility.
+
+## [0.6.0] - 2026-05-13
+
+### Added
+- `help` workflow: read-only orientation skill that inspects workspace state and recommends next steps via in-chat recommendations.
+- `brainstorm-deep` workflow: single-persona, high-volume ideation targeting 50-100 ideas with clustering and ranking. Outputs `brainstorm` artifact.
+- `elicit` workflow: iterative refinement using named methods (clarify, sharpen, generalize, specialize, stress-test, contextualize, simplify, formalize) with optimistic concurrency. Maximum 5 cycles per session.
+- `kind` field on `WorkflowOutput` to distinguish `create`, `update`, and `none` output types.
+- "Authoring loop" guidance and "brainstorm-deep vs brainstorm-party" matrix in README.
+- Authoring workflow registry and content tests.
+
+## [0.5.0] - 2026-05-13
+
+### Added
+- `review-edge-cases` workflow: method-driven edge-case enumeration (Path-tracer, Boundary-checker, Concurrency-skeptic personas). Outputs `qa` artifact with JSON findings array.
+- `editorial-prose` workflow: clinical copy-edit pass (Copy-editor persona). Applies confirmed edits in place via `spego update --expected-revision`. Outputs `qa` summary artifact.
+- `editorial-structure` workflow: structural review without mutation (Structural editor persona). Outputs `qa` artifact with prioritized restructuring recommendations.
+- Review suite registry and content tests.
+- "Complementary reviews" guidance in README.
+
+## [0.4.0] - 2026-05-12
+
+### Added
+- Workflow skills as a first-class concept alongside command skills.
+- `WORKFLOW_REGISTRY` with two reference workflows: `brainstorm-party` and `review-adversarial`.
+- `spego workflows` command listing workflow metadata as JSON.
+- Generator emits workflow skill files at `.claude/skills/spego-<workflow>/SKILL.md`.
+- Legacy flat-file cleanup covers workflow skill names.
+- Workflow and command skill coexistence tests, CLI tests, and legacy cleanup tests.
+
 ## [0.3.0] - 2026-05-11
 
 ### Changed

package/README.md

@@ -22,13 +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 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
 
@@ -67,7 +79,90 @@ 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
+
+Workflow skills guide an agent through a multi-persona process inside the chat, persisting results as spego artifacts at well-defined checkpoints.
+
+### brainstorm-party
+
+Multi-persona collaborative brainstorming. Six roles (PM, Architect, UX, Dev, QA, Skeptic) take turns framing, expanding, challenging, and converging on ideas. Outputs a `brainstorm` artifact and optionally drafts a follow-up `prd` or `design`.
+
+Use when exploring a problem space broadly or stress-testing a concept before committing.
+
+### review-adversarial
+
+Adversarial critique of an existing artifact. Five roles (Skeptic, Security, Reliability, UX, Cost) attack from different angles, surface gaps, and prioritize findings. Outputs a `qa` or `risk` artifact and optionally a `decision` or `retro`.
+
+Use when you need rigorous review before approval or implementation.
+
+### review-edge-cases
+
+Method-driven edge-case enumeration. Three roles (Path-tracer, Boundary-checker, Concurrency-skeptic) mechanically trace branching paths, derive edge classes (off-by-one, unguarded inputs, missing else/default, race conditions, timeout gaps), filter already-handled cases, and report only unhandled paths. Outputs a `qa` artifact with a fenced JSON array of findings.
+
+Use when you need to find logic defects that adversarial review may miss.
+
+### editorial-prose
+
+Clinical copy-edit pass. A single Copy-editor persona identifies ambiguous sentences, unnecessary jargon, long sentences, passive voice, and redundancy. Confirmed edits are applied in place via `spego update` with `--expected-revision`; declined edits are recorded as recommendations. Outputs a `qa` artifact summarizing all edits.
+
+Use when the artifact's ideas are sound but the prose needs tightening.
+
+### editorial-structure
+
+Structural review without mutation. A single Structural editor persona outlines the current structure, proposes cuts/merges/reorders/splits, and produces a prioritized recommendation list. Does not modify the source artifact. Outputs a `qa` artifact with restructuring recommendations.
+
+Use when content is correct but organization needs improvement.
+
+### help
+
+Orientation workflow that reads workspace state and recommends next steps. A single Guide persona runs `spego status`, `spego list`, and `spego epics` to inspect the workspace, then applies a recommendation rubric to suggest the most impactful action. Produces no artifact — recommendations are delivered in chat only.
+
+Use when starting a new session, unsure what to do next, or asking "what should I work on?".
+
+### brainstorm-deep
+
+Single-persona, high-volume ideation targeting 50-100 ideas on a focused topic. One Ideator persona generates breadth, then clusters, deduplicates, and ranks the output. Outputs a `brainstorm` artifact.
+
+Use when you have a focused problem and want maximum idea throughput without persona debate.
+
+**When to use brainstorm-deep vs brainstorm-party:**
+
+| Scenario | Use |
+|----------|-----|
+| Focused problem, need volume | `brainstorm-deep` |
+| Broad problem, need diverse perspectives | `brainstorm-party` |
+| One voice, fast iteration | `brainstorm-deep` |
+| Multiple viewpoints, stress-test ideas | `brainstorm-party` |
+
+### 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.
+
+Use when you have a draft that needs systematic improvement.
+
+### Authoring loop
+
+The recommended authoring sequence combines all workflow skills:
+
+1. **Orient** — Run `spego-help` to understand workspace state and get recommendations.
+2. **Ideate** — Run `spego-brainstorm-party` (multi-perspective breadth) or `spego-brainstorm-deep` (single-voice volume) to explore the problem space.
+3. **Capture** — Run `spego create --type prd` (or `architecture`, `design`, etc.) to persist the output.
+4. **Refine** — Run `spego-elicit` to iteratively improve the draft with structured methods.
+5. **Review** — Run `spego-review-adversarial` and `spego-review-edge-cases` for technical coverage, or `spego-editorial-prose` / `spego-editorial-structure` for communication quality.
+
+### Invocation
+
+All workflow skills are generated at `.claude/skills/spego-<workflow>/SKILL.md` during `spego init`. The agent picks them up automatically based on the skill description.
+
+### Complementary reviews
+
+For thorough artifact review, combine reviewers for orthogonal coverage:
+
+- **Technical defects:** Run `review-adversarial` (attitude-driven: hunts for gaps, weak assumptions) and `review-edge-cases` (method-driven: enumerates unhandled branching paths). Together they catch almost all technical defects.
+- **Communication defects:** Run `editorial-prose` (copy-edit) and `editorial-structure` (organizational review). These catch confusion, ambiguity, and poor organization that technical reviewers don't flag.
+- **Recommended minimum:** At least one technical reviewer + at least one editorial reviewer before declaring an artifact ready.
 
 ## Development
 

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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"}