Architecture design

Skill ahtishamshahzad/agent_dev_flow/.ai/skills/architecture-design

Tool-neutral AI Engineering System: 174 reusable skills (installable as Claude Code plugins) for planning and building software with AI agents. Classify → plan → approve → build under quality gates. Works with Claude Code, Codex, Cursor, Windsurf, Copilot & Antigravity. Canonical in .ai/.

Install

npx -y skills add ahtishamshahzad/agent_dev_flow --skill architecture-design

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

20 days oldThe repository was created 20 days ago. New is not bad, but a brand new repository carrying a familiar-sounding name is the shape a typosquat arrives in, and there has been no time for anyone else to find a problem with it.
0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Use after the stack is approved to define module boundaries, data flow, integration points, and cross-cutting concerns (auth, config, error handling). Produces the architecture that phases and tasks are generated from. Proportional to the request.

SKILL.md

3.9 KB, as published. Nobody here has run it

Architecture Design

Purpose

Define the system's shape: modules and their boundaries, how data flows, where integrations sit, and how cross-cutting concerns are handled — consistent with the approved applications and stack. Satisfies Gate 3.

When to Use

After Gate 2 (applications + stack approved), before phase/task generation.
When a feature needs a design decision within an existing architecture.
Not for a trivial change fully covered by existing patterns.

Inputs

Approved applications and stack (../../projects/current/).
Requirement baseline and audit findings.

Discovery Questions

What are the core domains/bounded contexts?
Which integrations (auth, payments, third-party APIs) are required?
What are the consistency, availability, and scale expectations?
What cross-cutting concerns need a single approach (auth, config, logging, errors)?

Responsibilities

Define module/service boundaries and responsibilities.
Define data flow and ownership between modules/apps.
Identify integration points and their contracts.
Decide cross-cutting concerns: auth, configuration, error handling, logging.
Keep the design proportional to the request.
Feed repository-architecture for the on-disk layout.

Required Workflow

Read approved apps/stack + requirements.
Identify domains and boundaries.
Define data flow and contracts.
Decide cross-cutting approaches.
Record the architecture (Gate 3) in ../../projects/current/ / ../../knowledge/.
Hand off to repository-architecture and phase generation.

Decision Rules

Boundaries follow domains and change-rate, not convenience.
Prefer the simplest architecture that meets the requirements; add complexity only when justified.
Contracts between apps/modules are explicit before parallel work begins.
Security-relevant flows (auth, PII, payments) get first-class treatment (security-review).

Rules

Consistent with the approved stack — no new stack decisions here.
Record decisions and rejected alternatives (the "why").
No code; this is design.

Anti-Patterns

Over-engineering (microservices/event buses for a small app).
Under-defining contracts, then parallelizing into conflicts.
Architecture that contradicts the approved stack.

Validation Checklist

Module/service boundaries defined.
Data flow and ownership defined.
Integration points + contracts identified.
Cross-cutting concerns decided.
Proportional to the request.
Decisions + alternatives recorded (Gate 3).

Definition of Done

A recorded architecture consistent with the approved stack — boundaries, data flow, integrations, and cross-cutting concerns — sufficient to generate phases, tasks, and the repository layout.

Related Skills

stack-recommendation, repository-architecture, task-planning, security-review, testing-strategy, project-orchestrator.

Related Knowledge

../../knowledge/ (architecture decision records, domain model).

Related References

../../references/<architecture-topic>/ when a pattern needs grounding.

Context Loading Guidance

Requires: approved apps/stack, requirement baseline.
Does not require: full source, unrelated references, implementation skills.
May load: repository-architecture, security-review for sensitive flows.
Stop when: the architecture is recorded and passes Gate 3.

Token Efficiency Guidance

Work from summaries of apps/stack/requirements. Capture the design as concise decisions + a diagram-in-text; avoid restating stack rationale already recorded.