ac-framework 2.3.0 → 2.4.0

package/framework/new_project/.agents/skills/vibe-security/references/payments.md

@@ -0,0 +1,63 @@
+# Payment Security (Stripe)
+
+## Never Trust Client-Submitted Prices
+
+The #1 payment vulnerability in vibe-coded apps: the price comes from the client. An attacker can set any amount, including $0.
+
+```typescript
+// BAD: price comes from the request body
+const session = await stripe.checkout.sessions.create({
+  line_items: [{
+    price_data: {
+      currency: 'usd',
+      unit_amount: req.body.price, // attacker controls this
+      product_data: { name: req.body.name },
+    },
+    quantity: 1,
+  }],
+});
+
+// GOOD: look up the price server-side
+const product = await db.products.findUnique({ where: { id: req.body.productId } });
+if (!product) return new Response('Not found', { status: 404 });
+
+const session = await stripe.checkout.sessions.create({
+  line_items: [{ price: product.stripePriceId, quantity: 1 }],
+});
+```
+
+Use Stripe Price IDs (created via the Stripe dashboard or API) rather than constructing prices from your database. This way, prices are defined in Stripe and can't be manipulated.
+
+## Webhook Signature Verification
+
+Stripe webhooks must have their signatures verified. This requires the **raw request body** — parsing the body as JSON first destroys the signature.
+
+```typescript
+// Express: webhook route MUST use express.raw() BEFORE express.json()
+app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
+  const sig = req.headers['stripe-signature'];
+  const event = stripe.webhooks.constructEvent(req.body, sig, webhookSecret);
+  // ... handle event
+});
+
+// Next.js App Router: use request.text(), NOT request.json()
+export async function POST(request: Request) {
+  const body = await request.text();
+  const sig = request.headers.get('stripe-signature')!;
+  const event = stripe.webhooks.constructEvent(body, sig, webhookSecret);
+  // ... handle event
+}
+```
+
+## Subscription Status Validation
+
+Check subscription status **server-side on every protected request** using your database (kept in sync via webhooks). Do not rely on:
+- A cached session value from login time
+- A client-side flag
+- A JWT claim that was set at token creation and never refreshed
+
+Subscriptions can be cancelled, expire, or change tier at any time. Your database (updated via webhooks) is the source of truth.
+
+## Checkout Session Metadata
+
+Validate that checkout session metadata (user ID, plan, etc.) was set **server-side** when creating the session, not passed from the client. If metadata comes from the client, an attacker can claim to be a different user or select a different plan.

package/framework/new_project/.agents/skills/vibe-security/references/rate-limiting.md

@@ -0,0 +1,55 @@
+# Rate Limiting & Abuse Prevention
+
+## Where Rate Limiting Is Required
+
+Every one of these endpoints needs rate limiting. AI assistants almost never add it:
+
+- **Auth endpoints** — login, register, password reset, OTP verification, magic link. Without limits, attackers can brute-force passwords or enumerate accounts.
+- **AI API calls** — Any endpoint that calls OpenAI, Anthropic, or similar. A single user can drain your entire monthly budget in minutes.
+- **Email / SMS sending** — Attackers can use your app as a spam relay.
+- **File processing** — Upload, resize, convert. CPU-intensive operations without limits enable denial-of-service.
+- **Webhook-like endpoints** — Anything accepting external input at scale.
+
+## Don't Store Rate Limits in Public Tables
+
+If rate limit counters live in a Supabase public table, users can reset their own counters via the REST API. Use:
+
+- **Upstash Redis** — Serverless Redis with built-in rate limiting primitives
+- **Private schema table** — Not exposed via PostgREST
+- **Middleware-level limiting** — At the edge or API gateway
+- **In-memory stores** — For single-server deployments (Redis for multi-server)
+
+## Combine Per-IP and Per-User Limiting
+
+- IP-only limits are defeated by rotating IPs (trivial with VPNs or botnets)
+- User-only limits are defeated by creating new accounts
+- Use both together for effective protection
+
+## Billing Protection
+
+- Set billing alerts on every cloud provider (AWS, GCP, Vercel, etc.)
+- Set **hard spending caps** on AI API providers (OpenAI, Anthropic)
+- Use per-user usage quotas with hard limits, not just soft warnings
+- Monitor for anomalous usage patterns (sudden spikes, requests at odd hours)
+
+## Implementation Pattern
+
+```typescript
+// Example: rate limiting with Upstash Redis
+import { Ratelimit } from '@upstash/ratelimit';
+import { Redis } from '@upstash/redis';
+
+const ratelimit = new Ratelimit({
+  redis: Redis.fromEnv(),
+  limiter: Ratelimit.slidingWindow(10, '1 m'), // 10 requests per minute
+});
+
+export async function POST(request: Request) {
+  const ip = request.headers.get('x-forwarded-for') ?? '127.0.0.1';
+  const { success } = await ratelimit.limit(ip);
+  if (!success) {
+    return new Response('Too many requests', { status: 429 });
+  }
+  // ... handle request
+}
+```

