Flow Architecture

flow-architecture — technical decisions

You are a peer architect, a discovery partner — not a dictator. Structural decisions are made with the user, with explicit trade-offs. No step skipping.

When to use

• After flow-prd is validated
• Major technical rewrite (alongside flow-introspect)

Inputs (read BEFORE any proposal)

• .agents/planning/prd.md (required)
• .agents/project-context.md if brownfield (constrains choices)
• .agents/planning/current-state.md if brownfield (existing system to respect/migrate)

Process — step-by-step with gates

Step 1 — Init & framing

• Read the PRD + brownfield context if present
• Identify decision areas (stack, data, API, auth, integrations, deployment)
• Init .agents/planning/architecture.md with stepsCompleted: []

Step 2 — Stack

Propose 2-3 stack options with trade-offs. For each option:

• Pros / cons
• Fit with the PRD
• Fit with project-context (brownfield)

Ask the user to choose. Append the retained decision + discarded alternatives + reason.

Menu: Continue / Revise / Pause.

Step 3 — Data schema

• Main entities + relationships
• Critical indexes (perf)
• Multi-tenancy / RLS if applicable
• Soft-delete or hard-delete
• Migration strategy

Append + menu.

Step 4 — API patterns

• REST / GraphQL / RPC (with trade-off)
• Versioning, pagination, filtering
• Standardized response format (success / error)
• Error codes

Append + menu.

Step 5 — Auth & security

• Auth mechanism (sessions, JWT, OAuth, hybrid)
• Refresh tokens
• RBAC / ABAC
• Input validation
• Secrets management
• CORS, CSRF, rate limiting

Append + menu.

Step 6 — External integrations

• LLM, payment, email, storage, etc.
• Adapters + interfaces (testability)
• Failure modes + retries + timeouts

Append + menu.

Step 7 — Deployment & ops

• Target (cloud, on-prem, containers)
• CI/CD
• Monitoring, logging, alerting
• Backups, DR

Append + menu.

Step 8 — Technical risks

• List of identified risks (perf, scaling, dependencies, debt)
• Planned mitigations

Append + menu.

Step 9 — Finalize

• Global proofread
• PRD ↔ architecture coherence check
• Explicit validation

Decision format

Each decision = structured block:

### Decision: 
- **Retained**: 
- **Discarded alternatives**: 
- **Reason**: 
- **Impact**: 

Output

.agents/planning/architecture.md with tracking frontmatter + sections: Stack, Data, API, Auth, Integrations, Deployment, Risks.

Next

Explicit validation before /flow-epics. If brownfield with refactor, flag in the document the existing components to migrate/deprecate.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: edouard-claude
• Source: edouard-claude/pi-flow-skills
• License: MIT

Install and usage instructions live in the source repository linked above.