devstack 0.1.0

package/vendor/skills/skills/organization-best-practices/SKILL.md

@@ -0,0 +1,478 @@
+---
+name: organization-best-practices
+description: Configure multi-tenant organizations, manage members and invitations, define custom roles and permissions, set up teams, and implement RBAC using Better Auth's organization plugin. Use when users need org setup, team management, member roles, access control, or the Better Auth organization plugin.
+---
+
+## Setup
+
+1. Add `organization()` plugin to server config
+2. Add `organizationClient()` plugin to client config
+3. Run `npx @better-auth/cli migrate`
+4. Verify: check that organization, member, invitation tables exist in your database
+
+```ts
+import { betterAuth } from "better-auth";
+import { organization } from "better-auth/plugins";
+
+export const auth = betterAuth({
+  plugins: [
+    organization({
+      allowUserToCreateOrganization: true,
+      organizationLimit: 5, // Max orgs per user
+      membershipLimit: 100, // Max members per org
+    }),
+  ],
+});
+```
+
+### Client-Side Setup
+
+```ts
+import { createAuthClient } from "better-auth/client";
+import { organizationClient } from "better-auth/client/plugins";
+
+export const authClient = createAuthClient({
+  plugins: [organizationClient()],
+});
+```
+
+## Creating Organizations
+
+The creator is automatically assigned the `owner` role.
+
+```ts
+const createOrg = async () => {
+  const { data, error } = await authClient.organization.create({
+    name: "My Company",
+    slug: "my-company",
+    logo: "https://example.com/logo.png",
+    metadata: { plan: "pro" },
+  });
+};
+```
+
+### Controlling Organization Creation
+
+Restrict who can create organizations based on user attributes:
+
+```ts
+organization({
+  allowUserToCreateOrganization: async user => {
+    return user.emailVerified === true;
+  },
+  organizationLimit: async user => {
+    // Premium users get more organizations
+    return user.plan === "premium" ? 20 : 3;
+  },
+});
+```
+
+### Creating Organizations on Behalf of Users
+
+Administrators can create organizations for other users (server-side only):
+
+```ts
+await auth.api.createOrganization({
+  body: {
+    name: "Client Organization",
+    slug: "client-org",
+    userId: "user-id-who-will-be-owner", // `userId` is required
+  },
+});
+```
+
+**Note**: The `userId` parameter cannot be used alongside session headers.
+
+## Active Organizations
+
+Stored in the session and scopes subsequent API calls. Set after user selects one.
+
+```ts
+const setActive = async (organizationId: string) => {
+  const { data, error } = await authClient.organization.setActive({
+    organizationId,
+  });
+};
+```
+
+Many endpoints use the active organization when `organizationId` is not provided (`listMembers`, `listInvitations`, `inviteMember`, etc.).
+
+Use `getFullOrganization()` to retrieve the active org with all members, invitations, and teams.
+
+## Members
+
+### Adding Members (Server-Side)
+
+```ts
+await auth.api.addMember({
+  body: {
+    userId: "user-id",
+    role: "member",
+    organizationId: "org-id",
+  },
+});
+```
+
+For client-side member additions, use the invitation system instead.
+
+### Assigning Multiple Roles
+
+```ts
+await auth.api.addMember({
+  body: {
+    userId: "user-id",
+    role: ["admin", "moderator"],
+    organizationId: "org-id",
+  },
+});
+```
+
+### Removing Members
+
+Use `removeMember({ memberIdOrEmail })`. The last owner cannot be removed — assign ownership to another member first.
+
+### Updating Member Roles
+
+Use `updateMemberRole({ memberId, role })`.
+
+### Membership Limits
+
+```ts
+organization({
+  membershipLimit: async (user, organization) => {
+    if (organization.metadata?.plan === "enterprise") {
+      return 1000;
+    }
+    return 50;
+  },
+});
+```
+
+## Invitations
+
+### Setting Up Invitation Emails
+
+```ts
+import { betterAuth } from "better-auth";
+import { organization } from "better-auth/plugins";
+import { sendEmail } from "./email";
+
+export const auth = betterAuth({
+  plugins: [
+    organization({
+      sendInvitationEmail: async data => {
+        const { email, organization, inviter, invitation } = data;
+
+        await sendEmail({
+          to: email,
+          subject: `Join ${organization.name}`,
+          html: `
+            <p>${inviter.user.name} invited you to join ${organization.name}</p>
+            <a href="https://yourapp.com/accept-invite?id=${invitation.id}">
+              Accept Invitation
+            </a>
+          `,
+        });
+      },
+    }),
+  ],
+});
+```
+
+### Sending Invitations
+
+```ts
+await authClient.organization.inviteMember({
+  email: "newuser@example.com",
+  role: "member",
+});
+```
+
+### Shareable Invitation URLs
+
+```ts
+const { data } = await authClient.organization.getInvitationURL({
+  email: "newuser@example.com",
+  role: "member",
+  callbackURL: "https://yourapp.com/dashboard",
+});
+
+// Share data.url via any channel
+```
+
+This endpoint does not call `sendInvitationEmail` — handle delivery yourself.
+
+### Invitation Configuration
+
+```ts
+organization({
+  invitationExpiresIn: 60 * 60 * 24 * 7, // 7 days (default: 48 hours)
+  invitationLimit: 100, // Max pending invitations per org
+  cancelPendingInvitationsOnReInvite: true, // Cancel old invites when re-inviting
+});
+```
+
+## Roles & Permissions
+
+Default roles: `owner` (full access), `admin` (manage members/invitations/settings), `member` (basic access).
+
+### Checking Permissions
+
+```ts
+const { data } = await authClient.organization.hasPermission({
+  permission: "member:write",
+});
+
+if (data?.hasPermission) {
+  // User can manage members
+}
+```
+
+Use `checkRolePermission({ role, permissions })` for client-side UI rendering (static only). For dynamic access control, use the `hasPermission` endpoint.
+
+## Teams
+
+### Enabling Teams
+
+```ts
+import { organization } from "better-auth/plugins";
+
+export const auth = betterAuth({
+  plugins: [
+    organization({
+      teams: {
+        enabled: true,
+      },
+    }),
+  ],
+});
+```
+
+### Creating Teams
+
+```ts
+const { data } = await authClient.organization.createTeam({
+  name: "Engineering",
+});
+```
+
+### Managing Team Members
+
+Use `addTeamMember({ teamId, userId })` (member must be in org first) and `removeTeamMember({ teamId, userId })` (stays in org).
+
+Set active team with `setActiveTeam({ teamId })`.
+
+### Team Limits
+
+```ts
+organization({
+  teams: {
+    maximumTeams: 20, // Max teams per org
+    maximumMembersPerTeam: 50, // Max members per team
+    allowRemovingAllTeams: false, // Prevent removing last team
+  },
+});
+```
+
+## Dynamic Access Control
+
+### Enabling Dynamic Access Control
+
+```ts
+import { organization } from "better-auth/plugins";
+import { dynamicAccessControl } from "@better-auth/organization/addons";
+
+export const auth = betterAuth({
+  plugins: [
+    organization({
+      dynamicAccessControl: {
+        enabled: true,
+      },
+    }),
+  ],
+});
+```
+
+### Creating Custom Roles
+
+```ts
+await authClient.organization.createRole({
+  role: "moderator",
+  permission: {
+    member: ["read"],
+    invitation: ["read"],
+  },
+});
+```
+
+Use `updateRole({ roleId, permission })` and `deleteRole({ roleId })`. Pre-defined roles (owner, admin, member) cannot be deleted. Roles assigned to members cannot be deleted until reassigned.
+
+## Lifecycle Hooks
+
+Execute custom logic at various points in the organization lifecycle:
+
+```ts
+organization({
+  hooks: {
+    organization: {
+      beforeCreate: async ({ data, user }) => {
+        // Validate or modify data before creation
+        return {
+          data: {
+            ...data,
+            metadata: { ...data.metadata, createdBy: user.id },
+          },
+        };
+      },
+      afterCreate: async ({ organization, member }) => {
+        // Post-creation logic (e.g., send welcome email, create default resources)
+        await createDefaultResources(organization.id);
+      },
+      beforeDelete: async ({ organization }) => {
+        // Cleanup before deletion
+        await archiveOrganizationData(organization.id);
+      },
+    },
+    member: {
+      afterCreate: async ({ member, organization }) => {
+        await notifyAdmins(organization.id, `New member joined`);
+      },
+    },
+    invitation: {
+      afterCreate: async ({ invitation, organization, inviter }) => {
+        await logInvitation(invitation);
+      },
+    },
+  },
+});
+```
+
+## Schema Customization
+
+Customize table names, field names, and add additional fields:
+
+```ts
+organization({
+  schema: {
+    organization: {
+      modelName: "workspace", // Rename table
+      fields: {
+        name: "workspaceName", // Rename fields
+      },
+      additionalFields: {
+        billingId: {
+          type: "string",
+          required: false,
+        },
+      },
+    },
+    member: {
+      additionalFields: {
+        department: {
+          type: "string",
+          required: false,
+        },
+        title: {
+          type: "string",
+          required: false,
+        },
+      },
+    },
+  },
+});
+```
+
+## Security Considerations
+
+### Owner Protection
+
+- The last owner cannot be removed from an organization
+- The last owner cannot leave the organization
+- The owner role cannot be removed from the last owner
+
+Always ensure ownership transfer before removing the current owner:
+
+```ts
+// Transfer ownership first
+await authClient.organization.updateMemberRole({
+  memberId: "new-owner-member-id",
+  role: "owner",
+});
+
+// Then the previous owner can be demoted or removed
+```
+
+### Organization Deletion
+
+Deleting an organization removes all associated data (members, invitations, teams). Prevent accidental deletion:
+
+```ts
+organization({
+  disableOrganizationDeletion: true, // Disable via config
+});
+```
+
+Or implement soft delete via hooks:
+
+```ts
+organization({
+  hooks: {
+    organization: {
+      beforeDelete: async ({ organization }) => {
+        // Archive instead of delete
+        await archiveOrganization(organization.id);
+        throw new Error("Organization archived, not deleted");
+      },
+    },
+  },
+});
+```
+
+### Invitation Security
+
+- Invitations expire after 48 hours by default
+- Only the invited email address can accept an invitation
+- Pending invitations can be cancelled by organization admins
+
+## Complete Configuration Example
+
+```ts
+import { betterAuth } from "better-auth";
+import { organization } from "better-auth/plugins";
+import { sendEmail } from "./email";
+
+export const auth = betterAuth({
+  plugins: [
+    organization({
+      // Organization limits
+      allowUserToCreateOrganization: true,
+      organizationLimit: 10,
+      membershipLimit: 100,
+      creatorRole: "owner",
+
+      // Slugs
+      defaultOrganizationIdField: "slug",
+
+      // Invitations
+      invitationExpiresIn: 60 * 60 * 24 * 7, // 7 days
+      invitationLimit: 50,
+      sendInvitationEmail: async data => {
+        await sendEmail({
+          to: data.email,
+          subject: `Join ${data.organization.name}`,
+          html: `<a href="https://app.com/invite/${data.invitation.id}">Accept</a>`,
+        });
+      },
+
+      // Hooks
+      hooks: {
+        organization: {
+          afterCreate: async ({ organization }) => {
+            console.log(`Organization ${organization.name} created`);
+          },
+        },
+      },
+    }),
+  ],
+});
+```