package/framework/new_project/.agents/skills/vibe-security/references/secrets-and-env.md

@@ -0,0 +1,47 @@
+# Secrets & Environment Variables
+
+## Hardcoded Credentials
+
+Never hardcode API keys, tokens, passwords, or credentials in source code. This includes:
+- Strings that look like API keys in source files
+- Connection strings with embedded passwords
+- Private keys or certificates in the repo
+
+If a secret was ever committed to Git history, consider it compromised — deleting the file doesn't remove it from history. The key must be rotated immediately. Run `gitleaks detect` to scan for leaked secrets.
+
+## Client-Side Environment Variable Prefixes
+
+These prefixes cause env vars to be inlined into the client bundle at build time. Everything in the bundle is visible to anyone:
+
+| Framework | Client Prefix | Danger |
+|-----------|--------------|--------|
+| Next.js | `NEXT_PUBLIC_` | Inlined into browser JS at build time |
+| Vite | `VITE_` | Inlined into browser JS at build time |
+| Expo / React Native | `EXPO_PUBLIC_` | Baked into the app bundle |
+| Create React App | `REACT_APP_` | Inlined into browser JS at build time |
+
+**What belongs client-side:**
+- Stripe publishable key (`pk_live_*`, `pk_test_*`)
+- Supabase anon key
+- Firebase client config (apiKey, authDomain, projectId)
+- Public analytics IDs
+
+**What must NEVER be client-side:**
+- Supabase `service_role` key (bypasses all RLS)
+- Stripe secret key (`sk_live_*`, `sk_test_*`)
+- Any database connection string
+- Any third-party API secret key
+- JWT signing secrets
+- OAuth client secrets
+
+## .gitignore
+
+Ensure `.env`, `.env.local`, `.env.*.local`, and any file containing secrets is in `.gitignore` **before the first commit**. Check that `.env.example` or `.env.sample` files contain only placeholder values, not real keys.
+
+## Detection Tips
+
+When auditing, search for:
+- Files named `.env` that are tracked by git (`git ls-files | grep .env`)
+- Strings matching common key patterns: `sk_live_`, `sk_test_`, `AKIA`, `ghp_`, `glpat-`, `xoxb-`, `Bearer `
+- `process.env.NEXT_PUBLIC_` or `import.meta.env.VITE_` referencing anything with "secret", "private", "service", or "key" in the name
+- Hardcoded URLs containing credentials (e.g., `postgresql://user:password@host`)

package/framework/new_project/.agents/workflows/ac-lite.md

