arthai-marketplace

/planning

Generate a PRD (product requirements document) for a feature — user stories, journey, edge cases, success criteria — plus an async tech feasibility note from the architect. Includes a design spec HTML by default (use –no-design to skip).

Synopsis

/planning <feature-name> [--no-design] [--gtm] [--sync] [--design-spec-only] [--check] [-- brief]

When to use it

Quickstart

/planning dark-mode -- Users want a dark theme that follows system preference and persists per account

What you’ll see: a PRD written to .claude/specs/dark-mode.md, a design spec at .claude/specs/dark-mode-design.html, and the architect’s feasibility verdict (GREEN / YELLOW / RED) — then a prompt to review the PRD before running /implementation-plan.

Examples

/planning oauth-login -- Add Google OAuth sign-in        # most common — name + inline brief
/planning oauth-login                                    # no brief — skill asks for one interactively
/planning admin-report --no-design -- CSV export...      # PRD only, skip UX brief + design spec HTML
/planning checkout --gtm -- One-click checkout...        # add GTM positioning input to the PRD
/planning oauth-login --design-spec-only                 # backfill a design spec for a PRD made with --no-design
/planning oauth-login --check                             # read-only: does the design spec still match the PRD?

Arguments & flags

Flag Values Default What it does
--no-design — off Skip the UX brief and design spec HTML — PRD only. Cannot be combined with --sync, --design-spec-only, or --check.
--gtm — off Adds a GTM Expert positioning note that shapes the PRD’s target user and success metrics
--sync — off Currently stubbed: prints a not-yet-implemented notice (design-artifact sync is planned for v1.1) and exits without changes. Use --design-spec-only or --check below instead.
--design-spec-only — off Skips PRD regeneration and operates on an existing PRD: spawns the design-spec-writer agent, writes the design spec sibling file, and patches the PRD frontmatter. Use this to backfill a design spec for a PRD that was generated with --no-design. Idempotent — safe to re-run.
--check — off Read-only drift check: compares the design spec’s recorded PRD hash against the current PRD body and exits 0 (match) or 1 (mismatch, with guidance). Makes no file changes. Useful for CI / pre-commit / drift-hook automation.
-- <brief> free text — Inline feature brief (2–3 sentences). Everything after -- is the brief.

--sync, --design-spec-only, and --check are pairwise exclusive — pass at most one, and all three require an existing PRD (pass feature-name as the first positional argument).

Mode flags like --fast/--lite/--full are not used in PRD generation — the skill prints a hint and continues with the normal PRD flow, ignoring the flag. Those flags belong to /implementation-plan, where they control the architecture debate.

What it does

  1. Interactive resolution — if the feature name or brief wasn’t passed inline, asks for them via AskUserQuestion (user-confirmation checkpoint; every question includes Cancel). Names are silently normalized to kebab-case. Running in the Arth cloud sandbox: you’ll also get one extra round of scope-clarifying questions (MVP vs. full, target user/surface, etc.) before the PRD is written — this only happens in cloud runs, never in a local terminal or CI.
  2. Context gathering — an explore-light agent scans the codebase for related routes, components, models, and tests; topic wikis and the project knowledge graph/base are consulted.
  3. Input briefs (parallel) — a Design Thinker writes a short UX brief (skipped with --no-design) and, with --gtm, a GTM Expert writes a positioning note. These feed into the PM — they are not separate PRD sections.
  4. PRD writing (parallel) — the Product Manager writes the PRD (user stories US-N with priorities and acceptance, user journey, edge cases EC-N, success criteria); the Architect writes a tech feasibility note (GREEN / YELLOW / RED) flagging hard constraints and high-risk areas. No debate happens here.
  5. Design spec generation — a design-spec-writer agent produces the design spec HTML (user journeys, key screens, interaction principles, accessibility, design system), hash-linked to the PRD for drift detection. Skipped with --no-design.
  6. Present and hand off — prints the PRD path and feasibility verdict, then stops. User-confirmation checkpoint: /implementation-plan is never auto-invoked — even in autopilot — because PRD review is the whole point of the two-phase split.

Agents spawned

Agent Model tier Role
explore-light haiku Codebase scan
design-thinker sonnet UX brief (default; skipped with --no-design)
gtm-expert sonnet Positioning note (--gtm only)
product-manager sonnet Writes the PRD
architect sonnet Tech feasibility note
design-spec-writer sonnet Design spec HTML (default; skipped with --no-design)

Output & artifacts

Troubleshooting

Problem Fix
missing required args in non-interactive mode In CI/autopilot the skill won’t prompt — pass the feature name and -- <brief> inline
--no-design cannot be used with --{flag} Pick one — --sync, --design-spec-only, and --check all require a PRD that already has design artifacts (i.e. was not generated with --no-design)
--sync is not yet implemented (planned for v1.1) Expected — --sync is a stub today. Use --design-spec-only to regenerate the design spec, or --check to read-only-detect drift
Feasibility comes back RED or YELLOW Read the printed hard constraints — revising the PRD now is far cheaper than after the architecture debate
Design spec contains TODO markers The writer’s output was incomplete on both attempts — re-run with /planning <feature> --design-spec-only as the warning suggests