cfsa-antigravity 2.19.3 → 3.0.0

package/template/.factory/skills/accessibility/references/ia-spec-checklist.md

@@ -0,0 +1,35 @@
+# Accessibility Specification Checklist
+
+> Part of [Accessibility](../SKILL.md) — use this checklist when writing accessibility specifications during IA spec design (Step 5.5 of `/write-architecture-spec-design`).
+
+**Invoked by**: `/write-architecture-spec-design` Step 5.5
+
+**Prerequisites**:
+- `{{SURFACES}}` must be filled (determines applicability)
+- User interactions must be documented (Step 2 of the workflow)
+
+## Applicability
+
+**Visual surfaces** (`web`, `mobile`, `desktop`): Follow the full checklist below.
+
+**Non-visual surfaces** (`api`, `cli`, `extension` only): Write `"Not applicable — no visual surfaces"` in the `## Accessibility` section and skip.
+
+## Per-Interaction Checklist
+
+For each user interaction documented in the spec's `## User Interactions` section, document:
+
+| Dimension | What to Document | Notes |
+|-----------|-----------------|-------|
+| **Keyboard navigation** | Tab order and focus management | How does the user complete this flow without a mouse? |
+| **Screen reader semantics** | ARIA roles, labels, live regions | What announcements does a screen reader make at each step? |
+| **Color contrast** | Requirements for visual states | Loading, error, empty, disabled — each needs contrast compliance |
+| **Motion** | `prefers-reduced-motion` implications | Which animations/transitions need a reduced-motion alternative? |
+| **Touch targets** | Minimum 44×44 px | Mobile surfaces only |
+
+## Review Questions
+
+Use these to validate the spec with the user:
+
+1. "Any interactions in this domain that could be problematic for keyboard-only users?"
+2. "Visual states (loading, error, empty, disabled) that need specific ARIA announcements?"
+3. (Mobile only) "Do any touch targets fall below the 44×44 px minimum?"

