From 766ab8f5c47ad99ac4bc0a6076ab5fdeadc64a1c Mon Sep 17 00:00:00 2001 From: "[._.]/ Adam Eivy" Date: Thu, 13 Aug 2026 08:57:25 -0700 Subject: [PATCH 1/4] add /do:goals --prd (and /do:prd) for generating a detailed PRD.md Same discovery pipeline as /do:goals, but synthesizes a requirements- level PRD.md (functional/non-functional/negative requirements with stable FR-/NFR-/NR- IDs, personas, out-of-scope, success metrics) instead of the strategic GOALS.md. /do:prd is a thin shorthand alias, following the /do:simplify pattern. Interactive mode gained a Risks & Open Questions step: judgment calls are asked via AskUserQuestion and folded into the document; purely factual items (e.g. tracker issue status) are checked directly instead of asked. Also refreshes GOALS.md (stale audit-dimension count, missing Grok Build environment) and adds CONTRIBUTING.md, both surfaced while dogfooding the new command against this repo. --- .changelogs/NEXT.md | 10 ++ CONTRIBUTING.md | 40 ++++++++ GOALS.md | 8 +- PLAN.md | 2 +- PRD.md | 162 +++++++++++++++++++++++++++++ README.md | 27 +++-- commands/do/goals.md | 237 +++++++++++++++++++++++++++++++++++++------ commands/do/help.md | 3 +- commands/do/prd.md | 20 ++++ install.sh | 2 +- uninstall.sh | 2 +- 11 files changed, 469 insertions(+), 44 deletions(-) create mode 100644 .changelogs/NEXT.md create mode 100644 CONTRIBUTING.md create mode 100644 PRD.md create mode 100644 commands/do/prd.md diff --git a/.changelogs/NEXT.md b/.changelogs/NEXT.md new file mode 100644 index 0000000..cbe8ce1 --- /dev/null +++ b/.changelogs/NEXT.md @@ -0,0 +1,10 @@ +# Unreleased Changes + +## Product requirements documents (`/do:goals --prd`, `/do:prd`) +- `/do:goals` now supports `--prd`, which generates a detailed `PRD.md` instead of the strategic `GOALS.md` — functional requirements, non-functional requirements, and explicit negative requirements ("must not") grouped by feature area, each with a stable ID and acceptance criteria, plus personas, out-of-scope, assumptions, success metrics, and open questions. +- `/do:prd` is a shorthand for `/do:goals --prd`. +- In `--interactive` mode, risks and open questions surfaced during generation are now resolved with you directly: judgment calls are asked and folded into the document, while purely factual items (like whether a referenced tracker issue is still open) are checked automatically instead of asked. +- Numeric success metrics are never invented — where the codebase doesn't evidence a concrete target, it's left as an open question rather than a fabricated number. + +## Contributing +- Added `CONTRIBUTING.md` covering project structure, local dev/test workflow, and commit/PR conventions. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..ebff705 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,40 @@ +# Contributing to slashdo + +Thanks for considering a contribution. slashdo is a small, actively-maintained project — issues and PRs are welcome. + +## Before you start + +- **Bugs and feature ideas**: [open an issue](https://github.com/atomantic/slashdo/issues). For anything beyond a trivial fix, opening an issue first (or commenting on an existing one) before writing code avoids duplicated effort — the project tracks its roadmap as `plan`-labeled issues rather than in `PLAN.md`. +- **Small, obvious fixes** (typos, broken links, a clearly wrong flag description): a PR without a prior issue is fine. + +## Project structure + +- `commands/do/*.md` — the source of truth for every `/do:*` command, written in Claude Code's native format +- `lib/*.md` — shared partials referenced from multiple commands +- `src/*.js` — the installer/transformer that converts `commands/do/` and `lib/` into each target environment's native format (Claude Code, OpenCode, Antigravity CLI, Codex, Grok Build) +- `install.sh` / `uninstall.sh` — the no-npm curl-based install path; their `COMMANDS`/`LIBS` arrays must stay in sync with `commands/do/` and `lib/` (`test/curl-installer-allowlist.test.js` enforces this in CI) +- `test/*.test.js` — the test suite, run with `node --test` + +## Making a change + +1. Fork and clone the repo. +2. Install dependencies: `npm install` (none currently required beyond dev tooling, but run it anyway). +3. Edit the relevant `commands/do/*.md` or `lib/*.md` source file. If you touch environment-specific behavior, wrap it in `……` (or the matching capability flag in `src/environments.js`) rather than hard-coding for one environment. +4. If you add or rename a command or lib file, update the `COMMANDS`/`LIBS` arrays in both `install.sh` and `uninstall.sh` — CI will fail the drift check otherwise. +5. Verify locally: + - `node bin/cli.js --list` — confirm the command shows up correctly + - `node bin/cli.js --dry-run` — preview what install would do + - `npm test` — run the full test suite +6. If your change affects behavior covered by an existing test, update it; if it adds new behavior worth locking in, add a test under `test/`. + +## Commit and PR conventions + +- Commit subjects are specific sentences, not vague tags — `fix: guard empty array expansion in review-loop bash 3.2 path`, not `fix bug`. +- Conventional prefixes (`fix:`, `feat:`, `docs:`, `chore:`, `refactor:`) are used but not strictly enforced by tooling — match the style in `git log`. +- Keep PRs scoped to one logical change. A doc fix and a behavior change should be separate PRs. +- CI runs the full test suite, a `shellcheck` pass on `install.sh`/`uninstall.sh`, and validates every command's frontmatter across Node 18/20/22 — make sure it's green before requesting review. +- No AI-attribution footers or co-author trailers in commits or PR descriptions, regardless of what tooling you used to help write the change. + +## License + +By contributing, you agree your contribution is licensed under the project's [MIT License](./LICENSE). diff --git a/GOALS.md b/GOALS.md index 6d0abc3..33e613d 100644 --- a/GOALS.md +++ b/GOALS.md @@ -13,19 +13,19 @@ slashdo is a curated library of slash commands that automate the software develo ## Core Goals ### 1. Multi-Environment Support -Provide a single source of truth for commands that works across Claude Code, OpenCode, Antigravity CLI, and Codex. Each environment gets commands in its native format with zero manual conversion. +Provide a single source of truth for commands that works across Claude Code, OpenCode, Antigravity CLI, Codex, and Grok Build. Each environment gets commands in its native format with zero manual conversion. ### 2. Automate DevSecOps Workflows -Provide one-command security auditing, code quality analysis, and automated remediation. `/do:better` scans across 7 dimensions, remediates findings in an isolated worktree, and delivers clean PRs. +Provide one-command security auditing, code quality analysis, and automated remediation. `/do:better` scans across up to 10 dimensions (8 core agents, plus a UX Consistency agent for UI-bearing projects and a Structural Ambition agent in strict mode), remediates findings in an isolated worktree, and delivers clean PRs. ### 3. Standardize Development Rituals Enforce consistent commit practices, SemVer versioning, and changelog management across projects. `/do:push` ensures every commit follows conventional commit prefixes and updates changelogs. ### 4. Orchestrate AI-Powered Code Review -Integrate Copilot review loops with automated thread resolution into the PR workflow. `/do:pr` and `/do:rpr` handle the full cycle from PR creation through review iteration. +Integrate multi-reviewer review loops — GitHub Copilot, CLI reviewers (Codex, Claude, Antigravity, Grok, Ollama), or any GitHub login — with automated thread resolution into the PR workflow. `/do:pr` and `/do:rpr` handle the full cycle from PR creation through review iteration. ### 5. Maintain Project Governance Documentation -Keep planning and standards documents current and well-structured. `/do:replan` manages the tactical backlog, `/do:goals` generates strategic goal documents, and `/do:omd` audits and optimizes markdown files (CLAUDE.md, README.md, AGENTS.md, etc.). +Keep planning and standards documents current and well-structured. `/do:replan` manages the tactical backlog, `/do:goals` generates strategic goal documents (or, with `--prd`, a detailed PRD.md of product requirements), and `/do:omd` audits and optimizes markdown files (CLAUDE.md, README.md, AGENTS.md, etc.). ### 6. Be Project-Agnostic Auto-detect tech stacks and adapt build commands, test runners, version bumping, and audit strategies accordingly. Commands should work on any codebase without manual configuration. diff --git a/PLAN.md b/PLAN.md index 24ff653..2435cd7 100644 --- a/PLAN.md +++ b/PLAN.md @@ -1,6 +1,6 @@ # Development Plan -For project mission, goals, and non-goals, see [GOALS.md](./GOALS.md). +For project mission, goals, and non-goals, see [GOALS.md](./GOALS.md). For detailed product requirements, see [PRD.md](./PRD.md). ## Work tracking diff --git a/PRD.md b/PRD.md new file mode 100644 index 0000000..94d163e --- /dev/null +++ b/PRD.md @@ -0,0 +1,162 @@ +# PRD.md — slashdo + +Curated slash commands for AI coding assistants — one install, multiple environments, one source of truth. + +--- + +## Overview + +slashdo (npm package `slash-do`) is a curated library of slash commands that automates the software development lifecycle for AI coding assistants. Developers using Claude Code, OpenCode, Antigravity CLI, Codex, or Grok Build each need consistent DevSecOps, code-review, planning, and release-management workflows — but hand-authoring bespoke prompt files per assistant duplicates effort and drifts out of sync across environments and across projects. slashdo solves this with a single source-of-truth command library, transformed automatically into each environment's native format and installed with one command (`npx slash-do@latest`), so a project gets the same audited, production-grade workflows regardless of which assistant a given contributor uses. + +--- + +## Goals & Objectives + +Aligned with [GOALS.md](./GOALS.md)'s Core Goals: + +1. **Multi-environment support** — a single source of truth for commands that works across Claude Code, OpenCode, Antigravity CLI, Codex, and Grok Build, each in its native format with zero manual conversion. +2. **Automate DevSecOps workflows** — one-command security auditing, code-quality analysis, and automated remediation via isolated worktrees and per-category PRs. +3. **Standardize development rituals** — consistent commit practices, SemVer versioning, and changelog management across projects. +4. **Orchestrate AI-powered code review** — multi-reviewer review loops with automated thread resolution folded into the PR workflow. +5. **Maintain project governance documentation** — keep GOALS.md, PRD.md, and PLAN.md current and well-structured via dedicated commands. +6. **Be project-agnostic** — auto-detect tech stacks and adapt build/test/versioning/audit strategies without manual configuration. +7. **Frictionless distribution** — npm-based install with semver versioning and self-update notifications; no git cloning required. + +--- + +## Target Users / Personas + +### Individual developer using an AI coding assistant +- **Needs:** wants DevSecOps audits, PR creation, and review-loop orchestration automated inside their daily assistant workflow instead of hand-rolled scripts or manual review. +- **Context:** works primarily in one assistant (most often Claude Code) on one or a few repos; installs via `npx slash-do@latest` and drives everything through `/do:*` commands. + +### Engineering lead standardizing practices across a team +- **Needs:** wants every repo and every contributor to follow the same commit, review, and release rituals regardless of which AI assistant an individual prefers. +- **Context:** cares about `/do:config` saved defaults, consistent SemVer/changelog discipline, and governance docs (GOALS.md/PRD.md/PLAN.md) staying current without manual upkeep. + +### Multi-assistant / tool-agnostic user +- **Needs:** switches between Claude Code, OpenCode, Antigravity CLI, Codex, and Grok Build across projects or teammates, and needs commands to behave identically everywhere. +- **Context:** relies on slashdo's per-environment transformation (subdirectory / flat / Agent-Skills-directory layouts) rather than maintaining separate prompt libraries per tool. + +--- + +## Functional Requirements + +### Installation & Environment Support + +| ID | Requirement | Priority | Acceptance Criteria | +|---|---|---|---| +| FR-1 | The system MUST detect which supported environments (Claude Code, OpenCode, Antigravity CLI, Codex, Grok Build) are already configured on the host and install into all detected environments when `--env` is omitted. | Must | Running `npx slash-do@latest` with no flags on a host with only `~/.claude` present installs only into `~/.claude/commands/`. | +| FR-2 | The system MUST support installing into an explicit subset of environments via `--env ` (comma-separated, case-insensitive, trimmed), including the aliases `gemini`/`agy` → `antigravity`. | Must | `--env CLAUDE,agy` installs into the claude and antigravity targets only. | +| FR-3 | The system MUST support installing/uninstalling a filtered subset of commands by name, accepting both bare (`push`) and `do:`-prefixed (`do:push`) forms. | Must | `npx slash-do@latest push pr` installs only the push and pr commands. | +| FR-4 | The system MUST transform each source command file into the native format of its target environment — subdirectory layout for Claude Code, flat `do-.md` for OpenCode, directory-per-skill (`SKILL.md`) for Antigravity/Codex/Grok — without per-environment hand-authoring. | Must | A single source file in `commands/do/` produces a correctly formatted, working command/skill file in every installed environment. | +| FR-5 | For environments without `!cat` file-inclusion support, the system MUST inline referenced `lib/*.md` content directly into the transformed command file (recursively, with cycle termination) rather than leaving a broken path reference. | Must | No dangling `~/.claude/lib/.md` references appear in Agent Skills output, even when the referenced file is missing. | +| FR-6 | Re-running install MUST be idempotent — unchanged files report up to date, changed files are updated in place, and hooks/config are not duplicated. | Must | Two consecutive installs with no source changes report 0 updates on the second run. | +| FR-7 | `--dry-run` MUST preview changes without writing, creating, or deleting any file, directory, hook registration, or config entry. | Must | A dry-run install on a clean host leaves the filesystem byte-for-byte unchanged. | +| FR-8 | `--list` MUST show all commands and their install status per environment without making changes. | Must | Output lists every command with an installed/not-installed/outdated status per detected environment. | +| FR-9 | `--uninstall` MUST remove installed commands, lib files, the version file, and the update-check cache for the targeted environment(s), and MUST clean up legacy/renamed command files (e.g. `cam.md`, `good.md`) left by older installs. | Must | After uninstall, none of the removed files remain in the target commands directory. | +| FR-10 | On Claude Code, install MUST register a SessionStart hook and status-line entry in `settings.json`, preserving any pre-existing user status-line configuration, and MUST reverse that registration cleanly on uninstall. | Must | Uninstall restores `settings.json` to its pre-install statusLine state. | + +### Configuration (`/do:config`) + +| ID | Requirement | Priority | Acceptance Criteria | +|---|---|---|---| +| FR-11 | The system MUST persist user-set defaults (e.g. `review-with`, `merge`, `autoUpdate`) to a per-environment config file and make them available to commands without the flag being re-specified each time. | Must | Setting `review-with` once via `/do:config` causes `/do:pr` to use it on a later run with no flag passed. | +| FR-12 | Saved config MUST survive a filtered (single-command) uninstall — only a full uninstall or explicit reset clears it. | Must | Uninstalling just `push` leaves `.slashdo-config.json` intact. | +| FR-13 | Config values MUST round-trip complex reviewer syntax verbatim (bracket groups, `~opt`, `~max=`, `@login[bot]`). | Should | A saved `review-with` value with brackets and `~max=3` reads back identical to what was written. | + +### Self-Update + +| ID | Requirement | Priority | Acceptance Criteria | +|---|---|---|---| +| FR-14 | The system MUST check the installed version against the latest published npm version and notify the user when an update is available, without blocking normal operation past a bounded timeout. | Must | The CLI completes normally even if the version-check network call stalls (see NFR-3). | +| FR-15 | Version comparison MUST correctly classify major/minor/patch bumps and accept `v`-prefixed version strings. | Must | `v3.27.0` → `3.28.0` classifies as a minor bump. | + +### Command Library (`do:*` commands) + +| ID | Requirement | Priority | Acceptance Criteria | +|---|---|---|---| +| FR-16 | The system MUST provide `/do:goals`, which scans the codebase and generates a strategic `GOALS.md`, and, via `--prd` (or the `/do:prd` shorthand), a detailed requirements-level `PRD.md`. | Must | Running `/do:prd` on a repo with no existing PRD.md produces one with functional/non-functional/negative requirement sections. | +| FR-17 | The system MUST provide `/do:pr`, which commits, pushes, and opens a PR/MR against the repo's default branch, deriving the push destination from the branch's configured upstream (`branch..remote`/`.merge`) rather than assuming `origin`/`HEAD`. | Must | On a branch tracking a fork remote, `/do:pr` pushes to that fork, not `origin`. | +| FR-18 | The system MUST provide a multi-reviewer review loop (`--review-with`) that classifies each reviewer's output into a fixed status vocabulary (clean/capped/no-verdict/guardrail/cli-error/push-failed/...) and blocks merge on any non-clean status not explicitly exempted. | Must | A reviewer returning an unparseable verdict blocks merge rather than being treated as clean. | +| FR-19 | The system MUST provide `/do:better` (and the structurally narrowed `/do:simplify`) for multi-agent DevSecOps/refactor auditing, remediation in an isolated worktree, and per-category PR creation. | Must | `/do:simplify` produces refactor-only PRs with the existing test suite passing unmodified. | +| FR-20 | The system MUST provide `/do:next` (including `--swarm`) to claim and ship PLAN.md items or tracker issues via isolated worktrees. | Must | `/do:next --swarm` ships more than one independent issue in a single run without branch collisions. | +| FR-21 | The system MUST provide `/do:replan` and `/do:plan-task` to keep the tactical backlog (PLAN.md or the issue tracker) current. | Should | `/do:replan --issues` prunes closed items from the tracked `plan`-labeled issue set. | +| FR-22 | The system MUST provide `/do:help`, listing every installed command with a one-line description and a check for available updates. | Must | `/do:help` output includes every file present in `commands/do/`. | + +### CLI Interface + +| ID | Requirement | Priority | Acceptance Criteria | +|---|---|---|---| +| FR-23 | `bin/cli.js` MUST support `--help`/`-h`, `--list`, `--dry-run`, `--uninstall`, `--env`, `--auto-update`/`--no-auto-update`, and positional command-name filters, usable in any combination. | Must | `--env claude --dry-run push` runs a scoped, non-mutating preview. | + +--- + +## Non-Functional Requirements + +| ID | Category | Requirement | +|---|---|---| +| NFR-1 | Reliability | Config and settings reads/writes MUST tolerate corrupted or malformed JSON without throwing — install/uninstall skip registration and leave the file untouched rather than crashing. | +| NFR-2 | Reliability | Hook registration MUST tolerate malformed existing `SessionStart` entries (null, string, number, non-array) without throwing. | +| NFR-3 | Performance | The update-check network call MUST be bounded by a timeout (3000ms default) so a slow or unreachable registry never blocks the CLI. | +| NFR-4 | Reliability | `--dry-run` MUST be a strict no-op, verified by tests asserting zero filesystem/config mutation. | +| NFR-5 | Portability | `install.sh`/`uninstall.sh` MUST remain compatible with bash 3.2 (stock macOS) under `set -u`, using guarded array expansions. | +| NFR-6 | Reliability | Long-running reviewer invocations MUST run in the background/poll rather than block the foreground past the host's execution cap (~10 minutes). | +| NFR-7 | Compatibility | The CLI MUST run on Node.js >=18 and is verified in CI across Node 18/20/22. | +| NFR-8 | Security / Supply chain | The curl-based install path (`install.sh`/`uninstall.sh`) MUST stay structurally in sync with the npm-distributed command/lib set — CI fails if the hard-coded `COMMANDS`/`LIBS` arrays drift from the actual `commands/do/*.md` / `lib/*.md` contents, so remote-install users never silently receive a broken or missing command. | + +--- + +## Negative Requirements + +| ID | Requirement | Why | +|---|---|---| +| NR-1 | The system MUST NOT write `autoUpdate` config for environments that don't support hooks (Codex, Antigravity, OpenCode, Grok). | That setting only has meaning where a hook can act on it; writing it elsewhere is dead state. | +| NR-2 | The system MUST NOT overwrite or mutate `settings.json` when its existing content is invalid JSON. | Silently rewriting a file the installer can't parse risks discarding user configuration it doesn't understand. | +| NR-3 | A filtered/single-command uninstall MUST NOT delete the user's saved `/do:config` defaults. | Defaults are shared across commands; removing one command shouldn't reset preferences for the rest. | +| NR-4 | `/do:pr` and the review loop MUST NOT push via a bare `git push` or `git push origin HEAD`/``, and MUST NOT push when the upstream remote is local (`.`). | Prevents pushing to the wrong remote/ref or silently no-op'ing against a local-only upstream. | +| NR-5 | The review loop MUST NOT classify an unparseable or no-verdict reviewer output as either a hard error or as clean. | Treating "inconclusive" as either extreme either blocks merges that should proceed or lets unreviewed changes through. | +| NR-6 | The review loop MUST NOT merge a reviewer's stderr into the log file the strict verdict parser validates. | Interleaved stderr can corrupt the parser's ability to find a clean verdict marker. | +| NR-7 | An `~opt` (optional) reviewer exemption MUST NOT excuse a `push-failed` status. | A reviewer being optional doesn't make its unpushed fixes safe to merge over. | +| NR-8 | `/do:goals --prd` (and `/do:prd`) MUST NOT fabricate numeric success metrics or KPIs the codebase doesn't evidence. | An invented target reads as fact in a document meant to be authoritative; an unverifiable number belongs in Open Questions instead (see this document's own Success Metrics section). | + +--- + +## Out of Scope + +- **CI/CD pipeline replacement** — commands complement GitHub Actions/GitLab CI by handling code-level workflows; infrastructure automation and deployment pipelines are out of scope. +- **A GUI or dashboard** — everything runs in the CLI via AI coding assistants; no web interface or visual tooling is planned. +- **Install integrity verification (checksums/signing)** — the curl-installer allowlist test (NFR-8) is a drift guard between the repo's source files and the hard-coded shell arrays, not a supply-chain signing or checksum system. This is an accepted risk for the standard curl-pipe-bash distribution pattern; the npm install path is the primary, recommended route and isn't subject to it. + +--- + +## Assumptions & Constraints + +- Single independent maintainer, no funding/sponsorship infrastructure — README and LICENSE attribute the project to Adam Eivy. +- Distribution depends on the npm registry (primary path) and GitHub raw-content availability (curl fallback) being reachable. +- Issue-tracker features (`--issues` modes) assume `gh` (or `glab`) is installed and authenticated; commands degrade gracefully (skip, don't halt) when it isn't. +- Node.js >=18 is assumed present in the host environment. +- Environment auto-detection assumes each assistant's config-directory convention (`~/.claude`, `~/.config/opencode`, etc.) is stable and not user-relocated. +- Contributions are actively solicited via the public GitHub issue tracker (MIT license, no CLA); the process is formalized in [CONTRIBUTING.md](./CONTRIBUTING.md). No `CODE_OF_CONDUCT.md` exists yet. + +--- + +## Success Metrics + +- Success is defined by correctness, not adoption: every functional and non-functional requirement in this document behaving per its stated acceptance criteria is the bar, not download counts or usage volume. +- The one concrete, codebase-evidenced operational target found is the update-check network call, bounded to 3000ms (NFR-3). + +--- + +## Risks & Open Questions + +None open as of this writing — every item discovery raised was resolved during generation: + +- Curl-installer integrity verification → accepted risk (see Out of Scope). +- Contribution model → contributions are actively solicited, formalized in `CONTRIBUTING.md` (see Assumptions & Constraints). +- Success metrics definition → correctness against this document's FR/NFR acceptance criteria is the bar (see Success Metrics). +- Possible stale `/do:fpr` upstream-detection issue → confirmed closed (GitHub issue #36, closed 2026-05-16). + +--- + +For strategic context (mission, tenets, long-term vision), see [GOALS.md](./GOALS.md). For the tactical backlog, see [PLAN.md](./PLAN.md). diff --git a/README.md b/README.md index ba3ee53..5eca54b 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@

