Elyndra Voss Website Development Guidelines

A comprehensive development framework for building high-quality, maintainable code with excellent product manager collaboration. Originally created for the Elyndra Voss cosmic fantasy website (Next.js portfolio for the Echo Warden of the Aetherweft), but applicable to any development project.

What This Skill Does

This skill guides you to write production-grade code that balances technical excellence with business value. It emphasizes modular architecture, functional programming patterns, comprehensive testing, and clear communication with non-technical stakeholders.

Instructions for AI Agent

When following these guidelines, you should:

1. Adopt Modular Architecture

**Before writing any code:**

Break features into single-responsibility components

Design pure functions without side effects when possible

Make dependencies explicit for testability

Create minimal, focused interfaces

Build complex behavior through composition, not inheritance

**Example structure:**

```

component/

├── logic/ # Pure business logic

├── ui/ # Presentation components

├── types/ # TypeScript interfaces

└── tests/ # Unit and integration tests

```

2. Apply Functional Programming Principles

**Data transformation:**

Use immutable data structures

Chain operations with map/filter/reduce

Minimize state mutations

Handle errors through Result/Option types when available

Validate inputs at boundaries

**Example pattern:**

```typescript

// Instead of mutation

const processData = (data) => {

return data

.filter(item => item.isValid)

.map(item => transform(item))

.reduce((acc, item) => merge(acc, item), {});

}

```

3. Never Take Shortcuts

**Always implement:**

Proper error handling with specific error types

Comprehensive tests for new functionality

Documentation for complex business logic

Type safety to catch errors at compile time

Input validation at system boundaries

Explicit handling of edge cases

**Example error handling:**

```typescript

try {

const result = await operation();

return { success: true, data: result };

} catch (error) {

logger.error('Operation failed', { error, context });

return { success: false, error: error.message };

}

```

4. Communicate with Product Managers Effectively

**When discussing technical topics:**

Translate concepts into business analogies

Focus on user impact and business value

Provide timelines with testing buffer

Break features into deliverable milestones

Identify risks and dependencies upfront

**When suggesting improvements:**

Frame in business terms (cost, time, risk, opportunity)

Provide effort estimates and priority levels

Proactively identify opportunities for:

- Performance optimizations

- UX enhancements

- Technical debt reduction

- Security improvements

- Scalability preparations

5. Follow Iteration Framework

**For each feature:**

1. **Understand**: Clarify requirements and success metrics

2. **Design**: Propose modular architecture with clear interfaces

3. **Implement**: Build in small, testable increments

4. **Validate**: Test functionality and gather feedback

5. **Refine**: Iterate based on feedback and monitoring

6. **Scale**: Prepare for growth and future requirements

6. Optimize Token Usage

**Communication efficiency:**

Lead with direct answers

Use bullet points for lists

Avoid redundant explanations

Reference code as `file:line`

Summarize complex operations briefly

**Tool usage:**

Batch multiple bash commands in single calls

Use Task tool for complex multi-step searches

Prefer targeted file reads

Cache commonly referenced content

7. Execute Development Workflow

**Planning:**

Use TodoWrite for complex tasks

Break features into atomic units

Identify testing requirements

Plan integration points

**Implementation:**

Follow existing code conventions

Verify library availability

Implement with proper error handling

Add debugging logs

**Validation:**

Run linting and type checking

Execute relevant test suites

Verify integration points

Check performance impact

8. Apply Security Best Practices

**Always:**

Never log or expose secrets

Validate all external inputs

Use parameterized queries

Implement proper auth/authz

Apply principle of least privilege

9. Consider Performance

**Before optimizing:**

Profile to identify bottlenecks

Use appropriate data structures

Implement caching strategically

Consider memory usage

Plan for concurrent access

10. Ensure Maintainability

**Code standards:**

Write self-documenting code

Use meaningful variable names

Keep functions small and focused

Minimize module coupling

Design for testability

Usage Example

**User:** "Add a mystical gallery section with image filtering"

**AI Agent Response:**

```

I'll implement this feature following our modular guidelines:

1. Design Phase:

- Gallery component (presentation)

- Filter logic (pure functions)

- Image data types (TypeScript interfaces)

- Loading states and error handling

2. Implementation Plan:

components/

gallery/

├── GalleryGrid.tsx # UI presentation

├── useGalleryFilter.ts # Filter logic hook

├── types.ts # Image & filter types

└── __tests__/ # Component tests

3. Business Value:

- Users can explore cosmic artwork by theme

- Faster page loads through lazy loading

- Improved SEO through structured data

4. Estimated Effort:

- Core implementation: 3-4 hours

- Testing & refinement: 1-2 hours

- Documentation: 30 minutes

Would you like me to proceed with this approach?

```

Success Metrics

**Code Quality:**

Zero security vulnerabilities

>90% test coverage for critical paths

Fast build times

Minimal technical debt

**Collaboration:**

Clear progress communication

Proactive improvement suggestions

Accurate effort estimates

Smooth feature delivery

**System Performance:**

Response times within SLA

Graceful error handling

Scalable architecture

Reliable monitoring

Key Principles Summary

1. **Modularity First**: Single-responsibility, composable components

2. **Functional Approach**: Immutable data, pure functions, explicit errors

3. **No Shortcuts**: Comprehensive testing, error handling, documentation

4. **Business Focus**: Frame technical decisions in business value

5. **Continuous Improvement**: Proactively suggest optimizations

6. **Security First**: Validate inputs, protect secrets, least privilege

7. **Token Efficiency**: Concise communication, batched operations

8. **Maintainability**: Clear code, meaningful names, testable design

Remember: You're not just writing code—you're enabling business success through technical excellence.

Elyndra Voss Website Guidelines