package/template/.factory/skills/adversarial-review/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: adversarial-review
+description: Structured methodology for adversarial thinking — generating attack scenarios, abuse cases, race conditions, and security edge cases against specs and implementations. Produces spec-level gap items, not code-level fixes.
+---
+
+# Adversarial Review
+
+This skill is invoked during spec deepening passes, ambiguity audits, and security review gates, and its output is always spec-level gap items — never code-level fixes.
+
+## When to Use
+
+- During `write-architecture-spec-deepen` Pass 3
+- During `audit-ambiguity-execute` Step 3c devil's advocate pass
+- During `remediate-pipeline-execute` adversarial consistency check
+- During `validate-phase` Step 8 security review
+- Before any spec layer audit gate
+
+## Instructions
+
+### 1. Attack Surface Enumeration
+
+Systematically enumerate each of the following categories for every feature or endpoint under review. For each category, apply the listed triggering question:
+
+- **Authentication bypass**: "What happens if the request arrives with no token, an expired token, or a token for a different service?"
+- **Privilege escalation**: "What happens if a user with role X calls an endpoint intended only for role Y — does the guard exist at the API layer, or only the UI layer?"
+- **Insecure direct object reference (IDOR)**: "What happens if an authenticated user sends a request substituting another user's resource ID?"
+- **Data exfiltration**: "Does any response field expose data about resources the caller did not request?"
+- **Denial-of-service**: "Is this endpoint bounded — are there rate limits, payload size limits, and query result limits specified in the spec?"
+- **Injection points**: "Is every user-supplied string that reaches a query, command, template, or file path validated and sanitized in the spec?"
+
+For every category where the spec does not provide an explicit answer, write a `SPEC GAP` item (see Step 5).
+
+### 2. Abuse Scenario Generation Framework
+
+For each feature or endpoint, generate all four scenario paths:
+
+- **Happy path**: The intended use by a legitimate, competent user.
+- **Malicious actor path**: A deliberate attempt to cause unauthorized access, data corruption, or system disruption.
+- **Incompetent actor path**: An accidental misuse — duplicate submissions, wrong resource IDs, malformed payloads — and whether the spec handles the resulting state gracefully.
+- **Concurrent execution path**: Two or more users executing the same operation simultaneously — does the spec describe the expected outcome, or does it silently assume serial execution?
+
+Document the expected behavior for each path. Any path for which the spec does not define expected behavior is a `SPEC GAP`.
+
+### 3. Race Condition and Concurrency Identification
+
+For every write operation in the spec, ask "what if two requests arrive simultaneously?" Specifically identify:
+
+- Shared mutable state that is read then written in non-atomic operations.
+- Read-modify-write sequences that do not specify a locking or optimistic-concurrency strategy.
+- Time-of-check-to-time-of-use (TOCTOU) windows (e.g., permission check followed by action, not wrapped atomically).
+- Distributed transaction boundaries where partial success is possible and the spec does not define a rollback or compensation behavior.
+
+Each identified pattern that is not addressed in the spec is a `SPEC GAP`.
+
+### 4. Boundary Condition Stress-Testing
+
+For every input in the spec, verify the spec defines behavior at:
+
+- **Empty string / empty collection** (where at least one item is assumed by downstream logic).
+- **Null and undefined** (for every optional field — what does the system do when the field is absent?).
+- **Maximum field length** (what happens when a string hits the character limit?).
+- **Integer overflow and underflow boundaries**.
+- **Negative numbers** where only positives are semantically valid.
+- **Unicode edge cases**: right-to-left characters, zero-width characters, emoji in identifiers.
+
+Any boundary for which the spec does not define behavior is a `SPEC GAP`.
+
+### 5. Documenting Findings as Spec-Level Gap Items
+
+All findings from Steps 1–4 must be written using this exact format:
+
+```
+SPEC GAP: [layer] § [section] — [what is underspecified] — [attack scenario or failure mode] — [proposed resolution or question for user]
+```
+
+- The **layer** field is one of: `IA`, `BE`, `FE`.
+- The **section** field quotes the heading of the spec section under review.
+- The **proposed resolution** is either a concrete suggestion (if the answer is determinable from `ideation-index.md` or `architecture-design.md`) or a question for the user (if it is a product decision).
+
+**Never** write the finding as a code change, a PR comment, or an implementation task.
+
+## Anti-Patterns
+
+- **Implementation TODOs instead of spec gaps** — Documenting findings as implementation TODOs rather than spec gap items. The output of this skill is always a spec amendment, never a code fix.
+- **Skipping the concurrent execution path** — Skipping the concurrent execution path because "the feature seems simple." Concurrency issues emerge precisely in features that appear trivial.
+- **Stopping at the happy path** — The malicious, incompetent, and concurrent paths are not optional. All four scenario paths must be generated for every feature and endpoint.
+
+## Related Skills
+
+- **`security-scanning-security-hardening`** — Use when transitioning from spec-level gap analysis to implementation-level security hardening. This skill identifies *what is underspecified* at the spec layer; `security-scanning-security-hardening` coordinates *multi-layer scanning and hardening* of the actual codebase and infrastructure after implementation.

package/template/.factory/skills/antigravity-workflows/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: antigravity-workflows
+description: "Orchestrate multiple Antigravity skills through guided workflows for SaaS MVP delivery, security audits, AI agent builds, and browser QA."
+risk: none
+source: self
+date_added: "2026-02-27"
+---
+
+# Antigravity Workflows
+
+Use this skill to turn a complex objective into a guided sequence of skill invocations.
+
+## When to Use This Skill
+
+Use this skill when:
+- The user wants to combine several skills without manually selecting each one.
+- The goal is multi-phase (for example: plan, build, test, ship).
+- The user asks for best-practice execution for common scenarios like:
+  - Shipping a SaaS MVP
+  - Running a web security audit
+  - Building an AI agent system
+  - Implementing browser automation and E2E QA
+
+## Workflow Source of Truth
+
+Read workflows in this order:
+1. `docs/WORKFLOWS.md` for human-readable playbooks.
+2. `data/workflows.json` for machine-readable workflow metadata.
+
+## How to Run This Skill
+
+1. Identify the user's concrete outcome.
+2. Propose the 1-2 best matching workflows.
+3. Ask the user to choose one.
+4. Execute step-by-step:
+   - Announce current step and expected artifact.
+   - Invoke recommended skills for that step.
+   - Verify completion criteria before moving to next step.
+5. At the end, provide:
+   - Completed artifacts
+   - Validation evidence
+   - Remaining risks and next actions
+
+## Default Workflow Routing
+
+- Product delivery request -> `ship-saas-mvp`
+- Security review request -> `security-audit-web-app`
+- Agent/LLM product request -> `build-ai-agent-system`
+- E2E/browser testing request -> `qa-browser-automation`
+
+## Copy-Paste Prompts
+
+```text
+Use @antigravity-workflows to run the "Ship a SaaS MVP" workflow for my project idea.
+```
+
+```text
+Use @antigravity-workflows and execute a full "Security Audit for a Web App" workflow.
+```
+
+```text
+Use @antigravity-workflows to guide me through "Build an AI Agent System" with checkpoints.
+```
+
+```text
+Use @antigravity-workflows to execute the "QA and Browser Automation" workflow and stabilize flaky tests.
+```
+
+## Limitations
+
+- This skill orchestrates; it does not replace specialized skills.
+- It depends on the local availability of referenced skills.
+- It does not guarantee success without environment access, credentials, or required infrastructure.
+- For stack-specific browser automation in Go, `go-playwright` may require the corresponding skill to be present in your local skills repository.
+
+## Related Skills
+
+- `concise-planning`
+- `brainstorming`
+- `workflow-automation`
+- `verification-before-completion`