@@ -0,0 +1,295 @@
+**Fundamental Principle**: *"Quality with focused context. Load only what is necessary, when it is necessary."*
+
+---
+
+## Purpose
+
+`ac-lite` keeps the same spec-driven quality bar as `ac.md`, but reduces token usage by:
+
+1. Loading only the core workflow skills by default.
+2. Activating extra skills only when objective risk gates require them.
+3. Enforcing mandatory quality checkpoints before implementation and archive.
+
+---
+
+## Default Skill Set (Always Load)
+
+These are the only mandatory skills for every change:
+
+1. `acfm-spec-workflow`
+2. `acfm-memory`
+3. `openspec-new-change` OR `openspec-ff-change`
+4. `openspec-continue-change`
+5. `openspec-apply-change`
+6. `openspec-verify-change`
+7. `openspec-archive-change`
+
+---
+
+## Persistent Memory Protocol (Always Active)
+
+Agents must use the available persistent memory system proactively on every chat/session.
+
+**Session-start requirement (always):**
+1. Consult the available persistent memory tool or MCP before planning, implementing, or giving project-specific guidance.
+2. Recall project-level context first, then search for task-specific decisions, conventions, bugfixes, and architecture notes.
+3. Treat recalled memory as active context unless the current repository state or an explicit user instruction supersedes it.
+4. If memory tooling is unavailable, continue with repository inspection and use the AC Framework CLI fallback when possible.
+
+**Save automatically when information is reusable:**
+- Architectural decisions from proposals/designs
+- Bugfix patterns and solutions
+- Performance optimizations
+- Refactoring techniques
+- Security fixes
+- API patterns and conventions
+- Reusable workflow conventions and project constraints
+
+**Memory hygiene rules:**
+- Save only reusable information likely to matter in future chats.
+- Do not save secrets, credentials, tokens, or one-off sensitive data.
+- Redact content inside `<private>...</private>` before saving.
+- Prefer concise titles, the correct memory type, clear tags, and realistic confidence scores.
+
+**Fallback examples:**
+```bash
+acfm memory recall "implementing authentication"
+acfm memory search "JWT token refresh"
+acfm memory recall
+acfm memory stats
+```
+
+---
+
+
+## SynapseGrid Collaboration Protocol (Optional but Recommended for Complex Tasks)
+
+Use SynapseGrid when a task benefits from role-based collaboration and explicit review loops.
+
+**Delegate to SynapseGrid when:**
+- Scope spans planning + implementation + review
+- Risk is medium/high (security, migrations, API contract changes)
+- You need auditable outputs (transcript, meeting summary, artifacts)
+- A single-pass implementation is likely to miss edge cases
+
+**Role delegation map:**
+- `planner` -> plan/constraints/acceptance criteria
+- `critic` -> risk analysis and challenge assumptions
+- `coder` -> implementation and concrete edits
+- `reviewer` -> final verification and readiness checks
+
+**Preferred MCP flow:**
+1. `collab_start_session`
+2. `collab_invoke_team`
+3. `collab_wait_run`
+4. `collab_get_result`
+5. Optional: `collab_get_transcript`, `collab_get_meeting_log`, `collab_status`
+
+**CLI fallback:**
+```bash
+acfm agents setup
+acfm agents runtime set auto
+acfm agents doctor --verbose
+acfm agents start --task "..." --mux auto
+acfm agents transcript --role all --limit 80
+acfm agents summary
+acfm agents artifacts --watch --interval 1200
+```
+
+**Model and runtime controls:**
+```bash
+acfm agents model list
+acfm agents model choose
+acfm agents runtime get
+acfm agents runtime install-zellij
+```
+
+**Artifacts to inspect:**
+- `~/.acfm/synapsegrid/<sessionId>/meeting-log.md`
+- `~/.acfm/synapsegrid/<sessionId>/meeting-summary.md`
+- `~/.acfm/synapsegrid/<sessionId>/turns/raw/*.ndjson`
+
+**Lite rule:** delegate only when collaboration adds value; otherwise continue with normal `ac-lite` flow.
+
+
+## Conditional Skills (Load Only If Gate Triggers)
+
+### Security Gate
+
+Load `secure-coding-cybersecurity` if the change touches any of:
+
+- Auth/session/permissions
+- User input handling or validation
+- SQL/ORM queries or dynamic filters
+- File paths/uploads
+- Secrets/tokens/credentials
+- Shell/command execution
+
+- Run `vibe-security` as the final security audit before archive (mandatory in Gate B).
+
+### Testing Gate
+
+Load `test-generator` if:
+
+- There are no tests for the changed behavior, or
+- Existing tests do not cover acceptance criteria, or
+- Regression risk is medium/high.
+
+### Consistency Gate
+
+Load `spec-analysis` and `requirement-checklist` if:
+
+- Requirements are ambiguous, or
+- Change spans multiple modules, or
+- Change modifies core domain behavior.
+
+### API Gate
+
+Load `api-design-principles` if API contracts/endpoints/schemas are added or modified.
+
+### UI Gate
+
+Load `interface-design` if dashboard/app UI behavior is introduced or changed.
+
+### Performance Gate
+
+Load `performance-optimizer` if:
+
+- The change affects hot paths, or
+- Latency/throughput targets exist, or
+- A performance regression is detected/suspected.
+
+### Context Scale Gate
+
+Load `project-index` and/or `context-synthesizer` if:
+
+- Codebase is large and discovery cost is high, or
+- Session is long and context drift appears.
+
+### Debug Gate
+
+Load `systematic-debugging` when blocked by non-trivial bugs or unstable behavior.
+
+---
+
+## Mandatory Quality Gates
+
+These gates are non-optional in `ac-lite`.
+
+### Gate A: Ready to Implement
+
+Before `openspec-apply-change`, all must be true:
+
+- Change exists and status is valid (`acfm spec status --change <name> --json`)
+- `tasks.md` exists with actionable checkboxes
+- Acceptance criteria are clear in artifacts
+- Required conditional skills (if triggered) were executed
+- Session-start memory recall completed for this chat/session
+
+If any item fails: stop, resolve, then continue.
+
+### Gate B: Ready to Archive
+
+Before `openspec-archive-change`, all must be true:
+
+- `openspec-verify-change` completed
+- `vibe-security` executed as final security validation
+- No unresolved CRITICAL/HIGH findings remain
+- Relevant tests pass for changed behavior
+- Tasks are complete or explicitly accepted by user with warning
+- Relevant reusable context from the completed work was saved to memory
+
+If any item fails: stop, fix, re-verify.
+
+---
+
+## Lite Workflows
+
+### New Change (Default Path)
+
+1. Run `acfm-spec-workflow` checks (`acfm spec status --json`, init if needed).
+2. Run a session-start memory recall using the available memory tool/MCP or the AC Framework CLI fallback.
+3. Create change with `openspec-new-change` (or `openspec-ff-change` if user requests speed).
+4. Build artifacts with `openspec-continue-change` until apply-ready.
+5. Evaluate conditional gates and load only triggered skills.
+6. Pass Gate A.
+7. Implement with `openspec-apply-change`.
+8. Verify with `openspec-verify-change`.
+9. Run `vibe-security` for final security audit and remediate findings.
+10. Pass Gate B.
+11. Archive with `openspec-archive-change`.
+
+### Existing Change (Default Path)
+
+1. Confirm initialization and active changes.
+2. Run a session-start memory recall using the available memory tool/MCP or the AC Framework CLI fallback.
+3. Select target change.
+4. Refresh artifact status.
+5. Evaluate conditional gates (only load what triggers).
+6. Pass Gate A.
+7. Implement.
+8. Verify.
+9. Run `vibe-security` for final security audit and remediate findings.
+10. Pass Gate B.
+11. Archive.
+
+---
+
+## Operational Rules
+
+1. Run memory recall at the start of every new chat/session before planning or implementation.
+2. Save important reusable context automatically after significant decisions, fixes, or conventions emerge.
+3. Do not load broad quality/documentation skills by default.
+4. Do not run optional skills "just in case".
+5. If risk increases during implementation, activate the matching conditional skill immediately.
+6. Prefer deterministic CLI checks over narrative assumptions.
+7. Keep outputs concise but auditable (show which gates passed/failed and why).
+
+---
+
+## Suggested Minimal Execution Template
+
+Use this structure in each run:
+
+1. **Change Context**
+   - Change name
+   - Current artifact progress
+
+2. **Memory Status**
+   - Session recall completed: yes/no
+   - Relevant prior decisions/patterns found
+   - Memory save needed at close: yes/no
+
+3. **Triggered Gates**
+   - Security: pass/fail + reason
+   - Testing: pass/fail + reason
+   - Consistency/API/UI/Performance/Context/Debug: pass/fail + reason
+
+4. **Skills Loaded**
+   - Core: always list
+   - Conditional: list only triggered ones
+
+5. **Gate A Status**
+   - Ready to implement: yes/no
+
+6. **Implementation + Verify**
+   - What was implemented
+   - Verify findings summary
+
+7. **Gate B Status**
+   - Ready to archive: yes/no
+
+8. **Archive Result**
+   - Archive path and timestamp
+
+---
+
+## Token Strategy Summary
+
+`ac-lite` reduces cost by replacing "load everything first" with:
+
+- Mandatory core workflow only
+- Risk-gated skill expansion
+- Hard quality checkpoints at implementation and archive boundaries
+
+This preserves software quality while avoiding unnecessary instruction/context overhead.