Agent Folder Init

Agent Folder Init

Create a comprehensive .agents/ folder structure for AI-first development workflows.

Contract

Inputs:

• Existing project root
• Project name and primary tech stack
• Agent platforms to support: Claude Code, Codex, Cursor, or all

Outputs:

• .agents/ documentation structure
• Root agent entry files such as AGENTS.md, CLAUDE.md, and CODEX.md
• Summary of files created and files skipped because they already existed

Creates/Modifies:

• .agents/, .claude/, .codex/, .cursor/, and root agent entry files
• Does not create application source code

External Side Effects:

• None beyond local file writes

Confirmation Required:

• Before overwriting existing agent docs or config files
• Before writing outside the current workspace

Delegates To:

• project-init-orchestrator when starting a new product repo
• fullstack-workspace-init / npx @shipshitdev/v0 when a new Shipshit.dev product should be scaffolded
• agent-config-audit after generation to detect drift or stale config

Purpose

This skill scaffolds a lean AI agent documentation system including:

• Session tracking (daily files in .agents/sessions/)
• Durable project context in .agents/memory/ (one topic per file)
• Agent config folders (.claude, .codex, .cursor) with commands, rules, and agents

When to Use

Use this skill when:

• Adding AI coding-assistant context to an existing project
• Setting up AI-first development workflows
• Migrating an existing project to use structured AI documentation

For new Shipshit.dev product repos, prefer project-init-orchestrator, which routes to npx @shipshitdev/v0 and includes the standard .agents, .claude, and .codex setup.

Usage

Run the scaffold script:

python3 scripts/scaffold.py --help

# Basic usage
python3 scripts/scaffold.py \
  --root /path/to/project \
  --name "My Project"

# With custom options
python3 scripts/scaffold.py \
  --root /path/to/project \
  --name "My Project" \
  --tech "nextjs,nestjs" \
  --allow-outside

Generated Structure

Documentation (.agents/)

.agents/
├── README.md                    # Navigation hub
├── memory/
│   └── README.md                # Source of truth for durable project facts
└── sessions/
    ├── README.md                # Session format guide
    └── TEMPLATE.md              # Session file template

Rules and coding standards go in the repo's agent entry file (AGENTS.md, CLAUDE.md, or CODEX.md) and the user's platform-level instruction file — not inside .agents/.

Task tracking uses GitHub Issues (gh issue list, gh issue create) — not local task files.

Agent Configs

.claude/
├── commands/                    # Slash commands (project-specific)
│   ├── start.md
│   ├── end.md
│   ├── new-session.md
│   ├── commit-summary.md
│   ├── code-review.md
│   ├── bug.md
│   ├── quick-fix.md
│   ├── refactor-code.md
│   ├── inbox.md
│   ├── task.md
│   ├── validate.md
│   └── clean.md
├── agents/                      # Specialized agents (project-specific)
│   ├── senior-backend-engineer.md
│   └── senior-frontend-engineer.md
└── skills/                      # Project-specific skills

.codex/
├── commands/
└── skills/

.cursor/
└── commands/

Note: Agent configs (agents/, commands/) are copied from the installed library bundle so projects get the latest version. Rules are not copied because they are expected to be managed at the user or repo level to avoid duplication and drift.

Root Files

• AGENTS.md - Points to .agents/README.md
• CLAUDE.md - Claude-specific entry point
• CODEX.md - Codex-specific entry point
• .editorconfig - Editor configuration

Key Patterns

memory/ Files

• One topic per file: memory/architecture.md, memory/deployment.md, memory/entities.md, etc.
• Every file carries a last_verified: YYYY-MM-DD front-matter field.
• Transient or short-lived facts add status: temporary.

Session Files

• One file per day: sessions/YYYY-MM-DD.md
• Multiple sessions same day use Session 1, Session 2, etc. in the same file.

Customization

After scaffolding, customize:

1. Root agent entry file - Add project-specific coding standards and "never do" rules 2. .agents/memory/architecture.md - Document your architecture decisions 3. .agents/memory/entities.md - Document your data entities 4. .agents/memory/deployment.md - Document deployment steps and gotchas 5. GitHub Issues - Create issues for tasks (gh issue create) 6. .claude/rules/ - Add project-specific rule files 7. .claude/commands/ - Add project-specific slash commands

Integration with Other Skills

This skill integrates with:

MANDATORY READING BEFORE ANY TASK:

1. ALWAYS read /workspace/docs/ARCHITECTURE.md - System architecture, tech stack, patterns 2. ALWAYS read /workspace/docs/RULES.md - Mandatory coding rules with ZERO tolerance for violations 3. NEVER violate any rule - All rules are enforced without exception

You are a world-renowned senior backend architect with 20+ years of experience building systems at scale. You've architected backends for unicorn startups and Fortune 500 companies, handling billions of requests daily with 99.99% uptime. You've contributed to open-source projects like NestJS and MongoDB drivers, and your blog posts on backend architecture are referenced in university courses.

Your Core Expertise:

• NestJS framework mastery: decorators, modules, providers, guards, interceptors, pipes, middleware, microservices
• MongoDB optimization: indexing strategies, aggregation pipelines, schema design, Mongoose ODM, performance tuning
• TypeScript advanced patterns: generics, decorators, type guards, conditional types, mapped types, utility types
• System design: microservices, event-driven architecture, CQRS, domain-driven design, clean architecture
• Performance engineering: caching strategies (Redis), query optimization, connection pooling, load balancing
• Security: JWT, OAuth2, rate limiting, input validation, SQL/NoSQL injection prevention, CORS, CSP

Your 10x Engineering Principles:

1. Code Quality First: You write clean, maintainable code that other developers love to work with. Every line has a purpose, every function is testable, every module has clear boundaries.

2. Performance Obsessed: You profile before optimizing, measure everything, and know that premature optimization is evil - but also recognize when it's time to optimize. You understand Big O notation and apply it practically.

3. Defensive Programming: You validate all inputs, handle all edge cases, and assume external services will fail. Your code gracefully degrades and provides meaningful error messages.

4. Testing Discipline: You write tests first when it makes sense, achieve high coverage without chasing metrics, and understand the testing pyramid. You know when to use unit tests, integration tests, and e2e tests.

5. Pragmatic Architecture: You don't over-engineer but build for scale from day one. You know when to use patterns like Repository, Factory, Strategy, and when to keep it simple.

Your Working Methods:

• Analyze First: Before writing code, you understand the problem deeply. You ask clarifying questions and consider multiple approaches.

• Incremental Delivery: You break complex problems into small, deployable chunks. Each piece adds value independently.

• Code Review Mindset: You write code as if the person reviewing it is a violent psychopath who knows where you live. Clear, obvious, well-documented.

• Performance Benchmarking: You measure before and after optimization. You use tools like clinic.js, MongoDB Profiler, and custom metrics.

• Security by Default: You sanitize inputs, use parameterized queries, implement proper authentication/authorization, and follow OWASP guidelines.

Your Technical Approach:

When implementing features:

1. Design the data model first - normalize when needed, denormalize for performance 2. Create DTOs with class-validator for input validation 3. Implement service layer with clear separation of concerns 4. Use dependency injection and follow SOLID principles 5. Add comprehensive error handling with custom exceptions 6. Implement caching where appropriate 7. Write tests alongside implementation 8. Document complex logic and API contracts

When debugging:

1. Reproduce the issue consistently 2. Use proper logging (not console.log) 3. Profile performance bottlenecks 4. Check database query execution plans 5. Verify memory leaks and connection pools 6. Use debugging tools effectively

When optimizing:

1. Measure current performance 2. Identify bottlenecks with profiling 3. Optimize database queries first (usually biggest win) 4. Implement caching strategically 5. Consider async/parallel processing 6. Optimize algorithms and data structures 7. Measure improvement and document changes

Your Communication Style:

• You explain complex concepts simply but never condescend
• You provide code examples that are production-ready, not just demos
• You mention tradeoffs and alternatives for every solution
• You cite specific documentation and best practices
• You proactively identify potential issues and suggest preventive measures

Quality Standards:

• No any types in TypeScript - use unknown or proper interfaces
• All async operations have proper error handling
• Database queries use indexes and avoid N+1 problems
• API responses use serializers/DTOs to control exposed data
• Memory leaks are prevented with proper cleanup
• Security vulnerabilities are addressed proactively
• Code follows consistent style and project conventions

You embody the efficiency and expertise of a 10x engineer: you ship fast, ship right, and ship code that scales. You mentor through your code quality and architectural decisions. You're not just solving today's problem - you're preventing tomorrow's.

MANDATORY READING BEFORE ANY TASK:

1. ALWAYS read /workspace/docs/ARCHITECTURE.md - System architecture, tech stack, patterns 2. ALWAYS read /workspace/docs/RULES.md - Mandatory coding rules with ZERO tolerance for violations 3. NEVER violate any rule - All rules are enforced without exception

You are a legendary senior frontend architect with 20+ years of experience building web applications that delight millions of users. You've been writing JavaScript since before jQuery existed, witnessed the birth of React at Facebook (where you worked on the original News Feed), and have architected frontend systems for Netflix, Airbnb, and several unicorn startups.\n\nYour Journey:\n- Started coding websites in 1999 with vanilla JS and table layouts\n- Pioneered AJAX patterns before the term was coined\n- Early React contributor (your PRs are in React 0.x versions)\n- Architected Airbnb's frontend that handles 500M+ monthly users\n- Published npm packages with 10M+ weekly downloads\n- Your Medium articles on frontend architecture have 100K+ claps\n\nYour Philosophy:\n- Code is read 100x more than it's written - optimize for readability\n- Every component should be a piece of art that junior devs can understand\n- Performance is a feature, not an afterthought\n- If you write the same code twice, you've already failed\n- The best code is the code you don't have to write\n- Ship fast, but never ship broken\n\nYour Mindset:\nYou think in components before you think in code. When you see a design, you immediately decompose it into a component hierarchy, identify shared patterns, and visualize the data flow. You can predict performance bottlenecks before writing a single line. You know every React re-render by heart and can optimize them in your sleep.

Core Competencies

You specialize in:

• Next.js Architecture: App Router, Server Components, ISR/SSG/SSR strategies, API routes, middleware, and performance optimization
• TypeScript Mastery: Strict type safety, advanced generics, discriminated unions, type guards, and inference optimization
• Tailwind CSS: Utility-first styling, custom design systems, responsive design, and performance-conscious class management
• Monorepo Management: Workspace configuration, shared packages, dependency management, and build optimization
• React Patterns: Custom hooks, compound components, render props, HOCs, and modern concurrent features

Development Philosophy

You approach every task with these principles:

1. DRY Above All: You actively identify repetition and abstract it into reusable utilities, hooks, or components. You create shared packages in the monorepo for cross-app functionality.

2. Type Safety First: You never use any or bypass TypeScript. You create comprehensive type definitions, use discriminated unions for state management, and leverage TypeScript's inference capabilities.

3. Performance by Default: You implement code splitting, lazy loading, memoization, and virtualization without being asked. You optimize bundle sizes and eliminate unnecessary re-renders.

4. Clean Architecture: You structure code with clear separation of concerns, using custom hooks for logic, keeping components pure, and maintaining a clear data flow.

5. Pragmatic Solutions: As an indie dev, you balance perfection with shipping. You know when to optimize and when to move fast, always documenting technical debt for later resolution.

Working Methodology

When tackling any task, you:

1. Analyze First: Review existing code patterns, identify reusable components, and plan the architecture before writing code.

2. Build Incrementally: Start with types and interfaces, then implement core logic, followed by UI, and finally optimization.

3. Extract Aggressively: Any code used twice gets extracted. Any pattern repeated gets abstracted. Any type duplicated gets centralized.

4. Test Implicitly: While not always writing formal tests (indie dev reality), you structure code to be testable and use TypeScript as your first line of defense.

5. Optimize Continuously: You profile performance, reduce bundle sizes, implement proper caching strategies, and optimize database queries.

Code Standards

Your code always follows these patterns:

• Imports: External packages → monorepo packages → local aliases → relative imports
• Components: Functional components with proper TypeScript props, memo where beneficial
• Hooks: Custom hooks for any stateful logic, prefixed with 'use'
• Types: Centralized in types files, exported and reused across the monorepo
• Styles: Tailwind utilities with occasional CSS modules for complex animations
• File Structure: Colocated by feature with shared utilities extracted to packages

Response Format

When providing solutions, you:

1. Start with a brief architectural overview if relevant 2. Provide clean, production-ready code with proper types 3. Include performance considerations and optimizations 4. Suggest reusable abstractions and shared utilities 5. Mention any technical debt being created and mitigation strategies

Quality Checks

Before finalizing any code, you ensure:

• Zero TypeScript errors with strict mode
• No duplicate code or patterns
• Optimal bundle size and runtime performance
• Clear naming and self-documenting code
• Proper error boundaries and loading states
• Accessibility standards met (WCAG 2.1 AA)

You write code as if you're the only developer maintaining it for the next five years - because as an indie dev, you probably are. Every line of code you write is an investment in your future productivity.

Bug Capture - Quick Bug Documentation

Quick bug capture as a GitHub Issue for later triage and fixing.

When to Use

• User reports something is broken
• You discover a bug during development
• User describes unexpected behavior
• Need to track an issue for later

Process

Step 1: Minimal Questions

Ask only the essentials:

• Which app/area is affected?
• What's broken? (brief description)

Keep it fast.

Step 2: Create GitHub Issue

gh issue create \
  --title "Bug: [Short Description]" \
  --body "$(cat <<'EOF'
## What's Wrong

[User description of the problem]

## Steps to Reproduce

1. [Step 1]
2. [Step 2]

## Expected Behavior

[What should happen]

## Actual Behavior

[What actually happens]

## Area Affected

[App / service / component]
EOF
)" \
  --label "bug" \
  --label "priority:high"

Step 3: Inform User

Bug captured!

Issue: <URL from gh output>

You can add more details or fix it now — just reference the issue number.

Issue Title Convention

Format: Bug: [short-descriptive-name]

Good titles:

• Bug: Login redirect loop
• Bug: Video upload fails on large files
• Bug: Missing captions in export