package/template/.factory/skills/antigravity-workflows/resources/implementation-playbook.md

@@ -0,0 +1,36 @@
+# Antigravity Workflows Implementation Playbook
+
+This document explains how an agent should execute workflow-based orchestration.
+
+## Execution Contract
+
+For every workflow:
+
+1. Confirm objective and scope.
+2. Select the best-matching workflow.
+3. Execute workflow steps in order.
+4. Produce one concrete artifact per step.
+5. Validate before continuing.
+
+## Step Artifact Examples
+
+- Plan step -> scope document or milestone checklist.
+- Build step -> code changes and implementation notes.
+- Test step -> test results and failure triage.
+- Release step -> rollout checklist and risk log.
+
+## Safety Guardrails
+
+- Never run destructive actions without explicit user approval.
+- If a required skill is missing, state the gap and fallback to closest available skill.
+- When security testing is involved, ensure authorization is explicit.
+
+## Suggested Completion Format
+
+At workflow completion, return:
+
+1. Completed steps
+2. Artifacts produced
+3. Validation evidence
+4. Open risks
+5. Suggested next action

package/template/.factory/skills/api-design-principles/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: api-design-principles
+description: "Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers. Use when designing new APIs, reviewing API specifications, or establishing API design standards."
+version: 2.0.0
+source: self
+date_added: "2026-02-27"
+date_rewritten: "2026-03-14"
+---
+
+# API Design Principles
+
+Design APIs that developers love to use — consistent, predictable, and well-documented.
+
+## When to Use
+
+- Designing new REST or GraphQL APIs
+- Reviewing API specs before implementation
+- Establishing API design standards for a team
+- Migrating between API paradigms
+
+## When NOT to Use
+
+- Framework-specific implementation details (use stack skills instead)
+- Infrastructure-only work without API contracts
+- Existing APIs that cannot be versioned
+
+---
+
+## Core Rules
+
+### 1. Resources Are Nouns, Methods Are Verbs
+
+```
+✅ GET    /api/users          → List users
+✅ POST   /api/users          → Create user
+✅ GET    /api/users/{id}     → Get user
+✅ PATCH  /api/users/{id}     → Update user fields
+✅ DELETE /api/users/{id}     → Delete user
+
+❌ POST   /api/createUser
+❌ GET    /api/getUserById
+❌ POST   /api/deleteUser
+```
+
+### 2. HTTP Methods Have Meaning
+
+| Method | Purpose | Idempotent | Safe | Request Body |
+|--------|---------|------------|------|:------------:|
+| GET | Read | ✅ | ✅ | No |
+| POST | Create | ❌ | ❌ | Yes |
+| PUT | Replace | ✅ | ❌ | Yes |
+| PATCH | Partial update | ❌ | ❌ | Yes |
+| DELETE | Remove | ✅ | ❌ | No |
+
+### 3. Status Codes Tell the Story
+
+| Code | When | Example |
+|------|------|---------|
+| 200 | Success with body | GET returns resource |
+| 201 | Created | POST creates new resource |
+| 204 | Success, no body | DELETE succeeds |
+| 400 | Client sent bad data | Malformed JSON |
+| 401 | Not authenticated | Missing/invalid token |
+| 403 | Authenticated but not authorized | Wrong role |
+| 404 | Resource doesn't exist | Invalid ID |
+| 409 | Conflict | Duplicate email |
+| 422 | Valid JSON, invalid content | Email format wrong |
+| 429 | Rate limited | Too many requests |
+| 500 | Server error | Unhandled exception |
+
+### 4. Error Responses Are Structured
+
+```json
+{
+  "error": "ValidationError",
+  "code": "INVALID_EMAIL",
+  "message": "Email address is not valid",
+  "details": {
+    "field": "email",
+    "value": "not-an-email",
+    "constraint": "Must be a valid email format"
+  }
+}
+```
+
+**Rules:**
+- Same envelope for every error
+- Machine-readable `code` for client logic
+- Human-readable `message` for display
+- `details` for field-level validation errors
+- NEVER include stack traces in production
+
+### 5. Always Paginate Collections
+
+```
+GET /api/users?page=2&page_size=20
+
+Response:
+{
+  "items": [...],
+  "total": 243,
+  "page": 2,
+  "page_size": 20,
+  "pages": 13
+}
+```
+
+For GraphQL, use cursor-based pagination (Relay spec):
+
+```graphql
+type UserConnection {
+  edges: [UserEdge!]!
+  pageInfo: PageInfo!
+  totalCount: Int!
+}
+```
+
+### 6. Version From Day One
+
+| Strategy | URL | Header | Query |
+|----------|-----|--------|-------|
+| Example | `/api/v1/users` | `Accept: application/vnd.api+json; version=1` | `/api/users?version=1` |
+| Pros | Simple, visible | Clean URLs | Simple to add |
+| Cons | URL pollution | Hidden from browsers | Caching complexity |
+| Best for | Most APIs | Internal APIs | Quick prototypes |
+
+### 7. Rate Limit Everything Public
+
+Every public endpoint must return rate limit headers:
+
+```
+X-RateLimit-Limit: 100
+X-RateLimit-Remaining: 42
+X-RateLimit-Reset: 1625097600
+```
+
+## API Design Checklist
+
+Before implementing any endpoint:
+
+- [ ] Resource name is a plural noun
+- [ ] HTTP method matches the operation semantics
+- [ ] Request/response schemas are defined (contract-first)
+- [ ] Error responses use consistent envelope
+- [ ] Pagination is implemented for collection endpoints
+- [ ] Authentication and authorization rules are specified
+- [ ] Rate limiting is configured
+- [ ] API version is specified
+- [ ] Input validation rules are documented per field
+
+## Anti-Patterns
+
+| Don't | Do |
+|-------|-----|
+| Verbs in URLs (`/getUser`) | Nouns + HTTP methods (`GET /users`) |
+| 200 for everything | Correct status codes per operation |
+| Generic errors ("Something went wrong") | Structured errors with codes |
+| Return all fields always | Support field selection or use GraphQL |
+| Nest resources >2 levels deep | `/users/{id}/orders` max; flatten after that |
+| Ignore backward compatibility | Version APIs; deprecation headers before removal |
+
+## Extended Reference
+
+See `resources/implementation-playbook.md` for:
+- Full pagination implementation (FastAPI)
+- HATEOAS patterns
+- GraphQL schema design with Relay-style connections
+- DataLoader patterns for N+1 prevention
+- Complete code templates

