Menu
Designs software architecture from a confirmed PRD. Use when a PRD exists and architecture must be designed before implementation, when writing ADRs, choosing an architecture style, or selecting technology and databases.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Delegates a task to OpenAI Codex running as an interactive session in a herdr pane - uses the user's ChatGPT subscription, visible in herdr, steerable mid-session. Use when delegating work to codex, offloading a task to a GPT model (sol, terra, luna), or running a second opinion from a non-Claude frontier model. Not for Claude Code's own Agent tool or local-LLM delegation (delegating-to-local-llm).
Delegates a task to a local LLM running as a Pi coding-agent session in a herdr pane - the subagent is visible in herdr, can be steered mid-session, and costs no cloud tokens. Use when delegating work to a local model, spawning a Pi subagent, offloading a task to omlx (qwen, gemma), or running agent work offline. Not for Claude Code's own Agent tool or subagents inside Pi.
Loads the rageatc-code-oss operating rules directly from the plugin when the SessionStart hook has not delivered them. Use when the rageatc-code-oss failsafe line appears in session-start hook output, when the plugin's operating rules are absent from context, or when the injected rules look truncated.
Loads the rageatc-core-oss operating rules directly from the plugin when the SessionStart hook has not delivered them. Use when the rageatc-core-oss failsafe line appears in session-start hook output, when the plugin's operating rules are absent from context, or when the injected rules look truncated.
Raises an artefact's signal-to-noise ratio by removing text that earns nothing for its reader — filler, repetition, over-explanation, ornamental phrasing — and relocating conditional detail to references. Use to slim a skill, agent, or document, cut bloat, tighten prose, or shrink a file that has grown too long. Tuned for SKILL.md files.
Creates a design system for software with a UI. Use when a project has a user interface and architecture is confirmed — whether creating from scratch or extracting patterns from existing code.
| name | architecting-software |
| description | Designs software architecture from a confirmed PRD. Use when a PRD exists and architecture must be designed before implementation, when writing ADRs, choosing an architecture style, or selecting technology and databases. |
Translates a confirmed PRD ("what to build") into system structure ("how to build it") — systematically, driver-first, without the documented failure modes of AI-generated architecture.
Position: managing-product (PRD.md) → architecting-software (ARCHITECTURE.md + ADRs) → decomposing-work (ROADMAP.md).
Inputs: a confirmed PRD.md; team size and composition (if absent and not inferable, flag for human input before Step 3 — it is an architectural driver); technology constraints from the PRD; existing systems to integrate with, or "greenfield".
Outputs: ARCHITECTURE.md in the project root (codemap-centric structure per references/architecture-template.md); when complexity warrants, one ADR per significant decision in docs/decisions/NNNN-title.md (MADR minimal format per references/adr-template.md).
Not covered: requirements gathering (managing-product), task decomposition (downstream), code generation, CI/CD design, detailed API specification.
Same process at every tier; only output depth differs. Calibrate to the project — do not produce a 200-line architecture document for a 3-file bug fix. When in doubt, start light and add detail only where it prevents downstream ambiguity.
| Tier | ARCHITECTURE.md depth | ADRs |
|---|---|---|
| Quick | 10-20 lines. Overview + key decisions only. Skip codemap if the project is navigable directly. | None |
| Standard | Codemap + key decisions. Component boundaries and primary patterns. | Only for genuinely significant decisions |
| Thorough | Full template — overview, codemap, cross-cutting concerns, invariants, key decisions, dependencies, open questions | One per significant decision |
Sort every PRD requirement — select no patterns yet:
Log ambiguous requirements as open questions for human resolution before proceeding.
Find the 3–7 requirements that force structural decisions: anything that affects many components, creates irreconcilable conflict with another requirement, cannot be met with standard patterns without deliberate choice, or carries significant business risk if unmet.
Scale calibration first:
| Signal | Simple | Moderate | Complex |
|---|---|---|---|
| User types | 1 | 2 | 3+ |
| External integrations | 0–1 | 2–3 | 4+ |
| Explicit quality attribute requirements | None | 1–2 | 3+ |
| Team size | 1–5 | 6–20 | 20+ |
| Compliance requirements | None | Light | Regulated |
Simple → focused ARCHITECTURE.md, ADRs only for genuinely non-obvious decisions. Moderate → ADRs for meaningful trade-offs. Complex → full documentation, ADR per significant decision.
Rank drivers by business impact if unmet and difficulty of satisfying given other constraints; primary drivers are high on both. Document the ranked list with brief justification before Step 3.
Select a pattern for each of five dimensions, in sequence — each decision constrains the next. Every selection must trace to a named driver; if no driver justifies the more complex option, the simpler default wins.
| Signal | Serverless | Containers/VMs |
|---|---|---|
| Traffic pattern | Variable, spiky | Predictable, sustained |
| Request duration | Short (under 15 min) | Any, including long-running |
| Cold start tolerance | Acceptable | Low latency required always |
| Ops maturity | Low — managed infra preferred | Medium–high |
| Cost model preference | Pay-per-request (cheap at low scale) | Provisioned compute (cheap at high scale) |
| Vendor lock-in tolerance | High | Low |
Default: containers for sustained workloads; serverless for event-driven background jobs. Most production systems blend both.
| Signal | Monolith | Modular Monolith | Microservices |
|---|---|---|---|
| Team size | 1–5 | 5–50 | 50+ |
| Domain clarity | Unknown or emerging | Moderately understood | Well-understood, stable bounded contexts |
| Scaling requirements | Uniform, modest | Mostly uniform | Highly variable per domain |
| Operational maturity | Low | Medium | High — mature CI/CD, observability |
| Data isolation requirement | Low | Medium | High — compliance or ownership |
Default: modular monolith. Move to microservices only on organisational signals: deployment coordination is a bottleneck, teams step on each other's code, or domains have dramatically differing scaling needs. Microservices are an organisational scaling pattern first — never speculative.
Conway's Law check: state what team structure this architecture requires; if it conflicts with known team constraints, revise the structure.
Structure inside a service or monolith — independent of deployment topology.
| Signal | Layered | Hexagonal | Clean |
|---|---|---|---|
| Project complexity | Simple–medium | Medium–complex | Complex |
| Team experience | Beginner–intermediate | Intermediate–advanced | Advanced |
| Expected lifespan | Short (MVP, prototype) | Medium–long | Long |
| Testing requirements | Light | High testability required | Maximum testability |
| External dependencies | Few, stable | Many or likely to change | Many, business logic must be isolated |
| Business logic complexity | Simple CRUD | Moderate domain logic | Rich domain model |
Default: layered for MVPs and simple projects; hexagonal when external dependencies are many or changeable and testability matters. Clean is hexagonal with more explicit layer naming — treat as interchangeable unless the extra structure is needed. Caution: layered degrades into a big ball of mud as complexity grows because layers are not enforced — for significant lifespan or domain complexity, choose hexagonal.
Dependency direction rule: state which way dependencies flow and encode it as an invariant. Hexagonal/clean: infrastructure depends on core, never the reverse. Layered: presentation → application → domain → infrastructure.
| Need | Request-Response | Event-Driven |
|---|---|---|
| User needs immediate result | Yes | No |
| Strong consistency required | Yes | No (needs saga/outbox pattern) |
| Background or async workflows | No | Yes |
| High fan-out (one event, many consumers) | No | Yes |
| Simple CRUD | Yes | Overkill |
Default: request-response. Add event-driven only for specific async workflows — it adds observability and debugging complexity.
| Signal | Relational (SQL) | Document (NoSQL) |
|---|---|---|
| Schema | Well-defined, stable | Variable, evolving |
| Relationships | Complex — many joins | Few — denormalised |
| Consistency requirement | Strong (ACID) | Eventual acceptable |
| Query patterns | Complex, ad-hoc | Known access patterns, high write throughput |
| Domain examples | Finance, inventory, user accounts | Content, catalogues, real-time apps |
Default: PostgreSQL. It handles most applications at significant scale, supports JSON columns, and its ACID guarantees prevent whole categories of bugs. Add specialised stores only against a specific, measurable problem: Redis for caching/sessions, Elasticsearch for full-text search, time-series DB for high-volume telemetry.
| Signal | SPA | SSR | SSG | MPA |
|---|---|---|---|---|
| SEO required | No | Yes | Yes | Yes |
| Interactivity | High | Medium–high | Low | Low |
| Content update frequency | Any | Real-time or per-user | Infrequent (rebuild on change) | Any |
| Infrastructure complexity | Low — static hosting | Medium — Node server | Low — static hosting | Medium |
| Domain examples | Admin dashboards, internal tools | E-commerce, SaaS, social | Blogs, docs, marketing | Enterprise portals |
Default: SSG for mostly-static content; SSR for SEO + interactivity + personalisation; SPA for internal tools and authenticated apps with no SEO requirement.
Patterns first, technology second. For Simple projects, apply the simplicity defaults directly — a formal matrix is only warranted when multiple viable options carry meaningful trade-offs. For any non-obvious choice, use a weighted decision matrix:
Anti-patterns: cargo culting (Netflix's choices assume Netflix's scale and team); recency bias (new tech, immature ecosystem); CV-driven selection; premature optimisation (start with PostgreSQL, add Redis when a cache-miss problem exists; start with a container, add Kubernetes when coordination complexity requires it).
Build vs buy: for commodity capabilities (authentication, payments, email delivery, search), prefer a managed service or open-source solution. Build only when the capability is a direct competitive differentiator or no adequate solution exists.
Walk the checklist AI-generated architectures consistently miss and state how the architecture handles each. If a PRD requirement or driver maps to an item, the architecture must address it; if an item has no driver, record a one-line statement of why it is out of scope or deferred.
ARCHITECTURE.md — use references/architecture-template.md. The codemap is the most important section; start there. Write at the level of structure and intent, not implementation detail; 500–1,500 words for most projects. Optionally add a C4 Container diagram (Mermaid/PlantUML) for systems with 3+ major components. Principles:
src/middleware/auth.ts", not "authentication is handled centrally"ADRs — one per significant decision, docs/decisions/NNNN-brief-title.md (e.g., 0001-use-modular-monolith.md), MADR minimal template. Significant = affects structural boundaries or data ownership, hard-to-reverse technology choice, trade-offs someone will question in six months, or directly addresses a primary driver. If nothing meets the bar, skip ADRs — a clear note in ARCHITECTURE.md suffices.
Fix every failing item before presenting — never present architecture with known gaps or unjustified complexity.
Output: validated ARCHITECTURE.md, ADRs, and a brief handoff statement of what was decided and what remains open.
No explicit quality attributes in the PRD: default drivers are maintainability for the team size and delivery speed. Apply simplicity defaults across all dimensions. Do not invent quality attributes that are not stated or clearly implied.
Technology specified before architecture: record it as a constraint; still run Steps 1–3 for structure. If the mandated technology conflicts with a driver, surface the conflict and flag for human decision.
Brownfield: map the existing patterns first; Step 3 is constrained by them. Determine whether the extension fits existing patterns or warrants a new bounded context. Do not redesign the existing system unless the PRD requires it.
Single-developer project: apply simplicity defaults forcefully — monolith, layered, PostgreSQL, static hosting. Complex-pattern overhead is itself an architectural problem for one person; document simplicity as the driver.
Irreconcilable driver conflicts (maximum performance + minimum cost, strong consistency + horizontal scale): present both options with trade-offs, state which driver takes precedence, and flag for human decision. Never silently choose and obscure the trade-off.
references/architecture-template.md — codemap-centric architecture document templatereferences/adr-template.md — MADR minimal ADR template