Codebase architecture

Skill dustinkeeton/wafflestack/stacks/code-quality/skills/codebase-architecture

🧇 One batter, every repo — reusable AI agent & skill definitions rendered into harness-native files (.claude/, .codex/, .agents/)

Install

npx -y skills add dustinkeeton/wafflestack --skill codebase-architecture

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

One thing to look at

1 stars1 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

Codebase architecture standards and best practices for {{project.longName}}. Covers file structure conventions, module patterns, naming conventions, dependency rules, and code organization. Use when enforcing or communicating architectural decisions.

SKILL.md

3.7 KB, as published. Nobody here has run it

Codebase Architecture Standards

Module Pattern

Every feature module follows a consistent contract: it takes the application handle plus a settings getter, exposes a load/registration entry point where it wires up its commands, views, and event listeners, and a teardown/cleanup path that releases everything it registered.

class FeatureModule {
  constructor(host: AppHost, getSettings: () => {{arch.settingsType}}) {}
  register(): void | Promise<void>;  // load/registration entry point — wire up commands, views, events
  teardown(): void;                  // cleanup path — release everything registered above
}

AppHost stands for whatever handle the application entry point owns (the app, plugin, or server instance) — modules receive it, they never construct it. The two lifecycle methods above are illustrative names; use whatever your framework or runtime convention dictates, but keep the two-phase contract: one place that registers, one place that tears down.

File Structure Conventions

src/
├── <entry>.ts                 # App entry point only — bootstrap/wiring, no business logic
├── settings.ts                # Unified settings interface + defaults
├── settings-ui.*              # Settings UI, if the app exposes settings to users
├── <feature>/                 # One directory per feature module
│   ├── index.ts               # Module class — the feature's public API
│   ├── types.ts               # Feature-specific interfaces and types
│   ├── <implementation>.ts    # Internal implementation files
│   └── <ui>/                  # UI components (views, modals, screens) if needed
└── shared/                    # Cross-feature building blocks
    ├── <service-client>.ts    # Shared client(s) for external services / APIs
    ├── <utils>.ts             # Cross-cutting helpers — retry, error handling
    └── <io>.ts                # File-system / storage / network operations

The names in angle brackets are placeholders — use whatever your project calls its entry file (main, index, app, server, …), its features, and its shared utilities. The shape is what matters: a thin entry file, a unified settings interface, one directory per feature (each with an index public API, a types file, and internal implementation), and a shared/ directory for cross-feature building blocks.

Rules

No circular dependencies — feature modules may depend on shared/ but never on each other, except {{arch.depExceptions}}
Minimal runtime deps — prefer the platform's HTTP client (fetch) for API calls and child_process for external tools over adding npm dependencies
Types in types.ts — each feature has its own types file; shared types go in shared/
Index files are public API — other modules import from feature/index.ts, never from internal files
Settings are read-only in modules — modules receive getSettings(), never mutate settings directly
All host registrations in the load path — commands, events, and views are registered through the host handle in the module's registration entry point, so teardown happens in one place
Naming: files use kebab-case, classes use PascalCase, functions/variables use camelCase
Exports: prefer named exports over default exports (except the entry-point class)