package/template/.factory/skills/api-design-principles/assets/api-design-checklist.md

@@ -0,0 +1,155 @@
+# API Design Checklist
+
+## Pre-Implementation Review
+
+### Resource Design
+
+- [ ] Resources are nouns, not verbs
+- [ ] Plural names for collections
+- [ ] Consistent naming across all endpoints
+- [ ] Clear resource hierarchy (avoid deep nesting >2 levels)
+- [ ] All CRUD operations properly mapped to HTTP methods
+
+### HTTP Methods
+
+- [ ] GET for retrieval (safe, idempotent)
+- [ ] POST for creation
+- [ ] PUT for full replacement (idempotent)
+- [ ] PATCH for partial updates
+- [ ] DELETE for removal (idempotent)
+
+### Status Codes
+
+- [ ] 200 OK for successful GET/PATCH/PUT
+- [ ] 201 Created for POST
+- [ ] 204 No Content for DELETE
+- [ ] 400 Bad Request for malformed requests
+- [ ] 401 Unauthorized for missing auth
+- [ ] 403 Forbidden for insufficient permissions
+- [ ] 404 Not Found for missing resources
+- [ ] 422 Unprocessable Entity for validation errors
+- [ ] 429 Too Many Requests for rate limiting
+- [ ] 500 Internal Server Error for server issues
+
+### Pagination
+
+- [ ] All collection endpoints paginated
+- [ ] Default page size defined (e.g., 20)
+- [ ] Maximum page size enforced (e.g., 100)
+- [ ] Pagination metadata included (total, pages, etc.)
+- [ ] Cursor-based or offset-based pattern chosen
+
+### Filtering & Sorting
+
+- [ ] Query parameters for filtering
+- [ ] Sort parameter supported
+- [ ] Search parameter for full-text search
+- [ ] Field selection supported (sparse fieldsets)
+
+### Versioning
+
+- [ ] Versioning strategy defined (URL/header/query)
+- [ ] Version included in all endpoints
+- [ ] Deprecation policy documented
+
+### Error Handling
+
+- [ ] Consistent error response format
+- [ ] Detailed error messages
+- [ ] Field-level validation errors
+- [ ] Error codes for client handling
+- [ ] Timestamps in error responses
+
+### Authentication & Authorization
+
+- [ ] Authentication method defined (Bearer token, API key)
+- [ ] Authorization checks on all endpoints
+- [ ] 401 vs 403 used correctly
+- [ ] Token expiration handled
+
+### Rate Limiting
+
+- [ ] Rate limits defined per endpoint/user
+- [ ] Rate limit headers included
+- [ ] 429 status code for exceeded limits
+- [ ] Retry-After header provided
+
+### Documentation
+
+- [ ] OpenAPI/Swagger spec generated
+- [ ] All endpoints documented
+- [ ] Request/response examples provided
+- [ ] Error responses documented
+- [ ] Authentication flow documented
+
+### Testing
+
+- [ ] Unit tests for business logic
+- [ ] Integration tests for endpoints
+- [ ] Error scenarios tested
+- [ ] Edge cases covered
+- [ ] Performance tests for heavy endpoints
+
+### Security
+
+- [ ] Input validation on all fields
+- [ ] SQL injection prevention
+- [ ] XSS prevention
+- [ ] CORS configured correctly
+- [ ] HTTPS enforced
+- [ ] Sensitive data not in URLs
+- [ ] No secrets in responses
+
+### Performance
+
+- [ ] Database queries optimized
+- [ ] N+1 queries prevented
+- [ ] Caching strategy defined
+- [ ] Cache headers set appropriately
+- [ ] Large responses paginated
+
+### Monitoring
+
+- [ ] Logging implemented
+- [ ] Error tracking configured
+- [ ] Performance metrics collected
+- [ ] Health check endpoint available
+- [ ] Alerts configured for errors
+
+## GraphQL-Specific Checks
+
+### Schema Design
+
+- [ ] Schema-first approach used
+- [ ] Types properly defined
+- [ ] Non-null vs nullable decided
+- [ ] Interfaces/unions used appropriately
+- [ ] Custom scalars defined
+
+### Queries
+
+- [ ] Query depth limiting
+- [ ] Query complexity analysis
+- [ ] DataLoaders prevent N+1
+- [ ] Pagination pattern chosen (Relay/offset)
+
+### Mutations
+
+- [ ] Input types defined
+- [ ] Payload types with errors
+- [ ] Optimistic response support
+- [ ] Idempotency considered
+
+### Performance
+
+- [ ] DataLoader for all relationships
+- [ ] Query batching enabled
+- [ ] Persisted queries considered
+- [ ] Response caching implemented
+
+### Documentation
+
+- [ ] All fields documented
+- [ ] Deprecations marked
+- [ ] Examples provided
+- [ ] Schema introspection enabled