npm version environments - commands + commands license

@@ -161,7 +161,8 @@ All commands live under the `do:` namespace: | `/do:simplify` | Refactor-only audit — architecture, DRY, simplification, cognitive load — as per-category PRs that must not change behavior ([details](#refactor-only-dosimplify)) | | `/do:scan` | Read-only safety audit of an unfamiliar directory — flags malware patterns, network calls, and vulnerable deps without executing code | | `/do:depfree` | Audit dependencies, remove unnecessary ones, write replacement code (`--heavy` targets all non-foundational libraries) | -| `/do:goals` | Generate GOALS.md from codebase analysis (autonomous by default; `--interactive` to review with you) | +| `/do:goals` | Generate GOALS.md from codebase analysis — `--prd` generates a detailed PRD.md instead ([details](#prd-mode-dogoals---prd)) (autonomous by default; `--interactive` to review with you) | +| `/do:prd` | Generate a detailed PRD.md from codebase analysis (`/do:goals --prd`) ([details](#prd-mode-dogoals---prd)) | | `/do:plan-task` | Investigate the codebase, draft a decision-complete issue, show it for approval, file it in the tracker ([workflow](#plan-a-task-then-let-an-agent-ship-it)) | | `/do:replan` | Audit/triage the plan — prune completed items, suggest new work — in `PLAN.md` or the issue tracker ([Issue mode](#issue-mode---issues)) | | `/do:next` | Claim the next unclaimed plan item or issue, implement it in an isolated worktree, ship a reviewed PR, clean up. `--swarm[=N]` ships several independent issues in parallel — auto-picked, or the exact numbers you name ([Issue mode](#issue-mode---issues)) | @@ -189,6 +190,22 @@ The contract that makes it safe to merge: **every fix must be observably behavio Every `/do:better` flag works here — `--interactive`, `--scan-only`, `--no-merge`, `--issues`, and the whole [review loop](#review-loop) set. +## PRD mode (`/do:goals --prd`) + +`/do:goals --prd` (shorthand: `/do:prd`) runs the same discovery pipeline as `/do:goals` but writes a `PRD.md` instead of a `GOALS.md` — a detailed, requirements-level document rather than a strategic one. GOALS.md answers *why* the project exists; PRD.md answers *what exactly* the product must (and must not) do. + +PRD.md is built from: an overview and problem statement, goals & objectives (aligned with an existing GOALS.md's Core Tenets when one exists), target users/personas, **functional requirements** grouped by feature area (stable `FR-` IDs, MUST/SHOULD/MAY priority, acceptance criteria), **non-functional requirements** (`NFR-` IDs — performance, security, reliability, usability), **negative requirements** (`NR-` IDs — explicit things the system must not do), an out-of-scope list, assumptions & constraints, success metrics, and open questions. + +An extra discovery agent mines test suites, validation/guard-clause logic, and auth/rate-limit code for requirements that are already implicitly specified in the codebase, since executable tests are high-confidence evidence of intended behavior. Numeric success metrics are never fabricated — where the codebase doesn't evidence a concrete target, it's left as an open question instead. + +``` +/do:goals --prd # generate PRD.md autonomously +/do:prd --interactive # same, with a validation pass on requirements, guardrails, and metrics +/do:prd --refresh # re-scan and update an existing PRD.md, preserving requirement IDs +``` + +Requirement IDs are stable across `--refresh` runs — unchanged requirements keep their ID, new ones get the next unused number, and requirements that no longer hold are marked `(status: removed — verify)` rather than silently deleted. + ## Review loop `/do:pr`, `/do:release`, `/do:pr-better`, `/do:review`, `/do:better`, `/do:better-swift`, `/do:simplify`, `/do:depfree`, and `/do:rpr` share one review system: you pick the reviewer(s) with `--review-with`, and a set of companion flags controls how the loop runs. **No reviewer is ever hardcoded** — omit the flag and no external review runs (each command still runs its own unconditional self-review gate). The one exception is `/do:rpr`, whose conditional default is [documented below](#command-specific-behavior). @@ -432,11 +449,7 @@ Existing installs from before this feature get asked on their next `npx slash-do ## Contributing -1. Commands live in `commands/do/` as Claude Code format `.md` files (source of truth) -2. Lib files (shared partials) live in `lib/` -3. The transformer handles format conversion for each environment -4. Capability-gated content: wrap environment-specific instructions in `……` blocks. The transformer keeps the matching branch per the target environment's capability flag (`supportsTeams` in `src/environments.js`) and strips the markers — e.g. `do:better` uses `TeamCreate` on Claude Code and falls back to parallel sub-agents elsewhere. -5. Test with `node bin/cli.js --list` and `node bin/cli.js --dry-run` +Issues and PRs are welcome — see [CONTRIBUTING.md](./CONTRIBUTING.md) for the project structure, local dev/test workflow, and PR conventions. ## License diff --git a/commands/do/goals.md b/commands/do/goals.md index cc4808b..4d2eea2 100644 --- a/commands/do/goals.md +++ b/commands/do/goals.md @@ -1,27 +1,33 @@ --- -description: Scan codebase to infer project goals and generate GOALS.md (default: fully autonomous; use --interactive to review with user) -argument-hint: "[--interactive] [--refresh] [focus hint, e.g. 'just the CLI']" +description: Scan codebase to infer project goals and generate GOALS.md, or a detailed PRD.md with --prd (default: fully autonomous; use --interactive to review with user) +argument-hint: "[--prd] [--interactive] [--refresh] [focus hint, e.g. 'just the CLI']" --- -# Goals — Generate a GOALS.md from Codebase Analysis +# Goals — Generate a GOALS.md or PRD.md from Codebase Analysis -Scan the codebase to infer the project's goals, purpose, and direction, then generate a comprehensive `GOALS.md` at the repo root. +Scan the codebase to infer the project's goals, purpose, and direction, then generate a comprehensive `GOALS.md` at the repo root — or, with `--prd`, a detailed `PRD.md` (Product Requirements Document) with functional and non-functional requirements, explicit exclusions, and acceptance criteria. -**Default mode: fully autonomous.** Scans the codebase, synthesizes goals, and writes GOALS.md without prompting. HIGH and MEDIUM confidence goals are included; LOW confidence goals are included but marked as inferred. +**Default mode: fully autonomous.** Scans the codebase, synthesizes goals (or requirements, in `--prd` mode), and writes the document without prompting. HIGH and MEDIUM confidence items are included; LOW confidence items are included but marked as inferred. -**`--interactive` mode:** Pauses after synthesis to validate purpose, prioritize goals, confirm non-goals, and refine wording with the user. +**`--prd` mode:** generate `PRD.md` instead of `GOALS.md`. Same discovery pipeline, same autonomous-by-default behavior, but the synthesis and output are requirements-level rather than strategic — see [PRD.md Structure](#prdmd-structure---prd) below. `/do:prd` is shorthand for `/do:goals --prd`. + +**`--interactive` mode:** Pauses after synthesis to validate purpose, prioritize goals (or requirements), confirm non-goals, and refine wording with the user. Parse `$ARGUMENTS` for: +- **`--prd`**: generate `PRD.md` (a detailed product requirements document) instead of `GOALS.md` - **`--interactive`**: pause after synthesis for user validation and refinement -- **`--refresh`**: re-scan and update an existing GOALS.md rather than creating from scratch +- **`--refresh`**: re-scan and update the existing target document (`GOALS.md`, or `PRD.md` when combined with `--prd`) rather than creating from scratch - **Focus hints**: e.g., "focus on API goals", "just the CLI" -## Boundary Rule: GOALS.md vs PLAN.md +`--prd` and `--refresh` combine normally: `--prd --refresh` re-scans and updates an existing `PRD.md`. + +## Boundary Rule: GOALS.md vs PRD.md vs PLAN.md -**GOALS.md is strategic. PLAN.md is tactical.** +**GOALS.md is strategic. PRD.md is the requirements spec. PLAN.md is tactical.** -GOALS.md answers: *Why does this project exist? What does success look like? What will we never do?* -PLAN.md answers: *What are we building next? What's the backlog? What's done?* +- GOALS.md answers: *Why does this project exist? What does success look like? What will we never do?* +- PRD.md answers: *What exactly must the product do, and not do? Who is it for? What counts as "it works"?* +- PLAN.md answers: *What are we building next? What's the backlog? What's done?* **GOALS.md must NEVER contain:** - Checkbox task lists (`- [ ] Add feature X`) @@ -42,6 +48,27 @@ When milestones describe what "done" looks like, write outcome-oriented prose: - GOOD: "v1.0 means daily entry takes under 30 seconds and APY calculations are auditable across all edge cases" - BAD: "- [ ] Add date range buttons above charts / - [ ] Filter chart data to selected range" +**PRD.md must NEVER contain:** +- Checkbox task lists or sprint/iteration planning — that's PLAN.md's job +- Specific file paths, function names, or line-level implementation detail +- Vague, untestable statements ("the system should be fast") without a concrete acceptance criterion +- Fabricated numeric targets the codebase doesn't evidence — an unverifiable KPI belongs in Open Questions, not stated as fact + +**PRD.md SHOULD contain:** +- Overview & problem statement +- Goals & objectives (aligned with GOALS.md's Core Tenets when a GOALS.md exists) +- Target users / personas +- Functional requirements — discrete, testable statements grouped by feature area, each with a stable ID, a MUST/SHOULD/MAY priority, and acceptance criteria +- Non-functional requirements — performance, security, reliability, usability, compatibility/scalability +- Negative requirements — explicit things the system MUST NOT do (safety/security guardrails, deliberately unsupported behavior) +- Out of scope — capabilities intentionally excluded from this version +- Assumptions & constraints +- Success metrics / KPIs +- Risks & open questions +- A footer link to GOALS.md (if present) and PLAN.md + +Requirement statements use RFC-2119-style keywords — **MUST/SHALL** (mandatory), **SHOULD** (recommended), **MAY** (optional) — e.g. "The system MUST reject uploads over 25MB" rather than "uploads should be limited." + ## Phase 1: Discovery Gather signals about the project's purpose and intent from multiple sources. Launch these as parallel Explore agents: @@ -67,7 +94,7 @@ Scan for what the project actually does: - Key domain types/interfaces — what concepts exist - Infrastructure files (`Dockerfile`, `docker-compose.*`, CI/CD configs, deploy scripts) -Extract: list of capabilities, deployment model, key domain concepts. +Extract: list of capabilities, deployment model, key domain concepts. **In `--prd` mode**, also enumerate each discrete feature/command/endpoint with its observed inputs, outputs, and error-handling behavior — this seeds functional requirements directly. ### Agent 3: Evolution & Direction Scan for trajectory signals: @@ -81,10 +108,22 @@ Scan for trajectory signals: Extract: recent themes, planned direction, known gaps, active work areas. -Wait for all agents to complete. +### Agent 4 (`--prd` mode only): Requirements Mining +Scan for behavior that's already been specified, even if never written down as a requirement: +- Test suites / spec files — encode expected behavior (positive cases) and expected rejections (negative cases) with high confidence, since they're executable +- Input validation, error handling, and guard clauses — encode implicit requirements ("must reject X") +- Auth/authz, rate limiting, and other security-relevant logic — seeds non-functional and negative requirements +- Config schemas, env vars, and documented limits (timeouts, size caps, pagination) — seeds non-functional requirements +- An existing `GOALS.md`, if present — reuse its Mission and Core Tenets as the PRD's Goals & Objectives rather than re-deriving them from scratch + +Extract: candidate functional requirements (with source evidence), candidate non-functional requirements, candidate negative requirements. + +Wait for all agents to complete (3 in default mode, 4 in `--prd` mode). ## Phase 2: Synthesis +### GOALS.md Mode (default) + Consolidate the findings into a draft goals structure: 1. **Project Purpose** — one-paragraph summary of what this project is and why it exists @@ -94,8 +133,23 @@ Consolidate the findings into a draft goals structure: 5. **Target Users** — who this is for (inferred from README, API design, CLI UX, documentation tone) 6. **Long-Term Vision** — aspirational direction in prose -For each goal, assign a confidence level: -- **HIGH** — directly stated in docs or clearly evidenced by code +### PRD.md Mode (`--prd`) + +Consolidate the findings into a draft requirements structure: + +1. **Overview & Problem Statement** — one paragraph: what the product is, the problem it solves, and for whom +2. **Goals & Objectives** — 3-7 objectives; reuse GOALS.md's Core Tenets verbatim where a GOALS.md exists rather than re-deriving them +3. **Target Users / Personas** — one short persona per primary user type (role, need, context of use) +4. **Functional Requirements** — grouped by feature area; each requirement gets a stable ID (`FR-1`, `FR-2`, ...), a MUST/SHOULD/MAY keyword, a one-sentence statement, and testable acceptance criteria +5. **Non-Functional Requirements** — same ID scheme (`NFR-1`, ...), covering performance, security, reliability, usability, and compatibility/scalability as applicable to the project +6. **Negative Requirements** — explicit "MUST NOT" statements (`NR-1`, ...) for safety/security guardrails and deliberately unsupported behavior +7. **Out of Scope** — capabilities intentionally excluded from this version, with a one-line reason each +8. **Assumptions & Constraints** — technical, business, or resourcing constraints taken as given +9. **Success Metrics / KPIs** — measurable criteria for "this product is working"; only state a concrete number where Discovery found evidence for one, otherwise list it under Open Questions rather than inventing a target +10. **Risks & Open Questions** — known unknowns and decisions still needed + +Both modes: for each item, assign a confidence level: +- **HIGH** — directly stated in docs or clearly evidenced by code (or, in `--prd` mode, by a passing test) - **MEDIUM** — strongly implied by patterns, architecture, or recent work - **LOW** — inferred/speculative, needs user confirmation @@ -103,7 +157,7 @@ For each goal, assign a confidence level: ### Default Mode (autonomous) -Skip user clarification. Include all HIGH and MEDIUM confidence goals directly. Include LOW confidence goals but mark them with `(inferred)` so the user can review after generation. Proceed directly to Phase 4. +Skip user clarification. Include all HIGH and MEDIUM confidence items directly. Include LOW confidence items but mark them with `(inferred)` so the user can review after generation. Proceed directly to Phase 4. ### Interactive Mode (`--interactive`) @@ -127,14 +181,28 @@ Present the inferred non-goals. Ask: "Are these accurate? Anything to add or rem #### 3e: Target Users Present the inferred target user description. Ask if it's accurate. -#### 3f: Success Criteria (optional) +#### 3f: Success Criteria (optional, GOALS.md mode) Ask: "Would you like to define measurable success criteria for any of these goals?" Offer examples relevant to the project type (e.g., "support N concurrent users", "< Xms response time", "100% test coverage on core module"). +#### 3g (`--prd` mode): Requirements Walkthrough +Present the grouped functional requirements. For each LOW or MEDIUM confidence requirement, confirm it's accurately scoped and correctly prioritized (Must/Should/May); ask if any requirements are missing from a feature area. + +#### 3h (`--prd` mode): Negative Requirements & Guardrails +Present the inferred negative requirements. Ask: "Are these accurate? Is there any safety or security boundary the product must enforce that I missed?" + +#### 3i (`--prd` mode): Success Metrics +For every KPI Discovery could not evidence with a concrete number, ask the user to supply a target rather than leaving it fabricated or blank. + +#### 3j (`--prd` mode): Risks & Open Questions +Before writing the document, walk the user through every item synthesized into Risks & Open Questions and try to close it out rather than shipping it open by default: +- **Judgment calls and missing information** (scope decisions, risk tolerance, product direction, anything only the user can decide) — ask with `AskUserQuestion`. If the user's answer resolves the question, fold it directly into the relevant PRD section (a resolved KPI target goes into Success Metrics, a scope call updates Out of Scope or Assumptions & Constraints, etc.) and drop it from Risks & Open Questions. If the user has no answer or wants it left open, keep it in Risks & Open Questions, refined with whatever context they gave. +- **Purely factual items** verifiable from `gh`/`glab`, git history, or the filesystem (e.g. "is issue #N still open?") — check directly instead of asking the user; only fall back to asking if the check is inconclusive (tool unavailable, ambiguous result). + ## Phase 4: Document Generation -Using the validated and refined information, generate `GOALS.md` at the repo root. +Using the validated and refined information, generate the target document at the repo root. -### Document Structure +### GOALS.md Structure (default) ```markdown # GOALS.md @@ -195,36 +263,147 @@ For the tactical backlog and current work items, see [PLAN.md](./PLAN.md). **Important:** The template above intentionally omits "Current State" tables and "Direction" sections — those are tactical concerns that belong in PLAN.md. If the user asks for them, add a brief (1-2 sentence) summary that points to PLAN.md rather than duplicating the detail. +### PRD.md Structure (`--prd`) + +```markdown +# PRD.md — {Project Name} + +{Optional: one-sentence tagline} + +--- + +## Overview + +{One-paragraph problem statement: what the product is, the problem it solves, and for whom.} + +--- + +## Goals & Objectives + +{3-7 objectives. If GOALS.md exists, align these with its Core Tenets rather than restating them differently.} + +1. **{Objective}** - {measurable or observable definition of success} +2. ... + +--- + +## Target Users / Personas + +### {Persona name/role} +- **Needs:** {what they're trying to accomplish} +- **Context:** {when/how they use the product} + +{Repeat per primary user type.} + +--- + +## Functional Requirements + +### {Feature Area} + +| ID | Requirement | Priority | Acceptance Criteria | +|---|---|---|---| +| FR-1 | The system MUST {behavior} | Must | {testable condition} | +| FR-2 | The system SHOULD {behavior} | Should | {testable condition} | + +{Repeat per feature area. IDs are sequential and never reused across the whole document.} + +--- + +## Non-Functional Requirements + +| ID | Category | Requirement | +|---|---|---| +| NFR-1 | Performance | {requirement} | +| NFR-2 | Security | {requirement} | + +--- + +## Negative Requirements + +{Explicit things the system MUST NOT do.} + +| ID | Requirement | Why | +|---|---|---| +| NR-1 | The system MUST NOT {behavior} | {rationale - safety, security, or deliberate scope boundary} | + +--- + +## Out of Scope + +{Capabilities intentionally excluded from this version.} + +- **{Excluded capability}** - {why it's excluded or deferred} + +--- + +## Assumptions & Constraints + +- {Assumption or constraint} + +--- + +## Success Metrics + +- {Metric} - {target, if evidenced; otherwise "open question — no target set yet"} + +--- + +## Risks & Open Questions + +- {Risk or open question} + +--- + +{Footer: link to [GOALS.md](./GOALS.md) if it exists, and [PLAN.md](./PLAN.md) for the tactical backlog.} +``` + +Requirement IDs (`FR-`, `NFR-`, `NR-`) are assigned sequentially at generation time and are **stable across `--refresh` runs** — an existing ID must never be reassigned to a different requirement. New requirements append the next unused number per prefix; a requirement that no longer holds retires its number rather than having it reused. + ### Refresh Mode (`--refresh`) -If `--refresh` was passed and `GOALS.md` already exists: -1. Read the existing `GOALS.md` -2. Compare existing goals against current codebase state -3. Identify goals whose status has changed (new progress, completed, abandoned) +If `--refresh` was passed and the target document already exists: +1. Read the existing document +2. Compare its content against the current codebase state +3. Identify items whose status has changed (new progress, completed, abandoned — or, in `--prd` mode, requirements that no longer hold, or new behavior that isn't yet captured as a requirement) 4. **Default mode**: Update the document in-place automatically, preserving user-written content where possible. Print a summary of what changed. **Interactive mode (`--interactive`)**: Present changes to the user for confirmation before updating. -5. If any checkbox task lists are found in the existing GOALS.md, move them to PLAN.md automatically (default) or offer to move them (interactive). When inserting each item into PLAN.md, **assign it a unique `[]` ID** per [lib/plan-id-format.md](../../lib/plan-id-format.md): kebab-case slug derived from the item title, ≤50 chars, unique against every existing `[slug]` in PLAN.md. +5. **GOALS.md mode**: If any checkbox task lists are found in the existing GOALS.md, move them to PLAN.md automatically (default) or offer to move them (interactive). When inserting each item into PLAN.md, **assign it a unique `[]` ID** per [lib/plan-id-format.md](../../lib/plan-id-format.md): kebab-case slug derived from the item title, ≤50 chars, unique against every existing `[slug]` in PLAN.md. +6. **PRD.md mode**: Preserve existing `FR-`/`NFR-`/`NR-` IDs for requirements that still hold. Assign the next unused ID (per prefix) to newly discovered requirements. If a requirement no longer appears to hold, mark it `(status: removed — verify)` in place rather than silently deleting it, and call it out in the change summary for the user to confirm. ## Phase 5: Finalize -1. Write the `GOALS.md` file to the repo root -2. If `PLAN.md` exists, ensure it has a reference link to GOALS.md (only if not already present) -3. If checkbox task lists were found in an existing GOALS.md during `--refresh`, offer to migrate them to PLAN.md +1. Write the target document (`GOALS.md`, or `PRD.md` in `--prd` mode) to the repo root +2. If `PLAN.md` exists, ensure it has a reference link to the generated document (only if not already present) +3. **GOALS.md mode**: if checkbox task lists were found in an existing GOALS.md during `--refresh`, offer to migrate them to PLAN.md 4. Print a summary: + + GOALS.md mode: ``` GOALS.md created with: - {N} core tenets - {M} milestones (outcome-oriented) - {K} non-goals ``` + + PRD.md mode: + ``` + PRD.md created with: + - {N} functional requirements + - {M} non-functional requirements + - {K} negative requirements + - {J} open questions + ``` 5. Do NOT commit — let the user review and commit when ready (suggest using `/do:push` to commit) ## Notes - This command is project-agnostic — it reads whatever project signals exist +- `/do:prd` is shorthand for `/do:goals --prd` - In default mode, scan and generate autonomously; in interactive mode, collaborate with the user - LOW confidence inferences are included as `(inferred)` in default mode; validated with the user in interactive mode -- Preserve the user's voice — if they provide rephrased goals, use their wording verbatim +- Preserve the user's voice — if they provide rephrased goals or requirements, use their wording verbatim - If the project is brand new with minimal code, lean more heavily on user input and less on codebase inference - If `gh` CLI is not authenticated, skip issue/PR scanning gracefully — don't halt -- **Never put checkbox task lists in GOALS.md** — if you discover tactical items during scanning, note them for PLAN.md but keep them out of GOALS.md +- **Never put checkbox task lists in GOALS.md or PRD.md** — if you discover tactical items during scanning, note them for PLAN.md but keep them out of both +- **In `--prd` mode, never fabricate numeric success metrics or KPIs** the codebase doesn't evidence — leave them as open questions, even in autonomous mode diff --git a/commands/do/help.md b/commands/do/help.md index 8664a00..27d4751 100644 --- a/commands/do/help.md +++ b/commands/do/help.md @@ -17,13 +17,14 @@ List all available `/do:*` commands with their descriptions. | `/do:config` | View or set saved slashdo defaults (e.g. `--review-with`) so future commands can omit the flag — global or per-project (`--project`) | | `/do:depfree` | Audit third-party dependencies and remove unnecessary ones by writing replacement code. Use `--heavy` for aggressive mode that targets all non-foundational libraries for replacement where feasible | | `/do:fpr` | Commit, push to fork, and open a PR against the upstream repo | -| `/do:goals` | Scan codebase to infer project goals and generate GOALS.md (autonomous by default; `--interactive` to review with you) | +| `/do:goals` | Scan codebase to infer project goals and generate GOALS.md — `--prd` generates a detailed PRD.md instead (autonomous by default; `--interactive` to review with you) | | `/do:help` | List all available slashdo commands | | `/do:next` | Claim the next unclaimed PLAN.md item (or tracker issue with `--issues`), implement it in an isolated worktree, ship a reviewed PR, and clean up — `--swarm[=N]` ships several independent issues in parallel, auto-picked or named (`--swarm #12 #14`) | | `/do:omd` | Audit and optimize markdown files (CLAUDE.md, README.md, etc.) against best practices | | `/do:plan-task` | Plan a task by investigating the codebase, then file a robust, decision-complete issue in the repo's tracker (GitHub `gh` / GitLab `glab`, auto-detected) — with an approval gate you can skip with `--yes` | | `/do:pr` | Commit, push, and open a PR (GitHub) or merge request (GitLab) against the repo's default branch — `--merge` auto-merges once reviews and CI pass | | `/do:pr-better` | Run a full do:better audit on the current branch, commit fixes directly, then open a single PR | +| `/do:prd` | Scan codebase to infer product requirements and generate a detailed PRD.md (`/do:goals --prd`) | | `/do:push` | Commit and push all work with changelog | | `/do:release` | Create a release PR using the project's documented release workflow | | `/do:replan` | Automated audit/triage of PLAN.md (or the issue tracker with `--issues`) — prune completed items, suggest new work, keep the plan lean | diff --git a/commands/do/prd.md b/commands/do/prd.md new file mode 100644 index 0000000..f5ee268 --- /dev/null +++ b/commands/do/prd.md @@ -0,0 +1,20 @@ +--- +description: Scan codebase to infer product requirements and generate a detailed PRD.md (default: fully autonomous; use --interactive to review with user) +argument-hint: "[--interactive] [--refresh] [focus hint, e.g. 'just the CLI']" +--- + +# PRD — Generate a PRD.md from Codebase Analysis + +Shorthand for `/do:goals --prd`: scan the codebase and generate a detailed `PRD.md` (Product Requirements Document) instead of the strategic `GOALS.md` — functional and non-functional requirements, explicit exclusions, and acceptance criteria. + +## Execution + +Run the workflow defined in `~/.claude/commands/do/goals.md` **verbatim**, with `--prd` forced on — whether or not it appears in `$ARGUMENTS`. Its [PRD.md Structure](goals.md#prdmd-structure---prd) section and every other `--prd`-mode deviation (Discovery's Agent 4, Synthesis, Validation 3g-3i, Refresh Mode) is the specification. This command adds none of its own. + +Argument handling: +- Pass `$ARGUMENTS` through to `do:goals` verbatim, with `--prd` added if not already present. It parses every flag itself, including `--interactive`, `--refresh`, and focus hints — there is nothing to extract or re-validate here. +- `--prd` in `$ARGUMENTS` is redundant but harmless — do not error on it. + +## Notes + +- See `/do:goals` for the full specification, including the GOALS.md vs PRD.md vs PLAN.md boundary rules. diff --git a/install.sh b/install.sh index 8c2da6d..9325ad5 100755 --- a/install.sh +++ b/install.sh @@ -47,7 +47,7 @@ banner() { COMMANDS=( better better-swift config depfree fpr goals help next omd - plan-task pr pr-better push release replan review rpr scan simplify update + plan-task pr pr-better prd push release replan review rpr scan simplify update ) diff --git a/uninstall.sh b/uninstall.sh index 94ac6dd..7e26d72 100755 --- a/uninstall.sh +++ b/uninstall.sh @@ -24,7 +24,7 @@ banner() { COMMANDS=( better better-swift config depfree fpr goals help next omd - plan-task pr pr-better push release replan review rpr scan simplify update + plan-task pr pr-better prd push release replan review rpr scan simplify update ) From 67f86aa5a24099cf57e03321c002fb67709dbd69 Mon Sep 17 00:00:00 2001 From: "[._.]/ Adam Eivy" Date: Thu, 13 Aug 2026 08:58:46 -0700 Subject: [PATCH 2/4] chore: release v3.28.0 --- .changelogs/NEXT.md | 10 ---------- .changelogs/v3.28.0.md | 23 +++++++++++++++++++++++ package.json | 2 +- 3 files changed, 24 insertions(+), 11 deletions(-) delete mode 100644 .changelogs/NEXT.md create mode 100644 .changelogs/v3.28.0.md diff --git a/.changelogs/NEXT.md b/.changelogs/NEXT.md deleted file mode 100644 index cbe8ce1..0000000 --- a/.changelogs/NEXT.md +++ /dev/null @@ -1,10 +0,0 @@ -# Unreleased Changes - -## Product requirements documents (`/do:goals --prd`, `/do:prd`) -- `/do:goals` now supports `--prd`, which generates a detailed `PRD.md` instead of the strategic `GOALS.md` — functional requirements, non-functional requirements, and explicit negative requirements ("must not") grouped by feature area, each with a stable ID and acceptance criteria, plus personas, out-of-scope, assumptions, success metrics, and open questions. -- `/do:prd` is a shorthand for `/do:goals --prd`. -- In `--interactive` mode, risks and open questions surfaced during generation are now resolved with you directly: judgment calls are asked and folded into the document, while purely factual items (like whether a referenced tracker issue is still open) are checked automatically instead of asked. -- Numeric success metrics are never invented — where the codebase doesn't evidence a concrete target, it's left as an open question rather than a fabricated number. - -## Contributing -- Added `CONTRIBUTING.md` covering project structure, local dev/test workflow, and commit/PR conventions. diff --git a/.changelogs/v3.28.0.md b/.changelogs/v3.28.0.md new file mode 100644 index 0000000..cbb9e01 --- /dev/null +++ b/.changelogs/v3.28.0.md @@ -0,0 +1,23 @@ +# Release v3.28.0 + +Released: 2026-08-13 + +## Highlights + +- **New `/do:goals --prd` mode (and `/do:prd` shorthand)** generates a detailed `PRD.md` instead of the strategic `GOALS.md` — functional requirements, non-functional requirements, and explicit negative requirements ("must not") grouped by feature area, each with a stable ID and acceptance criteria, plus personas, out-of-scope, assumptions, success metrics, and open questions. +- **Interactive mode now resolves risks and open questions with you directly** — judgment calls are asked and folded into the document, while purely factual items (like whether a referenced tracker issue is still open) are checked automatically instead of asked. +- **No fabricated metrics**: numeric success metrics are never invented — where the codebase doesn't evidence a concrete target, it's left as an open question rather than a made-up number. +- **Contributing**: added `CONTRIBUTING.md` covering project structure, local dev/test workflow, and commit/PR conventions. + +## Product requirements documents (`/do:goals --prd`, `/do:prd`) +- `/do:goals` now supports `--prd`, which generates a detailed `PRD.md` instead of the strategic `GOALS.md` — functional requirements, non-functional requirements, and explicit negative requirements ("must not") grouped by feature area, each with a stable ID and acceptance criteria, plus personas, out-of-scope, assumptions, success metrics, and open questions. +- `/do:prd` is a shorthand for `/do:goals --prd`. +- In `--interactive` mode, risks and open questions surfaced during generation are now resolved with you directly: judgment calls are asked and folded into the document, while purely factual items (like whether a referenced tracker issue is still open) are checked automatically instead of asked. +- Numeric success metrics are never invented — where the codebase doesn't evidence a concrete target, it's left as an open question rather than a fabricated number. + +## Contributing +- Added `CONTRIBUTING.md` covering project structure, local dev/test workflow, and commit/PR conventions. + +## Full Changelog + +**Full Diff**: https://github.com/atomantic/slashdo/compare/v3.27.1...v3.28.0 diff --git a/package.json b/package.json index 547cb55..b945b53 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "slash-do", - "version": "3.27.1", + "version": "3.28.0", "description": "Curated slash commands for AI coding assistants — Claude Code, OpenCode, Antigravity CLI, Codex, and Grok Build", "author": "Adam Eivy ", "license": "MIT", From f7e7a1037f3387480ad04eba9ad32f1a106c3b4e Mon Sep 17 00:00:00 2001 From: "[._.]/ Adam Eivy" Date: Thu, 13 Aug 2026 09:00:23 -0700 Subject: [PATCH 3/4] address review (local): fix stale cross-reference and inaccurate dependency claim commands/do/prd.md still pointed at "Validation 3g-3i" after 3j (Risks & Open Questions) was added to goals.md. CONTRIBUTING.md's install step implied dev-tooling dependencies exist; package.json has none. --- CONTRIBUTING.md | 11 +++++------ commands/do/prd.md | 2 +- 2 files changed, 6 insertions(+), 7 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ebff705..b8b9937 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -17,15 +17,14 @@ Thanks for considering a contribution. slashdo is a small, actively-maintained p ## Making a change -1. Fork and clone the repo. -2. Install dependencies: `npm install` (none currently required beyond dev tooling, but run it anyway). -3. Edit the relevant `commands/do/*.md` or `lib/*.md` source file. If you touch environment-specific behavior, wrap it in `……` (or the matching capability flag in `src/environments.js`) rather than hard-coding for one environment. -4. If you add or rename a command or lib file, update the `COMMANDS`/`LIBS` arrays in both `install.sh` and `uninstall.sh` — CI will fail the drift check otherwise. -5. Verify locally: +1. Fork and clone the repo. There are no npm dependencies to install — the package has none, and the test suite runs on Node's built-in test runner. +2. Edit the relevant `commands/do/*.md` or `lib/*.md` source file. If you touch environment-specific behavior, wrap it in `……` (or the matching capability flag in `src/environments.js`) rather than hard-coding for one environment. +3. If you add or rename a command or lib file, update the `COMMANDS`/`LIBS` arrays in both `install.sh` and `uninstall.sh` — CI will fail the drift check otherwise. +4. Verify locally: - `node bin/cli.js --list` — confirm the command shows up correctly - `node bin/cli.js --dry-run` — preview what install would do - `npm test` — run the full test suite -6. If your change affects behavior covered by an existing test, update it; if it adds new behavior worth locking in, add a test under `test/`. +5. If your change affects behavior covered by an existing test, update it; if it adds new behavior worth locking in, add a test under `test/`. ## Commit and PR conventions diff --git a/commands/do/prd.md b/commands/do/prd.md index f5ee268..89bcb3a 100644 --- a/commands/do/prd.md +++ b/commands/do/prd.md @@ -9,7 +9,7 @@ Shorthand for `/do:goals --prd`: scan the codebase and generate a detailed `PRD. ## Execution -Run the workflow defined in `~/.claude/commands/do/goals.md` **verbatim**, with `--prd` forced on — whether or not it appears in `$ARGUMENTS`. Its [PRD.md Structure](goals.md#prdmd-structure---prd) section and every other `--prd`-mode deviation (Discovery's Agent 4, Synthesis, Validation 3g-3i, Refresh Mode) is the specification. This command adds none of its own. +Run the workflow defined in `~/.claude/commands/do/goals.md` **verbatim**, with `--prd` forced on — whether or not it appears in `$ARGUMENTS`. Its [PRD.md Structure](goals.md#prdmd-structure---prd) section and every other `--prd`-mode deviation (Discovery's Agent 4, Synthesis, Validation 3g-3j, Refresh Mode) is the specification. This command adds none of its own. Argument handling: - Pass `$ARGUMENTS` through to `do:goals` verbatim, with `--prd` added if not already present. It parses every flag itself, including `--interactive`, `--refresh`, and focus hints — there is nothing to extract or re-validate here. From 0bbf4c507e929d3c5144142e858ec50cb02a14b8 Mon Sep 17 00:00:00 2001 From: "[._.]/ Adam Eivy" Date: Thu, 13 Aug 2026 09:04:54 -0700 Subject: [PATCH 4/4] address review (claude): fix commands badge to match the actual 21-row table MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The badge undercounted by one both before and after this diff's +1 bump — commands/do/ has 21 files (20 workflow commands plus help.md, which is itself a listed command), matching the README table's 21 rows. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 5eca54b..9d41a6d 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@

npm version environments - commands + commands license