skills.rest
stacksjs
stacksjsOFFICIAL
Explore all skills by this author →
Website𝕏@stacksjsGitHub

stacks-codebase-design

Guides design of deep modules with small interfaces in Stacks TypeScript projects.

625|19|Updated Apr 26, 2022
Search Tags:#typeScript#Ports and Adapters#deep modules#SEAMS#code design#Stacks#Software Architecture
One-click install
npx skills add https://github.com/stacksjs/stacks --skill stacks-codebase-design
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: stacks-codebase-design
Source: https://github.com/stacksjs/stacks/tree/main/storage/framework/defaults/ai/skills/stacks-codebase-design
Command: npx skills add https://github.com/stacksjs/stacks --skill stacks-codebase-design

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

When designing or restructuring code in a Stacks project, it is easy to end up with shallow modules whose interfaces are as complex as their implementations, scattered seams, and untestable code. This Skill provides a shared vocabulary (module, interface, depth, seam, adapter, leverage, locality) and concrete principles for designing deep modules that are testable through their interface.

Core Features & Use Cases

  • Deep-module design vocabulary: Standardized terms for module, interface, seam, adapter, depth, leverage, and locality so teams name architectural concepts consistently across Stacks packages.
  • Dependency-aware deepening guidance: Classifies dependencies (in-process, local-substitutable, remote-owned, true external) and prescribes the right seam and adapter strategy for each, including when to use ports and adapters versus mocks.
  • Design-it-twice workflow: Spawns parallel sub-agents to produce radically different interface designs for a candidate module, then compares them on depth, locality, and seam placement.
  • Use Case: When writing the fifth near-identical action in a Stacks app, use this Skill to decide whether a model trait should be born, where the seam belongs, and how to test through the new interface.

Quick Start

Ask the AI to review a Stacks action or package interface and recommend how to deepen it using the module, seam, and adapter vocabulary.

Frequently Asked Questions about stacks-codebase-design

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I design a deep module in a Stacks project?▼

Design a small interface that hides substantial implementation behind it, then place it at a clean seam. In Stacks, model traits like useApi are the canonical example: one config object yields actions, routes, an OpenAPI entry, and a dashboard view.

What is the difference between a seam and an adapter?▼

A seam is the location where a module's interface lives and behavior can be altered without editing that place. An adapter is a concrete thing that satisfies the interface at that seam, such as the memory or redis driver selected in config/cache.ts.

When should I introduce a port and adapter pattern?▼

Introduce a port only when at least two adapters are justified, typically production plus test. A single-adapter seam is just indirection, and you should not add one where the framework already provides a seam like the app/ override model.

How do I test a deepened module with external dependencies?▼

Inject the external dependency as a port and provide a mock adapter in tests, as the Stacks driver packages do for Stripe, SES, and AI providers. For the database, use refreshDatabase() with model factories instead of injecting anything.

When should I choose a trait over a helper in Stacks?▼

Choose a trait when a capability varies per model, and a driver in config/*.ts when it varies per environment. If you find yourself writing the fifth near-identical action, that repetition signals a trait wants to be born.

Related Skills

Explore More Software Engineering Skills→
The-Vibe-CompanyThe-Vibe-Company
2.4k

codebase-design

Designs deep modules with small interfaces placed at clean seams.

Official
Intermediate
The-Vibe-CompanyThe-Vibe-Company
2.4k

tdd

Guides test-driven development through red-green cycles with seam-based test design.

Official
Intermediate
mostafa-K-raihanmostafa-K-raihan

improve-codebase-architecture

Identify shallow modules and surface deepening opportunities in a codebase.

Community
Advanced
jasonmichaelbell78-creatorjasonmichaelbell78-creator

code-reviewer

Identifies code quality issues and security concerns in JavaScript/TypeScript changes.

Community
Advanced