project-summary

name	project-summary
description	Render a branded visual artifact from a project's prd.json (plan summary) or brainstorm.md (research deck) and deploy it gated, returning a link.
allowed-tools	Read, Grep, Glob, Write, Edit, Bash(ls:*), Bash(cat:*), Bash(jq:*), Bash(date:*), Bash(mkdir:*), Bash(awk:*), Bash(grep:*), Bash(test:*), Bash(bash:*), Bash(.claude/skills/project-summary/scripts/deploy-summary.sh:*)

Project Summary

Render a visual, shareable artifact for a project and deploy it via hq-deploy, returning a link. Two modes:

• plan mode (default) — visualizes a finished PRD: objectives, the plan (story map), phasing, and product-style UX mockups (or an architecture diagram for backend work). Auto-run at the end of /plan and /deep-plan (their Step 8.9), and via /project-summary {co}/{name}.
• deck mode (--brainstorm) — visualizes a brainstorm as a research/findings deck: the framing, what we know / don't know, the premise verdict, the approaches compared with their tradeoffs, and the recommendation. Auto-run at the end of /brainstorm, and via /project-summary {co}/{name} --brainstorm.

Guiding principle: the source file already exists; this skill only visualizes it. It reads prd.json (plan mode) or brainstorm.md (deck mode), never re-plans, and never touches target repos. It is idempotent — rerun anytime to regenerate and redeploy at the same stable URL.

---

Step 1: Resolve the project + mode

Accept {co}/{name}, a bare {name}, or a project directory path, plus an optional --brainstorm flag (or a brainstorm.md path) selecting deck mode.

1. Locate the project dir:
   • companies/{co}/projects/{name}/ when a company is given or inferable.
   • projects/{name}/ or personal/projects/{name}/ for personal / HQ projects (no company).
   • If only {name} is given, find it: qmd search "{name}" --json -n 5 or check the locations directly.
2. Pick the mode + source file:
   • deck mode (--brainstorm, or input points at a brainstorm.md) → source is {dir}/brainstorm.md.
   • plan mode (default) → source is {dir}/prd.json.
   • If the chosen source is missing, stop with a one-line message: No {source} at {path} — run /{prd|brainstorm} first. (When called from a skill's auto-step the path is already known, so this never triggers.)
3. Set {co} (may be empty for personal projects), {name}, and {mode} for the rest of the flow.

Step 2: Read project data

Plan mode

Read prd.json (and README.md if present). Extract:

• name, description
• metadata.goal, metadata.successCriteria
• metadata.audiences, metadata.designRef, metadata.repoPath
• metadata.nonGoals, metadata.dataModel, metadata.architectureNotes, metadata.integrations
• userStories[] → id, title, priority, labels, acceptanceCriteria, dependsOn

Derive phasing from priority (group stories by priority ascending; respect dependsOn ordering within a group). This is the "shape of it, ordered for execution."

Deck mode

Parse brainstorm.md — its frontmatter (company, status, source_idea_id) and sections:

• # {Title} + the > {framing} blockquote (one-line problem/opportunity)
• ## Context
• ## What We Know (bullets) and ## What We Don't Know (bullets)
• ## Premise Check → the verdict token (STRONG / QUESTIONABLE / WEAK) + reasoning
• ## Narrowest Wedge (if present)
• ## Approaches → each ### Option {X}: {Name} with How it works, Tradeoffs (Pro/Con bullets), Effort (S/M/L/XL), When to choose this
• ## Recommendation → preferred option, Key condition, Biggest risk
• ## Next Steps (checkbox bullets)

Step 3: Resolve the design standard

Look for a company design pack:

ls companies/{co}/knowledge/design-styles/packs/*/pack.yaml 2>/dev/null

• Pack found → pick the bound/default pack (if multiple, prefer one whose pack.yaml type: brand; for Indigo this is indigo-blueprint). Then, per companies/{co}/policies/*deploy*blueprint* (load-at-authoring-time rules):
  1. Read the pack's design-tokens.css and inline it into :root of the artifact.
  2. Read the pack's implementation.md and build sections from its HTML/CSS blocks — copy the system, edit only the content. Never hardcode hex; reference var(--token).
  3. Honor the typeface roles and single-accent discipline the pack defines.
• No pack (personal projects, or company without one) → inline the shipped fallback theme .claude/skills/project-summary/templates/default.css into :root. It uses the same token names, so the same markup renders correctly either way.

Step 4: Decide the visuals

Plan mode — mockup type (auto-detect)

Classify the project from prd.json to choose what to draw:

User-facing product → UX / screen mockups if ANY of:

• metadata.audiences names end users / customers (not just "developers" / "internal tooling"),
• metadata.designRef is non-empty,
• story titles or acceptance criteria contain UI words: page, screen, view, form, button, dashboard, modal, onboarding, wizard, table, list, UI, UX, component, layout, nav.

Otherwise → architecture / flow diagram (backend, CLI, data, infra): draw a labeled box-and-arrow SVG of the system (inputs → components → outputs / data stores), derived from metadata.dataModel, metadata.integrations, metadata.architectureNotes, and the stories.

In BOTH cases the mockups are illustrative wireframes generated from the PRD, drawn as inline SVG/HTML styled with the resolved tokens, and each is clearly labeled "concept mockup — not final UI" (use the .concept-note class). Do not imply these are real screenshots.

Deck mode — comparison visuals

No UX mockups. Instead draw, from brainstorm.md:

• a premise verdict badge (STRONG = --pass, QUESTIONABLE = --warn, WEAK = --err),
• an options-comparison of the approaches side by side: one card per option with its effort badge and Pro/Con tradeoffs, the recommended option visually highlighted (accent border / "RECOMMENDED" tag),
• the recommendation as a highlighted callout (preferred option + key condition + biggest risk).

Step 5: Render index.html

Write a single self-contained file (inline CSS + inline SVG, no external fetches beyond the brand's web-font <link> if the pack uses one) to:

workspace/project-summary/{slug}/index.html

Build slug: {co}-{name} for company projects, personal-{name} for personal ones; in deck mode append -brainstorm (e.g. personal-publish-kit-direct-brainstorm) so plan and deck artifacts never collide.

Plan mode sections (in order)

1. Hero — kicker ({co} · project), {name} as h1, one-line goal as .lead.
2. Objectives & success — metadata.goal + metadata.successCriteria as .checks.
3. The plan — story-map table: # / Story / Priority (mirror the PRD-done screenshot; id in the .num column). One row per story.
4. Phasing — stories grouped by priority into phases, with a one-line intent per phase.
5. Mockups — UX screens OR architecture diagram per Step 4, each .concept-note labeled.
6. Footer — metadata.nonGoals (or "None defined") + generated from prd.json · {date}.

Deck mode sections (in order) — a research/findings deck

1. Title slide — kicker ({co} · brainstorm), title as h1, the framing line as .lead, and the premise verdict badge.
2. Context — the ## Context prose.
3. What we know / What we don't — two columns (.grid2), .checks lists.
4. Approaches — the comparison cards from Step 4 (effort badge + Pro/Con per option, recommended one highlighted).
5. Recommendation — highlighted callout: preferred option, key condition, biggest risk.
6. Next steps — the ## Next Steps checklist, plus the promotion path.
7. Footer — generated from brainstorm.md · {date} (date -u +%Y-%m-%d).

Keep it responsive to 360px. Verify the file exists and is non-trivial (>2KB) before deploying.

Step 6: Deploy + return the link

Run the deploy wrapper. App name is {slug}-summary in plan mode, {slug}-brainstorm in deck mode (the build slug already carries the -brainstorm suffix, so pass it as the app name too). Company slug is optional — omit/empty for personal projects:

# plan mode
bash .claude/skills/project-summary/scripts/deploy-summary.sh \
  "workspace/project-summary/{slug}" "{slug}-summary" "{co}"
# deck mode ({slug} ends in -brainstorm)
bash .claude/skills/project-summary/scripts/deploy-summary.sh \
  "workspace/project-summary/{slug}" "{slug}" "{co}"

It is idempotent (stable app name → stable URL), gates to the project's company when a cloud_uid resolves from companies/manifest.yaml, and falls back to a password gate for personal / no-company projects. Parse its KEY=VALUE output and report:

• Plan, company-gated → Visual summary is live (members only): {LIVE}
• Deck, company-gated → Brainstorm deck is live (members only): {LIVE}
• Password-gated → … is live: {LIVE} — password: {PASSWORD} (copied to clipboard)

Non-fatal: if the script exits non-zero (e.g. ERR: no_identity), do NOT fail the caller. Report skipped — {reason} and continue. The calling skill must never be blocked by this deploy.

Rules

• Read-only on the project — never edit prd.json, brainstorm.md, README.md, or any target repo. This is a visualization of existing planning output, subject to the no-implement rule.
• The source file is the source of truth — every value shown comes from prd.json (plan mode) or brainstorm.md (deck mode); never invent stories, options, criteria, or scope.
• Stay on the brand — when a company pack exists, build from its implementation.md and reference var(--token); never hardcode colors or hand-roll a competing stylesheet.
• Idempotent — same project → same app name → same URL. Reruns refresh content in place.
• Quiet + plain — surface only the final link (or a one-line skip). No play-by-play.
• Tenant isolation — only ever read the resolved company's pack/policies and gate to that company. Never cross companies.