ac-framework 1.5.0 → 1.7.0

package/framework/.antigravity/skills/api-design-principles/references/rest-best-practices.md

@@ -0,0 +1,408 @@
+# REST API Best Practices
+
+## URL Structure
+
+### Resource Naming
+
+```
+# Good - Plural nouns
+GET /api/users
+GET /api/orders
+GET /api/products
+
+# Bad - Verbs or mixed conventions
+GET /api/getUser
+GET /api/user  (inconsistent singular)
+POST /api/createOrder
+```
+
+### Nested Resources
+
+```
+# Shallow nesting (preferred)
+GET /api/users/{id}/orders
+GET /api/orders/{id}
+
+# Deep nesting (avoid)
+GET /api/users/{id}/orders/{orderId}/items/{itemId}/reviews
+# Better:
+GET /api/order-items/{id}/reviews
+```
+
+## HTTP Methods and Status Codes
+
+### GET - Retrieve Resources
+
+```
+GET /api/users              → 200 OK (with list)
+GET /api/users/{id}         → 200 OK or 404 Not Found
+GET /api/users?page=2       → 200 OK (paginated)
+```
+
+### POST - Create Resources
+
+```
+POST /api/users
+  Body: {"name": "John", "email": "john@example.com"}
+  → 201 Created
+  Location: /api/users/123
+  Body: {"id": "123", "name": "John", ...}
+
+POST /api/users (validation error)
+  → 422 Unprocessable Entity
+  Body: {"errors": [...]}
+```
+
+### PUT - Replace Resources
+
+```
+PUT /api/users/{id}
+  Body: {complete user object}
+  → 200 OK (updated)
+  → 404 Not Found (doesn't exist)
+
+# Must include ALL fields
+```
+
+### PATCH - Partial Update
+
+```
+PATCH /api/users/{id}
+  Body: {"name": "Jane"}  (only changed fields)
+  → 200 OK
+  → 404 Not Found
+```
+
+### DELETE - Remove Resources
+
+```
+DELETE /api/users/{id}
+  → 204 No Content (deleted)
+  → 404 Not Found
+  → 409 Conflict (can't delete due to references)
+```
+
+## Filtering, Sorting, and Searching
+
+### Query Parameters
+
+```
+# Filtering
+GET /api/users?status=active
+GET /api/users?role=admin&status=active
+
+# Sorting
+GET /api/users?sort=created_at
+GET /api/users?sort=-created_at  (descending)
+GET /api/users?sort=name,created_at
+
+# Searching
+GET /api/users?search=john
+GET /api/users?q=john
+
+# Field selection (sparse fieldsets)
+GET /api/users?fields=id,name,email
+```
+
+## Pagination Patterns
+
+### Offset-Based Pagination
+
+```python
+GET /api/users?page=2&page_size=20
+
+Response:
+{
+  "items": [...],
+  "page": 2,
+  "page_size": 20,
+  "total": 150,
+  "pages": 8
+}
+```
+
+### Cursor-Based Pagination (for large datasets)
+
+```python
+GET /api/users?limit=20&cursor=eyJpZCI6MTIzfQ
+
+Response:
+{
+  "items": [...],
+  "next_cursor": "eyJpZCI6MTQzfQ",
+  "has_more": true
+}
+```
+
+### Link Header Pagination (RESTful)
+
+```
+GET /api/users?page=2
+
+Response Headers:
+Link: <https://api.example.com/users?page=3>; rel="next",
+      <https://api.example.com/users?page=1>; rel="prev",
+      <https://api.example.com/users?page=1>; rel="first",
+      <https://api.example.com/users?page=8>; rel="last"
+```
+
+## Versioning Strategies
+
+### URL Versioning (Recommended)
+
+```
+/api/v1/users
+/api/v2/users
+
+Pros: Clear, easy to route
+Cons: Multiple URLs for same resource
+```
+
+### Header Versioning
+
+```
+GET /api/users
+Accept: application/vnd.api+json; version=2
+
+Pros: Clean URLs
+Cons: Less visible, harder to test
+```
+
+### Query Parameter
+
+```
+GET /api/users?version=2
+
+Pros: Easy to test
+Cons: Optional parameter can be forgotten
+```
+
+## Rate Limiting
+
+### Headers
+
+```
+X-RateLimit-Limit: 1000
+X-RateLimit-Remaining: 742
+X-RateLimit-Reset: 1640000000
+
+Response when limited:
+429 Too Many Requests
+Retry-After: 3600
+```
+
+### Implementation Pattern
+
+```python
+from fastapi import HTTPException, Request
+from datetime import datetime, timedelta
+
+class RateLimiter:
+    def __init__(self, calls: int, period: int):
+        self.calls = calls
+        self.period = period
+        self.cache = {}
+
+    def check(self, key: str) -> bool:
+        now = datetime.now()
+        if key not in self.cache:
+            self.cache[key] = []
+
+        # Remove old requests
+        self.cache[key] = [
+            ts for ts in self.cache[key]
+            if now - ts < timedelta(seconds=self.period)
+        ]
+
+        if len(self.cache[key]) >= self.calls:
+            return False
+
+        self.cache[key].append(now)
+        return True
+
+limiter = RateLimiter(calls=100, period=60)
+
+@app.get("/api/users")
+async def get_users(request: Request):
+    if not limiter.check(request.client.host):
+        raise HTTPException(
+            status_code=429,
+            headers={"Retry-After": "60"}
+        )
+    return {"users": [...]}
+```
+
+## Authentication and Authorization
+
+### Bearer Token
+
+```
+Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
+
+401 Unauthorized - Missing/invalid token
+403 Forbidden - Valid token, insufficient permissions
+```
+
+### API Keys
+
+```
+X-API-Key: your-api-key-here
+```
+
+## Error Response Format
+
+### Consistent Structure
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Request validation failed",
+    "details": [
+      {
+        "field": "email",
+        "message": "Invalid email format",
+        "value": "not-an-email"
+      }
+    ],
+    "timestamp": "2025-10-16T12:00:00Z",
+    "path": "/api/users"
+  }
+}
+```
+
+### Status Code Guidelines
+
+- `200 OK`: Successful GET, PATCH, PUT
+- `201 Created`: Successful POST
+- `204 No Content`: Successful DELETE
+- `400 Bad Request`: Malformed request
+- `401 Unauthorized`: Authentication required
+- `403 Forbidden`: Authenticated but not authorized
+- `404 Not Found`: Resource doesn't exist
+- `409 Conflict`: State conflict (duplicate email, etc.)
+- `422 Unprocessable Entity`: Validation errors
+- `429 Too Many Requests`: Rate limited
+- `500 Internal Server Error`: Server error
+- `503 Service Unavailable`: Temporary downtime
+
+## Caching
+
+### Cache Headers
+
+```
+# Client caching
+Cache-Control: public, max-age=3600
+
+# No caching
+Cache-Control: no-cache, no-store, must-revalidate
+
+# Conditional requests
+ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"
+If-None-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"
+→ 304 Not Modified
+```
+
+## Bulk Operations
+
+### Batch Endpoints
+
+```python
+POST /api/users/batch
+{
+  "items": [
+    {"name": "User1", "email": "user1@example.com"},
+    {"name": "User2", "email": "user2@example.com"}
+  ]
+}
+
+Response:
+{
+  "results": [
+    {"id": "1", "status": "created"},
+    {"id": null, "status": "failed", "error": "Email already exists"}
+  ]
+}
+```
+
+## Idempotency
+
+### Idempotency Keys
+
+```
+POST /api/orders
+Idempotency-Key: unique-key-123
+
+If duplicate request:
+→ 200 OK (return cached response)
+```
+
+## CORS Configuration
+
+```python
+from fastapi.middleware.cors import CORSMiddleware
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["https://example.com"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+```
+
+## Documentation with OpenAPI
+
+```python
+from fastapi import FastAPI
+
+app = FastAPI(
+    title="My API",
+    description="API for managing users",
+    version="1.0.0",
+    docs_url="/docs",
+    redoc_url="/redoc"
+)
+
+@app.get(
+    "/api/users/{user_id}",
+    summary="Get user by ID",
+    response_description="User details",
+    tags=["Users"]
+)
+async def get_user(
+    user_id: str = Path(..., description="The user ID")
+):
+    """
+    Retrieve user by ID.
+
+    Returns full user profile including:
+    - Basic information
+    - Contact details
+    - Account status
+    """
+    pass
+```
+
+## Health and Monitoring Endpoints
+
+```python
+@app.get("/health")
+async def health_check():
+    return {
+        "status": "healthy",
+        "version": "1.0.0",
+        "timestamp": datetime.now().isoformat()
+    }
+
+@app.get("/health/detailed")
+async def detailed_health():
+    return {
+        "status": "healthy",
+        "checks": {
+            "database": await check_database(),
+            "redis": await check_redis(),
+            "external_api": await check_external_api()
+        }
+    }
+```

package/framework/.antigravity/skills/brainstorming/SKILL.md

@@ -0,0 +1,282 @@
+---
+name: brainstorming
+description: Generates comprehensive questions about decisions before implementing. Explores requirements, constraints, success criteria, edge cases, and hidden assumptions in a SINGLE comprehensive prompt. Use when starting any significant work to surface unknowns early.
+license: MIT
+metadata:
+  author: AC Framework
+  version: "2.0"
+---
+
+# Brainstorming - Comprehensive Question Generation
+
+Surface unknowns, challenge assumptions, and explore the problem space BEFORE committing to a solution.
+
+## When to Use This Skill
+
+Use this skill when:
+- Starting a new project or major feature
+- Facing ambiguous requirements
+- Need to explore multiple approaches
+- Want to identify risks early
+- Before creating any OpenSpec change
+
+**CRITICAL: This skill generates ALL questions in ONE prompt, not sequentially.**
+
+---
+
+## Instructions
+
+### Step 1: Analyze the Context
+
+Read and understand:
+1. The user's stated goal/requirement
+2. Any existing project context from `project-index`
+3. Constraints mentioned or implied
+4. Success criteria (explicit or assumed)
+
+### Step 2: Generate Comprehensive Brainstorming Questions
+
+**⚠️ IMPORTANT: Generate ALL questions in a SINGLE comprehensive prompt.**
+
+Do NOT ask questions one by one. Instead, present a complete brainstorming document with ALL relevant questions organized by category.
+
+Structure your response as:
+
+```
+## 🧠 Brainstorming Analysis: [Feature/Project Name]
+
+### Context Summary
+[Brief summary of what you're building and why]
+
+### Category 1: Requirements & Scope
+Questions to clarify WHAT we're building:
+- Q1: [Specific question about requirements]
+- Q2: [Question about scope boundaries]
+- Q3: [Question about feature completeness]
+- ...
+
+### Category 2: Constraints & Limitations
+Questions about boundaries and restrictions:
+- Q1: [Technical constraint question]
+- Q2: [Time/budget constraint question]
+- Q3: [Regulatory/compliance question]
+- ...
+
+### Category 3: User Experience & Interface
+Questions about HOW users will interact:
+- Q1: [User flow question]
+- Q2: [Accessibility concern]
+- Q3: [Error handling UX question]
+- ...
+
+### Category 4: Technical Architecture
+Questions about implementation approach:
+- Q1: [Technology stack question]
+- Q2: [Integration point question]
+- Q3: [Scalability concern]
+- Q4: [Data model question]
+- ...
+
+### Category 5: Edge Cases & Failure Modes
+Questions about what could go wrong:
+- Q1: [Edge case scenario question]
+- Q2: [Failure recovery question]
+- Q3: [Security vulnerability question]
+- Q4: [Performance degradation scenario]
+- ...
+
+### Category 6: Success Criteria & Metrics
+Questions about how we measure success:
+- Q1: [Success metric question]
+- Q2: [Quality threshold question]
+- Q3: [User adoption question]
+- ...
+
+### Category 7: Dependencies & Blockers
+Questions about external factors:
+- Q1: [Third-party dependency question]
+- Q2: [Team/resource dependency]
+- Q3: [Upstream/downstream system question]
+- ...
+
+### Category 8: Alternative Approaches
+Questions exploring different solutions:
+- Q1: [Alternative technology question]
+- Q2: [Simpler approach question]
+- Q3: [Trade-off analysis question]
+- ...
+
+---
+
+## 🎯 Next Steps
+
+Please answer the questions above. Once clarified, we can proceed to:
+1. `openspec-new-change` - Create structured change
+2. `openspec-ff-change` - Fast-forward to implementation
+3. Continue brainstorming if needed
+
+**Your answers will shape the entire implementation approach.**
+```
+
+### Step 3: Wait for Comprehensive Answers
+
+After presenting ALL questions:
+- Wait for the user to answer them (may be partial or complete)
+- Ask follow-up questions ONLY if answers reveal new unknowns
+- Do NOT re-ask questions already answered
+
+### Step 4: Synthesize Insights
+
+Once you have answers:
+1. Summarize key decisions made
+2. Identify any remaining ambiguities
+3. Document assumptions being made
+4. Suggest the best path forward
+
+---
+
+## Question Categories Reference
+
+Always consider questions from these categories:
+
+**1. Requirements & Scope**
+- What exactly needs to be built?
+- What is explicitly OUT of scope?
+- Are there different user types with different needs?
+- What is the minimum viable version?
+
+**2. Constraints & Limitations**
+- Technical stack constraints?
+- Time/deadline constraints?
+- Budget/resource constraints?
+- Regulatory/compliance requirements?
+- Legacy system constraints?
+
+**3. User Experience**
+- Who are the users?
+- What is their technical sophistication?
+- What devices/platforms will they use?
+- Accessibility requirements?
+- Localization needs?
+
+**4. Technical Architecture**
+- Integration points with existing systems?
+- Data storage requirements?
+- Scalability expectations?
+- Security requirements?
+- Performance requirements (latency, throughput)?
+
+**5. Edge Cases & Failure Modes**
+- What happens when [X] fails?
+- How does the system handle invalid input?
+- What about concurrent access?
+- What's the behavior at scale limits?
+- Disaster recovery needs?
+
+**6. Success Metrics**
+- How do we know this is working?
+- What are the KPIs?
+- User satisfaction measures?
+- Technical performance thresholds?
+
+**7. Dependencies**
+- External APIs or services needed?
+- Other team dependencies?
+- Infrastructure requirements?
+- Third-party licenses or approvals?
+
+**8. Alternatives**
+- What simpler approaches exist?
+- What are the trade-offs?
+- Buy vs build decisions?
+- Short-term vs long-term considerations?
+
+---
+
+## Example Output
+
+**User says:** "Build a user authentication system"
+
+**Your brainstorming (SINGLE PROMPT):**
+
+```
+## 🧠 Brainstorming Analysis: User Authentication System
+
+### Context Summary
+Building an auth system for user login/signup. Critical security component affecting all users.
+
+### Category 1: Requirements & Scope
+- Q1: What authentication methods? (email/password, OAuth, SSO, magic links, 2FA?)
+- Q2: Do users need profiles, or just auth?
+- Q3: Session duration? Remember me feature?
+- Q4: Account recovery options?
+- Q5: Admin/moderator roles needed?
+
+### Category 2: Constraints & Limitations
+- Q6: Any compliance requirements? (GDPR, HIPAA, SOC2)
+- Q7: Password complexity requirements?
+- Q8: Rate limiting needs for brute force protection?
+
+### Category 3: User Experience
+- Q9: Login/signup flow preference? (modal, separate page, inline)
+- Q10: Error message style? (specific vs generic for security)
+- Q11: Email verification required before access?
+
+### Category 4: Technical Architecture
+- Q12: JWT vs session cookies vs other?
+- Q13: Database for user storage?
+- Q14: Password hashing algorithm? (bcrypt, Argon2)
+- Q15: Token refresh strategy?
+
+### Category 5: Edge Cases & Failure Modes
+- Q16: What if email provider is down during signup?
+- Q17: Handle concurrent login attempts from different devices?
+- Q18: Account lockout after failed attempts?
+- Q19: Session invalidation on password change?
+
+### Category 6: Success Criteria
+- Q20: Login success rate target?
+- Q21: Maximum acceptable login latency?
+- Q22: Security audit requirements?
+
+### Category 7: Dependencies
+- Q23: Email service provider? (SendGrid, AWS SES, etc.)
+- Q24: Existing user database to migrate?
+- Q25: Frontend framework constraints?
+
+### Category 8: Alternative Approaches
+- Q26: Use Auth0/Firebase Auth instead of building?
+- Q27: Start with simple email/pass, add OAuth later?
+```
+
+---
+
+## Guardrails
+
+- **ALWAYS ask ALL questions in ONE prompt** - Never sequential
+- **Be thorough** - Better to ask too much than miss critical context
+- **Organize clearly** - Categories help the user answer systematically
+- **Wait for answers** - Don't proceed until user responds
+- **Synthesize** - After answers, provide clear summary and recommendation
+- **No implementation** - This is thinking only, no code yet
+
+---
+
+## Integration with OpenSpec
+
+After brainstorming is complete:
+
+1. Summarize decisions made
+2. Recommend next step:
+   - `openspec-new-change` for structured approach
+   - `openspec-ff-change` if ready to fast-forward
+3. Include brainstorming insights in the change proposal
+
+---
+
+## Requirements
+
+- Understanding of the problem domain
+- Ability to think systematically about edge cases
+- Familiarity with common software architecture patterns
+- Knowledge of security, performance, and UX best practices