Multi-agent debate to derive optimal design through two perspectives. Domain Architect + Best Practice Advisor collaborate in round-based debate. Triggers: arch, architecture, blueprint, 설계, 아키텍처
Generates software architecture designs through multi-agent debate between domain and best-practice perspectives.
/plugin marketplace add samdae/archflow/plugin install archflow@archflow-marketplaceThis skill is limited to using the following tools:
templates/be.mdtemplates/fe.mdGlobal Rules: Adheres to
rules/archflow-rules.md. Code Mapping#Rule: Always usemax(existing #) + 1for new rows. NEVER reuse deleted numbers. Document Version Control: After changes, commit recommended. Message:docs({serviceName}): arch - {summary}. If git unavailable, skip. Req ID Parsing: Extract from spec.md## 0. Requirement Summarytable. Each Req ID maps to Code MappingSpec Ref(1:N).
Model: Opus required. Design quality determines implementation quality.
Two perspective sub-agents collaborate to derive optimal design.
| Tool | Alternative |
|---|---|
| Read/Grep | Request file path, ask for copy-paste |
| AskQuestion | "Please select: 1) A 2) B 3) C" format |
| Task | Use Self-Debate Pattern (see below) |
Play two roles sequentially:
**Role A: Domain Architect** - Full project context, design that fits this project
Considerations: Existing patterns, technical constraints, team familiarity
**Role B: Best Practice Advisor** - Feature requirements only, ideal design
Considerations: Industry standards, scalability, maintainability
Phase 1: Role A provides design proposal
Phase 2 (Cross-Review): Switch to Role B.
Review the Role A design and provide:
1. What you agree with
2. Concerns or risks
3. Alternative suggestions
4. Can we reach consensus? [Yes / Need discussion]
Phase 3 (Counter-Review): Return to Role A.
Review Role B's feedback and provide:
1. Valid points you can accept
2. Points you must reject (with project-specific reasons)
3. Proposed compromises
4. Final stance: [Agreement / Need user decision]
Phase 4 (Synthesis): Synthesize both perspectives into final design.
Document in "Risks & Tradeoffs":
- Chosen approach
- Rejected alternatives and why
- Assumptions made
- Points requiring user decision (if any)
When to use: Only when Task tool is unavailable.
docs/{serviceName}/
spec.md <- input
arch-be.md <- output (Backend)
arch-fe.md <- output (Frontend)
ui.md <- input (FE only, from /ui skill)
serviceName inference: Extracted from input file path docs/{serviceName}/spec.md
| Agent | Role | Context |
|---|---|---|
| domain-architect | Project context-based design | Requirements + project structure |
| best-practice-advisor | Best practice suggestions | Feature request only (no context) |
docs/ subdirectoriesdocs/auth): auto-select, confirm with user
If multiple: ask user to select. If none: manual input.spec.md = docs/{serviceName}/spec.mdarch-be.md = docs/{serviceName}/arch-be.mdarch-fe.md = docs/{serviceName}/arch-fe.mdui.md = docs/{serviceName}/ui.mdWARNING: This skill strongly recommends Opus model. Design quality determines implementation quality, so maintain Opus even when cost savings are needed.
Input:
docs/{serviceName}/spec.md| Output:docs/{serviceName}/arch-be.mdorarch-fe.md
If serviceName resolved in Phase -1: verify spec.md exists, proceed to 0-1.5.
If not exists: "Requirements not found at docs/{serviceName}/spec.md. Run /spec or /reverse first."
If NOT resolved:
{"title":"Start Design Debate","questions":[{"id":"has_requirements","prompt":"Do you have a requirements document? (docs/{serviceName}/spec.md)","options":[{"id":"yes","label":"Yes - I will provide via @filepath"},{"id":"no","label":"No - Need requirements refinement first"}]}]}
yes -> Request file path -> 0-1.5no -> Guide to spec skill{"title":"Architecture Type","questions":[{"id":"arch_type","prompt":"What type of architecture are you designing?","options":[{"id":"be","label":"Backend - API server, business logic, database"},{"id":"fe","label":"Frontend - Web app, SPA, components"}]}]}
be -> Read templates/be.md, use as output templatefe -> Check for ui.md first, then read templates/fe.mdWARNING: MUST read the template file before proceeding to Phase 1.
Verify docs/{serviceName}/ui.md exists:
{"title":"UI Specification Check","questions":[{"id":"has_ui_spec","prompt":"Do you have a UI specification? (docs/{serviceName}/ui.md)","options":[{"id":"yes","label":"Yes - I will provide via @filepath"},{"id":"no","label":"No - I need to run /ui first"}]}]}
yes -> Request ui.md path -> Proceed to Phase 1no -> Show guidance:
WARNING: UI specification required for Frontend architecture. Run
/uifirst to generate UI specification from:
docs/{serviceName}/spec.mddocs/{serviceName}/arch-be.mdThe ui.md defines screens, components, and interactions needed for arch-fe.
NOTE: Frontend arch input = spec.md + ui.md (NOT arch-be.md directly).
{"title":"Project Type","questions":[{"id":"project_type","prompt":"Is this a new project or existing project?","options":[{"id":"new","label":"New project - Start from scratch"},{"id":"existing","label":"Existing project - Has code already"}]}]}
new -> 0-1.8 (Setup Strategy)existing -> 0-1.7a (Path Detection)Auto-detect by scanning for dependency files:
| Language | Files to Check | Detected Path |
|---|---|---|
| Python | pyproject.toml, requirements.txt | Parent directory of file |
| Node.js | package.json | Parent directory of file |
{"title":"Detected Project Paths","questions":[{"id":"path_confirm","prompt":"I found:\n- BE: {detected_be_path}\n- FE: {detected_fe_path}\n\nCorrect?","options":[{"id":"accept","label":"Yes - Use these paths"},{"id":"modify","label":"No - I will specify manually"}]}]}
accept -> 0-1.7b | modify -> manual input -> 0-1.7bRead dependency files from detected paths. Extract:
-> Proceed to 0-1.9
{"title":"Setup Strategy","questions":[{"id":"setup_strategy","prompt":"How would you like to configure the project?","options":[{"id":"recommend","label":"LLM Recommendation - AI proposes optimal setup based on requirements"},{"id":"manual","label":"Manual Selection - I will choose each option"}]}]}
recommend -> 0-1.8a | manual -> 0-1.8bAnalyze spec.md and propose complete setup:
{"title":"Proposed Project Setup","questions":[{"id":"full_proposal","prompt":"Based on analysis:\n\n**Structure**: {type}\n- BE: {be_path} | FE: {fe_path}\n\n**Stack**: {lang} / {fw} / {db} / {orm}\n**PM**: {pm}\n**Run**: BE: {cmd_be} | FE: {cmd_fe}\n**Libraries**: {libs}\n\nAccept?","options":[{"id":"accept","label":"Accept - Proceed with this setup"},{"id":"modify","label":"Modify - Switch to manual selection"}]}]}
accept -> Save all, proceed to 0-2 | modify -> 0-1.8b{"title":"Project Structure","questions":[{"id":"project_structure","prompt":"What project structure do you want?","options":[{"id":"monorepo","label":"Monorepo - BE+FE in same repo (apps/{serviceName}-api|web)"},{"id":"monolith","label":"Monolith - Single service (backend/, frontend/)"},{"id":"custom","label":"Custom - I will specify paths"}]}]}
monorepo -> apps/{serviceName}-api, apps/{serviceName}-webmonolith -> backend/, frontend/custom -> manual path input{"title":"Language Selection","questions":[{"id":"language","prompt":"What programming language for backend?","options":[{"id":"python","label":"Python"},{"id":"typescript","label":"TypeScript (Node.js)"},{"id":"go","label":"Go"},{"id":"java","label":"Java"},{"id":"other","label":"Other (specify)"}]}]}
Then ask framework based on language:
| Language | Framework Options |
|---|---|
| Python | FastAPI, Django, Flask |
| TypeScript | NestJS, Express, Fastify |
| Go | Gin, Echo, Fiber |
| Java | Spring Boot, Quarkus |
{"title":"Database Selection","questions":[{"id":"database","prompt":"What database will you use?","options":[{"id":"postgresql","label":"PostgreSQL"},{"id":"mysql","label":"MySQL / MariaDB"},{"id":"mongodb","label":"MongoDB"},{"id":"sqlite","label":"SQLite"},{"id":"none","label":"No database"},{"id":"other","label":"Other (specify)"}]}]}
ORM by language:
| Language | ORM Options |
|---|---|
| Python | SQLAlchemy, Tortoise ORM, Raw SQL |
| TypeScript | Prisma, TypeORM, Drizzle, Raw SQL |
| Go | GORM, sqlx, Raw SQL |
| Java | JPA/Hibernate, MyBatis, Raw SQL |
Python:
{"title":"Python Package Manager","questions":[{"id":"python_pkg_manager","prompt":"Which package manager?","options":[{"id":"uv","label":"uv - Fast, modern"},{"id":"pip","label":"pip + venv - Standard Python"},{"id":"poetry","label":"Poetry - Dep management + packaging"}]}]}
Node.js:
{"title":"Node Package Manager","questions":[{"id":"node_pkg_manager","prompt":"Which package manager?","options":[{"id":"npm","label":"npm - Default Node.js"},{"id":"yarn","label":"Yarn - Fast, reliable"},{"id":"pnpm","label":"pnpm - Efficient disk space"}]}]}
-> After all manual selections, proceed to 0-1.9
Analyze spec.md requirements, recommend libraries per feature:
{"title":"Library Review: {feature_name}","questions":[{"id":"lib_{library_name}","prompt":"{library_name} ({version}) - {purpose}","options":[{"id":"use","label":"Use as recommended"},{"id":"skip","label":"Don't use"},{"id":"alt","label":"Use alternative (specify)"},{"id":"recommend","label":"Get LLM recommendation"}]}]}
For existing projects: show installed with markers, highlight missing. Record decisions in Dependencies section.
Extract from path: docs/alert/spec.md -> serviceName = "alert"
Output: docs/alert/arch-be.md or docs/alert/arch-fe.md
Confirm requirements doc path (e.g., @docs/alert/spec.md).
If already provided -> Phase 1.5.
Read spec.md and extract Requirement Summary grid:
## 0. Requirement Summary sectionSpec Ref (1:N)If not found: warn "spec.md missing Requirement Summary grid", suggest /reinforce.
Task(
subagent_type: "domain-architect",
description: "Project context-based design",
prompt: """
Requirements: {requirements MD content}
Feature description: {feature description}
Project structure: {project exploration results}
Based on the above, provide a design proposal.
"""
)
Expected: design proposal (implementation approach, file structure, dependencies), constraints, tradeoffs.
Task(
subagent_type: "best-practice-advisor",
description: "Best practice-based design",
prompt: """
Feature description: {feature description only, no project context}
Provide an ideal design proposal for implementing this feature.
"""
)
Expected: ideal design (based on best practices), patterns/anti-patterns, considerations.
Forward the following relay prompt to both agents:
From now on, I will relay another LLM's response.
That LLM was also instructed on the same feature definition.
Other agent's design:
{other_agent_response}
Review from your perspective and provide:
1. Points you agree with
2. Concerns
3. Alternative suggestions (if any)
4. Can we reach consensus: [Agree / Need further discussion]
Round 1: Domain Architect design -> Best Practice Advisor reviews. Round 2: Best Practice review -> Domain Architect revises/rebuts.
After 2 rounds, must provide interim report:
| Item | Domain Architect | Best Practice Advisor |
|---|---|---|
| Core argument | (1-2 sentence) | (1-2 sentence) |
| Agreed points | (list) | (list) |
| Disputed points | (list) | (list) |
Options (AskQuestion, dynamically generated based on debate results):
| Field | Description |
|---|---|
| title | Reflect debate topic (e.g., "Alert Scheduling Design Debate") |
| prompt | Include report table summary above |
| options | 4 basic options below, adjust based on situation |
domain: Adopt Domain Architect - Prioritize project realitybest: Adopt Best Practice - Prioritize ideal designcontinue: 2 more rounds of debatecustom: User combines on disputed pointsOption adjustment: If both agree -> exclude continue. If one clearly superior -> mark as default.
NOTE: Run in Normal mode, not Plan mode. Can both intervene mid-process with AskQuestion + write final file.
Options 1,2,4 -> Phase 6. Option 3 -> Rounds 3-4, auto-terminate after 4. If no consensus: adopt Domain Architect + note Best Practice recommendations.
Validate completeness based on arch_type before writing.
Backend (BE):
| Item | Validation Criteria | If Incomplete |
|---|---|---|
| DB Schema | All tables have full column definitions | Enter question loop |
| Code Mapping | All features mapped to file/class/method | Enter question loop |
| API Spec | All endpoints have Request/Response defined | Enter question loop |
| Error Policy | Main error scenarios and responses defined | Enter question loop |
Frontend (FE):
| Item | Validation Criteria | If Incomplete |
|---|---|---|
| Component Structure | Page and reusable component hierarchy | Enter question loop |
| Code Mapping | All features mapped to file/component/hook | Enter question loop |
| State Management | Global/Server/Local state defined | Enter question loop |
| Route Definition | Routes and auth guards defined | Enter question loop |
| API Integration | Backend endpoints connected to hooks | Enter question loop |
{"title":"Design Information Supplement Required","questions":[{"id":"missing_info","prompt":"Missing:\n- {list}\n\nHow to proceed?","options":[{"id":"provide","label":"Provide - I will provide the information"},{"id":"infer","label":"Allow inference - AI can estimate"},{"id":"skip","label":"Skip - I will supplement later"}]}]}
provide -> user input | infer -> AI estimates, note in Assumptions | skip -> mark "[TBD]"Backend:
| Condition | Minimum Requirement |
|---|---|
| If API exists | Request/Response spec + at least 2 error responses |
| If Auth exists | Role/Permission table with at least 1 entry |
| If Data (DB) exists | Core entity with at least 5 fields defined |
Frontend:
| Condition | Minimum Requirement |
|---|---|
| If Pages exist | At least 1 page component with route defined |
| If Auth exists | Auth guard and protected route defined |
| If API calls exist | At least 1 hook/service with endpoint connection |
| If State exists | At least 1 global state store defined |
WARNING: If any fails -> re-enter Phase 5.5. When all pass -> Phase 6.
Write implementation-ready design document based on debate results.
| Section | Content | Source |
|---|---|---|
| 0. Summary | Goal/Non-goals/Metrics | Requirements |
| 1. Scope | In/Out | Debate |
| 1.5. Tech Stack | Language, framework, DB, etc. | Exploration/user |
| 2. Architecture Impact | Components, Data | Domain Architect |
| 3. Code Mapping | Feature -> file/module | Domain Architect + exploration |
| 4. Implementation Plan | Order + reference files | Agreed priority |
| 5. Sequence Diagram | Main flow | Main agent |
| 6. API Specification | Endpoints, Req/Res | Main agent |
| 7. Infra/Ops | Env vars, deployment | Domain Architect |
| 8. Risks & Tradeoffs | Debate conclusion | Both agents |
| 9. Checklist | Error/Auth/Data | Error, auth, data integrity |
| Item | Examples |
|---|---|
| Project Structure | Monorepo / Monolith / Custom |
| BE Path | apps/auth-api / backend / ./ |
| FE Path | apps/auth-web / frontend / ./ |
| Run Command (BE) | uv run uvicorn main:app / npm run dev |
| Run Command (FE) | npm run dev / yarn dev |
| Language | Python 3.11 / TypeScript 5.x / Go 1.21 / Java 17 |
| Framework | FastAPI / NestJS / Spring Boot / Gin |
| DB | PostgreSQL 15 / MySQL 8 / MongoDB 6 |
| ORM | SQLAlchemy / Prisma / TypeORM / GORM / None (Raw SQL) |
| Package Manager | uv / pip / poetry / npm / yarn / pnpm |
| 3rd-party | Redis, Kafka, S3, Elasticsearch, etc. |
| Infra | K8s / Docker / AWS / GCP / On-premise |
NOTE: BE/FE Paths and Run Commands used by build, test, debug skills.
All tables must have full column definitions.
Anti-patterns (Prohibited):
Example:
| Column | Type | Change | Description |
|---|---|---|---|
| id | INTEGER | Maintain | PK |
| event_type | VARCHAR(100) | Maintain | Event type |
| reference_id | VARCHAR(100) | New | Related resource ID |
| Delete | Moved to separate table |
When manual SQL migration: record change types (CREATE TABLE / ALTER TABLE / CREATE INDEX) for build phase.
Require: full file path, class, method, call location, code to add.
Anti-patterns (Prohibited):
Example:
| # | Feature | File | Class | Method | Action | Impl |
|---|---|---|---|---|---|---|
| 1 | Quality Create | .../quality_issue/service.py | QualityIssueService | create_issue() | After DB save call _publish_create_alert() | [ ] |
| 2 | Quality Resolve | .../quality_issue/service.py | QualityIssueService | resolve_issue() | After status change call _publish_resolve_alert() | [ ] |
[ ]= not implemented,[x]= done by build.#= row number, never reused.
## 8. Risks & Tradeoffs (Debate Conclusion)
### Chosen Option
- (adopted design approach)
### Rejected Alternatives
- (unadopted items and reasons)
### Reasoning
- Project constraints: ...
- Best practice adoption: ...
- Future improvement points: ...
### Assumptions
- **Confirmed**: (clearly decided in debate)
- **Estimated**: (assumed due to lack of confirmation)
docs/{serviceName}/arch-be.md or docs/{serviceName}/arch-fe.md
templates/be.md | Frontend: templates/fe.mdskills/arch/templates/. Read selected template before writing.# Backend Design Doc: {Feature Name}
> Created: {date} | Service: {serviceName} | Spec: docs/{serviceName}/spec.md
## 0. Summary
**Goal**: (1-2 sentences)
**Non-goals**: (excluded)
**Success metrics**: (criteria)
## 1. Scope
**In scope**: (items)
**Out of scope**: (future improvements)
## 1.5. Tech Stack
\`\`\`yaml
tech_stack:
language: "{lang}"
framework: "{fw}"
database: "{db}"
orm: "{orm}"
third_party: ["{svc1}", "{svc2}"]
infra: "{infra}"
\`\`\`
## 2. Architecture Impact
| Service/Module | Responsibility | Change type |
|----------------|----------------|-------------|
| {service} | {role} | new/modify |
### Database Schema
\`\`\`yaml
database_schema:
new_tables:
- name: "{table}"
columns:
- {name: "id", type: "INTEGER", constraints: ["PK","AUTO_INCREMENT"]}
- {name: "{col}", type: "{type}", constraints: ["{c1}"], desc: "{desc}"}
- {name: "created_at", type: "TIMESTAMP", constraints: ["NOT NULL","DEFAULT NOW()"]}
modified_tables:
- name: "{table}"
changes:
- {column: "{col}", type: "{type}", action: "ADD|DROP|MODIFY", desc: "{desc}"}
indexes:
- {table: "{tbl}", columns: ["{c1}","{c2}"], type: "BTREE", unique: false}
migrations:
- {type: "CREATE_TABLE", table: "{tbl}", desc: "{desc}"}
- {type: "ALTER_TABLE", table: "{tbl}", desc: "{change}"}
- {type: "CREATE_INDEX", table: "{tbl}", desc: "{index desc}"}
\`\`\`
## 3. Code Mapping
| # | Feature | File | Class | Method | Action | Impl |
|---|---------|------|-------|--------|--------|------|
| 1 | {feature} | {full path} | {class} | {method} | {action} | [ ] |
## 4. Implementation Plan
**Reference Files**: {path1} ({purpose}), {path2} ({purpose})
1. **{step}** - {tasks}
2. **{step}** - {tasks}
## 5. Sequence Diagram
\`\`\`mermaid
sequenceDiagram
participant Client
participant API
participant Service
participant DB
Client->>API: {request}
API->>Service: {call}
Service->>DB: {query}
DB-->>Service: {result}
Service-->>API: {return}
API-->>Client: {response}
\`\`\`
## 6. API Specification
\`\`\`yaml
api_endpoints:
- name: "{api}"
method: "{GET|POST|PUT|DELETE}"
path: "/api/v1/{path}"
auth_required: true
request:
headers: [{name: "Authorization", type: "string", required: true}]
params: [{name: "{param}", type: "{type}", required: true}]
body: {content_type: "application/json", schema: {field1: "{type}", field2: "{type}"}}
response:
success: {status: 200, schema: {success: "boolean", data: "{type}"}}
errors:
- {status: 400, code: "INVALID_INPUT", message: "{msg}"}
- {status: 404, code: "NOT_FOUND", message: "{msg}"}
\`\`\`
## 7. Infra/Ops
| Variable | Description | Default |
|----------|-------------|---------|
| {VAR} | {desc} | {val} |
## 8. Risks & Tradeoffs
**Chosen**: {approach} | **Rejected**: {alternatives and why}
**Reasoning**: constraints: {reason}, best practice: {applied}, future: {later}
**Assumptions**: Confirmed: {decided} | Estimated: {assumed, needs verification}
## 9. Error/Auth/Data Checklist
**Error Handling**
| Situation | Location | Handling | Response |
|---|---|---|---|
| {scenario} | {file/method} | {try-catch/propagation/logging} | {HTTP code, msg} |
**Auth Rules**
| Action | Permission | Location | On Failure |
|---|---|---|---|
| {api} | {role} | {middleware} | {403/401} |
**Data Validation**
| Validation | Timing | On Failure |
|---|---|---|
| {FK existence} | {before save} | {400 + msg} |
| {Duplicate} | {on create} | {409 Conflict} |
| {Range} | {on input} | {422 + details} |
WARNING: If empty, 80% of implementation will be unstable - Must complete
After saving: read spec.md, find ## 0. Requirement Summary table.
Update Status Draft -> Designed for each Req ID used in Code Mapping.
Example:
| Req ID | Category | Requirement | Priority | Status |
|--------|----------|-------------|----------|--------|
| FR-001 | Auth | Email/password login | High | Designed | <- Updated
| FR-002 | Auth | Social login | Medium | Designed | <- Updated
Design Document Complete Saved to:
docs/{serviceName}/arch-be.mdorarch-fe.mdUpdated: spec.md (Status -> Designed) Next: Run/build(recommend Sonnet in new session)
[spec] -> spec.md -> [arch] -> arch-be/fe.md -> [build] -> Implementation -> (Bug) -> [debug] -> trace.md
Activates when the user asks about AI prompts, needs prompt templates, wants to search for prompts, or mentions prompts.chat. Use for discovering, retrieving, and improving prompts.
Search, retrieve, and install Agent Skills from the prompts.chat registry using MCP tools. Use when the user asks to find skills, browse skill catalogs, install a skill for Claude, or extend Claude's capabilities with reusable AI agent components.
Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.