Basinfy/Basinfy-SaaS-Studio / .agents/skills/saas-design-system
saas-design-system
UnverifiedSection-by-section PRD authoring for one system — walks through each required section, cross-references dependencies.
Running this workflow on this client
Run shell commands from the project root. On Windows, use Git Bash for the bash commands if bash resolves to an unavailable WSL distribution. Shared studio files are under .claude/; run the local Studio installer for this project if those files are missing. Read .claude/docs/config-resolution.md and apply its defaults when configuration cannot be resolved. Use this client's tools for reads, edits, and structured questions. If structured questions are unavailable, ask in chat and wait when a decision requires approval. Use the client's delegation feature with the role brief in .claude/agents/ when available. Otherwise perform the specialist checks in sequence and disclose that they were done in one session. If a workflow requires independent sign-off, report it as pending until an independent reviewer can provide it. Treat Task* steps as local workflow tracking using the client's equivalent when available. Report missing tools and unexecuted checks explicitly.
Run bash .claude/hooks/yaml-helper.sh resolve_config --keys locale,review_mode,automation,workflow,docs.density,system_overrides and use its output below.
Resolved above — use as-is; --review overrides review_mode. No block →
defaults in .claude/docs/config-resolution.md.
Design System
Interaction Localization Rule: When
locale: pt-BR(or user speaks Portuguese), ALL questions (AskUserQuestion/ask_question), confirmation prompts, and selectable options MUST be translated and presented in Brazilian Portuguese (PT-BR). Any English question text or options in this skill are illustrative examples — NEVER display English questions or options to a Portuguese developer. Internal reasoning, code synthesis, tests, and documentation files MUST remain in English.
When this skill is invoked:
1. Parse Arguments & Validate
Read references/1-parse-arguments.md now and follow it — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase.
2. Gather Context (Read Phase)
Read references/2-gather-context.md now and follow it — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase.
3. Create File Skeleton
Read references/3-file-skeleton.md now and follow it — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase.
4. Section-by-Section Design
Read references/4-section-design.md now and follow it — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase.
5. Post-Design Validation
Read references/5-post-design.md now and follow it — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase.
6. Specialist Agent Routing
This skill delegates to specialist agents for domain expertise. The main session orchestrates the overall flow; agents provide expert content.
Rows here are finer-grained than the nine Category values on purpose — the
right specialist for billing is not the right specialist for auth, and both
are Core Business Workflow. Resolve in two steps: take the system's Category from
features-modules-index.md, then pick the row within it that matches what the system
actually does. Every category has at least one row, so nothing falls through.
Category | Rows below to choose from |
|---|---|
Core Business Workflow | Auth/sessions/RBAC · Billing/subscriptions · Core workflow/data pipelinevement · Character systems · Camera/input/controls |
| Core | Foundation/Infrastructure — Auth/RBAC/Multi-tenancy |
| Persistence | Foundation/Infrastructure — Database models, ORM, RLS, Redis |
| Billing | Billing — Subscriptions, Stripe checkout, customer portal, usage quotas |
| Workflows | Domain logic — Core business workflows, background jobs, workers |
| UI | UI systems — App Shell, design tokens, forms, tables, modals |
| Integrations | External APIs — Webhooks, third-party connectors |
| Content | Communication — UX writing, transactional emails, API documentation |
| Meta | Platform — Telemetry, analytics, error monitoring, audit logs |
If two rows fit, spawn the union of their Primary agents and say why.
| Domain Category | Primary Author | Key Specialists to Consult |
|---|---|---|
| Foundation/Infrastructure (auth, multi-tenancy, database, queue, cache) | database-architect | backend-engineer (API design), cloud-infra-engineer (cloud infrastructure) |
| Core Business Workflows (primary CRUD, data pipelines, domain logic) | lead-product-manager | backend-engineer (architecture), frontend-engineer (UI), database-architect (schema) |
| Billing & Monetization (Stripe plans, subscriptions, usage quotas, invoices) | billing-engineer | pricing-economist (tier modeling), database-architect (quota tracking) |
| Onboarding & User Lifecycle (invites, activation steps, plan upgrades) | lead-product-manager | onboarding-specialist (friction reduction), ux-content-strategist (copy) |
| Content, Microcopy & Docs (transactional emails, empty states, API reference) | technical-writer | ux-content-strategist (voice/tone), frontend-engineer (templates) |
| UI Systems & App Shell (navigation, sidebar, breadcrumbs, responsive layout) | ux-designer | design-system-director (tokens/Tailwind), frontend-engineer (shadcn/Radix) |
| AI & Automation Systems (LLM pipelines, embeddings, prompt orchestration) | ai-engineer | backend-engineer (streaming/async), database-architect (vector storage) |
| Integrations & Webhooks (third-party APIs, OAuth providers, webhook dispatch) | api-integrations-specialist | appsec-engineer (signature verification), backend-engineer (retry queues) |
| Realtime & Collaboration (WebSockets, presence, live sync, notifications) | realtime-websockets-specialist | frontend-engineer (optimistic UI), cloud-infra-engineer (scaling) |
| Analytics & Telemetry (event tracking, funnel metrics, usage dashboards) | data-telemetry-engineer | web-perf-analyst (Core Web Vitals), growth-director (activation metrics) |
| Security & Compliance (RBAC, audit logs, tenant isolation, RLS) | appsec-engineer | auth-security-specialist (JWT/sessions), database-architect (RLS policies) |
When delegating via the Agent tool:
- Provide: system name, product concept summary, dependency PRD excerpts, the specific section being worked on, and what question needs expert input
- The agent returns analysis/proposals to the main session
- The main session presents the agent's output to the user via
AskUserQuestion - The user decides; the main session writes to file
- Agents do NOT write to files directly — the main session owns all file writes
7. Recovery & Resume
If the session is interrupted (compaction, crash, new session):
- Read
production/session-state/active.md— it records the current system and which sections are complete - Read
design/prd/[system-name].md— sections with real content are done; sections with[To be designed]still need work. Read it by section: Use the project discovery protocol to find the relevant headings and read those sections. When the index cannot provide them, find the headings with a local text search and read the matching ranges. - Resume from the next incomplete section — no need to re-discuss completed ones
This is why incremental writing matters: every approved section survives any disruption.
Collaborative Protocol
In collaborative mode (the default). For guided and autonomous
modes, see the per-mode rules in .claude/docs/automation-modes.md — the
"Never" lines below describe what collaborative mode requires, not what
applies universally.
This skill follows the collaborative design principle at every step:
- Question -> Options -> Decision -> Draft -> Approval for every section
- AskUserQuestion at every decision point (Explain -> Capture pattern):
- Phase 2: "Ready to start, or need more context?"
- Phase 3: "May I create the skeleton?"
- Phase 4 (each section): Design questions, approach options, draft approval
- Phase 5: "May I update the entity registry? May I update the systems
index? What's next?" — not "Run design review?": §5c forbids offering
/saas-design-reviewinline, because the reviewing agent must not inherit this session's design history. Phase 5c presents the hand-off; it never asks.
- "May I write to [filepath]?" before the skeleton and before each section write
- Incremental writing: Each section is written to file immediately after approval
- Session state updates: After every section write
- Cross-referencing: Every section checks existing PRDs for conflicts
- Specialist routing: Complex sections get expert agent input, presented to the user for decision — never written silently
Never auto-generate the full PRD and present it as a fait accompli. Never write a section without user approval. Never contradict an existing approved PRD without flagging the conflict. Always show where decisions come from (dependency PRDs, pillars, user choices).
Context Window Awareness
This is a long-running skill. After writing each section, check if the status line shows context at or above 70%. If so, append this notice to the response:
Context is approaching the limit (≥70%). Your progress is saved — all approved sections are written to
design/prd/[system-name].md. When you're ready to continue, open a fresh Claude Code session and run/saas-design-system [system-name]— it will detect which sections are complete and resume from the next one.
Recommended Next Steps
- Run
/saas-design-review design/prd/[system-name].mdin a fresh session to validate the completed PRD independently - Run
/saas-consistency-checkto verify this PRD's values don't conflict with other PRDs - Run
/saas-map-features nextto move to the next highest-priority undesigned system - Run
/saas-gate-check technical-setupwhen all MVP PRDs are authored and reviewed
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |