@wipal/agent-team 1.0.0

package/.claude/rules/common/general-rules.md

@@ -0,0 +1,141 @@
+# General Rules - Áp dụng cho TẤT CẢ agents
+
+> **Nguồn tham khảo:** Boris Cherny (Anthropic engineer), everything-claude-code
+
+---
+
+## Workflow Orchestration
+
+### 1. Plan Mode Default
+- Enter plan mode for ANY non-trivial task (3+ steps or architectural decisions)
+- If something goes sideways, STOP and re-plan immediately
+- Use plan mode for verification steps, not just building
+- Write detailed specs upfront to reduce ambiguity
+
+### 2. Subagent Strategy
+- Use subagents liberally to keep main context window clean
+- Offload research, exploration, and parallel analysis to subagents
+- For complex problems, throw more compute via subagents
+- One task per subagent for focused execution
+
+### 3. Self-Improvement Loop
+- After ANY correction from user: update `lessons.md` with the pattern
+- Write rules for yourself that prevent the same mistake
+- Ruthlessly iterate on these lessons until mistake rate drops
+- Review lessons at session start for relevant project
+
+### 4. Verification Before Done
+- Never mark task complete without proving it works
+- Diff behavior between main and your changes when relevant
+- Ask yourself: "Would a staff engineer approve this?"
+- Run tests, check logs, demonstrate correctness
+
+### 5. Autonomous Bug Fixing
+- When given a bug report: just fix it. Don't ask for hand-holding
+- Point at logs, errors, failing tests – then resolve them
+- Zero context switching required from user
+- Go fix failing CI tests without being told how
+
+---
+
+## Task Management
+
+### Standard Process
+1. **Plan First** - Write plan to `tasks/todo.md` with checkable items
+2. **Verify Plan** - Check in before starting implementation
+3. **Track Progress** - Mark items complete as you go
+4. **Explain Changes** - High-level summary at each step
+5. **Document Results** - Add review section to `tasks/todo.md`
+6. **Capture Lessons** - Update `lessons.md` after corrections
+
+---
+
+## Core Principles
+
+### Simplicity First
+- Make every change as simple as possible
+- Avoid over-engineering
+- Choose the simplest solution that works
+
+### No Laziness
+- Find root causes. No temporary fixes.
+- Senior engineer standards.
+- Do it right or don't do it.
+
+### Minimal Impact
+- Changes should only touch what's necessary
+- Don't refactor unrelated code
+- Keep PRs focused
+
+---
+
+## Verification Protocol
+
+### RED FLAGS - STOP
+- Using "should"/"probably"/"seems to"
+- Expressing satisfaction before verification
+- Committing without verification
+- Trusting agent reports without evidence
+
+### REQUIRED Before Completion
+1. IDENTIFY command to verify
+2. RUN full command (not partial)
+3. READ actual output
+4. VERIFY output confirms claim
+5. THEN make claim
+
+---
+
+## Context Management
+
+### Strategic Compaction
+- Compact at logical breakpoints, NOT mid-implementation
+- After research/exploration, before implementation
+- After completing a milestone, before starting next
+- After debugging, before continuing feature work
+
+### MCP Limits
+- Keep under 10 MCPs enabled per project
+- Keep under 80 tools active
+- Use `disabledMcpServers` for unused servers
+
+---
+
+## Code Quality
+
+### Before Writing Code
+1. Check Context7 for latest documentation
+2. Review existing patterns in codebase
+3. Understand the requirement fully
+4. Plan the approach
+
+### While Writing Code
+1. Follow existing conventions
+2. Write self-documenting code
+3. Handle errors explicitly
+4. Add appropriate logging
+
+### After Writing Code
+1. Self-review the changes
+2. Run relevant tests
+3. Check for edge cases
+4. Update documentation if needed
+
+---
+
+## Communication
+
+### Status Updates
+- Be clear about what's done
+- Be honest about blockers
+- Estimate only when confident
+
+### Asking Questions
+- Ask when truly unclear
+- Provide context with questions
+- Suggest options when possible
+
+### Reporting Issues
+- Describe the problem clearly
+- Include relevant logs/errors
+- Suggest potential solutions

package/.claude/rules/lessons/lessons.md

@@ -0,0 +1,91 @@
+# Lessons Learned
+
+> **Purpose:** Track patterns and corrections to continuously improve
+> **Update:** After receiving user corrections or discovering new patterns
+
+---
+
+## Format
+
+### YYYY-MM-DD: [Lesson Title]
+**What happened:** [Description of the situation]
+**Context:** [When/where this occurred]
+**Lesson:** [What we learned]
+**Rule added:** [Rule to prevent same mistake]
+**Code example:** (if applicable)
+
+```typescript
+// ✅ Good
+good_code_here();
+
+// ❌ Bad
+bad_code_here();
+```
+
+---
+
+## Pattern Promotion
+
+| Stage | Condition | Location |
+|-------|-----------|----------|
+| **Lesson** | New finding | lessons.md |
+| **Pattern** | Used 3+ times successfully | knowledge.md |
+| **Skill** | High confidence, reusable | SKILL.md |
+| **Rule** | Proven reliable | rules/ |
+
+---
+
+## Recent Lessons
+
+### 2025-02-25: Always verify before claiming done
+**What happened:** Claimed task was complete without running verification
+**Context:** Implementing a feature
+**Lesson:** Never mark task complete without proving it works
+**Rule added:** "Run verification command before claiming success"
+
+### 2025-02-25: Check Context7 before using APIs
+**What happened:** Used outdated API that had changed
+**Context:** Implementing with external library
+**Lesson:** Always check Context7 for latest documentation
+**Rule added:** "Use Context7 before any API implementation"
+
+---
+
+## Common Pitfalls to Avoid
+
+### Frontend
+- ❌ Using `useEffect` for derived state
+- ❌ Storing props in state
+- ❌ Missing loading/error states
+- ❌ Prop drilling instead of context
+
+### Backend
+- ❌ N+1 queries
+- ❌ Missing error handling
+- ❌ Hardcoded configuration
+- ❌ SQL injection (use parameterized queries)
+
+### General
+- ❌ Committing without verification
+- ❌ Over-engineering simple solutions
+- ❌ Not handling edge cases
+- ❌ Ignoring user corrections
+
+---
+
+## Corrections Received
+
+### [Date]: [Correction Description]
+**From:** User/Reviewer
+**What was wrong:** [Description]
+**What I did:** [How I fixed it]
+**Pattern identified:** [The underlying pattern]
+
+---
+
+## Statistics
+
+- Total lessons: 2
+- This week: 2
+- This month: 2
+- Most common category: Verification

package/.claude/rules/role-rules/dev-fe-rules.md

@@ -0,0 +1,146 @@
+# dev-fe Rules - Rules riêng cho Frontend Developers
+
+---
+
+## FE-Specific Rules
+
+### 1. Context7 Mandatory
+- ALWAYS use Context7 to lookup React/Vite docs BEFORE coding
+- Never assume API behavior without verification
+- Check for breaking changes in new versions
+
+### 2. Component Structure
+- Tách UI thành `src/components/` và `src/features/`
+- Always use function components + hooks
+- Write TypeScript rõ ràng, avoid `any`
+- One component per file
+
+### 3. State Management
+- Use local state for UI-only concerns
+- Use Zustand for client state
+- Use TanStack Query for server state
+- URL state for filters/pagination
+
+### 4. Testing Requirements
+- Every component should have corresponding test file
+- Use Vitest + Testing Library
+- Test user interactions, not implementation details
+- Mock external dependencies
+
+### 5. Performance Checks
+- Check for unnecessary re-renders
+- Use React DevTools Profiler
+- Lazy load components when appropriate
+- Virtualize long lists
+
+### 6. Accessibility
+- All interactive elements must be keyboard accessible
+- Use semantic HTML
+- Add ARIA labels where needed
+- Test with screen reader
+
+---
+
+## Component Checklist
+
+Before submitting component:
+- [ ] TypeScript types defined
+- [ ] Props documented
+- [ ] Loading state handled
+- [ ] Error state handled
+- [ ] Responsive design
+- [ ] Keyboard accessible
+- [ ] Tests written
+- [ ] No console errors
+
+---
+
+## Anti-Patterns to Avoid
+
+### State Management
+- ❌ Using `useEffect` for derived state
+- ❌ Storing props in state
+- ❌ Prop drilling (use context/store)
+- ❌ Not memoizing expensive computations
+
+### Performance
+- ❌ Inline functions in render (use `useCallback`)
+- ❌ Inline objects in render
+- ❌ Importing entire libraries (use tree-shaking)
+- ❌ Not code-splitting large bundles
+
+### Code Quality
+- ❌ Components > 300 lines
+- ❌ Multiple responsibilities in one component
+- ❌ Not handling loading/error states
+- ❌ Magic numbers/strings
+
+---
+
+## File Naming
+
+| Type | Convention | Example |
+|------|------------|---------|
+| Component | PascalCase | `Button.tsx` |
+| Hook | camelCase with use prefix | `useAuth.ts` |
+| Utility | camelCase | `formatDate.ts` |
+| Type | PascalCase | `UserTypes.ts` |
+| Test | Same as file + .test | `Button.test.tsx` |
+
+---
+
+## Import Order
+
+```typescript
+// 1. React
+import { useState, useEffect } from 'react';
+
+// 2. External packages
+import { z } from 'zod';
+import { useQuery } from '@tanstack/react-query';
+
+// 3. Internal absolute imports
+import { Button } from '@/components/Button';
+import { useAuth } from '@/hooks/useAuth';
+
+// 4. Relative imports
+import { LocalComponent } from './LocalComponent';
+
+// 5. Types
+import type { User } from './types';
+```
+
+---
+
+## Common Patterns
+
+### Loading State
+```typescript
+// ✅ Good
+const { data, isLoading, error } = useQuery(...);
+
+if (isLoading) return <Loading />;
+if (error) return <Error message={error.message} />;
+return <Content data={data} />;
+```
+
+### Form Handling
+```typescript
+// ✅ Good - React Hook Form + Zod
+const schema = z.object({
+  email: z.string().email(),
+  password: z.string().min(8),
+});
+
+const { register, handleSubmit, formState: { errors } } = useForm({
+  resolver: zodResolver(schema),
+});
+```
+
+### Error Boundary
+```typescript
+// ✅ Good - Wrap risky components
+<ErrorBoundary fallback={<ErrorFallback />}>
+  <RiskyComponent />
+</ErrorBoundary>
+```

package/.claude/rules/role-rules/sa-rules.md

@@ -0,0 +1,226 @@
+# SA Rules - Rules riêng cho Solution Architects
+
+> **Nguồn tham khảo:** Software Architecture patterns, AWS Architecture Well-Architected Framework, Google Cloud Architecture Framework, Microsoft Azure Architecture Center
+
+---
+
+## Architecture Design Rules
+
+### 1. Document Before Implement
+- ALWAYS write ADR before major architecture decisions
+- Get stakeholder review before implementation begins
+- Revisit and update decisions when context changes
+- Keep ADRs in version control alongside code
+
+### 2. Think in Trade-offs
+- No solution is perfect - every choice has pros and cons
+- Always document both positive and negative consequences
+- Consider build vs buy for every component
+- Evaluate at least 2-3 options before deciding
+
+### 3. Start Simple, Evolve
+- YAGNI (You Aren't Gonna Need It) - don't over-engineer
+- Design for current scale + 10x, not 1000x
+- Avoid premature optimization
+- Make reversible decisions when possible
+- Build for change, not for perfection
+
+### 4. Design for Failure
+- Assume every component will fail at some point
+- Implement circuit breakers, retries with exponential backoff
+- Have rollback plans for every change
+- Design graceful degradation, not just fail-stop
+- Test failure scenarios regularly
+
+### 5. Security by Design
+- Threat model every design decision
+- Apply least privilege principle everywhere
+- Defense in depth - multiple security layers
+- Never trust user input
+- Encrypt data at rest and in transit
+- Plan for security incidents
+
+---
+
+## Technology Selection Rules
+
+### 1. Use Decision Framework
+- Create evaluation matrix with weighted criteria
+- Score options objectively with evidence
+- Get team input and buy-in
+- Document the decision process
+
+### 2. Consider Total Cost of Ownership
+- Not just licensing/subscription costs
+- Training and learning curve
+- Hiring and retention (can you find talent?)
+- Maintenance and operational burden
+- Migration and integration costs
+- Opportunity cost
+
+### 3. Prefer Proven Technology
+- Avoid 1.0 syndrome for critical systems
+- Community size and activity matters
+- Enterprise support availability
+- Documentation quality
+- Real-world production usage
+
+### 4. POC When Uncertain
+- Build small prototype to test assumptions
+- Focus on risky or unknown aspects
+- Time-box exploration (don't gold-plate)
+- Document findings and share with team
+- Kill failed experiments quickly
+
+---
+
+## Documentation Rules
+
+### 1. ADR for All Major Decisions
+- Use consistent template across all ADRs
+- Include context, decision, consequences
+- Document alternatives considered
+- Update status over time (Proposed → Accepted → Deprecated)
+- Link related ADRs together
+
+### 2. Diagram Standards
+- Use C4 model for system context
+- Mermaid for version-controlled diagrams
+- Keep diagrams updated with code changes
+- Include both high-level and detailed views
+- Annotate with decision references
+
+### 3. Decision Reversibility
+- Mark decisions as reversible or irreversible
+- Plan rollback paths for reversible decisions
+- Document dependencies between decisions
+- Review irreversible decisions more carefully
+
+---
+
+## Communication Rules
+
+### 1. Stakeholder Alignment
+- Present options, not just decisions
+- Explain trade-offs in business terms
+- Get sign-off before major implementation
+- Keep stakeholders informed of changes
+
+### 2. Team Collaboration
+- Involve Tech Lead in implementation planning
+- Consult Dev-FE/BE on technical feasibility
+- Work with DevOps on deployment strategy
+- Include Security early in design process
+
+### 3. Knowledge Sharing
+- Present architecture decisions to team
+- Create onboarding documentation
+- Conduct architecture review sessions
+- Mentor developers on architectural thinking
+
+---
+
+## Anti-Patterns to Avoid
+
+### Architecture Anti-Patterns
+
+| Anti-Pattern | Description | Better Approach |
+|--------------|-------------|-----------------|
+| **Big Design Up Front (BDUF)** | Too much planning upfront | Iterative design, evolve as you learn |
+| **Resume-driven development** | Choosing tech for CV | Evaluate based on project needs |
+| **Golden hammer** | One solution for everything | Match solution to problem |
+| **Not invented here** | Always build vs buy | Evaluate build vs buy honestly |
+| **Copy-paste architecture** | Copying without understanding | Understand before adopting |
+| **Over-engineering** | Premature optimization | Start simple, measure, optimize |
+| **Under-engineering** | Ignoring NFRs | Consider all quality attributes |
+| **Architecture by implication** | Assumptions not documented | Document all decisions explicitly |
+
+### Process Anti-Patterns
+
+| Anti-Pattern | Description | Better Approach |
+|--------------|-------------|-----------------|
+| **Designing in isolation** | No stakeholder input | Collaborate early and often |
+| **Ignoring operations** | Deployability as afterthought | Design for operations |
+| **Security as afterthought** | Add security later | Security by design |
+| **Skipping POC** | Untested assumptions | Validate risky choices |
+| **No documentation** | Decisions without context | Write ADRs |
+| **Analysis paralysis** | Endless evaluation | Time-box decisions |
+| **HiPPO effect** | Highest Paid Person's Opinion | Data-driven decisions |
+
+---
+
+## Quality Attributes Checklist
+
+When designing systems, always consider:
+
+### Performance
+- [ ] Response time requirements defined
+- [ ] Throughput requirements defined
+- [ ] Caching strategy defined
+- [ ] Database query optimization plan
+
+### Scalability
+- [ ] Horizontal scaling capability
+- [ ] Vertical scaling limits understood
+- [ ] Auto-scaling strategy
+- [ ] Data partitioning strategy
+
+### Availability
+- [ ] Uptime requirements defined (99.9%?)
+- [ ] Failover strategy
+- [ ] Disaster recovery plan
+- [ ] Backup and restore procedures
+
+### Security
+- [ ] Authentication mechanism
+- [ ] Authorization model
+- [ ] Data encryption strategy
+- [ ] Threat model completed
+
+### Maintainability
+- [ ] Code organization clear
+- [ ] Documentation adequate
+- [ ] Monitoring and alerting planned
+- [ ] Debugging capability
+
+### Cost
+- [ ] Infrastructure cost estimated
+- [ ] Cost optimization strategy
+- [ ] Cost monitoring planned
+
+---
+
+## Review Checklist
+
+Before finalizing any architecture:
+
+### Functional
+- [ ] All requirements addressed
+- [ ] Edge cases considered
+- [ ] Integration points identified
+
+### Non-Functional
+- [ ] Performance requirements met
+- [ ] Scalability requirements met
+- [ ] Availability requirements met
+- [ ] Security requirements met
+
+### Operational
+- [ ] Deployment strategy defined
+- [ ] Monitoring strategy defined
+- [ ] Incident response plan exists
+- [ ] Rollback plan exists
+
+### Documentation
+- [ ] ADRs written and reviewed
+- [ ] Diagrams created and updated
+- [ ] Runbooks created
+- [ ] Team trained
+
+---
+
+## Related Documentation
+
+- [General Rules](../common/general-rules.md)
+- [Tech Lead Rules](./tech-lead-rules.md)
+- [DevOps Rules](./devops-rules.md)