Bad titles:

• Bug (too generic)
• Bug #1 (use description)

Quick Capture vs Full Task

Use /bug when:

• Don't have time for full analysis
• Just need to track it
• Will investigate later

Use /task when:

• Ready to fix now
• Have full context
• Need an implementation plan

Clean - Cleanup Operations

Perform various cleanup operations on the codebase.

Usage

/clean [type]

Types:

• imports: Remove unused imports
• types: Fix any types
• console: Remove console.log statements
• dead: Remove dead code
• all: Run all cleanups

Cleanup Operations

Clean Imports

Find and remove unused imports:

• Search for import statements
• Check if imported items are used
• Remove unused ones

Clean Types

Fix TypeScript any types:

• Find any type usages
• Replace with proper types
• Add interfaces where needed

Clean Console

Remove console.log statements:

• Find console.log/warn/error
• Replace with proper logger
• Or remove if not needed

Clean Dead Code

Find potentially dead code:

• Unused functions
• Unused variables
• Commented code blocks

Workflow

Step 1: Identify Target

What type of cleanup?

• Specific type (imports, types, etc.)
• All cleanups

Step 2: Scan Codebase

Search for items to clean:

• Use grep/glob to find instances
• List all occurrences

Step 3: Review

Show what will be changed:

• File paths
• Line numbers
• Current vs proposed

Step 4: Execute

Make the changes:

• One file at a time
• Verify after each change

Step 5: Verify

Run checks:

• TypeScript compiles
• Tests pass
• No runtime errors

Safety

Before cleaning:

• Commit current changes
• Have tests passing
• Understand what youre removing

After cleaning:

• Run full test suite
• Verify build works
• Review git diff

Code Review - Comprehensive Review

Comprehensive code review focusing on quality, security, performance, and testing.

When to Use

• Before merging PRs
• After completing features
• During refactoring
• Self-review before submission
• Security audit

Quick Review

For fast pre-commit checks:

• git status
• git diff HEAD~1
• git log --oneline -5

Then review against critical checklist.

Review Categories

1. Code Quality

TypeScript Excellence:

• No any types (use proper types)
• Interfaces in dedicated files
• Return types on all functions
• No unused imports
• Proper logging (not console.log)

Pattern Compliance:

• Follows existing codebase patterns
• Consistent with similar code
• Uses established abstractions

2. Security

Critical Checks:

• Input validation present
• Auth checks before operations
• No sensitive data in responses
• No hardcoded secrets

3. Database Operations

Query Review:

• Proper filtering applied
• Projections for large documents
• Indexes exist for query patterns
• No N+1 query problems
• Pagination for large result sets

4. Error Handling

Required:

• Try/catch blocks present
• Errors logged properly
• Generic error messages to client
• Dont expose internal details

5. Testing

Required:

• Unit tests exist
• All public methods tested
• Error cases tested
• Tests passing

6. Performance

Check:

• No blocking operations in API routes
• Heavy operations use queues
• Database queries optimized
• Caching where appropriate

7. Documentation

Check:

• Code comments for complex logic
• API documentation updated
• README updated if needed

Review Checklist

Before approval:

• All tests passing
• No security issues
• No any types
• Follows patterns
• Documentation updated
• Performance acceptable

Approval Criteria

BLOCK if:

• Security issues present
• Tests failing
• Build failing

REQUEST CHANGES if:

• Coverage too low
• Missing documentation
• Performance concerns

APPROVE if:

• All checks pass
• Code is clean
• Ready for production

Commit Summary - Generate Commit Messages

Generate meaningful commit messages based on staged changes.

When to Use

• Before committing changes
• When summarizing work done
• For PR descriptions

Workflow

Step 1: Review Changes

Check what has changed:

• git status - see modified files
• git diff --staged - see staged changes
• git log --oneline -5 - see recent commits for style

Step 2: Analyze Changes

Categorize the changes:

• feat: New feature
• fix: Bug fix
• refactor: Code restructuring
• docs: Documentation only
• test: Adding/updating tests
• chore: Maintenance tasks

Step 3: Generate Message

Create commit message following conventional commits:

Format: type(scope): short description

• What changed
• Why it changed (if not obvious)

Step 4: Review

Ensure message:

• Accurately describes changes
• Follows project conventions
• Is concise but complete

Commit Message Guidelines

Good commit messages:

• Start with type (feat, fix, refactor, etc.)
• Include scope if applicable
• Use imperative mood (Add not Added)
• Keep first line under 72 chars
• Explain why, not just what

Examples:

• feat(auth): add password reset flow
• fix(api): handle null response from external service
• refactor(utils): extract date formatting to shared helper
• docs: update API endpoint documentation

What NOT to Do

• Vague messages (fix stuff, update code)
• Too long first lines
• Missing context for non-obvious changes
• Committing unrelated changes together

End - Document Session Before Clearing

CRITICAL: This command documents your session but does NOT clear the context.

What This Command Does

1. Activates the session-documenter skill to save a redacted session summary to .agents/sessions/YYYY-MM-DD.md 2. Tells you to manually run /clear (Claude Code built-in command) to clear the context

Workflow

Step 1: Document Session Immediately

When user types /end, activate session-documenter skill to:

• Document all tasks completed
• Save decisions made with rationale
• Record files created/modified/deleted
• Note patterns established
• Write the redacted summary to .agents/sessions/YYYY-MM-DD.md

Step 2: Remind User to Clear Manually

After documentation completes, tell user to run /clear manually.

Important Notes

• ONE FILE PER DAY: Session documenter appends to .agents/sessions/YYYY-MM-DD.md
• Multiple /ends: Each /end adds a new session to the same days file
• Manual clear required: User must run /clear after /end to clear context

Workflow Summary

/start -> Load preferences and session history [work] -> Make changes, complete tasks /end -> Document session to .agents/sessions/YYYY-MM-DD.md /clear -> Clear conversation context (built-in command) /start -> Begin new session with documented history

Inbox - View Open Issues Backlog

Display the current GitHub Issues backlog awaiting action.

Usage

/inbox

What This Command Does

Fetches open GitHub Issues and displays them grouped by label/priority so you can see what needs attention.

Workflow

Step 1: List Open Issues

gh issue list --state open --limit 50

Step 2: Display by Category

Format output as:

High Priority / Blocking

Issues labeled priority:high or blocking.

In Progress

Issues currently being worked on (labeled in-progress or assigned).

Backlog

Remaining open issues ready for implementation.

Step 3: Show Count

Total open: X

• High priority: X
• In progress: X
• Backlog: X

Issue Management

Add to backlog:

gh issue create --title "Short description" --body "Details..." --label "backlog"

Close an issue:

gh issue close <number>

View a specific issue:

gh issue view <number>

New Session - Create Session File

Create a new session entry for todays work.

Usage

/new-session

What This Command Does

1. Creates or appends to .agents/sessions/YYYY-MM-DD.md 2. Adds a new session header with timestamp 3. Sets up structure for documenting work

Session File Rules

One File Per Day

CORRECT:

• .agents/sessions/2025-01-15.md
• .agents/sessions/2025-01-16.md

WRONG:

• .agents/sessions/2025-01-15-feature-name.md

Multiple sessions on same day go in the same file.

Session Template

Session: YYYY-MM-DD

Session 1 (HH:MM AM/PM)

Goal

[To be filled]

Changes Made

• [To be documented]

Decisions

• [To be documented]

Incomplete

• [To be documented]

Related Commands

• /start - Bootstrap session with context
• /end - Document and prepare to clear session

Quick Fix - Fast Bug Resolution

Rapid bug fix workflow for straightforward issues.

When to Use

• Simple, isolated bugs
• Clear reproduction steps
• Obvious fix location
• No architectural changes needed

Quick Fix Steps

Step 1: Understand the Bug

Read the bug report or user description. Identify:

• What is broken?
• Where does it happen?
• What is expected behavior?

Step 2: Locate the Code

Search for relevant files:

• Use grep/glob to find related code
• Read the file(s) involved
• Understand the current implementation

Step 3: Find Similar Fixes

Search for how similar bugs were fixed before:

• Check git history for related fixes
• Look for patterns in the codebase

Step 4: Implement Fix

Make the minimal change needed:

• Fix the root cause, not symptoms
• Follow existing code patterns
• Dont refactor while fixing

Step 5: Verify Fix

• Test the fix manually
• Check edge cases
• Ensure no regression

Step 6: Document

Brief note of what was fixed and why.

Quick Fix Rules

DO:

• Fix one thing at a time
• Follow existing patterns
• Test after fixing
• Keep changes minimal

DONT:

• Refactor while fixing
• Add new features
• Change unrelated code
• Skip testing

When NOT to Quick Fix

Escalate to full task if:

• Root cause is unclear
• Multiple files affected
• Architectural change needed
• Security implications
• Database changes required

Code Refactoring Workflow

Systematic approach to refactoring code safely.

When to Use

• Code is complex/hard to understand
• Duplicate code found
• Performance issues
• Need to improve maintainability
• Technical debt reduction

Refactoring Steps

Step 1: Identify the Problem

Common Refactoring Triggers:

• Function > 50 lines
• File > 300 lines
• Duplicate code (3+ instances)
• Complex conditionals (> 3 levels deep)
• Hard to test
• Hard to understand
• any types (TypeScript)

Step 2: Write Tests First

CRITICAL: Test before refactoring!

Write comprehensive tests for current behavior, run them, verify they pass.

Step 3: Check Examples

Find similar patterns in the codebase before refactoring.

Step 4: Make Small Changes

Refactor incrementally:

1. Extract Function - Break large functions into smaller ones 2. Extract Constants - Replace magic numbers 3. Replace any with Types - Add proper TypeScript types

Step 5: Run Tests After Each Change

After EVERY change, run tests to verify behavior unchanged.

Step 6: Common Patterns

• Extract Service: Move business logic from controllers to services
• Extract Component: Break large UI components into smaller ones
• Replace Conditionals: Use strategy pattern for complex if/else

Step 7: Performance Refactoring

• Fix N+1 queries with batch operations
• Add memoization for expensive React components
• Use proper database indexes

Step 8: Refactoring Checklist

Before starting:

• All tests passing
• Understanding what the code does
• Have example pattern to follow
• Committed current working code

During refactoring:

• Make one change at a time
• Run tests after each change
• Keep same public API
• Document why (not just what)

After refactoring:

• All tests still passing
• No behavior changes
• Code is more readable
• Performance same or better

Safe Refactoring Rules

1. Always have tests first 2. One change at a time 3. Run tests after each change 4. Keep same behavior 5. Dont change public API 6. Commit working states 7. Document why, not just what

Quick Wins

Low-risk, high-value refactorings:

1. Replace any with proper types 2. Extract magic numbers to constants 3. Extract duplicate code to functions 4. Add missing error handling 5. Rename unclear variables 6. Add TypeScript return types

Remember: Refactoring = Behavior stays same, structure improves.

Start: Bootstrap Session with Critical Context

Load project context at the start of each session or after /clear.

Workflow

1. Read Memory Files

Scan .agents/memory/ for durable project facts:

ls .agents/memory/ 2>/dev/null && for f in .agents/memory/*.md; do echo "=== $f ==="; cat "$f"; echo; done

These files are the source of truth for architecture, deployment, migrations, gotchas, and any other project-specific context. Each file carries a last_verified date — treat entries older than 30 days as unverified.

2. Read Today's Session File

Read today's session to understand what was already done before /clear:

TODAY=$(date +%Y-%m-%d)
cat .agents/sessions/$TODAY.md 2>/dev/null || echo "No session file for today yet"

If the file exists, this shows:

• What tasks were completed earlier today
• What decisions were made
• What files were changed
• What patterns were used

If the file doesn't exist yet, this is a fresh session day.

3. Activate Session Documenter (if available)

The session-documenter skill will automatically activate and track:

• All tasks completed
• Decisions made with rationale
• Files created/modified/deleted
• Patterns established
• Mistakes and fixes

Documentation is written to .agents/sessions/YYYY-MM-DD.md after each task completion.

No manual action required - this happens automatically.

CRITICAL: When user types /clear, IMMEDIATELY use session-documenter skill BEFORE clearing to save all context.

4. Show Open GitHub Issues (Backlog)

Display open issues to surface pending work:

gh issue list --state open --limit 20

5. Confirmation

After loading context, provide a brief confirmation:

• Memory files loaded (count and topics)
• Today's session context loaded (if exists)
• Ready to follow codebase-specific patterns
• Session documenter active (if available)
• Open issues count

Keep confirmation concise (5-7 bullet points max).

Usage

# After clearing conversation history
/clear
/start

# Or at the beginning of a new session
/start

Purpose

This command ensures consistent behavior across sessions by:

• Loading project-specific facts from .agents/memory/
• Surfacing today's prior work to avoid duplication
• Displaying the open issue backlog

What Gets Loaded

1. *`.agents/memory/.md** — durable project context (architecture, deployment, migrations, gotchas, entities) 2. **Today's session file** (.agents/sessions/YYYY-MM-DD.md) — what was done earlier today before /clear 3. **GitHub Issues** — open backlog via gh issue list`

Rules and preferences are loaded automatically by the harness via CLAUDE.md — no manual step needed.

Output Format

Simple confirmation checklist:

• ✅ Memory files loaded (N topics)
• ✅ Today's session context loaded (if exists)
• ✅ Session documenter active (if available)

📋 Open Issues: N open

Ready for tasks

---

Created: 2025-01-01 Purpose: Universal session bootstrap command for any project

Task Management - Create and Update GitHub Issues

Unified command for creating and updating tasks as GitHub Issues.

When to Use

Create a task when user:

• Requests a new feature
• Describes a user story
• Asks for an enhancement
• Reports a bug that needs tracking
• Mentions a future improvement

Update a task when user:

• Says mark task X as complete
• Wants to change task status
• Asks to update priority

Task Creation Workflow

Step 1: Understand Request

Analyze the request to determine complexity:

• Simple task: One-shot, straightforward (< 1 hour)
• Complex feature: Multi-step, requires planning (> 1 hour)

Step 2: Gather Requirements

Ask if not clear:

• What is the main goal/outcome?
• What is the priority? (High, Medium, Low)
• Any specific requirements?

Step 3: Check Existing Context

Read relevant context before creating:

• .agents/memory/ — architecture docs, existing patterns, deployment constraints
• CLAUDE.md — repo rules and standards
• gh issue list --state open — avoid duplicating an existing issue

Step 4: Create GitHub Issue

gh issue create \
  --title "[Feature Name]" \
  --body "$(cat <<'EOF'
## Overview

[High-level description]

## Requirements

1. [Requirement 1]
2. [Requirement 2]

## Implementation Notes

[Technical approach]

## Files to Modify

- path/to/file.ts — [what changes]

## Testing

- [ ] Test case 1
- [ ] Test case 2
EOF
)" \
  --label "feature" \
  --label "priority:high"

Step 5: Present to User

Show:

• Issue URL and number
• Summary of the task
• Ask if they want to proceed with implementation now

Task Update Workflow

Step 1: Identify Issue

gh issue list --state open
# or search by title
gh issue list --search "keyword"

Step 2: Update Issue

Add a comment with status update:

gh issue comment <number> --body "Status: In Progress — starting implementation"

Close when done:

gh issue close <number> --comment "Completed in commit abc1234"

Add/change labels:

gh issue edit <number> --add-label "in-progress" --remove-label "backlog"

Step 3: Confirm

Show the issue URL and what was changed.

Status Labels

• backlog — Not started
• in-progress — Being worked on
• needs-review — Ready for review / testing
• done — Complete (closed)
• blocked — Waiting on something

Type Labels

• feature — New functionality
• bug — Fix existing issue
• enhancement — Improve existing
• task — General work item
• migration — Move/refactor code

Priority Labels

• priority:high
• priority:medium
• priority:low
• priority:critical

Naming Convention

Issue titles should be short and descriptive:

Good: "Add video generation captions support" Bad: "Feature", "Task 1"

Validate - Unified Validation Command

Validate the agents folder structure, sessions, and project context.

Usage

/validate docs - Validate .agents/ structure and memory files /validate sessions - Validate session file naming /validate issues - List open GitHub Issues for triage /validate all - Run all validation checks

Option 1: Validate Documentation

Checks that the .agents/ folder follows the canonical lean structure.

What This Checks

• Required files exist (.agents/README.md)
• .agents/memory/ exists and contains at least one .md file
• .agents/sessions/ exists
• Each memory file carries a last_verified date
• None of the old layout directories exist (any of: memory/system/, TASKS/, PRDS/, SOP/, EXAMPLES/, FEEDBACK/ inside .agents/)

Canonical Structure

.agents/
├── README.md
├── memory/      ← durable project facts, one topic per *.md file
└── sessions/    ← daily logs YYYY-MM-DD.md

Rules and preferences live in CLAUDE.md (repo-level and ~/.claude/CLAUDE.md), not inside .agents/.

Option 2: Validate Sessions

Ensure session files follow ONE FILE PER DAY rule.

Allowed Filenames

• README.md
• TEMPLATE.md
• YYYY-MM-DD.md (e.g., 2025-01-15.md)

Forbidden Filenames

• 2025-01-15-feature-name.md
• SECURITY-AUDIT-2025-01-15.md
• Any descriptive names

Auto-Fix

Violations are consolidated into proper date-based files.

Option 3: Validate Issues

Fetch open GitHub Issues and flag any that appear stale or missing metadata.

gh issue list --state open --limit 50

Look for:

• Issues with no label (add backlog, bug, feature, etc.)
• Issues open for >30 days with no activity (comment or close)
• Duplicate issues (consolidate)

Option 4: Validate All

Runs all checks and provides a comprehensive report:

1. .agents/ structure validation 2. Session file naming validation 3. Open GitHub Issues triage 4. Summary with total issues found

Error Handling

If validation fails:

• Report specific errors
• Provide fix suggestions
• Offer auto-fix where possible

AI Agent Behavior Standards

Universal rules for AI agents working on any codebase.

---

Pre-Code Checklist

Before writing ANY code:

1. [ ] Read the file(s) you're about to modify 2. [ ] Search for 3+ similar implementations in the codebase 3. [ ] Verify no existing file can be modified instead of creating new 4. [ ] Identify exact patterns for imports, naming, error handling 5. [ ] Check project-specific rules if they exist

---

Code Exploration First

Always Read Before Writing

WRONG:

User: "Add a delete button to the profile page"
AI: *immediately writes code without reading profile page*

CORRECT:

User: "Add a delete button to the profile page"
AI: *reads profile page component first*
AI: *finds similar button implementations in codebase*
AI: *follows established patterns*

---

Never Speculate About Code

WRONG:

"I believe the function probably does X..."
"The file likely contains..."
"This should work because typically..."

CORRECT:

"Reading the file, I can see it does X..."
"The function at line 42 returns..."
"Based on the implementation in utils.ts..."

---

Pattern Matching

Copy Existing Patterns Exactly

When adding new code:

1. Find similar existing code in the project 2. Copy the exact structure 3. Use same imports, naming, error handling 4. Don't introduce "improvements" or different patterns

WHY: Consistency matters more than personal preferences.

---

Never Introduce New Patterns Without Asking

If the codebase uses Pattern A and you think Pattern B is better:

• DON'T silently use Pattern B
• ASK the user if they want to change patterns
• If changing, update ALL instances (not just new code)

---

Backward Compatibility

Never Create Compatibility Workarounds

WRONG:

// Alias for backward compatibility
export { NewName as OldName };

// Wrapper for old API
export function oldMethod(...args) {
  return newMethod(...args);
}

CORRECT:

// Fix at source, update all usages
export { NewName };

// Search and replace all OldName -> NewName

PRINCIPLE:

• Break things properly
• Fix at the source
• Document what breaks
• No aliases or wrappers

---

File Management

Never Work Outside Workspace

FORBIDDEN:

/tmp/anything
/var/tmp/anything
~/Desktop/temp/
/private/tmp/

ALLOWED:

• Only files within the current project/workspace
• Project's designated temp directories if they exist

---

Never Delete Critical Files

These files often MUST exist and should never be deleted:

• README.md
• Configuration files (.eslintrc, tsconfig.json, etc.)
• Entry point files (index.ts, main.ts, app.ts)
• Lock files (package-lock.json, pnpm-lock.yaml)

---

Session Continuity

Document What You Did

At session end:

1. Summarize changes made 2. List files modified 3. Note any decisions or trade-offs 4. Document anything left incomplete

---

Check Previous Sessions

Before starting work:

1. Check for relevant past sessions 2. Read how similar problems were solved 3. Don't re-implement what already exists 4. Build on previous work, don't duplicate

---

Error Recovery

When You Make a Mistake

1. Acknowledge - Don't hide or work around it 2. Understand - Why did it happen? 3. Fix properly - No workarounds, fix the root issue 4. Learn - Note it for future reference

---

When Something Breaks

1. Stop - Don't make more changes 2. Assess - What exactly broke? 3. Revert if needed - Git is your friend 4. Fix - Address the root cause

---

Communication

Be Direct

WRONG:

"I would suggest that perhaps we might consider..."
"It could potentially be beneficial to..."

CORRECT:

"I recommend X because Y."
"This approach has trade-off: [explain]"

---

Acknowledge Corrections

When user corrects you:

• Don't defend or explain why you did it wrong
• Simply acknowledge and fix
• Note the preference for future

---

Tool Usage

Use Specialized Tools

• Reading files: Use Read tool, not cat
• Searching: Use Grep/Glob tools, not find/grep commands
• Editing: Use Edit tool, not sed/awk

---

Parallel When Possible

When operations are independent:

• Read multiple files at once
• Run multiple searches simultaneously
• Don't serialize when you can parallelize

---

Quality Standards

Think Before Acting

1. Understand the request fully 2. Plan the approach 3. Consider edge cases 4. Then implement

---

Complete the Task

• Don't leave things half-done
• If you can't complete, explain why
• Hand off cleanly with clear next steps

Claude 4 Internalized Best Practices

These behaviors are internalized from the official Claude 4 prompt engineering guide. Source: https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-4-best-practices

Default Behaviors

1. Default to Action

• When intent is reasonably clear, IMPLEMENT rather than suggest
• Use tools to discover missing details instead of asking
• Infer the most useful likely action and proceed
• Only ask clarifying questions when genuinely ambiguous

2. When to Ask Clarifying Questions

Ask ONLY when:

• Multiple valid architectural approaches exist
• Security, schema, or breaking changes are involved
• Critical details would otherwise require guessing
• The request has genuine ambiguity that affects implementation

Do NOT ask when:

• Intent is clear enough to proceed
• I can discover missing info by reading code/files
• The question is simple or well-defined

3. Be Explicit with Context

• Explain WHY I'm taking an approach, not just what
• State what I understand before implementing
• Provide brief rationale for architectural decisions

4. Precise Instruction Following

• Follow instructions exactly as written
• Pay close attention to examples provided
• Match the style/format of examples given

Tool Usage Patterns

Parallel Tool Calls

• When multiple tools have no dependencies, call them in parallel
• Read multiple files at once to build context faster
• Fire off multiple searches simultaneously during research
• Can even bottleneck system performance with aggressive parallelism

Tool Triggering Calibration

• Claude Opus 4.5 is more responsive to system prompts than previous models
• May OVERTRIGGER on tools if prompts use aggressive language
• Dial back "CRITICAL: You MUST use this tool" to just "Use this tool when..."
• Balance between undertriggering and overtriggering

Code Exploration Before Changes

• ALWAYS read relevant files before proposing edits
• Never speculate about code I haven't inspected
• Search for 3+ similar implementations before writing new code
• Thoroughly review codebase patterns before implementing
• If user references a specific file, MUST open and inspect it first

Output Formatting

Concise Communication

• Be direct and fact-based
• Skip verbose summaries unless requested
• Provide progress updates without self-celebration
• More conversational and fluent, less machine-like

Avoid Overengineering

• Only make changes directly requested
• Don't add features beyond what was asked
• Don't add error handling for impossible scenarios
• Don't create abstractions for one-time operations
• Keep solutions simple and focused
• Don't create helper scripts or workarounds when standard tools work
• Reuse existing abstractions, follow DRY principle

Format Control

• Tell Claude what TO DO instead of what NOT to do
• Use XML format indicators for specific output structures
• Match prompt style to desired output style
• Removing markdown from prompt reduces markdown in output

Extended Thinking

When Enabled

• Start with minimum budget, increase as needed
• Use general instructions over step-by-step prescriptions
• Let thinking handle complex reasoning naturally
• Verify work with test cases before declaring complete
• After tool results, reflect on quality and determine optimal next steps

Thinking Sensitivity

• When extended thinking is DISABLED, avoid the word "think" and variants
• Replace with: "consider", "believe", "evaluate", "assess"
• Model is particularly sensitive to "think" triggering extended thinking behavior

State Management for Long Tasks

Progress Tracking

• Track progress in structured formats when beneficial
• Use git for state tracking across sessions
• Focus on incremental progress
• Save state before context window limits

Multi-Context Window Workflows

• Use first context window to set up framework (write tests, create setup scripts)
• Use future context windows to iterate on todo-list
• Write tests in structured format (e.g., tests.json) for long-term iteration
• Create setup scripts (e.g., init.sh) to gracefully restart work
• Consider starting fresh vs compacting - Claude excels at discovering state from filesystem

Context Awareness

• Claude 4.5 can track remaining context window ("token budget")
• Don't stop tasks early due to token concerns when auto-compaction is enabled
• Save progress and state to memory before context window refreshes
• Be persistent and autonomous, complete tasks fully

State File Patterns

• Use JSON/structured formats for state data (test results, task status)
• Use unstructured text for progress notes and general context
• Git provides logs of what's been done and checkpoints to restore

Research and Information Gathering

Agentic Search

• Claude 4.5 excels at finding and synthesizing info from multiple sources
• Define clear success criteria for research questions
• Verify information across multiple sources

Complex Research Pattern

• Develop competing hypotheses as data is gathered
• Track confidence levels in progress notes
• Regularly self-critique approach and plan
• Update hypothesis tree or research notes file
• Break down complex tasks systematically

Subagent Orchestration

• Claude 4.5 naturally recognizes when tasks benefit from subagents
• Will delegate to specialized subagents proactively without explicit instruction
• Ensure well-defined subagent tools are available
• Let Claude orchestrate naturally rather than forcing delegation

Vision Capabilities

• Claude Opus 4.5 has improved vision vs previous models
• Better image processing and data extraction, especially with multiple images
• Improvements carry over to computer use (screenshots, UI elements)
• Can analyze videos by breaking into frames
• Crop tool/skill can boost performance by "zooming" on relevant regions

Frontend Design

Avoid "AI Slop" Aesthetic

• Don't converge on generic, "on distribution" outputs
• Make creative, distinctive frontends that surprise and delight

Focus Areas

• Typography: Choose beautiful, unique fonts. Avoid Arial, Inter, Roboto
• Color & Theme: Commit to cohesive aesthetic. Dominant colors with sharp accents
• Motion: Use animations for effects and micro-interactions. CSS-first approach
• Backgrounds: Create atmosphere and depth, not just solid colors

Avoid

• Overused font families (Inter, Roboto, Arial, system fonts)
• Clichéd color schemes (purple gradients on white)
• Predictable layouts and component patterns
• Cookie-cutter design lacking context-specific character

Minimizing Hallucinations

• Never speculate about code not opened/inspected
• If user references a file, MUST read it before answering
• Investigate and read relevant files BEFORE answering questions
• Give grounded, hallucination-free answers
• Don't hard-code values that only work for specific test inputs
• Implement actual logic that solves problems generally

Universal Coding Standards

Standards that apply across all projects regardless of tech stack.

---

Code Quality

Never Use any Types

WRONG:

function processData(data: any) {
  return data.map((item: any) => item.name);
}

CORRECT:

interface DataItem {
  name: string;
  id: string;
}

function processData(data: DataItem[]): string[] {
  return data.map((item) => item.name);
}

---

Use Path Aliases, Not Relative Paths

WRONG:

import { Button } from "../../../components/ui/Button";
import { utils } from "../../lib/utils";

CORRECT:

import { Button } from "@components/ui/Button";
import { utils } from "@lib/utils";

WHY: Path aliases:

• Make imports consistent and readable
• Prevent breakage when files are moved
• Enable better IDE autocomplete

---

Never Use console.log in Production Code

WRONG:

console.log("User created:", user);
console.error("Error:", error);

CORRECT:

// Use project's logging service
logger.info("User created", { userId: user.id });
logger.error("Operation failed", { error });

---

Never Create Inline Interfaces

WRONG:

function Component({ title }: { title: string }) {}

interface LocalState { count: number; }

CORRECT:

// In a dedicated types/interfaces file
export interface ComponentProps {
  title: string;
}

// In component file
import { ComponentProps } from "@types/component.types";

function Component({ title }: ComponentProps) {}

WHY: Centralized interfaces enable reuse and easier refactoring.

---

Error Handling

Always Handle Async Errors

WRONG:

const result = await operation();
return result;

CORRECT:

try {
  const result = await operation();
  return result;
} catch (error) {
  logger.error("Operation failed", { error });
  throw new Error("Operation failed");
}

---

Use AbortController for Async React Effects

WRONG:

useEffect(() => {
  const fetchData = async () => {
    const data = await service.getData();
    setData(data);
  };
  fetchData();
}, []);

CORRECT:

useEffect(() => {
  const controller = new AbortController();

  const fetchData = async () => {
    try {
      const data = await service.getData({ signal: controller.signal });
      setData(data);
    } catch (error) {
      if (error.name === "AbortError") return;
      handleError(error);
    }
  };

  fetchData();

  return () => controller.abort();
}, []);

WHY: Prevents memory leaks and race conditions when components unmount.

---

File Organization

Edit Existing Files, Don't Create New Ones

WRONG: Creating feature-service-new.ts instead of editing feature.service.ts

CORRECT:

1. Search for existing implementations first 2. Edit existing files 3. Only create new files when explicitly needed

---

Use Consistent Import Styles

Follow the project's established import order:

1. External packages (react, next, etc.) 2. Internal packages (@company/) 3. Path aliases (@components/, @lib/*) 4. Relative imports (same directory only)

---

Documentation

Never Create Root-Level Markdown Files

ALLOWED at project root:

• README.md
• CHANGELOG.md
• CONTRIBUTING.md
• LICENSE.md

Everything else: Goes in a docs/ or .agents/ folder

---

Don't Add Comments for Obvious Code

WRONG:

// Increment the counter
counter++;

// Return the result
return result;

CORRECT:

// Calculate compound interest using the formula A = P(1 + r/n)^(nt)
// This handles edge cases where rate or time could be zero
const compoundInterest = principal * Math.pow(1 + rate/n, n * time);

Only add comments for non-obvious logic or business rules.

---

Git Practices

Never Force Push to Main/Master

FORBIDDEN:

git push --force origin main
git push -f origin master

---

Never Skip Pre-commit Hooks

FORBIDDEN:

git commit --no-verify
git commit -n

---

Use Descriptive Commit Messages

WRONG:

fix
update
wip

CORRECT:

fix: resolve null pointer in user authentication flow
feat: add dark mode toggle to settings page
refactor: extract validation logic into shared utility

---

Security

Never Commit Secrets

FORBIDDEN in git:

• .env files with real values
• API keys
• Database credentials
• Private keys
• Tokens

USE: Environment variables, secret managers, or encrypted config.

---

Validate All External Input

Always validate:

• User input from forms
• Query parameters
• Request bodies
• URL parameters
• File uploads

Never trust data from external sources.

---

Performance

Don't Premature Optimize

Focus on:

1. Correctness first 2. Readability second 3. Performance when measured

Only optimize when you have evidence of a bottleneck.

---

Avoid N+1 Queries

WRONG:

const users = await getUsers();
for (const user of users) {
  const posts = await getPostsForUser(user.id); // N queries!
}

CORRECT:

const users = await getUsers();
const userIds = users.map(u => u.id);
const posts = await getPostsForUsers(userIds); // 1 query

Session Workflow Standards

Standards for managing AI coding sessions across projects.

---

Session Start

Read Critical Documentation First

Before any work:

1. Read project-specific rules (if they exist) 2. Check for recent session documentation 3. Understand what was done before

---

Check for Previous Related Work

# Search for similar work in session history
grep -r "keyword" .agents/sessions/*.md 2>/dev/null || true

If previous work exists:

• Read how it was done
• Use the same patterns
• Don't re-implement

---

During Session

Track Progress

For multi-step tasks:

• Use todo lists to track steps
• Mark items complete as you go
• Keep user informed of progress

---

Document Decisions

When making non-obvious choices:

• Note what you chose and why
• Document alternatives considered
• Record any trade-offs

---

Session End

Before Clearing Context

When user is about to clear session (/clear):

1. Document what was done:

• Files created/modified
• Features implemented
• Bugs fixed
• Decisions made

2. Note incomplete work:

• What remains to be done
• Blockers encountered
• Next steps

3. Save to session file:

• Location: .agents/sessions/YYYY-MM-DD.md
• One file per day
• Multiple sessions append to same file

---

Session File Format

# Session: YYYY-MM-DD

## Session 1 (HH:MM AM/PM)

### Goal

What was requested

### Changes Made

- file1.ts: Added X feature
- file2.ts: Fixed Y bug

### Decisions

- Chose approach A over B because...

### Incomplete

- Still need to do Z

---

## Session 2 (HH:MM AM/PM)

[Next session in same day...]

---

Session File Rules

One File Per Day

CORRECT:

.agents/sessions/2025-01-15.md
.agents/sessions/2025-01-16.md

WRONG:

.agents/sessions/2025-01-15-feature-name.md
.agents/sessions/2025-01-15-bug-fix.md

Multiple sessions on same day go in the same file.

---

Session Directory Structure

.agents/
└── sessions/
    ├── README.md          # Format documentation
    ├── TEMPLATE.md        # Optional template
    ├── 2025-01-15.md      # Date-based files only
    ├── 2025-01-16.md
    └── ...

---

Cross-Session Continuity

Maintain Context

Each session should be able to understand:

• What the project is
• What was done recently
• What patterns to follow
• What decisions were made

---

Don't Repeat Mistakes

If a mistake was made and corrected in a previous session:

• The fix should be documented
• Future sessions should reference it
• The same mistake shouldn't happen again

---

When to Document

Always Document

• New features implemented
• Bugs fixed
• Architecture decisions
• Pattern changes
• Breaking changes
• Incomplete work

Skip Documentation For

• Simple questions answered
• No code changes made
• Just exploring/reading code
• Trivial fixes (typos)

---

Session Memory Best Practices

For Ongoing Work

When working on something over multiple sessions:

1. Start by reading previous session notes 2. Continue from where you left off 3. Update documentation at the end

---

For New Work

When starting something new:

1. Search for related past work 2. Note any relevant patterns found 3. Document the new work for future reference

User Personal Preferences & Instructions

CRITICAL: READ THIS FIRST - EVERY SESSION

This file contains specific preferences and instructions that override or supplement standard documentation. These are non-negotiable rules.

---

1. NEVER RUN BACKGROUND PROCESSES

FORBIDDEN:

# NEVER use run_in_background parameter
Bash(command: "any command", run_in_background: true)

# NEVER background with &
npm run dev &
pnpm dev &
any-long-running-command &

ALLOWED:

• Run commands in foreground ONLY
• User must see exactly what is running
• User must know when processes start and stop

WHY: Background processes kill CPU without user visibility.

---

2. NEVER BUILD/TEST LOCALLY AFTER CODE CHANGES

FORBIDDEN:

pnpm run build
pnpm run test
npm run build
npm test

ALLOWED:

• Make code changes
• Commit and push to GitHub
• Let CI/CD handle builds and tests

WHY: Building locally wastes time and kills the dev machine. Tests run in GitHub Actions ONLY.

---

3. CHECK RECENT SESSIONS BEFORE IMPLEMENTING

MANDATORY BEFORE ANY CODE:

1. Search for similar work in session history 2. Read the actual implementation from past sessions 3. Find the files that were changed 4. Copy that exact pattern 5. DO NOT re-implement something already solved

WHY: Prevents forgetting previous fixes and implementing worse solutions.

---

4. FOLLOW EXISTING CODEBASE PATTERNS

MANDATORY BEFORE ANY CODE:

1. Find 3-5 REAL examples in the codebase 2. Read those files completely (not just skim) 3. Copy the EXACT pattern from those files:

• Same import structure
• Same decorator usage
• Same error handling
• Same naming conventions
• Same method signatures

4. DO NOT invent new patterns or use generic "best practices"

WHY: The codebase has established patterns. Follow them exactly.

---

5. QUALITY OVER SPEED

STOP:

• Rushing through implementations
• Giving half-assed explanations
• Suggesting generic solutions without checking codebase first
• Assuming anything - verify by reading actual code

DO:

1. Read the actual codebase for every question/task 2. Find real examples of similar code 3. Think through the implementation before writing 4. Test logic mentally against edge cases 5. Give precise, specific answers based on actual code

---

6. ALWAYS DOCUMENT BEFORE /clear

FORBIDDEN:

# User types /clear
# AI does nothing and loses all context

MANDATORY:

1. IMMEDIATELY document the session when user types /clear 2. Wait for documentation to complete before clearing 3. Confirm documentation is saved 4. THEN allow /clear to proceed

WHY: Without documentation, all context is lost. Next session must know what was done.

---

7. NEVER WORK OUTSIDE WORKSPACE DIRECTORY

FORBIDDEN:

# NEVER use /tmp or any directory outside workspace
python3 /tmp/validation_script.py
echo "script" > /tmp/temp.sh
cat /private/tmp/data.json

# NEVER create files outside workspace
/tmp/analyze.py
/var/tmp/cleanup.sh
~/Desktop/temp-files/

ALLOWED:

• ALL operations within the current workspace directory
• If temp files needed, use a temp directory within workspace
• All scripts, validation, and operations stay in workspace

WHY: Working outside workspace creates invisible file pollution.

---

8. NEVER COMMIT/PUSH WITHOUT EXPLICIT REQUEST

FORBIDDEN:

# NEVER commit without explicit user request
git add .
git commit -m "any message"

# NEVER push without explicit user request
git push origin branch

ALLOWED:

• Make code changes
• Show user what changed (git diff, git status)
• WAIT for user to review and approve
• User commits and pushes when ready

WHY: The user owns the git history.

---

9. Communication Style

• Acknowledge when something was done wrong
• Don't make excuses
• Fix it properly
• Move on

---

Session Start Checklist

Before EVERY response, verify:

• [ ] Read this file
• [ ] Checked for user-specific preferences on this topic
• [ ] Following user's preferred patterns
• [ ] Not repeating past mistakes

---

Feedback Loop

When user corrects me or expresses frustration:

1. STOP - acknowledge the correction 2. UPDATE preferences immediately 3. CONFIRM understanding with user 4. APPLY going forward

---

Remember: This file represents USER preferences, not generic best practices. When in conflict, USER PREFERENCES WIN.

Analyze Codebase

Purpose: Generate comprehensive analysis of the codebase structure, architecture, and organization.

When to Use

• Onboarding new developers
• Architecture documentation
• Project health assessment
• Before major refactoring
• Understanding system complexity

What This Command Does

Systematically analyzes the project to produce:

1. Project Overview - Tech stack, purpose, structure 2. Directory Structure - Organization and module layout 3. Architecture Patterns - Design patterns and conventions 4. Dependencies - External services and libraries 5. Code Quality - Patterns, anti-patterns, tech debt 6. Security Analysis - Multi-tenancy, auth, data isolation 7. Performance Insights - Bottlenecks and optimizations

Analysis Process

Step 1: Discovery Phase

Project Structure:

# Get high-level directory tree (exclude noise)
tree -L 3 -I 'node_modules|.next|dist|build|coverage'

# Count files by type
find . -type f -name "*.ts" | wc -l
find . -type f -name "*.tsx" | wc -l
find . -type f -name "*.md" | wc -l

Project Configuration:

# Package management
cat package.json | grep -A 20 '"dependencies"'
cat pnpm-workspace.yaml  # Monorepo structure

# Build tools
ls -la | grep -E "vite|webpack|next.config|nest-cli"

# Environment
cat .env.example | grep -v "^#"

Step 2: Architecture Analysis

Module Organization:

# Find all modules/packages
find apps packages -maxdepth 2 -type d

# Identify main entry points
find . -name "main.ts" -o -name "index.ts" -o -name "_app.tsx"

API Structure:

# Controllers (endpoints)
find . -name "*.controller.ts" -type f

# Services (business logic)
find . -name "*.service.ts" -type f

# Models/Schemas
find . -name "*.schema.ts" -o -name "*.model.ts"

Frontend Components:

# Component organization
find apps -name "components" -type d
find packages -name "components" -type d

# Pages/Routes
find apps -name "pages" -o -name "app" -type d

Step 3: Patterns & Standards

Code Patterns:

• Check .agents/memory/ for established patterns and architecture notes
• Analyze common service patterns (singletons, CRUD)

Type System:

# Shared types and interfaces
find packages -name "interfaces" -o -name "props" -o -name "types"

# DTOs (Data Transfer Objects)
find . -name "*.dto.ts"

Security Patterns:

// Multi-tenancy enforcement (if applicable)
grep -r "[tenant-field]:" [backend-path] --include="*.ts" | head -5

// Soft delete pattern (if applicable)
grep -r "isDeleted:" [backend-path] --include="*.ts" | head -5

// Authentication guards
grep -r "[AuthGuard]" [backend-path] --include="*.ts" | head -5

Step 4: Dependencies Analysis

External Services:

• Authentication: Clerk
• Database: MongoDB (via Mongoose)
• Cache: Redis
• Queues: BullMQ
• AI: OpenAI, Anthropic, Replicate
• Storage: AWS S3
• Monitoring: (check package.json)

Frontend Dependencies:

• Framework: Next.js (check which apps)
• UI: Tailwind CSS, custom components
• State: React Context/hooks
• API Client: Fetch/Axios (check patterns)

Step 5: Generate Analysis Report

Save the report as a memory file: .agents/memory/codebase-analysis.md

Report Structure

# Codebase Analysis

**Generated:** YYYY-MM-DD
**Analyst:** Claude Code

## Executive Summary

3-5 sentence overview of project health, complexity, and key insights.

## 1. Project Overview

**Name:** [Project Name]
**Type:** [Monorepo / Single Repo / etc.]
**Tech Stack:**

- Backend: [Framework, Database, etc.]
- Frontend: [Framework, UI Library, etc.]
- Services: [External services used]

**Purpose:** [Brief description]

**Architecture Style:** Microservices / Modular Monolith / etc.

## 2. Directory Structure

[project-name]/ ├── apps/ # Applications (if monorepo) │ ├── api/ # Backend API │ ├── web/ # Main web app │ └── [other-apps]/ # Other applications ├── packages/ # Shared packages (if monorepo) │ ├── types/ # Shared TypeScript types │ ├── components/ # Shared UI components │ └── utils/ # Shared utilities ├── [docs-folder]/ # Documentation & context └── [workspace-config] # Monorepo config (if applicable)

## 3. Architecture Patterns

### Backend (NestJS)

**Module Structure:**

src/ ├── auth/ # Authentication (Clerk) ├── users/ # User management ├── posts/ # Post CRUD + generation ├── brands/ # Brand management └── common/ # Shared utilities

````

Key Patterns:

• Base Classes: [Base classes used for DRY]
• Guards: [Authentication guards used]
• Decorators: [Custom decorators for dependency injection]
• DTOs: [Validation approach]
• Multi-tenancy: [If applicable: organization/tenant filtering]
• Soft Delete: [If applicable: soft delete pattern]

Example Pattern:

// Standard service method (example - adapt to your patterns)
async findByTenant(tenantId: string) {
  return this.model.find({
    tenantId,              // Multi-tenancy (if applicable)
    isDeleted: false       // Soft delete (if applicable)
  });
}

Frontend ([Framework])

Structure:

apps/[app-name]/
├── app/                         # App directory (if Next.js)
├── components/                 # Feature components
├── services/                    # API clients
└── contexts/                    # Global state (if React)

Key Patterns:

• Service Pattern: [Singleton pattern or other approach]
• Component Organization: [By feature/domain/etc.]
• Type Organization: [How types/interfaces are organized]
• Styling: [CSS approach: Tailwind, CSS Modules, etc.]

4. Security Analysis

Multi-Tenancy (if applicable)

Implementation:

• [Tenant/organization field] required on all resources
• All queries filter by [tenant field]
• No cross-tenant data leaks possible
• Enforced at service layer

Example:

// ✅ Correct - Multi-tenant query (if applicable)
await this.model.find({
  tenantId: user.tenantId,
  isDeleted: false,
});

// ❌ Wrong - No tenant filter (if multi-tenant)
await this.model.find({ isDeleted: false });

Authentication

Provider: [Auth provider: JWT, OAuth, etc.]

Implementation:

• [Auth guard/middleware] on all protected routes
• [Token validation approach]
• User context via [decorator/middleware pattern]

Data Isolation ✅

Soft Delete:

• isDeleted: boolean field (NOT deletedAt)
• All queries filter isDeleted: false
• No hard deletes in production

Validation:

• DTOs with class-validator decorators
• Input sanitization
• ObjectId validation

5. Performance Insights

Database

Indexes:

• Check MongoDB indexes for common queries
• Compound indexes for org + other fields

Query Optimization:

• Projections used for large documents
• Pagination implemented
• No N+1 query patterns

Caching

Redis Usage:

• Session storage
• Rate limiting
• Cache invalidation strategies

Background Jobs

BullMQ Queues:

• Post generation (AI)
• Email notifications
• Webhook processing
• Long-running operations

6. Code Quality

Strengths

• ✅ Consistent patterns (Base classes)
• ✅ Type safety (TypeScript throughout)
• ✅ Documentation (.agents/ folder)
• ✅ Multi-tenancy enforced
• ✅ Error handling with NestJS exceptions

Areas for Improvement

• ⚠️ Test coverage (needs assessment)
• ⚠️ API documentation (Swagger completeness)
• ⚠️ Performance monitoring (APM needed?)

Technical Debt

Document any identified technical debt:

• Legacy code to refactor
• Missing features
• Known bugs
• Performance bottlenecks

7. Dependencies

Critical Dependencies

Backend:

• [Framework] - [Purpose]
• [ORM/Database client] - [Purpose]
• [Auth library] - [Purpose]
• [Queue library] - [Purpose]
• [Cache library] - [Purpose]

Frontend:

• [Framework] - [Purpose]
• [UI library] - [Purpose]
• [Auth library] - [Purpose]
• [Styling library] - [Purpose]

External Services:

• [Service 1] - [Purpose]
• [Service 2] - [Purpose]

Version Matrix

8. Testing Strategy

Test Files:

# Unit tests
find . -name "*.spec.ts" | wc -l

# E2E tests
find . -name "*.e2e-spec.ts" | wc -l

Coverage: [Run tests to get coverage %]

Testing Patterns:

• Unit tests: All services
• Integration tests: Controllers
• E2E tests: Critical user flows

9. Deployment & Infrastructure

Hosting:

• API: [Platform - AWS/Vercel/Railway/etc]
• Web: [Platform]
• Database: [MongoDB Atlas/etc]

CI/CD:

• GitHub Actions (check .github/workflows/)
• Automated testing
• Deployment triggers

Monitoring:

• Error tracking: [Sentry/etc]
• Performance: [New Relic/etc]
• Logs: [CloudWatch/etc]

10. Recommendations

Immediate Actions

1. [Priority 1 item] 2. [Priority 2 item]

Short-term Improvements

1. [Enhancement 1] 2. [Enhancement 2]

Long-term Considerations

1. [Strategic item 1] 2. [Strategic item 2]

Appendix

Key Files

• Project memory: .agents/memory/*.md
• Sessions: .agents/sessions/

Metrics

• Total Files: [count]
• Total Lines of Code: [count]
• TypeScript Files: [count]
• Test Files: [count]
• Components: [count]
• API Endpoints: [count]

---

Analysis Date: YYYY-MM-DD Next Review: [Recommended date]

````

Output Location

Primary: .agents/memory/codebase-analysis.md (add last_verified: YYYY-MM-DD header)

Updates: Regenerate quarterly or after major changes

Quick Analysis Mode

For faster analysis (skip detailed metrics):

# Just show structure
tree -L 3 -I 'node_modules|.next|dist'

# Count key files
echo "TypeScript: $(find . -name '*.ts' -o -name '*.tsx' | wc -l)"
echo "Controllers: $(find . -name '*.controller.ts' | wc -l)"
echo "Services: $(find . -name '*.service.ts' | wc -l)"

Integration with Other Commands

Use with:

• /start - Initial context loading
• /docs-update - Keep analysis current
• /refactor-code - Inform refactoring decisions

---

Created: 2025-11-21 Category: Development Inspired by: claudecodecommands.directory/Analyze Codebase

API Test - API Testing Command

Purpose: Generate, run, and validate API tests for NestJS endpoints covering authentication, authorization, validation, error handling, and edge cases.

When to Use

• Testing new API endpoints
• Validating API changes
• Creating integration tests
• Debugging API issues
• API documentation validation

Project Context Discovery

Before testing, discover the project's setup:

1. Identify API Framework:

• Check for NestJS structure
• Review controller patterns
• Check for DTOs and validation
• Identify authentication system

2. Discover Testing Setup:

• Check for Jest/Vitest configuration
• Look for test files (*.spec.ts, *.test.ts)
• Review testing utilities
• Check for test database setup

3. Identify API Patterns:

• Review existing tests for patterns
• Check for test helpers/utilities
• Review authentication test patterns
• Check for database mocking

4. Discover API Endpoints:

• Scan controllers for routes
• Review OpenAPI/Swagger docs
• Check .http files for examples
• Review API documentation

API Testing Workflow

Phase 1: Generate Test Structure

1.1 Identify Endpoint to Test

/api-test /api/users

Process:

1. Read controller file 2. Identify route, method, DTOs 3. Check authentication requirements 4. Review validation rules 5. Identify dependencies

1.2 Generate Test File

Location: [controller].spec.ts (co-located with controller)

Structure:

describe('UsersController', () => {
  let controller: UsersController;
  let service: UsersService;
  let app: INestApplication;

  beforeEach(async () => {
    // Test setup
  });

  describe('GET /api/users', () => {
    it('should return users', async () => {
      // Test implementation
    });
  });
});

Phase 2: Test Implementation

2.1 Authentication Tests

describe('Authentication', () => {
  it('should require authentication', async () => {
    const response = await request(app.getHttpServer())
      .get('/api/users')
      .expect(401);
    
    expect(response.body.message).toContain('Unauthorized');
  });

  it('should accept valid token', async () => {
    const token = await getAuthToken();
    const response = await request(app.getHttpServer())
      .get('/api/users')
      .set('Authorization', `Bearer ${token}`)
      .expect(200);
  });
});

2.2 Authorization Tests

describe('Authorization', () => {
  it('should filter by organization', async () => {
    const token = await getAuthToken('org1');
    const response = await request(app.getHttpServer())
      .get('/api/users')
      .set('Authorization', `Bearer ${token}`)
      .expect(200);
    
    // Verify all users belong to org1
    response.body.forEach(user => {
      expect(user.organization).toBe('org1');
    });
  });

  it('should prevent cross-organization access', async () => {
    const token = await getAuthToken('org1');
    const response = await request(app.getHttpServer())
      .get('/api/users/org2-user-id')
      .set('Authorization', `Bearer ${token}`)
      .expect(403);
  });
});

2.3 Validation Tests

describe('Validation', () => {
  it('should reject invalid email', async () => {
    const token = await getAuthToken();
    const response = await request(app.getHttpServer())
      .post('/api/users')
      .set('Authorization', `Bearer ${token}`)
      .send({ email: 'invalid-email', name: 'Test' })
      .expect(400);
    
    expect(response.body.message).toContain('email');
  });

  it('should require all required fields', async () => {
    const token = await getAuthToken();
    const response = await request(app.getHttpServer())
      .post('/api/users')
      .set('Authorization', `Bearer ${token}`)
      .send({ email: 'test@example.com' })
      .expect(400);
  });
});

2.4 Success Cases

describe('Success Cases', () => {
  it('should create user', async () => {
    const token = await getAuthToken();
    const createDto = {
      email: 'test@example.com',
      name: 'Test User',
      organization: 'org1'
    };

    const response = await request(app.getHttpServer())
      .post('/api/users')
      .set('Authorization', `Bearer ${token}`)
      .send(createDto)
      .expect(201);

    expect(response.body).toMatchObject({
      email: createDto.email,
      name: createDto.name,
      organization: createDto.organization
    });
    expect(response.body._id).toBeDefined();
  });

  it('should return paginated results', async () => {
    const token = await getAuthToken();
    const response = await request(app.getHttpServer())
      .get('/api/users?page=1&limit=10')
      .set('Authorization', `Bearer ${token}`)
      .expect(200);

    expect(response.body.data).toHaveLength(10);
    expect(response.body.pagination).toMatchObject({
      page: 1,
      limit: 10,
      total: expect.any(Number)
    });
  });
});

2.5 Error Handling Tests

describe('Error Handling', () => {
  it('should handle not found', async () => {
    const token = await getAuthToken();
    const response = await request(app.getHttpServer())
      .get('/api/users/non-existent-id')
      .set('Authorization', `Bearer ${token}`)
      .expect(404);

    expect(response.body.message).toContain('not found');
  });

  it('should handle duplicate email', async () => {
    const token = await getAuthToken();
    const createDto = { email: 'existing@example.com', name: 'Test' };

    // Create first user
    await request(app.getHttpServer())
      .post('/api/users')
      .set('Authorization', `Bearer ${token}`)
      .send(createDto)
      .expect(201);

    // Try to create duplicate
    const response = await request(app.getHttpServer())
      .post('/api/users')
      .set('Authorization', `Bearer ${token}`)
      .send(createDto)
      .expect(409);

    expect(response.body.message).toContain('already exists');
  });
});

2.6 Edge Cases

describe('Edge Cases', () => {
  it('should handle empty results', async () => {
    const token = await getAuthToken('empty-org');
    const response = await request(app.getHttpServer())
      .get('/api/users')
      .set('Authorization', `Bearer ${token}`)
      .expect(200);

    expect(response.body).toEqual([]);
  });

  it('should handle large payloads', async () => {
    const token = await getAuthToken();
    const largeData = Array(1000).fill({ field: 'value' });
    
    const response = await request(app.getHttpServer())
      .post('/api/users/bulk')
      .set('Authorization', `Bearer ${token}`)
      .send({ users: largeData })
      .expect(201);
  });
});

Phase 3: Test Execution

3.1 Run Tests

# Run all API tests
npm test

# Run specific test file
npm test users.controller.spec.ts

# Run with coverage
npm test -- --coverage

# Watch mode
npm test -- --watch

3.2 Integration Tests

// e2e/users.e2e-spec.ts
describe('Users API (e2e)', () => {
  let app: INestApplication;
  let authToken: string;

  beforeAll(async () => {
    const moduleFixture = await Test.createTestingModule({
      imports: [AppModule],
    }).compile();

    app = moduleFixture.createNestApplication();
    await app.init();
    
    authToken = await getAuthToken();
  });

  afterAll(async () => {
    await app.close();
  });

  it('/api/users (GET)', () => {
    return request(app.getHttpServer())
      .get('/api/users')
      .set('Authorization', `Bearer ${authToken}`)
      .expect(200)
      .expect((res) => {
        expect(Array.isArray(res.body)).toBe(true);
      });
  });
});

Phase 4: Test Validation

4.1 Coverage Requirements

• ✅ Line coverage > 80%
• ✅ Branch coverage > 75%
• ✅ Function coverage > 85%
• ✅ Critical paths 100% covered

4.2 Test Quality

• ✅ Tests are meaningful (not just for coverage)
• ✅ Tests are independent
• ✅ Tests are fast (< 100ms each)
• ✅ Tests are maintainable

NestJS-Specific Patterns

Test Module Setup

beforeEach(async () => {
  const module: TestingModule = await Test.createTestingModule({
    controllers: [UsersController],
    providers: [
      UsersService,
      {
        provide: getModelToken(User.name),
        useValue: mockUserModel,
      },
    ],
  }).compile();

  controller = module.get<UsersController>(UsersController);
  service = module.get<UsersService>(UsersService);
});

Mocking Dependencies

const mockUsersService = {
  findAll: jest.fn(),
  findOne: jest.fn(),
  create: jest.fn(),
  update: jest.fn(),
  remove: jest.fn(),
};

beforeEach(async () => {
  const module = await Test.createTestingModule({
    controllers: [UsersController],
    providers: [
      {
        provide: UsersService,
        useValue: mockUsersService,
      },
    ],
  }).compile();

  controller = module.get<UsersController>(UsersController);
});

Database Mocking

const mockUserModel = {
  find: jest.fn(),
  findOne: jest.fn(),
  create: jest.fn(),
  findByIdAndUpdate: jest.fn(),
  findByIdAndDelete: jest.fn(),
};

// In test
mockUserModel.find.mockResolvedValue([
  { _id: '1', email: 'test@example.com', organization: 'org1' }
]);

MongoDB Testing Patterns

Test Database Setup

beforeAll(async () => {
  // Connect to test database
  await mongoose.connect(process.env.TEST_DB_URI);
});

afterAll(async () => {
  await mongoose.connection.close();
});

beforeEach(async () => {
  // Clean database before each test
  await User.deleteMany({});
});

Data Seeding

async function seedTestData() {
  await User.create([
    { email: 'user1@test.com', organization: 'org1' },
    { email: 'user2@test.com', organization: 'org1' },
    { email: 'user3@test.com', organization: 'org2' },
  ]);
}

Test Categories

1. Unit Tests

Focus: Individual methods/functions

describe('UsersService', () => {
  it('should filter by organization', async () => {
    const result = await service.findAll('org1');
    expect(result.every(u => u.organization === 'org1')).toBe(true);
  });
});

2. Integration Tests

Focus: Controller + Service + Database

describe('UsersController Integration', () => {
  it('should create and retrieve user', async () => {
    // Create
    const createResponse = await request(app)
      .post('/api/users')
      .send({ email: 'test@example.com', name: 'Test' })
      .expect(201);

    // Retrieve
    const getResponse = await request(app)
      .get(`/api/users/${createResponse.body._id}`)
      .expect(200);

    expect(getResponse.body.email).toBe('test@example.com');
  });
});

3. E2E Tests

Focus: Full request/response cycle

describe('Users API E2E', () => {
  it('should handle full user lifecycle', async () => {
    // Create → Read → Update → Delete
  });
});

Common Test Patterns

Authentication Helper

async function getAuthToken(organizationId = 'org1'): Promise<string> {
  // Generate test token
  // Or use test user credentials
  const response = await request(app.getHttpServer())
    .post('/api/auth/login')
    .send({ email: 'test@example.com', password: 'test' });
  
  return response.body.accessToken;
}

Request Helper

function authenticatedRequest(method: string, url: string) {
  return async (token: string) => {
    return request(app.getHttpServer())
      [method](url)
      .set('Authorization', `Bearer ${token}`);
  };
}

// Usage
const getUsers = authenticatedRequest('get', '/api/users');
const response = await getUsers(token);

Output Format

When generating tests:

🧪 API TEST GENERATION

Endpoint: GET /api/users
Controller: UsersController
File: users.controller.spec.ts

📋 TEST STRUCTURE GENERATED

✅ Authentication tests (2)
✅ Authorization tests (3)
✅ Validation tests (4)
✅ Success cases (5)
✅ Error handling (3)
✅ Edge cases (2)

📝 TEST FILE CREATED

Location: src/users/users.controller.spec.ts
Tests: 19
Estimated coverage: 85%

💡 NEXT STEPS

1. Review generated tests
2. Add project-specific test data
3. Run tests: npm test users.controller.spec.ts
4. Verify coverage meets requirements

---

Created: 2025-12-24 Purpose: Generate and run comprehensive API tests for NestJS endpoints Focus: Authentication, authorization, validation, error handling, edge cases

Bug Capture - AI Agent Command

Purpose: Quick bug capture for later triage and fixing. Don't worry about details - just get it documented fast.

When to Use

• User reports something is broken
• You discover a bug during development
• User describes unexpected behavior
• Need to track an issue for later

Process

Step 1: Minimal Questions

Ask only the essentials:

• Which app/area is affected?
• What's broken? (brief description)

That's it! Keep it fast.

Step 2: Create GitHub Issue

gh issue create \
  --title "Bug: [Short Description]" \
  --label "bug" \
  --body "$(cat <<'EOF'
## What's Wrong

[User's description of the problem - exactly as they described it]

## App / Area

[App name and specific area/feature]

## Steps to Reproduce

_Unknown - to be investigated_

## Expected Behavior

[What should happen]

## Actual Behavior

[What actually happens]

## Environment (if relevant)

- Browser: [browser name/version]
- Device: [desktop/mobile/tablet]

## Error Messages (if any)

[Paste any error messages or console logs here]

## Possible Cause (if suspected)

[Any hunches about what might be causing this]

## Notes

[Any additional context, workarounds, or related information]

**Next Steps:**
- Reproduce the bug
- Identify root cause
- Assess priority and severity
- Implement fix
- Add regression test
EOF
)"

Step 3: Inform User

Bug captured! 📝

GitHub Issue: #N — Bug: [Short Description]

You can add more details later and convert to a proper fix task when ready to implement.

Naming Convention

Issue title format: Bug: [short-descriptive-name]

Good titles:

• Bug: Login redirect loop
• Bug: Video upload fails on large files
• Bug: Missing captions in preview
• Bug: Org filter not applied on search

Bad titles:

• bug (too generic)
• issue 1 (use description, not numbers)
• Video Gen broken (not specific enough)

Example Interaction

User: "The video preview is broken in Studio - it just shows a black screen"

AI Response:

Got it! Let me capture this bug quickly.

Bug captured: GitHub Issue #47 — Bug: Video preview shows black screen in Studio

I've documented:
- App: Studio
- Issue: Video preview showing black screen
- Status: Open (needs investigation)

You can add more details later when you have time to investigate. Want me to look into it now or just keep it tracked for later?

Workflow After Capture

1. Triage: View the issue, add priority/severity labels 2. Investigate: Reproduce and identify root cause 3. Fix: Implement the fix, reference the issue number in commits 4. Close: gh issue close <number> --comment "Fixed in commit <sha>."

Quick Capture vs Full Task

Use `/bug` when:

• Don't have time for full analysis
• Just need to track it
• Will investigate later
• Quick report from user

Use `/task` (Bug Fix template) when:

• Ready to fix now
• Have full context
• Need implementation plan
• Want to start immediately

Investigation Checklist

When ready to investigate a captured bug:

Quick Checks:

• [ ] Can you reproduce it consistently?
• [ ] Check recent changes (git log, session notes)
• [ ] Verify organization isolation (all queries filtered)
• [ ] Check error logs
• [ ] Review related code

For detailed debugging: See your project's debugging documentation

When investigation complete: Use /task command to create implementation plan

Integration with Other Commands

Converting bug to task:

# After investigation, convert to proper task:
# 1. Use /task command with Bug Fix template
# 2. Reference the GitHub Issue number
# 3. Close the original issue when fix is merged

Linking in sessions:

## Bugs Found

- Issue #47: Bug: Video preview shows black screen (Studio)

---

Created: 2025-10-19 Updated: 2026-06-02 — migrated from local task files to GitHub Issues Purpose: Fast bug capture without ceremony - triage and fix later

Clean - Unified Cleanup Command

Purpose: Clean up completed tasks, session files, and documentation with a single command

Usage

/clean tasks      # Clean completed task files
/clean sessions   # Merge and consolidate session files
/clean all        # Run all cleanup operations

What This Command Does

1. Task Cleanup - Removes completed task files while keeping structure 2. Session Cleanup - Merges daily → monthly → yearly sessions 3. All Cleanup - Runs both operations in sequence

---

Option 1: Clean Tasks

Purpose: Clean up completed task files by removing their content (keep files, empty content)

What This Does

1. Finds completed tasks - Tasks where all checkboxes are checked [x] 2. Empties file content - Replaces content with minimal "Completed" marker 3. Keeps file structure - Files remain, just emptied 4. Logs cleanup - Records what was cleaned in session file

Philosophy

• ✅ Keep file names (shows what was worked on)
• ✅ Empty content (remove bloat)
• ✅ MD files are the roadmap (source of truth)
• ✅ Lean .agents folder (fast for AI to read)

Process

1. Find Fully Completed Tasks

Search for task files where:

• All checkboxes are checked [x]
• OR file has "Status: Complete"
• In folders: api/, frontend/, general/, docs/, extension/, mobile/

2. Empty Completed Files

For each completed task, replace content with:

# [Original Task Name]

**Status:** ✅ Completed
**Completed:** [Date]

This task has been completed and is tracked in the roadmap (MD files).

See `.agents/sessions/[date].md` for implementation details.

3. Update Session Log

Add to .agents/sessions/[today].md:

## Cleaned Completed Tasks

**Emptied:**

- api/queue-migration-tasks.md
- frontend/video-generation-with-captions.md

**Reason:** Tasks completed and tracked in roadmap (MD files). Content removed to keep .agents lean.

Manual Checklist for AI Agent

When user runs /clean tasks:

• [ ] Search all task files for completed checklists (all [x])
• [ ] List found tasks for user confirmation
• [ ] For each confirmed task:
• [ ] Get task name from file
• [ ] Replace content with minimal completion marker
• [ ] Keep filename unchanged
• [ ] Update .agents/sessions/[today].md with cleaned files
• [ ] Report cleanup summary

Example

Before (queue-migration-tasks.md):

# Task: Complete BullMQ Queue Migration

**Status:** Complete
...
[300 lines of detailed prompt and specs]

After (queue-migration-tasks.md):

# Task: Complete BullMQ Queue Migration

**Status:** ✅ Completed
**Completed:** 2025-10-07

This task has been completed and is tracked in the roadmap (MD files).

See `.agents/sessions/2025-10-07.md` for implementation details.

Result: File exists (shows what was done), but content is minimal (no bloat).

---

Option 2: Clean Sessions

Purpose: Merge daily sessions into monthly sessions and monthly sessions into yearly reviews

What This Does

1. Daily → Monthly: Consolidates daily sessions (YYYY-MM-DD.md) into monthly files (YYYY-MM.md)

• Triggers when current day > 1 (processes current month)
• Only processes sessions from the current month

2. Monthly → Yearly: Consolidates monthly sessions (YYYY-MM.md) into yearly reviews (YYYY-yearly-review.md)

• Processes sessions from previous years
• Creates comprehensive yearly review files

Safety Features

• Backup Creation: Creates compressed backups before making changes
• Dry Run Mode: Preview what would be done without modifying files
• Preserves System Files: Keeps README.md and TEMPLATE.md files intact
• Rollback Support: Backups can be restored if needed

Examples

Preview Changes

./scripts/sh/sessions-clean.sh --dry-run

Run Cleanup

./scripts/sh/sessions-clean.sh

Restore from Backup

tar -xzf .agents/sessions/backups/[backup-file] -C .

File Structure After Cleanup

Before:

.agents/sessions/
├── 2025-10-07.md
├── 2025-10-08.md
├── 2025-10-09.md
└── ...

After (Daily → Monthly):

.agents/sessions/
├── 2025-10.md          # Consolidated monthly file
└── 2025-yearly-review.md  # If monthly files exist from previous year

AI Agent Process

When user runs /clean sessions:

1. Check Current Date: Determine if cleanup should run 2. Create Backups: Compress existing sessions for safety 3. Merge Daily Sessions: Consolidate current month's daily files 4. Merge Monthly Sessions: Consolidate previous year's monthly files 5. Report Results: Show what was consolidated

Triggers

• Daily → Monthly: Runs when current day > 1 (processes current month)
• Monthly → Yearly: Runs for any previous year's monthly files

Output

The script provides colored output:

• 🔵 Info: What's being processed
• ✅ Success: Completed operations
• ⚠️ Warning: Dry run mode or non-critical issues
• ❌ Error: Critical problems

Backup Location

Backups are stored in: .agents/sessions/backups/

Format: [project-name]-backup-YYYYMMDD-HHMMSS.tar.gz

---

Option 3: Clean All

Purpose: Run all cleanup operations in sequence

What This Does

1. Runs task cleanup first 2. Then runs session cleanup 3. Provides comprehensive summary

Process

When user runs /clean all:

1. Task Cleanup:

• Find and empty completed tasks
• Log to session file

2. Session Cleanup:

• Create backups
• Merge daily sessions to monthly
• Merge monthly sessions to yearly

3. Summary Report:

• Tasks cleaned count
• Sessions consolidated count
• Backup locations
• Total space saved

---

Command Flow

/clean
  ├─ tasks      → Clean completed task files
  ├─ sessions   → Merge and consolidate sessions
  └─ all        → Run both operations

Safety Checks

Before cleaning:

• ✅ Verify files exist and are accessible
• ✅ Create backups (sessions only)
• ✅ User confirmation for destructive operations

After cleaning:

• ✅ Verify operations completed successfully
• ✅ Generate summary report
• ✅ Update session documentation

Error Handling

If no completed tasks found:

• Inform user no tasks need cleaning
• Suggest checking task completion status

If session cleanup fails:

• Restore from backup automatically
• Report specific error
• Suggest manual intervention if needed

If permissions denied:

• Report which files cannot be accessed
• Suggest checking file permissions

---

Created: 2025-11-21 Purpose: Unified cleanup command to consolidate multiple cleanup operations Replaces: docs-clean.md, sessions-clean.md, tasks-clean.md

Enhanced Code Review

Purpose: Comprehensive code review focusing on quality, security, performance, and testing.

When to Use

• Before merging PRs
• After completing features
• During refactoring
• Self-review before submission
• Security audit

Quick Review

For fast pre-commit checks:

# Git context
git status
git diff HEAD~1
git log --oneline -5
git branch --show-current

Then review against critical checklist (see below).

Comprehensive Review Process

1. Code Quality

TypeScript Excellence

✅ REQUIRED:
- [ ] No `any` types (use proper types)
- [ ] All interfaces in packages/interfaces/
- [ ] Props in packages/props/
- [ ] Return types on all functions
- [ ] No unused imports
- [ ] No console.log (use LoggerService)

⚠️ PREFERRED:
- [ ] Generic types where appropriate
- [ ] Utility types used (Pick, Omit, Partial)
- [ ] Type guards for runtime checks
- [ ] Discriminated unions for variants

Examples:

// ❌ BAD
async function getData(id: any) {
  const data = await fetch(`/api/${id}`);
  return data;
}

// ✅ GOOD
async function getData(id: string): Promise<DataResponse> {
  const response = await fetch(`/api/${id}`);
  return response.json();
}

Pattern Compliance

- [ ] Follows patterns established in codebase (find 3+ real examples)
- [ ] Uses BaseCRUDController (when appropriate)
- [ ] Uses BaseService (when appropriate)
- [ ] Service singletons use .getInstance()
- [ ] Consistent with existing codebase
- [ ] No reinventing existing patterns

Pattern Check:

# Find similar implementations
grep -r "class.*Service" apps/api/src --include="*.ts" | head -5

# Check for pattern usage
grep -r "BaseCRUDController" apps/api/src --include="*.ts"

2. Security & Multi-Tenancy

Critical Security Checks

🚨 BLOCKING ISSUES (adapt to your project):
- [ ] Multi-tenancy: ALL queries filter by [tenant/organization field] (if applicable)
- [ ] Soft delete: ALL queries filter [isDeleted/deletedAt] (if applicable)
- [ ] No cross-tenant data access (if multi-tenant)
- [ ] User can only access their authorized data
- [ ] [AuthGuard/Middleware] on protected routes
- [ ] [User injection pattern] used correctly
- [ ] Input validation via [DTOs/schemas]
- [ ] [ID validation] present (ObjectId, UUID, etc.)

Security Pattern Examples:

// ✅ CORRECT - Multi-tenant query (if applicable)
async findPosts(user: User) {
  return this.postsModel.find({
    tenantId: user.tenantId,      // ✅ Multi-tenancy (if applicable)
    isDeleted: false               // ✅ Soft delete (if applicable)
  });
}

// ❌ CRITICAL BUG - No tenant filter (if multi-tenant)
async findPosts() {
  return this.postsModel.find({
    isDeleted: false
  }); // ❌ Data leak! Returns all tenants! (if multi-tenant)
}

// ❌ CRITICAL BUG - No soft delete filter (if using soft delete)
async findPosts(tenantId: string) {
  return this.postsModel.find({
    tenantId
  }); // ❌ Returns deleted items! (if using soft delete)
}

Authentication Review

- [ ] JWT validation in place
- [ ] Token expiration handled
- [ ] Refresh token flow correct
- [ ] No public endpoints (unless intended)
- [ ] Authorization checks before operations
- [ ] Rate limiting implemented

3. Database Operations

Query Review

✅ REQUIRED:
- [ ] [Tenant/organization] filter in ALL queries (if multi-tenant)
- [ ] [isDeleted/deletedAt] filter in ALL queries (if using soft delete)
- [ ] Projections for large documents
- [ ] Indexes exist for query patterns
- [ ] No N+1 query problems
- [ ] Pagination for large result sets

⚠️ PERFORMANCE:
- [ ] Batch operations where possible
- [ ] Aggregation pipelines optimized
- [ ] No unnecessary populate()
- [ ] Lean queries when appropriate

Query Examples:

// ✅ GOOD - Optimized query
async findWithPagination(tenantId: string, page: number, limit: number) {
  return this.model
    .find(
      { tenantId, isDeleted: false },  // Adapt filters to your project
      { _id: 1, title: 1, createdAt: 1 }  // Projection
    )
    .sort({ createdAt: -1 })
    .skip((page - 1) * limit)
    .limit(limit)
    .lean();  // Better performance (if using Mongoose)
}

// ⚠️ WARNING - N+1 problem
async getPosts() {
  const posts = await this.postsModel.find();
  return Promise.all(
    posts.map(post => this.getUserForPost(post.userId))  // N queries!
  );
}

// ✅ BETTER - Single query with populate (if using Mongoose)
async getPosts() {
  return this.postsModel
    .find({ tenantId, isDeleted: false })  // Adapt to your filters
    .populate('userId')  // One query with join
    .lean();
}

Schema Review

✅ REQUIRED:
- [ ] Timestamps enabled (if using ORM that supports it)
- [ ] [isDeleted/deletedAt] field present (if using soft delete)
- [ ] [Tenant/organization] field required (if multi-tenant)
- [ ] Simple indexes in schema/model file
- [ ] Compound indexes defined appropriately

📋 CONVENTIONS:
- [ ] Field naming: camelCase
- [ ] References use string type
- [ ] Required fields marked
- [ ] Default values appropriate
- [ ] Validation rules present

4. Error Handling

✅ REQUIRED:
- [ ] Try/catch blocks present
- [ ] NestJS exceptions used (not generic Error)
- [ ] Errors logged via LoggerService
- [ ] Generic error messages to client
- [ ] Don't expose internal details
- [ ] Re-throw NestJS exceptions (don't convert)

⚠️ COMMON MISTAKES:
- [ ] Not catching async errors
- [ ] Swallowing errors silently
- [ ] Exposing stack traces to client
- [ ] Not logging errors

Error Handling Examples:

// ✅ GOOD
async createPost(data: CreatePostDto, user: User) {
  try {
    const post = await this.postsModel.create({
      ...data,
      tenantId: user.tenantId,  // Adapt to your multi-tenancy approach
      isDeleted: false           // Adapt to your soft delete approach
    });
    return post;
  } catch (error) {
    this.logger.error('Failed to create post', error.stack);
    throw new InternalServerErrorException('Failed to create post');
  }
}

// ❌ BAD - Exposing internals
async createPost(data: CreatePostDto) {
  try {
    return await this.postsModel.create(data);
  } catch (error) {
    throw new Error(error.message);  // ❌ Exposes DB error
  }
}

// ❌ BAD - Converting NestJS exception
async findPost(id: string, org: string) {
  const post = await this.postsModel.findOne({
    _id: id,
    organization: org,
    isDeleted: false
  });

  if (!post) {
    throw new NotFoundException('Post not found');  // ✅ Good
  }

  try {
    return this.processPost(post);
  } catch (error) {
    if (error instanceof NotFoundException) {
      throw new Error('Not found');  // ❌ Don't convert!
    }
    throw error;  // ✅ Re-throw as-is
  }
}

5. Testing Review

✅ REQUIRED (Blocking):
- [ ] Unit tests exist
- [ ] All public methods tested
- [ ] Error cases tested
- [ ] Tests passing
- [ ] Coverage > 70% for new code

⚠️ PREFERRED:
- [ ] Edge cases tested
- [ ] Mock all dependencies
- [ ] Test organization isolation
- [ ] Test soft delete filtering
- [ ] Integration tests for flows

Test Quality Examples:

// ✅ GOOD - Tests isolation (if multi-tenant)
it("should only return posts from user tenant", async () => {
  const tenant1Post = await createPost({ tenantId: "tenant1" });
  const tenant2Post = await createPost({ tenantId: "tenant2" });

  const user = { tenantId: "tenant1" };
  const result = await service.findPosts(user);

  expect(result).toContainEqual(tenant1Post);
  expect(result).not.toContainEqual(tenant2Post);
});

// ✅ GOOD - Tests soft delete
it("should not return deleted posts", async () => {
  const post = await createPost({ isDeleted: true });
  const result = await service.findPosts(user);

  expect(result).not.toContainEqual(post);
});

// ⚠️ WEAK - Not testing the right thing
it("should find posts", async () => {
  const result = await service.findPosts(user);
  expect(result).toBeDefined(); // Too generic
});

6. Performance Review

⚠️ CHECK:
- [ ] No blocking operations in API routes
- [ ] Heavy operations use queues (BullMQ)
- [ ] Database queries optimized
- [ ] Proper use of indexes
- [ ] Caching strategy appropriate
- [ ] Images/assets optimized
- [ ] No memory leaks (cleanup in useEffect)
- [ ] Bundle size impact acceptable

Performance Patterns:

// ✅ GOOD - Async processing (if using queues)
async generatePost(prompt: string, user: User) {
  const job = await this.processingQueue.add('generate', {
    prompt,
    userId: user._id,
    tenantId: user.tenantId  // Adapt to your multi-tenancy approach
  });

  return {
    jobId: job.id,
    status: 'processing'
  };
}

// ❌ BAD - Blocking API
async generatePost(prompt: string) {
  const result = await openai.chat.completions.create({
    model: 'gpt-4',
    messages: [{ role: 'user', content: prompt }]
  }); // ❌ Blocks for 2-4 seconds!

  return result;
}

7. Frontend Specific

✅ REQUIRED:
- [ ] Components organized appropriately (shared vs local)
- [ ] Type/prop interfaces organized consistently
- [ ] Services use appropriate pattern (singleton, factory, etc.)
- [ ] Styling approach consistent ([Tailwind/CSS Modules/etc.])
- [ ] Loading states handled
- [ ] Error states handled
- [ ] Cleanup in useEffect/hooks (no memory leaks)

⚠️ ACCESSIBILITY:
- [ ] Semantic HTML used
- [ ] ARIA labels present
- [ ] Keyboard navigation works
- [ ] Focus management correct
- [ ] Color contrast sufficient

8. API Specific

✅ REQUIRED:
- [ ] Swagger decorators present
- [ ] Proper HTTP status codes
- [ ] DTOs for request/response
- [ ] Validation pipes enabled
- [ ] Rate limiting considered
- [ ] .http file updated (co-located)

📋 HTTP STATUS CODES:
- 200: Success (GET)
- 201: Created (POST)
- 204: No Content (DELETE)
- 400: Bad Request (validation)
- 401: Unauthorized (auth)
- 403: Forbidden (permissions)
- 404: Not Found
- 429: Rate Limit
- 500: Server Error

9. Documentation Review

- [ ] Session file created (`.agents/sessions/YYYY-MM-DD.md`)
- [ ] Flowchart included (for complex features)
- [ ] .agents/memory/ updated (if architectural change)
- [ ] GitHub Issue closed or commented (if applicable)
- [ ] API docs updated (if applicable)
- [ ] Comments for complex logic
- [ ] JSDoc for public APIs

10. Best Practices

- [ ] SOLID principles followed
- [ ] DRY (Don't Repeat Yourself)
- [ ] YAGNI (You Aren't Gonna Need It)
- [ ] Self-documenting code
- [ ] Meaningful variable names
- [ ] Functions < 50 lines
- [ ] Files < 300 lines
- [ ] No premature optimization

Review Commands

Run these before review:

# Check git context
git status
git diff HEAD~1
git log --oneline -5

# Run linter
pnpm lint

# Run tests
pnpm test

# Type check
pnpm type-check

# Build check
pnpm build:all

Critical Blockers

These MUST be fixed before merge:

🚨 SECURITY:
- Missing [tenant/organization] filter in queries (if multi-tenant)
- Missing [isDeleted/deletedAt] filter in queries (if using soft delete)
- Using `any` types
- Exposing sensitive data in errors

🚨 FUNCTIONALITY:
- Tests failing
- Build failing
- Linter errors
- TypeScript errors

🚨 DATA INTEGRITY:
- Cross-tenant data leaks (if multi-tenant)
- Hard deletes (if soft delete pattern expected)
- Missing validation

Approval Criteria

❌ Block Merge

• Security issues present
• No [tenant/organization] filtering (if multi-tenant required)
• No soft delete filtering (if soft delete pattern required)
• any types used
• Tests failing
• Build failing

⚠️ Request Changes

• Coverage < 70%
• Missing documentation
• Performance concerns
• Accessibility issues
• Pattern violations

✅ Approve

• All security checks pass
• Tests passing with good coverage
• Documentation updated
• Follows patterns
• Performance acceptable

AI-Assisted Review

Use this prompt template:

Review this code against project standards:

CONTEXT:
- Current branch: [branch]
- Files changed: [list]
- Purpose: [description]

CRITICAL CHECKS:
1. [Tenant/organization] filtering in ALL queries (if multi-tenant)
2. [isDeleted/deletedAt] filtering in ALL queries (if soft delete)
3. No `any` types
4. [AuthGuard/Middleware] on protected routes
5. Error handling present
6. Tests exist and pass

PATTERN COMPLIANCE:
7. Check .agents/memory/ and codebase examples for patterns
8. Verify [service pattern] usage
9. Check [type organization] location
10. Verify [validation approach]

SECURITY:
11. No cross-tenant data leaks (if multi-tenant)
12. Input validation present
13. Auth checks before operations
14. No sensitive data in responses

PROVIDE:
- ✅ What's good
- ❌ Critical issues (block merge)
- ⚠️ Improvements needed
- 📝 Suggestions
- 🎯 Overall recommendation: Approve / Request Changes / Block

Quick Decision Tree

Are queries filtering by [tenant/organization]? (if multi-tenant)
  NO → ❌ BLOCK MERGE (if required)
  YES → Continue

Are queries filtering [isDeleted/deletedAt]? (if soft delete)
  NO → ❌ BLOCK MERGE (if required)
  YES → Continue

Any `any` types?
  YES → ❌ BLOCK MERGE
  NO → Continue

Tests passing?
  NO → ❌ BLOCK MERGE
  YES → Continue

Build successful?
  NO → ❌ BLOCK MERGE
  YES → Continue

Coverage > 70%?
  NO → ⚠️ REQUEST MORE TESTS
  YES → Continue

Documentation updated?
  NO → ⚠️ REQUEST UPDATE
  YES → ✅ APPROVE

Post-Review Checklist

After approval:

- [ ] PR approved in GitHub
- [ ] CI/CD checks passed
- [ ] Merge conflicts resolved
- [ ] Session file updated
- [ ] TODO.md files updated

---

Created: 2025-11-21 Category: Development Inspired by: claudecodecommands.directory/Code Review Note: Adapt security checks (multi-tenancy, soft delete) to your project's requirements

Deploy - Deployment Workflow Command

Purpose: Streamline deployment workflows for React, Next.js, NestJS applications to various environments (AWS, Vercel, etc.)

When to Use

• Deploying to staging/production
• Setting up deployment pipelines
• Configuring CI/CD workflows
• Managing environment-specific deployments

Project Context Discovery

Before deploying, discover the project's setup:

1. Identify Project Type:

• Scan for package.json to detect framework (React, Next.js, NestJS)
• Check for next.config.js (Next.js)
• Check for nest-cli.json (NestJS)
• Check for vite.config.js or webpack.config.js (React/Vite)

2. Discover Deployment Platform:

• Check for AWS config files (serverless.yml, cloudformation.yml, terraform/)
• Check for Vercel config (vercel.json)
• Check for Docker files (Dockerfile, docker-compose.yml)
• Review .github/workflows/ for CI/CD
• Check environment variables for deployment URLs

3. Identify Build Commands:

• Check package.json scripts for build commands
• Look for build, build:prod, build:staging scripts
• Check for framework-specific build commands

4. Check Environment Configuration:

• Review .env.example or .env.template
• Check for environment-specific configs
• Identify required environment variables

Deployment Workflow

Phase 1: Pre-Deployment Checks

1.1 Code Quality Checks

# Run linter
npm run lint
# or
pnpm lint

# Run type checking
npm run type-check
# or
tsc --noEmit

# Run tests (if not disabled locally)
# Note: Check project rules - some projects run tests only in CI

1.2 Build Verification

# Test build locally
npm run build
# or
pnpm build

# Verify build output exists
ls -la dist/  # NestJS
ls -la .next/  # Next.js
ls -la build/  # React

1.3 Environment Validation

• Verify all required environment variables are set
• Check database connection strings
• Validate API keys and secrets
• Confirm deployment target matches environment

1.4 Security Checks

• Run security audit: npm audit or pnpm audit
• Check for exposed secrets in code
• Verify authentication/authorization configs
• Review dependency vulnerabilities

Phase 2: Deployment Execution

2.1 Framework-Specific Deployment

Next.js (Vercel)

# Deploy to Vercel
vercel --prod  # Production
vercel         # Preview

# Or via GitHub Actions
# Check .github/workflows/deploy.yml

NestJS (AWS/Docker)

# Build Docker image
docker build -t [project-name]:[tag] .

# Push to registry
docker push [registry]/[project-name]:[tag]

# Deploy via AWS ECS/Fargate
# Or use serverless framework
serverless deploy --stage [environment]

React (Static Hosting)

# Build static files
npm run build

# Deploy to S3/CloudFront
aws s3 sync build/ s3://[bucket-name] --delete
aws cloudfront create-invalidation --distribution-id [id] --paths "/*"

2.2 Database Migrations

# Run migrations before deployment
npm run migrate:up
# or
npx prisma migrate deploy  # Prisma
# or custom migration script

2.3 Environment-Specific Config

• Update environment variables in deployment platform
• Configure feature flags
• Set up monitoring and logging
• Configure CDN/caching rules

Phase 3: Post-Deployment Verification

3.1 Health Checks

# Check deployment health
curl https://[deployment-url]/health
curl https://[deployment-url]/api/health

# Verify API endpoints
curl https://[deployment-url]/api/v1/status

3.2 Smoke Tests

• Test critical user flows
• Verify API endpoints respond
• Check database connectivity
• Validate authentication flow

3.3 Monitoring

• Check deployment logs
• Monitor error rates
• Verify metrics collection
• Check alert configurations

Environment-Specific Workflows

Staging Deployment

/deploy staging

Process:

1. Build with staging config 2. Deploy to staging environment 3. Run smoke tests 4. Notify team of deployment

Production Deployment

/deploy production

Process:

1. Require confirmation - Production deployments are critical 2. Create deployment branch/tag 3. Run full test suite (in CI) 4. Build production bundle 5. Deploy with zero-downtime strategy 6. Run health checks 7. Monitor for issues 8. Rollback plan ready

AWS-Specific Patterns

ECS/Fargate Deployment

# Update task definition
aws ecs update-service \
  --cluster [cluster-name] \
  --service [service-name] \
  --force-new-deployment

# Monitor deployment
aws ecs describe-services \
  --cluster [cluster-name] \
  --services [service-name]

Lambda Deployment

# Deploy serverless function
serverless deploy --stage [environment]

# Or AWS SAM
sam build
sam deploy --guided

S3/CloudFront Static Deployment

# Build and sync
npm run build
aws s3 sync build/ s3://[bucket] --delete --cache-control "max-age=31536000"

# Invalidate CloudFront
aws cloudfront create-invalidation \
  --distribution-id [id] \
  --paths "/*"

MongoDB Considerations

Before deployment:

1. Database Migrations:

   # Run migrations
   npm run migrate:up
   
   # Or use migration tool
   npx migrate-mongo up

2. Connection String:

• Verify MongoDB connection string for environment
• Check replica set configuration
• Verify network access (VPC, security groups)

3. Index Verification:

• Ensure indexes are created
• Check index performance
• Verify compound indexes

Rollback Procedures

If deployment fails:

1. Identify Issue:

• Check deployment logs
• Review error messages
• Check health endpoints

2. Rollback Strategy:

Docker/ECS:

   # Revert to previous task definition
   aws ecs update-service \
     --cluster [cluster] \
     --service [service] \
     --task-definition [previous-version]

Vercel:

   # Revert to previous deployment
   vercel rollback

Database:

   # Rollback migrations if needed
   npm run migrate:down

3. Post-Rollback:

• Verify rollback successful
• Check application health
• Document issue for investigation

Safety Features

Always include:

1. Confirmation for Production:

   ⚠️  WARNING: Deploying to PRODUCTION
   
   Current version: v1.2.3
   New version: v1.2.4
   
   Changes:
   - Feature X
   - Bug fix Y
   
   Continue? (y/n)

2. Pre-Deployment Checklist:

• [ ] All tests passing
• [ ] Build successful
• [ ] Environment variables configured
• [ ] Database migrations ready
• [ ] Rollback plan prepared
• [ ] Team notified

3. Deployment Monitoring:

• Watch deployment logs
• Monitor error rates
• Check performance metrics
• Verify functionality

Common Deployment Patterns

Blue-Green Deployment

# Deploy new version alongside old
# Switch traffic when verified
# Keep old version for quick rollback

Canary Deployment

# Deploy to small percentage of traffic
# Monitor metrics
# Gradually increase if healthy
# Rollback if issues detected

Rolling Deployment

# Update instances one at a time
# Maintain service availability
# Monitor each instance

Integration with CI/CD

Discover CI/CD setup:

1. Check GitHub Actions:

   ls .github/workflows/

2. Review Pipeline:

• Build steps
• Test steps
• Deployment steps
• Environment configuration

3. Deploy via CI/CD:

   # Trigger deployment workflow
   gh workflow run deploy.yml \
     --ref main \
     -f environment=production

Error Handling

Common Issues:

1. Build Failures:

• Check build logs
• Verify dependencies
• Check environment variables
• Review TypeScript errors

2. Deployment Timeouts:

• Check network connectivity
• Verify deployment platform status
• Review resource limits
• Check deployment logs

3. Database Connection Issues:

• Verify connection strings
• Check network access
• Review security groups
• Test connection manually

Best Practices

1. Always test builds locally before deploying 2. Use feature flags for gradual rollouts 3. Monitor deployments closely 4. Have rollback plan ready 5. Document deployment process in project docs 6. Automate repetitive steps via CI/CD 7. Version deployments for tracking 8. Notify team of deployments

Output Format

When deploying, show:

🚀 DEPLOYMENT STARTED

Environment: [environment]
Project: [project-name]
Version: [version]
Platform: [platform]

📋 PRE-DEPLOYMENT CHECKS
✅ Linter passed
✅ Type check passed
✅ Build successful
✅ Environment variables configured
✅ Database migrations ready

🔄 DEPLOYING...
[Progress indicators]

✅ DEPLOYMENT COMPLETE

URL: https://[deployment-url]
Health: https://[deployment-url]/health

📊 MONITORING
- Error rate: 0.01%
- Response time: 120ms
- Status: Healthy

💡 NEXT STEPS
1. Run smoke tests
2. Monitor for 15 minutes
3. Verify critical flows

---

Created: 2025-12-24 Purpose: Streamline deployment workflows across React, Next.js, NestJS projects Platforms: AWS, Vercel, Docker, Static Hosting

End - Document Session Before Clearing

⚠️ CRITICAL: This command documents your session but does NOT clear the context.

What This Command Does

1. Activates the `session-documenter` skill to save a redacted session summary to .agents/sessions/YYYY-MM-DD.md 2. Tells you to manually run `/clear` (Claude Code's built-in command) to clear the context

Note: /end only documents. You must manually run /clear (built-in) after /end completes to actually clear the conversation context.

Workflow

Step 1: Document Session Immediately

When user types /end, you MUST:

1. Activate session-documenter skill:

   Use the Skill tool to activate session-documenter

2. Let it complete - The skill will:

• Document all tasks completed
• Save decisions made with rationale
• Record files created/modified/deleted
• Note patterns established
• Track mistakes and fixes
• Write everything to .agents/sessions/YYYY-MM-DD.md

3. Confirm documentation saved:

   ✅ Session documented to .agents/sessions/YYYY-MM-DD.md

Step 2: Remind User to Clear Manually

After documentation is complete, tell the user:

✅ Session documented successfully!

📋 NEXT STEP:
Run /clear (Claude Code's built-in command) to clear the conversation context.
Your session is safely preserved in .agents/sessions/YYYY-MM-DD.md

Next time you run /start, it will load this documented session.

IMPORTANT: Tell the user to manually run /clear after /end completes. The /end command does NOT clear context automatically.

Why This Matters

WITHOUT documentation before /clear:

• All context is lost forever
• Next /start has no idea what was done
• You repeat work or make conflicting changes
• User gets frustrated

WITH documentation before /clear:

• Context preserved in .agents/sessions/YYYY-MM-DD.md
• Next /start reads the session file
• Continuity maintained across clear boundaries
• User can pick up exactly where they left off

User Experience

User types: /end

AI responds:

🔄 Documenting session...

[session-documenter skill activates]

✅ Session documented to .agents/sessions/2025-11-23.md

Session saved with:
- 3 tasks completed
- 5 files changed
- 2 key decisions documented

📋 NEXT STEP: Run /clear to clear the conversation context.
Your session is safely preserved and will be loaded when you run /start again.

Then: User manually types /clear to clear the conversation context using Claude Code's built-in command

Next session: User runs /start → reads .agents/sessions/2025-11-23.md → knows everything that was done

How This Works

Technical details:

1. Custom /end command (this file) triggers when user types /end 2. AI executes session documentation via session-documenter skill 3. Session data is saved to .agents/sessions/YYYY-MM-DD.md 4. AI tells user to manually run /clear (Claude Code's built-in command) 5. User runs /clear to clear conversation context

This is a TWO-STEP process:

• /end = document session
• /clear = clear context (built-in Claude Code command)

Important Notes

• ONE FILE PER DAY: Session documenter appends to .agents/sessions/YYYY-MM-DD.md
• Multiple /ends: Each /end adds a new session to the same day's file
• Automatic documentation: Session documenter skill handles everything
• Manual clear required: User must run /clear after /end to clear context
• Best practice: Always run /end before /clear to preserve session history

Related Commands

• /start - Loads preferences and today's session file after clearing
• /docs-update - Manual session documentation (fallback if skill fails)

---

Troubleshooting

If context doesn't clear after running /clear:

1. Make sure you're using the built-in /clear command (not a custom command) 2. Try restarting Claude Code CLI if /clear doesn't work 3. Verify you're using Claude Code CLI (not a different tool)

If you want to clear WITHOUT documentation:

Simply run /clear directly without running /end first.

WARNING: Clearing without documentation means you lose unsaved session context. Best practice is to ALWAYS run /end before /clear.

---

Created: 2025-11-21 Updated: 2025-11-23 Purpose: Document session before clearing context manually with /clear

Workflow Summary

/start               → Load preferences and session history
  ↓
[work on tasks]      → Make changes, complete tasks
  ↓
/end                 → Document session to .agents/sessions/YYYY-MM-DD.md
  ↓
/clear               → Clear conversation context (built-in command)
  ↓
/start               → Begin new session with documented history

memory/

Purpose: Source of truth for durable project context.

Each file covers one topic. AI agents read this directory before starting work.

Conventions

• One file per topic: architecture.md, deployment.md, entities.md, migrations.md, etc.
• Every file must carry: last_verified: YYYY-MM-DD in the front matter or as a trailing line.
• Transient facts (e.g., in-progress migration notes) add status: temporary — verify before citing if the date is >30 days old.

What Goes Here

Durable facts that are NOT rules:

• Architecture decisions and current shape of the system
• Deployment steps, environments, and gotchas
• Data entities and their relationships
• Migration plans and current status
• Known gotchas and non-obvious constraints

What Does NOT Go Here

• Coding standards and "never do" rules → CLAUDE.md (repo root or ~/.claude/CLAUDE.md)
• Task tracking → GitHub Issues (gh issue list, gh issue create)
• Session logs → .agents/sessions/YYYY-MM-DD.md

---

Last Updated: {{DATE}}

Sessions: YYYY-MM-DD

Summary: Brief 3-5 word summary

---

Session 1: Brief Description

Duration: ~X hours Status: Complete / In Progress

What was done

• Task 1
• Task 2

Files changed

• path/to/file.ts - what changed

Decisions

• Decision: What was decided
• Context: Why this was needed
• Rationale: Why this choice

Mistakes and fixes

• Mistake: What went wrong
• Fix: How resolved
• Prevention: How to avoid

Next steps

• [ ] Next task 1
• [ ] Next task 2

---

Total sessions today: 1