package/vendor/skills/skills/outside-to-issue/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: outside-to-issue
+description: Transform outside-of-diff review files into properly formatted issue files for a given PR. Use when converting review files from ai-docs/reviews-pr-<PR>/outside/ into issue format in ai-docs/reviews-pr-<PR>/issues/. Automatically determines starting issue number and preserves all metadata (file path, date, status) from original review files.
+---
+
+# Outside to Issue
+
+Transform outside-of-diff review files into properly formatted issue files for PR review tracking.
+
+## Overview
+
+This skill converts review files from the `outside/` directory into standardized issue files in the `issues/` directory, following the project's issue template format. The transformation preserves all metadata and automatically handles issue numbering.
+
+## Usage
+
+Run the transformation script for a specific PR:
+
+```bash
+scripts/transform-outside-to-issues.sh --pr <PR_NUMBER>
+```
+
+**Example:**
+
+```bash
+scripts/transform-outside-to-issues.sh --pr 90
+```
+
+## What It Does
+
+1. **Finds all outside files**: Reads all `.md` files from `ai-docs/reviews-pr-<PR>/outside/` directory
+2. **Determines starting issue number**: Automatically finds the highest existing issue number and starts numbering from the next available number
+3. **Transforms each file**: Converts outside review files into issue format with:
+   - Issue number and title
+   - File path from the review
+   - Date and status
+   - Body section containing the review details
+   - Footer indicating it's from outside-of-diff review
+
+## File Structure
+
+The script expects this directory structure:
+
+```
+ai-docs/reviews-pr-<PR>/
+├── outside/
+│   ├── 002-outside_01_<file-path>.md
+│   ├── 002-outside_02_<file-path>.md
+│   └── ...
+└── issues/
+    ├── 001-issue.md
+    ├── 002-issue.md
+    └── ...
+```
+
+## Output Format
+
+Each transformed issue file follows this format:
+
+```markdown
+# Issue <NUMBER> - Outside-of-diff
+
+**File:** `<file-path>`
+**Date:** <date>
+**Status:** <status>
+
+## Body
+
+<review-details-content>
+
+---
+
+_Generated from outside-of-diff review_
+```
+
+## Example
+
+For PR 90 with 18 outside files:
+
+```bash
+scripts/transform-outside-to-issues.sh --pr 90
+```
+
+**Output:**
+
+```
+Created: issues/026-issue.md
+Created: issues/027-issue.md
+...
+Created: issues/043-issue.md
+Transformation complete! Created issues starting from 26
+```
+
+## Notes
+
+- The script automatically determines the starting issue number based on existing issues
+- Files are processed in sorted order (alphabetically by filename)
+- All metadata (file path, date, status) is preserved from the original outside file
+- The Details section content becomes the Body section in the issue file
+- The script creates the `issues/` directory if it doesn't exist
+
+## Related Commands
+
+- `read_pr_issues.sh` - Read and display PR review issues
+- `resolve_pr_issues.sh` - Mark issues as resolved and update GitHub threads
+- `pr-fix` command - Fix issues for a given PR