Claude Code Agent System - Setup Complete

This document summarizes the Claude Code agent system setup for StemBlock AI.

What Was Created

1. Project Configuration

File: CLAUDE.md (project root)

• Project overview and context
• Technology stack (Next.js 14, NestJS, React 19, TypeScript)
• Agent system overview
• Development workflow guide
• Core development principles
• Documentation references

2. Agent System

Directory: .claude/agents/

Seven specialized agents were created:

Agent	File	Purpose
Plan	plan.md	Creates implementation plans and specifications
Architecture Review	architecture-review.md	Reviews plans for technical soundness
Frontend Dev	frontend-dev.md	Implements Next.js/React components
Backend Dev	backend-dev.md	Implements NestJS APIs and services
Testing	testing.md	Generates comprehensive tests
Troubleshoot	troubleshoot.md	Debugs issues and root cause analysis
Marketing Research	marketing-research.md	Market research and feature planning

3. Slash Commands

Directory: .claude/commands/

Created /new_feature command that orchestrates the full feature development workflow:

1. Plan creation
2. Architecture review
3. Implementation (backend + frontend)
4. Testing

4. Documentation Structure

Directory: stemblockai-docs/plan/

• plan/ - Implementation plan files
• plan/reviews/ - Architecture review files
• plan/test-reports/ - Test coverage reports

How to Use

For New Features

# In Claude Code CLI
/new_feature Add CSV export for student grades

Or manually:

Use the Task tool to invoke the plan agent to create implementation plan for [feature]
Use the Task tool to invoke the architecture review agent to review the plan
Use the Task tool to invoke the backend dev agent to implement [feature]
Use the Task tool to invoke the frontend dev agent to implement [feature]
Use the Task tool to invoke the testing agent to generate tests

For Bug Fixes

Use the Task tool to invoke the [backend-dev|frontend-dev] agent to fix [bug description]

For Code Reviews

Use the Task tool to invoke the architecture review agent to review [plan file]

Key Features

Agent Specialization

Each agent has a specific role and expertise:

• Plan Agent: Research, design, specification
• Architecture Review: Validation, security, consistency
• Frontend Dev: React 19/Next.js 14 implementation
• Backend Dev: NestJS API implementation
• Testing: Test generation and coverage verification
• Troubleshoot: Root cause analysis and debugging
• Marketing Research: Market analysis and feature validation

No SQLite Dependency

Unlike Cursor-based systems, this Claude Code implementation:

• ✅ Uses file-based documentation (stemblockai-docs/plan/)
• ✅ No MCP server requirements
• ✅ Simple file structure
• ✅ Easy to track in git

Context Awareness

Agents are aware of:

• StemBlock AI's purpose (AI-powered STEM education)
• Multi-role system (Students, Coaches, Parents, Admins)
• Tech stack (Next.js 14, React 19, NestJS, TypeORM, PostgreSQL)
• Existing codebase structure
• Documentation location

Core Principles Enforced

Frontend

• ❌ No useEffect (except for external systems)
• ✅ Conditional modal rendering (unmount when closed)
• ✅ Tailwind CSS only (no inline styles)
• ✅ React Query for server state
• ✅ React 19 patterns (ref as prop)
• ✅ TypeScript strict mode

Backend

• ✅ TypeORM repositories (no raw SQL)
• ✅ DTO validation with class-validator
• ✅ Standard API envelope: \{ data: T, meta: \{\} \}
• ✅ Role-based access control
• ✅ Dependency injection
• ✅ Comprehensive error handling

Testing

• ✅ Backend: ≥ 80% coverage
• ✅ Frontend: ≥ 70% coverage
• ✅ Test behavior, not implementation
• ✅ Role-based permission tests
• ✅ Integration and E2E tests

Documentation

All project documentation is in stemblockai-docs/:

• CODEBASE_OVERVIEW.md - System structure and features
• ROUTING_AND_NAVIGATION.md - Navigation patterns
• API_ENDPOINTS_SUMMARY.md - API reference
• plan/ - Implementation plans and reviews

File Structure

.
├── CLAUDE.md                          # Project-level configuration
├── .claude/
│   ├── README.md                      # Agent system guide
│   ├── agents/
│   │   ├── plan.md
│   │   ├── architecture-review.md
│   │   ├── frontend-dev.md
│   │   ├── backend-dev.md
│   │   ├── testing.md
│   │   ├── troubleshoot.md
│   │   └── marketing-research.md
│   └── commands/
│       └── new-feature.md
├── stemblockai-frontend/              # Next.js 14 + React 19 frontend
├── stemblockai-backend/               # NestJS backend
└── stemblockai-docs/                  # Documentation
    ├── CODEBASE_OVERVIEW.md
    ├── API_ENDPOINTS_SUMMARY.md
    ├── ROUTING_AND_NAVIGATION.md
    ├── CLAUDE-CODE-SETUP.md          # This file
    ├── plan/
    │   ├── README.md
    │   ├── reviews/
    │   └── test-reports/
    ├── research/                      # Market research reports
    └── troubleshooting/               # Debug reports

Next Steps

1. Try it out: Use /new_feature command for a new feature
2. Review agents: Familiarize yourself with each agent's capabilities
3. Customize: Modify agent prompts as needed for your workflow
4. Document: Update stemblockai-docs/ as the codebase evolves

Differences from Cursor System

Feature	Cursor	Claude Code
Agent invocation	@agent-name.mdc	Task tool with agent prompt
Memory/State	SQLite MCP	File-based (stemblockai-docs/plan/)
Handoffs	SQLite database	Plan documents
Corrections	SQLite feedback table	N/A (not needed)
Packs	.mdc files	Embedded in agent prompts
Commands	@command.md	Slash commands

Benefits

1. No infrastructure dependencies: No MCP servers needed
2. Git-friendly: All plans and reviews are markdown files
3. Transparent: Easy to see what agents are doing
4. Portable: Works anywhere Claude Code runs
5. Customizable: Easy to modify agent behavior
6. Maintainable: Simple file structure

Support

• Agent documentation: .claude/README.md
• Project overview: CLAUDE.md
• Codebase structure: stemblockai-docs/CODEBASE_OVERVIEW.md
• API reference: stemblockai-docs/API_ENDPOINTS_SUMMARY.md

---

Created: 2025-12-13 Ready for use: Yes ✅

Start using the agent system with /new_feature or by invoking agents directly via the Task tool!