Inspect manifests, lockfiles, build/test configuration, CI definitions, and representative source files before applying a technology- or command-specific rule. Treat a tool, script, path alias, or runtime as observed only when repository evidence names it. Label conclusions from surrounding patterns as inferred. When a missing decision changes architecture, compatibility, security, or verification, stop and name the exact configuration or user decision required.
Basic Technology Stack Policy
These rules apply to a TypeScript application when repository configuration confirms that stack. Select architecture by mapping current requirements and accepted constraints to explicit module responsibilities, dependency direction, data flow, and verification boundaries.
Environment Variable Management and Security
Environment Variable Management
Centrally manage environment variables and build mechanisms to ensure type safety
Read environment variables through one typed configuration boundary; application code consumes validated configuration values
Give a variable a default only when requirements define valid behavior for absence; otherwise fail configuration validation with the variable name and expected format
Security
Keep local .env files outside version control and provide non-secret example files for required variable names
Load API keys and secrets from the configured secret store or runtime environment boundary
Log and return only fields approved for the current trust boundary; redact credentials, tokens, personal data, and internal diagnostics from untrusted responses
Architecture Design
Architecture Design Principles
Select architecture using these observable decisions:
Responsibilities: Each module/layer names the behavior it owns and the behavior it delegates
Dependency direction: Imports and runtime calls follow the project boundary rules observed in configuration or representative implementations
State/data ownership: Each persisted or mutable value has one authoritative owner
Verification boundary: Each public contract has a unit, integration, or E2E check that can observe it
Unified Data Flow Principles
Basic Principles
Single Data Source: Store the same information in only one place
Structured Data Priority: Use parsed objects rather than JSON strings
Responsibility Separation: Each layer names the data or behavior it owns and the boundary through which other layers use it
Data Flow Best Practices
Validation at Input: Validate data at input layer and pass internally in type-safe form
Centralized Transformation: Consolidate data transformation logic in dedicated utilities
Structured Logging: Output structured logs at each stage of data flow
Build and Testing
Select the package manager from the packageManager field, lockfile, or established CI command in that order. Execute only scripts present in the selected manifest.
Build Commands
build - TypeScript build
type-check - Type check (no emit)
Testing Commands
test - Run tests
test:coverage - Run tests with coverage
test:coverage:fresh - Run tests with coverage (fresh cache)
test:safe - Safe test execution (with auto cleanup)
cleanup:processes - Cleanup Vitest processes
Quality Assurance Mechanism Awareness
Before executing quality checks, identify what quality mechanisms exist for the change area:
Primary detection: inspect the change area's file types, project manifest, and configuration to identify applicable quality tools
Check CI pipeline definitions for checks that cover the affected paths
Check for domain-specific linter or validator configurations (e.g., schema validators, API spec validators, configuration file linters)
Check for domain-specific constraints in project configuration (naming rules, length limits, format requirements)
Supplementary hint: IF task file specifies Quality Assurance Mechanisms → use them as additional hints for which domain-specific checks to look for
Include discovered domain-specific checks alongside standard quality phases below
Quality Check Requirements
Quality checks are mandatory upon implementation completion:
Phase 1-3: Code Quality Checks
Auto-detect and execute the following from package.json scripts:
lint + format check
Detect unused exports
Detect circular dependencies
TypeScript build
Transition evidence: every applicable static/domain check exits successfully. A missing required script is reported with the manifest/configuration path and blocks the next phase until an equivalent established command is identified.
Phase 4: Tests
test - Test execution
Transition evidence: all applicable configured test suites pass, or an environment-dependent suite is recorded as blocked with its exact prerequisite.
Phase 5: Code Quality Re-verification
check:code - Re-verify code quality (clean up side effects from test fixes in Phase 4)
Completion evidence: static/domain checks still pass after test-related fixes, the build succeeds, and every required test has passed or is explicitly blocked.
Port in use error: Run the cleanup:processes script
Cache issues: Run the test:coverage:fresh script
Dependency errors: First record the failing resolver output, selected package manager, manifest, and lockfile state. Use the repository's established clean-install command only when it preserves the lockfile and generated artifacts; request approval before an operation that removes or regenerates dependency state
Coverage
Treat coverage as a diagnostic signal for finding untested areas, not a target (a target gets gamed into trivial tests — Goodhart's Law). Concentrate tests on critical paths and business logic whose regression would matter
Any enforced numeric threshold is the project's CI/coverage config, not a goal in itself