Basinfy/Basinfy-SaaS-Studio / .agents/skills/saas-create-architecture
saas-create-architecture
UnverifiedAuthor the architecture blueprint before code is written. Validates decisions against the pinned engine, flags knowledge gaps.
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 and use its output below.
Resolved above — use as-is; --review overrides review_mode. No block →
defaults in .claude/docs/config-resolution.md.
Create Architecture
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.
This skill produces docs/architecture/architecture.md — the master architecture
document that translates all approved PRDs into a concrete technical blueprint.
It sits between design and implementation, and must exist before sprint planning begins.
Distinct from /saas-architecture-decision: ADRs record individual point decisions.
This skill creates the whole-system blueprint that gives ADRs their context.
See .claude/docs/director-gates.md for the full check pattern. Individual gate definitions live in .claude/docs/director-gates/[gate-id].md — the spawned agent reads its own gate file; do not read it in the parent session.
Every AskUserQuestion call follows .claude/docs/automation-modes.md
(collaborative asks always · guided major-only · autonomous logs and proceeds;
automation_always_ask categories always prompt).
docs.density — it controls per-section depth, where workflow
controls which sections exist. modes.rigor sets both together; set
docs.density explicitly to vary depth alone: terse (the default, via rigor: minimal) = layer diagrams + decision bullets,
no essays; balanced = diagrams + paragraph explanations of layer choices
(rigor: standard); thorough = full prose with rationale, trade-offs, and alternatives
considered per layer. Apply it to every section you author.
workflow (see .claude/docs/workflow-modes.md):
full— full architecture: all layers, module ownership, data flow, API boundaries, full ADR audit.standard— simplified: system layer map + critical ADR list only.minimal— not required. Can still be run voluntarily.
Argument modes:
- No argument /
full: Full guided walkthrough — all sections, start to finish layers: Focus on the system layer diagram onlydata-flow: Focus on data flow between modules onlyapi-boundaries: Focus on API boundary definitions onlyadr-audit: Audit existing ADRs for stack compatibility gaps only
Phase 0: Load All Context
Read references/0-load-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.
Phase 1: System Layer Mapping
Read references/1-layers.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.
Phase 2: Module Ownership Map
Read references/2-module-ownership.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.
Phase 3: Data Flow
Read references/3-data-flow.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.
Phase 4: API Boundaries
Read references/4-api-boundaries.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.
Phase 5: ADR Audit + Traceability Check
Read references/5-adr-audit.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.
Phase 6: Missing ADR List
Read references/6-missing-adrs.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.
Phase 7: Write the Master Architecture Document
Read references/7-write.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.
Phase 8: Handoff
Read references/8-handoff.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.
Collaborative Protocol
Applies in collaborative mode (the default). For guided and
autonomous modes, see .claude/docs/automation-modes.md — the rules below
describe what collaborative mode requires, not universal behavior.
This skill follows the collaborative design principle at every phase:
- Load context silently — do not narrate file reads
- Present findings — show the knowledge gap inventory and layer proposals
- Ask before deciding — present options for each architectural choice
- Draft before approval — show the content inline before asking to write it. Never ask approval for a section the user has not yet seen.
- Use
AskUserQuestionfor write approvals — plain text "May I?" is not sufficient. Use the structured tool with labeled options [A]/[B]/[C] (write now / show full draft first / not yet). For multi-file changesets, list every file and what changes, then ask once grouped — not separate plain-text asks per file. - One write, after every section is approved — the document is written once,
at Phase 7; Phase 7b's Step 4 only updates its Document Status, after its own
ask. Record each approved section's decisions in
production/session-state/active.mdas you go, so a crash loses no decision. A revision that Phase 7b forces is written the same way — once, after its re-drafted sections are approved — and an update (Phase 0e) writes only the sections it chose.
Never make a binding architectural decision without user input. If the user is unsure, present 2-4 options with pros/cons before asking them to decide.
Recommended Next Steps
- Run
/saas-architecture-decision [title]for each required ADR listed in Phase 6 — Foundation layer ADRs first - Run
/saas-architecture-review— bootstraps the Requirements Traceability Matrix and TR registry from the ADRs just written, and gives each provisional TR-ID its permanent one. Required before the Pre-Production gate. - Run
/saas-test-setupto scaffoldtests/unit/,tests/integration/, CI workflow, and an example test (required for gate-check) - Run
/saas-ux-designto initializedesign/ux/interaction-patterns.mdanddesign/accessibility-requirements.md(required for gate-check) - Run
/saas-create-control-manifestonce the required ADRs are written to produce the layer rules manifest - Run
/saas-gate-check pre-productionwhen all required ADRs,/saas-test-setup, and/saas-ux-designare complete
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |